1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件项目毕竟“rig”这个词在英文里常指设备支架或者矿机机架。但在当前 AI 编程工具爆发的语境下openrig 指向的是一个非常具体且迫切的需求把 Claude Code、Codex 这类命令行 AI 编程助手统一管理起来让它们在不同项目、不同模型后端之间自由切换而不需要每次手动改配置、重装工具或者反复登录。我最初接触这个方向是因为同时在使用 Claude Code 和 Codex 两套工具。Claude Code 在代码理解和长上下文任务上表现很稳Codex 在某些场景下的响应速度和代码生成风格又更合我意。问题在于这两个工具各自维护一套配置体系Claude Code 依赖~/.claude目录下的设置Codex 有自己的~/.codex配置和认证机制。每次切换项目如果项目对模型后端的要求不同我就得手动改配置文件有时候还要重新走一遍认证流程。这种重复劳动积累到一定程度就变成了一个必须解决的问题。openrig 的核心价值就在这里它本质上是一个配置编排层通过 YAML 文件定义不同的“装备方案”每个方案里指定用哪个 AI 编程工具、连接哪个模型端点、使用什么参数。你只需要在命令行敲一个切换命令整个环境就切过去了。这个概念有点像前端开发里的 nvm 或者 Python 环境里的 conda只不过它管理的是 AI 编程助手的运行时配置。适合谁来用如果你只是偶尔用一下 Claude Code 写个小脚本那可能不需要 openrig。但如果你符合以下任意一条它就值得你花时间研究每天在终端里跟 Claude Code 或 Codex 打交道超过两小时需要在多个项目之间切换而不同项目用的模型后端不一样团队里有人用 Claude Code 有人用 Codex需要统一配置规范或者你单纯厌倦了每次换工具都要重新配置一遍环境。我个人的判断标准很简单当你开始觉得“配置 AI 工具”这件事本身在消耗你的精力时就是引入 openrig 的时机。还有一个背景值得提一下。Claude Code 和 Codex 这类工具在国内的使用环境比较特殊网络条件、API 端点可用性、账号认证方式都会影响实际体验。openrig 的 YAML 配置方式恰好提供了一层抽象让你可以把这些环境相关的差异都封装在配置文件里切换的时候不需要动工具本身的安装。这个设计思路在实际使用中非常实用后面我会详细展开。2. openrig 的核心设计思路与方案选型2.1 为什么是 YAML 而不是 JSON 或 TOMLopenrig 选择 YAML 作为配置格式这个决定背后有很实际的考量。JSON 的问题在于不支持注释而 AI 编程工具的配置里经常需要标注“这个端点用于测试环境”“这个模型 ID 是临时的”之类的说明。TOML 虽然支持注释但在表达嵌套结构时不如 YAML 直观尤其是当你要定义多个 profile、每个 profile 下面又有多个工具配置的时候YAML 的缩进层级读起来更清晰。我实际写 openrig 配置的体验是一个典型的 profile 大概长这样profiles: claude-deepseek: tool: claude-code model: deepseek-chat endpoint: https://api.deepseek.com/v1 env: ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic ANTHROPIC_API_KEY: ${DEEPSEEK_API_KEY} tmux_session: claude-work codex-local: tool: codex model: local-model endpoint: http://localhost:1234/v1 env: OPENAI_API_BASE: http://localhost:1234/v1 OPENAI_API_KEY: not-needed tmux_session: codex-local这种结构的优势在于你可以把环境变量、模型参数、tmux 会话名都放在一个地方管理。切换的时候 openrig 会读取对应的 profile设置好环境变量然后在指定的 tmux 会话里启动工具。整个过程不需要你手动 export 任何东西。注意YAML 对缩进非常敏感建议统一用两个空格不要用 Tab。我见过太多因为缩进问题导致配置解析失败的案例排查起来很浪费时间。2.2 tmux 集成为什么是关键设计openrig 把 tmux 作为核心依赖而不是可选功能这个选择一开始让我有点意外但用久了就理解了。AI 编程助手的一个典型使用场景是你让它处理一个比较大的重构任务它需要跑几分钟甚至更久。如果没有 tmux你关掉终端窗口任务就断了。有了 tmux你可以随时 detach过一会儿再 attach 回来看进度。更重要的是openrig 利用 tmux 的会话管理能力实现了多工具并行。你可以同时开一个 Claude Code 会话在重构后端代码另一个 Codex 会话在写前端组件互不干扰。切换的时候只需要tmux attach -t claude-work或者tmux attach -t codex-local比开多个终端窗口优雅得多。我自己的习惯是给每个长期项目建一个 tmux 会话会话名跟项目名对应。openrig 的配置里直接指定tmux_session字段启动的时候如果会话不存在就新建存在就 attach 进去。这个细节看起来小但省去了很多“先 tmux new 再 cd 到项目目录再启动工具”的重复操作。2.3 环境变量注入的隔离策略openrig 在处理环境变量时采用了一种“按 profile 隔离”的策略。每个 profile 可以定义自己的env块切换时这些变量只对当前会话生效不会污染全局 shell 环境。这个设计解决了一个很实际的问题Claude Code 和 Codex 可能都需要OPENAI_API_KEY这个变量但值不一样。如果直接 export 到全局切换工具的时候就会冲突。实现方式上openrig 通常是在启动 tmux 会话时通过tmux new-session -d -s $SESSION创建会话然后用tmux send-keys把环境变量设置命令和工具启动命令依次发送进去。这样每个会话里的环境变量是独立的互不影响。我实测下来这种方式比在 shell 配置文件里写一堆 alias 要可靠得多尤其是在需要频繁切换的场景下。提示如果你在 profile 里引用了${SOME_SECRET}这样的变量确保它在当前 shell 里已经定义。openrig 一般不会帮你管理密钥密钥管理建议交给系统的密钥链或者专门的密码管理器。3. 核心细节解析与实操要点3.1 Claude Code 的配置要点与常见坑Claude Code 的配置核心在于两个环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。默认情况下它连接官方端点但通过修改ANTHROPIC_BASE_URL你可以把它指向任何兼容 Anthropic API 格式的服务。这个特性在实际使用中非常关键因为国内直接访问官方端点往往不稳定而通过兼容端点可以获得更一致的体验。在 openrig 的 profile 里配置 Claude Code 时有几个细节需要特别注意。第一ANTHROPIC_BASE_URL的路径要写完整有些服务需要/v1后缀有些不需要这个要看你用的具体服务商的文档。第二Claude Code 在启动时会检查~/.claude.json或者项目目录下的.claude配置如果这些文件里也有端点设置可能会覆盖环境变量。我的做法是在 openrig 启动前先确保这些文件不存在冲突配置或者直接用--config参数指定配置文件路径。还有一个经常被忽略的点Claude Code 的模型名称映射。当你把端点指向第三方服务时Claude Code 默认会请求claude-sonnet-4-20250514这样的模型 ID但第三方服务可能用的是deepseek-chat或者别的命名。这时候需要在配置里做模型名称的映射或者在启动参数里显式指定模型。openrig 的 profile 里可以加一个model_map字段来处理这种转换。profiles: claude-via-deepseek: tool: claude-code env: ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic ANTHROPIC_API_KEY: ${DEEPSEEK_API_KEY} ANTHROPIC_MODEL: deepseek-chat args: - --model - deepseek-chat注意有些第三方端点对 Anthropic API 的兼容程度不一样比如流式响应的格式可能有细微差异。如果遇到 Claude Code 卡住不输出或者报解析错误优先检查端点的兼容性说明。3.2 Codex 的认证机制与配置隔离Codex 的配置比 Claude Code 稍微复杂一些因为它涉及认证 token 的管理。Codex 通常把认证信息存在~/.codex/auth.json或者类似的位置如果你同时用多个账号或者多个端点就需要在不同的认证文件之间切换。openrig 处理这个问题的方式是允许每个 profile 指定独立的CODEX_HOME目录这样不同 profile 的认证信息天然隔离。具体操作上你可以在 openrig 的配置目录下建几个子目录比如codex-profiles/work/和codex-profiles/personal/每个目录里放一份auth.json和config.toml。profile 里设置CODEX_HOME指向对应的目录启动的时候 Codex 就会读取那个目录下的配置。这个方案的好处是你不需要反复登录切换 profile 就等于切换账号。Codex 的另一个配置重点是模型选择。Codex 支持通过--model参数指定模型也支持在config.toml里设置默认模型。如果你用的是兼容 OpenAI API 的第三方服务需要在配置里把base_url指向对应的端点。我实测下来Codex 对 OpenAI API 的兼容性要求比 Claude Code 对 Anthropic API 的要求更严格一些特别是在 function calling 和 streaming 这两个特性上如果端点实现不完整可能会遇到工具调用失败的问题。3.3 tmux 会话命名与工作目录管理openrig 的 tmux 集成里会话命名和工作目录是两个容易被忽视但影响很大的细节。会话命名建议遵循一个固定的规则比如工具名-项目名或者项目名-用途。我自己的规则是cc-项目简称表示 Claude Code 会话cx-项目简称表示 Codex 会话。这样tmux ls的时候一眼就能看出每个会话是干什么的。工作目录的管理上openrig 的 profile 里可以指定workdir字段。启动 tmux 会话时openrig 会先cd到指定目录再启动工具。这个功能看起来简单但省去了很多手动切换目录的操作。特别是当你同时维护多个项目的时候每个项目的 AI 会话都在自己的目录里启动不会出现“在 A 项目目录里启动了 B 项目的 AI 助手”这种低级错误。还有一个实用技巧在 tmux 会话里设置history-limit。AI 编程助手的输出有时候会很长默认的 tmux 回滚缓冲区可能不够用。在~/.tmux.conf里加上set-option -g history-limit 50000可以保留更多的输出历史方便回溯之前的对话和代码生成结果。3.4 配置文件版本管理与团队协作openrig 的配置文件天然适合纳入版本管理。你可以把openrig.yaml放在项目的.openrig/目录下跟代码一起提交。团队成员拉取代码后只需要根据自己的环境调整密钥相关的环境变量其他配置直接复用。这个做法在团队协作场景下特别有价值因为它统一了 AI 工具的使用规范。不过这里有一个安全注意事项绝对不要把 API 密钥直接写在 YAML 文件里提交到仓库。正确的做法是在 YAML 里用${VAR_NAME}引用环境变量然后在本地通过.env文件或者系统的环境变量来提供实际值。.env文件要加入.gitignore确保不会被误提交。我见过不止一个团队因为把密钥写进配置文件提交到公开仓库而导致密钥泄露的案例这个坑一定要避开。提示如果你的团队用 1Password 或者类似的密码管理器可以结合它们的 CLI 工具在启动 openrig 前自动注入环境变量这样既安全又方便。4. 实操过程与核心环节实现4.1 环境准备与 openrig 安装在开始配置之前需要确保系统里已经装好了基础依赖。openrig 本身通常是一个 shell 脚本或者轻量级的 CLI 工具安装方式取决于具体的发行版本。我建议从源码安装这样你可以清楚地知道它在做什么也方便根据自己的需求调整。首先确认 tmux 已经安装并且版本不要太老。在 Ubuntu 或者 Debian 系统上sudo apt install tmux就够了。macOS 用户用brew install tmux。安装完成后用tmux -V检查版本建议 3.0 以上。然后安装 Claude Code 和 Codex。Claude Code 的安装方式通常是npm install -g anthropic-ai/claude-codeCodex 的安装方式类似具体命令参考官方文档。安装完成后分别运行一次claude --version和codex --version确认工具本身可以正常工作。这一步很重要因为如果工具本身有问题openrig 的配置再正确也没用。openrig 本身的安装如果是脚本形式下载后放到~/bin/或者/usr/local/bin/下加上执行权限即可。如果是通过包管理器分发按照对应的安装命令操作。安装完成后运行openrig --help确认命令可用。4.2 编写第一个 openrig 配置文件配置文件的位置通常在~/.config/openrig/config.yaml或者项目目录下的.openrig.yaml。我建议先从全局配置开始把常用的 profile 定义好然后项目级别的配置只覆盖需要差异化的部分。一个完整的配置示例version: 1 defaults: tmux_history_limit: 50000 shell: /bin/bash profiles: cc-official: tool: claude-code workdir: ~/projects/main tmux_session: cc-main env: ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY} args: [] cc-deepseek: tool: claude-code workdir: ~/projects/main tmux_session: cc-main-ds env: ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic ANTHROPIC_API_KEY: ${DEEPSEEK_API_KEY} ANTHROPIC_MODEL: deepseek-chat args: - --model - deepseek-chat cx-local: tool: codex workdir: ~/projects/experiment tmux_session: cx-exp env: CODEX_HOME: ~/.config/openrig/codex-local OPENAI_API_BASE: http://localhost:1234/v1 OPENAI_API_KEY: local args: - --model - local-model这个配置定义了三个 profile一个用官方端点的 Claude Code一个用第三方端点的 Claude Code一个用本地模型的 Codex。每个 profile 都有独立的 tmux 会话名和工作目录。4.3 切换与启动流程详解配置写好后使用 openrig 切换 profile 的命令通常是openrig use profile-name或者openrig switch profile-name。执行这个命令时openrig 会做以下几件事第一步读取配置文件找到对应的 profile 定义。如果 profile 不存在会报错并列出可用的 profile 列表。第二步检查 tmux 会话是否已经存在。如果存在直接 attach 进去如果不存在创建新会话。第三步在新会话里设置环境变量。这一步通常是通过tmux send-keys发送 export 命令实现的。环境变量设置完成后再发送工具启动命令。第四步attach 到 tmux 会话你就能看到 AI 编程助手已经启动并等待输入了。整个过程通常在 1-2 秒内完成。我实测下来比手动开终端、cd 目录、export 变量、启动工具这一套流程快很多而且不容易出错。注意如果你在 profile 里引用了未定义的环境变量openrig 可能会静默使用空值导致工具启动后认证失败。建议在启动前用env | grep KEY_NAME确认变量已经设置。4.4 多项目并行场景下的实操记录我目前同时维护三个项目一个后端服务、一个前端应用、一个数据分析脚本集。每个项目对 AI 工具的需求不一样。后端服务用 Claude Code 配合官方端点因为需要处理复杂的重构任务前端应用用 Codex 配合本地模型因为主要是写组件和样式本地模型响应更快数据分析脚本用 Claude Code 配合第三方端点因为需要长上下文来处理大量数据文件。openrig 的配置里对应三个 profile每个 profile 的workdir指向不同的项目目录tmux_session用不同的名称。早上开始工作的时候我依次执行三个openrig use命令三个 tmux 会话就都起来了。然后在需要的时候用tmux attach -t cc-backend切到后端会话处理完再切到前端会话。这种工作方式比之前开一堆终端窗口要清爽得多而且每个会话的环境是隔离的不会出现变量冲突。一个实际踩过的坑tmux 会话名如果包含特殊字符或者空格attach 的时候会很麻烦。建议只用字母、数字和连字符。另外如果项目路径里有中文或者空格workdir字段最好用引号包起来避免解析问题。5. 常见问题与排查技巧实录5.1 Claude Code 启动后无法连接端点这是最常见的问题之一。表现是 Claude Code 启动后一直转圈或者报连接超时。排查思路按以下顺序进行先确认ANTHROPIC_BASE_URL是否设置正确。在 tmux 会话里执行echo $ANTHROPIC_BASE_URL看输出是否符合预期。如果为空说明 openrig 的环境变量注入没生效检查 profile 的env块缩进是否正确。再确认端点本身是否可达。用curl -I $ANTHROPIC_BASE_URL测试连通性。如果返回 404 或者 403说明端点地址不对或者密钥无效。注意有些端点需要特定的路径前缀比如/v1/messages而ANTHROPIC_BASE_URL只需要写到域名部分。最后检查密钥是否有效。用curl直接调一次 API看返回的认证错误信息。如果提示invalid api key说明密钥配置有问题。如果提示insufficient balance那就是账户余额的问题了。5.2 Codex 报 auth token is unavailable这个错误通常意味着 Codex 找不到有效的认证信息。排查步骤确认CODEX_HOME指向的目录里存在auth.json文件。如果文件不存在需要先运行一次codex login生成认证信息。如果文件存在但报错检查文件权限确保当前用户有读取权限。另一个可能的原因是auth.json的格式跟当前 Codex 版本不兼容。Codex 更新比较频繁认证文件的格式偶尔会变。解决办法是删除旧的auth.json重新登录生成新的。如果用的是第三方端点确认OPENAI_API_KEY设置正确。有些第三方端点不需要密钥但 Codex 可能仍然要求这个变量存在这时候随便填一个非空值即可。5.3 tmux 会话无法 attach 或显示异常有时候tmux attach会报no sessions或者 attach 后界面混乱。前者的原因通常是会话已经退出用tmux ls确认一下。如果会话列表为空说明之前的会话已经结束了重新用 openrig 启动即可。界面混乱通常是终端类型不匹配导致的。在 tmux 会话里执行echo $TERM正常应该是screen-256color或者tmux-256color。如果是dumb或者空值需要在~/.tmux.conf里加上set -g default-terminal screen-256color然后重启 tmux 服务。还有一个常见问题是中文显示乱码。这通常是因为 tmux 的 locale 设置不对。在~/.tmux.conf里加上set -g utf8 on和set -g status-utf8 on并确保系统的LANG环境变量设置为en_US.UTF-8或者zh_CN.UTF-8。5.4 配置文件修改后不生效openrig 通常会在每次执行时重新读取配置文件所以修改后不需要重启什么服务。但如果你发现修改没生效检查以下几点确认修改的是正确的配置文件。openrig 可能同时支持全局配置和项目级配置项目级配置的优先级更高。用openrig config path之类的命令确认当前生效的配置文件路径。确认 YAML 语法正确。用python -c import yaml; yaml.safe_load(open(config.yaml))快速检查语法。常见的语法错误包括缩进不一致、冒号后面缺空格、字符串里有未转义的特殊字符。确认环境变量已经重新加载。如果你在 shell 里 export 了新的变量但 openrig 是在另一个 shell 里执行的那个 shell 可能看不到新变量。解决办法是在同一个 shell 里执行 openrig或者把变量写进~/.bashrc后重新打开终端。5.5 常见问题速查表问题现象可能原因排查命令解决方案Claude Code 连接超时端点地址错误或网络不通curl -I $ANTHROPIC_BASE_URL检查端点地址和网络连接Codex 认证失败auth.json 缺失或过期ls $CODEX_HOME/auth.json重新执行 codex logintmux 会话不存在会话已退出或名称错误tmux ls重新用 openrig 启动中文显示乱码locale 设置不正确echo $LANG设置 UTF-8 locale配置修改不生效改错了文件或语法错误openrig config path确认文件路径和 YAML 语法环境变量为空变量未定义或注入失败envgrep VAR_NAME模型名称不匹配端点不支持默认模型 ID查看端点文档在 args 里显式指定模型提示遇到问题时先用openrig --debug或者类似参数启动查看详细的日志输出。大部分问题在日志里都有明确的错误信息比盲目猜测高效得多。5.6 几个我踩过的坑和对应的技巧第一个坑是 tmux 会话里的 PATH 问题。openrig 启动 tmux 会话时如果用的是tmux new-session -d这种非登录 shell 的方式可能会继承一个不完整的 PATH导致找不到 claude 或者 codex 命令。解决办法是在 profile 的启动命令里用绝对路径或者在 tmux 会话里先source ~/.bashrc再启动工具。第二个坑是多个 profile 共用同一个 tmux 会话名。如果你不小心在两个 profile 里写了相同的tmux_session后启动的会 attach 到已有的会话而不是创建新的。结果就是你以为切换了 profile实际上还在旧的环境里。建议在配置里加一个校验确保会话名唯一。第三个坑是 YAML 里的布尔值陷阱。YAML 会把yes、no、on、off解析成布尔值如果你本来想写字符串就会出问题。比如模型名称里如果有on这个词可能会被解析成true。解决办法是给这类值加上引号明确告诉 YAML 这是字符串。第四个坑是环境变量里的特殊字符。如果 API 密钥里包含$、!或者反引号在 shell 里 export 的时候可能会被解释成特殊含义。建议用单引号包裹变量值或者在.env文件里用引号包起来。我遇到过密钥里有个$符号导致认证一直失败的情况排查了很久才发现是 shell 转义的问题。5.7 性能优化与日常维护建议openrig 本身很轻量性能瓶颈通常不在它身上而在 AI 工具和网络连接上。但有几个小优化可以提升日常使用体验。tmux 的history-limit建议设大一些50000 行起步。AI 编程助手的输出有时候会很长回滚缓冲区不够的话之前的对话记录就找不回来了。如果经常切换 profile可以给常用的几个 profile 设置 shell alias。比如alias ccopenrig use cc-official这样敲两个字母就能切换比打完整命令快很多。定期清理不再使用的 tmux 会话。用tmux ls查看所有会话用tmux kill-session -t 会话名关闭不需要的。会话太多会占用系统资源也会让tmux ls的输出变得难以阅读。配置文件建议纳入 git 管理但记得把包含密钥的部分排除掉。可以用git-secrets或者类似的工具做提交前检查防止密钥意外泄露。最后openrig 的配置不是一成不变的。随着你使用的 AI 工具和模型端点变化配置文件也需要相应调整。我自己的习惯是每个月回顾一次配置把不再使用的 profile 清理掉把新的常用配置加进去。保持配置文件的整洁跟保持代码整洁一样重要。