tmux Worker 集成与跨平台兼容

学习目标

理解 tmux CLI Worker 的进程隔离架构
掌握 macOS/Linux/Windows(psmux)/WSL2 四平台兼容策略
设计自己的多进程 Agent 隔离方案
识别 tmux 会话泄露和 Worker 清理的陷阱

前置知识

多 Agent 编排的异构编排模式已在通用知识中介绍：

多 Agent 路由模式

下文假设你已理解跨 Provider 异构编排的基础概念，直接聚焦 OMC 的 tmux Worker 集成与跨平台兼容 的具体实现。

项目实践

tmux CLI Worker 架构

v4.4.0 引入了通过 tmux 启动真实多进程 Worker 的能力，替代了之前的 Codex/Gemini MCP 服务器：

Worker 启动流程

解析命令：omc team 2:codex "review auth flow" → 2 个 Codex Worker
创建 tmux session：以任务名命名的 tmux session（如 review-auth-flow）
分割 panes：根据 Worker 数量分割 tmux 窗口
启动 CLI：在每个 pane 中启动对应的 CLI（codex、gemini、claude）
注入任务：通过互操作状态（interop state）将任务描述传递给 Worker
监控循环：omc team status 监控 Worker 进度

Worker 互操作 API

Worker 通过 omc team api 进行通信：

# 发送消息
omc team api send-message --input '{"team_name":"my-team","from_worker":"worker-1","to_worker":"leader","body":"ACK"}' --json

# 创建任务
omc team api create-task --input '{"team_name":"my-team","subject":"Fix bug","description":"..."}' --json

# 列出任务
omc team api list-tasks --input '{"team_name":"my-team"}' --json

四平台兼容

平台	tmux Provider	安装	兼容性
macOS	tmux	`brew install tmux`	完整
Ubuntu/Debian	tmux	`sudo apt install tmux`	完整
Windows（原生）	psmux	`winget install psmux`	76/100 命令
WSL2	tmux	`sudo apt install tmux`	完整

psmux 是一个原生 Windows tmux 兼容二进制，由社区成员 marlocarlo 开发，提供 76 个 tmux 兼容命令。OMC 是唯一支持 psmux 的多 Agent 编排系统。

Git Worktree 模式（可选）

OMC 支持在独立的 git worktree 中启动 Worker：

# 通过配置启用
{
  "team": {
    "ops": {
      "worktreeMode": "detached"
    }
  }
}

每个 Worker 在独立的工作树中运行（.omc/team/<team>/worktrees/<worker>），避免文件冲突。配合 --auto-merge 标志可实现自动合并。

自动合并（v2 运行时）

omc team 2:codex "fix bugs" --auto-merge

每个 Worker 在专用的 git worktree 中运行（omc-team/{team}/{worker}）
快速提交合并：Worker 的突发提交合并为 leader 的 HEAD
Leader 分支不能是 main 或 master

问题与规避

问题 1：tmux 会话泄露

Worker 异常退出时，tmux pane 可能残留。

规避策略：omc team shutdown <team-name> 清理整个 tmux session。--force 标志强制关闭。

问题 2：Worker 未正确清理

Worker 完成后，状态文件可能残留。

规避策略：OMC 在完成时自动清理 .omc/state/team-state.json。手动清理可使用 omc team shutdown。

问题 3：Windows psmux 兼容性

psmux 只支持 76 个 tmux 命令，不是全部。某些高级功能（如自定义窗口选项）可能不可用。

规避策略：OMC 在 Windows 上只使用 psmux 支持的核心命令。如果检测到不支持的命令，降级到简化模式。

设计取舍

为什么选择 tmux 而非 Docker 容器？

维度	tmux 进程	Docker 容器
启动速度	快（毫秒级）	慢（秒级）
资源消耗	低（共享主机 OS）	高（独立运行时）
CLI 支持	高——任何 CLI 都可以在 tmux 中运行	中——需要容器镜像
跨平台	中——需要 tmux/psmux	高——Docker 支持的平台
隔离性	中——进程级隔离	高——容器级隔离

OMC 的选择：tmux 进程——启动速度快、资源消耗低，适合交互式 Agent 编排场景。Docker 的隔离性更好但启动开销过大。

参考来源

OMC Team Mode 文档 — Team 模式的官方文档
psmux GitHub 仓库 — Windows 原生 tmux 兼容方案
TMUX Team Worktree Mode — Worktree 模式的完整文档

版本信息

📅 2026-05-31 🏷️ v4.14.4 🔀 ed7800d