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 原生没有 tmux；YAML 配置里的路径写法在 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 key，Codex 用 OpenAI 的 API key 或者 auth token。绝对不要把 key 直接写在 YAML 文件里，尤其是如果这个文件要提交到 git 仓库。
正确做法是用环境变量。在~/.bashrc或~/.zshrc里加：
export CLAUDE_KEY="sk-ant-xxxxxxxx" export CODEX_KEY="sk-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 Code | Sonnet 4 | 长上下文稳定，理解力强 |
| 单函数实现 | Codex | GPT-5 Codex | 生成快，代码风格好 |
| 敏感代码处理 | Claude Code + 本地 | LM Studio 本地模型 | 数据不出本地 |
| 批量测试修复 | Codex | GPT-5 Codex | 吞吐高，成本可控 |
| 文档生成 | Claude Code | Sonnet 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 unavailable | token 未配置或过期 | echo $CODEX_KEY检查环境变量 | 重新登录或更新 key |
| claude subscription access disabled | 账号权限问题 | 单独跑claude验证 | 联系账号管理员 |
| 401 Unauthorized | key 错误或端点不匹配 | 检查 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里每行一个KEY=VALUE，openrig 启动时读取并注入。
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 缩进，必须用空格。我用编辑器自动补全的时候不小心混入了 Tab，openrig 解析报错但错误信息很模糊，排查了半小时才发现。建议在编辑器里设置 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 的会话列表里一眼就能看出哪个在干什么，切换的时候不用猜。这个习惯看起来小，但实际用起来效率提升很明显。
