tmux远程控制技能Skill 用法详解

tmux远程控制技能Skill：给 AI 代理一双手，远程操控交互式终端

核心定位：这不是一个普通工具，而是一套「让 AI 代理操控真实 tmux 会话」的操作规范——通过发送按键（send-keys）和抓取窗格输出（capture-pane），实现对交互式 CLI 的远程控制。
关键差异：普通命令执行工具只能跑完就返回；tmux 技能可以进入一个持续存在的终端会话，喂输入、看屏幕、等提示符，专治各种需要 TTY 的交互式程序。
隔离设计：使用私有套接字（由 OTTO_TMUX_SOCKET_DIR 指定）与独立会话命名，不污染用户自己的 tmux 环境。
最典型玩法：并行编排多个编码代理（Codex / Claude Code），一个套接字里跑起一支「代理小队」。
平台边界：仅支持 macOS（darwin）与 Linux，且要求系统 PATH 中存在 tmux 可执行文件；Windows 用户需走 WSL。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能中文名：tmux远程控制技能Skill 技能英文名：tmux 技能ID：13534

这个技能要解决的问题非常具体：很多命令行程序必须跑在交互式 TTY 里才正常工作。比如 Python 的交互式解释器、Claude Code / Codex 这类全屏 TUI 应用，一旦你用普通的「执行命令并等结果」方式去调用，要么卡住，要么行为异常。tmux 技能给出的答案是：先在一个后台 tmux 会话里把程序跑起来，之后所有交互都变成「往里发按键」+「从窗格里截图看输出」，AI 代理就能像人一样操作终端了。

安装前提（以下为技能声明的真实约束）：

操作系统需为 macOS 或 Linux（技能元数据中标注的 os 为 darwin、linux）；
系统 PATH 上必须能找到 tmux 可执行文件（元数据 requires.bins 明确要求 tmux）；
Windows 用户需先安装 WSL，并在 WSL 内部安装 tmux 后再使用。

一键安装思路与步骤：

第一步：准备运行环境。确认本机已安装 tmux（macOS / Linux 上可用各自系统包管理器安装，具体命令以官方说明为准），并确保 tmux 版本能在终端里直接执行 tmux -V 看到版本号。
第二步：通过技能市场/技能管理入口安装。在该 AI 助手平台的技能中心搜索技能名「tmux」或技能ID 13534，点击安装或启用。具体的安装命令、入口路径与是否需要额外授权，以官方说明为准。
第三步：验证是否生效。安装后让助手执行一次最小验证：新建一个隔离套接字上的后台会话，发送一条简单命令，再抓取窗格输出。若能正常看到会话被创建、且 capture-pane 返回了内容，就说明技能链路已经打通：

SOCKET_DIR="${OTTO_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/otto-tmux-sockets}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/otto.sock"
SESSION=otto-python
tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'PYTHON_BASIC_REPL=1 python3 -q' Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200

第四步：养成好习惯。技能里特别强调，会话一旦启动，必须把监控命令一起打印出来，方便人随时接手：

To monitor:
  tmux -S "$SOCKET" attach -t "$SESSION"
  tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200

「一键安装 + 一套约定俗成的操作范式」，就是它提升开发效率的核心逻辑：把「怎么跟交互式终端打交道」这件事标准化，AI 代理不必每次重新摸索。

该技能的主要功能和特点

远程按键注入：通过 send-keys 向指定窗格发送文本或控制键（如 C-c），支持「只发文字不回车」的精确模式（-l --），避免被 TUI 误判为粘贴。
窗格输出抓取：capture-pane -p -J -t target -S -200 可拉取最近 200 行历史并拼接长行，让 AI 真正「看见」终端画面。
私有套接字隔离：默认使用 "$OTTO_TMUX_SOCKET_DIR/otto.sock"（未设置时回落到 ${TMPDIR:-/tmp}/otto-tmux-sockets），与用户自己的 tmux 服务互不干扰，清理时一个 kill-server 就能整体收干净。
规范化目标寻址：统一采用 session:window.pane 目标格式，默认为 :0.0，命名保持简短、避免空格。
会话查找能力：提供 {baseDir}/scripts/find-sessions.sh，可列出指定套接字上的会话（-S "$SOCKET"），或用 --all 扫描全部套接字。
智能等待助手：{baseDir}/scripts/wait-for-text.sh 用正则（或 -F 固定字符串）轮询窗格内容，支持超时 -T、轮询间隔 -i、搜索历史行数 -l，让「等程序跑完」变成可控的事件。
TUI 场景的时序处理：针对 Claude Code / Codex 这类交互式应用，明确要求把「文字」和「Enter」拆成两条命令发送，中间留出小延迟（示例为 sleep 0.1，可按环境调整），避免被当成多行输入而不提交。
Python REPL 兼容处理：建议为 Python 设置 PYTHON_BASIC_REPL=1，因为非基本 REPL 会打断 send-keys 的输入流。
编排能力的边界提示：技能明确写清了「只在需要交互式 TTY 时用 tmux」，长时间运行的非交互式任务应优先走 exec 后台模式——这是一种克制的设计，避免用重手段解决轻问题。

跟普通工具比，它强在有状态：普通命令执行是「一次性函数调用」，tmux 技能是「开一个持续会话，反复交互」。跟直接用系统自带终端比，它强在可编排：所有操作都是纯命令行参数，天然适配 AI 代理调用。

如何使用该技能？

步骤 1：创建隔离会话

SOCKET_DIR="${OTTO_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/otto-tmux-sockets}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/otto.sock"
SESSION=otto-python
tmux -S "$SOCKET" new -d -s "$SESSION" -n shell

步骤 2：在会话里启动目标程序

tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'PYTHON_BASIC_REPL=1 python3 -q' Enter

步骤 3：确认会话与窗格状态

tmux -S "$SOCKET" list-sessions
tmux -S "$SOCKET" list-panes -a

如果记不清有哪些会话，可用 {baseDir}/scripts/find-sessions.sh -S "$SOCKET" 查看，或用 --all 扫描全部套接字。

步骤 4：发送输入（区分三种模式）

纯文本：tmux -S "$SOCKET" send-keys -t target -l -- "$cmd"
控制键：tmux -S "$SOCKET" send-keys -t target C-c
面向 TUI（Claude Code / Codex 等）：文字与 Enter 分开送，中间加延迟

tmux -S "$SOCKET" send-keys -t target -l -- "$cmd" && sleep 0.1 && tmux -S "$SOCKET" send-keys -t target Enter

步骤 5：读取输出

tmux -S "$SOCKET" capture-pane -p -J -t target -S -200

如需精确等待某个提示出现，用助手脚本：

{baseDir}/scripts/wait-for-text.sh -t session:0.0 -p 'pattern' [-F] [-T 20] [-i 0.5] [-l 2000]

步骤 6：并行编排多个编码代理

SOCKET="${TMPDIR:-/tmp}/codex-army.sock"
for i in 1 2 3 4 5; do
  tmux -S "$SOCKET" new-session -d -s "agent-$i"
done
tmux -S "$SOCKET" send-keys -t agent-1 "cd /tmp/project1 && codex --yolo 'Fix bug X'" Enter
tmux -S "$SOCKET" send-keys -t agent-2 "cd /tmp/project2 && codex --yolo 'Fix bug Y'" Enter

轮询完成情况时，可检查提示符是否恢复：

for sess in agent-1 agent-2; do
  if tmux -S "$SOCKET" capture-pane -p -t "$sess" -S -3 | grep -q "❯"; then
    echo "$sess: DONE"
  else
    echo "$sess: Running..."
  fi
done

步骤 7：清理现场

tmux -S "$SOCKET" kill-session -t "$SESSION"
tmux -S "$SOCKET" list-sessions -F '#{session_name}' | xargs -r -n1 tmux -S "$SOCKET" kill-session -t
tmux -S "$SOCKET" kill-server

输入与输出的预期：输入是一串「发给哪个窗格、发什么内容」的指令；输出则是窗格的纯文本快照（-p 打印到标准输出，-J 拼接换行）。AI 代理据此判断下一步动作。

同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
tmux 技能（本技能）	面向 AI 代理的交互式终端远程控制规范	send-keys 注入、capture-pane 抓取、私有套接字隔离、wait-for-text 等待、多代理并行编排	需 macOS/Linux + PATH 中有 tmux；安装入口以官方说明为准	交互式 TUI、并行跑多个编码代理、需要长期驻留的会话	优势：有状态、可编排、隔离干净、有明确时序约定；不足：不支持 Windows 原生，需 WSL
原生 tmux 手动操作	人类开发者直接使用的终端复用器	分屏、会话保持、detach/attach	需熟悉快捷键（如 `Ctrl+b d`）	人工值守的远程开发	优势：灵活直观；不足：全靠人工，难以被程序化编排
expect / pexpect 等脚本	传统交互式自动化脚本	按模式匹配自动应答	需编写脚本、处理超时与匹配逻辑	固定流程的自动化交互	优势：专为自动化而生；不足：脚本脆弱、维护成本高、难以应对 TUI 画面变化
exec 后台模式（非交互任务）	通用长任务执行方式	后台跑命令、回收结果	门槛最低	构建、安装依赖、跑测试等非交互任务	优势：轻量直接；不足：无法进入需要 TTY 的程序，不能持续喂输入

从上表可以看出，本技能的定位非常清晰：它不是要取代普通命令执行，而是补上「必须交互」这块短板。技能本身也明确要求——长时间运行的非交互式任务优先用 exec 后台模式，只有在需要交互式 TTY 时才动用 tmux。

该技能的典型应用场景与实际体验情况

场景一：AI 代理操作交互式 TUI（Claude Code / Codex）

角色：使用编码代理的开发者。痛点是——直接把提示词发给 TUI，容易被识别成「粘贴/多行输入」而不提交，代理就卡在那里等。使用方式：先建会话启动 TUI，再用「文字与控制键分离 + 小延迟」的方式发送提示，随后用 capture-pane 观察提示符是否恢复。实际体验：这一条时序约定是整个技能里最实用的一环，加上延迟后提交成功率明显稳定；但技能也提醒延迟需按环境调整，机器慢时要适当加大。

场景二：并行修复多个仓库的 Bug

角色：需要同时处理多个项目的工程师。痛点：串行修复效率低，手工开多个终端窗口又难以统一收割结果。使用方式：在一个套接字下批量 new-session 创建 agent-1 到 agent-5，分别 cd 到不同项目目录启动 codex，最后用 grep "❯" 轮询完成状态，再从已完成的会话里 capture-pane -S -500 拉完整输出。技能还给了配套建议：为并行修复使用独立的 git 工作树避免分支冲突，并在新鲜克隆里先 pnpm install。

场景三：驱动 Python 交互式解释器做分步验证

角色：需要逐步试探、边看结果边决定下一步的开发者。痛点：普通执行是「跑完给结果」，没有中间过程。使用方式：以 PYTHON_BASIC_REPL=1 启动 REPL，之后每一步 send-keys 一段代码，再 capture-pane 看回显。实际体验：必须设置 PYTHON_BASIC_REPL=1，否则非基本 REPL 的富文本渲染会干扰按键流，这是文档里明示的坑。

场景四：等待型任务的精确同步

角色：需要在某个输出出现后再执行下一步的自动化流程。痛点：靠固定 sleep 等待要么太短要么太浪费时间。使用方式：wait-for-text.sh -t session:0.0 -p 'pattern' -T 20 -i 0.5 -l 2000，用正则或 -F 固定字符串轮询，带超时与搜索历史行数控制。实际体验：比盲等可靠得多，参数语义清晰。

上手难度与整体注意事项：需要理解 tmux 的 session:window.pane 寻址、套接字隔离、TUI 提交时序这几个概念，门槛中等偏低。注意事项集中在三点：一是务必使用私有套接字并坚持清理；二是 TUI 场景永远把文字和 Enter 拆开发；三是别忘了给用户打印监控命令，让人类随时能接手。

该技能能为用户带来的价值

打通「最后一公里」：大量真实工作流卡在交互式程序上，本技能用标准化的按键注入与画面抓取，让 AI 代理能进入这些程序内部操作，而不是停在门外。
效率的量级提升：通过一个套接字并行跑多个编码代理，把原本串行等待的修复任务变成同时推进，配合轮询脚本收割结果，等待时间被显著压缩。
降低自动化门槛：不需要写 expect 脚本、不需要处理复杂的模式匹配逻辑，只要会发按键、会抓输出，就能搭出可靠的交互自动化。
安全与可控：私有套接字目录 + 独立会话命名 + 明确的清理命令（kill-session / kill-server），让实验性操作不会污染日常开发环境。
长期价值：这套「发输入—看输出—等提示」的范式可以复用到任何需要 TTY 的场景，形成可沉淀的操作资产，而不是一次性脚本。

常见问题 FAQ

Q1：这个技能怎么安装？装完怎么确认能用？ 先确认系统是 macOS 或 Linux、PATH 里有 tmux；然后在技能中心搜索 tmux 或技能ID 13534 安装启用，具体命令与入口以官方说明为准。验证方式是跑一遍最小流程：建私有套接字会话 → send-keys 一条命令 → capture-pane 能看到输出，即代表生效。

Q2：Windows 上能用吗？ 不能直接使用。技能元数据限定了 darwin 与 linux，Windows 需改用 WSL，并在 WSL 内安装 tmux 后再使用。

Q3：什么时候该用 tmux 技能，什么时候不该用？ 只在需要交互式 TTY 时用。长时间运行的非交互式任务（比如构建、装依赖、跑测试）应优先走 exec 后台模式，更轻、更快、更简单。

Q4：为什么发给 Claude Code / Codex 的提示经常不提交？ 因为把文字和 Enter 塞在同一条 send-keys 里，可能被 TUI 认定为粘贴或多行输入。正确做法是拆成两条命令，中间加延迟（示例为 sleep 0.1，按环境调整；不支持亚秒级 sleep 时用 sleep 1）。

Q5：收费吗？适合谁用？ 技能本身是一套 tmux 操作规范与配套脚本，费用相关信息请以官方说明为准。它最适合三类人：使用编码代理做并行开发的工程师、需要自动化交互式 CLI 的开发者，以及希望让 AI 代理进入真实终端环境操作的技术团队。