openrig

OpenRig

harness 包裹一个模型。rig 包裹你的所有 harness。用 YAML 定义你的 agent 团队，一条命令即可启动。Claude Code 与 Codex 同处一个 rig，作为一个系统统一管理。

OpenRig 将 AI 编码 agent 从一堆终端会话，转变为一个持久、有组织的团队。你只需向 lead agent 说明想要的结果；它能够跨团队协调专职 agent，并把结果以及需要你关注的决策带回来。从一个仓库和一处有用的改动开始，随后让团队的工作与上下文始终停留在相同的地址上。

安装与首次运行

需要 Node.js 20、22 或 24，以及 tmux。启动一个 rig 会写入 provider hooks 与 workspace 信任设置。在运行下列命令之前，请阅读 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 之前，先审阅 setup 的计划：它会同时检查原生 harness 与 cmux。本入门流程需要 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

kernel 提供独立的运维支持以及共享仪表盘。若要脱离而不停止仪表盘，请按 Ctrl-b 然后按 d；rig tui --shared 会回到该视图。单纯运行 rig tui 会打开一个独立的视图。关闭查看终端并不意味着你应该重新启动团队。

用 rig ps --nodes --rig first-project 检查项目席位的就绪状态，并在分派工作前解决任何认证、信任或权限弹窗。然后从你的仓库中给 owner 一个范围明确的结果目标：

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 与功能请求： 提交 issue
• 参与贡献： CONTRIBUTING.md · 行为准则 · 安全策略 · 获取帮助
• 视频： youtube.com/@openrig
• 发行版本： GitHub Releases 以及 npm @openrig/cli

我们力争在一天内响应 issue 与 pull request；审阅目标请参见 CONTRIBUTING.md。

OpenRig 会在你的机器上改动什么

作为 setup 与运行过程的一部分，OpenRig 会写入实例状态、provider 集成以及 workspace 文件。其中包括 信任设置和可执行 hook。下文的概览对应本源码版本；使用已发布的包时请检查 rig --version，因为仓库中的指引可能领先于 npm。

时机	改动内容与原因
npm 安装	在你的 npm prefix 下（使用 Bun 时为 Bun 的全局目录）安装 CLI、捆绑组件和依赖。OpenRig 的 postinstall 会检查 Node.js 版本以及 SQLite 模块能否加载；Bun 可能会拦截该脚本。它不会运行 daemon 或 provider setup。
rig setup	尝试安装缺失的工具，并在 ~/.tmux.conf 中写入一段 OpenRig 配置块以支持鼠标和回滚缓冲。在 macOS 上它可能安装 cmux，并在 ~/.config/cmux/settings.json 中启用其自动化 socket 控制。--full 会额外安装工作站工具。--dry-run 展示 setup 的计划而不实际应用。
Daemon 启动	在 OPENRIG_HOME（通常为 ~/.openrig）下创建/更新实例状态，包括其数据库和托管的 plugin 资源。在 ~/.claude/skills 和 ~/.agents/skills 中植入 openrig-skills 发现 skill，受现有版本归属约束。当 runtime.codex.hooks_enabled 启用（默认）时，会写入 Codex hook 配置和信任记录，如下文所述——甚至在一个 rig 启动之前就会写入。
Rig/席位启动与接入	创建 tmux 会话，提供席位身份和 daemon 连接环境，并将选定的指引、skill、plugin 和运行时资源投射到 workspace。托管启动会预先信任该 workspace。对于已接入的会话，也可以配置 Claude 上下文采集并在监控期间刷新。
显式权限配置	内置 bootstrap 不会添加 rig 命令允许规则。请让你的 agent 应用你所选定的项目级或用户级作用域；现有规则依然有效。更宽泛的访问权限是另一项独立选择。

provider 文件与实例状态是分开的。此处的 ~ 指 daemon 用户的 home 目录；仅修改 OPENRIG_HOME 并不能隔离 provider 配置。

• Claude Code： 托管启动会把 workspace 信任和 onboarding 完成状态写入 ~/.claude.json。在 workspace 中，.claude/settings.local.json 会写入上下文采集器的 statusLine 命令和选定的活动 hook；辅助脚本位于 .openrig/ 下。选定的 settings/MCP 资源也可能改动该 settings 文件和 .mcp.json。共享 settings 资源会把 permissions.defaultMode 设置为 acceptEdits，并启用 Exa/Context7 MCP 条目；选定的 MCP 资源会配置这些外部服务。内置 bootstrap 不再向 ~/.claude/settings.json 写入命令允许列表，也不会移除较早的允许项。信任写入器使用 daemon 的 home 目录，因此自定义 CLAUDE_CONFIG_DIR 并不能普遍地重定向这些写入。
• Codex： 写入 daemon 的 CODEX_HOME/config.toml（通常为 ~/.codex/config.toml）。启动时会启用 hook、添加 OpenRig 活动中继命令，并预先为这些命令写入信任哈希。席位启动会为该 workspace 添加 trust_level = "trusted"；选定的 config 资源可以添加 MCP 设置。启动期间可以跳过识别出的更新通知，并在 Codex 的缓存中记录被跳过的版本；这并不是安装更新。

活动中继会把事件类型/子类型、席位/运行时身份、时间戳和原生会话身份，使用其活动 token 发送到已配置的 OpenRig daemon 的 /api/activity/hooks 端点。该载荷不包含 prompt 文本和工具参数。Claude 的采集器会把上下文/token 用量、会话/transcript 路径元数据以及可获取的速率限制数据写入实例的 state/context-usage 和 state/provider-usage。provider 以及选定的 MCP 连接有其各自的数据流。Daemon plugin 初始化还会检查 GitHub 上的 OpenRig plugin 发行端点。

托管启动会提供 HOME、CODEX_HOME 以及 OPENRIG_* 身份/连接变量。Claude 使用 --permission-mode acceptEdits，并默认使用经典渲染器以获得终端回滚缓冲。Codex 使用 -s workspace-write，除非有具名 profile 管控其沙箱；OpenRig 不会强制指定审批策略标志。全新的 Codex 启动还会通过 --add-dir 为 workspace 的 .git 以及 pod 的共享队列状态目录添加可写访问权限；共享根目录来自 OPENRIG_SHARED_DOCS_ROOT 或 ~/.openrig/shared-docs。 YOLO 是默认关闭的。显式设置 OPENRIG_YOLO=1 或采用完全绕过式席位策略，会选择 Claude 的 --dangerously-skip-permissions 或 Codex 的 -s danger-full-access；已解析的席位策略优先于环境变量设置。

托管 hook 块只针对 OpenRig 的条目，并保留无关的 hook，但信任条目、选定的资源键以及 Claude 现有的 status-line 命令可能被替换。某些写入器在遇到无法读取的 settings 时会将其恢复为空对象；这并不构成完整的保留或回滚保证。首次使用前请备份相关文件。Daemon/bootstrap 的写入是自动的，并非每一项都有交互式预览；rig setup --dry-run 不会预览之后每一次启动的效果。

它能做什么

OpenRig 是一个多 agent harness——它管理的是编码 agent 一起运行时形成的系统。不是管理 agent 本身，而是管理它们组成的团队：哪些会话正在运行、它们如何关联、重启后如何恢复，以及如何避免其演变成终端泛滥。

• 定义 拓扑（RigSpec），以 YAML 描述 pod、边以及连续性策略
• 启动 一切：rig up 负责 tmux 会话、harness、启动文件、就绪检查
• 查看 rig、pod 和席位：在 TUI 的拓扑表和图中查看；检查项目、spec、feed 以及实例健康状况
• 发现 tmux 中现有的 Claude Code 和 Codex 会话，并将其纳入托管的 rig
• 快照 拓扑：rig down --snapshot，按名称还原：rig up <name>
• 通信 跨 agent 交互：rig send、rig broadcast 和 rig chatroom
• 演化 运行中的拓扑：rig grow、rig shrink、rig launch、rig remove

每个 agent 都运行在一个 tmux 会话中，你可以直接接入、查看和操作。

入门 Rig

使用 first-project 走聚焦的首次使用路径。product-team 是一个可选的大型产品开发示例：

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

当你想要一支规模更大的产品小队时使用它：两个 orchestrator、实现、QA、设计，以及两个独立评审者。

若想要更小的入门示例，可使用 conveyor：

rig specs preview conveyor --kind rig
rig up conveyor

conveyor 是一个四席位的入门 rig，混合了 Claude Code 与 Codex。它展示了一条经由 intake、planning、build 和 review 的交接路径；first-project 仍然是更小的两席位起点。

此外还附带：implementation-pair、adversarial-review、research-team 和 secrets-manager（由专职 agent 管理的 HashiCorp Vault）。

浏览库：

rig specs ls

工作原理

OpenRig 是一个本地 daemon + CLI + 终端 UI + MCP server，构建于 tmux 之上。较旧的 React web UI 仍处于维护模式，提供尽力而为的支持。

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

• CLI：供人和 agent 使用的命令，用于启动团队、检查状态、发送消息、跟踪已认领的工作以及管理上下文。
• TUI：拓扑浏览器、表格与图形视图、席位详情、Specs、Projects、Terminals、Feed 和 System。可通过键盘、鼠标或命令栏导航。
• MCP：一系列工具，让 agent 能够管理自己的拓扑（rig_up、rig_ps、rig_send、rig_chatroom_send 等）
• 运行时：原生 Claude Code 和 Codex 会话、终端节点，以及一个在终端面板内使用 RPC runner 的 Pi adapter。

终端 UI 与 Workspace

TUI 展示团队的协调状态；herdr 和 cmux 在其旁边展示实际的 agent 终端。使用 rig tui commands 列出 TUI 的命令栏导航，或 试试交互式 TUI 导览。

取自交互式 TUI 演示，使用了虚构的项目数据。

在已安装并连接 herdr 的情况下，一同打开入门 rig 的终端：

rig terminal open first-project --provider herdr

对于 cmux，使用 --provider cmux。底层会话仍可通过 tmux 访问。配置以及回到现有视图的方法，请参见 终端 workspace 指南。

核心概念

• RigSpec：以 YAML 声明的多 agent harness 定义。包含 pod、成员、边、连续性策略、culture 文件。
• AgentSpec：可复用的 agent 蓝图，包含 skill、指引、hook、profile 以及启动契约。
• Seat（席位）：rig 中稳定的角色与地址，例如 dev-owner@first-project。占据该席位的会话可以更替，而其身份和由其编写的上下文保持不变。
• Pod：一组相关席位，共享指引与上下文。每个 agent 仍然拥有自己的上下文窗口。
• Discovery（发现）：rig discover 对现有 tmux 会话进行指纹识别。rig adopt 将它们纳入管理。
• Snapshot/Restore（快照/还原）：rig down --snapshot 捕获完整状态。rig up <name> 从最新快照还原。还原会按节点报告结果（已恢复、全新或失败）。
• RigBundle：可移植归档，内含 vendored AgentSpec 并通过 SHA-256 校验完整性。可跨机器共享拓扑。
• Culture（文化）：CULTURE.md 为整个团队设定协调规范。研究类 rig 采用探索性文化。实现类 rig 采用保守的、信任但验证的文化。

Agent 管理的软件

一个 rig 可以把实际的软件与负责管理它的 agent 一起打包。随附的示例是 secrets-manager：一个由专职 agent 运维的 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 的布局边界

从 0.5.9 之前的实例升级时，下面的迁移仍然适用。

0.5.9 将 $OPENRIG_HOME/context 作为可寻址的上下文库，把 Claude 遥测写入 state/context-usage（并把 provider 遥测写入 state/provider-usage），并在 context/system/system-world.yaml 安装默认的 System World。现有实例通过随附的 openrig-upgrade skill 进行一次 由 agent 操作的迁移 来跨越此边界。目标运行时会优先读取 canonical、回退到 legacy，而新写入使用 canonical 根目录；自定义的上下文库根目录在激活期间保持稳定。这并非在旧采集器仍在写入时可以简单执行的目录重命名。

# SKILL_DIR is the installed openrig-upgrade skill directory.
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

# Activate the exact target runtime separately. After every bounded legacy tail is followed by newer paired samples at both new state roots:
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

# Run the separately invoked non-destructive finalizer only with that exact receipt:
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

# Restore only helper-owned preparation/finalizer effects if the observed upgrade must be reversed:
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME" --rollback /safe/path/layout-0.5.9-before

--help 会打印各阶段的语法，而不会清点该实例。没有哪个阶段标志会刻意运行只读计划；未知选项会在计划或变更之前以非零状态失败。

每个阶段都会输出 JSON。遇到任何问题或不完整的回执时请停下，并遵循其 next 动作；不要从已复制的 legacy 遥测继续，也不要盲目重试部分变更。准备阶段会保留 legacy 状态和采集器设置。仅当同一席位在 state/ 下拥有更新的成对 context 和 provider 样本时，验证阶段才会接受精确的尾部字节；终结阶段会重新校验已接受的尾部，以不覆盖的方式复制库，并最后切换配置。该 helper 从不删除 legacy 遥测或库。退役需要另外分别具备稳定的运行时、写入器、读取器和恢复证明。Daemon、数据库、席位、plugin 以及发行的生命周期动作仍然由 agent 负责。

环境要求

• Node.js 20、22 或 24（本发行版支持的版本）
• tmux

可选：

• herdr 或 cmux，用于在同一视图中展示各 agent 的终端 workspace
• Docker，用于由服务支撑的 rig 和托管应用

Setup 与故障排查

• rig setup 会尝试进行核心的机器准备：tmux、cmux、Claude Code、Codex 以及 tmux 默认值。它会报告尝试了什么以及实际成功了什么。若有失败，它会为本地 agent 提供足够的上下文以完成任务。
• rig setup --full 会在核心之外尝试更全面的操作员工作站配置（jq、gh）。
• rig doctor 检查当前系统健康状况，并帮助诊断 setup 之后的问题。当有东西停止工作或机器发生变动后使用它。

两条命令都支持 --json，以便用于由 agent 驱动的工作流。

在 setup 或托管启动之前，请审阅 OpenRig 会在你的机器上改动什么，包括 provider 信任、hook 以及选定的运行时资源。

已在运行中被纳入的会话可能需要重启，才能获取新写入的运行时配置。

给 agent 的说明： 在选择调用方式之前，先询问用户是想要核心 setup（rig setup）还是更完整的工作站路径（rig setup --full）。用 --json 检查结果，并使用 rig doctor 完成任何剩余的机器特定问题。

与 Claude Managed Agents 的比较

OpenRig 是开源且自托管的，Claude Code 和 Codex 同处一个团队。你在自己的基础设施上运行它；所选 provider 的模型使用费用仍然适用。

完整对比

链接

• 网站：openrig.dev
• 文档：openrig.dev/docs（供 agent 使用的文档索引）
• 博客：openrig.dev/blog · 我为什么构建 OpenRig
• 开放规范：openrig.dev/specs
• 视频：youtube.com/@openrig
• X：@_feralmachine
• 关注项目：openrig.dev/follow

Star 历史

许可证

Apache 2.0