1. 痛点突围：它究竟击穿了什么工程死穴？
终端内的 AI 编程工具正在陷入严重的碎片化陷阱。开发者在日常迭代中往往需要同时维护多个独立的终端窗口，分别运行 Claude Code、Codex 或是其他独立代理。这些终端彼此看不见对方的上下文，无法交接任务，更无法形成代码审查闭环。当项目规模扩大，开发者反而成了笨拙的人肉消息转发器，在多个终端之间复制粘贴日志、错误堆栈与补丁方案。
OpenRig 的出现直接终结了这种手工拼凑的工作流。它将底层终端多路复用工具 tmux、进程状态管理数据库 SQLite 以及统一的供应商钩子进行了深度封装。通过将独立的代理包裹进 harness 抽象层，再用 rig 将多个 harness 编织为团队，系统允许主代理直接调度各路专家代理，在隔离的 workspace 内并行推进任务，并在合并前通过独立的检查席位完成校验。
💡 架构核心洞见：OpenRig 并没有发明新的 LLM 运行时，而是把现有的异构终端工具降维成了标准化的工程计算节点，利用成熟的终端复用基础设施实现了多代理的分布式流水线。
2. 核心架构与底层数据流向解析
OpenRig 的整体架构建立在宿主机的进程边界与 tmux 会话管理之上。整个系统由 CLI 控制面、Daemon 守护进程、SQLite 状态持久化层、tmux 虚拟终端集群以及挂载特定模型的 harness 包装器构成。当开发者输入启动指令时，控制面会读取 YAML 配置文件，初始化本地实例状态并预授信 workspace。
[ rig CLI / User Prompt ] ---> [ Daemon Controller ] ---> [ SQLite Instance State ]
│
▼
[ tmux Multiplexer Sessions ]
│
┌───────────────────────────┴───────────────────────────┐
▼ ▼
[ dev-owner (Claude Code) ] [ dev-check (Codex Checker) ]
│ │
└───────────────> [ Local Workspace ] <─────────────────┘
在底层数据流转中，Daemon 进程负责维护实例的生命周期与配置同步。rig up 命令启动时，系统会创建对应的 tmux 会话，并将特定技能（如 discovery skills）注入到代理的本地目录。主代理（Owner）接收到边界明确的业务目标后，在本地执行修改、记录队列任务，并交由检查代理（Checker）对候选代码进行精确验证。所有的会话输出、状态和上下文采集器（statusLine）均在后台保持活跃，允许开发者随时通过共享看板（rig tui --shared）切入观察。
3. 技术选型与性能横热对比
| 选型维度 | 本方案 (openrig) | 传统实现范式 | 典型竞品方案 | 生产环境收益 |
|---|---|---|---|---|
| 多代理协同 | tmux 会话集群与 YAML 统一定义 | 纯手工开多个终端窗口拼凑 | 云端 SaaS 封闭沙箱调度 | 消除人肉传话开销，实现毫秒级会话内联 |
| 状态持久化 | 本地 SQLite 与 ~/.openrig 目录 |
依赖单次终端内存与临时日志 | 远端数据库黑盒存储 | 数据主权完全归属本地，无隐私泄漏风险 |
| 异构模型支持 | 同时驾驭 Claude Code 与 Codex | 绑定单一厂商生态环境 | 仅支持自有 API 封装模型 | 自由组合各家最强编码代理，避免厂商锁定 |
| 环境依赖约束 | 要求 Node.js 22 与 tmux | 无强制要求，但管理极其混乱 | 需配置专有容器或虚拟集群 | 零重型虚拟化开销，直接复用宿主机开发环境 |
从架构选型上看，OpenRig 极度克制地选择了拥抱现有成熟工具链。它不尝试重写终端模拟器，也不强行打包笨重的 Docker 容器，而是利用 tmux 作为进程隔离沙箱，用 SQLite 保证状态的原子性。这种设计使它在本地开发机上的资源消耗压制在极低水平，同时保留了极高的系统透明度。
4. 手把手极客实操：从零构建最小闭环
在开始运行前，必须确保宿主机已安装 Node.js 22 以及 tmux，并且目标机上的 Codex 已完成认证。原生 Windows 暂不支持，建议在 macOS 或 Linux 环境下操作。
# 全局安装 OpenRig CLI 工具
npm install -g @openrig/cli
# 执行干跑测试，检查本地 tmux 与 cmux 依赖环境
rig setup --dry-run
# 验证基础运行环境与 Codex 登录状态
tmux -V
codex --version
codex login status
# 进入目标代码仓库目录
cd /path/to/your/repository
# 检查首个项目的启动拓扑结构
rig up first-project --cwd . --plan
# 正式拉起名为 first-project 的工程团队 rig
rig up first-project --cwd .
# 打开共享看板 TUI 监控所有代理实时状态
rig tui --shared
当团队成功启动后，可以通过 CLI 向特定的 seat 发送任务指令。以下指令指定所有者代理实现某项具体变更并交由检查代理复核：
rig send dev-owner@first-project 'Implement feature X. 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.'
# 查看当前队列状态
rig queue list --destination dev-owner@first-project --limit 1000
5. 生产落地踩坑指南与避坑建议 (Gotchas)
在将 OpenRig 引入日常高强度开发流时，底层机制的一些副作用需要特别防范。由于守护进程会在初始化时向 ~/.claude.json 写入 workspace 信任状态，并在用户的 tmux 配置中注入鼠标支持与滚动缓冲区规则，盲目执行安装可能会破坏现有的终端个性化配置。
⚠️ 避坑预警 [Bun 包管理器阻断]：使用
bun add -g @openrig/cli安装时，Bun 可能会拦截包的 postinstall 脚本。这会导致 Node.js 版本校验与 SQLite 模块加载检查失效，因此在使用 Bun 安装后必须手动确认环境兼容性。⚠️ 避坑预警 [工作区预授信与权限滥用]：OpenRig 默认的引导程序不会主动添加
rig命令的放行规则。切勿直接赋予代理全局无限制的操作系统执行权限。应当在启动前明确配置项目级或用户级的安全作用域，防止代理在自动化迭代过程中误删关键生产文件。
在多代理并发向同一个代码库写入变更时，必须合理规划 dev-owner 与 dev-check 的边界。将任务切分为原子化的单点变更，并严格依赖队列管理获取任务 ID，才能在享受多代理吞吐量红利的同时，守住本地代码库的质量底线。