1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到“openrig”这个词我脑子里蹦出来的第一反应是“open”加“rig”——一个开放的、可拼装的装置或工作台。放到当下 AI 编程助手满天飞的环境里这个名字其实非常贴切它想做的事情就是给各种命令行 AI 编程工具搭一个统一、开放、可自由组合的“工作台”让你不再被某一家工具、某一个模型、某一种配置方式绑死。我接触命令行 AI 编程工具的时间不算短从最早手动敲 API 请求到后来用上各种 CLI 助手踩过的坑基本能写一本小册子。最典型的一个痛点就是工具太多配置太散模型切换太麻烦。今天想用 Claude Code 写业务逻辑明天想用 Codex 处理一段重构后天又想接本地模型跑点隐私数据结果每个工具都有自己的配置文件、自己的环境变量、自己的登录方式光是来回切换就能耗掉半小时。openrig 这类项目的核心价值就是把这些零散的东西收拢到一个统一的配置层里。它通常以 YAML 作为配置载体以 Node.js 作为运行环境把 Claude Code、Codex 这类 CLI 工具的接入方式抽象成可复用的“装置rig”。你可以把它理解成一个模型与工具之间的转接插排墙上的插座模型服务可能有好几个规格手里的电器CLI 工具插头也各不相同openrig 就是那个让你随便插、随便换的插排。这篇文章适合几类人看一是刚开始接触 Claude Code、Codex 这类命令行工具被安装和配置卡住的新手二是已经在用但被多工具、多模型切换折磨得够呛的老用户三是想自己搭一套本地化、可定制的 AI 编程工作流又不想从零造轮子的折腾党。我会把 openrig 背后的思路、YAML 配置怎么写、Node.js 环境怎么搭、Claude Code 和 Codex 怎么接进来、以及一堆实际会遇到的报错怎么排查全部掰开揉碎讲清楚。需要先说明一点openrig 目前并不是一个官方大一统的标准不同人手里的实现细节会有差异。所以下面讲的内容是基于这类“统一配置层”项目的常见实践来展开的具体到你手上的版本参数名可能有出入但思路和排查方法是通用的。2. 整体设计思路为什么是 YAML Node.js 这套组合2.1 用 YAML 做配置层图的是什么先说为什么这类项目普遍选 YAML而不是 JSON、TOML 或者干脆用 JS 对象。JSON 的问题在于不能写注释。AI 工具的配置里有大量需要标注的地方比如“这个 key 是临时测试用的”“这个模型名对应的是本地部署的哪个端口”没有注释过两周自己都看不懂。TOML 表达嵌套结构时又比较啰嗦尤其是当你要配置多个工具、多个模型、多组参数的时候层级一深就写得很别扭。YAML 的优势正好卡在这个点上支持注释、层级直观、缩进即结构。一个典型的 openrig 配置大概长这样version: 1 defaults: provider: local timeout: 120 rigs: claude: tool: claude-code provider: anthropic model: claude-sonnet env: ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY} codex: tool: codex-cli provider: openai-compatible model: gpt-5.6-sol endpoint: http://127.0.0.1:8080/v1你看注释可以随便加层级一眼能看懂改起来也方便。这就是为什么 YAML 成了这类工具的事实标准。但 YAML 有个著名的坑缩进必须用空格绝对不能用 Tab。我见过太多人复制粘贴配置后报一堆莫名其妙的解析错误最后发现是编辑器自动把空格转成了 Tab。这个后面排查章节会细讲。2.2 Node.js 作为运行环境是必然还是巧合再看为什么是 Node.js。Claude Code、Codex CLI 这些工具绝大多数都是基于 Node.js 生态分发的通过 npm 全局安装。openrig 要做的“统一调度”本质上是在这些工具外面包一层所以它自己也跑在 Node.js 上最自然——不用跨语言调用直接复用同一套进程管理和环境变量机制。Node.js 在这里扮演的角色说白了就是胶水层。它负责读取 YAML、解析配置、把对应的环境变量注入到子进程、启动目标 CLI 工具。你不需要精通 Node.js 才能用 openrig但你必须把 Node.js 环境装对否则后面全是连锁反应。这里有个关键点很多人忽略Node.js 版本。Claude Code 和 Codex 对 Node 版本有要求太老的版本会直接报错。我建议直接用 LTS 版本目前主流是 20.x 或 22.x。别去追最新的奇数版本那些是实验性的工具链兼容性没保证。2.3 统一配置层解决了哪些真实痛点把 YAML 和 Node.js 组合起来openrig 实际解决的是这么几个问题模型切换成本高以前换个模型要改环境变量、重启终端现在改一行 YAML 就行。多工具配置分散Claude Code 的配置、Codex 的配置各在一处现在集中管理。本地模型接入麻烦想接本地部署的模型要手动改 endpoint、改模型名现在配置里写清楚就行。团队协作难统一一份 YAML 提交到仓库所有人用同一套配置减少“在我机器上能跑”的问题。理解了这层设计意图后面的实操就顺理成章了。3. 环境准备Node.js 与 YAML 的安装细节3.1 Node.js 安装别在版本上栽跟头安装 Node.js 最稳的方式是去官网下载 LTS 版本。Windows 用户直接下.msi安装包一路下一步即可macOS 用户可以用官方.pkg也可以用包管理器Linux 用户建议用 NodeSource 的源或者版本管理工具。我个人的习惯是用版本管理工具因为不同项目对 Node 版本要求不一样能随时切换会省很多事。以常见的nvm为例# 安装 nvm 后 nvm install 22 nvm use 22 node -v npm -v装完之后一定要验证版本。我遇到过有人装是装了但系统 PATH 里指向的是另一个老版本结果node -v显示的是 16.x然后 Claude Code 一启动就报错。注意Windows 上如果同时装过多个 Node 版本PATH 顺序很容易乱。装完后在命令行里敲where nodeWindows或which nodemacOS/Linux确认指向的是你刚装的那个。还有一个高频报错值得单独说error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个错误通常出现在你用某个工具去安装一个还不存在的版本号时。解决办法很简单别指定那个版本改用 LTS 或者已经正式发布的版本号。版本号不是越大越好稳定可用才是第一位的。3.2 YAML 需不需要单独“安装”这是新手最容易困惑的点。YAML 本身是一种数据格式不是软件所以严格来说不需要“安装”。你需要的只是一个能正确识别 YAML 缩进的编辑器VS Code 就很好装个 YAML 插件更佳。运行环境里能解析 YAML 的库Node.js 项目里通常是js-yaml或yaml包openrig 一般会自带依赖。所以当有人搜“yaml 安装”时真正要做的往往是确认你的项目依赖里有没有 YAML 解析库以及你的编辑器有没有把.yaml文件当成 YAML 来高亮和校验。如果你要自己写脚本解析 YAMLNode.js 里可以这样const fs require(fs); const yaml require(js-yaml); try { const config yaml.load(fs.readFileSync(./openrig.yaml, utf8)); console.log(config.rigs); } catch (e) { console.error(YAML 解析失败:, e.message); }这段代码的价值在于当 openrig 报配置错误时你可以用它单独验证 YAML 文件本身有没有语法问题从而把“配置格式错误”和“工具逻辑错误”区分开。这个排查思路后面还会用到。3.3 编辑器配置VS Code 的 YAML 校验用 VS Code 的话强烈建议装官方 YAML 扩展。它能在你写配置时实时提示缩进错误、重复 key、类型不匹配等问题。很多人配置报错排查半天其实编辑器早就用红色波浪线标出来了只是没注意。配置关联也很重要。在settings.json里可以指定 schema让编辑器知道你的 openrig 配置应该符合什么结构{ yaml.schemas: { ./schemas/openrig.schema.json: openrig.yaml } }有了 schema写错字段名、写错类型编辑器当场就告诉你比等到运行时才报错高效得多。4. 核心配置解析把 Claude Code 和 Codex 接进来4.1 Claude Code 的接入方式Claude Code 是 Anthropic 推出的命令行编程助手安装方式通常是 npm 全局安装npm install -g anthropic-ai/claude-code装完之后第一次运行需要认证。这里有个高频问题your organization has disabled claude subscription access for claude code。这个报错的意思是你当前账号所属的组织关闭了通过订阅方式访问 Claude Code 的权限。遇到这个通常需要联系组织管理员确认权限策略或者改用 API key 的方式接入。在 openrig 的配置里Claude Code 这一块一般要指定rigs: claude: tool: claude-code provider: anthropic model: claude-sonnet env: ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY} ANTHROPIC_BASE_URL: https://api.anthropic.comANTHROPIC_BASE_URL这个字段很关键。如果你要接的是兼容 Anthropic 协议的第三方服务或本地服务改这个地址就能把请求导向别处。这也是 openrig 灵活性的体现——工具本身不变只改配置里的地址和 key。VS Code 里集成 Claude Code 也是常见需求。一般是在扩展市场装对应插件然后在设置里填 API key 和模型。如果你更习惯终端直接在 VS Code 的集成终端里跑 CLI 版本体验更一致。4.2 Codex 的接入与常见报错Codex CLI 的安装类似npm install -g openai/codexCodex 的配置里最容易出问题的是endpoint 和模型名的匹配。比如你看到这个报错{detail:the gpt-5.6-sol model is not supported when using codex with a ...}它的意思是你配置里写的模型名当前这个接入方式不支持。原因通常有两个一是模型名拼错了二是你用的 endpoint 根本不提供这个模型。解决办法是去确认你的服务方到底支持哪些模型名然后改成正确的。还有一个经典报错cc switch local proxy failed while handling codex endpoint /responses。这个通常出现在你用某种本地代理或转发层去接 Codex 的时候代理在处理/responses这个路径时失败了。排查方向是确认代理服务是否正常启动、路径是否正确转发、请求体格式是否符合 Codex 的预期。Codex 接入第三方模型比如 DeepSeek、Qwen、GLM 这类兼容 OpenAI 协议的服务时配置大概是这样rigs: codex: tool: codex-cli provider: openai-compatible model: deepseek-chat endpoint: https://api.deepseek.com/v1 env: OPENAI_API_KEY: ${DEEPSEEK_API_KEY}注意provider写的是openai-compatible因为 Codex 走的是 OpenAI 的接口协议只要对方兼容这个协议就能接。模型名要写对方文档里明确支持的那个别自己臆造。4.3 本地模型接入以 LM Studio 为例想接本地模型的话LM Studio 是个不错的选择它能在本地起一个兼容 OpenAI 协议的服务。配置思路和上面接第三方服务一样只是 endpoint 换成本地地址rigs: local: tool: codex-cli provider: openai-compatible model: local-model-name endpoint: http://127.0.0.1:1234/v1 env: OPENAI_API_KEY: not-needed本地服务通常不校验 key随便填一个占位符就行。模型名要和你 LM Studio 里实际加载的模型对应上否则会报模型不存在。提示本地模型的上下文长度和推理能力通常不如云端大模型接进来适合做隐私敏感或离线场景的任务别指望它干重活。5. 实操全流程从零搭起一套可用的 openrig5.1 第一步确认基础环境动手之前先把三件事确认清楚Node.js 版本符合要求node -v输出 20.x 或 22.x。npm 能正常用npm -v有输出。目标 CLI 工具已经全局安装claude --version或codex --version能跑。这三步任何一步失败后面都别急着往下走。我见过太多人跳过验证结果配置写了一堆最后发现是 Node 没装对。5.2 第二步编写 openrig 配置文件在项目根目录建一个openrig.yaml按前面的结构把要用的工具和模型写进去。建议从最小可用配置开始先只配一个工具跑通了再加第二个。version: 1 defaults: timeout: 120 logLevel: info rigs: claude: tool: claude-code provider: anthropic model: claude-sonnet env: ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}写完先用前面那段 Node.js 脚本验证一下 YAML 能不能正常解析。这一步能过滤掉 80% 的低级错误。5.3 第三步环境变量的处理配置里用${VAR}这种写法引用环境变量是常见做法。好处是敏感信息不写进配置文件配置文件可以放心提交到仓库。设置环境变量的方式各平台不同# macOS / Linux export ANTHROPIC_API_KEYyour_key_here # Windows PowerShell $env:ANTHROPIC_API_KEYyour_key_here # Windows CMD set ANTHROPIC_API_KEYyour_key_here注意环境变量是会话级的关掉终端就没了。想持久化macOS/Linux 写进~/.bashrc或~/.zshrcWindows 用系统环境变量设置界面。5.4 第四步启动与验证配置和环境变量都就绪后启动 openrig 对应的 rig。启动后做一次实际调用验证比如让 Claude Code 解释一段代码或者让 Codex 补全一个函数。能正常返回结果说明整条链路通了。如果启动失败按这个顺序排查YAML 语法 → 环境变量是否生效 → CLI 工具本身能否独立运行 → endpoint 是否可达。这个顺序是从内到外能最快定位问题层。6. 常见问题与排查技巧实录6.1 配置类问题速查报错现象可能原因解决方向YAML 解析失败用了 Tab 缩进 / 冒号后没空格全部改空格冒号后加空格环境变量为空变量没导出 / 拼写错误用echo $VAR验证模型不支持模型名错误 / endpoint 不提供核对服务方文档代理处理失败代理未启动 / 路径转发错检查代理日志和路径组织权限受限账号策略限制联系管理员或换接入方式6.2 几个我踩过的坑坑一YAML 里的布尔值陷阱。YAML 会把yes、no、on、off自动解析成布尔值。如果你某个字段的值恰好是这些词就会类型不匹配。解决办法是加引号写成no。坑二环境变量在子进程里丢失。openrig 启动 CLI 工具时是开子进程的如果环境变量没正确传递子进程里就取不到。排查时可以在配置里临时打印一下环境变量确认传递链路。坑三本地服务端口冲突。本地模型服务默认端口如果被占用启动会失败但报错不明显。换个端口或者先确认端口没被占。坑四Node 版本和工具要求不匹配。有些工具要求 Node 18 以上有些要求 20 以上。装之前先看工具的文档要求别想当然。6.3 排查的通用心法遇到报错先别急着搜。把报错信息完整读一遍很多时候答案就在里面。比如前面那个模型不支持的报错它明确告诉你是哪个模型名不支持你只要去核对就行。其次二分法定位。把链路拆成几段配置解析、环境变量、工具启动、网络请求。逐段验证能快速缩小范围。最后保留最小复现。把配置精简到只剩一个工具、一个模型如果这样能跑通再逐步加回去问题自然浮现。7. 一些延伸玩法和个人体会openrig 这套思路跑通之后能玩的花样其实不少。比如你可以给不同的项目配不同的 rig前端项目用响应快的模型后端重构用推理强的模型切换只改一行配置。也可以把配置模板化团队里共享一份基础配置各自覆盖自己的 key 和本地路径。我还试过把 openrig 和 VS Code 的任务系统结合一键启动对应的 AI 助手省去手动敲命令的步骤。对于经常在多个工具间切换的人来说这种自动化能省下不少零碎时间。最后分享一个小技巧给配置文件加版本号字段。工具在迭代配置格式也可能变有了版本号将来迁移或兼容处理会方便很多。这个习惯在配置管理里很值钱早养成早受益。这套东西说到底核心不是某个具体工具而是把配置和工具解耦的思路。工具会换模型会更新但一套清晰的配置层能让你在变化里始终保持主动。 openrig 统一配置层：YAML+Node.js 接入 Claude Code 与 Codex 实战
1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到“openrig”这个词我脑子里蹦出来的第一反应是“open”加“rig”——一个开放的、可拼装的装置或工作台。放到当下 AI 编程助手满天飞的环境里这个名字其实非常贴切它想做的事情就是给各种命令行 AI 编程工具搭一个统一、开放、可自由组合的“工作台”让你不再被某一家工具、某一个模型、某一种配置方式绑死。我接触命令行 AI 编程工具的时间不算短从最早手动敲 API 请求到后来用上各种 CLI 助手踩过的坑基本能写一本小册子。最典型的一个痛点就是工具太多配置太散模型切换太麻烦。今天想用 Claude Code 写业务逻辑明天想用 Codex 处理一段重构后天又想接本地模型跑点隐私数据结果每个工具都有自己的配置文件、自己的环境变量、自己的登录方式光是来回切换就能耗掉半小时。openrig 这类项目的核心价值就是把这些零散的东西收拢到一个统一的配置层里。它通常以 YAML 作为配置载体以 Node.js 作为运行环境把 Claude Code、Codex 这类 CLI 工具的接入方式抽象成可复用的“装置rig”。你可以把它理解成一个模型与工具之间的转接插排墙上的插座模型服务可能有好几个规格手里的电器CLI 工具插头也各不相同openrig 就是那个让你随便插、随便换的插排。这篇文章适合几类人看一是刚开始接触 Claude Code、Codex 这类命令行工具被安装和配置卡住的新手二是已经在用但被多工具、多模型切换折磨得够呛的老用户三是想自己搭一套本地化、可定制的 AI 编程工作流又不想从零造轮子的折腾党。我会把 openrig 背后的思路、YAML 配置怎么写、Node.js 环境怎么搭、Claude Code 和 Codex 怎么接进来、以及一堆实际会遇到的报错怎么排查全部掰开揉碎讲清楚。需要先说明一点openrig 目前并不是一个官方大一统的标准不同人手里的实现细节会有差异。所以下面讲的内容是基于这类“统一配置层”项目的常见实践来展开的具体到你手上的版本参数名可能有出入但思路和排查方法是通用的。2. 整体设计思路为什么是 YAML Node.js 这套组合2.1 用 YAML 做配置层图的是什么先说为什么这类项目普遍选 YAML而不是 JSON、TOML 或者干脆用 JS 对象。JSON 的问题在于不能写注释。AI 工具的配置里有大量需要标注的地方比如“这个 key 是临时测试用的”“这个模型名对应的是本地部署的哪个端口”没有注释过两周自己都看不懂。TOML 表达嵌套结构时又比较啰嗦尤其是当你要配置多个工具、多个模型、多组参数的时候层级一深就写得很别扭。YAML 的优势正好卡在这个点上支持注释、层级直观、缩进即结构。一个典型的 openrig 配置大概长这样version: 1 defaults: provider: local timeout: 120 rigs: claude: tool: claude-code provider: anthropic model: claude-sonnet env: ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY} codex: tool: codex-cli provider: openai-compatible model: gpt-5.6-sol endpoint: http://127.0.0.1:8080/v1你看注释可以随便加层级一眼能看懂改起来也方便。这就是为什么 YAML 成了这类工具的事实标准。但 YAML 有个著名的坑缩进必须用空格绝对不能用 Tab。我见过太多人复制粘贴配置后报一堆莫名其妙的解析错误最后发现是编辑器自动把空格转成了 Tab。这个后面排查章节会细讲。2.2 Node.js 作为运行环境是必然还是巧合再看为什么是 Node.js。Claude Code、Codex CLI 这些工具绝大多数都是基于 Node.js 生态分发的通过 npm 全局安装。openrig 要做的“统一调度”本质上是在这些工具外面包一层所以它自己也跑在 Node.js 上最自然——不用跨语言调用直接复用同一套进程管理和环境变量机制。Node.js 在这里扮演的角色说白了就是胶水层。它负责读取 YAML、解析配置、把对应的环境变量注入到子进程、启动目标 CLI 工具。你不需要精通 Node.js 才能用 openrig但你必须把 Node.js 环境装对否则后面全是连锁反应。这里有个关键点很多人忽略Node.js 版本。Claude Code 和 Codex 对 Node 版本有要求太老的版本会直接报错。我建议直接用 LTS 版本目前主流是 20.x 或 22.x。别去追最新的奇数版本那些是实验性的工具链兼容性没保证。2.3 统一配置层解决了哪些真实痛点把 YAML 和 Node.js 组合起来openrig 实际解决的是这么几个问题模型切换成本高以前换个模型要改环境变量、重启终端现在改一行 YAML 就行。多工具配置分散Claude Code 的配置、Codex 的配置各在一处现在集中管理。本地模型接入麻烦想接本地部署的模型要手动改 endpoint、改模型名现在配置里写清楚就行。团队协作难统一一份 YAML 提交到仓库所有人用同一套配置减少“在我机器上能跑”的问题。理解了这层设计意图后面的实操就顺理成章了。3. 环境准备Node.js 与 YAML 的安装细节3.1 Node.js 安装别在版本上栽跟头安装 Node.js 最稳的方式是去官网下载 LTS 版本。Windows 用户直接下.msi安装包一路下一步即可macOS 用户可以用官方.pkg也可以用包管理器Linux 用户建议用 NodeSource 的源或者版本管理工具。我个人的习惯是用版本管理工具因为不同项目对 Node 版本要求不一样能随时切换会省很多事。以常见的nvm为例# 安装 nvm 后 nvm install 22 nvm use 22 node -v npm -v装完之后一定要验证版本。我遇到过有人装是装了但系统 PATH 里指向的是另一个老版本结果node -v显示的是 16.x然后 Claude Code 一启动就报错。注意Windows 上如果同时装过多个 Node 版本PATH 顺序很容易乱。装完后在命令行里敲where nodeWindows或which nodemacOS/Linux确认指向的是你刚装的那个。还有一个高频报错值得单独说error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个错误通常出现在你用某个工具去安装一个还不存在的版本号时。解决办法很简单别指定那个版本改用 LTS 或者已经正式发布的版本号。版本号不是越大越好稳定可用才是第一位的。3.2 YAML 需不需要单独“安装”这是新手最容易困惑的点。YAML 本身是一种数据格式不是软件所以严格来说不需要“安装”。你需要的只是一个能正确识别 YAML 缩进的编辑器VS Code 就很好装个 YAML 插件更佳。运行环境里能解析 YAML 的库Node.js 项目里通常是js-yaml或yaml包openrig 一般会自带依赖。所以当有人搜“yaml 安装”时真正要做的往往是确认你的项目依赖里有没有 YAML 解析库以及你的编辑器有没有把.yaml文件当成 YAML 来高亮和校验。如果你要自己写脚本解析 YAMLNode.js 里可以这样const fs require(fs); const yaml require(js-yaml); try { const config yaml.load(fs.readFileSync(./openrig.yaml, utf8)); console.log(config.rigs); } catch (e) { console.error(YAML 解析失败:, e.message); }这段代码的价值在于当 openrig 报配置错误时你可以用它单独验证 YAML 文件本身有没有语法问题从而把“配置格式错误”和“工具逻辑错误”区分开。这个排查思路后面还会用到。3.3 编辑器配置VS Code 的 YAML 校验用 VS Code 的话强烈建议装官方 YAML 扩展。它能在你写配置时实时提示缩进错误、重复 key、类型不匹配等问题。很多人配置报错排查半天其实编辑器早就用红色波浪线标出来了只是没注意。配置关联也很重要。在settings.json里可以指定 schema让编辑器知道你的 openrig 配置应该符合什么结构{ yaml.schemas: { ./schemas/openrig.schema.json: openrig.yaml } }有了 schema写错字段名、写错类型编辑器当场就告诉你比等到运行时才报错高效得多。4. 核心配置解析把 Claude Code 和 Codex 接进来4.1 Claude Code 的接入方式Claude Code 是 Anthropic 推出的命令行编程助手安装方式通常是 npm 全局安装npm install -g anthropic-ai/claude-code装完之后第一次运行需要认证。这里有个高频问题your organization has disabled claude subscription access for claude code。这个报错的意思是你当前账号所属的组织关闭了通过订阅方式访问 Claude Code 的权限。遇到这个通常需要联系组织管理员确认权限策略或者改用 API key 的方式接入。在 openrig 的配置里Claude Code 这一块一般要指定rigs: claude: tool: claude-code provider: anthropic model: claude-sonnet env: ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY} ANTHROPIC_BASE_URL: https://api.anthropic.comANTHROPIC_BASE_URL这个字段很关键。如果你要接的是兼容 Anthropic 协议的第三方服务或本地服务改这个地址就能把请求导向别处。这也是 openrig 灵活性的体现——工具本身不变只改配置里的地址和 key。VS Code 里集成 Claude Code 也是常见需求。一般是在扩展市场装对应插件然后在设置里填 API key 和模型。如果你更习惯终端直接在 VS Code 的集成终端里跑 CLI 版本体验更一致。4.2 Codex 的接入与常见报错Codex CLI 的安装类似npm install -g openai/codexCodex 的配置里最容易出问题的是endpoint 和模型名的匹配。比如你看到这个报错{detail:the gpt-5.6-sol model is not supported when using codex with a ...}它的意思是你配置里写的模型名当前这个接入方式不支持。原因通常有两个一是模型名拼错了二是你用的 endpoint 根本不提供这个模型。解决办法是去确认你的服务方到底支持哪些模型名然后改成正确的。还有一个经典报错cc switch local proxy failed while handling codex endpoint /responses。这个通常出现在你用某种本地代理或转发层去接 Codex 的时候代理在处理/responses这个路径时失败了。排查方向是确认代理服务是否正常启动、路径是否正确转发、请求体格式是否符合 Codex 的预期。Codex 接入第三方模型比如 DeepSeek、Qwen、GLM 这类兼容 OpenAI 协议的服务时配置大概是这样rigs: codex: tool: codex-cli provider: openai-compatible model: deepseek-chat endpoint: https://api.deepseek.com/v1 env: OPENAI_API_KEY: ${DEEPSEEK_API_KEY}注意provider写的是openai-compatible因为 Codex 走的是 OpenAI 的接口协议只要对方兼容这个协议就能接。模型名要写对方文档里明确支持的那个别自己臆造。4.3 本地模型接入以 LM Studio 为例想接本地模型的话LM Studio 是个不错的选择它能在本地起一个兼容 OpenAI 协议的服务。配置思路和上面接第三方服务一样只是 endpoint 换成本地地址rigs: local: tool: codex-cli provider: openai-compatible model: local-model-name endpoint: http://127.0.0.1:1234/v1 env: OPENAI_API_KEY: not-needed本地服务通常不校验 key随便填一个占位符就行。模型名要和你 LM Studio 里实际加载的模型对应上否则会报模型不存在。提示本地模型的上下文长度和推理能力通常不如云端大模型接进来适合做隐私敏感或离线场景的任务别指望它干重活。5. 实操全流程从零搭起一套可用的 openrig5.1 第一步确认基础环境动手之前先把三件事确认清楚Node.js 版本符合要求node -v输出 20.x 或 22.x。npm 能正常用npm -v有输出。目标 CLI 工具已经全局安装claude --version或codex --version能跑。这三步任何一步失败后面都别急着往下走。我见过太多人跳过验证结果配置写了一堆最后发现是 Node 没装对。5.2 第二步编写 openrig 配置文件在项目根目录建一个openrig.yaml按前面的结构把要用的工具和模型写进去。建议从最小可用配置开始先只配一个工具跑通了再加第二个。version: 1 defaults: timeout: 120 logLevel: info rigs: claude: tool: claude-code provider: anthropic model: claude-sonnet env: ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}写完先用前面那段 Node.js 脚本验证一下 YAML 能不能正常解析。这一步能过滤掉 80% 的低级错误。5.3 第三步环境变量的处理配置里用${VAR}这种写法引用环境变量是常见做法。好处是敏感信息不写进配置文件配置文件可以放心提交到仓库。设置环境变量的方式各平台不同# macOS / Linux export ANTHROPIC_API_KEYyour_key_here # Windows PowerShell $env:ANTHROPIC_API_KEYyour_key_here # Windows CMD set ANTHROPIC_API_KEYyour_key_here注意环境变量是会话级的关掉终端就没了。想持久化macOS/Linux 写进~/.bashrc或~/.zshrcWindows 用系统环境变量设置界面。5.4 第四步启动与验证配置和环境变量都就绪后启动 openrig 对应的 rig。启动后做一次实际调用验证比如让 Claude Code 解释一段代码或者让 Codex 补全一个函数。能正常返回结果说明整条链路通了。如果启动失败按这个顺序排查YAML 语法 → 环境变量是否生效 → CLI 工具本身能否独立运行 → endpoint 是否可达。这个顺序是从内到外能最快定位问题层。6. 常见问题与排查技巧实录6.1 配置类问题速查报错现象可能原因解决方向YAML 解析失败用了 Tab 缩进 / 冒号后没空格全部改空格冒号后加空格环境变量为空变量没导出 / 拼写错误用echo $VAR验证模型不支持模型名错误 / endpoint 不提供核对服务方文档代理处理失败代理未启动 / 路径转发错检查代理日志和路径组织权限受限账号策略限制联系管理员或换接入方式6.2 几个我踩过的坑坑一YAML 里的布尔值陷阱。YAML 会把yes、no、on、off自动解析成布尔值。如果你某个字段的值恰好是这些词就会类型不匹配。解决办法是加引号写成no。坑二环境变量在子进程里丢失。openrig 启动 CLI 工具时是开子进程的如果环境变量没正确传递子进程里就取不到。排查时可以在配置里临时打印一下环境变量确认传递链路。坑三本地服务端口冲突。本地模型服务默认端口如果被占用启动会失败但报错不明显。换个端口或者先确认端口没被占。坑四Node 版本和工具要求不匹配。有些工具要求 Node 18 以上有些要求 20 以上。装之前先看工具的文档要求别想当然。6.3 排查的通用心法遇到报错先别急着搜。把报错信息完整读一遍很多时候答案就在里面。比如前面那个模型不支持的报错它明确告诉你是哪个模型名不支持你只要去核对就行。其次二分法定位。把链路拆成几段配置解析、环境变量、工具启动、网络请求。逐段验证能快速缩小范围。最后保留最小复现。把配置精简到只剩一个工具、一个模型如果这样能跑通再逐步加回去问题自然浮现。7. 一些延伸玩法和个人体会openrig 这套思路跑通之后能玩的花样其实不少。比如你可以给不同的项目配不同的 rig前端项目用响应快的模型后端重构用推理强的模型切换只改一行配置。也可以把配置模板化团队里共享一份基础配置各自覆盖自己的 key 和本地路径。我还试过把 openrig 和 VS Code 的任务系统结合一键启动对应的 AI 助手省去手动敲命令的步骤。对于经常在多个工具间切换的人来说这种自动化能省下不少零碎时间。最后分享一个小技巧给配置文件加版本号字段。工具在迭代配置格式也可能变有了版本号将来迁移或兼容处理会方便很多。这个习惯在配置管理里很值钱早养成早受益。这套东西说到底核心不是某个具体工具而是把配置和工具解耦的思路。工具会换模型会更新但一套清晰的配置层能让你在变化里始终保持主动。