OpenRig：用 YAML 定义多 Agent 团队，Claude Code 与 Codex 协同作战

A harness wraps a model. A rig wraps your harnesses. Define your agent team in YAML, boot it with one command. Claude Code and Codex in the same rig, managed as one system.

OpenRig turns AI coding agents from a pile of terminal sessions into a persistent, organized team. Talk to a lead agent about the outcome you want; it can coordinate specialists across teams and bring you results and decisions that need your attention. Start with a repository and one useful change, then keep the team's work and context at the same addresses.

安装与首次运行

需要 Node.js 20、22 或 24 以及 tmux。启动 rig 会写入 provider 钩子和工作区信任设置。在运行以下命令之前，请阅读 OpenRig 对你机器做了哪些改动，并备份相关文件。

npm install -g @openrig/cli
rig setup --dry-run

如需使用 Bun 安装，请运行 bun add -g @openrig/cli。OpenRig 仍运行在 Node.js 上，所以也要安装 Node.js 22。Bun 可能会阻止该包的 postinstall 脚本，这种情况下安装时不会运行下述"OpenRig 对你机器做了哪些改动"中描述的 Node.js 和 SQLite 检查。

在执行 rig setup 前先审查其计划——它会检查 native harnesses 和 cmux。该 starter 需要 tmux 和已认证的 Codex；其他 harness 和终端 provider 对其仓库任务而言是可选的。

启动前，请让你的 agent 配置你选择的权限：保留提示词、记住已选命令，或主动选择更广泛的访问权限。agent 负责处理设置和验证；OpenRig 附带的默认值保持不变。

在启动 shell 中检查前置条件：

tmux -V
codex --version
codex login status

在继续之前解决缺失工具或登录问题。从你的仓库中，在启动两个 Codex 席位（owner 和 checker）前审查计划：

cd /path/to/your/repository
rig up first-project --cwd . --plan
rig up first-project --cwd .
rig tui --shared

内核提供独立的操作支持和共享仪表板。如需分离而不停止仪表板，按 Ctrl-b 然后 d；rig tui --shared 返回该视图。单独的 rig tui 打开一个独立视图。关闭查看终端不意味着你应该重新启动团队。

用 rig ps --nodes --rig first-project 检查项目席位就绪状态，并在分配工作前解决任何认证、信任或权限提示。然后给你的 owner 一个bounded outcome（bounded outcome）：

rig send dev-owner@first-project 'Implement <one useful change>. Track the task in the queue and return its ID. Keep it local, verify the behavior, ask dev-check@first-project to check the exact candidate, and record the result and how I can try it.'
rig queue list --destination dev-owner@first-project --limit 1000

发送消息本身不会创建队列项；owner 负责记录任务。阅读最终产物及其精确候选的审查，然后回到同一个 owner 进行下一次变更。引导式首次使用路径涵盖就绪状态、一个有用的任务、一个已审查的结果、Herdr/cmux 终端和恢复。

问题：Discussions › Q&A

Bug 和功能请求：open an issue

贡献：CONTRIBUTING.md · Code of Conduct · Security policy · Getting help

视频：youtube.com/@openrig

版本：GitHub Releases and npm @openrig/cli

我们力求在一天内回复 issues 和 pull requests；参见 CONTRIBUTING.md 了解审查目标。

OpenRig 对你机器做了哪些改动

OpenRig 在设置和运行过程中写入实例状态、provider 集成和工作区文件。包括信任设置和可执行钩子。下面的总结跟随此源码版本；使用发布包时请检查 rig --version，因为仓库文档可能领先于 npm。

provider 文件与实例状态是分开的。这里的 ~ 指守护进程用户的主目录；单独更改 OPENRIG_HOME 不会隔离 provider 配置。

Claude Code: managed startup 将工作区信任和 onboarding 完成状态写入 ~/.claude.json。在工作区中，.claude/settings.local.json 接收 context collector 的 statusLine 命令和选定的 activity hooks；辅助脚本位于 .openrig/ 下。选定的 settings/MCP 资源也可能更改该 settings 文件和 .mcp.json。共享 settings 资源将 permissions.defaultMode 设置为 acceptEdits，并启用 Exa/Context7 MCP 条目；选定的 MCP 资源配置那些外部服务。内置 bootstrap 不再向 ~/.claude/settings.json 写入命令 allowlist 或删除旧的白名单。信任写入器使用守护进程主目录，因此自定义 CLAUDE_CONFIG_DIR 不是这些写入的通用重定位方案。

Codex: 写入守护进程的 CODEX_HOME/config.toml（通常为 ~/.codex/config.toml）。启动时启用 hooks、添加 OpenRig activity relay 命令，并为这些命令预写信任哈希。席位启动时为工作区添加 trust_level = "trusted"；选定的 config 资源可以添加 MCP 设置。在启动期间可以跳过已识别的更新通知，将跳过的版本记录在 Codex 的缓存中；这不是安装更新。

Activity relays 将事件类型/子类型、席位/运行时身份、时间戳和原生会话身份发送到配置的 OpenRig 守护进程的 /api/activity/hooks 端点，使用其 activity token。该 payload 不包含提示词文本和工具参数。Claude 的 collector 将 context/token 使用量、会话/转录路径元数据和可用的 rate-limit 数据写入实例的 state/context-usage 和 state/provider-usage。Provider 和选定的 MCP 连接有各自的数据流。守护进程插件初始化也会检查 GitHub 上的 OpenRig 插件发布端点。

Managed launches 供应 HOME、CODEX_HOME 和 OPENRIG_* 身份/连接变量。Claude 使用 --permission-mode acceptEdits，默认使用经典渲染器处理终端回滚。Codex 使用 -s workspace-write，除非命名 profile 管理其沙箱；OpenRig 不强制 approval-policy 标志。新的 Codex 启动还会通过 --add-dir 添加对工作区 .git 和 pod 共享 queue-state 目录的可写访问；共享根目录来自 OPENRIG_SHARED_DOCS_ROOT 或 ~/.openrig/shared-docs。YOLO 默认关闭。显式 OPENRIG_YOLO=1 或完全 bypass 的席位策略会选择 Claude 的 --dangerously-skip-permissions 或 Codex 的 -s danger-full-access；已解析的席位策略优先于环境设置。

Managed hook 块针对 OpenRig 的条目，保留无关的 hooks，但信任条目、选定的资源密钥和 Claude 现有的 status-line 命令可能被替换。一些写入器将不可读的设置恢复为空对象；这不是完整的保留或回滚保证。在首次使用前备份相关文件。守护进程/bootstrap 写入是自动的，并非每个都有交互式预览；rig setup --dry-run 不会预览每个后续启动效果。

OpenRig is a multi-agent harness — it manages the system that coding agents form when you run them together. Not the agents themselves, but the team they create: which sessions are running, how they relate, how to recover after a reboot, and how to stop it from becoming terminal sprawl.

Define topologies in YAML (RigSpec) with pods, edges, and continuity policies

Boot everything with rig up — tmux sessions, harnesses, startup files, readiness checks

See rigs, pods, and seats in the TUI topology table and graph; inspect projects, specs, feeds, and instance health

Discover existing Claude Code and Codex sessions in tmux and adopt them into a managed rig

Snapshot the topology with rig down --snapshot, restore by name with rig up <name>

Communicate across agents with rig send, rig broadcast, and rig chatroom

Evolve running topologies with rig grow, rig shrink, rig launch, rig remove

每个智能体运行在独立的 tmux 会话中，你可以直接 attach、检查和操作。

使用 first-project 作为专注的首次使用路径。product-team 是一个可选的大型产品开发示例：

rig specs preview product-team --kind rig
rig up product-team

当你需要一个更大的产品团队时使用它：两个编排器、一个实施者、一个 QA、一个设计师，以及两个独立的审查者。

更小的入门版本是 conveyor：

rig specs preview conveyor --kind rig
rig up conveyor

conveyor 是一个四人小队，混合了 Claude Code 和 Codex。它展示了一条贯穿 intake、规划、构建和审查的交接路径；first-project 仍是更小的双人起点。

还包含：implementation-pair、adversarial-review、research-team 和 secrets-manager（由专业智能体管理的 HashiCorp Vault）。

rig specs ls

OpenRig 是一个本地守护进程 + CLI + 终端 UI + MCP 服务器，构建在 tmux 之上。旧的 React Web UI 仍在维护模式，提供尽力而为的支持。

CLI / TUI / MCP
      |
Hono HTTP daemon
      |
  Domain services
      |
  SQLite + tmux + runtime adapters

CLI：面向人类和智能体的命令，用于启动团队、检查状态、发送消息、跟踪负责的工作和管理上下文。

TUI：拓扑浏览器、表格和图形视图、席位详情、Specs、Projects、Terminals、Feed 和 System。用键盘、鼠标或命令栏导航。

MCP：供智能体管理自身拓扑的工具（rig_up、rig_ps、rig_send、rig_chatroom_send 等）

运行时：原生 Claude Code 和 Codex 会话、终端节点，以及使用终端窗格内 RPC 运行器的 Pi 适配器。

终端 UI 和工作区

TUI 显示团队的协作状态；herdr 和 cmux 在其旁边显示实际的智能体终端。使用 rig tui 命令列出 TUI 的命令栏导航，或尝试交互式 TUI 导览。

使用虚构项目数据从交互式 TUI 演示中捕获。

安装并连接 herdr 后，一起打开启动模板的终端：

rig terminal open first-project --provider herdr

对于 cmux，使用 --provider cmux。底层会话仍可通过 tmux 访问。参见终端工作区指南，了解设置和返回现有视图。

RigSpec：YAML 中的声明式多智能体 harness 定义。包含 Pod、成员、边、连续性策略和文化文件。

AgentSpec：可重用的智能体蓝图，包含技能、指南、钩子、配置文件和启动契约。

Seat：rig 中的稳定角色和地址，例如 dev-owner@first-project。占用它的对话可以变化，但其身份和创作内容保持不变。

Pod：一组相关的席位，共享指南和上下文。每个智能体仍有自己的上下文窗口。

Discovery：rig discover 对现有 tmux 会话进行指纹识别。rig adopt 将它们纳入管理。

快照/恢复：rig down --snapshot 捕获完整状态。rig up <name> 从最新快照恢复。恢复报告每个节点的结果（已恢复、全新或失败）。

RigBundle：包含供应商 AgentSpecs 和 SHA-256 完整性的可移植归档。跨机器共享拓扑。

Culture：CULTURE.md 为团队设置协作规范。研究型 rig 获得探索性文化。实施型 rig 获得保守的、信任但验证的文化。

智能体管理的软件

rig 可以将实际软件打包到管理它的智能体旁边。附带的示例是 secrets-manager：一个由专业智能体运营的 HashiCorp Vault 实例。

rig up secrets-manager
rig env status secrets-manager
rig send vault-specialist@secrets-manager "Check Vault health and report status." --verify

服务型 rig 和托管应用需要 Docker。

升级现有实例

对于现有安装，按照升级步骤和 0.5.14 发布说明操作。升级期间保留实时席位；rig down 不是升级步骤。

跨越 0.5.9 布局边界

从 pre-0.5.9 实例升级时，以下迁移仍然适用。

0.5.9 将 $OPENRIG_HOME/context 设为可寻址的上下文库，将 Claude 遥测写入 state/context-usage（提供商遥测写入 state/provider-usage），并在 context/system/system-world.yaml 安装默认 System World。现有实例通过附带的 openrig-upgrade skill 进行智能体操作迁移。目标运行时以规范优先、遗留回退的方式读取；新写入使用规范根目录；自定义 context-library 根目录在激活期间保持稳定。这不是目录重命名，不要在旧收集器仍在写入时执行。

# SKILL_DIR 是已安装的 openrig-upgrade skill 目录。
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --help
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME"
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME" --apply-state --preimage /safe/path/layout-0.5.9-before

# 单独激活确切的目标运行时。在每个有界的遗留尾部之后，都有新配对样本同时出现在新的状态根目录下：
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME" --verify --preimage /safe/path/layout-0.5.9-before > /safe/path/layout-0.5.9-verify.json

# 仅使用该确切收据运行单独调用的非破坏性最终化器：
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME" --apply-library --preimage /safe/path/layout-0.5.9-before --verification /safe/path/layout-0.5.9-verify.json

# 如果观察到的升级必须回滚，仅恢复 helper 拥有的准备/最终化效果：
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME" --rollback /safe/path/layout-0.5.9-before

--help 打印阶段语法而不清点实例。没有阶段标志故意运行只读计划；未知选项在计划或变更之前以非零退出。

每个阶段都发出 JSON。在任何问题或不完整收据时停止，并遵循其下一步操作；不要从复制的遗留遥测盲目继续或重试部分变更。准备工作保留遗留状态和收集器设置。验证仅在同一个席位在 state/ 下有更新的配对上下文和提供商样本时接受确切的尾部字节；最终化重新验证接受的尾部，复制库而不覆盖，最后切换配置。helper 永远不会删除遗留遥测或库。退役遵循独立的稳定运行时、写入器、读取器和恢复证明。守护进程、数据库、席位、插件和发布生命周期操作仍由智能体拥有。

Node.js 20、22 或 24（此版本支持这些版本）

herdr 或 cmux 用于终端工作区，将智能体们显示在一起

用于服务型 rig 和托管应用的 Docker

安装和故障排除

rig setup 尝试核心机器准备：tmux、cmux、Claude Code、Codex 和 tmux 默认配置。它报告尝试的内容和实际成功的部分。如果某些失败，它为本地智能体提供足够的上下文来完成任务。

rig setup --full 在核心基础上尝试更广泛的操作员工作站设置（jq、gh）。

rig doctor 检查当前系统健康状况，并帮助在设置后诊断问题。当某些东西停止工作或机器变更后使用它。

两个命令都支持 --json 用于智能体驱动的工作流。

在设置或托管启动之前，查看 OpenRig 对你机器的更改，包括提供商信任、钩子和选定的运行时资源。

已运行并被 adopt 的会话可能需要重启才能获取新写入的运行时配置。

对于智能体：在选择调用之前，询问用户想要核心设置（rig setup）还是更完整的工作站路径（rig setup --full）。用 --json 检查结果，并使用 rig doctor 完成任何剩余的机器特定问题。

与 Claude Managed Agents 的比较

OpenRig 是开源且自托管的，Claude Code 和 Codex 在同一团队中。你在自己的基础设施上运营它；选定的提供商的模型使用费用仍然适用。

文档：openrig.dev/docs（面向智能体的文档索引）

博客：openrig.dev/blog · 为什么我构建了 OpenRig

开放规范：openrig.dev/specs

视频：youtube.com/@openrig

关注项目：openrig.dev/follow