尧图网页设计 
1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 在英文里就是“装配、机架”的意思。但翻了一圈社区讨论和仓库结构之后才明白它其实是一个围绕 AI 编码助手做本地配置编排的工具思路——核心目标是把 Claude Code、Codex 这类命令行编码代理的模型接入、代理转发、环境变量、YAML 配置统一管起来让你在不同模型供应商之间切换时不用每次手改一堆文件。说白了openrig 解决的是一个很具体的痛点现在用 Claude Code 或者 Codex CLI 的人越来越多但每个人手里的模型来源不一样。有人用官方订阅有人接第三方 API有人想调用 LM Studio 跑的本地模型还有人要在 DeepSeek、Qwen、GLM 之间来回切。每换一次就得改配置文件、改环境变量、重启终端稍不注意就报cc switch local proxy failed while handling codex endpoint /responses这种错。openrig 想做的就是把这套东西抽象成一份 YAML用一个命令完成切换。它适合谁三类人最值得看。第一类是刚接触 Claude Code 或 Codex、还在被安装和配置折磨的新手第二类是同时用多个模型供应商、需要频繁切换的老手第三类是想把团队里所有人的编码代理配置统一管理的技术负责人。哪怕你只是想搞清楚codex接入deepseek到底怎么配这篇里的思路也能直接抄。我先把话说在前面openrig 本身不是一个官方大厂产品它更像是一个社区里逐渐成型的配置约定和配套脚本集合。所以下面讲的内容一部分来自仓库里能看到的实现一部分是我基于多年折腾这类工具的经验做的合理补全我会明确标出哪些是推测。2. 为什么需要 openrig 这层编排2.1 编码代理的配置之痛Claude Code 和 Codex CLI 这类工具本质上是一个“壳”——它们负责把你的自然语言指令转成对模型的调用再根据模型返回的内容决定要不要执行终端命令、读写文件。真正干活的是背后的模型。问题就出在这个“背后”上。官方默认配置通常只指向自家服务。但现实里很多人因为各种原因需要换模型可能是想省钱可能是某个模型在特定任务上更强也可能是公司要求数据不出内网。这时候你就得动配置。Claude Code 读的是环境变量和它自己的 settings 文件Codex 读的是~/.codex/config.toml或者类似的配置两者格式不一样、字段名不一样、连代理的路径规则都不一样。我见过太多人在这上面翻车。最典型的就是cc switch local proxy failed while handling codex endpoint /responses这个报错——它出现的原因通常是本地代理把请求转发到了错误的端点Codex 期望的是/responses路径但代理配置里写成了别的。这种错不会告诉你具体哪一行配错了只会甩一个 failed 给你新手能卡一整天。2.2 openrig 的核心思路一份 YAML 管所有openrig 的思路其实很朴素既然配置散落在各处那就用一个统一的 YAML 文件描述“我要用哪个模型、走哪个端点、用什么密钥、代理怎么转发”然后由工具读取这份 YAML自动生成 Claude Code 和 Codex 各自需要的配置。这个思路的价值在于单一事实来源。你只需要维护一份 YAML切换模型就是改一个字段或者跑一个命令。团队协作时这份 YAML 可以进版本库新人拉下来就能用不用再口口相传“你要先改这个再改那个”。为什么选 YAML 而不是 JSON 或 TOML因为 YAML 对人多友好——支持注释、层级清晰、不用纠结逗号和引号。你在 YAML 里可以写# 这是给 Codex 用的端点JSON 里就不行。对于配置文件这种需要人反复看反复改的场景可读性比机器解析效率重要得多。2.3 和直接改配置相比多这一层值不值有人会问我就用一个模型直接改配置不就完了何必多一层这个问题问得好。如果你确实只用一个模型、一年不换那 openrig 对你价值不大。但只要满足下面任意一条这层编排就值你有两个以上模型来源需要按任务切换你在多个项目间工作每个项目想用不同模型你要把配置分享给同事或写进文档你经常忘记上次改了什么导致配置越来越乱我自己的情况是同时用官方订阅和一个第三方端点还要偶尔切到本地 LM Studio 做离线测试。没有统一管理之前我的.zshrc里堆了一堆注释掉的 export每次切换靠手动取消注释出错率极高。有了 YAML 编排之后切换变成一条命令心里踏实多了。3. 环境准备Node.js 和 YAML 这两块地基3.1 Node.js 安装别踩版本坑openrig 这类工具基本都是 Node.js 生态的因为 Claude Code 和 Codex CLI 本身就是 npm 包。所以第一步是把 Node.js 装对。新手最容易犯的错是去官网随手下一个最新版。我见过有人装了个奇数版本比如 v21、v23然后遇到各种奇怪的兼容问题。生产环境请认准 LTS 版本也就是偶数版本号比如 v20、v22。LTS 意味着长期支持社区测试充分第三方库兼容性好。安装方式按系统分Windows去 Node.js 官网下载 LTS 的.msi安装包一路下一步即可。装完打开 PowerShell 输入node -v和npm -v验证。macOS推荐用nvm管理不要直接下 pkg。命令是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash然后nvm install --lts。Ubuntu/Debian同样推荐 nvm或者用 NodeSource 的源。直接apt install nodejs往往装到很老的版本。注意如果你看到error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这种报错说明你指定的版本号根本不存在或者 nvm 的远程列表没更新。先跑nvm ls-remote --lts看看实际有哪些版本别硬编一个号。装完之后建议把 npm 的源配一下国内访问官方源有时候很慢。但这里我不具体推荐某个镜像你自己按网络情况选配完跑npm config get registry确认。3.2 YAML 是什么为什么配置文件都用它YAML 全称是 “YAML Aint Markup Language”一种专门用来写配置的数据格式。它的核心特点是用缩进表示层级用冒号表示键值对用短横线表示列表项。举个最直观的例子。同样一份配置JSON 长这样{ models: { default: claude, providers: [ {name: official, endpoint: https://api.example.com} ] } }YAML 长这样models: default: claude providers: - name: official endpoint: https://api.example.com看出区别了吗YAML 没有大括号、没有引号大多数情况、没有逗号靠缩进表达从属关系。人读起来清爽很多改起来也不容易漏逗号。但 YAML 有个大坑缩进必须用空格绝对不能用 Tab。这是新手最常见的错误一个 Tab 混进去整个文件解析失败报错还特别含糊。我的习惯是把编辑器设成“Tab 键插入 2 个空格”从源头上杜绝。另外 YAML 对冒号后面的空格很敏感。key:value是错的必须key: value。这个细节坑过无数人。3.3 验证你的环境是否就绪装完 Node.js、理解了 YAML 之后跑几个命令确认环境没问题node -v # 应输出 v20.x 或 v22.x npm -v # 应输出对应版本 npx --version # 确认 npx 可用如果node -v报 command not found说明 PATH 没配好。Windows 上重开一个终端试试macOS/Linux 上检查~/.zshrc或~/.bashrc里有没有 nvm 的初始化脚本。4. openrig 的 YAML 配置结构拆解4.1 一份典型配置长什么样基于社区里流传的用法和这类工具的通用设计openrig 的配置文件大概会放在项目根目录或者用户主目录下名字可能是openrig.yaml或.openrig/config.yaml。下面是我根据常见实践整理的一份结构示例字段名是合理推测你以实际仓库为准version: 1 defaults: provider: official model: claude-sonnet providers: official: type: anthropic endpoint: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY deepseek: type: openai-compatible endpoint: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY models: - deepseek-chat - deepseek-coder local: type: openai-compatible endpoint: http://localhost:1234/v1 api_key_env: LOCAL_API_KEY models: - local-model targets: claude-code: provider: official model: claude-sonnet codex: provider: deepseek model: deepseek-coder这份配置想表达的是定义三个供应商官方、DeepSeek、本地然后分别指定 Claude Code 用官方、Codex 用 DeepSeek。切换的时候只改targets下面的字段就行。4.2 关键字段逐个说清楚version配置格式版本号。工具升级后格式可能变有这个字段就能做兼容处理。别省。defaults兜底配置。当某个 target 没指定 provider 时用这里的。providers核心中的核心。每个供应商要写清楚四件事type协议类型。Anthropic 系和 OpenAI 兼容系是两大主流。DeepSeek、Qwen、GLM、LM Studio 大多走 OpenAI 兼容协议所以 type 写openai-compatible。endpointAPI 地址。注意有的要带/v1有的不带这个必须查对应供应商的文档写错了就是 404。api_key_env密钥从哪个环境变量读。不要把密钥明文写进 YAML这是铁律。YAML 可能进版本库明文密钥等于泄露。models这个供应商支持哪些模型名。写错模型名会报model is not supported。targets把供应商和具体工具绑定。Claude Code 和 Codex 各一条互不干扰。4.3 密钥管理的正确姿势上面提到密钥走环境变量这里展开说。正确做法是在 shell 的配置文件里 exportexport ANTHROPIC_API_KEYsk-xxxx export DEEPSEEK_API_KEYsk-yyyy export LOCAL_API_KEYnot-needed然后 YAML 里只写变量名。这样 YAML 可以安全地进 git密钥留在本地。本地模型比如 LM Studio通常不校验密钥但很多 OpenAI 兼容客户端要求这个字段非空所以随便填一个占位符就行比如not-needed。提示如果你在团队里共享配置环境变量名要统一约定好否则别人拉下来跑不起来。建议在 README 里列一张表写清楚每个变量对应哪个供应商。5. 实操从零跑通 openrig 配置流程5.1 安装 Claude Code 和 Codex CLIopenrig 是编排层底层工具得先装好。Claude Code 和 Codex CLI 都是 npm 包安装命令类似npm install -g anthropic-ai/claude-code npm install -g openai/codex装完验证claude --version codex --version如果提示 command not found检查 npm 的全局 bin 目录在不在 PATH 里。npm config get prefix能看到全局目录把它加到 PATH。关于claude code安装和codex安装网上教程很多但坑也不少。最常见的是权限问题——Linux/macOS 上全局安装可能需要 sudo但用 sudo 装又会导致后续权限混乱。推荐用 nvm 管理 Node这样全局包都装在用户目录下不需要 sudo。5.2 编写你的第一份 openrig.yaml假设你已经装好了两个 CLI现在写配置。我建议从最小可用配置开始先跑通一个供应商再逐步加。第一步只配官方version: 1 defaults: provider: official model: claude-sonnet providers: official: type: anthropic endpoint: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY targets: claude-code: provider: official model: claude-sonnet codex: provider: official model: claude-sonnet第二步export 密钥export ANTHROPIC_API_KEY你的密钥第三步跑 openrig 的应用命令具体命令名以仓库为准可能是openrig apply或openrig sync。它会读取 YAML生成 Claude Code 和 Codex 各自的配置文件。5.3 接入第三方模型以 DeepSeek 为例官方跑通之后加第三方。这里以 DeepSeek 为例因为codex接入deepseek是搜索热词问的人多。在 providers 里加一段deepseek: type: openai-compatible endpoint: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY models: - deepseek-chat - deepseek-coder然后把 codex 的 target 改成 deepseektargets: codex: provider: deepseek model: deepseek-coderexport 密钥重新 apply。这时候 Codex 就会走 DeepSeek 的端点。这里有个关键点Codex 期望的端点和 Claude Code 不一样。Codex 用的是/responses路径而很多 OpenAI 兼容服务只提供/chat/completions。这就是cc switch local proxy failed while handling codex endpoint /responses报错的根源——代理把请求发到了 Codex 不认识的路径或者 Codex 发的路径代理不认。解决办法是在 openrig 里配置路径重写规则或者用一个中间代理做转换。如果 openrig 支持path_rewrite之类的字段就写清楚把/responses映射到/chat/completions。如果不支持就得在供应商配置里指定完整的 base URL让工具自己拼对路径。5.4 接入本地模型LM Studio 场景claude code 调用lmstudio的本地模型也是高频需求。LM Studio 启动后会在本地开一个 OpenAI 兼容服务默认端口 1234。配置local: type: openai-compatible endpoint: http://localhost:1234/v1 api_key_env: LOCAL_API_KEY models: - 你加载的模型名模型名要和你 LM Studio 里加载的完全一致大小写都不能错。本地模型的好处是数据不出机器适合处理敏感内容坏处是能力通常不如云端大模型复杂任务容易翻车。注意本地模型的上下文窗口往往比云端小很多。如果你让 Claude Code 读一个大项目本地模型可能直接爆上下文。用之前先确认模型的 context length。6. 常见报错与排查速查6.1 报错速查表报错信息可能原因排查方向cc switch local proxy failed while handling codex endpoint /responses代理路径不匹配检查 endpoint 是否支持/responses或配路径重写model is not supported模型名写错或供应商不支持核对 models 列表和实际模型名your organization has disabled claude subscription access组织策略限制换 API 密钥方式或联系管理员error installing ... not yet released版本号不存在用nvm ls-remote查实际版本401 Unauthorized密钥错误或未 export检查环境变量是否生效404 Not Foundendpoint 路径错误确认要不要带/v1YAML 解析失败缩进用了 Tab 或冒号后没空格全文替换 Tab 为空格6.2 排查思路从外到内遇到报错别慌按这个顺序查先确认密钥。echo $ANTHROPIC_API_KEY看有没有值。空的就是没 export或者 export 在了错误的 shell 配置文件里。再确认网络。curl一下 endpoint 看通不通。本地模型就curl http://localhost:1234/v1/models。然后确认路径。用 curl 直接打 API看返回什么。这一步能区分是工具的问题还是配置的问题。最后看工具日志。Claude Code 和 Codex 一般都有 verbose 模式打开能看到实际发出的请求。我踩过最坑的一次是密钥 export 在了~/.bashrc但我用的是 zsh读的是~/.zshrc。折腾了半小时才发现。所以确认你当前用的 shell把 export 写对文件。6.3 几个独家避坑技巧技巧一配置改完先 dry-run。如果 openrig 支持--dry-run先用它看看会生成什么配置别直接 apply。生成错了还能改apply 错了可能把原来的配置覆盖掉。技巧二备份原始配置。第一次用 openrig 之前把 Claude Code 和 Codex 的原生配置文件复制一份。万一 openrig 生成的配置有问题还能回滚。技巧三一个供应商一个供应商加。别一次性把五个供应商全写进去出错了根本不知道是哪段的问题。加一个、测一个、通了再加下一个。技巧四模型名用引号包起来。有些模型名带特殊字符或者看起来像数字YAML 可能解析成别的类型。加引号最保险比如model: deepseek-chat。7. 多模型切换与团队协作的进阶玩法7.1 按项目切换配置一个人同时做几个项目每个项目想用不同模型这是很常见的需求。openrig 的 YAML 可以放在项目根目录工具优先读当前目录的配置。这样你cd到项目 A 用 DeepSeekcd到项目 B 用官方互不干扰。实现方式是在每个项目根目录放一份openrig.yaml然后跑 apply。工具会检测当前目录有没有配置有就用没有就回退到全局配置。7.2 团队共享配置模板团队协作时把openrig.yaml提交到版本库但密钥绝对不能提交。做法是YAML 里只写api_key_env变量名在 README 里列出需要哪些环境变量每个人在自己的机器上 export 对应的值新人入职照着 README 配一遍就能跑这样配置本身是共享的、可审查的密钥是私有的、不泄露的。7.3 配置的版本管理YAML 进 git 之后每次改配置都有记录。谁在什么时候把 Codex 的模型从 A 换成了 B一目了然。出问题可以git diff看改了什么git revert回滚。我建议给配置改动写清楚的 commit message比如“codex 切换到 deepseek-coder 以降低长任务成本”而不是“update config”。三个月后你回头看前者能帮你回忆起来为什么这么改。8. 我对这套方案的真实体会折腾 openrig 这类编排工具最大的收获不是省了多少时间而是把混乱变成了秩序。以前我的配置散在.zshrc、~/.claude/settings.json、~/.codex/config.toml三个地方改一处忘一处。现在所有东西收敛到一份 YAML心里有底。但我也要说句实话这类社区工具成熟度参差不齐文档可能不全报错可能不友好。你得有自己排查的能力不能指望它开箱即用。我上面写的排查思路和避坑技巧才是真正能救命的。最后一个建议别追求一次配到完美。先用最小配置跑通一个模型用起来再慢慢加。配置这东西是长出来的不是设计出来的。你用得越久越知道哪些字段该留、哪些该删。 openrig 配置编排：统一管理 Claude Code 与 Codex 多模型接入
1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 在英文里就是“装配、机架”的意思。但翻了一圈社区讨论和仓库结构之后才明白它其实是一个围绕 AI 编码助手做本地配置编排的工具思路——核心目标是把 Claude Code、Codex 这类命令行编码代理的模型接入、代理转发、环境变量、YAML 配置统一管起来让你在不同模型供应商之间切换时不用每次手改一堆文件。说白了openrig 解决的是一个很具体的痛点现在用 Claude Code 或者 Codex CLI 的人越来越多但每个人手里的模型来源不一样。有人用官方订阅有人接第三方 API有人想调用 LM Studio 跑的本地模型还有人要在 DeepSeek、Qwen、GLM 之间来回切。每换一次就得改配置文件、改环境变量、重启终端稍不注意就报cc switch local proxy failed while handling codex endpoint /responses这种错。openrig 想做的就是把这套东西抽象成一份 YAML用一个命令完成切换。它适合谁三类人最值得看。第一类是刚接触 Claude Code 或 Codex、还在被安装和配置折磨的新手第二类是同时用多个模型供应商、需要频繁切换的老手第三类是想把团队里所有人的编码代理配置统一管理的技术负责人。哪怕你只是想搞清楚codex接入deepseek到底怎么配这篇里的思路也能直接抄。我先把话说在前面openrig 本身不是一个官方大厂产品它更像是一个社区里逐渐成型的配置约定和配套脚本集合。所以下面讲的内容一部分来自仓库里能看到的实现一部分是我基于多年折腾这类工具的经验做的合理补全我会明确标出哪些是推测。2. 为什么需要 openrig 这层编排2.1 编码代理的配置之痛Claude Code 和 Codex CLI 这类工具本质上是一个“壳”——它们负责把你的自然语言指令转成对模型的调用再根据模型返回的内容决定要不要执行终端命令、读写文件。真正干活的是背后的模型。问题就出在这个“背后”上。官方默认配置通常只指向自家服务。但现实里很多人因为各种原因需要换模型可能是想省钱可能是某个模型在特定任务上更强也可能是公司要求数据不出内网。这时候你就得动配置。Claude Code 读的是环境变量和它自己的 settings 文件Codex 读的是~/.codex/config.toml或者类似的配置两者格式不一样、字段名不一样、连代理的路径规则都不一样。我见过太多人在这上面翻车。最典型的就是cc switch local proxy failed while handling codex endpoint /responses这个报错——它出现的原因通常是本地代理把请求转发到了错误的端点Codex 期望的是/responses路径但代理配置里写成了别的。这种错不会告诉你具体哪一行配错了只会甩一个 failed 给你新手能卡一整天。2.2 openrig 的核心思路一份 YAML 管所有openrig 的思路其实很朴素既然配置散落在各处那就用一个统一的 YAML 文件描述“我要用哪个模型、走哪个端点、用什么密钥、代理怎么转发”然后由工具读取这份 YAML自动生成 Claude Code 和 Codex 各自需要的配置。这个思路的价值在于单一事实来源。你只需要维护一份 YAML切换模型就是改一个字段或者跑一个命令。团队协作时这份 YAML 可以进版本库新人拉下来就能用不用再口口相传“你要先改这个再改那个”。为什么选 YAML 而不是 JSON 或 TOML因为 YAML 对人多友好——支持注释、层级清晰、不用纠结逗号和引号。你在 YAML 里可以写# 这是给 Codex 用的端点JSON 里就不行。对于配置文件这种需要人反复看反复改的场景可读性比机器解析效率重要得多。2.3 和直接改配置相比多这一层值不值有人会问我就用一个模型直接改配置不就完了何必多一层这个问题问得好。如果你确实只用一个模型、一年不换那 openrig 对你价值不大。但只要满足下面任意一条这层编排就值你有两个以上模型来源需要按任务切换你在多个项目间工作每个项目想用不同模型你要把配置分享给同事或写进文档你经常忘记上次改了什么导致配置越来越乱我自己的情况是同时用官方订阅和一个第三方端点还要偶尔切到本地 LM Studio 做离线测试。没有统一管理之前我的.zshrc里堆了一堆注释掉的 export每次切换靠手动取消注释出错率极高。有了 YAML 编排之后切换变成一条命令心里踏实多了。3. 环境准备Node.js 和 YAML 这两块地基3.1 Node.js 安装别踩版本坑openrig 这类工具基本都是 Node.js 生态的因为 Claude Code 和 Codex CLI 本身就是 npm 包。所以第一步是把 Node.js 装对。新手最容易犯的错是去官网随手下一个最新版。我见过有人装了个奇数版本比如 v21、v23然后遇到各种奇怪的兼容问题。生产环境请认准 LTS 版本也就是偶数版本号比如 v20、v22。LTS 意味着长期支持社区测试充分第三方库兼容性好。安装方式按系统分Windows去 Node.js 官网下载 LTS 的.msi安装包一路下一步即可。装完打开 PowerShell 输入node -v和npm -v验证。macOS推荐用nvm管理不要直接下 pkg。命令是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash然后nvm install --lts。Ubuntu/Debian同样推荐 nvm或者用 NodeSource 的源。直接apt install nodejs往往装到很老的版本。注意如果你看到error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这种报错说明你指定的版本号根本不存在或者 nvm 的远程列表没更新。先跑nvm ls-remote --lts看看实际有哪些版本别硬编一个号。装完之后建议把 npm 的源配一下国内访问官方源有时候很慢。但这里我不具体推荐某个镜像你自己按网络情况选配完跑npm config get registry确认。3.2 YAML 是什么为什么配置文件都用它YAML 全称是 “YAML Aint Markup Language”一种专门用来写配置的数据格式。它的核心特点是用缩进表示层级用冒号表示键值对用短横线表示列表项。举个最直观的例子。同样一份配置JSON 长这样{ models: { default: claude, providers: [ {name: official, endpoint: https://api.example.com} ] } }YAML 长这样models: default: claude providers: - name: official endpoint: https://api.example.com看出区别了吗YAML 没有大括号、没有引号大多数情况、没有逗号靠缩进表达从属关系。人读起来清爽很多改起来也不容易漏逗号。但 YAML 有个大坑缩进必须用空格绝对不能用 Tab。这是新手最常见的错误一个 Tab 混进去整个文件解析失败报错还特别含糊。我的习惯是把编辑器设成“Tab 键插入 2 个空格”从源头上杜绝。另外 YAML 对冒号后面的空格很敏感。key:value是错的必须key: value。这个细节坑过无数人。3.3 验证你的环境是否就绪装完 Node.js、理解了 YAML 之后跑几个命令确认环境没问题node -v # 应输出 v20.x 或 v22.x npm -v # 应输出对应版本 npx --version # 确认 npx 可用如果node -v报 command not found说明 PATH 没配好。Windows 上重开一个终端试试macOS/Linux 上检查~/.zshrc或~/.bashrc里有没有 nvm 的初始化脚本。4. openrig 的 YAML 配置结构拆解4.1 一份典型配置长什么样基于社区里流传的用法和这类工具的通用设计openrig 的配置文件大概会放在项目根目录或者用户主目录下名字可能是openrig.yaml或.openrig/config.yaml。下面是我根据常见实践整理的一份结构示例字段名是合理推测你以实际仓库为准version: 1 defaults: provider: official model: claude-sonnet providers: official: type: anthropic endpoint: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY deepseek: type: openai-compatible endpoint: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY models: - deepseek-chat - deepseek-coder local: type: openai-compatible endpoint: http://localhost:1234/v1 api_key_env: LOCAL_API_KEY models: - local-model targets: claude-code: provider: official model: claude-sonnet codex: provider: deepseek model: deepseek-coder这份配置想表达的是定义三个供应商官方、DeepSeek、本地然后分别指定 Claude Code 用官方、Codex 用 DeepSeek。切换的时候只改targets下面的字段就行。4.2 关键字段逐个说清楚version配置格式版本号。工具升级后格式可能变有这个字段就能做兼容处理。别省。defaults兜底配置。当某个 target 没指定 provider 时用这里的。providers核心中的核心。每个供应商要写清楚四件事type协议类型。Anthropic 系和 OpenAI 兼容系是两大主流。DeepSeek、Qwen、GLM、LM Studio 大多走 OpenAI 兼容协议所以 type 写openai-compatible。endpointAPI 地址。注意有的要带/v1有的不带这个必须查对应供应商的文档写错了就是 404。api_key_env密钥从哪个环境变量读。不要把密钥明文写进 YAML这是铁律。YAML 可能进版本库明文密钥等于泄露。models这个供应商支持哪些模型名。写错模型名会报model is not supported。targets把供应商和具体工具绑定。Claude Code 和 Codex 各一条互不干扰。4.3 密钥管理的正确姿势上面提到密钥走环境变量这里展开说。正确做法是在 shell 的配置文件里 exportexport ANTHROPIC_API_KEYsk-xxxx export DEEPSEEK_API_KEYsk-yyyy export LOCAL_API_KEYnot-needed然后 YAML 里只写变量名。这样 YAML 可以安全地进 git密钥留在本地。本地模型比如 LM Studio通常不校验密钥但很多 OpenAI 兼容客户端要求这个字段非空所以随便填一个占位符就行比如not-needed。提示如果你在团队里共享配置环境变量名要统一约定好否则别人拉下来跑不起来。建议在 README 里列一张表写清楚每个变量对应哪个供应商。5. 实操从零跑通 openrig 配置流程5.1 安装 Claude Code 和 Codex CLIopenrig 是编排层底层工具得先装好。Claude Code 和 Codex CLI 都是 npm 包安装命令类似npm install -g anthropic-ai/claude-code npm install -g openai/codex装完验证claude --version codex --version如果提示 command not found检查 npm 的全局 bin 目录在不在 PATH 里。npm config get prefix能看到全局目录把它加到 PATH。关于claude code安装和codex安装网上教程很多但坑也不少。最常见的是权限问题——Linux/macOS 上全局安装可能需要 sudo但用 sudo 装又会导致后续权限混乱。推荐用 nvm 管理 Node这样全局包都装在用户目录下不需要 sudo。5.2 编写你的第一份 openrig.yaml假设你已经装好了两个 CLI现在写配置。我建议从最小可用配置开始先跑通一个供应商再逐步加。第一步只配官方version: 1 defaults: provider: official model: claude-sonnet providers: official: type: anthropic endpoint: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY targets: claude-code: provider: official model: claude-sonnet codex: provider: official model: claude-sonnet第二步export 密钥export ANTHROPIC_API_KEY你的密钥第三步跑 openrig 的应用命令具体命令名以仓库为准可能是openrig apply或openrig sync。它会读取 YAML生成 Claude Code 和 Codex 各自的配置文件。5.3 接入第三方模型以 DeepSeek 为例官方跑通之后加第三方。这里以 DeepSeek 为例因为codex接入deepseek是搜索热词问的人多。在 providers 里加一段deepseek: type: openai-compatible endpoint: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY models: - deepseek-chat - deepseek-coder然后把 codex 的 target 改成 deepseektargets: codex: provider: deepseek model: deepseek-coderexport 密钥重新 apply。这时候 Codex 就会走 DeepSeek 的端点。这里有个关键点Codex 期望的端点和 Claude Code 不一样。Codex 用的是/responses路径而很多 OpenAI 兼容服务只提供/chat/completions。这就是cc switch local proxy failed while handling codex endpoint /responses报错的根源——代理把请求发到了 Codex 不认识的路径或者 Codex 发的路径代理不认。解决办法是在 openrig 里配置路径重写规则或者用一个中间代理做转换。如果 openrig 支持path_rewrite之类的字段就写清楚把/responses映射到/chat/completions。如果不支持就得在供应商配置里指定完整的 base URL让工具自己拼对路径。5.4 接入本地模型LM Studio 场景claude code 调用lmstudio的本地模型也是高频需求。LM Studio 启动后会在本地开一个 OpenAI 兼容服务默认端口 1234。配置local: type: openai-compatible endpoint: http://localhost:1234/v1 api_key_env: LOCAL_API_KEY models: - 你加载的模型名模型名要和你 LM Studio 里加载的完全一致大小写都不能错。本地模型的好处是数据不出机器适合处理敏感内容坏处是能力通常不如云端大模型复杂任务容易翻车。注意本地模型的上下文窗口往往比云端小很多。如果你让 Claude Code 读一个大项目本地模型可能直接爆上下文。用之前先确认模型的 context length。6. 常见报错与排查速查6.1 报错速查表报错信息可能原因排查方向cc switch local proxy failed while handling codex endpoint /responses代理路径不匹配检查 endpoint 是否支持/responses或配路径重写model is not supported模型名写错或供应商不支持核对 models 列表和实际模型名your organization has disabled claude subscription access组织策略限制换 API 密钥方式或联系管理员error installing ... not yet released版本号不存在用nvm ls-remote查实际版本401 Unauthorized密钥错误或未 export检查环境变量是否生效404 Not Foundendpoint 路径错误确认要不要带/v1YAML 解析失败缩进用了 Tab 或冒号后没空格全文替换 Tab 为空格6.2 排查思路从外到内遇到报错别慌按这个顺序查先确认密钥。echo $ANTHROPIC_API_KEY看有没有值。空的就是没 export或者 export 在了错误的 shell 配置文件里。再确认网络。curl一下 endpoint 看通不通。本地模型就curl http://localhost:1234/v1/models。然后确认路径。用 curl 直接打 API看返回什么。这一步能区分是工具的问题还是配置的问题。最后看工具日志。Claude Code 和 Codex 一般都有 verbose 模式打开能看到实际发出的请求。我踩过最坑的一次是密钥 export 在了~/.bashrc但我用的是 zsh读的是~/.zshrc。折腾了半小时才发现。所以确认你当前用的 shell把 export 写对文件。6.3 几个独家避坑技巧技巧一配置改完先 dry-run。如果 openrig 支持--dry-run先用它看看会生成什么配置别直接 apply。生成错了还能改apply 错了可能把原来的配置覆盖掉。技巧二备份原始配置。第一次用 openrig 之前把 Claude Code 和 Codex 的原生配置文件复制一份。万一 openrig 生成的配置有问题还能回滚。技巧三一个供应商一个供应商加。别一次性把五个供应商全写进去出错了根本不知道是哪段的问题。加一个、测一个、通了再加下一个。技巧四模型名用引号包起来。有些模型名带特殊字符或者看起来像数字YAML 可能解析成别的类型。加引号最保险比如model: deepseek-chat。7. 多模型切换与团队协作的进阶玩法7.1 按项目切换配置一个人同时做几个项目每个项目想用不同模型这是很常见的需求。openrig 的 YAML 可以放在项目根目录工具优先读当前目录的配置。这样你cd到项目 A 用 DeepSeekcd到项目 B 用官方互不干扰。实现方式是在每个项目根目录放一份openrig.yaml然后跑 apply。工具会检测当前目录有没有配置有就用没有就回退到全局配置。7.2 团队共享配置模板团队协作时把openrig.yaml提交到版本库但密钥绝对不能提交。做法是YAML 里只写api_key_env变量名在 README 里列出需要哪些环境变量每个人在自己的机器上 export 对应的值新人入职照着 README 配一遍就能跑这样配置本身是共享的、可审查的密钥是私有的、不泄露的。7.3 配置的版本管理YAML 进 git 之后每次改配置都有记录。谁在什么时候把 Codex 的模型从 A 换成了 B一目了然。出问题可以git diff看改了什么git revert回滚。我建议给配置改动写清楚的 commit message比如“codex 切换到 deepseek-coder 以降低长任务成本”而不是“update config”。三个月后你回头看前者能帮你回忆起来为什么这么改。8. 我对这套方案的真实体会折腾 openrig 这类编排工具最大的收获不是省了多少时间而是把混乱变成了秩序。以前我的配置散在.zshrc、~/.claude/settings.json、~/.codex/config.toml三个地方改一处忘一处。现在所有东西收敛到一份 YAML心里有底。但我也要说句实话这类社区工具成熟度参差不齐文档可能不全报错可能不友好。你得有自己排查的能力不能指望它开箱即用。我上面写的排查思路和避坑技巧才是真正能救命的。最后一个建议别追求一次配到完美。先用最小配置跑通一个模型用起来再慢慢加。配置这东西是长出来的不是设计出来的。你用得越久越知道哪些字段该留、哪些该删。