openrig 配置编排实战：统一管理 Claude Code 与 Codex 的 YAML 方案

1. 从零认识 openrig：它到底解决什么问题

第一次看到 openrig 这个名字，很多人会以为是某个硬件项目或者机械臂相关的工具，毕竟“rig”这个词在工程领域常指设备支架或测试台架。但如果你最近在折腾 Claude Code、Codex 这类命令行 AI 编程助手，就会知道 openrig 其实是一个围绕这些工具做统一编排和配置管理的开源方案。它的核心价值用一句话概括：把散落在各个配置文件、环境变量、终端会话里的 AI 编程助手配置，收敛成一套可版本化、可复用、可切换的 YAML 驱动体系。

我最初接触这类需求，是因为同时在使用 Claude Code 和 Codex 两个工具。Claude Code 的配置散落在用户目录的隐藏文件夹里，Codex 又有自己的一套认证和端点配置，每次换项目、换模型、换 API 提供商，都要手动改一堆东西。更麻烦的是，团队协作时每个人的本地配置都不一样，出了问题很难复现。openrig 出现的意义就在于，它把这些配置抽象成声明式的 YAML 文件，配合 tmux 做会话管理，让“换一套配置”变成“切一个 profile”这么简单。

这篇文章适合三类人看：第一类是刚开始接触 Claude Code 或 Codex，被安装和配置折腾得够呛的新手；第二类是已经在用这些工具，但配置管理一团乱麻、想找系统化方案的中级用户；第三类是想把 AI 编程助手集成到团队工作流里，需要统一配置标准的技术负责人。我会从设计思路讲到实操细节，把 YAML 怎么写、tmux 怎么配合、常见坑怎么排都讲清楚，你跟着做就能搭起一套自己的 openrig 工作流。

提示：openrig 本身是一个配置编排层，它不替代 Claude Code 或 Codex 的功能，而是让这些工具的配置和使用更可控。理解这一点，后面的内容才不会跑偏。

2. openrig 的整体设计与核心思路拆解

2.1 为什么需要一层配置编排

要理解 openrig 的设计，先得看清楚它要解决的问题本质。Claude Code 和 Codex 这类工具，本质上都是“命令行客户端 + 远端模型服务”的组合。客户端需要知道三件事：用哪个模型端点、用什么认证凭证、走什么网络配置。这三件事在不同场景下答案不同——公司内网可能走自建端点，个人开发可能用官方服务，测试环境可能指向本地模型。如果每次切换都靠手动改配置文件，出错概率极高，而且没法追溯“上次能用是什么配置”。

openrig 的思路是把这些变量抽出来，用 YAML 做声明式描述。YAML 的好处是结构清晰、人类可读、天然适合做配置。你定义一个 profile，里面写清楚端点地址、认证方式、模型名称、超时参数，然后 openrig 负责把这些值注入到 Claude Code 或 Codex 期望的环境变量或配置文件里。这样一来，切换配置就是切换 profile 名称，回滚就是 git checkout，团队共享就是提交 YAML 文件。

这个设计背后有一个关键判断：AI 编程助手的配置复杂度会持续上升。现在可能只是换个 API key，将来可能涉及多模型路由、上下文长度管理、工具权限控制。如果没有一层编排，每个工具各自为政，维护成本会指数级增长。openrig 提前把这层抽象做出来，相当于给未来的扩展留好了接口。

2.2 YAML 作为配置核心的选型理由

为什么是 YAML 而不是 JSON、TOML 或环境变量文件？这里有几个实际考量。JSON 不支持注释，配置里想写“这个端点仅用于测试”都没地方写，维护起来很痛苦。TOML 虽然支持注释，但嵌套结构表达力不如 YAML 直观，尤其是涉及列表和深层映射时。环境变量文件最简单，但没法表达层级关系，profile 一多就乱。

YAML 的缩进语法虽然容易踩坑（比如 tab 和空格混用），但它的表达力和可读性在配置场景下是最优解。openrig 选择 YAML，还有一个现实原因：Claude Code 和 Codex 生态里已经有大量 YAML 配置实践，比如 CI 流程、模型参数文件，用户对这个格式不陌生。另外 YAML 天然支持锚点和引用，可以在多个 profile 之间复用公共配置块，减少重复。

我自己的做法是把配置分成三层：基础层放通用参数（超时、日志级别），中间层放环境相关配置（端点地址、认证方式），最上层是具体 profile（日常开发、测试、演示）。用 YAML 的锚点语法，上层可以继承下层，只覆盖需要改的字段。这样新增一个 profile 只需要写几行，维护成本很低。

2.3 tmux 在 openrig 工作流中的角色

tmux 在这里不是可选项，而是 openrig 工作流的重要组成。原因很直接：Claude Code 和 Codex 都是长时间运行的交互式进程，你可能同时开好几个会话，一个在跑代码生成，一个在等模型响应，一个在做调试。如果没有 tmux，这些会话管理起来很麻烦，关掉终端就全没了。

openrig 配合 tmux 的典型用法是：每个 profile 对应一个 tmux 会话或窗口，会话里预设好环境变量和启动命令。你想切换到某个配置，不是去改文件，而是 attach 到对应的 tmux 会话。这样做的好处是会话隔离——不同 profile 的环境变量互不干扰，而且会话可以后台保持，网络断了重连后继续用。

更深一层，tmux 还解决了“配置生效时机”的问题。环境变量在进程启动时读取，如果你在已经运行的 Claude Code 里改了配置，不重启是不生效的。但重启意味着丢失当前上下文。用 tmux 的话，你可以开一个新窗口用新配置，旧窗口保持不动，需要时再切回去。这种“多配置并行”的能力，在调试模型端点问题时特别有用。

2.4 方案优势与要规避的问题

openrig 这套方案的核心优势有三个。第一是可复现：配置在 YAML 里，出问题可以精确对比“能用”和“不能用”的差异。第二是可协作：YAML 文件进 git，团队成员拉下来就能用，不需要口头传递配置。第三是可扩展：新增工具或新增模型，只需要加一个 profile 块，不影响现有配置。

但要规避的问题也很明确。首先是密钥管理：YAML 里绝对不能硬编码 API key，必须用环境变量引用或外部密钥管理。我见过有人把 key 提交到公开仓库，结果被扫到滥用，这个坑一定要避开。其次是YAML 语法陷阱：缩进错误、冒号后缺空格、特殊字符未转义，这些都会导致解析失败，而且报错信息往往不直观。最后是tmux 会话泄漏：如果脚本里创建了会话但没清理，时间长了会积累一堆僵尸会话，需要定期检查。

3. 核心细节解析与实操要点

3.1 openrig 配置文件的结构设计

一个典型的 openrig 配置目录长这样：根目录下有一个openrig.yaml作为主配置，旁边有profiles/目录存放各个 profile 文件，还有secrets/目录（加入 .gitignore）存放本地密钥引用。主配置里定义默认值和 profile 列表，profile 文件里写具体覆盖项。

主配置的关键字段包括：default_profile指定默认使用哪个 profile，tools定义支持的工具（claude-code、codex 等），env_passthrough列出需要从系统环境透传的变量名。profile 文件里则写endpoint、model、auth_type、timeout、extra_env这些具体值。

这里有个设计细节值得说：env_passthrough机制。有些密钥你不希望写在 YAML 里，而是放在系统环境变量或密钥管理工具里。openrig 启动时会把env_passthrough列出的变量从当前环境读取，注入到目标工具的进程中。这样 YAML 文件可以安全提交，密钥留在本地。我通常把ANTHROPIC_API_KEY、OPENAI_API_KEY这类敏感变量放进 passthrough 列表。

另一个细节是 profile 的继承。YAML 锚点语法可以这样用：

# profiles/base.yaml base: &base timeout: 120 log_level: info retry_count: 3 # profiles/dev.yaml dev: <<: *base endpoint: "http://localhost:8080" model: "local-model"

这样devprofile 自动继承base的超时、日志、重试配置，只覆盖端点和模型。新增 profile 时复制这几行改一下就行，不用重复写公共参数。

3.2 Claude Code 与 Codex 的配置差异处理

Claude Code 和 Codex 虽然都是命令行 AI 助手，但配置方式有差异。Claude Code 主要通过环境变量读取配置，比如端点地址、认证 token、模型名称都走环境变量。Codex 则更依赖配置文件，通常在用户目录下有~/.codex/config之类的文件，认证信息可能走单独的 auth 流程。

openrig 处理这种差异的方式是“适配器模式”。每个工具在 openrig 里有一个适配器定义，说明这个工具期望的配置形式是什么。对于 Claude Code，适配器把 profile 里的值转成环境变量；对于 Codex，适配器可能生成一个临时配置文件，或者设置特定的环境变量让 Codex 读取。

实际操作中，我建议先手动把每个工具跑通，记录下“能用”的状态下哪些环境变量或配置文件起了作用。然后把这些观察结果写成适配器规则。比如 Claude Code 需要ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY，Codex 可能需要OPENAI_BASE_URL和OPENAI_API_KEY，适配器就负责把统一的 profile 字段映射到这些具体变量名。

注意：不同版本的 Claude Code 和 Codex 可能改变配置读取方式。升级工具后，先验证适配器是否仍然有效，再批量应用到所有 profile。

3.3 tmux 会话模板的编写要点

tmux 会话模板是 openrig 工作流里最实用的部分。一个模板本质上是一个 shell 脚本，负责创建会话、设置环境变量、启动工具。我通常把模板放在templates/目录下，每个 profile 对应一个模板。

模板的关键步骤：首先用tmux new-session -d -s <session_name>创建后台会话，然后用tmux send-keys发送环境变量设置命令，最后发送启动 Claude Code 或 Codex 的命令。环境变量设置可以用export VAR=value的形式，但更安全的做法是把 openrig 解析后的配置写到一个临时文件，在会话里 source 这个文件。

这里有个细节：tmux send-keys发送的命令需要等待 shell 就绪。如果会话刚创建就发命令，可能丢失。稳妥的做法是在创建会话后加一个短延迟，或者用tmux wait-for做同步。我自己的模板里会先发一个echo ready并等待输出，确认 shell 就绪后再发后续命令。

会话命名建议带上 profile 名称和时间戳，比如claude-dev-20250101，方便识别和清理。清理可以用tmux kill-session -t <name>，也可以写一个openrig clean命令批量清理超过一定时间的会话。

3.4 密钥与敏感信息的安全处理

密钥处理是 openrig 使用中最容易出问题的地方。我的原则是：YAML 文件里永远不出现真实密钥，只出现引用。引用的形式可以是环境变量名，比如${ANTHROPIC_API_KEY}，openrig 解析时从环境读取。也可以是外部命令的输出，比如$(pass show anthropic/key)，openrig 执行命令获取值。

对于团队协作，建议把密钥管理独立出来。每个人本地有自己的密钥存储方式，openrig 只负责引用。CI 环境里用 CI 平台的密钥管理功能注入环境变量。这样 YAML 文件可以放心提交，不会泄露。

还有一个容易忽略的点：日志和错误输出。openrig 在调试模式下可能会打印解析后的配置，如果配置里包含密钥，就会泄露到日志里。所以解析后的配置在打印前必须做脱敏处理，把密钥字段替换成***。这个功能要在 openrig 的日志模块里实现，不能依赖使用者自觉。

4. 实操过程与核心环节实现

4.1 环境准备与 openrig 初始化

开始之前，确认系统里有这些基础工具：git（拉取 openrig 仓库）、Python 3.9+ 或 Node.js 18+（取决于 openrig 的实现语言）、tmux 3.0+。Claude Code 和 Codex 本身也需要提前装好，确保能手动跑通。

初始化 openrig 的步骤：先克隆仓库到本地，然后运行初始化脚本。初始化脚本会创建配置目录结构、生成示例 profile、检查依赖是否齐全。我建议初始化后先不要改配置，用默认 profile 跑一次，确认基础流程通畅。

git clone <openrig-repo-url> ~/openrig cd ~/openrig ./scripts/init.sh

初始化完成后，目录结构应该是这样：

~/openrig/ ├── openrig.yaml ├── profiles/ │ ├── base.yaml │ └── example.yaml ├── templates/ │ └── example.sh ├── secrets/ │ └── .gitkeep └── scripts/ ├── init.sh ├── launch.sh └── clean.sh

secrets/目录默认加入.gitignore，用来放本地密钥文件。launch.sh是核心启动脚本，负责解析配置、创建 tmux 会话、启动工具。

4.2 编写第一个可用的 profile

从example.yaml复制一份，改名为mydev.yaml。打开文件，先填最基本的字段：

mydev: <<: *base tool: claude-code endpoint: "https://api.anthropic.com" model: "claude-sonnet-4-20250514" auth_env: "ANTHROPIC_API_KEY" timeout: 180 extra_env: CLAUDE_CODE_MAX_TOKENS: "8192"

这里auth_env指定从哪个环境变量读取密钥，而不是直接写密钥值。extra_env用来传递工具特有的配置项。填完后，在openrig.yaml的profiles列表里加上mydev，并把default_profile设为mydev。

验证配置是否有效：运行./scripts/launch.sh --dry-run mydev，这个命令会解析配置并打印将要设置的环境变量和启动命令，但不实际创建会话。检查输出里端点、模型、超时是否符合预期，密钥字段是否显示为***。

4.3 启动 tmux 会话并运行 Claude Code

确认 dry-run 输出无误后，正式启动：

./scripts/launch.sh mydev

这个命令会创建一个名为claude-mydev-<timestamp>的 tmux 会话，在会话里设置好环境变量，然后启动 Claude Code。你会自动 attach 到这个会话，看到 Claude Code 的交互界面。

如果想在后台启动不自动 attach，加--detach参数。之后用tmux attach -t <session_name>进入。查看当前有哪些 openrig 会话：

tmux ls | grep openrig

我通常会在 tmux 配置里加一个快捷键，快速列出和切换 openrig 会话。比如在~/.tmux.conf里加：

bind o run-shell "tmux ls | grep openrig"

这样按Ctrl+b再按o就能看到所有 openrig 会话。

4.4 切换 profile 与多会话并行

切换 profile 不是修改现有会话，而是启动一个新会话。比如从mydev切到mytest：

./scripts/launch.sh mytest

新会话会用自己的配置启动，旧会话保持不动。你可以在两个会话之间用tmux switch-client -t <session_name>切换，或者用Ctrl+b加s打开会话选择界面。

多会话并行的价值在调试时特别明显。比如你怀疑是端点问题，可以同时开一个指向官方服务的会话和一个指向本地模型的会话，对比行为差异。又比如你在跑一个长任务，不想中断，可以开一个新会话做其他事，长任务在后台继续。

提示：每个 tmux 会话都会占用一定内存，Claude Code 和 Codex 本身也是资源消耗大户。同时开的会话建议不超过 5 个，用完及时清理。

4.5 清理会话与配置维护

定期清理不再使用的会话：

./scripts/clean.sh --older-than 24h

这个脚本会列出超过 24 小时未活动的 openrig 会话并询问是否关闭。也可以加--force直接关闭。我习惯每天下班前跑一次，保持环境干净。

配置维护方面，建议把~/openrig目录本身用 git 管理。profile 文件的变更走 commit，这样每次配置调整都有记录。如果某个配置改坏了，git diff一看就知道改了什么，git checkout就能回滚。团队共享时，每个人 fork 一份仓库，通过 pull request 合并配置变更，评审后再应用。

5. 常见问题与排查技巧实录

5.1 配置解析失败的典型原因

YAML 解析错误是最高频的问题。常见原因和排查方法整理成表：

我踩过最坑的一次是缩进混用。编辑器里看着对齐，实际上一行是空格一行是 tab，YAML 解析器直接报错但错误行号指向别处。后来养成习惯，写完 YAML 先跑一次python -c "import yaml; yaml.safe_load(open('file.yaml'))"验证语法，通过了再启动。

5.2 工具启动后连不上端点的排查

配置解析通过，但 Claude Code 或 Codex 启动后报连接错误，排查顺序如下。先确认环境变量是否真的注入到了 tmux 会话里：attach 到会话，运行env | grep -i anthropic或env | grep -i openai，看端点地址和密钥是否存在。如果环境变量缺失，说明 launch 脚本的注入逻辑有问题，检查env_passthrough列表是否包含相关变量名。

环境变量存在但连不上，用curl手动测试端点可达性：

curl -v -H "Authorization: Bearer $ANTHROPIC_API_KEY" $ANTHROPIC_BASE_URL/v1/models

如果 curl 也失败，问题在网络层或端点配置。如果 curl 成功但工具失败，问题在工具本身的配置读取逻辑，可能需要检查工具版本或适配器映射是否正确。

还有一种情况是代理设置干扰。有些环境里HTTP_PROXY或HTTPS_PROXY环境变量会影响工具的网络请求。如果端点不需要代理，在 profile 的extra_env里显式设置NO_PROXY包含端点域名。

5.3 tmux 会话异常的处理

tmux 会话创建失败，常见原因是会话名冲突。如果同名会话已存在，new-session会报错。launch 脚本里应该先检查会话是否存在，存在则提示或自动加时间戳后缀。另一个原因是 tmux server 没启动，首次运行 tmux 命令时会自动启动 server，但如果权限或 socket 路径有问题，会启动失败。检查tmux ls是否能正常列出会话。

会话创建成功但命令没执行，通常是send-keys时机问题。shell 还没就绪就发命令，命令会丢失。解决办法是在模板里加等待逻辑，比如发送命令后检查输出里是否有预期提示符。我自己的模板里用了一个简单的重试机制：发送echo __READY__，循环检查 pane 内容里是否出现__READY__，出现后再发真正的启动命令。

会话积累过多导致系统变慢，用clean.sh清理。如果 clean 脚本本身出问题，手动清理：tmux ls | grep openrig | cut -d: -f1 | xargs -I{} tmux kill-session -t {}。

5.4 密钥相关问题的独家避坑技巧

密钥问题最隐蔽也最危险。第一个坑是密钥泄露到日志。openrig 的调试输出、tmux 的 pane 历史、shell 的 history 文件，都可能记录密钥。我的做法是：密钥只通过环境变量传递，不写在命令行参数里；tmux 会话里设置HISTFILE=/dev/null避免命令历史记录；调试输出强制脱敏。

第二个坑是密钥过期或额度耗尽。表现是工具突然连不上，但配置没改。排查时先确认密钥是否有效，用 curl 测试。如果密钥失效，更新环境变量后需要重启 tmux 会话才能生效，因为环境变量在进程启动时读取。

第三个坑是多 profile 共用密钥导致混淆。比如测试 profile 误用了生产密钥，产生意外费用。我的做法是不同 profile 用不同的环境变量名，比如ANTHROPIC_API_KEY_DEV和ANTHROPIC_API_KEY_PROD，profile 里明确指定用哪个。这样即使配置写错，也不会误用。

5.5 性能与资源占用的优化建议

Claude Code 和 Codex 都是资源消耗较大的进程，多个会话并行时要注意系统负载。几个优化点：tmux 会话里可以设置history-limit限制回滚缓冲区大小，默认可能很大，改成 5000 行足够用。Claude Code 的上下文长度设置也会影响内存占用，如果不是必须，不要把CLAUDE_CODE_MAX_TOKENS设得过高。

网络层面，如果端点响应慢，适当增加timeout值，但不要无限大。我通常设 180 秒，超过这个时间基本是网络问题，继续等没意义。重试次数设 2 到 3 次，太多会放大问题。

磁盘层面，tmux 的 pane 日志如果开启会持续写文件，定期清理。openrig 的日志文件也要设置轮转，避免单个文件过大。我一般配置 logrotate 每天轮转，保留 7 天。

6. 进阶用法与个人实践体会

6.1 多模型端点的快速切换实践

用 openrig 一段时间后，我最常用的功能是快速切换模型端点。比如日常开发用官方服务，成本敏感的任务切到本地模型，需要长上下文时切到支持大窗口的端点。每个端点对应一个 profile，切换就是启动新会话。

为了让切换更快，我写了一个switch.sh脚本，接受 profile 名称作为参数，自动关闭当前会话（可选）并启动新会话。配合 tmux 的会话切换快捷键，整个过程不到两秒。这个脚本的核心逻辑就是调用launch.sh，但加了会话清理和状态提示。

还有一个技巧是在 profile 里预设多个端点的 fallback 顺序。openrig 本身不直接支持 fallback，但可以在启动脚本里实现：先尝试主端点，失败后自动切换到备用端点。这个逻辑对稳定性要求高的场景很有用，比如演示时不能中断。

6.2 把 openrig 配置纳入版本控制

把~/openrig目录用 git 管理后，配置变更变得可追溯。我的做法是：主分支保持稳定配置，每个实验性配置开一个分支，验证通过后合并。commit message 写清楚改了什么、为什么改，比如“将 dev profile 端点切换到本地模型以降低测试成本”。

团队协作时，每个人 fork 主仓库，通过 pull request 提交配置变更。评审时重点看端点地址、模型名称、超时参数是否合理，密钥引用是否正确。合并后，其他人 pull 下来就能用新配置。

注意：.gitignore必须包含secrets/目录和任何包含真实密钥的文件。提交前用git diff --cached检查一遍，确认没有密钥混入。

6.3 我踩过的三个印象深刻的坑

第一个坑是 YAML 锚点跨文件引用。我以为锚点可以在不同 YAML 文件之间共享，实际上不行。锚点只在单个文件内有效。解决办法是把公共配置放在同一个文件里，或者用 openrig 的 include 机制合并文件后再解析。

第二个坑是 tmux 会话里的环境变量污染。有一次我在一个会话里手动 export 了一个变量做测试，忘了 unset，结果后续在这个会话里启动的工具都读到了错误的值。后来我养成习惯，测试用的环境变量只在子 shell 里设置，不影响会话主环境。

第三个坑是配置文件权限。secrets/目录如果权限是 755，同机器其他用户可能读到密钥文件。改成 700，并且确保密钥文件本身是 600。这个细节很容易忽略，但安全影响很大。

6.4 后续可以扩展的方向

openrig 这套框架搭好后，可以往几个方向扩展。一是支持更多工具，比如把其他命令行 AI 助手也纳入统一配置管理。二是增加配置校验功能，启动前自动检查端点可达性、密钥有效性、模型名称是否正确。三是做配置模板市场，团队成员分享常用配置模板，新人直接套用。

我个人还在探索的一个方向是把 openrig 和 CI 流程结合。比如在 CI 里用 openrig 启动一个 Claude Code 会话，自动跑代码审查任务。这需要解决 CI 环境里的密钥注入和会话生命周期管理问题，目前还在试验阶段，但初步效果不错。

最后分享一个小技巧：在 tmux 状态栏显示当前 openrig profile 名称。这样你一眼就能看出当前会话用的是哪套配置，避免在错误的配置下操作。实现方式是在 tmux 配置里用#(openrig current)之类的命令获取当前 profile，显示在状态栏右侧。这个小小的提示，帮我避免了好几次“以为在用测试配置实际在用生产配置”的尴尬。