tmux-watch：基于输出稳定性监测的终端会话自动化监控插件

1. 项目概述

如果你和我一样，日常开发重度依赖 tmux 来管理多个终端会话，那你肯定也遇到过这样的场景：一个长时间运行的任务，比如一个数据处理的脚本、一个持续编译的进程，或者一个交互式的 AI 编程助手（比如 Claude Code 或 Codex），它在前台跑着，你切到别的窗口忙活一阵，回头一看，它可能早就卡在某个地方不动了，白白浪费了时间和计算资源。更头疼的是，你根本不知道它是什么时候停的，停了多久，以及停在了哪一步。手动去检查每一个 pane 的状态，既低效又容易遗漏。

tmux-watch这个 OpenClaw 插件，就是为了解决这个痛点而生的。它的核心功能非常直接：自动监控 tmux 中指定窗格（pane）的输出内容，当输出在连续多次捕获中保持完全不变时，就判定为“卡住”或“停滞”，然后自动唤醒 AI Agent（比如 Claude）来分析最后捕获到的输出，生成一个总结，并通过你配置的渠道（比如微信、Slack）通知你。简单来说，它给你的 tmux 会话装上了一双永不疲倦的“眼睛”和一个聪明的“大脑”，让你能从繁琐的“人工盯屏”中彻底解放出来。

这个工具特别适合监控那些输出不规律、但一旦停滞就说明有问题的场景。比如，你让 AI 助手在 tmux 里写代码，它可能会思考、会输出代码片段、会运行测试，但突然它停在那里超过一分钟没有任何新输出，这很可能意味着它遇到了逻辑困惑、依赖缺失或者干脆就是“发呆”了。这时候，tmux-watch的告警和总结就能及时把你拉回现场，让你快速介入。

2. 核心设计思路与工作原理拆解

2.1 为什么是“输出稳定性”监测？

监控进程状态有很多种方法，比如检查进程是否存活（PID）、CPU/内存占用率等。但对于 tmux 中的交互式任务，尤其是 AI 驱动的任务，这些指标往往不够准确。一个 AI 助手进程可能还在运行（PID 存在），但它的“思考”可能已经陷入了死循环，或者等待用户输入而停滞。此时，最直观、最可靠的指标就是终端输出内容的变化。

tmux-watch采用了“基于内容变化的稳定性监测”模型。它周期性地捕获指定 tmux pane 的最后若干行输出（默认50行），并进行比对。其核心逻辑是：如果连续 N 次捕获到的文本内容完全一致（或仅在空白字符上有差异），则认为该 pane 的输出已进入“稳定”或“停滞”状态。这里的“稳定”是一个中性词，对于需要持续输出的任务来说，“稳定”通常意味着“卡住”。

这种设计有几个关键优势：

1. 与任务逻辑解耦：不关心你跑的是 Python 脚本、Go 程序还是 AI 对话，只关心输出是否变化，普适性强。
2. 低侵入性：完全通过 tmux 的capture-pane命令获取内容，不需要修改或侵入被监控的进程。
3. 可配置的敏感度：通过captureIntervalSeconds（捕获间隔）和stableCount（稳定次数）这两个参数，你可以灵活调整监测的“耐心”程度。例如，间隔3秒，连续5次不变则告警，那么从真正卡住到触发告警，最长等待时间是15秒。这对于需要快速响应的场景（如高频交易监控）可以调敏感些；对于输出本身较慢的任务（如模型训练），则可以调宽松些。

2.2 插件在 OpenClaw 生态中的角色

tmux-watch不是一个独立运行的后台服务，而是作为 OpenClaw 的一个插件运行。OpenClaw 本身是一个 AI Agent 框架和网关（Gateway）。这意味着：

• 事件驱动：tmux-watch的监控循环由 OpenClaw Gateway 托管。当插件被启用并配置了订阅后，Gateway 会按设定的间隔驱动插件进行捕获和比对。
• Agent 集成：当稳定条件触发时，插件并不是简单地发一条“卡住了”的消息。它的核心动作是“唤醒 Agent”。它会向 OpenClaw 框架发起一个请求，调用配置好的 AI Agent（例如 Claude）来处理这个事件。
• 智能总结：被唤醒的 Agent 会收到一个包含“卡住”的 pane 最后输出内容的上下文。Agent 的任务是分析这些内容，理解当前任务的状态、可能卡住的原因，并生成一份人类可读的总结。这比单纯转发原始日志要有用得多。
• 通知分发：总结完成后，插件会根据你的配置，通过 OpenClaw 支持的多种通知渠道（Channel），如 Gewe（一个微信机器人桥接）、Slack、Telegram 等，将这份智能总结发送给你。

所以，tmux-watch的本质是一个“感知-决策-执行”循环中的“感知”模块，它负责发现异常，然后交由 OpenClaw 的“决策”（Agent）和“执行”（通知）模块来完成后续动作。这种架构使得它非常灵活和强大。

2.3 远程监控与本地监控的统一

一个非常亮眼的功能是它对远程 tmux 会话的支持。很多开发者的工作环境是本地笔记本连接远程开发机，所有 tmux 会话都跑在远程。tmux-watch通过hosts配置项，完美解决了这个问题。

它的实现思路很清晰：

1. 配置远程主机档案：你只需要预先通过openclaw tmux-watch host add命令，告诉插件如何通过 SSH 连接到你的远程开发机（sshCommand），以及远程机上 tmux 的 socket 路径（可选）。
2. 抽象化访问：之后，无论是在 CLI 命令中通过--host参数，还是在 Agent 工具的 JSON 调用中指定host字段，插件都会自动使用配置的 SSH 命令去连接远程主机，并在远程执行相应的 tmux 命令（如capture-pane）。
3. 对用户透明：除了多一个--host参数，本地 pane 和远程 pane 的监控、捕获、发送输入等操作，在命令和体验上完全一致。这极大地简化了混合环境的运维复杂度。

3. 从零开始：安装与基础配置详解

3.1 环境与依赖准备

在安装插件之前，请确保你的系统满足以下条件：

• tmux：这是核心依赖，必须安装。通常系统包管理器（apt,yum,brew）都可直接安装。
• OpenClaw：插件运行的基础框架。你需要先安装并配置好 OpenClaw Gateway。请参考 OpenClaw 官方文档完成基础安装和 Agent 配置。
• 可选截图工具：如果你需要捕获 pane 的图片快照（而不仅仅是文本），则需要安装cryosnap或freeze。插件优先使用cryosnap，因为它通常更快、质量更好。你可以通过插件自带的命令安装：openclaw tmux-watch install cryosnap。

注意：tmux-watch插件版本与 OpenClaw 主版本存在依赖关系。项目要求openclaw >= 2026.1.29。在安装前，最好用openclaw --version确认一下版本，避免因版本不兼容导致插件无法启用或运行异常。

3.2 插件的多种安装方式

插件的安装完全通过 OpenClaw 的插件管理系统，非常方便。

3.2.1 从 npm 仓库安装（推荐）这是最标准的方式，适合绝大多数用户。OpenClaw 的插件仓库托管在 npm 上。

openclaw plugins install tmux-watch

执行后，OpenClaw 会自动从 npm 下载、解压并注册该插件。安装完成后，必须重启 OpenClaw Gateway以使插件生效。你可以通过openclaw gateway restart或相应的服务管理命令来重启。

3.2.2 从本地目录安装（用于开发或测试）如果你克隆了tmux-watch的源码，或者想测试自己的修改，可以使用本地安装。

openclaw plugins install /path/to/your/tmux-watch

更推荐在开发时使用--link参数创建软链接，这样你在源码目录的任何修改都会实时反映到插件中，无需重复安装。

openclaw plugins install --link /path/to/your/tmux-watch

3.2.3 从压缩包安装如果你从其他地方获得了插件的.tgz压缩包，也可以直接安装。

openclaw plugins install ./tmux-watch.tgz

无论哪种方式，安装成功后，你都可以通过openclaw plugins list命令查看已安装的插件列表，确认tmux-watch的状态是否为enabled。

3.3 核心配置文件解析

插件的所有行为都由~/.openclaw/openclaw.json配置文件中的对应段落控制。下面我们逐项拆解配置项的含义和最佳实践。

{ "plugins": { "entries": { "tmux-watch": { // 插件标识，固定为 `tmux-watch` "enabled": true, // 总开关，设为 false 可临时关闭插件 "config": { // 插件专属配置 "debug": false, // 调试开关，设为 true 可在日志中看到详细轮询和决策过程 "socket": "/private/tmp/tmux-501/default", // 【关键】本地 tmux socket 路径 "hosts": { // 远程主机配置字典 "devbox": { // 主机档案名，可自定义，如 `aws-prod`, `pi-server` "sshCommand": "ssh devbox", // 连接该主机的 SSH 命令 "socket": "/tmp/tmux-remote.sock" // 【可选】远程主机的 tmux socket 路径 } }, "captureIntervalSeconds": 10, // 捕获输出内容的间隔时间（秒） "stableCount": 6, // 连续多少次捕获内容不变则触发告警 "cooldownSeconds": 120, // 同一订阅的告警冷却时间（秒） "minOutputChars": 8, // 输出内容少于多少字符时忽略（避免监控空屏） "ignoreWhitespaceOnlyChanges": true, // 是否忽略纯空白字符的变化 "captureLines": 50, // 每次从 pane 底部向上捕获多少行 "stripAnsi": true, // 是否剥离 ANSI 转义码（颜色、光标移动等） "maxOutputChars": 4000, // 通知消息中最多包含的字符数，超长会截断 "notify": { // 通知配置 "mode": "targets", // 通知模式：`targets`(仅目标), `last`(仅上次会话), `targets+last`(两者) "targets": [ // 通知目标列表 { "channel": "gewe-openclaw", // 通知渠道，如 gewe（微信）、slack 等 "target": "wxid_xxx", // 该渠道下的具体目标，如微信个人ID、群ID、Slack channel ID "label": "gewe" // 用于日志标识的标签 } ] } } } } } }

关键配置项深度解读：

1. socket（必填）：这是插件与 tmux 通信的桥梁。tmux 采用客户端-服务器架构，服务器通过一个 Unix Socket 文件与客户端通信。你需要提供这个 socket 文件的路径。获取方法很简单：在你想监控的那个 tmux 会话中，执行echo $TMUX，输出类似/private/tmp/tmux-501/default,3191,4，取第一个逗号前的部分/private/tmp/tmux-501/default即可。务必注意：你监控的 pane 必须位于这个 socket 对应的 tmux 服务器实例中。

2. captureIntervalSeconds&stableCount：这两个参数共同决定了监测的灵敏度和延迟。总等待时间 = 间隔 × 次数。例如，间隔设为5秒，次数设为6次，那么从输出真正停止变化到触发告警，最多需要30秒。你需要根据被监控任务的性质来权衡：

   • 快速交互任务（如 CLI 问答）：间隔可设短（2-5秒），次数可设少（3-5次），实现快速响应。
   • 慢速输出任务（如编译、下载）：间隔应设长（10-30秒），次数可设多（6-10次），避免因任务本身输出慢而产生误报。

3. stripAnsi: true（强烈建议开启）：终端输出中包含了大量用于控制颜色、字体、光标位置的 ANSI 转义序列。这些序列对于显示是必要的，但对于内容比对是噪音。开启此选项后，插件会在比对前清理这些序列，确保比对的是纯文本内容，避免因为颜色变化而误判为“内容变化”。

4. notify.mode：

   • targets：只发送到notify.targets列表中配置的目标。这是最常用的模式。
   • last：只发送到上次与 OpenClaw Gateway 交互的会话（例如，你最后发送命令的聊天窗口）。这在临时调试时有用。
   • targets+last：两者都发送。确保你不会错过任何通知。

5. cooldownSeconds：这是一个非常重要的防骚扰机制。假设一个 pane 卡住了，插件触发告警并通知了你。在你处理之前，该 pane 的输出可能依然是静止的。如果没有冷却时间，插件会在下一个监测周期（比如10秒后）再次判定为稳定，再次触发告警，导致消息轰炸。设置一个合理的冷却时间（如120秒），可以确保在第一次告警后的一段时间内，即使条件依然满足，也不会重复发送通知。

3.4 一键初始化向导的使用

对于新手，手动编辑 JSON 配置和寻找 socket 可能有些麻烦。插件提供了非常友好的setup向导命令。

openclaw tmux-watch setup

运行这个命令后，它会引导你完成以下步骤：

1. 自动探测 Socket：它会尝试列出系统上可用的 tmux socket，并让你选择。
2. 列出可用 Pane：连接到你选择的 socket，列出当前所有 tmux 会话和窗格，并提供一个列表供你选择。
3. 创建订阅：在你选择目标 pane 后，它会询问你一些基本信息（如标签、备注、监测间隔等），然后自动生成对应的 Agent 工具调用请求，帮你创建第一个监控订阅。

整个过程是交互式的，非常适合快速上手。如果你想跳过交互，也可以直接指定参数：

openclaw tmux-watch setup --socket "/private/tmp/tmux-501/default" --target "work:0.1"

4. 核心功能实操：监控、捕获与交互

4.1 管理监控订阅

监控的核心是“订阅”（Subscription）。一个订阅定义了监控哪个 pane、如何监控以及如何通知。

4.1.1 通过 Agent 工具创建订阅（推荐）这是最灵活、最自动化的方式。你不需要手动编辑配置文件，而是通过向你的 AI Agent（如 Claude）发送一个结构化的 JSON 请求来创建订阅。这通常可以整合到你的自动化工作流中。

{ "action": "add", "host": "devbox", // 可选，指定远程主机档案名。省略则使用本地 socket。 "target": "session:0.0", // 【关键】目标 pane 标识符。格式：`session_name:window_index.pane_index` "label": "codex-tui", // 订阅的标签，用于日志和通知中标识，方便管理 "note": "本会话是AI编程TUI助手，卡住时总结最后输出并通知我", // 备注信息 "captureIntervalSeconds": 3, // 覆盖全局配置的捕获间隔 "stableCount": 5 // 覆盖全局配置的稳定次数 }

你需要将这个 JSON 通过你配置的渠道（如 Gewe 微信）发送给你的 OpenClaw Agent。Agent 识别到这个工具调用后，会将其转发给tmux-watch插件执行。

如何确定target？在目标 tmux 会话中，使用tmux list-panes -F '#{session_name}:#{window_index}.#{pane_index}'命令，可以列出所有 pane 的标识符。例如，输出work:0.0表示会话名为work，第一个窗口（索引0），第一个窗格（索引0）。

4.1.2 订阅的管理与查看目前，tmux-watch插件主要侧重于动态订阅（通过 Agent 工具添加）。订阅列表由插件在内存中管理。你可以通过查看 OpenClaw Gateway 的日志（开启debug模式）来了解当前活跃的订阅及其轮询状态。未来版本可能会增加list、remove等管理命令。

4.2 主动捕获与快照

除了自动监控，插件也提供了强大的手动捕获功能，相当于给 tmux pane 拍“照片”。

4.2.1 捕获文本输出这是最基本的功能，获取 pane 当前的文本内容。

# 捕获本地 pane 内容 openclaw tmux-watch capture work:0.0 # 捕获远程 pane 内容 openclaw tmux-watch capture --host devbox work:0.0

命令会直接将捕获的文本输出到终端。这对于脚本化获取某个命令的输出结果非常有用。

4.2.2 捕获图像快照这是非常酷的功能！它能将 tmux pane 的当前界面渲染成一张图片。

# 捕获为图片（默认生成临时文件，10分钟后自动删除） openclaw tmux-watch capture work:0.0 --format image # 指定图片格式和保存路径（不会自动删除） openclaw tmux-watch capture work:0.0 --format image --image-format png --output /tmp/my_pane_snapshot.png # 同时捕获文本和图片，并将图片以 base64 编码形式内联在文本中 openclaw tmux-watch capture work:0.0 --format both --base64

实操心得：截图依赖的选择插件支持cryosnap和freeze两个后端来生成图片。cryosnap通常是更好的选择，它基于 Chrome DevTools Protocol，渲染质量高，支持现代字体和图形。如果系统没有安装，直接用插件命令安装：openclaw tmux-watch install cryosnap。如果安装失败或不可用，可以回退到freeze。在某些无头（headless）服务器环境或终端模拟器较特殊的情况下，截图功能可能受限，此时文本捕获是更可靠的备选。

4.2.3 图像快照的应用场景

• 故障报告：当某个进程出错时，自动截图并附在告警通知里，直观展示错误界面。
• 进度记录：对长时间任务进行定期截图，生成可视化的进度日志。
• 知识存档：将某个复杂的终端布局或输出结果保存为图片，便于分享和文档化。

4.3 向 Pane 发送输入

tmux-watch不仅能“读”，还能“写”。它允许你从外部向指定的 tmux pane 发送文本输入，并模拟回车执行。

# 向本地 pane 发送命令并执行 openclaw tmux-watch send work:0.0 "ls -la" # 只发送文本，不按回车（适用于需要手动确认的场景） openclaw tmux-watch send work:0.0 "sudo apt-get update" --no-enter # 发送到远程 pane openclaw tmux-watch send --host devbox work:0.0 "docker ps"

工作原理：该命令本质上是通过 tmux 的send-keys命令实现的。默认行为是两步：首先发送文本（send-keys -l “your text”），然后延迟约20毫秒发送一个回车键（send-keys C-m）。--delay-ms参数可以调整这个延迟，这在某些响应慢的终端或交互式程序中可能有用。

注意事项：

• 权限与上下文：你通过插件发送的命令，将以运行 OpenClaw Gateway 的用户身份，在目标 pane 的当前工作目录和环境中执行。请确保该用户有足够的权限。
• 交互式程序：对于像vim、htop或需要复杂交互的程序，简单的文本输入可能不够，需要更精细的控制逻辑。
• 输入风暴：避免在脚本中高频调用此命令向同一个 pane 发送输入，可能会造成输入混乱。合理使用--delay-ms或结合其他协调机制。

5. 高级配置与远程监控实战

5.1 配置与管理远程 Tmux 主机

远程监控是tmux-watch的杀手级功能。假设你的开发环境在云服务器dev.example.com上，所有工作都在那里的 tmux 中。

第一步：添加远程主机档案你需要告诉插件如何连接到你的远程服务器。

openclaw tmux-watch host add dev-example \ --ssh "ssh dev-user@dev.example.com -p 2222" \ --socket "/tmp/tmux-501/default"

• dev-example：你为这个远程连接起的名字，后续命令中用这个名字引用它。
• --ssh：完整的 SSH 连接命令。你可以在这里使用 SSH 配置文件中定义的 Host、指定密钥、端口等任何 SSH 支持的参数。
• --socket：可选但强烈建议指定。这是远程服务器上 tmux server 的 socket 路径。如果不指定，插件会尝试使用默认路径或通过 SSH 执行echo $TMUX来探测，但这可能不可靠，尤其是在监控的 pane 不在当前 SSH 会话关联的 tmux 中时。最稳妥的方式是登录远程服务器，进入你要监控的 tmux 会话，执行echo $TMUX获取路径并填在这里。

第二步：测试连接添加完成后，立即测试连接是否畅通，以及能否正确访问 tmux。

openclaw tmux-watch host test dev-example

这个命令会尝试执行 SSH 连接，并可能在远程执行简单的 tmux 命令（如list-sessions）。如果成功，你会看到连接成功的提示；如果失败，会输出具体的错误信息（如 SSH 认证失败、tmux 未安装等）。

第三步：列出所有已配置的主机

openclaw tmux-watch host list

这会显示所有已配置的远程主机档案，方便你管理。

5.2 远程监控工作流

配置好远程主机后，所有针对本地 pane 的操作，只需加上--host <档案名>参数，即可无缝切换到远程。

1. 监控远程 pane：在创建订阅的 Agent 工具调用 JSON 中，加上"host": "dev-example"字段即可。
2. 手动捕获远程输出：

   openclaw tmux-watch capture --host dev-example “my-remote-session:1.2”

3. 向远程 pane 发送命令：

   openclaw tmux-watch send --host dev-example “my-remote-session:1.2” “tail -f /var/log/app.log”

远程监控的内部机制：当你执行一个带--host的命令时，插件会在本地构造一个 tmux 命令（如capture-pane -p -t session:0.0），然后通过你配置的 SSH 命令，在远程主机上执行这个 tmux 命令，最后将结果传回本地处理。所以，远程主机上必须安装 tmux，并且 SSH 用户必须有权限访问指定的 tmux socket。

5.3 调试与日志分析

当你发现监控没有按预期工作时，调试日志是你的第一手资料。

开启调试模式：在配置文件openclaw.json中，将tmux-watch配置下的debug设为true，然后重启 OpenClaw Gateway。

查看日志：日志位置取决于你的 OpenClaw 部署方式。如果是 systemd 服务，通常用journalctl -u openclaw-gateway -f跟踪。如果是直接运行，日志会输出到标准错误或指定的日志文件。

在调试日志中，重点关注以下几类信息：

• [tmux-watch][debug] Polling started for subscription ...：表示对一个订阅开始了新一轮的捕获检查。
• [tmux-watch][debug] Captured content for ...：显示捕获到的原始内容（可能很长）。
• [tmux-watch][debug] Stability counter for ... is now X/6：这是关键信息，显示某个订阅的“稳定计数器”当前值。数字递增表示连续捕获到相同内容。当达到设定的stableCount（如6）时，下一行应该会触发告警。
• [tmux-watch][debug] Triggering notify for ...：表示稳定条件满足，正在触发通知流程。
• [tmux-watch][debug] Dispatching reply to channel ...：表示正在向某个通知渠道（如微信）发送消息。
• [tmux-watch][debug] Notification sent successfully to ...或... failed ...：通知发送的成功或失败结果。

通过跟踪这些日志，你可以清晰地看到插件的工作节奏：何时捕获、内容是否变化、计数器如何累积、何时触发、通知发往何处。这对于排查“为什么不告警”或“为什么误告警”至关重要。

6. 常见问题排查与实战技巧

6.1 监控不触发或误触发

这是最常见的问题，根本原因通常在于“什么算作变化”的判断上。

问题：任务明明卡住了，却没有收到告警。

• 检查1：minOutputChars设置是否过大？如果 pane 里最后的输出内容（去除 ANSI 码后）长度小于这个值，插件会直接忽略，不进行稳定性判断。确保你的任务有足够长的输出。
• 检查2：输出真的“完全静止”了吗？有些程序会输出闪烁的光标、动态的时间戳（如[2024-01-01 12:34:56]）或微小的状态字符。这些都会导致每次捕获的内容不同。解决方案：
  • 如果是不必要的信息，看能否在程序端关闭这些动态输出。
  • 使用stripAnsi: true（默认已开启）可以过滤光标和颜色变化。
  • 对于时间戳，可以考虑在监控前通过管道 (|) 用sed等工具过滤掉，但这需要更复杂的 pane 包装。
• 检查3：captureLines是否足够？如果程序的最新输出已经滚动出了你捕获的行数范围，那么插件捕获到的始终是旧的、不变的内容，从而无法感知到新输出。对于输出较快的任务，适当增加captureLines（例如到100或200）。
• 检查4：cooldownSeconds是否正在生效？查看日志，确认是否刚刚触发过一次告警，目前正处于冷却期。

问题：任务正常在运行，却频繁误告警。

• 检查1：stableCount是否设置过小？对于输出本身是间歇性的任务（例如，一个每30秒输出一行日志的脚本），如果captureIntervalSeconds是5秒，stableCount是3，那么在两次日志输出的15秒间隔内，就很容易触发告警。你需要将stableCount调大，或者将captureIntervalSeconds调大到接近或大于任务正常输出的间隔。
• 检查2：是否忽略了空白变化？ignoreWhitespaceOnlyChanges: true（默认）是很好的防误报设置。如果程序输出只是多了几个空格或换行，这不会被判定为“变化”。如果你希望连空白变化也视为有效变化，可以将此选项设为false。
• 检查3：目标 pane 是否处于活跃状态？tmux 有一个特性：当有多个客户端连接时，只有“活跃”的客户端连接的 pane，其输出才会实时更新。如果监控的 pane 所在的窗口并非当前“活跃”窗口，其输出缓冲区可能不会更新，导致插件捕获到陈旧内容。确保被监控的 pane 所在的会话/窗口在某个 tmux 客户端中是“可见”或“活跃”的。

6.2 通知发送失败

告警触发了，但你没收到微信/Slack消息。

• 检查1：notify.mode和targets配置是否正确？确认channel名称与你在 OpenClaw 中配置的通知渠道完全一致（大小写敏感）。确认target是该渠道下的有效目标ID（如正确的微信ID）。
• 检查2：OpenClaw 通知渠道本身是否工作正常？先测试不通过tmux-watch，直接用 OpenClaw 的其他功能或测试命令向该渠道发送一条消息，看是否能收到。确保 Gewe 等桥接服务在线且配置正确。
• 检查3：查看插件调试日志。日志中会有Dispatching reply to channel ...和发送成功/失败的信息。根据错误信息进一步排查。

6.3 远程主机连接失败

• 检查1：SSH 命令是否能手动执行成功？在本地终端直接运行配置的sshCommand（例如ssh dev-user@dev.example.com -p 2222），确保无需交互式输入密码（应使用密钥认证）并能成功登录。
• 检查2：远程主机上的 tmux socket 路径是否正确？使用openclaw tmux-watch host test <主机名>测试。如果测试失败，提示 tmux 错误，请登录远程主机，确认--socket参数指定的路径是否存在，并且运行 OpenClaw Gateway 的本地用户，通过 SSH 连接到远程后，有权限读取该 socket 文件。
• 检查3：远程主机的 tmux 是否在运行？确保你要监控的 tmux 服务器正在运行。

6.4 性能与资源考量

• 监控的 pane 数量：每个订阅都会创建一个独立的定时轮询任务。监控几十个 pane 可能问题不大，但如果监控上百个，需要考虑 Gateway 的负载和定时器的精度。
• 捕获的行数：captureLines设置得越大，每次捕获和比对的数据量就越大。对于内容非常长的 pane（例如tail -f一个巨大的日志文件），捕获50行和捕获500行，在内存和CPU消耗上有差异。在满足需求的前提下，建议使用合理的行数。
• 捕获间隔：captureIntervalSeconds设置得过小（如1秒），会对 tmux 和系统造成频繁的轮询压力。通常5-30秒的间隔对于大多数场景都是平衡的选择。

6.5 实战技巧：与 AI Agent 工作流结合

tmux-watch的真正威力在于与 AI Agent 的联动。这里分享几个进阶思路：

1. 分级告警：你可以配置多个订阅，对同一个 pane 使用不同的stableCount。例如，一个订阅stableCount: 3用于“初步停滞警告”，Agent 总结后可能只是提醒你关注；另一个订阅stableCount: 10用于“严重停滞告警”，Agent 可以尝试执行一些自动恢复操作（如通过send功能发送Ctrl+C再重启命令）。

2. 上下文丰富的总结：在创建订阅的note字段中，详细描述这个 pane 的任务背景。例如：“这是用于处理用户上传文件的队列处理器，正常状态应每秒处理1-2个文件。” 当 Agent 被唤醒总结时，这段 note 会作为上下文的一部分，帮助 AI 做出更准确的判断。

3. 自动恢复尝试：你可以教导你的 Agent，当收到某种特定类型的停滞总结时（例如“编译错误：找不到某个依赖”），让它不仅通知你，还可以自动执行修复命令（如openclaw tmux-watch send --host devbox build:0.0 “make install-deps”）。这需要精心设计 Agent 的提示词（Prompt）和工具调用逻辑。

4. 聚合监控看板：虽然tmux-watch本身不提供 UI，但你可以让 Agent 定期（或根据告警）使用capture命令获取多个关键 pane 的状态（文本或图片），然后汇总成一份格式化的报告，定期发送到你的通知渠道，形成一个简单的监控看板。

tmux-watch将 tmux 这个终端复用器的价值提升到了一个新的层次。它不再是简单的窗口管理工具，而是变成了一个可观测、可交互、可智能响应的自动化平台节点。通过合理的配置和与 AI Agent 的结合，你可以构建出一个高度自动化、能主动发现并应对问题的个人或团队开发运维环境。从监控一个简单的编译任务，到看管一个分布式的数据处理流水线，它的应用场景只受限于你的想象力。