1. 从 openrig 说起一个被低估的 AI 编码工作流编排工具第一次看到 openrig 这个名字很多人会以为是某个硬件项目或者机械臂框架毕竟 rig 这个词在工程领域通常指“装配、搭建”。但如果你最近在折腾 Claude Code、Codex 这类终端 AI 编码助手并且开始觉得每次手动敲命令、切模型、管会话越来越烦那 openrig 解决的恰好就是这个问题——它把 AI 编码工具链的配置、启动、会话管理、多模型切换整合成了一套可复用的编排方案。我最初接触 openrig 是因为一个很具体的痛点手上同时有 Claude Code 和 Codex 两个 CLI 工具前者在代码理解和长上下文方面表现稳定后者在某些推理任务和特定模型接入上更灵活。但每次切换都要改配置、重设环境变量、重新开 tmux 窗口一天下来光折腾环境就消耗不少精力。openrig 的核心价值就在于用 YAML 定义工作流用 tmux 管理会话把 Claude Code、Codex 以及各种本地或远程模型的调用统一到一个可版本控制的配置体系里。这篇文章适合三类人看第一类是在终端里重度使用 AI 编码助手、已经开始感到管理成本上升的开发者第二类是想把 Claude Code 或 Codex 接入本地模型比如通过 LM Studio 跑开源模型但被配置问题卡住的人第三类是习惯用 tmux 做多窗口开发、希望把 AI 工具无缝嵌入现有工作流的老手。我会从设计思路、核心配置、实操步骤、常见问题四个维度展开尽量把每个参数为什么这么设、每个步骤背后的意图讲清楚。2. openrig 的整体设计思路与核心组件拆解2.1 为什么是 YAML tmux 这套组合openrig 选择 YAML 作为配置载体这个决策背后有很实际的考量。Claude Code 和 Codex 各自的配置文件格式不统一Claude Code 偏向 JSON 风格的设置Codex 有自己的 TOML 或环境变量体系如果每次都要分别维护很容易出现配置漂移。YAML 的好处是结构清晰、支持注释、嵌套层次直观而且几乎所有主流编辑器都有语法高亮和校验插件。你可以把模型端点、API 密钥引用、启动参数、会话名称全部写在一个openrig.yaml里改一处就能影响整个工作流。tmux 的引入则是为了解决会话持久化问题。AI 编码助手的一个典型使用场景是你让 Claude Code 分析一个大型代码库它需要几分钟甚至更长时间来读取文件、建立索引、生成回答。如果直接在前台终端跑一旦网络波动或者你不小心关了窗口整个会话就丢了。tmux 把每个 AI 工具跑在独立的 pane 或 window 里断线重连后会话还在输出还能翻回去看。更重要的是openrig 利用 tmux 的 session 命名机制让不同项目、不同模型组合可以并行运行互不干扰。提示如果你之前没用过 tmux建议先花二十分钟熟悉tmux new -s、tmux attach -t、Ctrlb d这三个操作后面所有 openrig 的会话管理都建立在这上面。2.2 openrig 要解决的核心问题清单我把 openrig 的价值归纳为四个层面每个层面都对应着实际开发中会遇到的摩擦点配置统一化Claude Code 的安装、Codex 的安装、模型端点切换、代理设置全部收敛到一份 YAML 中避免“这个工具改了那个工具忘了”的情况。会话可恢复通过 tmux 托管AI 编码会话不会因为终端关闭或网络抖动而丢失特别适合长上下文任务。多模型并行同一个项目下可以同时跑 Claude Code 和 Codex一个负责代码生成一个负责审查或推理通过 tmux 分屏对照输出。环境隔离不同项目使用不同的 openrig 配置API 密钥、模型选择、工作目录互不影响减少“在 A 项目用了 B 项目密钥”这类低级错误。2.3 与直接使用 Claude Code / Codex 的差异对比很多人会问我直接装 Claude Code 和 Codex 不就行了为什么要多一层 openrig这个问题我在最初也纠结过。直接使用的优势是简单装完就能跑。但当你的使用场景从“偶尔问一个问题”变成“每天数小时在终端里和 AI 协作写代码”时直接使用的边际成本会快速上升。对比维度直接使用 Claude Code / Codex通过 openrig 编排配置管理各工具独立配置容易不一致统一 YAML版本可控会话持久性终端关闭即丢失tmux 托管可恢复多模型切换手动改环境变量或配置文件配置中预定义一键切换多项目隔离依赖手动切换目录和密钥每个项目独立配置文件团队协作配置难以共享YAML 可提交到仓库共享本地模型接入需要单独调试端点配置中统一声明端点这个对比不是说 openrig 适合所有人。如果你只是偶尔用 Claude Code 问几个问题直接装官方 CLI 完全够用。但如果你已经进入“AI 编码助手是日常主力工具”的阶段openrig 带来的效率提升会非常明显。3. 核心配置细节与实操要点全解析3.1 openrig.yaml 的骨架结构与字段含义一份典型的 openrig 配置大概长这样我把它拆开逐段解释version: 1 project: my-backend-service workdir: /home/dev/projects/backend sessions: - name: claude-main tool: claude-code model: claude-sonnet args: - --max-tokens - 8192 env: ANTHROPIC_API_KEY: ${CLAUDE_KEY} tmux: window: editor pane: 0 - name: codex-review tool: codex model: gpt-5-codex args: - --reasoning-effort - high env: OPENAI_API_KEY: ${CODEX_KEY} tmux: window: review pane: 1 models: claude-sonnet: endpoint: https://api.anthropic.com context_window: 200000 gpt-5-codex: endpoint: https://api.openai.com context_window: 128000 local-qwen: endpoint: http://localhost:1234/v1 context_window: 32768version字段用于配置格式的向后兼容openrig 后续如果调整字段结构可以通过版本号做迁移。project和workdir决定了 AI 工具的工作目录这一点很关键——Claude Code 和 Codex 都会基于当前目录来理解项目结构如果 workdir 设错了AI 看到的代码库就是错的。sessions是核心数组每个元素定义一个独立的 AI 会话。tool字段告诉 openrig 要启动哪个 CLI目前主要支持claude-code和codex两种。model引用的是下面models段中定义的模型别名这样切换模型只需要改一个引用名不用在每个 session 里重复写端点信息。env字段支持环境变量引用${CLAUDE_KEY}这种写法会从当前 shell 环境或.env文件中读取实际值。这样做的好处是 API 密钥不会明文写在 YAML 里配置可以安全地提交到 Git 仓库。3.2 模型端点配置从官方 API 到本地 LM Studioopenrig 的models段是整个配置中最灵活的部分。你可以在这里定义任意多个模型端点包括官方 API、第三方兼容端点、以及本地运行的模型服务。以本地模型为例如果你用 LM Studio 在本地跑了一个开源模型它默认会在http://localhost:1234/v1暴露一个兼容接口。在 openrig 中配置如下models: local-qwen: endpoint: http://localhost:1234/v1 api_key: not-needed context_window: 32768 compatibility: openaicompatibility: openai这个字段告诉 openrig 用 OpenAI 风格的请求格式去调用这个端点。大多数本地模型服务LM Studio、Ollama 的兼容层、vLLM 等都支持这种格式。context_window字段用于 openrig 在启动时做上下文长度校验如果配置的 max_tokens 超过了模型实际支持的范围openrig 会提前警告而不是等到运行时报错。注意本地模型的 context_window 一定要填准确。我见过有人把 32K 的模型写成 128K结果 Claude Code 在读取大文件时直接截断生成的代码缺胳膊少腿排查了半天才发现是上下文长度配置错误。3.3 tmux 会话布局与窗口命名策略openrig 对 tmux 的利用不只是“跑在里面”这么简单它支持精细的窗口和窗格分配。上面的配置中tmux.window指定窗口名称tmux.pane指定窗格编号。这意味着你可以让 Claude Code 跑在editor窗口的第 0 个窗格Codex 跑在review窗口的第 1 个窗格切换时用Ctrlb加窗口号即可。我自己的习惯是按功能划分窗口editor窗口放 Claude Code 负责代码生成和重构review窗口放 Codex 负责代码审查和边界情况分析local窗口放本地模型做快速问答和文档查询。这样三个窗口各司其职需要哪个就切到哪个不用在一个会话里反复切换模型。窗口命名还有一个好处是 tmux 的状态栏可以直接显示当前有哪些 AI 会话在跑。配合 tmux 的status-left配置你可以一眼看到所有活跃的 openrig 会话状态。3.4 环境变量与密钥管理的最佳实践API 密钥管理是很多人容易忽视的环节。直接把密钥写在 YAML 里然后提交到仓库是典型的安全事故。openrig 推荐的做法是在项目根目录创建.env文件写入实际密钥值。在.gitignore中排除.env。在openrig.yaml中使用${VAR_NAME}引用。提交一个.env.example作为模板列出需要哪些变量但不含实际值。# .env.example CLAUDE_KEYyour_anthropic_key_here CODEX_KEYyour_openai_key_here LOCAL_MODEL_ENDPOINThttp://localhost:1234/v1这样团队协作时每个人复制.env.example为.env并填入自己的密钥即可。openrig 启动时会自动加载.env文件不需要手动source。4. 完整实操流程从零搭建 openrig 工作环境4.1 前置依赖安装与版本确认在开始配置 openrig 之前需要确保以下工具已经就绪。我按安装顺序列出每一步都附上版本确认命令第一步安装 tmux。Ubuntu 或 Debian 系用sudo apt install tmuxmacOS 用brew install tmux。安装后运行tmux -V建议版本不低于 3.2因为 openrig 用到了一些较新的窗口管理特性。第二步安装 Claude Code。根据你的平台选择对应方式。Node.js 环境下可以用npm install -g anthropic-ai/claude-code安装完成后运行claude --version确认。如果你在 Windows 上建议通过 WSL 来运行原生 Windows 终端对 tmux 的支持不够完整。第三步安装 Codex。Codex 的 CLI 安装方式类似确认codex --version能正常输出版本号。如果你遇到codex auth token is unavailable这类报错通常是登录态问题重新执行一次登录流程即可。第四步安装 openrig 本身。根据官方仓库的说明通常是通过包管理器或直接下载二进制。安装后运行openrig --version确认。提示Claude Code 和 Codex 的安装包在国内下载可能较慢建议提前配置好包管理器的镜像源或者使用离线安装包。具体镜像配置方法各平台不同这里不展开。4.2 初始化项目配置文件的完整步骤假设你有一个后端项目在/home/dev/projects/backend现在要给它配置 openrig。操作流程如下# 进入项目目录 cd /home/dev/projects/backend # 初始化 openrig 配置 openrig init # 这一步会生成 openrig.yaml 和 .env.example # 编辑 openrig.yaml按你的需求修改 sessions 和 modelsopenrig init生成的默认配置包含一个 Claude Code 会话和一个 Codex 会话的基本骨架。你需要根据实际情况修改workdir、model引用和env变量名。接下来创建.env文件并填入密钥cp .env.example .env # 用编辑器打开 .env填入实际的 API 密钥然后验证配置是否合法openrig validate这个命令会检查 YAML 语法、模型引用是否存在、环境变量是否已设置、tmux 是否可用。如果有问题会给出具体行号和错误原因。4.3 启动、切换与恢复会话的操作细节配置验证通过后启动整个工作流openrig up这个命令会做几件事创建一个名为openrig-project的 tmux 会话按配置中的sessions数组依次启动各个 AI 工具并把它们分配到对应的窗口和窗格。启动完成后你会自动 attach 到这个 tmux 会话看到 Claude Code 和 Codex 已经在各自的窗口里待命。切换窗口用Ctrlb然后按窗口编号或者用Ctrlb w打开窗口列表选择。如果你临时需要离开按Ctrlb ddetach会话在后台继续运行。回来时用openrig attach这个命令会自动找到当前项目的 tmux 会话并 attach不需要手动记会话名。如果某个 AI 工具崩溃了或者你想重启单个会话可以用openrig restart claude-main这只重启名为claude-main的会话不影响其他正在运行的会话。4.4 多项目并行时的配置隔离方案当你同时维护多个项目时每个项目有自己的openrig.yaml和.env。openrig 通过项目路径来区分不同的 tmux 会话所以不会出现冲突。但有一点需要注意环境变量是在启动时加载的如果你在项目 A 的终端里启动了 openrig然后又想在项目 B 里启动两个项目的.env不会互相污染因为 openrig 会为每个项目创建独立的加载上下文。我自己的做法是在每个项目的根目录放一个openrig.yaml然后在 shell 配置里加一个别名alias oropenrig这样在任何项目目录下敲or up就能启动当前项目的 AI 工作流or attach就能恢复非常顺手。5. 常见问题与排查技巧实录5.1 启动失败类问题的排查路径问题一cc switch local proxy failed while handling codex endpoint /responses这个报错通常出现在你同时配置了 Claude Code 和 Codex并且它们共用了一些代理或端点转发逻辑时。根本原因往往是两个工具对/responses路径的处理方式不同。排查步骤检查openrig.yaml中两个 session 的endpoint是否指向了同一个地址。如果是尝试给它们分配不同的端点或不同的路径前缀。确认本地代理服务是否在运行。如果你用了类似 cc switch 这样的本地代理来做模型切换确保它在 openrig 启动之前已经就绪。查看 openrig 的日志输出通常在~/.openrig/logs/下里面有每个 session 的详细启动日志。问题二your organization has disabled claude subscription access for claude code这个提示说明你的账号权限或订阅状态有问题。先确认你的 Claude Code 是否已经正确登录然后检查账号的订阅类型是否支持 CLI 访问。如果是团队账号可能需要管理员在后台开启相应权限。问题三Codex 启动后提示auth token is unavailableCodex 的登录态过期或未初始化。解决方法codex login按照提示完成登录流程然后重新执行openrig restart codex-review。5.2 模型接入类问题的典型表现与解决本地模型无响应或返回格式错误。最常见的原因是端点地址写错或者模型服务没有启动。先用curl直接测试端点curl http://localhost:1234/v1/models如果这个命令返回模型列表说明服务正常问题在 openrig 配置。如果不返回说明本地模型服务本身有问题需要先解决 LM Studio 或 Ollama 的启动问题。上下文长度不匹配导致输出截断。前面提到过context_window配置必须和模型实际能力一致。如果你发现 AI 生成的代码在中间突然断掉或者回答明显不完整优先检查这个参数。模型切换后行为异常。有时候你改了model引用但 openrig 没有重新加载配置。执行openrig reload强制重新读取配置并重启受影响的会话。5.3 会话管理类问题的速查表现象可能原因解决方法openrig attach找不到会话tmux 会话已被清理或项目路径变更用tmux ls查看现有会话确认项目路径会话启动后立即退出工具未安装或路径不在 PATH 中手动运行claude --version和codex --version确认窗口布局混乱tmux 版本不兼容或配置冲突升级 tmux 到 3.2检查~/.tmux.conf环境变量未生效.env文件位置不对或格式错误确认.env在项目根目录每行格式为KEYvalue多个项目会话互相干扰tmux 会话名冲突确保每个项目的project字段唯一5.4 我踩过的三个坑与对应经验第一个坑workdir 用了相对路径。最初配置时我写了workdir: ./backend结果 openrig 从不同目录启动时解析到了不同的绝对路径导致 AI 看到的项目结构不一致。后来改成绝对路径就再没出过问题。建议所有路径字段都用绝对路径省心。第二个坑tmux pane 编号从 0 开始还是从 1 开始。tmux 的 pane 编号默认从 0 开始但窗口编号默认从 0 开始还是 1 开始取决于base-index配置。我在一台机器上配了base-index 1另一台没配结果同样的 openrig 配置在两台机器上窗口分配不一样。统一 tmux 配置后解决。第三个坑API 密钥里有特殊字符。有一次密钥里包含$符号写在.env里没有加引号被 shell 解析成了变量引用导致认证失败。后来养成习惯.env里的值一律用双引号包起来。6. 进阶用法把 openrig 嵌入现有开发工作流6.1 与 VS Code 终端的协同方式如果你日常在 VS Code 里开发可以把 openrig 的 tmux 会话直接嵌入 VS Code 的集成终端。方法是在 VS Code 的settings.json中配置一个自定义终端 profile{ terminal.integrated.profiles.linux: { openrig: { path: bash, args: [-c, openrig attach || openrig up] } } }这样在 VS Code 里打开终端时选择 openrig profile就会自动 attach 到当前项目的 AI 工作流。如果会话不存在就自动创建存在就直接恢复。配合 VS Code 的分屏功能你可以左边写代码右边看 Claude Code 的输出效率提升很明显。6.2 用 YAML 锚点和引用减少重复配置当你有多个项目使用相似的模型配置时YAML 的锚点功能可以帮你减少重复。比如models: claude-base: claude-base endpoint: https://api.anthropic.com context_window: 200000 claude-fast: : *claude-base model_name: claude-haiku claude-strong: : *claude-base model_name: claude-sonnet这样claude-fast和claude-strong都继承了claude-base的端点配置只需要覆盖模型名称。当端点地址变更时改一处即可。6.3 会话日志的留存与回溯分析openrig 默认会把每个会话的输出记录到~/.openrig/logs/project/session/下。这些日志对于回溯问题很有价值。比如你让 Claude Code 重构了一个模块几天后发现有问题可以翻日志看当时的完整对话和生成的代码。我建议定期清理旧日志避免占用过多磁盘空间。可以加一个 cron 任务# 每周清理 30 天前的日志 0 3 * * 0 find ~/.openrig/logs -type f -mtime 30 -delete6.4 团队共享配置的注意事项把openrig.yaml提交到团队仓库时确保.env和任何包含密钥的文件都在.gitignore中。同时提供一个清晰的.env.example并在 README 中说明每个变量的用途和获取方式。如果团队使用不同的模型供应商可以在models段中定义多个端点让每个人根据自己的权限选择。另外tmux 的窗口布局在不同终端尺寸下可能表现不同。建议在配置中避免硬编码过于复杂的窗格分割保持布局简单让每个人根据自己的屏幕调整。这套 openrig 工作流我从去年开始用到现在最大的感受是它把“管理 AI 工具”这件事从手工操作变成了配置驱动。以前每次换项目都要重新想一遍“Claude Code 的密钥是哪个、Codex 的端点要不要改、tmux 窗口怎么分”现在这些全部固化在 YAML 里openrig up一条命令搞定。如果你也在终端里重度使用 AI 编码助手值得花一个下午把 openrig 配起来后面省下的时间远超这个投入。