openrig 实战：用 YAML 和 tmux 统一编排 Claude Code 与 Codex

1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件支架项目毕竟 rig 在英文里有“装配、支架”的意思。但在当前 AI 编程工具爆发的语境下openrig 指向的是一个非常具体且刚需的方向把 Claude Code、Codex 这类命令行 AI 编程助手统一编排起来用一份 YAML 配置驱动多个工具协同工作。你可以把它理解成一个“AI 编程助手的调度中枢”核心价值在于让不同厂商、不同能力的模型各司其职而不是每次手动切换、手动复制粘贴。我接触这个方向起因是团队里同时用着 Claude Code 和 Codex 两套工具。Claude Code 在长上下文理解和复杂重构上表现稳定Codex 在某些代码补全和快速生成场景里响应更快但两者的配置体系、会话管理、认证方式完全不同。每次切换都要重新登录、重新配置环境变量团队协作时更是灾难——A 同事的配置在 B 同事机器上跑不起来问题排查全靠猜。openrig 这类工具的出现本质上是把“多工具并存”这件事从手工操作变成了声明式配置。它适合谁三类人最该关注。第一类是同时使用多个 AI 编程工具的开发者尤其是那些在 Claude Code 和 Codex 之间反复横跳的人第二类是需要团队统一 AI 编程环境的技术负责人一份 YAML 就能让所有人环境一致第三类是喜欢折腾本地模型接入的玩家比如把 Claude Code 接到 LM Studio 的本地模型上openrig 能帮你把这类非标准配置管理得井井有条。哪怕你只是刚装好 Claude Code 的新手理解 openrig 的设计思路也能让你少走很多弯路。需要说明的是openrig 目前并不是一个官方统一命名的产品它更像是一类“开源编排方案”的统称。市面上围绕 Claude Code、Codex 的配置管理工具很多有的叫 ccswitch有的叫 codex 配置管理器但核心逻辑相通用 YAML 描述工具、模型、会话、代理之间的关系用 tmux 或类似机制管理多会话生命周期。下面我讲的这套方案是基于这类工具最常见的实现方式结合我自己在 Ubuntu 和 Windows 双平台上的实操经验整理出来的你可以直接抄作业也可以按需调整。2. 核心设计思路为什么是 YAML tmux 这套组合2.1 声明式配置为什么比命令行参数更靠谱Claude Code 和 Codex 都支持通过命令行参数指定模型、API 端点、认证信息比如claude --model xxx或者codex --endpoint xxx。刚开始用的时候我也觉得这样挺方便敲一行命令就完事。但用久了问题就暴露了参数一多命令长得没法看换个项目就要重新敲一遍团队里每个人记的参数还不一样。更麻烦的是有些配置项比如代理地址、认证 token涉及敏感信息写在命令行历史里本身就是个安全隐患。YAML 的好处在于把“配置”和“执行”彻底分开。你只需要在openrig.yaml里定义好每个工具的模型、端点、环境变量、启动参数之后所有操作都基于这份配置。改配置不用改命令换项目不用重新记参数团队共享配置直接传文件就行。这跟 Docker Compose 的思路是一样的——用声明式文件描述“我想要什么”而不是用一堆命令描述“我怎么做”。从实操角度看YAML 的层级结构天然适合表达“工具-模型-会话”这种嵌套关系。比如一个典型的 openrig 配置大概长这样version: 1 tools: claude: command: claude model: claude-sonnet-4-20250514 env: ANTHROPIC_BASE_URL: http://localhost:8080 ANTHROPIC_API_KEY: ${CLAUDE_KEY} args: - --dangerously-skip-permissions codex: command: codex model: gpt-5-codex env: OPENAI_BASE_URL: http://localhost:8080/v1 OPENAI_API_KEY: ${CODEX_KEY} sessions: - name: refactor tool: claude workdir: ~/projects/myapp - name: quickfix tool: codex workdir: ~/projects/myapp这份配置里tools定义了每个工具怎么启动sessions定义了要开哪些会话、用哪个工具、在哪个目录下工作。${CLAUDE_KEY}这种写法是环境变量引用敏感信息不落盘这是基本的安全习惯。2.2 tmux 在其中的角色会话持久化与并行管理光有 YAML 还不够因为 Claude Code 和 Codex 都是交互式命令行工具你启动它之后得有个终端窗口挂着。如果直接在普通终端里跑关掉窗口会话就断了长任务跑到一半断掉是常有的事。tmux 在这里的作用就是提供持久化的会话容器让每个 AI 编程会话独立运行、随时 attach 回去查看进度。我实测下来tmux 方案比“开一堆终端标签页”强太多。首先tmux 会话在 SSH 断开后依然存活你在服务器上跑 Claude Code 做大规模重构本地网络断了也不影响其次tmux 支持分屏和窗口切换一个终端里就能管理多个 AI 会话最后tmux 的会话命名机制和 openrig 的 session 概念天然对应openrig start refactor本质上就是tmux new-session -s refactor加上工具启动命令。这里有个细节值得展开为什么不用 screen 而用 tmux。screen 更老、更稳定但 tmux 的配置更灵活、脚本化能力更强尤其是tmux send-keys和tmux capture-pane这两个命令让自动化编排成为可能。openrig 需要在启动会话后自动发送初始化命令、捕获输出判断状态这些用 tmux 做起来很顺手。另外 tmux 的pipe-pane功能可以把会话输出实时写到日志文件方便后续排查问题。2.3 多工具协同的典型场景拆解openrig 最核心的价值场景是让 Claude Code 和 Codex 在同一个项目里分工。我举几个自己常用的组合方式。场景一Claude Code 做架构设计Codex 做代码填充。先用 Claude Code 的长上下文能力分析整个代码库产出重构方案和接口定义然后把具体某个函数的实现交给 Codex因为它生成速度快、代码风格更贴近训练数据。openrig 配置里可以定义两个 session一个跑 Claude Code 做规划一个跑 Codex 做实现两者共享同一个工作目录。场景二本地模型做敏感代码处理云端模型做通用任务。有些项目涉及内部算法不方便发给云端模型。这时候可以用 Claude Code 接入 LM Studio 的本地模型处理敏感部分Codex 接云端模型处理通用部分。openrig 的 YAML 里通过不同的ANTHROPIC_BASE_URL和OPENAI_BASE_URL就能实现分流。场景三多会话并行跑不同任务。一个 session 在跑测试修复一个 session 在写文档一个 session 在做代码审查。tmux 的会话隔离保证了它们互不干扰openrig 的 session 管理让你能快速切换查看。注意多会话并行时如果多个工具同时修改同一个文件冲突几乎不可避免。我的做法是给每个 session 分配不同的工作目录或者用 git worktree 做物理隔离最后再合并。3. 环境准备与安装实操Ubuntu 和 Windows 双平台3.1 Ubuntu 下的完整安装流程Ubuntu 是我主要的生产环境整个安装流程走下来大概十分钟。先把基础依赖装齐sudo apt update sudo apt install -y tmux curl git python3 python3-piptmux 版本建议 3.0 以上老版本在某些send-keys行为上有差异。检查一下tmux -V接下来装 Claude Code。官方推荐的方式是通过 npm 安装前提是 Node.js 版本在 18 以上node -v npm install -g anthropic-ai/claude-code装完之后验证claude --versionCodex 的安装类似也是 npm 包npm install -g openai/codex codex --version如果 npm 安装过程中遇到权限问题不要用sudo npm install -g那样容易把全局目录搞乱。正确做法是配置 npm 的全局目录到用户空间mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc然后重新执行安装命令。这个坑我踩过好几次用 sudo 装完之后普通用户跑不起来排查半天才发现是权限问题。openrig 本身如果是以脚本形式分发通常就是一个 Python 脚本或者 shell 脚本。假设你拿到的是openrig.py给它加执行权限放到 PATH 里chmod x openrig.py sudo mv openrig.py /usr/local/bin/openrig如果是通过 pip 安装的包直接pip install openrig即可。具体以你拿到的分发方式为准。3.2 Windows 下的安装要点与 WSL 选择Windows 平台的情况稍微复杂。Claude Code 和 Codex 都有原生 Windows 版本但我的建议是优先用 WSL2原因有三个tmux 在 WSL 里是原生体验Windows 原生没有 tmuxYAML 配置里的路径写法在 WSL 里和 Linux 一致不用处理反斜杠转义很多 openrig 脚本假设了 Unix 环境WSL 兼容性最好。WSL2 安装wsl --install -d Ubuntu-22.04装完之后在 WSL 里按上面的 Ubuntu 流程走一遍就行。如果你坚持用 Windows 原生环境Claude Code 有桌面版安装包Codex 也有 Windows 桌面版但 tmux 需要额外装可以用wsl里的 tmux 配合 Windows Terminal 使用或者用tmux的 Windows 移植版功能有缺失不推荐。Windows 原生环境下配置 YAML 时路径要写成C:/Users/xxx/projects这种正斜杠形式或者用双反斜杠C:\\Users\\xxx。单反斜杠在 YAML 里是转义字符会出问题。这个细节很多人第一次配的时候都会栽跟头。3.3 认证配置token 管理和环境变量注入Claude Code 和 Codex 都需要认证。Claude Code 用 Anthropic 的 API keyCodex 用 OpenAI 的 API key 或者 auth token。绝对不要把 key 直接写在 YAML 文件里尤其是如果这个文件要提交到 git 仓库。正确做法是用环境变量。在~/.bashrc或~/.zshrc里加export CLAUDE_KEYsk-ant-xxxxxxxx export CODEX_KEYsk-xxxxxxxx然后在 YAML 里用${CLAUDE_KEY}引用。openrig 在解析配置时会做环境变量替换。如果你用的是 Claude Code 的订阅登录方式不是 API key那认证信息存在~/.claude/目录下openrig 不需要额外处理只要保证这个目录存在且登录状态有效即可。Codex 类似codex login之后认证信息存在~/.codex/下。提示如果遇到 “your organization has disabled claude subscription access” 这类提示通常是账号权限问题不是 openrig 配置问题。先确认账号本身能正常使用 Claude Code再排查 openrig。4. 配置文件编写从最小可用到生产级4.1 最小可用配置的逐行解读先从一个能跑起来的最小配置开始理解每一行的作用version: 1 tools: claude: command: claude env: ANTHROPIC_API_KEY: ${CLAUDE_KEY} sessions: - name: main tool: claude workdir: ~/projects/demoversion是配置格式版本方便后续升级时做兼容处理。tools下定义了一个叫claude的工具command是启动命令env是注入的环境变量。sessions下定义了一个叫main的会话使用claude工具工作目录是~/projects/demo。启动这个会话openrig start mainopenrig 内部做的事情是创建一个名为main的 tmux 会话cd 到工作目录注入环境变量执行claude命令。你可以用tmux attach -t main进去看或者用openrig attach main如果工具提供了这个子命令。4.2 多工具多会话配置的进阶写法生产级配置需要处理更多情况。下面这份配置覆盖了 Claude Code 接本地模型、Codex 接云端、多会话并行这几个场景version: 1 defaults: shell: /bin/bash tmux_prefix: rig- tools: claude-local: command: claude model: local-model env: ANTHROPIC_BASE_URL: http://localhost:1234 ANTHROPIC_API_KEY: local args: - --dangerously-skip-permissions claude-cloud: command: claude model: claude-sonnet-4-20250514 env: ANTHROPIC_API_KEY: ${CLAUDE_KEY} codex-cloud: command: codex model: gpt-5-codex env: OPENAI_API_KEY: ${CODEX_KEY} sessions: - name: sensitive tool: claude-local workdir: ~/projects/internal-algo autostart: true - name: refactor tool: claude-cloud workdir: ~/projects/webapp autostart: true - name: quickfix tool: codex-cloud workdir: ~/projects/webapp autostart: falsedefaults里定义了全局默认值tmux_prefix给所有 tmux 会话加前缀避免和手动创建的会话混淆。autostart控制openrig start不带参数时是否自动启动该会话。这里有个设计取舍值得说为什么把工具定义和会话定义分开。因为同一个工具可能被多个会话复用比如两个会话都用claude-cloud但工作目录不同。如果合并在一起配置会有大量重复。分开之后改工具配置比如换模型只需要改一处。4.3 参数计算与模型选择依据模型选择不是拍脑袋决定的要根据任务类型和成本算账。我一般按这个逻辑走任务类型推荐工具推荐模型理由全库架构分析Claude CodeSonnet 4长上下文稳定理解力强单函数实现CodexGPT-5 Codex生成快代码风格好敏感代码处理Claude Code 本地LM Studio 本地模型数据不出本地批量测试修复CodexGPT-5 Codex吞吐高成本可控文档生成Claude CodeSonnet 4语言组织能力强成本方面Claude Code 按 token 计费长上下文任务消耗大Codex 的计费模式类似。如果预算有限把重任务分配给本地模型轻任务分配给云端模型是性价比最高的组合。本地模型的硬件要求至少 16GB 显存跑 7B 量化模型32GB 以上可以跑更大的模型。LM Studio 的配置里把ANTHROPIC_BASE_URL指向http://localhost:1234即可Claude Code 会以 OpenAI 兼容格式调用。注意Claude Code 接本地模型时某些高级功能比如工具调用、文件编辑可能不完全兼容取决于本地模型的实现。实测 LM Studio 配合合适的模型模板基础对话和代码生成没问题但复杂的多步工具调用容易出错。5. 实操全流程从启动到多会话协同5.1 启动、attach 与状态查看配置写好后启动流程很直接openrig start不带参数时启动所有autostart: true的会话。也可以指定单个openrig start refactor启动后查看所有会话状态openrig status输出大概是这样NAME TOOL STATUS WORKDIR sensitive claude-local running ~/projects/internal-algo refactor claude-cloud running ~/projects/webapp quickfix codex-cloud stopped ~/projects/webappattach 到某个会话openrig attach refactor这等价于tmux attach -t rig-refactor。进去之后就是正常的 Claude Code 交互界面你可以像平时一样使用。退出 attach 用Ctrl-b d会话继续在后台跑。停止会话openrig stop refactor这会发送退出信号给工具然后关闭 tmux 会话。如果工具卡住了可以加--force强制杀掉。5.2 多会话协同的实际操作记录我拿一个真实的重构任务举例。项目是一个 Python 后端服务需要把同步的数据库调用改成异步。我的操作流程第一步启动refactor会话Claude Code让它分析整个代码库产出改造方案 分析这个项目的数据库调用模式列出所有需要改成异步的函数给出改造优先级Claude Code 花了大概三分钟扫描完所有文件输出了一份详细的清单包括每个文件的路径、函数名、依赖关系。第二步启动quickfix会话Codex让它按清单逐个改造 把 db.py 里的 get_user 函数改成 async使用 asyncpg 替代 psycopg2Codex 生成代码很快几秒钟就给出了改造后的版本。我 review 之后让它继续下一个函数。第三步两个会话并行跑。Claude Code 在refactor里继续分析其他模块Codex 在quickfix里批量改造。我在两个 tmux 窗口之间切换用Ctrl-b n和Ctrl-b p。这个流程跑下来原本需要大半天的重构工作两个小时就完成了主体部分。关键收益在于不用手动在工具之间复制粘贴上下文每个会话有自己的工作目录和会话历史互不干扰。5.3 日志捕获与问题回溯tmux 的pipe-pane功能可以把会话输出实时写到文件这对排查问题非常有用。openrig 如果支持日志配置可以在 YAML 里加sessions: - name: refactor tool: claude-cloud workdir: ~/projects/webapp log: ~/logs/refactor.log底层实现是tmux pipe-pane -t rig-refactor -o cat ~/logs/refactor.log。这样即使会话关了日志还在可以回溯 AI 到底做了什么操作。如果没有内置日志功能手动加也很简单tmux pipe-pane -t rig-refactor -o cat ~/logs/refactor.log日志文件建议按日期分目录避免单个文件过大mkdir -p ~/logs/$(date %Y%m%d)6. 常见问题与排查技巧实录6.1 认证类问题速查认证问题是最高频的故障来源。我整理了一份速查表现象可能原因排查方法解决方式codex auth token is unavailabletoken 未配置或过期echo $CODEX_KEY检查环境变量重新登录或更新 keyclaude subscription access disabled账号权限问题单独跑claude验证联系账号管理员401 Unauthorizedkey 错误或端点不匹配检查 BASE_URL 和 KEY 是否对应修正配置本地模型无响应LM Studio 未启动或端口不对curl localhost:1234/v1/models启动 LM Studio 并加载模型环境变量不生效是常见坑。如果你在~/.bashrc里加了 export但 openrig 是通过 systemd 或 cron 启动的那些环境变量不会自动加载。解决方式是在 openrig 配置里显式指定或者用env文件tools: claude: command: claude env_file: ~/.openrig/envenv_file里每行一个KEYVALUEopenrig 启动时读取并注入。6.2 会话管理类问题tmux 会话名冲突是最常见的问题。如果你手动创建了一个叫refactor的 tmux 会话openrig 再启动同名会话就会失败。解决办法是用tmux_prefix加前缀或者启动前先清理tmux kill-session -t rig-refactor 2/dev/null会话启动后立即退出通常是工具命令本身有问题。排查步骤先手动在终端里跑一遍claude或codex确认能正常启动然后检查 openrig 注入的环境变量是否完整最后看 tmux 会话的退出码tmux list-sessions tmux capture-pane -t rig-refactor -p | tail -20capture-pane能抓到会话退出前的最后输出通常错误信息就在里面。attach 后界面乱码多半是 TERM 环境变量不对。在 openrig 配置里加defaults: env: TERM: xterm-256color6.3 模型接入类问题Claude Code 接 LM Studio 本地模型时最常见的错误是cc switch local proxy failed while handling codex endpoint /responses。这个错误说明 Claude Code 尝试用 Codex 的端点格式去请求本地模型但本地模型不支持那个端点。解决方式是确认 LM Studio 的 API 格式设置正确通常要选 “OpenAI Compatible” 模式而不是 Anthropic 原生模式。Codex 接入 DeepSeek 这类第三方模型时关键是OPENAI_BASE_URL要指向兼容 OpenAI 格式的端点。DeepSeek 的 API 是 OpenAI 兼容的配置tools: codex-deepseek: command: codex model: deepseek-chat env: OPENAI_BASE_URL: https://api.deepseek.com/v1 OPENAI_API_KEY: ${DEEPSEEK_KEY}提示第三方模型对 Codex 的工具调用协议支持程度不一有些模型能对话但无法执行文件编辑操作。接入前先用简单对话测试确认基础功能正常再用于实际项目。6.4 我踩过的三个坑第一个坑YAML 缩进用 Tab。YAML 规范不允许 Tab 缩进必须用空格。我用编辑器自动补全的时候不小心混入了 Tabopenrig 解析报错但错误信息很模糊排查了半小时才发现。建议在编辑器里设置 YAML 文件自动把 Tab 转成两个空格。第二个坑环境变量里有特殊字符。API key 里如果包含$或#在 YAML 里会被特殊处理。解决方式是给值加引号ANTHROPIC_API_KEY: ${CLAUDE_KEY}引号能避免大部分转义问题。第三个坑工作目录不存在。openrig 启动会话时会 cd 到 workdir如果目录不存在tmux 会话会启动失败但错误信息不明显。建议在配置里用绝对路径或者启动前先确认目录存在。我现在的习惯是在 openrig 启动脚本里加一行mkdir -p做兜底。7. 进阶玩法把 openrig 用出花来7.1 结合 git worktree 做物理隔离多会话并行最大的风险是文件冲突。git worktree 能给每个会话分配独立的工作树物理隔离最后再合并git worktree add ../webapp-refactor -b refactor-branch git worktree add ../webapp-quickfix -b quickfix-branch然后 openrig 配置里把两个会话的 workdir 分别指向这两个目录。这样 Claude Code 在webapp-refactor里改代码Codex 在webapp-quickfix里改代码互不影响。完成后用 git 合并分支冲突在合并时统一处理比实时冲突好排查得多。7.2 用 hook 做启动后自动初始化openrig 如果支持 hook 机制可以在会话启动后自动执行一些命令比如加载项目特定的上下文文件sessions: - name: refactor tool: claude-cloud workdir: ~/projects/webapp hooks: post_start: - tmux send-keys -t rig-refactor 请先阅读 ARCHITECTURE.md 了解项目结构 Enter这样每次启动会话AI 都会先读一遍架构文档省去手动输入的麻烦。hook 也可以用来做健康检查、日志轮转等。7.3 团队共享配置的最佳实践团队协作时openrig 配置应该提交到 git 仓库但敏感信息不能提交。做法是openrig.yaml提交里面用${VAR}引用敏感信息.env.example提交列出所有需要的环境变量名.env不提交每个成员自己填.gitignore里加上.env和*.log新成员加入时cp .env.example .env填上自己的 key然后openrig start就能跑起来。这套流程我用了大半年团队里再也没出现过“在我机器上能跑”的问题。7.4 监控与告警的轻量方案如果会话需要长时间运行比如批量重构可以加一个简单的监控脚本#!/bin/bash while true; do if ! tmux has-session -t rig-refactor 2/dev/null; then echo Session rig-refactor died at $(date) ~/logs/alert.log # 可以在这里加邮件或 webhook 通知 fi sleep 60 done这个脚本每分钟检查一次会话是否存活挂了就记录日志。配合 cron 或 systemd timer 跑基本能覆盖大部分场景。8. 关于 openrig 这类工具的个人体会我用 openrig 这套思路管理 AI 编程工具大概有半年时间最大的感受是工具编排的价值不在于工具本身多强大而在于它把混乱变成了秩序。以前我的终端里开着五六个标签页每个跑着不同的 AI 工具配置散落在各处换个项目就要重新折腾一遍。现在一份 YAML 管所有启动、停止、切换都有统一入口心智负担小了很多。另一个体会是不要追求一步到位。我刚开始配的时候想把所有场景都覆盖配置写了三百多行结果自己都记不住哪个 session 是干嘛的。后来精简到只保留最常用的三四个会话配置降到五十行以内反而用得更顺手。配置这东西够用就好需要的时候再加。最后分享一个小技巧给每个 session 起名的时候用“动作对象”的格式比如refactor-auth、fix-tests、doc-api比session1、session2这种命名好记太多。tmux 的会话列表里一眼就能看出哪个在干什么切换的时候不用猜。这个习惯看起来小但实际用起来效率提升很明显。