OpenRig 技术解读：用 YAML 把 Claude Code 和 Codex 编排成一支团队

在同一个仓库里同时开两三个 AI 编程代理，多数人的工作流还停留在多开几个终端窗口：每个窗口登录一个 CLI，人工在窗口之间传话、复制报错、盯着进度。OpenRig（mvschwarz/openrig）给这件事加了一套编制制度：用 YAML 文件定义谁当负责人、谁当校验者，用常驻守护进程管理座位（seat），用持久队列传递任务，让 Claude Code 和 Codex 作为同一个系统里的成员协作。README 开头那句定位写得精确：harness 包住一个模型，rig 包住你的所有 harness。

分层架构：daemon、kernel、rig 与 seat

OpenRig 的运行时分成四层。最底下是 daemon，一个常驻守护进程，提供 HTTP 健康检查和队列服务；中间是 kernel，一个随 daemon 自动启动的特殊 rig，负责运营支持和共享仪表盘；再往上是各个 rig（团队），每个 rig 由若干 seat（座位）组成，一个 seat 对应一个真实的 CLI 代理会话。

tmux 充当传输层：每个 seat 跑在自己的 tmux 会话里，OpenRig 通过向 tmux pane 键入内容来驱动底层 CLI。CLI 的版本、登录态、权限模式全部沿用你机器上已装好的那一份，OpenRig 不复制凭据、不接管账号。这也解释了它对依赖的严格要求：Node 22/24 与 tmux 缺一不可，Apple silicon 机型上目前只认 Node 22，Node 20 已停止支持。

健康信号在这个架构里是分离的。daemon 的 HTTP 健康检查绑定得很早，kernel 可能还在启动中；rig status 把 kernel 就绪状态单独暴露（走 /api/kernel/status 接口），rig daemon start --wait-for-kernel 会轮询等待。文档反复强调一条原则：所有状态汇报只描述当前是什么，从不保证下游工作会成功。daemon up 不等于每个 agent 健康，workspace 处于 live 状态也不等于它就是你项目对应的那个目录。

用 YAML 写编制：RigSpec 与 AgentSpec

团队结构由 RigSpec 定义，成员能力由 AgentSpec 定义。官方提供三个起步编制，对应三种账号组合：first-project 是两个 Codex 代理（模型钉在 gpt-6-astra），first-project-claude 是两个 Claude 代理（沿用原生默认模型），first-project-mixed 是 Claude 当负责人、Codex 当校验者。三个编制用同一套 owner/checker 角色分工和同一个任务。

一个 AgentSpec 长这样（官方 implementer 示例节选）：

name: implementer
version: "1.0"
description: Implementation agent — writes code following TDD discipline

defaults:
  runtime: claude-code

imports:
  - ref: local:../../shared

profiles:
  default:
    uses:
      skills: [openrig-user, development-team, test-driven-development]
      guidance: []

resources:
  guidance:
    - id: role
      path: guidance/role.md

startup:
  files:
    - path: guidance/role.md
      delivery_hint: send_text
      required: true

resources 声明这个 agent 拥有的资源池（skills、guidance、hooks、subagents、runtime_resources 五类），profiles 里的 uses 从池子里挑选本次激活的子集。startup 块定义上下文注入方式：delivery_hint: send_text 表示文件内容作为文本直接发进会话，guidance_merge 走引导合并，applies_on: [fresh_start] 表示只在全新会话注入。imports 支持 local: 相对引用和 path: 绝对引用，版本约束只接受精确版本，^ 和 ~ 这类范围语法会被直接拒绝——编制文件里的每个依赖都得钉死。

生命周期同样显式。execution_mode 在 v1 里只有 interactive_resident 一个合法值（wake_on_demand 被校验器明确拒绝）；compaction_strategy 提供四档上下文压缩策略：default-compaction、managed-compaction、handover、apprentice-handover；restore_policy 决定重启后的恢复方式，默认 resume_if_possible。这些字段都有默认值，但全部写在纸面上，可审计。

任务怎么跑：持久队列与 seat 地址

给团队派活的入口是一条消息：

rig send "dev-owner@first-project" 'Improve the CSV import error when a
required column is missing: name the column and leave the existing data
unchanged. Add a regression check, ask dev-check for an independent check
of the exact candidate, and record the result and how I can try it.'

seat 地址的格式是 角色名@rig名。rig send 创建一个持久任务：owner 落地实现，然后把候选改动路由给 dev-check 做独立校验，结果和验证方式记录回队列。人不需要在两个终端之间传话。

队列操作是显式的：rig queue list 默认只显示调用者所在 rig 的义务，rig queue show <id> --full 看单个任务详情，rig queue transitions 看状态迁移历史。文档里有一句值得所有多代理工具抄写的话：一条已送达的消息不是一个已评审的结果。消息进了对方的会话，不等于工作完成了，读完工件、实际运行、确认候选改动通过评审之后才算数。

和队列配套的是 scope 与 workflow 两个原语，文档专门提醒别混淆。rig scope 管理磁盘上的持久工件（mission 和 slice 文件），记录要做的活是什么；rig workflow 管理运行时实例，执行 instantiate 时守护进程创建工作流实例加一个入口队列项，把第一步路由给 owner，解决下一步谁来做的问题。创建或编辑 mission 不会启动任何工作，定义和执行在数据模型层面就是分开的。

权限模型：批准与沙箱是两回事

OpenRig 对权限的拆解比多数同类项目细。它反复区分两件事：approval（批准）决定一个动作能不能执行，sandbox（沙箱）决定进程的文件系统和网络访问范围。关掉批准并不会授予网络访问权，这两个维度在 Codex 和 Claude 的原生机制里纠缠在一起，OpenRig 把组合方式全部摊开在文档里。

默认启动参数相当克制：Codex 座位用 -s workspace-write（工作区可写，网络默认封锁，包括本地 OpenRig daemon 的端口），Claude 座位用 --permission-mode acceptEdits（文件编辑放行，其余动作走原生规则与提示）。要放开，路径有三条：

1. 给 Codex 配命名 profile，在 rig 里用 codex_config_profile 指向一个写好 sandbox_mode 和 approval_policy 的 .config.toml；
2. 用 rig policy apply yolo 显式记录 bypass 策略，下一轮受管启动传入 --dangerously-skip-permissions；
3. 对单个座位执行 rig seat set-permissions owner@first-project --mode full_bypass --reason "Operator selected broader access"，这条命令把操作者、理由、新旧选择都记录在座位上，不重新启动会话，也不改动兄弟座位。

优先级规则同样写明：AgentSpec 成员级 permission_policy 覆盖 rig 级设置；Codex 侧从 CLI 参数、trusted project settings、所选 profile 到用户设置逐层覆盖；Claude 侧 managed settings 先于 launch flag，先于项目本地与项目共享设置。每一次权限选择和后续启动都重新校验支持性，没有缓存。

文档里的方法论：规划档位与知识成熟度

OpenRig 的 reference 目录下有二十多篇参考文档，其中两篇讲的已经超出这个软件本身，是它给代理团队内置的工作方法论。

一篇是规划档位（planning dial），P0 到 P4 五档。P0 是几句可观察结果加指针，把怎么实现留给执行者；P1 是正式 spec，默认档；P2 在 spec 冻结前加一轮研究，研究可以并行铺开网络、文档、代码阅读多条线，但返回的是带引用的上下文而非处方；P3 加一轮对抗评审，由持有产品上下文的非作者从两个方向攻击计划，修订必须落成带复选框的证明契约，拒绝散文式建议；P4 加盲设计门，先不看既有方案独立做一版设计再 diff，差异显著就停下来和 owner 开设计会。档位按什么选？文档给出的判别式是：一个错误计划的代价是否高昂、难以回退、且从作者视角不可见。重要性本身构不成升档理由。配套的 context gate 规定：只有装了产品世界上下文的 agent 才能撰写研究提示、跑对抗评审，不知道产品是干什么的 agent 写出的研究提示，会流畅地回答一个错误的问题。

另一篇是知识成熟度阶梯。知识分四级：DATA（流事件、日志，持续变化）到 FIELD NOTES（天到周级变化）到 INSIGHTS（月级稳定）到 CANON（年级别，几乎不变），相邻两级的变化速率差大约一个数量级，信任度跟着内容所在的地址走。晋升是显式动作：harvest、用自己的话折叠、注明日期的 curate，晋升的断言必须携带压缩过的 warrant（证据）。文档里那句原话：没有 warrant 的 canon 是格式良好的货物崇拜。canon 的 diff 应该读起来像增补，频繁修改既有 canon 行是个坏味道，要么那行从来不是 canon，要么发生了值得仪式感的转向。

两篇文档指向同一个设计取向：OpenRig 把 AI 代理团队当组织来治理。编制有 spec，任务有队列，规划纪律有档位，组织记忆有阶梯，每一样都落在仓库里的文本文件上。

上手路径与边界

上手四条命令：

npm install -g @openrig/cli
rig setup --dry-run          # 预览会改动哪些本机设置
cd your-repository
rig up first-project --cwd . # 启动双 Codex 编制
rig tui --shared             # 打开共享仪表盘

rig setup --dry-run 会预览完整的本机改动；正式执行 setup 前文档要求先读「OpenRig 会改动你机器上的什么」一节并备份相关文件。启动后 agent 会问一次「是否允许代理免重复提示运行 rig 命令」，答 No 则保留原生提示，答 Yes 也只覆盖 rig 命令族，不碰沙箱和网络设置，随时可以说一句 undo 撤销它加过的全部规则。

边界要说清：macOS 和 Linux，Node 22/24 加 tmux；原生 Windows 不支持，WSL2 未测试。已有 Claude Code 或 Codex 账号即可开跑，不需要第二个订阅——kernel 启动时按原生登录探测结果自动选择 Claude、Codex 或两者混用的变体，没装的账号不构成阻塞。kernel 也能放进 Herdr 或 cmux 这类终端管理器（rig terminal open --provider herdr），两者都是可选项，不装不影响主流程。

三个起步编制刻意保持小型，七个座位的展示编制是可选项，消耗更多并发容量。想自定义编制，把安装目录里的整个 specs 目录复制成仓库里的 ./openrig-specs 再改，只复制 rig.yaml 一个文件会断掉内部相对引用，这是文档明确警告的坑。

对一个已经付费订阅 Claude Code 或 Codex、又想在同一个仓库里跑多代理工作流的开发者，OpenRig 提供的是一层此前缺失的组织结构：座位有地址，任务有队列，权限有档位，记忆有阶梯。团队的定义、成员的能力、规划与记忆的纪律全部是仓库里的文本文件，可版本管理，可代码评审，可审计。

来源：

• 仓库：mvschwarz/openrig（Apache-2.0）
• 官方文档：Getting started、AgentSpec Reference、The planning dial、Knowledge maturity（docs/reference/）