1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设的开源项目毕竟 rig 这个词在英文里本就有“装配、设备”的意思。但翻了一圈社区讨论和仓库结构之后才反应过来它其实是围绕 AI 编程助手生态做的一套配置编排方案核心解决的是同一个开发环境里同时跑 Claude Code、Codex 这类命令行智能体时配置互相打架、模型端点切换混乱的问题。说白了openrig 就是给你的 AI 编程工具链做“统一接线板”的那一层。你可能会问为什么需要这么个东西。我举个自己踩过的真实场景我本地同时装了 Claude Code 和 Codex CLI前者默认走 Anthropic 的端点后者默认走 OpenAI 的端点但我又想让它们都能调用本地 LM Studio 里跑的开源模型或者临时切到 DeepSeek、Qwen、GLM 这些第三方 API。结果就是每换一次模型我得手动改好几个配置文件改完 Claude Code 能用了Codex 那边又报cc switch local proxy failed while handling codex endpoint /responses这种错。openrig 要干的事就是把这些散落在不同工具、不同目录下的 YAML 配置、环境变量、代理转发规则收敛到一处统一管理。它适合谁呢我觉得有三类人最该关注。第一类是同时使用多个 AI 编程助手的开发者尤其是那种“Claude Code 写前端、Codex 跑脚本”的双修党第二类是想把本地模型接入云端工具链的人比如用 LM Studio 或 Ollama 起服务再让 Claude Code 去调用第三类是做团队环境标准化的需要把一套可复现的配置分发给多个成员避免每个人机器上跑出来的行为都不一样。这三类需求背后其实指向同一个痛点AI 编程工具的配置层太碎了碎到没有一个统一的抽象层去管理。从技术栈上看openrig 依赖 Node.js 运行时配置文件以 YAML 为主这跟当前主流 AI CLI 工具的生态是吻合的。Claude Code 和 Codex 本身都是 Node.js 写的命令行工具它们的配置习惯也大量使用 YAML 和 JSON。所以 openrig 选择 Node.js YAML 这套组合不是拍脑袋决定的而是顺着生态惯性走降低接入成本。你不需要额外装 Python 环境或者 Go 工具链一个node -v能跑起来基本就具备使用条件了。2. 核心设计思路与方案选型拆解2.1 为什么是 YAML 而不是 JSON 或 TOML配置文件格式的选择看着是小事实际影响很大。openrig 选 YAML 作为主要配置载体我认为有三个层面的考量。第一是可读性YAML 用缩进表达层级没有大括号和引号的视觉噪音对于需要频繁手改的模型端点、代理规则这类配置肉眼扫一遍就能定位问题。第二是注释支持JSON 原生不支持注释而实际运维中你经常需要标注“这行是临时测试用的”“这个 key 下个月过期”YAML 的#注释能直接写。第三是生态兼容Claude Code 和 Codex 自身的配置文件本来就大量使用 YAML 风格openrig 顺着这个习惯走迁移成本最低。但 YAML 也有坑最典型的就是缩进敏感。我见过太多人因为 tab 和空格混用导致解析失败报错信息还特别隐晦。所以 openrig 的配置里我建议统一用两个空格缩进并且在编辑器里开启“显示空白字符”从源头避免这类问题。另外 YAML 的布尔值解析也有陷阱yes、no、on、off在某些解析器里会被当成布尔值而不是字符串如果你某个字段确实要填这些词记得加引号。2.2 统一端点抽象层的价值openrig 最核心的设计我觉得是它做了一层端点抽象。什么意思呢就是不管你底层用的是 Anthropic 官方、OpenAI 官方、DeepSeek、Qwen 还是本地 LM Studio在 openrig 的配置里你都用同一套字段来描述比如base_url、api_key、model、provider_type。上层工具Claude Code、Codex只管调用 openrig 暴露出来的统一接口不需要关心底层到底连的是谁。这个设计的价值在于解耦。以前你换一个模型供应商得去改 Claude Code 的配置、再改 Codex 的配置、可能还要改环境变量改完还得重启所有工具。现在你只改 openrig 里的一处配置上层工具无感知。这就像家里所有电器都插在一个带开关的插线板上你要换供电来源只需要动插线板那一端不用把每个电器都拆开。2.3 代理转发与端点路由的处理逻辑热词里出现了cc switch local proxy failed while handling codex endpoint /responses这个报错这其实暴露了一个关键问题Claude Code 和 Codex 的 API 路径结构不一样。Claude Code 走的是 Anthropic 风格的/v1/messagesCodex 走的是 OpenAI 风格的/v1/responses或/v1/chat/completions。当你用一个本地代理去同时服务这两个工具时代理必须能识别请求路径并把它路由到正确的后端。openrig 在这块的思路是按路径前缀做路由分发。配置里你会看到类似这样的结构/responses开头的请求转发到 Codex 对应的后端/messages开头的转发到 Claude Code 对应的后端。如果路由规则没配对就会出现“代理收到了请求但不知道怎么转发”的情况表现就是那个failed while handling codex endpoint的报错。理解这一点后面排查问题就有方向了。3. 环境准备与依赖安装实操3.1 Node.js 版本选择与安装避坑openrig 跑在 Node.js 上所以第一步是把 Node.js 装好。这里有个热词提到的报错值得单独说error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个错误的本质是你指定的版本号在官方源里根本不存在可能是版本号写错了也可能是那个版本还没正式发布。我的建议是不要手动指定过于具体的版本号直接用 LTS 版本最稳。安装方式我推荐两种。第一种是去 Node.js 官网下载 LTS 安装包Windows 和 macOS 都有图形化安装程序一路下一步就行。第二种是用版本管理工具比如nvmNode Version Manager这样你可以在多个 Node 版本之间切换遇到某个工具只兼容特定版本时特别有用。Linux 和 macOS 上装 nvm 的命令大致是这样curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完之后重新打开终端然后nvm install --lts nvm use --lts node -v npm -vWindows 用户可以用nvm-windows安装包在它的 GitHub releases 页面能下到。装完同样用nvm install lts和nvm use lts来管理。注意如果你之前用系统包管理器装过 Node.js再装 nvm 可能会冲突。建议先把旧的卸干净确认which node找不到残留再装 nvm。3.2 包管理器与全局安装路径Node.js 装好后自带 npm但 npm 的全局安装路径有时候会有权限问题尤其在 Linux 和 macOS 上。如果你执行npm install -g时报EACCES权限错误不要直接用sudo硬上那样会把全局包装到 root 目录下后续管理很麻烦。正确做法是给 npm 配置一个用户级的全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到你的PATH环境变量里。在~/.bashrc或~/.zshrc末尾加一行export PATH~/.npm-global/bin:$PATH重新加载配置source ~/.zshrc再npm install -g就不会有权限问题了。这一步看着琐碎但能省掉后面无数次的权限报错。3.3 Claude Code 与 Codex 的安装顺序openrig 本身是编排层它依赖 Claude Code 和 Codex 这些被编排的工具已经装好。安装顺序我建议是先装 Node.js再装 Claude Code再装 Codex最后装 openrig。原因是 openrig 在初始化时会去探测这两个工具的存在和版本如果它们还没装openrig 的自动配置功能会失效你得手动填一堆路径。Claude Code 的安装官方推荐用 npm 全局装npm install -g anthropic-ai/claude-code装完执行claude --version验证。Codex 的安装类似具体包名以官方文档为准装完用codex --version验证。两个都能正常输出版本号之后再装 openrig。提示如果你在 VS Code 里用 Claude Code 扩展注意扩展版本和 CLI 版本要匹配。我遇到过扩展更新了但 CLI 没更新导致vscode配置claude code时连接失败的情况。养成习惯扩展和 CLI 一起更新。4. openrig 配置文件详解与实操4.1 配置文件结构与字段含义openrig 的主配置文件通常叫openrig.yaml放在项目根目录或者用户主目录下的.openrig/文件夹里。一个典型的配置结构大概长这样version: 1 providers: - name: local-lmstudio type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - qwen2.5-coder-7b - deepseek-coder-v2 - name: deepseek-cloud type: openai-compatible base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} models: - deepseek-chat routes: - match: /v1/messages provider: local-lmstudio model: qwen2.5-coder-7b - match: /v1/responses provider: deepseek-cloud model: deepseek-chat这里几个关键字段我逐个解释。providers是后端供应商列表每个供应商有name自定义标识、type协议类型常见的是openai-compatible和anthropic、base_url端点地址、api_key密钥支持环境变量引用、models该供应商支持的模型列表。routes是路由规则match是请求路径前缀provider指定用哪个供应商model指定默认模型。api_key用${DEEPSEEK_API_KEY}这种写法是引用环境变量好处是密钥不落在配置文件里避免误提交到代码仓库。你需要在 shell 里export DEEPSEEK_API_KEY你的密钥或者在.env文件里定义。4.2 本地模型接入的完整流程把本地 LM Studio 的模型接入 openrig是我用得最多的场景。完整流程分四步。第一步在 LM Studio 里加载模型并启动本地服务默认端口是 1234服务地址是http://127.0.0.1:1234/v1。第二步在 openrig 配置里加一个openai-compatible类型的 providerbase_url填上面那个地址api_key随便填个占位符因为本地服务通常不校验密钥。第三步在models列表里填上你在 LM Studio 里加载的模型标识这个标识要跟 LM Studio 里显示的一致。第四步在routes里把 Claude Code 的/v1/messages路径指到这个 provider。这里有个细节容易翻车LM Studio 的模型标识有时候带版本后缀比如qwen2.5-coder-7b-instruct你配置里写qwen2.5-coder-7b就会报模型不存在。最稳妥的办法是先用 curl 探一下curl http://127.0.0.1:1234/v1/models返回的 JSON 里id字段就是准确的模型标识直接复制到配置里。4.3 第三方 API 接入与密钥管理接入 DeepSeek、Qwen、GLM 这些第三方 API流程跟本地模型类似区别在于base_url要换成官方端点api_key要填真实密钥。以 DeepSeek 为例base_url是https://api.deepseek.com/v1模型填deepseek-chat或deepseek-reasoner。Qwen 的兼容端点、GLM 的兼容端点也都能用同样的openai-compatible类型接入。密钥管理我强烈建议用环境变量不要硬编码。如果你有多个密钥可以统一放在一个.env文件里然后 openrig 启动时加载。.env文件记得加到.gitignore里防止误提交。团队协作时每个人维护自己的.env配置文件本身可以共享这样既统一了结构又隔离了敏感信息。注意有些第三方 API 对请求频率有限制如果你同时用 Claude Code 和 Codex 打同一个端点可能触发限流。openrig 的routes支持给不同工具分配不同 provider把负载分散开这是个实用的规避手段。5. 常见报错排查与避坑经验5.1 代理转发失败的典型原因回到热词里那个cc switch local proxy failed while handling codex endpoint /responses报错。这个错误的字面意思是代理在处理 Codex 的/responses端点请求时失败了。可能的原因我梳理成一张表报错现象可能原因排查方法failed while handling codex endpoint路由规则没匹配到/responses检查routes里是否有/v1/responses或/responses的匹配项连接被拒绝后端服务没启动curl一下base_url看是否可达401 未授权api_key 缺失或错误检查环境变量是否导出密钥是否过期模型不存在模型标识写错用/v1/models端点列出可用模型超时后端响应太慢或网络不通加大超时配置检查网络连通性排查顺序我建议从下往上先确认后端服务活着再确认密钥有效再确认模型标识正确最后确认路由规则匹配。这样一层层排除比盲目改配置高效得多。5.2 组织策略限制导致的订阅访问问题热词里还有一条your organization has disabled claude subscription access for claude code这个报错跟 openrig 本身关系不大但会影响你的使用体验。它的意思是你的组织管理员在后台关闭了 Claude Code 的订阅访问权限。遇到这种情况你能做的有限要么联系组织管理员开通要么改用 API 密钥方式而不是订阅方式接入。openrig 的配置里如果用的是 API 密钥模式就不受订阅策略影响这也是我推荐用 API 密钥的一个附带好处。5.3 模型不支持类报错的处理热词里有个the gpt-5.6-sol model is not supported when using codex with a的报错这类“模型不支持”的错误通常有两个来源。一是模型标识拼写错误比如把gpt-4写成gpt-5.6-sol这种不存在的名字。二是该模型确实不被当前工具支持比如某些工具只支持特定系列的模型。处理办法是先确认模型标识的准确性再确认该工具官方文档里列出的支持模型范围。openrig 的models列表可以起到白名单的作用把确认可用的模型列进去避免误填。5.4 我踩过的三个坑第一个坑是YAML 缩进用了 tab。当时配置文件看着没问题但 openrig 启动就报解析错误报错信息还指向一个完全无关的行号。后来用cat -A openrig.yaml一看混了 tab 和空格。从那以后我所有 YAML 文件都强制两个空格缩进。第二个坑是环境变量没生效。我在.zshrc里 export 了密钥但 openrig 是在另一个终端窗口启动的那个窗口没加载新配置。解决办法是source ~/.zshrc或者干脆重开终端。更稳妥的做法是用.env文件配合 dotenv 加载不依赖 shell 环境。第三个坑是端口冲突。本地 LM Studio 默认 1234 端口但我另一个服务也占了 1234导致 openrig 连过去连到了错误的服 openrig 配置编排：统一管理 Claude Code 与 Codex 的 AI 编程工具链
1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设的开源项目毕竟 rig 这个词在英文里本就有“装配、设备”的意思。但翻了一圈社区讨论和仓库结构之后才反应过来它其实是围绕 AI 编程助手生态做的一套配置编排方案核心解决的是同一个开发环境里同时跑 Claude Code、Codex 这类命令行智能体时配置互相打架、模型端点切换混乱的问题。说白了openrig 就是给你的 AI 编程工具链做“统一接线板”的那一层。你可能会问为什么需要这么个东西。我举个自己踩过的真实场景我本地同时装了 Claude Code 和 Codex CLI前者默认走 Anthropic 的端点后者默认走 OpenAI 的端点但我又想让它们都能调用本地 LM Studio 里跑的开源模型或者临时切到 DeepSeek、Qwen、GLM 这些第三方 API。结果就是每换一次模型我得手动改好几个配置文件改完 Claude Code 能用了Codex 那边又报cc switch local proxy failed while handling codex endpoint /responses这种错。openrig 要干的事就是把这些散落在不同工具、不同目录下的 YAML 配置、环境变量、代理转发规则收敛到一处统一管理。它适合谁呢我觉得有三类人最该关注。第一类是同时使用多个 AI 编程助手的开发者尤其是那种“Claude Code 写前端、Codex 跑脚本”的双修党第二类是想把本地模型接入云端工具链的人比如用 LM Studio 或 Ollama 起服务再让 Claude Code 去调用第三类是做团队环境标准化的需要把一套可复现的配置分发给多个成员避免每个人机器上跑出来的行为都不一样。这三类需求背后其实指向同一个痛点AI 编程工具的配置层太碎了碎到没有一个统一的抽象层去管理。从技术栈上看openrig 依赖 Node.js 运行时配置文件以 YAML 为主这跟当前主流 AI CLI 工具的生态是吻合的。Claude Code 和 Codex 本身都是 Node.js 写的命令行工具它们的配置习惯也大量使用 YAML 和 JSON。所以 openrig 选择 Node.js YAML 这套组合不是拍脑袋决定的而是顺着生态惯性走降低接入成本。你不需要额外装 Python 环境或者 Go 工具链一个node -v能跑起来基本就具备使用条件了。2. 核心设计思路与方案选型拆解2.1 为什么是 YAML 而不是 JSON 或 TOML配置文件格式的选择看着是小事实际影响很大。openrig 选 YAML 作为主要配置载体我认为有三个层面的考量。第一是可读性YAML 用缩进表达层级没有大括号和引号的视觉噪音对于需要频繁手改的模型端点、代理规则这类配置肉眼扫一遍就能定位问题。第二是注释支持JSON 原生不支持注释而实际运维中你经常需要标注“这行是临时测试用的”“这个 key 下个月过期”YAML 的#注释能直接写。第三是生态兼容Claude Code 和 Codex 自身的配置文件本来就大量使用 YAML 风格openrig 顺着这个习惯走迁移成本最低。但 YAML 也有坑最典型的就是缩进敏感。我见过太多人因为 tab 和空格混用导致解析失败报错信息还特别隐晦。所以 openrig 的配置里我建议统一用两个空格缩进并且在编辑器里开启“显示空白字符”从源头避免这类问题。另外 YAML 的布尔值解析也有陷阱yes、no、on、off在某些解析器里会被当成布尔值而不是字符串如果你某个字段确实要填这些词记得加引号。2.2 统一端点抽象层的价值openrig 最核心的设计我觉得是它做了一层端点抽象。什么意思呢就是不管你底层用的是 Anthropic 官方、OpenAI 官方、DeepSeek、Qwen 还是本地 LM Studio在 openrig 的配置里你都用同一套字段来描述比如base_url、api_key、model、provider_type。上层工具Claude Code、Codex只管调用 openrig 暴露出来的统一接口不需要关心底层到底连的是谁。这个设计的价值在于解耦。以前你换一个模型供应商得去改 Claude Code 的配置、再改 Codex 的配置、可能还要改环境变量改完还得重启所有工具。现在你只改 openrig 里的一处配置上层工具无感知。这就像家里所有电器都插在一个带开关的插线板上你要换供电来源只需要动插线板那一端不用把每个电器都拆开。2.3 代理转发与端点路由的处理逻辑热词里出现了cc switch local proxy failed while handling codex endpoint /responses这个报错这其实暴露了一个关键问题Claude Code 和 Codex 的 API 路径结构不一样。Claude Code 走的是 Anthropic 风格的/v1/messagesCodex 走的是 OpenAI 风格的/v1/responses或/v1/chat/completions。当你用一个本地代理去同时服务这两个工具时代理必须能识别请求路径并把它路由到正确的后端。openrig 在这块的思路是按路径前缀做路由分发。配置里你会看到类似这样的结构/responses开头的请求转发到 Codex 对应的后端/messages开头的转发到 Claude Code 对应的后端。如果路由规则没配对就会出现“代理收到了请求但不知道怎么转发”的情况表现就是那个failed while handling codex endpoint的报错。理解这一点后面排查问题就有方向了。3. 环境准备与依赖安装实操3.1 Node.js 版本选择与安装避坑openrig 跑在 Node.js 上所以第一步是把 Node.js 装好。这里有个热词提到的报错值得单独说error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个错误的本质是你指定的版本号在官方源里根本不存在可能是版本号写错了也可能是那个版本还没正式发布。我的建议是不要手动指定过于具体的版本号直接用 LTS 版本最稳。安装方式我推荐两种。第一种是去 Node.js 官网下载 LTS 安装包Windows 和 macOS 都有图形化安装程序一路下一步就行。第二种是用版本管理工具比如nvmNode Version Manager这样你可以在多个 Node 版本之间切换遇到某个工具只兼容特定版本时特别有用。Linux 和 macOS 上装 nvm 的命令大致是这样curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完之后重新打开终端然后nvm install --lts nvm use --lts node -v npm -vWindows 用户可以用nvm-windows安装包在它的 GitHub releases 页面能下到。装完同样用nvm install lts和nvm use lts来管理。注意如果你之前用系统包管理器装过 Node.js再装 nvm 可能会冲突。建议先把旧的卸干净确认which node找不到残留再装 nvm。3.2 包管理器与全局安装路径Node.js 装好后自带 npm但 npm 的全局安装路径有时候会有权限问题尤其在 Linux 和 macOS 上。如果你执行npm install -g时报EACCES权限错误不要直接用sudo硬上那样会把全局包装到 root 目录下后续管理很麻烦。正确做法是给 npm 配置一个用户级的全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到你的PATH环境变量里。在~/.bashrc或~/.zshrc末尾加一行export PATH~/.npm-global/bin:$PATH重新加载配置source ~/.zshrc再npm install -g就不会有权限问题了。这一步看着琐碎但能省掉后面无数次的权限报错。3.3 Claude Code 与 Codex 的安装顺序openrig 本身是编排层它依赖 Claude Code 和 Codex 这些被编排的工具已经装好。安装顺序我建议是先装 Node.js再装 Claude Code再装 Codex最后装 openrig。原因是 openrig 在初始化时会去探测这两个工具的存在和版本如果它们还没装openrig 的自动配置功能会失效你得手动填一堆路径。Claude Code 的安装官方推荐用 npm 全局装npm install -g anthropic-ai/claude-code装完执行claude --version验证。Codex 的安装类似具体包名以官方文档为准装完用codex --version验证。两个都能正常输出版本号之后再装 openrig。提示如果你在 VS Code 里用 Claude Code 扩展注意扩展版本和 CLI 版本要匹配。我遇到过扩展更新了但 CLI 没更新导致vscode配置claude code时连接失败的情况。养成习惯扩展和 CLI 一起更新。4. openrig 配置文件详解与实操4.1 配置文件结构与字段含义openrig 的主配置文件通常叫openrig.yaml放在项目根目录或者用户主目录下的.openrig/文件夹里。一个典型的配置结构大概长这样version: 1 providers: - name: local-lmstudio type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - qwen2.5-coder-7b - deepseek-coder-v2 - name: deepseek-cloud type: openai-compatible base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} models: - deepseek-chat routes: - match: /v1/messages provider: local-lmstudio model: qwen2.5-coder-7b - match: /v1/responses provider: deepseek-cloud model: deepseek-chat这里几个关键字段我逐个解释。providers是后端供应商列表每个供应商有name自定义标识、type协议类型常见的是openai-compatible和anthropic、base_url端点地址、api_key密钥支持环境变量引用、models该供应商支持的模型列表。routes是路由规则match是请求路径前缀provider指定用哪个供应商model指定默认模型。api_key用${DEEPSEEK_API_KEY}这种写法是引用环境变量好处是密钥不落在配置文件里避免误提交到代码仓库。你需要在 shell 里export DEEPSEEK_API_KEY你的密钥或者在.env文件里定义。4.2 本地模型接入的完整流程把本地 LM Studio 的模型接入 openrig是我用得最多的场景。完整流程分四步。第一步在 LM Studio 里加载模型并启动本地服务默认端口是 1234服务地址是http://127.0.0.1:1234/v1。第二步在 openrig 配置里加一个openai-compatible类型的 providerbase_url填上面那个地址api_key随便填个占位符因为本地服务通常不校验密钥。第三步在models列表里填上你在 LM Studio 里加载的模型标识这个标识要跟 LM Studio 里显示的一致。第四步在routes里把 Claude Code 的/v1/messages路径指到这个 provider。这里有个细节容易翻车LM Studio 的模型标识有时候带版本后缀比如qwen2.5-coder-7b-instruct你配置里写qwen2.5-coder-7b就会报模型不存在。最稳妥的办法是先用 curl 探一下curl http://127.0.0.1:1234/v1/models返回的 JSON 里id字段就是准确的模型标识直接复制到配置里。4.3 第三方 API 接入与密钥管理接入 DeepSeek、Qwen、GLM 这些第三方 API流程跟本地模型类似区别在于base_url要换成官方端点api_key要填真实密钥。以 DeepSeek 为例base_url是https://api.deepseek.com/v1模型填deepseek-chat或deepseek-reasoner。Qwen 的兼容端点、GLM 的兼容端点也都能用同样的openai-compatible类型接入。密钥管理我强烈建议用环境变量不要硬编码。如果你有多个密钥可以统一放在一个.env文件里然后 openrig 启动时加载。.env文件记得加到.gitignore里防止误提交。团队协作时每个人维护自己的.env配置文件本身可以共享这样既统一了结构又隔离了敏感信息。注意有些第三方 API 对请求频率有限制如果你同时用 Claude Code 和 Codex 打同一个端点可能触发限流。openrig 的routes支持给不同工具分配不同 provider把负载分散开这是个实用的规避手段。5. 常见报错排查与避坑经验5.1 代理转发失败的典型原因回到热词里那个cc switch local proxy failed while handling codex endpoint /responses报错。这个错误的字面意思是代理在处理 Codex 的/responses端点请求时失败了。可能的原因我梳理成一张表报错现象可能原因排查方法failed while handling codex endpoint路由规则没匹配到/responses检查routes里是否有/v1/responses或/responses的匹配项连接被拒绝后端服务没启动curl一下base_url看是否可达401 未授权api_key 缺失或错误检查环境变量是否导出密钥是否过期模型不存在模型标识写错用/v1/models端点列出可用模型超时后端响应太慢或网络不通加大超时配置检查网络连通性排查顺序我建议从下往上先确认后端服务活着再确认密钥有效再确认模型标识正确最后确认路由规则匹配。这样一层层排除比盲目改配置高效得多。5.2 组织策略限制导致的订阅访问问题热词里还有一条your organization has disabled claude subscription access for claude code这个报错跟 openrig 本身关系不大但会影响你的使用体验。它的意思是你的组织管理员在后台关闭了 Claude Code 的订阅访问权限。遇到这种情况你能做的有限要么联系组织管理员开通要么改用 API 密钥方式而不是订阅方式接入。openrig 的配置里如果用的是 API 密钥模式就不受订阅策略影响这也是我推荐用 API 密钥的一个附带好处。5.3 模型不支持类报错的处理热词里有个the gpt-5.6-sol model is not supported when using codex with a的报错这类“模型不支持”的错误通常有两个来源。一是模型标识拼写错误比如把gpt-4写成gpt-5.6-sol这种不存在的名字。二是该模型确实不被当前工具支持比如某些工具只支持特定系列的模型。处理办法是先确认模型标识的准确性再确认该工具官方文档里列出的支持模型范围。openrig 的models列表可以起到白名单的作用把确认可用的模型列进去避免误填。5.4 我踩过的三个坑第一个坑是YAML 缩进用了 tab。当时配置文件看着没问题但 openrig 启动就报解析错误报错信息还指向一个完全无关的行号。后来用cat -A openrig.yaml一看混了 tab 和空格。从那以后我所有 YAML 文件都强制两个空格缩进。第二个坑是环境变量没生效。我在.zshrc里 export 了密钥但 openrig 是在另一个终端窗口启动的那个窗口没加载新配置。解决办法是source ~/.zshrc或者干脆重开终端。更稳妥的做法是用.env文件配合 dotenv 加载不依赖 shell 环境。第三个坑是端口冲突。本地 LM Studio 默认 1234 端口但我另一个服务也占了 1234导致 openrig 连过去连到了错误的服