openrig 配置编排：Claude Code 与 Codex 本地模型接入实战

1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件项目毕竟“rig”在英文里常指设备支架或矿机架。但如果你最近在折腾 Claude Code、Codex 这类命令行 AI 编程工具大概率已经在某个 issue 或讨论帖里见过它。openrig 本质上是一个面向 AI 编程助手的本地配置编排层它把散落在各处的 YAML 配置、终端会话管理、模型接入参数整合成一套可复用的工程化方案。我最初接触 openrig 是因为一个很具体的痛点手头同时用着 Claude Code 和 Codex 两个 CLI 工具前者接的是本地 LM Studio 跑的模型后者偶尔切到 DeepSeek 的 API 做对比测试。每次换项目目录都要重新检查配置文件路径、环境变量、tmux 会话名稍不留神就出现“cc switch local proxy failed while handling codex endpoint /responses”这类报错。openrig 的出现让我意识到配置管理本身就是一门需要认真对待的工程而不是随手改改.env就能糊弄过去的事。这个项目适合三类人一是刚接触 Claude Code 或 Codex、被安装和配置流程搞得头大的新手二是同时维护多个 AI 编程工具、需要统一管理配置的进阶用户三是想把 AI 助手接入自己本地模型或私有 API、对数据流向有要求的开发者。它不解决模型能力问题也不替代工具本身它解决的是**“工具太多、配置太乱、切换太烦”**这个看似琐碎但极其消耗精力的工程问题。提示openrig 不是官方项目它更像是一个社区驱动的配置模板集合所以不同版本之间可能有差异建议以你实际拉取到的仓库内容为准。2. 核心设计思路为什么是 YAML tmux 这套组合2.1 配置即代码YAML 承担的角色openrig 选择 YAML 作为配置载体这个决定背后有很实际的考量。Claude Code 和 Codex 本身都支持通过配置文件或环境变量来指定模型端点、API Key、超时时间等参数但这些配置分散在不同位置有的在~/.claude/下有的在项目根目录的.codex/里还有的依赖 shell 环境变量。YAML 的好处是结构清晰、层级分明、支持注释你可以把多个工具的配置写在一个文件里用不同的顶层键区分。举个例子一个典型的 openrig 配置片段长这样claude: model: local-model endpoint: http://127.0.0.1:1234/v1 max_tokens: 8192 timeout: 120 codex: provider: deepseek api_base: https://api.deepseek.com/v1 model: deepseek-chat temperature: 0.3 tmux: session_name: ai-rig windows: - name: claude command: claude - name: codex command: codex这种写法的好处是你不需要记住每个工具的具体参数名openrig 的启动脚本会读取 YAML 并转换成对应工具能识别的格式。我试过手动管理这些配置结果就是每次换模型都要翻文档查参数名而 YAML 文件本身就是一个可读性极强的备忘录。2.2 tmux 作为会话容器不只是为了分屏很多人第一次看到 openrig 用 tmux 管理会话会觉得这只是为了分屏好看。实际上 tmux 在这里承担了更重要的角色会话持久化。Claude Code 和 Codex 都是长时间运行的任务一次代码生成可能持续几分钟甚至更久。如果你用普通终端SSH 断线或不小心关掉窗口任务就中断了。tmux 会话独立于终端窗口存在你可以随时 detach 再 attach 回来。openrig 的 tmux 配置通常会把不同工具放在不同 window 里比如 window 0 跑 Claude Codewindow 1 跑 Codexwindow 2 留一个 shell 用来查看日志或手动测试 API。这种布局不是随意设计的它对应的是实际工作流中的角色分离一个窗口负责代码生成一个窗口负责代码审查或对比第三个窗口处理杂项。我自己的习惯是在 window 2 里跑一个watch命令监控本地模型的显存占用这样切换模型时能立刻看到资源变化。注意tmux 的 session 名不要用中文或特殊字符某些终端模拟器在 attach 时会出现乱码。建议用ai-rig、dev这类纯英文短名。2.3 为什么不用 Docker 或 systemd有人可能会问既然要管理配置和进程为什么不用 Docker Compose 或 systemd user service我的理解是openrig 的目标用户是开发者本机环境而不是服务器部署。Docker 会引入额外的文件挂载和网络配置复杂度systemd 则对 Windows 用户不友好。tmux YAML 的组合几乎零依赖Linux、macOS 甚至 Windows 的 WSL 里都能跑这才是它被社区接受的原因。3. 实操落地从安装到跑通第一个会话3.1 前置准备Claude Code 与 Codex 的安装确认在配置 openrig 之前你得先确保 Claude Code 和 Codex 本身能正常运行。Claude Code 的安装方式取决于你的系统常见的是通过 npm 全局安装或下载独立二进制包。Codex 类似官方提供了 CLI 版本和桌面版两种形态。我建议先用最简命令测试claude --version codex --version如果这两个命令有一个报“command not found”那 openrig 配置得再完美也没用。Windows 用户如果遇到路径问题检查一下 npm 全局 bin 目录是否在 PATH 里。另外Claude Code 在某些区域可能提示“your organization has disabled claude subscription access”这是账号权限问题需要先解决账号层面的访问资格。3.2 获取 openrig 配置模板并理解目录结构openrig 通常以 Git 仓库形式分发克隆下来后你会看到类似这样的结构openrig/ ├── configs/ │ ├── claude.yaml │ ├── codex.yaml │ └── tmux.yaml ├── scripts/ │ ├── start.sh │ └── reload.sh └── README.mdconfigs/目录放的是各工具的配置片段scripts/里是启动和重载脚本。我建议不要直接修改仓库里的文件而是复制一份到自己的项目目录或~/.config/openrig/下这样仓库更新时不会冲突。这个习惯是从管理 dotfiles 的经验里来的永远把个人配置和上游模板分开。3.3 编写你的第一个 openrig YAML假设你要配置一个最简场景Claude Code 接本地 LM StudioCodex 接 DeepSeek两者在同一个 tmux 会话里各占一个 window。YAML 可以这样写version: 1 claude: env: ANTHROPIC_BASE_URL: http://127.0.0.1:1234/v1 ANTHROPIC_API_KEY: lm-studio args: - --model - local-model codex: env: OPENAI_BASE_URL: https://api.deepseek.com/v1 OPENAI_API_KEY: sk-your-deepseek-key args: - --model - deepseek-chat tmux: session: openrig windows: - name: claude cmd: claude - name: codex cmd: codex这里有几个细节值得展开。ANTHROPIC_BASE_URL指向本地 LM Studio 的 OpenAI 兼容端点LM Studio 默认监听 1234 端口路径是/v1。API Key 随便填一个非空字符串即可本地模型通常不校验。Codex 那边用的是 DeepSeek 的 OpenAI 兼容接口所以环境变量名是OPENAI_BASE_URL和OPENAI_API_KEY而不是 Codex 特有的变量名。这种通过环境变量注入配置的方式比修改工具本身的配置文件更灵活也更容易在不同项目间切换。3.4 启动脚本与 tmux 会话初始化openrig 的启动脚本核心逻辑通常是这样的#!/usr/bin/env bash set -euo pipefail CONFIG_FILE${1:-$HOME/.config/openrig/config.yaml} SESSION$(yq .tmux.session $CONFIG_FILE) tmux has-session -t $SESSION 2/dev/null tmux kill-session -t $SESSION tmux new-session -d -s $SESSION -n $(yq .tmux.windows[0].name $CONFIG_FILE) # ... 后续 window 创建和环境变量注入这里用到了yq这个工具来解析 YAML。如果你没装yq可以用 Python 的pyyaml替代但yq在 shell 脚本里更顺手。脚本先检查同名 session 是否存在存在就杀掉重建避免残留状态导致奇怪问题。然后创建第一个 window后续 window 通过tmux new-window追加。环境变量的注入方式是在每个 window 的启动命令前加上env VARvalue或者用tmux send-keys先 export 再执行命令。提示set -euo pipefail这三件套建议所有 shell 脚本都加上能提前暴露未定义变量和管道错误省去大量调试时间。3.5 验证配置是否生效启动会话后用tmux attach -t openrig进入然后分别在两个 window 里执行一次简单请求。Claude Code 那边可以输入一个短提示词观察是否返回本地模型的输出Codex 那边同样。如果 Claude Code 报连接错误先用curl直接测端点curl http://127.0.0.1:1234/v1/models这个命令能列出 LM Studio 当前加载的模型。如果返回空列表或连接拒绝说明 LM Studio 的服务没开或者端口不对。Codex 那边如果报认证失败检查 DeepSeek 的 API Key 是否有效、余额是否充足。先排除工具本身的问题再怀疑 openrig 配置这个排查顺序能节省大量时间。4. 进阶配置多模型切换与常见报错处理4.1 用 YAML 锚点减少重复配置当你需要管理多个模型端点时YAML 的锚点anchor和引用alias能大幅减少重复。比如defaults: defaults timeout: 120 max_tokens: 8192 claude_local: : *defaults endpoint: http://127.0.0.1:1234/v1 claude_remote: : *defaults endpoint: https://api.anthropic.comdefaults定义锚点: *defaults把默认值合并进来。这样改超时时间只需要改一处。我见过有人把每个模型的配置完整写一遍结果改一个参数要改五六个地方很容易漏。YAML 的复用机制就是为这种场景设计的不用白不用。4.2 处理“cc switch local proxy failed”类错误这个报错通常出现在 Claude Code 尝试通过本地代理转发请求到 Codex 端点时。根本原因往往是代理配置和实际端点不匹配Claude Code 以为自己在跟 Anthropic 官方 API 通信但环境变量把它指向了一个 OpenAI 兼容端点协议差异导致/responses路径解析失败。解决办法是确认ANTHROPIC_BASE_URL指向的端点确实支持 Anthropic 的消息格式或者改用支持双协议的网关做转换。排查时可以用curl -v看实际请求发到了哪个 URL、返回了什么状态码。如果是 404说明路径不对如果是 401说明认证有问题如果是 502说明代理后面的服务没起来。状态码是最诚实的线索比看日志猜要快得多。4.3 Codex 认证令牌不可用的处理“codex auth token is unavailable”这个提示一般意味着 Codex 没有找到有效的认证信息。Codex 的认证方式有几种环境变量、配置文件、或者交互式登录。如果你用的是 API 方式确保OPENAI_API_KEY已经 export 到当前 shell并且 tmux 会话启动时继承了这个变量。tmux 有个坑它默认不会继承启动它的 shell 的所有环境变量特别是通过tmux new-session -d后台创建时。解决办法是在启动脚本里显式传递或者在 tmux 配置里用set-environment设置。我自己的做法是在~/.tmux.conf里加一行set-option -g update-environment OPENAI_API_KEY ANTHROPIC_API_KEY这样每次 attach 时 tmux 会从当前环境更新这些变量。这个技巧对经常切换 API Key 的场景特别有用。4.4 常见问题速查表现象可能原因排查动作Claude Code 连接超时本地模型服务未启动curl测试端点连通性Codex 返回 401API Key 无效或未传递检查环境变量是否在 tmux 内可见tmux 会话无法 attachsession 名冲突或权限问题tmux ls查看现有会话YAML 解析报错缩进用了 Tab 或冒号后缺空格用yq或在线校验器验证模型输出乱码端点协议不匹配确认用的是 OpenAI 还是 Anthropic 格式这张表是我在实际使用中逐步积累的每次遇到新问题就加一行。维护自己的排查清单比任何文档都管用因为你的环境只有你自己最清楚。5. 把 openrig 融入日常工作流的一些经验5.1 项目级配置与全局配置的取舍openrig 支持在项目目录放一个.openrig.yaml覆盖全局配置。这个设计很实用全局配置里放通用的 API Key 和默认模型项目级配置里只写这个项目特有的参数比如某个项目需要更长的超时时间或者不同的模型。但要注意优先级顺序通常是项目级 用户级 系统级。如果你发现改了项目配置没生效先确认加载顺序是否符合预期。我一般会在项目根目录放一个极简的.openrig.yaml只写model和timeout两个字段其余继承全局。这样既保持了项目间的差异又不会让配置文件变得臃肿。5.2 与 VS Code 的配合虽然 openrig 主打 CLI 体验但很多人还是在 VS Code 里写代码。VS Code 的集成终端可以直接 attach 到 tmux 会话这样你在编辑器里就能看到 Claude Code 和 Codex 的输出。具体做法是在 VS Code 的settings.json里配置终端 profile让它启动时自动执行tmux attach -t openrig。这样打开 VS Code 终端就等于进入了 openrig 环境省去手动切换的步骤。另外VS Code 的 Claude Code 扩展和 CLI 版本可以共存但要注意它们可能读取不同的配置文件。如果你在扩展里配置了模型CLI 那边不一定同步。以 CLI 配置为准扩展只当作一个便捷入口。5.3 定期清理与配置版本化openrig 的配置文件建议纳入 Git 管理但 API Key 不要明文提交。可以用envsubst或者sops这类工具做变量替换把敏感信息放在.env文件里并加入.gitignore。我见过有人直接把 Key 写进 YAML 然后推到公开仓库结果被扫到后产生意外费用。配置版本化的前提是敏感信息剥离这个原则适用于所有基础设施即代码的场景。清理方面tmux 会话如果长期不关会积累很多僵尸 session建议在启动脚本里加一个清理逻辑把超过一定时间未活动的 session 杀掉。或者养成习惯每天工作结束时tmux kill-server一次第二天重新启动。这个动作花不了几秒钟但能避免很多“为什么我的配置没生效”的困惑——因为很可能你 attach 到了一个旧 session。5.4 关于模型选择的个人体会最后说一点关于模型选择的经验。openrig 让你能方便地在本地模型和远程 API 之间切换但不要为了切换而切换。本地模型胜在隐私和零成本适合日常代码补全和简单重构远程 API 胜在能力强适合复杂逻辑设计和疑难 bug 排查。我的习惯是默认用本地模型处理 80% 的日常任务遇到卡壳的地方再切到远程。openrig 的 YAML 配置让这个切换只需要改一个字段但真正重要的是建立自己的判断标准什么任务值得用更强的模型什么任务本地模型就够用。这个判断力比任何配置技巧都值钱。