10 分钟让 Claude Code 和 Codex 同屏开黑：OpenRig 首跑保姆级指南

【免费下载链接】openrigBuild your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, shared context and owned work.项目地址: https://gitcode.com/GitHub_Trending/op/openrig

让 Claude Code 和 Codex 同时在一个终端里各干各的活，互相评审、共享上下文、掉线后还能恢复现场——听起来像是要把几个"各自为政"的 CLI 进程硬塞进一个编排系统。OpenRig 的做法是：不碰这两个工具本身，而是用 YAML 定义"战队拓扑"（RigSpec），用 tmux 管理会话边界，用一个本地 daemon 统一调度。本文不绕弯子，直接带你走完从环境核查到第一支双引擎 Agent 战队上线验证的完整路径，每一步都有仓库源码作为依据。

环境核查：Node 22/24 与 tmux 前置清单

OpenRig 的前置要求收敛成两条硬性条件：Node.js 版本和 tmux。系统支持的平台是 macOS 与 Linux（Windows 用户走 WSL2，原生 Windows 不受支持）。

先说 Node.js。README 与 CLI 源码的结论完全一致：只支持 Node.js 22 和 24 两个偶数 LTS 大版本。打开 node-support.ts 可以看到支持策略的实现：

export const SUPPORTED_NODE_MAJORS = [22, 24] as const;

• 低于 22 的大版本直接拒绝，源码注释解释了原因：SQLite 绑定better-sqlite3 13要求 Node 22 以上，在 Node 20 上会直接崩溃；
• 奇数版本（如 21、23）不支持，理由是只认 LTS 偶数线；
• 高于 24 的偶数版本（如 26）目前"允许但未测试"，preflight 会给出 warning 而不是直接拦截。

网上不少文章还在讲"Node 20/22/24 都行"，那是旧版本的信息。按当前仓库代码，nvm install 22是最稳妥的选择；Apple Silicon（M 系列 Mac）上务必使用 Node 22，以规避 better-sqlite3 预编译产物缺失导致的安装与运行时故障。

tmux 是第二道硬门槛，它是 Agent 会话的隔离与恢复基础。rig setup会尝试自动安装，但最好先自查一遍：

node -v # 应为 v22.x 或 v24.x tmux -V # tmux 3.x claude --version && claude auth status codex --version && codex login status

其中认证检查遵循"只查你选用的引擎"原则：Claude Code 用claude auth status，Codex 用codex login status，有一个能用的即可，不必两个都登录。未登录时先补一次claude auth login或codex login。

这些前置检查并非散落在 README 里的"建议"，而是被固化进了 CLI 的SystemPreflight。在 system-preflight.ts 中可以看到四步检查的完整实现：node_version（Node 大版本归类）、tmux（探测 tmux 控制通道是否可用）、writable_home（OPENRIG_HOME、数据库目录、transcript 目录必须可写）、port_available（daemon 端口未被占用，占用时会提示rig config set daemon.port <port+1>或先用lsof定位进程）。

rig setup --dry-run：先看计划再改机器

环境自查通过后，安装本身也可以"先预览后执行"。OpenRig 把这种"计划模式"做进了rig setup这个命令本身：

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

--dry-run的语义在 setup.ts 里写得很明确：零副作用地枚举将要执行的全部步骤。核心流程固定为 10 个步骤（CORE_STEP_IDS）：

const CORE_STEP_IDS = [ "brew", // macOS 上检查 Homebrew "tmux_install", // 安装 tmux（brew install tmux） "herdr_install", // 默认安装 herdr（可用 --no-herdr 拒绝） "ghostty_install", // macOS 可选安装 Ghostty 终端 "claude_install", // 缺失时 npm install -g @anthropic-ai/claude-code "claude_auth", // 检查 Claude Code 登录态 "codex_install", // 缺失时 npm install -g @openai/codex "codex_auth", // 检查 Codex 登录态 "tmux_config", // 在 ~/.tmux.conf 写入 OpenRig 托管块 "verify", // 汇总校验 ];

dry-run 模式下每一步只输出Dry run: <step> would be attempted.，不会真正执行任何安装或写入。同时它还会披露runtimeConfig——即 OpenRig 会改动你机器上的哪些文件：~/.claude.json（预信任托管工作区）、项目级.claude/settings.local.json、.mcp.json，以及$CODEX_HOME/config.toml（默认~/.codex/config.toml）。tmux 配置写入的内容是开启鼠标支持与滚动缓冲（set -g mouse on、set -g history-limit 50000），且以# OpenRig managed block标记，重复执行会替换旧块而不是追加。

配合--json可以输出机器可读的计划，方便接入自动化流程；每个步骤带OK / APPLIED / WARN / SKIP / FAIL状态标记，失败项会附Fix提示。确认计划无误后再真正执行：

rig setup

若最后一步报FAILED [4/4]，多半是某个引擎还没登录——rig setup会把这些项归入 "Some steps need attention"，按提示补登录即可，这不代表安装本身失败。

启动你的第一支 Agent 战队并验证

OpenRig 内置了三支开箱即用的战队，starter是最小可用的一支：一个 Claude Code 负责实现（dev-build），一个 Codex 负责评审（dev-review），正好覆盖"双引擎同屏协作"的诉求。另有 workshop（lead + builder + QA + reviewer）和 factory（七人编队）供后续进阶。

先看一眼规格库，再预览这支队伍的结构：

rig specs preview starter --kind rig

specs preview会按 pod 结构逐层列出成员及其 runtime（Claude Code / Codex），源码在 specs.ts 中实现。战队拓扑本身是 YAML 声明式的 RigSpec，仓库里现成的例子可以参考 demo/rig.yaml——它定义了 orch（编排）、dev（开发）、rev（评审）、infra（基础设施）四个 pod，成员通过runtime: claude-code/runtime: codex声明归属，pod 间用edges建立协作关系（如delegates_to、can_observe、collaborates_with）：

version: "0.2" name: demo-rig culture_file: culture.md pods: - id: dev label: Development members: - id: impl agent_ref: "local:agents/impl" runtime: claude-code cwd: . - id: qa agent_ref: "local:agents/qa" runtime: codex cwd: . edges: - kind: can_observe from: qa to: impl

正式启动同样有两段式：先用--plan只解析不执行，确认无误后再真正拉起：

cd /path/to/your/repository rig up starter --cwd . --plan rig up starter --cwd .

--plan在 up.ts 中被定义为 "Plan mode — preview without executing"；--cwd则一次性覆盖所有成员的工作目录。启动后 daemon 会创建 tmux 会话、注入 seat 身份与连接环境变量，并做就绪检查。仓库的 demo/run.sh 展示了完整的验证节奏：rig daemon start确保 daemon 在跑，rig up启动拓扑并从输出解析 rig ID，再用rig ps --nodes --rig <id>检查节点状态。

在派活之前，用 TUI 看一眼战队的运行状态（拓扑图、seat 的 runtime/model/context/state 一目了然）：

rig terminal open saved:kernel --window

TUI 不可用时，rig tui --shared是 dashboard-only 的降级方案。然后检查项目 seat 是否就绪，再给 builder 派一个边界清晰的任务：

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

至此，Claude Code 和 Codex 已经在同一支队伍里各司其职：实现、评审、队列追踪、结果归档，全都在 OpenRig 的 daemon 与 tmux 会话体系下受管。

常见失败点与快速修复

首跑最容易踩的坑集中在下面几个，均可在仓库源码或 README 中找到对应处理：

另外两条容易被忽略的规则：安装会向~/.tmux.conf写入托管配置块，建议动手前备份相关文件；OPENRIG_HOME（默认~/.openrig）承载数据库、配置与 transcript，不要把 home 目录的写权限问题留给 daemon 启动时才暴露——rig setup --dry-run的writable_home检查会提前发现它。

把"环境核查 → dry-run 预览 → 计划启动 → 状态验证 → 派活"这条链路走完，10 分钟足够让 Claude Code 与 Codex 从两个孤立的终端进程，变成一支有分工、有上下文共享、可恢复现场的常驻战队。

【免费下载链接】openrigBuild your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, shared context and owned work.项目地址: https://gitcode.com/GitHub_Trending/op/openrig