1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件项目毕竟 “rig” 这个词在英文里常指设备支架、矿机架或者实验台。但在当前 AI 编程助手爆发的背景下openrig 实际上是一个围绕Claude Code、Codex 等命令行 AI 编程工具构建的开源配置管理与运行环境编排方案。它的核心目标很直接让你在不同机器、不同终端会话、不同模型供应商之间快速切换和稳定运行这些 AI 编程助手而不是每次手动改配置、重装依赖、重新登录。我最初接触 openrig 是因为一个很现实的问题我在本地同时用 Claude Code 做代码审查用 Codex 做快速补全和重构偶尔还要把请求转发到本地模型做离线测试。每换一个项目目录就要改一遍 YAML 配置每开一个新终端就要重新确认环境变量有没有加载tmux 会话一多根本记不清哪个窗口跑的是哪个工具。openrig 的出现本质上是把“AI 编程助手的运行环境”当成一个可声明、可复现、可版本管理的工程问题来处理。它适合的人群很明确第一已经在用或者准备用 Claude Code、Codex 这类 CLI 工具的开发者第二需要在多台机器之间同步配置的人第三想把本地模型、远程 API、不同供应商统一接入同一套工作流的人第四喜欢用 tmux 做多会话管理、追求终端效率的工程师。如果你只是偶尔在网页上问问代码问题那 openrig 可能有点重但如果你已经把 AI 编程助手当成日常主力工具它的价值会非常明显。从热词分布也能看出来大家最关心的几个点集中在Claude Code 安装与使用、Codex 安装与登录、YAML 配置文件怎么写、tmux 怎么配合、本地模型怎么接入、以及各种代理和端点报错怎么排查。openrig 恰好覆盖了这些痛点它不是某一个单独的工具而是一层“胶水”和“规范”把配置、启动、切换、日志、会话管理串起来。提示openrig 本身不是模型也不是 API 供应商。它不提供算力也不绕过任何官方限制。它做的事情是让你已有的工具和账号在本地跑得更顺、更可管理。2. openrig 的整体设计思路与核心组件拆解2.1 为什么选择 YAML 作为配置核心openrig 用 YAML 作为主要配置格式这个选择不是随意的。YAML 在 DevOps 和云原生领域已经是事实标准Kubernetes、GitHub Actions、Docker Compose、Ansible 都在用。它的优势在于结构清晰、支持嵌套、可读性好、注释方便、几乎所有语言都有成熟解析库。对于 AI 编程助手这种需要描述“多个供应商、多个模型、多个端点、多个环境变量”的场景YAML 比 JSON 更适合手写比 TOML 更适合表达层级关系。一个典型的 openrig 配置会包含几个核心块providers定义模型供应商比如官方 API、本地推理服务、第三方兼容端点agents定义 Claude Code、Codex 等工具的运行参数sessions定义 tmux 会话布局env定义环境变量注入规则。这样设计的好处是你不需要记住每个工具的具体环境变量名只需要在 YAML 里声明“我要用哪个供应商”openrig 负责把它翻译成对应工具能识别的格式。我自己的习惯是把配置分成三层全局默认配置放在~/.config/openrig/base.yaml项目级覆盖放在项目根目录的.openrig.yaml临时实验配置放在~/.config/openrig/experiments/下。这样既保证了常用配置的稳定性又不会因为一次实验把主环境搞乱。YAML 的合并策略通常是深度合并但要注意列表类型一般是替换而不是追加这个后面会详细说。2.2 Claude Code 与 Codex 的差异化接入Claude Code 和 Codex 虽然都是命令行 AI 编程助手但它们的配置方式、认证机制、端点格式并不一样。Claude Code 更偏向于通过环境变量和配置文件来指定 API 端点与密钥Codex 则有自己的登录流程和 token 管理机制。openrig 的价值就在于把这些差异封装起来对外提供统一的“启动一个 agent”的接口。具体来说Claude Code 常见的配置项包括 API base URL、API key、模型名称、最大上下文长度等。Codex 则涉及 auth token、组织 ID、端点路径等。openrig 在内部为每个 agent 维护一个适配器把统一的 YAML 字段映射到各自需要的环境变量或配置文件。比如你在 YAML 里写provider: local-deepseekopenrig 会根据当前 agent 是 Claude Code 还是 Codex分别设置不同的变量名和端点路径。这里有一个容易踩的坑不同版本的 Claude Code 和 Codex 对环境变量的命名可能发生变化。openrig 的适配器需要跟随上游更新所以建议锁定版本不要盲目追最新。我在实际使用中会把每个 agent 的版本号也写进 YAML这样换机器时能复现完全一致的环境。2.3 tmux 在 openrig 中的角色tmux 是 openrig 的“会话层”。很多人用 tmux 只是为了防止 SSH 断连但 openrig 把 tmux 用成了多 agent 并行工作的调度台。你可以定义一个 session 叫ai-work里面开三个 window一个跑 Claude Code 做代码审查一个跑 Codex 做补全一个跑日志监控。openrig 可以根据 YAML 里的sessions配置自动创建这些 window并注入对应的环境变量。这样做的好处是你不需要每次手动开三个终端、cd 到不同目录、export 一堆变量。一条openrig up ai-work就能把整个工作环境拉起来。而且 tmux 的 session 可以 detach 和 reattach即使本地终端关了远程机器上的 agent 还在跑。对于需要长时间运行的任务比如让 Claude Code 扫描整个仓库这个特性非常实用。注意tmux 的 window 和 pane 布局在不同终端尺寸下可能错乱。建议在 YAML 里使用相对布局而不是绝对坐标openrig 通常会提供layout: even-horizontal或layout: tiled这类选项。2.4 本地模型与远程 API 的统一抽象热词里频繁出现“Claude Code 调用 LM Studio 的本地模型”“Codex 接入 DeepSeek”说明大家很关心如何把不同来源的模型统一接入。openrig 的设计思路是不管模型跑在本地还是远程只要它提供兼容的 HTTP 端点就把它抽象成一个provider。本地 LM Studio 通常暴露http://localhost:1234/v1DeepSeek 有官方兼容端点其他开源推理框架也大多支持 OpenAI 风格的接口。在 YAML 里你只需要定义 provider 的base_url、api_key、model三个核心字段openrig 会根据 agent 类型决定如何注入。对于本地模型api_key 通常可以随便填一个占位符但有些工具会校验非空所以不要留空。对于远程 API密钥建议通过环境变量引用而不是直接写在 YAML 里避免误提交到 Git。这里的关键点是端点路径的拼接。Claude Code 和 Codex 对/v1、/responses、/chat/completions这些路径的处理方式不同。openrig 的适配器需要知道当前 agent 期望的路径格式必要时做重写。热词里出现的 “cc switch local proxy failed while handling codex endpoint /responses” 就是典型的路径不匹配问题后面排查章节会详细讲。3. 核心细节解析与实操要点3.1 YAML 配置文件的结构设计一个可用的 openrig YAML 配置我建议至少包含以下顶层字段version: 1 providers: local-lmstudio: base_url: http://127.0.0.1:1234/v1 api_key: local-placeholder model: qwen2.5-coder-7b deepseek-remote: base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} model: deepseek-chat agents: claude: provider: deepseek-remote extra_env: CLAUDE_CODE_MAX_OUTPUT_TOKENS: 8192 codex: provider: local-lmstudio extra_env: CODEX_MODEL: qwen2.5-coder-7b sessions: ai-work: windows: - name: claude agent: claude cwd: ~/projects/main - name: codex agent: codex cwd: ~/projects/main - name: logs command: tail -f ~/.local/state/openrig/agent.log这个结构的设计逻辑是providers和agents解耦同一个 provider 可以被多个 agent 复用sessions和agents解耦同一个 agent 可以出现在多个 session 里。这样当你换模型供应商时只需要改 provider 的 base_url 和 model所有引用它的 agent 自动生效。version字段很重要openrig 在不同大版本之间可能有配置格式变化。写上版本号可以让工具在加载时做兼容性检查避免用旧格式跑新版本导致莫名其妙的问题。3.2 环境变量注入的优先级与陷阱openrig 在启动 agent 时会按照一定优先级注入环境变量。通常的顺序是系统环境变量 全局 YAML 的env 项目 YAML 的env agent 的extra_env session 的env。后面的覆盖前面的。这个设计让你可以在不同层级做覆盖但也容易踩坑。最常见的坑是你在 shell 里已经 export 了一个OPENAI_API_KEY但 YAML 里又定义了一个不同的值结果 agent 用了 YAML 里的而你以为是 shell 里的。排查这类问题时可以在 openrig 启动后打印最终生效的环境变量或者用openrig debug env agent这类命令查看。另一个坑是变量引用。YAML 里写${DEEPSEEK_API_KEY}时openrig 需要知道从哪里读取这个变量。如果 shell 里没有设置有些实现会报错有些会留空字符串。留空字符串更危险因为 agent 可能带着空密钥去请求然后返回一个模糊的认证失败。建议在 YAML 里对关键变量做非空校验或者至少在启动日志里明确提示。提示不要把真实密钥直接写进 YAML 并提交到版本控制。用${VAR}引用配合.env文件或系统密钥管理工具。openrig 通常支持从.env文件加载变量但要注意.env也要加入.gitignore。3.3 Claude Code 安装与配置的关键步骤Claude Code 的安装方式在不同平台上略有差异。常见做法是通过包管理器或安装脚本获取 CLI 二进制然后配置 API 端点和密钥。openrig 不会替代安装过程但它可以在安装完成后接管配置管理。安装完成后你需要确认几件事第一claude命令是否在 PATH 里第二版本号是否与 YAML 里声明的一致第三默认配置文件位置在哪里。Claude Code 通常会读取用户主目录下的某个配置目录openrig 在启动时会根据 YAML 生成临时配置或设置环境变量覆盖默认值。一个实操技巧是先用原生方式手动跑通一次 Claude Code确认账号、端点、模型都能正常工作然后再把这套配置迁移到 openrig 的 YAML 里。这样如果出问题你能快速判断是 openrig 的注入逻辑有问题还是上游工具本身有问题。我见过不少人一上来就全交给 openrig结果报错时完全不知道是哪一层出的问题。3.4 Codex 安装与登录的注意事项Codex 的安装和登录流程相对独立。它通常需要先通过 CLI 完成登录获取 auth token然后才能调用模型。openrig 可以管理 token 的存储位置和注入方式但不能代替你完成首次登录。热词里出现 “codex auth token is unavailable” 和 “codex 登录”说明 token 管理是高频问题。常见原因有几个token 过期、token 存储路径不对、环境变量没有正确传递、或者多台机器之间 token 没有同步。openrig 的做法通常是把 token 文件路径写进 YAML启动时检查文件是否存在且未过期如果过期则提示重新登录。另一个注意点是 Codex 的端点路径。有些兼容端点使用/responses而不是/chat/completions如果 openrig 的适配器没有正确重写路径就会报 “local proxy failed while handling codex endpoint /responses” 这类错误。解决方法是确认 provider 的 base_url 是否包含了正确的版本前缀以及 agent 适配器是否知道当前 Codex 版本期望的路径格式。3.5 tmux 会话布局的实操配置tmux 会话配置是 openrig 里最容易出效果、也最容易出问题的部分。一个实用的布局是左侧一个大 pane 跑主 agent右侧上下两个小 pane一个跑日志一个跑辅助命令。openrig 的 YAML 里可以用layout字段描述这种结构。实际操作中我建议先用 tmux 手动搭一次你想要的布局然后用tmux list-windows和tmux display-message -p查看具体的 pane 划分参数再把这些参数写进 YAML。这样比凭空想象布局要靠谱得多。另外tmux 的remain-on-exit选项建议打开这样 agent 崩溃时 pane 不会立刻关闭你能看到最后的错误信息。还有一个细节openrig 启动 session 时如果同名 session 已经存在是复用还是重建不同实现策略不同。我倾向于配置成“如果存在则 attach不存在则创建”避免误杀正在运行的任务。如果需要强制重建应该有一个显式的--force参数。4. 实操过程与核心环节实现4.1 环境准备与依赖安装在开始配置 openrig 之前你需要先准备好基础环境。以常见的 Linux 或 macOS 开发机为例核心依赖包括一个可用的 shellbash 或 zsh、tmux、Git、以及 Claude Code 和 Codex 的 CLI 本体。如果你打算接入本地模型还需要一个本地推理服务比如 LM Studio 或其他兼容 OpenAI 接口的运行时。安装顺序建议是先装 tmux 和 Git再装 Claude Code 和 Codex最后装 openrig。每装完一个都手动验证一下命令是否可用。比如tmux -V、claude --version、codex --version。这样能把问题隔离在单个组件里而不是等到 openrig 启动时一起爆发。openrig 本身的安装方式取决于它的发布形式。如果是 Go 或 Rust 写的二进制通常直接下载对应平台的可执行文件放到 PATH 即可如果是 Node 或 Python 写的可能需要包管理器。安装完成后运行openrig --version和openrig doctor做一次自检。doctor命令通常会检查依赖是否齐全、配置文件是否可解析、关键环境变量是否存在。注意如果你在 Windows 上使用建议通过 WSL 运行这套工具链。原生 Windows 下 tmux 不可用Claude Code 和 Codex 的某些行为也可能不一致。WSL 能提供接近 Linux 的体验减少兼容性问题。4.2 编写第一份 openrig YAML 配置第一份配置不要追求大而全先跑通一个 agent、一个 provider、一个 session。我建议从本地模型开始因为本地模型不依赖网络和远程密钥排查起来最简单。假设你用 LM Studio 在本地启动了推理服务监听http://127.0.0.1:1234加载了一个代码模型。那么最小配置可以这样写version: 1 providers: local: base_url: http://127.0.0.1:1234/v1 api_key: local model: your-local-model-name agents: claude: provider: local sessions: test: windows: - name: claude agent: claude保存到~/.config/openrig/base.yaml然后运行openrig up test。如果一切正常你会进入一个 tmux session里面有一个 window 跑着 Claude Code并且已经指向本地模型。这时候你可以问它一个简单的代码问题看是否能正常返回。如果报错先看 openrig 的启动日志确认它注入的环境变量是什么再手动在 shell 里 export 同样的变量直接跑claude命令对比行为。这一步能快速定位是 openrig 的问题还是上游工具的问题。4.3 接入远程 API 与密钥管理本地跑通后再接入远程 API。以 DeepSeek 为例你需要在环境里设置DEEPSEEK_API_KEY然后在 YAML 里新增一个 providerproviders: deepseek: base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} model: deepseek-chat然后把 agent 的 provider 改成deepseek。重启 session 后Claude Code 或 Codex 就会通过 DeepSeek 的端点来请求模型。这里的关键是密钥不要硬编码。用${DEEPSEEK_API_KEY}引用并在 shell 的配置文件里 export或者用.env文件加载。如果你在多台机器上工作建议用统一的密钥管理方式比如系统钥匙串或加密的 dotfiles 仓库。openrig 本身不负责密钥加密它只负责读取和注入。一个实操心得是为不同的 agent 使用不同的密钥或不同的 provider 别名。比如deepseek-for-claude和deepseek-for-codex即使它们指向同一个端点。这样当某个 agent 出问题时你能快速切换而不影响另一个。4.4 多 agent 并行会话的搭建当你需要同时跑 Claude Code 和 Codex 时session 配置就派上用场了。一个实用的双 agent 布局sessions: dual: windows: - name: claude agent: claude cwd: ~/projects/app - name: codex agent: codex cwd: ~/projects/app - name: shell command: bash cwd: ~/projects/app启动openrig up dual后你会得到三个 window。用Ctrl-b n在 window 之间切换。Claude Code 可以用来做整体架构审查和复杂重构Codex 可以用来做快速补全和单元测试生成。两者共享同一个项目目录但各自有独立的会话状态。需要注意的是两个 agent 同时修改同一个文件可能冲突。建议在分工上明确一个负责读和审查一个负责写和补全或者在不同的 Git 分支上工作。openrig 不解决并发编辑冲突这是工作流层面要设计的事情。4.5 日志、监控与状态查看openrig 运行过程中日志是排查问题的第一手资料。建议在 session 里专门开一个 window 跑日志监控比如tail -f ~/.local/state/openrig/agent.log。日志里应该包含启动时间、加载的配置文件、生效的 provider、注入的环境变量密钥要脱敏、agent 的退出码。如果 openrig 支持状态命令比如openrig status可以查看当前有哪些 session 在跑、每个 session 里有哪些 agent、它们分别用的什么 provider。这个在多个项目并行时特别有用避免你忘了某个 session 还在跑占着本地模型或者消耗远程额度。提示日志文件建议做轮转避免长期运行后占满磁盘。可以用系统的 logrotate或者在 openrig 配置里设置最大日志大小和保留份数。5. 常见问题与排查技巧实录5.1 端点路径不匹配导致的代理失败热词里 “cc switch local proxy failed while handling codex endpoint /responses” 是一个典型问题。它的根源通常是Codex 期望的请求路径是/responses但本地代理或 provider 的 base_url 配置成了/v1导致最终请求路径变成/v1/responses或者/responses/v1服务端不认识。排查步骤第一确认 provider 的 base_url 是否包含了正确的版本前缀第二确认 agent 适配器是否对路径做了重写第三用curl手动请求目标端点看服务端实际接受什么路径。比如curl -v http://127.0.0.1:1234/v1/responses \ -H Content-Type: application/json \ -d {model:your-model,input:hello}如果返回 404说明路径不对如果返回 401说明路径对了但认证有问题如果返回 200说明路径和认证都没问题那问题就在 openrig 的注入逻辑上。5.2 认证失败与 token 不可用“codex auth token is unavailable” 通常意味着 Codex 找不到有效的 token。可能原因包括token 文件不存在、token 过期、环境变量没有传递、或者 token 存储路径与 Codex 期望的不一致。解决思路先手动运行codex的登录命令确认能正常登录并生成 token。然后找到 token 文件的实际路径把它写进 openrig 的 YAML。如果 Codex 支持通过环境变量传递 token优先用环境变量因为这样 openrig 的注入更直接。注意不要在有日志输出的地方打印完整 token只打印前几位和后几位用于确认。5.3 本地模型连接失败本地模型连接失败常见于几种情况推理服务没有启动、端口不对、模型名称不对、或者防火墙拦截。先用curl确认服务可达再确认模型名称与 LM Studio 里加载的一致。有些推理服务要求model字段必须精确匹配差一个字符都会报错。另一个坑是api_key留空。虽然本地服务通常不校验密钥但某些客户端库会检查非空。填一个占位符比如local就能绕过。如果 openrig 的 YAML 里写的是${LOCAL_API_KEY}而环境变量没设置最终会变成空字符串也可能触发这个问题。5.4 tmux 会话异常与恢复tmux 会话异常通常表现为session 创建失败、window 数量不对、pane 布局错乱、或者 agent 启动后立刻退出。排查时先用tmux ls看 session 是否存在再用tmux attach -t name进去看具体状态。如果 agent 启动后立刻退出多半是环境变量或配置有问题。可以在 session 里手动跑一次 agent 命令看报错信息。如果 pane 布局错乱检查 YAML 里的 layout 参数是否与当前终端尺寸兼容。必要时先用简单布局跑通再逐步调整。5.5 常见问题速查表问题现象可能原因排查方法解决方向代理报错 /responses端点路径不匹配curl 手动请求目标路径修正 base_url 或适配器重写规则auth token unavailabletoken 缺失或过期检查 token 文件和环境变量重新登录或修正注入路径本地模型连接失败服务未启动或端口错误curl 测试本地端点启动服务或修正 base_urlagent 启动即退出环境变量或配置错误手动运行 agent 命令检查 YAML 和 shell 环境tmux 布局错乱layout 参数不兼容查看当前终端尺寸改用相对布局或简化结构密钥未生效变量引用未解析打印最终环境变量检查 .env 和 export 顺序5.6 独家避坑经验第一个经验永远先手动跑通再交给 openrig。openrig 是一层封装封装会隐藏细节也会隐藏错误。手动跑通意味着你知道正确的命令、正确的环境变量、正确的端点这样 openrig 出问题时你能快速对比。第二个经验YAML 里的列表合并要小心。很多配置合并工具对列表是替换而不是追加。如果你在项目级 YAML 里写了一个windows列表它可能会完全覆盖全局的windows列表而不是追加。需要追加时用显式的合并键或者分开命名。第三个经验版本锁定。Claude Code、Codex、openrig 本身都在快速迭代今天能用的配置明天可能因为上游改名而失效。在生产环境或主力工作流里锁定版本号升级前先在实验环境验证。第四个经验日志脱敏。openrig 的日志里可能包含环境变量如果直接打印密钥会泄露。确保日志组件对KEY、TOKEN、SECRET这类变量名做脱敏处理只显示前后几位。6. 进阶用法与工作流扩展6.1 多项目配置继承与覆盖当你同时维护多个项目时配置继承能大幅减少重复。做法是全局 YAML 定义通用 provider 和 agent 模板项目级 YAML 只写差异部分。比如全局定义deepseekprovider项目 A 覆盖 model 为deepseek-chat项目 B 覆盖 model 为deepseek-coder。openrig 的合并策略需要明确标量覆盖映射深度合并列表替换。理解这个规则后你就能设计出清晰的配置层级。我通常把项目级配置控制在 20 行以内只写真正不同的部分其余全部继承全局。6.2 结合 Git 做配置版本管理把 openrig 的 YAML 配置纳入 Git 管理能带来几个好处配置变更可追溯、多机器同步方便、出问题能回滚。但要注意密钥不能进 Git。做法是YAML 里只写${VAR}引用真实密钥放在.env文件或系统密钥管理里.env加入.gitignore。如果团队多人使用可以维护一个共享的配置仓库每个人用自己的.env覆盖密钥。这样 provider 定义、agent 参数、session 布局都能统一减少“我这里能跑你那里不能跑”的问题。6.3 与编辑器和工作流的衔接openrig 管的是终端里的 agent 运行环境但你的日常工作可能还在 VS Code 或其他编辑器里。一个实用的衔接方式是在 VS Code 的集成终端里 attach 到 openrig 创建的 tmux session这样编辑器里就能直接看到 agent 的输出同时保留 tmux 的会话管理能力。另一个方式是用 openrig 启动 agent 后把 agent 的输出日志写到固定文件然后在编辑器里用 tail 插件实时查看。这样你不需要切换窗口就能看到 Claude Code 或 Codex 的实时反馈。6.4 资源占用与性能调优同时跑多个 agent 和本地模型时资源占用会明显上升。本地模型吃 GPU 和内存多个 agent 吃 CPU 和网络。建议根据机器配置限制并行数量。比如 16GB 内存的机器本地模型加两个 agent 可能就到极限了。openrig 层面可以做的优化包括延迟启动非关键 agent、复用同一个 provider 连接、限制日志写入频率。如果本地模型响应慢可以考虑换更小的量化模型或者把非关键任务切到远程 API。7. 我个人的使用体会与几个实用建议我用 openrig 管理 Claude Code 和 Codex 的工作流已经有一段时间了最大的感受是它把“配置”从一件每次都要重新想的事情变成了一件写一次就能反复用的事情。以前换机器要折腾半天现在把 YAML 和.env同步过去基本就能复现。几个我觉得特别值得做的习惯第一给每个 provider 起一个有意义的名字不要用provider1、provider2用local-qwen、deepseek-chat这种一看就懂的。第二session 名字用项目名或用途名比如app-review、lib-refactor不要用test1、test2。第三定期清理不再使用的 provider 和 session 配置避免 YAML 越来越臃肿。还有一个小心得openrig 的配置文件本身也值得写注释。YAML 支持#注释把你为什么选这个模型、为什么用这个端点、这个参数是干什么的简单写一句。过几个月回头看你会感谢自己。最后再分享一个排查技巧当 openrig 启动失败但报错信息很模糊时用openrig --dry-run或者类似的调试模式让它只打印将要执行的操作和将要注入的环境变量而不真正启动 agent。这样你能在不产生副作用的情况下看清 openrig 到底做了什么。这个技巧帮我省了很多次反复启动和退出的时间。