1. 从 openrig 这个标题说起它到底想解决什么问题第一次看到 openrig 这个名字我脑子里蹦出来的第一个念头是“open rig”也就是“开放式的设备/工具架”。在 AI 编程助手这个圈子里这个命名其实非常贴切——它想做的事情就是把 Claude Code、Codex 这类命令行 AI 编程工具和本地模型、第三方 API、各种配置项“架”在一起让它们能协同工作而不是各自为政。我接触 Claude Code 和 Codex 有一段时间了最开始是单独用 Claude Code 写代码后来发现 Codex 在某些场景下补全和推理更顺手于是就想两个都用。问题随之而来两套工具各有各的配置文件、各有各的环境变量、各有各的模型接入方式切换一次要改一堆东西稍不注意就报错。openrig 这类工具出现的背景正是为了解决这种“多工具、多模型、多配置”的混乱局面。具体来说openrig 面向的是这样一群人你已经在用或者准备用 Claude Code、Codex 这类 AI 编程 CLI 工具你希望接入本地模型比如通过 LM Studio 跑起来的模型或者第三方 API你不想每次切换工具都手动改配置文件你希望有一套统一的 YAML 配置来管理这些工具的接入参数。如果你符合其中任意一条那 openrig 这个方向的东西就值得你花时间研究。它解决的核心问题可以归纳为三点。第一是配置统一把散落在各个工具目录下的配置收敛到一套 YAML 里第二是模型接入标准化不管是本地模型还是远程 API都用统一的接口描述第三是切换成本降低改一个字段就能换模型、换端点不用去翻每个工具的文档。这三点听起来简单但真正落地的时候坑非常多后面我会逐个拆开讲。2. 核心概念拆解Claude Code、Codex 与 YAML 配置的关系2.1 Claude Code 和 Codex 各自是什么定位Claude Code 是 Anthropic 推出的命令行编程助手它的特点是能直接在你的终端里执行命令、读写文件、跑测试相当于一个能动手的编程搭档。Codex 则是 OpenAI 系的命令行工具偏向代码生成和补全在接入第三方模型方面比较灵活。两者定位有重叠但使用手感差别不小Claude Code 更“主动”会自己规划步骤去改代码Codex 更“听话”你让它改哪它就改哪。很多人一开始只用一个用着用着发现另一个在某些任务上更合适于是就想两个都装。但两个工具的配置体系完全不一样。Claude Code 走的是它自己的一套配置目录和环境变量Codex 走的是另一套。你要接入本地模型还得再折腾 LM Studio 或者类似的本地推理服务。三套东西叠在一起配置文件能绕晕人。2.2 YAML 在这里扮演什么角色YAML 是一种对人类友好的数据序列化格式用缩进表示层级读起来像清单。在 openrig 这类工具里YAML 通常承担“总配置单”的角色哪个工具用哪个模型、端点地址是什么、API Key 从哪个环境变量读、超时设多久全部写在一个文件里。为什么选 YAML 而不是 JSON 或 TOML我自己的体会是YAML 写注释方便层级表达直观改起来不容易出错。JSON 不支持注释配置一多就没法标注TOML 虽然也友好但在嵌套结构上不如 YAML 灵活。对于“一个工具下挂多个模型、一个模型下挂多个参数”这种结构YAML 是最顺手的。一个典型的 openrig 风格配置大概长这样tools: claude-code: model: local-qwen endpoint: http://127.0.0.1:1234/v1 api_key_env: LOCAL_API_KEY timeout: 120 codex: model: deepseek-chat endpoint: https://api.example.com/v1 api_key_env: DEEPSEEK_API_KEY timeout: 60 models: local-qwen: provider: openai-compatible context_window: 32768 deepseek-chat: provider: openai-compatible context_window: 65536这段配置的意思是Claude Code 用本地跑的 qwen 模型Codex 用远程的 deepseek-chat两者的端点、密钥来源、超时都分开管理。改模型只需要改model字段不用去动工具本身的任何文件。2.3 Node.js 为什么绕不开Claude Code 和 Codex 的 CLI 基本都是 Node.js 生态的产物安装方式通常是npm install -g。这意味着你机器上必须有一个能用的 Node.js 环境。这里有个高频坑Node.js 版本不对安装直接失败。热搜词里那条 “error installing 24.21.0: node.js v24.21.0 is not yet released” 就是典型症状——你照着某个教程敲了命令但那个版本号根本不存在或者还没发布。我的建议是永远装 LTS 版本去 Node.js 官网下载页选 “LTS” 那个按钮不要追最新的 Current 版本。LTS 版本经过长时间验证和 npm 生态兼容性最好。装完之后用node -v和npm -v确认两个命令都能正常输出版本号才算环境就绪。3. 环境搭建实操从零把 openrig 这套东西跑起来3.1 Node.js 安装与版本管理先说安装。Windows 用户直接去官网下载 LTS 的 msi 安装包一路下一步即可。macOS 用户可以用 Homebrewbrew install node20这种指定大版本的方式更稳。Ubuntu 用户我强烈建议不要用apt install nodejs因为系统源里的版本往往很旧装 Claude Code 或 Codex 时容易报兼容性错误。Ubuntu 上更靠谱的做法是用 NodeSource 的脚本装指定大版本curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完验证node -v npm -v如果输出类似v20.11.0和10.2.4就说明没问题。这里有个细节如果你之前装过旧版本先sudo apt remove nodejs清干净再装否则可能出现两个版本打架node -v显示的版本和你以为的不一样。提示不要同时用 nvm 和系统包管理器装 Node.js两者会互相干扰。选一种方式坚持用到底。3.2 Claude Code 与 Codex 的安装Node.js 就绪后安装这两个 CLI 就是一条命令的事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看全局目录在哪然后把这个目录下的 bin 加进 PATH。这里踩过的坑是权限问题。在 Linux 和 macOS 上如果不用 sudo 装全局包有时会因为目录权限报错。我的做法是配置 npm 的全局目录到用户目录下避免每次都要 sudomkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后那行 export 写进~/.bashrc或~/.zshrc以后开终端就自动生效。3.3 本地模型服务的准备如果你想接入本地模型需要先有一个本地推理服务在跑。LM Studio 是比较省事的选择图形界面点几下就能把模型跑起来并且它默认会暴露一个 OpenAI 兼容的端点通常是http://127.0.0.1:1234/v1。启动模型后在 LM Studio 的开发者页面能看到这个地址用浏览器访问一下确认有响应。这一步的关键是确认端点真的通了。我见过太多人配置写好了结果模型服务根本没启动或者端口被占用换了端口却没改配置。先用 curl 测一下curl http://127.0.0.1:1234/v1/models能返回模型列表说明服务正常。返回连接拒绝就是服务没起来或者端口不对。3.4 用 YAML 把配置串起来环境都就绪后就到了 openrig 的核心环节写 YAML 配置。我建议在项目根目录建一个openrig.yaml把所有工具的接入信息集中管理。写的时候注意几个点缩进必须用空格不能用 Tab字符串里的特殊字符要加引号环境变量名要和实际设置的一致。配置写完后用工具提供的加载命令让它生效。不同实现方式不一样有的是openrig apply有的是在启动 Claude Code 或 Codex 时通过参数指定配置文件。具体命令要看 openrig 本身的文档但思路是一致的让工具读取这份 YAML而不是去读它默认的配置。4. 模型接入的深水区本地模型与第三方 API 的差异处理4.1 本地模型接入的常见问题本地模型最大的优势是数据不出本机隐私性好而且不花钱。但它的坑也不少。第一个坑是上下文窗口。本地跑的模型往往上下文窗口比云端小比如 32K 甚至 8K。如果你在 YAML 里把context_window写大了工具会以为模型能处理那么长的输入结果一超限就报错或者截断。所以这个值必须和模型实际能力一致。第二个坑是推理速度。本地模型受限于你的显卡和内存生成速度可能比云端慢很多。这时候timeout就要设大一点默认的 30 秒可能不够设成 120 秒甚至 300 秒更稳妥。我自己的经验是本地模型跑复杂任务时超时设 180 秒起步不然经常在快出结果的时候被掐断。第三个坑是模型名称匹配。有些工具会校验模型名你写了个它不认识的名称就直接拒绝。解决办法是先用/v1/models端点查一下服务实际暴露的模型名照着填。4.2 第三方 API 接入的注意事项第三方 API 的接入相对标准化基本都是 OpenAI 兼容格式。但有几个细节容易翻车。一是 API Key 的管理千万不要把 Key 直接写进 YAML 明文里而是通过环境变量引用。YAML 里写api_key_env: DEEPSEEK_API_KEY然后在 shell 里export DEEPSEEK_API_KEY你的key。这样配置文件可以放心提交到版本库不会泄露密钥。二是端点地址的路径。有些服务商的端点是https://api.example.com/v1有些是https://api.example.com少写或多写/v1都会导致 404。接入前先看服务商文档确认完整路径。三是模型名的差异。同一个服务商不同模型的名称格式可能不一样有的带前缀有的不带。填错模型名请求会返回“模型不存在”之类的错误。4.3 用一张表看清本地与远程的配置差异配置项本地模型第三方 API端点地址http://127.0.0.1:端口/v1https://服务商域名/v1API Key通常任意填或留空必须真实有效上下文窗口按模型实际能力填偏小一般较大按文档填超时设置建议 120 秒以上60 秒左右即可网络依赖无需要稳定网络成本电费按量计费这张表是我自己踩坑总结出来的照着填能避开大部分低级错误。5. 常见报错与排查技巧实录5.1 安装阶段的典型报错“error installing 24.21.0: node.js v24.21.0 is not yet released” 这个报错根源是你指定的 Node.js 版本号不存在。解决办法是去官网确认当前 LTS 版本号或者直接用nvm install --lts让工具自己选。不要凭记忆敲版本号。“npm ERR! code EACCES” 是权限问题前面说的配置用户级全局目录就能解决。如果不想改目录临时用 sudo 也能过但长期看还是改目录更干净。“command not found: claude” 是 PATH 问题确认 npm 全局 bin 目录在 PATH 里。用npm bin -g或npm config get prefix找到目录手动加进 PATH。5.2 运行阶段的典型报错“cc switch local proxy failed while handling codex endpoint /responses” 这类报错通常出现在用中间层代理转发请求的场景。核心原因是代理没有正确处理 Codex 的/responses端点。排查思路是先确认代理服务本身在跑再确认代理配置里/responses路径有没有被正确转发最后看代理日志里请求到底发到了哪里。很多时候是路径拼接多了或少了斜杠。“codex is ignoring 1 unrecognized configuration setting” 是配置项名称写错了。Codex 对配置项名称校验比较严拼错一个字母它就忽略。解决办法是照着官方文档的配置项列表逐字核对别自己造名字。“your organization has disabled claude subscription access” 是账号层面的限制和本地配置无关。这种情况需要检查账号的订阅状态和组织设置不是改配置文件能解决的。5.3 排查速查表报错关键词可能原因排查动作not yet released版本号不存在查官网确认 LTS 版本EACCES全局目录权限不足配置用户级 npm 目录command not foundPATH 未包含 bin 目录检查并添加 PATHlocal proxy failed代理路径转发错误查代理日志和路径拼接unrecognized setting配置项名称拼写错误对照官方文档核对organization disabled账号订阅限制检查账号状态提示遇到报错先看完整错误信息不要只看第一行。很多关键线索在后面的堆栈里。6. 我踩过的坑和几条实用经验第一个经验是关于配置文件的版本管理。我一开始把 API Key 直接写在 YAML 里后来意识到这样提交到 Git 会泄露改成环境变量引用后才安心。现在我的做法是 YAML 里只写api_key_env真正的 Key 放在.env文件里.env加进.gitignore。这样配置可以共享密钥不会外泄。第二个经验是关于模型切换的测试。每次改完 YAML 里的模型配置不要直接上复杂任务先用一个简单请求测通。比如让工具解释一段短代码确认能正常返回再去跑大任务。这样能把配置问题和模型能力问题分开排查起来快很多。第三个经验是关于超时和重试。本地模型偶尔会因为显存不足卡住这时候如果超时设得太短请求会被反复掐断重试反而更慢。我的做法是超时设长一点同时关掉自动重试让它一次跑完。如果确实卡死手动中断再排查显存问题。第四个经验是关于多工具共存。Claude Code 和 Codex 装在同一台机器上时注意它们的配置目录不要互相覆盖。openrig 这类工具的价值就在于把配置集中管理避免你手动去改每个工具的目录。如果你不用 openrig至少也要把两个工具的配置目录分开记清楚别改混了。最后说一个关于 YAML 缩进的细节。YAML 对缩进极其敏感多一个空格少一个空格都可能解析失败。我建议用支持 YAML 语法高亮的编辑器比如 VS Code 装个 YAML 插件缩进错了会直接标红。写完之后用在线 YAML 校验工具过一遍能省掉很多莫名其妙的报错。这套东西搭起来之后日常使用其实很省心。改模型就是改一行配置切换工具就是改一个字段不用再去翻每个工具的文档。前期花一两个小时把环境和配置理顺后面能省下大量折腾的时间。 openrig 实战：统一管理 Claude Code 与 Codex 的 YAML 配置与模型接入
1. 从 openrig 这个标题说起它到底想解决什么问题第一次看到 openrig 这个名字我脑子里蹦出来的第一个念头是“open rig”也就是“开放式的设备/工具架”。在 AI 编程助手这个圈子里这个命名其实非常贴切——它想做的事情就是把 Claude Code、Codex 这类命令行 AI 编程工具和本地模型、第三方 API、各种配置项“架”在一起让它们能协同工作而不是各自为政。我接触 Claude Code 和 Codex 有一段时间了最开始是单独用 Claude Code 写代码后来发现 Codex 在某些场景下补全和推理更顺手于是就想两个都用。问题随之而来两套工具各有各的配置文件、各有各的环境变量、各有各的模型接入方式切换一次要改一堆东西稍不注意就报错。openrig 这类工具出现的背景正是为了解决这种“多工具、多模型、多配置”的混乱局面。具体来说openrig 面向的是这样一群人你已经在用或者准备用 Claude Code、Codex 这类 AI 编程 CLI 工具你希望接入本地模型比如通过 LM Studio 跑起来的模型或者第三方 API你不想每次切换工具都手动改配置文件你希望有一套统一的 YAML 配置来管理这些工具的接入参数。如果你符合其中任意一条那 openrig 这个方向的东西就值得你花时间研究。它解决的核心问题可以归纳为三点。第一是配置统一把散落在各个工具目录下的配置收敛到一套 YAML 里第二是模型接入标准化不管是本地模型还是远程 API都用统一的接口描述第三是切换成本降低改一个字段就能换模型、换端点不用去翻每个工具的文档。这三点听起来简单但真正落地的时候坑非常多后面我会逐个拆开讲。2. 核心概念拆解Claude Code、Codex 与 YAML 配置的关系2.1 Claude Code 和 Codex 各自是什么定位Claude Code 是 Anthropic 推出的命令行编程助手它的特点是能直接在你的终端里执行命令、读写文件、跑测试相当于一个能动手的编程搭档。Codex 则是 OpenAI 系的命令行工具偏向代码生成和补全在接入第三方模型方面比较灵活。两者定位有重叠但使用手感差别不小Claude Code 更“主动”会自己规划步骤去改代码Codex 更“听话”你让它改哪它就改哪。很多人一开始只用一个用着用着发现另一个在某些任务上更合适于是就想两个都装。但两个工具的配置体系完全不一样。Claude Code 走的是它自己的一套配置目录和环境变量Codex 走的是另一套。你要接入本地模型还得再折腾 LM Studio 或者类似的本地推理服务。三套东西叠在一起配置文件能绕晕人。2.2 YAML 在这里扮演什么角色YAML 是一种对人类友好的数据序列化格式用缩进表示层级读起来像清单。在 openrig 这类工具里YAML 通常承担“总配置单”的角色哪个工具用哪个模型、端点地址是什么、API Key 从哪个环境变量读、超时设多久全部写在一个文件里。为什么选 YAML 而不是 JSON 或 TOML我自己的体会是YAML 写注释方便层级表达直观改起来不容易出错。JSON 不支持注释配置一多就没法标注TOML 虽然也友好但在嵌套结构上不如 YAML 灵活。对于“一个工具下挂多个模型、一个模型下挂多个参数”这种结构YAML 是最顺手的。一个典型的 openrig 风格配置大概长这样tools: claude-code: model: local-qwen endpoint: http://127.0.0.1:1234/v1 api_key_env: LOCAL_API_KEY timeout: 120 codex: model: deepseek-chat endpoint: https://api.example.com/v1 api_key_env: DEEPSEEK_API_KEY timeout: 60 models: local-qwen: provider: openai-compatible context_window: 32768 deepseek-chat: provider: openai-compatible context_window: 65536这段配置的意思是Claude Code 用本地跑的 qwen 模型Codex 用远程的 deepseek-chat两者的端点、密钥来源、超时都分开管理。改模型只需要改model字段不用去动工具本身的任何文件。2.3 Node.js 为什么绕不开Claude Code 和 Codex 的 CLI 基本都是 Node.js 生态的产物安装方式通常是npm install -g。这意味着你机器上必须有一个能用的 Node.js 环境。这里有个高频坑Node.js 版本不对安装直接失败。热搜词里那条 “error installing 24.21.0: node.js v24.21.0 is not yet released” 就是典型症状——你照着某个教程敲了命令但那个版本号根本不存在或者还没发布。我的建议是永远装 LTS 版本去 Node.js 官网下载页选 “LTS” 那个按钮不要追最新的 Current 版本。LTS 版本经过长时间验证和 npm 生态兼容性最好。装完之后用node -v和npm -v确认两个命令都能正常输出版本号才算环境就绪。3. 环境搭建实操从零把 openrig 这套东西跑起来3.1 Node.js 安装与版本管理先说安装。Windows 用户直接去官网下载 LTS 的 msi 安装包一路下一步即可。macOS 用户可以用 Homebrewbrew install node20这种指定大版本的方式更稳。Ubuntu 用户我强烈建议不要用apt install nodejs因为系统源里的版本往往很旧装 Claude Code 或 Codex 时容易报兼容性错误。Ubuntu 上更靠谱的做法是用 NodeSource 的脚本装指定大版本curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完验证node -v npm -v如果输出类似v20.11.0和10.2.4就说明没问题。这里有个细节如果你之前装过旧版本先sudo apt remove nodejs清干净再装否则可能出现两个版本打架node -v显示的版本和你以为的不一样。提示不要同时用 nvm 和系统包管理器装 Node.js两者会互相干扰。选一种方式坚持用到底。3.2 Claude Code 与 Codex 的安装Node.js 就绪后安装这两个 CLI 就是一条命令的事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看全局目录在哪然后把这个目录下的 bin 加进 PATH。这里踩过的坑是权限问题。在 Linux 和 macOS 上如果不用 sudo 装全局包有时会因为目录权限报错。我的做法是配置 npm 的全局目录到用户目录下避免每次都要 sudomkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后那行 export 写进~/.bashrc或~/.zshrc以后开终端就自动生效。3.3 本地模型服务的准备如果你想接入本地模型需要先有一个本地推理服务在跑。LM Studio 是比较省事的选择图形界面点几下就能把模型跑起来并且它默认会暴露一个 OpenAI 兼容的端点通常是http://127.0.0.1:1234/v1。启动模型后在 LM Studio 的开发者页面能看到这个地址用浏览器访问一下确认有响应。这一步的关键是确认端点真的通了。我见过太多人配置写好了结果模型服务根本没启动或者端口被占用换了端口却没改配置。先用 curl 测一下curl http://127.0.0.1:1234/v1/models能返回模型列表说明服务正常。返回连接拒绝就是服务没起来或者端口不对。3.4 用 YAML 把配置串起来环境都就绪后就到了 openrig 的核心环节写 YAML 配置。我建议在项目根目录建一个openrig.yaml把所有工具的接入信息集中管理。写的时候注意几个点缩进必须用空格不能用 Tab字符串里的特殊字符要加引号环境变量名要和实际设置的一致。配置写完后用工具提供的加载命令让它生效。不同实现方式不一样有的是openrig apply有的是在启动 Claude Code 或 Codex 时通过参数指定配置文件。具体命令要看 openrig 本身的文档但思路是一致的让工具读取这份 YAML而不是去读它默认的配置。4. 模型接入的深水区本地模型与第三方 API 的差异处理4.1 本地模型接入的常见问题本地模型最大的优势是数据不出本机隐私性好而且不花钱。但它的坑也不少。第一个坑是上下文窗口。本地跑的模型往往上下文窗口比云端小比如 32K 甚至 8K。如果你在 YAML 里把context_window写大了工具会以为模型能处理那么长的输入结果一超限就报错或者截断。所以这个值必须和模型实际能力一致。第二个坑是推理速度。本地模型受限于你的显卡和内存生成速度可能比云端慢很多。这时候timeout就要设大一点默认的 30 秒可能不够设成 120 秒甚至 300 秒更稳妥。我自己的经验是本地模型跑复杂任务时超时设 180 秒起步不然经常在快出结果的时候被掐断。第三个坑是模型名称匹配。有些工具会校验模型名你写了个它不认识的名称就直接拒绝。解决办法是先用/v1/models端点查一下服务实际暴露的模型名照着填。4.2 第三方 API 接入的注意事项第三方 API 的接入相对标准化基本都是 OpenAI 兼容格式。但有几个细节容易翻车。一是 API Key 的管理千万不要把 Key 直接写进 YAML 明文里而是通过环境变量引用。YAML 里写api_key_env: DEEPSEEK_API_KEY然后在 shell 里export DEEPSEEK_API_KEY你的key。这样配置文件可以放心提交到版本库不会泄露密钥。二是端点地址的路径。有些服务商的端点是https://api.example.com/v1有些是https://api.example.com少写或多写/v1都会导致 404。接入前先看服务商文档确认完整路径。三是模型名的差异。同一个服务商不同模型的名称格式可能不一样有的带前缀有的不带。填错模型名请求会返回“模型不存在”之类的错误。4.3 用一张表看清本地与远程的配置差异配置项本地模型第三方 API端点地址http://127.0.0.1:端口/v1https://服务商域名/v1API Key通常任意填或留空必须真实有效上下文窗口按模型实际能力填偏小一般较大按文档填超时设置建议 120 秒以上60 秒左右即可网络依赖无需要稳定网络成本电费按量计费这张表是我自己踩坑总结出来的照着填能避开大部分低级错误。5. 常见报错与排查技巧实录5.1 安装阶段的典型报错“error installing 24.21.0: node.js v24.21.0 is not yet released” 这个报错根源是你指定的 Node.js 版本号不存在。解决办法是去官网确认当前 LTS 版本号或者直接用nvm install --lts让工具自己选。不要凭记忆敲版本号。“npm ERR! code EACCES” 是权限问题前面说的配置用户级全局目录就能解决。如果不想改目录临时用 sudo 也能过但长期看还是改目录更干净。“command not found: claude” 是 PATH 问题确认 npm 全局 bin 目录在 PATH 里。用npm bin -g或npm config get prefix找到目录手动加进 PATH。5.2 运行阶段的典型报错“cc switch local proxy failed while handling codex endpoint /responses” 这类报错通常出现在用中间层代理转发请求的场景。核心原因是代理没有正确处理 Codex 的/responses端点。排查思路是先确认代理服务本身在跑再确认代理配置里/responses路径有没有被正确转发最后看代理日志里请求到底发到了哪里。很多时候是路径拼接多了或少了斜杠。“codex is ignoring 1 unrecognized configuration setting” 是配置项名称写错了。Codex 对配置项名称校验比较严拼错一个字母它就忽略。解决办法是照着官方文档的配置项列表逐字核对别自己造名字。“your organization has disabled claude subscription access” 是账号层面的限制和本地配置无关。这种情况需要检查账号的订阅状态和组织设置不是改配置文件能解决的。5.3 排查速查表报错关键词可能原因排查动作not yet released版本号不存在查官网确认 LTS 版本EACCES全局目录权限不足配置用户级 npm 目录command not foundPATH 未包含 bin 目录检查并添加 PATHlocal proxy failed代理路径转发错误查代理日志和路径拼接unrecognized setting配置项名称拼写错误对照官方文档核对organization disabled账号订阅限制检查账号状态提示遇到报错先看完整错误信息不要只看第一行。很多关键线索在后面的堆栈里。6. 我踩过的坑和几条实用经验第一个经验是关于配置文件的版本管理。我一开始把 API Key 直接写在 YAML 里后来意识到这样提交到 Git 会泄露改成环境变量引用后才安心。现在我的做法是 YAML 里只写api_key_env真正的 Key 放在.env文件里.env加进.gitignore。这样配置可以共享密钥不会外泄。第二个经验是关于模型切换的测试。每次改完 YAML 里的模型配置不要直接上复杂任务先用一个简单请求测通。比如让工具解释一段短代码确认能正常返回再去跑大任务。这样能把配置问题和模型能力问题分开排查起来快很多。第三个经验是关于超时和重试。本地模型偶尔会因为显存不足卡住这时候如果超时设得太短请求会被反复掐断重试反而更慢。我的做法是超时设长一点同时关掉自动重试让它一次跑完。如果确实卡死手动中断再排查显存问题。第四个经验是关于多工具共存。Claude Code 和 Codex 装在同一台机器上时注意它们的配置目录不要互相覆盖。openrig 这类工具的价值就在于把配置集中管理避免你手动去改每个工具的目录。如果你不用 openrig至少也要把两个工具的配置目录分开记清楚别改混了。最后说一个关于 YAML 缩进的细节。YAML 对缩进极其敏感多一个空格少一个空格都可能解析失败。我建议用支持 YAML 语法高亮的编辑器比如 VS Code 装个 YAML 插件缩进错了会直接标红。写完之后用在线 YAML 校验工具过一遍能省掉很多莫名其妙的报错。这套东西搭起来之后日常使用其实很省心。改模型就是改一行配置切换工具就是改一个字段不用再去翻每个工具的文档。前期花一两个小时把环境和配置理顺后面能省下大量折腾的时间。