1. 从标题说起openrig 到底想解决什么问题第一次看到openrig这个名字我脑子里蹦出来的第一反应是“open”加“rig”——rig 在英文里本意是“装配、搭台子”在工程语境里常指把一堆零散部件组装成一套能跑起来的装置。把这两个词拼在一起基本就能猜到它的定位一套开放的、用来把 AI 编码工具链“搭起来”的脚手架或者配置框架。结合热搜词里高频出现的 Claude Code、Codex、YAML、Node.js这个判断基本可以坐实——openrig大概率是一个围绕命令行 AI 编码助手做统一配置、统一接入、统一管理的开源项目。为什么我这么判断因为最近这半年我身边做开发的朋友几乎人手一个 Claude Code 或者 Codex CLI但真正用顺手的没几个。问题不在于模型本身不行而在于“接入”这件事太碎了。你想让 Claude Code 走本地模型得改环境变量想让 Codex 接第三方兼容端点得动配置文件想在不同项目之间切换不同的模型供应商又得手动改一堆东西。每个人都在重复造轮子每个人踩的坑还都不一样。openrig这类项目出现的动机就是把这堆重复劳动收敛成一份可版本化、可复用、可分享的配置。所以这篇东西我打算按“一个真实使用者会怎么把它跑起来”的思路来写。不管你是刚听说 Claude Code 想试试水的新手还是已经在 Codex 和 Claude Code 之间来回横跳的老手只要你对“用一份配置管住多个 AI 编码工具”这件事有兴趣下面的内容应该都能直接用上。我会把 YAML 怎么写、Node.js 环境怎么备、Claude Code 和 Codex 分别怎么接、出问题怎么查一条条拆开讲清楚中间穿插我自己踩过的坑。2. 整体设计思路为什么是 YAML Node.js 这套组合2.1 用 YAML 做配置层是权衡之后的最优解先说说为什么这类工具几乎清一色选 YAML 而不是 JSON 或者 TOML。JSON 的问题在于不能写注释你配置一个模型端点想标注“这个是给 Codex 用的、那个是给 Claude Code 用的”JSON 里没法写只能靠字段名硬猜。TOML 表达嵌套结构又比较别扭尤其是当你要描述“多个供应商、每个供应商下面多个模型、每个模型还有各自的参数”这种三层结构时TOML 的[table.subtable]写法会让人看得头晕。YAML 刚好卡在中间支持注释、支持嵌套、缩进即层级人眼扫一遍就能看懂结构。我实测下来一份中等复杂度的openrig配置大概长这样providers: local: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - name: qwen2.5-coder-7b context: 32768 remote: type: openai-compatible base_url: https://api.example.com/v1 api_key: ${OPENRIG_REMOTE_KEY} models: - name: deepseek-coder context: 65536 tools: claude-code: provider: local model: qwen2.5-coder-7b codex: provider: remote model: deepseek-coder这份配置里有两个细节值得说。第一api_key用了${OPENRIG_REMOTE_KEY}这种占位符而不是把密钥硬编码进去。这是配置管理的基本纪律——配置文件是要进 Git 仓库、要分享给同事的密钥绝对不能明文躺在里面。第二tools这一段把“哪个工具用哪个供应商的哪个模型”这件事显式声明出来了这就是openrig这类框架的核心价值把工具和模型解耦换模型不用改工具本身的配置。注意YAML 对缩进极其敏感而且不允许用 Tab 缩进只能用空格。我见过太多人从编辑器里复制配置Tab 和空格混在一起报错信息还特别隐晦查半天查不出来。建议在编辑器里把 YAML 文件的 Tab 自动转空格打开。2.2 Node.js 是绕不开的运行时底座热搜词里node.js、node.js安装、node.js是干什么的出现频率极高说明很多人卡在第一步。Claude Code 和 Codex CLI 这两个工具本质上都是 Node.js 写的命令行程序通过 npm 分发。你想用它们机器上就必须有 Node.js 运行时。这里有个版本坑必须提前说。热搜里有一条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这就是典型的版本号写错或者源里没有这个版本导致的。Node.js 的版本策略是偶数大版本号是 LTS长期支持奇数大版本号是 Current尝鲜。生产环境或者日常开发一律选 LTS。截至我写这篇的时候稳妥的选择是 Node.js 20 LTS 或者 22 LTS别去追那些还没正式发布的版本号。安装方式我推荐两种。第一种是去 Node.js 官网下载 LTS 的安装包Windows 和 macOS 都有图形化安装程序一路下一步就行适合不想折腾的人。第二种是用版本管理工具比如nvmNode Version Manager好处是可以在多个 Node 版本之间切换遇到某个工具只兼容特定版本时特别有用# 安装 nvm 后 nvm install 20 nvm use 20 node -v # 应该输出 v20.x.x npm -v装完之后验证一下node -v和npm -v都能正常输出版本号这一步过了后面装 Claude Code 和 Codex 才有基础。2.3 把工具链拆成“配置层 运行时层 工具层”我把openrig这套东西的心智模型总结成三层理解了这三层后面所有操作都是顺理成章的层级职责对应组件配置层声明供应商、模型、工具映射关系YAML 文件运行时层提供命令行程序执行环境Node.js npm工具层实际干活的 AI 编码助手Claude Code、Codex CLI配置层是“意图”运行时层是“地基”工具层是“执行者”。很多人出问题是因为分不清自己卡在哪一层。比如cc switch local proxy failed while handling codex endpoint /responses这种报错表面看是工具层的问题实际上往往是配置层里端点路径写错了或者运行时层的某个依赖版本不对。分层之后排查就有了方向先确认 Node 版本对不对再确认 YAML 能不能解析最后才去看工具本身的日志。3. 核心细节解析Claude Code 与 Codex 的接入要点3.1 Claude Code 的安装与本地模型接入Claude Code 的安装本身不复杂npm 全局装一下就行npm install -g anthropic-ai/claude-code装完之后在终端里敲claude第一次运行会引导你做认证。这里有个热搜词值得单独拎出来说your organization has disabled claude subscription access for claude code。这个报错的意思是你当前登录的账号所属组织把 Claude Code 的订阅访问权限关掉了。遇到这个不是你的配置问题是账号权限问题得找组织管理员开权限或者换一个个人账号。另一个高频需求是claude code 调用 lmstudio 的本地模型。这个场景很实际不想把代码发到远端想用本地跑的小模型。做法是通过环境变量把 Claude Code 的请求指向本地兼容端点。LM Studio 默认会在http://127.0.0.1:1234/v1起一个 OpenAI 兼容的服务你只要把 base URL 和 key 指过去就行export ANTHROPIC_BASE_URLhttp://127.0.0.1:1234/v1 export ANTHROPIC_API_KEYlocal claude提示本地模型对上下文长度的支持往往不如云端模型Claude Code 默认会塞比较长的上下文进去本地小模型很容易爆上下文。建议在 LM Studio 里把模型的 context length 调大或者用openrig的配置层给不同工具指定不同的上下文预算。在 VS Code 里用 Claude Code 也是热搜里的高频需求vscode配置claude code、claude code for vs code。官方有对应的扩展装完之后在 VS Code 的集成终端里跑claude就能用好处是它能直接读取当前打开的项目文件改代码的时候不用来回切窗口。Ubuntu 用户ubuntu配置claude code注意一下如果 npm 全局安装报权限错误别用sudo npm install -g正确做法是配置 npm 的全局目录到用户目录下避免污染系统目录。3.2 Codex 的安装与第三方端点接入Codex CLI 的安装同样是 npm 路线npm install -g openai/codexCodex 的配置比 Claude Code 稍微灵活一点它支持通过配置文件指定模型和端点。热搜里codex接入deepseek、codex接入第三方api这类需求核心就是改配置文件里的 base URL 和模型名。Codex 的配置文件一般在用户目录下的.codex/config.toml或者通过环境变量注入。这里要重点讲一个热搜里出现的报错{detail:the gpt-5.6-sol model is not supported when using codex with a...}。这个报错的意思是你在配置里指定的模型名当前端点不认。原因通常是模型名拼错了或者你用的第三方端点根本没有这个模型。解决办法很简单把模型名改成端点实际支持的名称。第三方兼容端点一般会提供一份模型列表照着列表里的名字填别自己臆想。codex无法加载组织设置这个报错也常见多半是认证信息过期或者配置文件路径不对。Codex 会按优先级从多个位置读配置环境变量 项目级配置 用户级配置。排查的时候先确认环境变量有没有覆盖掉你想要的配置。3.3 用 openrig 把两者统一管起来单独配 Claude Code 和单独配 Codex 都不难难的是两者共存的时候不打架。比如你想让 Claude Code 走本地模型、Codex 走远端模型两套环境变量如果都写在 shell 的 profile 里很容易互相覆盖。openrig的价值就在这儿它把两套配置放在一份 YAML 里通过工具名区分启动的时候按需注入对应的环境变量。我自己的做法是给每个项目目录放一份openrig.yaml里面声明这个项目要用哪个工具、哪个模型。切换项目的时候配置跟着项目走不用去动全局环境变量。这种“配置跟着项目走”的模式比全局配置干净得多尤其是你同时维护好几个不同技术栈的项目时。4. 实操过程从零把 openrig 跑起来4.1 环境准备与版本核对第一步永远是核对环境。我见过太多人跳过这步结果在后面的报错里绕圈子。按顺序执行node -v npm -v git --versionNode 版本建议 20 LTS 或 22 LTS。如果版本不对用 nvm 切一下。npm 版本一般跟着 Node 走不用单独管。git 是很多工具拉取依赖时需要的顺手确认一下。第二步确认 npm 的全局安装目录在用户目录下避免权限问题npm config get prefix如果输出的是/usr/local或者/usr这种系统目录建议改到用户目录npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后这行加到你的 shell 配置文件.bashrc或.zshrc里重开终端生效。4.2 安装 Claude Code 与 Codex环境确认无误后两个工具一起装npm install -g anthropic-ai/claude-code npm install -g openai/codex装完分别验证claude --version codex --version能输出版本号就说明安装成功。如果某个工具报“command not found”八成是 PATH 没配好回头检查上一步的npm config get prefix和 PATH 设置。4.3 编写 openrig 配置文件在项目根目录建一个openrig.yaml内容参考前面第 2.1 节的示例。这里我把关键字段再解释一遍方便你按自己的情况改providers定义模型供应商。type一般填openai-compatible因为绝大多数第三方端点和本地推理服务都兼容 OpenAI 的接口格式。base_url端点地址。本地服务一般是http://127.0.0.1:端口/v1远端服务看供应商文档。api_key密钥。强烈建议用环境变量占位符不要明文写。models该供应商下可用的模型列表name必须和端点实际支持的名称一致。tools把工具映射到具体的供应商和模型。写完配置后先做一次语法校验。YAML 的语法错误很隐蔽用 Node.js 自带的解析能力快速验一下node -e const yamlrequire(js-yaml);const fsrequire(fs);yaml.load(fs.readFileSync(openrig.yaml,utf8));console.log(YAML OK)如果没装js-yaml先npm install js-yaml。这行命令能解析成功说明 YAML 语法没问题剩下的就是逻辑问题了。4.4 启动与验证配置就绪后按工具分别启动验证。先验证 Claude Code 能不能连上你指定的模型claude进去之后随便问一句看它有没有正常返回。如果卡住不动或者报连接错误先检查base_url能不能通curl http://127.0.0.1:1234/v1/models这个命令能列出模型说明端点活着列不出来说明本地推理服务没起来或者端口不对。再验证 Codexcodex同样问一句看返回。Codex 的日志比 Claude Code 详细一些出问题的时候它会打印请求的端点和模型名对着日志排查效率很高。4.5 参数选择与计算上下文预算怎么定上下文长度这个参数很多人是拍脑袋填的其实可以算。一个粗略的估算公式是可用上下文 模型最大上下文 - 系统提示占用 - 预留输出空间假设模型最大上下文是 32768系统提示大概占 2000你想让模型一次输出最多 4000 token那么留给代码内容的预算就是32768 - 2000 - 4000 26768。如果你的项目单文件就超过这个数要么换更大上下文的模型要么把任务拆小。本地模型尤其要注意这点。很多本地小模型的标称上下文是 32K但实际有效上下文可能只有一半超过之后输出质量断崖式下跌。我的经验是本地模型按标称值的 60% 来用比较稳。5. 常见问题与排查技巧实录5.1 高频报错速查表报错关键词可能原因排查方向cc switch local proxy failed端点路径或端口错误用 curl 测端点连通性model is not supported模型名与端点不匹配查端点模型列表改配置organization has disabled账号权限被限制换账号或找管理员node.js vXX is not yet released版本号不存在改用 LTS 版本无法加载组织设置认证过期或配置路径错检查环境变量优先级command not foundPATH 未配置检查 npm prefix 和 PATH5.2 我踩过的三个坑第一个坑是 YAML 缩进。有次我从网上抄了一份配置看着没问题跑起来一直报解析错误。后来用编辑器打开“显示空白字符”发现混了 Tab。YAML 对 Tab 零容忍这个坑几乎每个新手都会踩一次。第二个坑是环境变量覆盖。我在 shell profile 里设了ANTHROPIC_BASE_URL又在项目配置里设了另一个结果工具读的是 profile 里那个怎么改项目配置都不生效。后来才搞明白环境变量的优先级高于项目配置。解决办法是把 profile 里的全局设置清掉全部交给项目级配置管。第三个坑是本地模型上下文爆掉。我用一个标称 32K 上下文的本地模型跑 Claude Code稍微大一点的文件就报错或者输出乱码。后来把上下文预算降到 20K 以内稳定多了。本地模型别太相信标称值留足余量。5.3 排查的通用思路遇到问题按“运行时 → 配置 → 工具”的顺序查。先确认 Node 版本和 npm 全局路径没问题再确认 YAML 能解析、端点能连通最后才去看工具本身的日志。这个顺序能帮你快速定位问题在哪一层避免在错误的层面上浪费时间。具体到命令层面我常用的三板斧是node -v # 运行时层 curl base_url/models # 配置层端点连通性 tool --version # 工具层安装是否成功这三条命令覆盖了绝大多数入门级问题。如果三条都正常但工具还是跑不起来那问题多半在认证或者模型名上去看工具的详细日志。5.4 关于第三方 API 的使用技巧热搜里第三方api使用技巧出现频率不低这里补几句。第三方兼容端点最大的价值是让你用一份代码适配多个模型供应商。但要注意几点一是模型名必须严格对齐别自己造名字二是有些端点对请求频率有限制批量任务要加退避重试三是密钥管理要规范用环境变量或者密钥管理工具别写死在配置里。这几点做到了第三方端点的稳定性其实相当可观。6. 一些实操之外的体会openrig这类工具真正解决的不是某个具体的技术难题而是“配置散落各处、换环境就重来一遍”这种低效状态。我自己的项目目录里现在每个都有一份openrig.yaml换电脑、换同事接手把配置一拉环境基本就齐了。这种“配置即文档”的做法比写一堆 README 说明谁用哪个模型靠谱得多。如果你刚开始接触 Claude Code 和 Codex我的建议是先别急着上复杂配置把单个工具跑通再引入openrig做统一管理。顺序反了容易一头雾水。等两个工具都能单独跑起来你会发现把它们收敛到一份 YAML 里是水到渠成的事。最后分享一个小技巧把openrig.yaml里的密钥占位符和实际的密钥文件分开管理密钥文件加进.gitignore配置模板进仓库。这样团队协作的时候新人拉下代码照着模板填自己的密钥就能跑既安全又省事。这个习惯养成之后后面接多少个模型、换多少个工具都不会乱。
openrig 实战：用 YAML 统一管理 Claude Code 与 Codex 的 AI 编码工具链
1. 从标题说起openrig 到底想解决什么问题第一次看到openrig这个名字我脑子里蹦出来的第一反应是“open”加“rig”——rig 在英文里本意是“装配、搭台子”在工程语境里常指把一堆零散部件组装成一套能跑起来的装置。把这两个词拼在一起基本就能猜到它的定位一套开放的、用来把 AI 编码工具链“搭起来”的脚手架或者配置框架。结合热搜词里高频出现的 Claude Code、Codex、YAML、Node.js这个判断基本可以坐实——openrig大概率是一个围绕命令行 AI 编码助手做统一配置、统一接入、统一管理的开源项目。为什么我这么判断因为最近这半年我身边做开发的朋友几乎人手一个 Claude Code 或者 Codex CLI但真正用顺手的没几个。问题不在于模型本身不行而在于“接入”这件事太碎了。你想让 Claude Code 走本地模型得改环境变量想让 Codex 接第三方兼容端点得动配置文件想在不同项目之间切换不同的模型供应商又得手动改一堆东西。每个人都在重复造轮子每个人踩的坑还都不一样。openrig这类项目出现的动机就是把这堆重复劳动收敛成一份可版本化、可复用、可分享的配置。所以这篇东西我打算按“一个真实使用者会怎么把它跑起来”的思路来写。不管你是刚听说 Claude Code 想试试水的新手还是已经在 Codex 和 Claude Code 之间来回横跳的老手只要你对“用一份配置管住多个 AI 编码工具”这件事有兴趣下面的内容应该都能直接用上。我会把 YAML 怎么写、Node.js 环境怎么备、Claude Code 和 Codex 分别怎么接、出问题怎么查一条条拆开讲清楚中间穿插我自己踩过的坑。2. 整体设计思路为什么是 YAML Node.js 这套组合2.1 用 YAML 做配置层是权衡之后的最优解先说说为什么这类工具几乎清一色选 YAML 而不是 JSON 或者 TOML。JSON 的问题在于不能写注释你配置一个模型端点想标注“这个是给 Codex 用的、那个是给 Claude Code 用的”JSON 里没法写只能靠字段名硬猜。TOML 表达嵌套结构又比较别扭尤其是当你要描述“多个供应商、每个供应商下面多个模型、每个模型还有各自的参数”这种三层结构时TOML 的[table.subtable]写法会让人看得头晕。YAML 刚好卡在中间支持注释、支持嵌套、缩进即层级人眼扫一遍就能看懂结构。我实测下来一份中等复杂度的openrig配置大概长这样providers: local: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - name: qwen2.5-coder-7b context: 32768 remote: type: openai-compatible base_url: https://api.example.com/v1 api_key: ${OPENRIG_REMOTE_KEY} models: - name: deepseek-coder context: 65536 tools: claude-code: provider: local model: qwen2.5-coder-7b codex: provider: remote model: deepseek-coder这份配置里有两个细节值得说。第一api_key用了${OPENRIG_REMOTE_KEY}这种占位符而不是把密钥硬编码进去。这是配置管理的基本纪律——配置文件是要进 Git 仓库、要分享给同事的密钥绝对不能明文躺在里面。第二tools这一段把“哪个工具用哪个供应商的哪个模型”这件事显式声明出来了这就是openrig这类框架的核心价值把工具和模型解耦换模型不用改工具本身的配置。注意YAML 对缩进极其敏感而且不允许用 Tab 缩进只能用空格。我见过太多人从编辑器里复制配置Tab 和空格混在一起报错信息还特别隐晦查半天查不出来。建议在编辑器里把 YAML 文件的 Tab 自动转空格打开。2.2 Node.js 是绕不开的运行时底座热搜词里node.js、node.js安装、node.js是干什么的出现频率极高说明很多人卡在第一步。Claude Code 和 Codex CLI 这两个工具本质上都是 Node.js 写的命令行程序通过 npm 分发。你想用它们机器上就必须有 Node.js 运行时。这里有个版本坑必须提前说。热搜里有一条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这就是典型的版本号写错或者源里没有这个版本导致的。Node.js 的版本策略是偶数大版本号是 LTS长期支持奇数大版本号是 Current尝鲜。生产环境或者日常开发一律选 LTS。截至我写这篇的时候稳妥的选择是 Node.js 20 LTS 或者 22 LTS别去追那些还没正式发布的版本号。安装方式我推荐两种。第一种是去 Node.js 官网下载 LTS 的安装包Windows 和 macOS 都有图形化安装程序一路下一步就行适合不想折腾的人。第二种是用版本管理工具比如nvmNode Version Manager好处是可以在多个 Node 版本之间切换遇到某个工具只兼容特定版本时特别有用# 安装 nvm 后 nvm install 20 nvm use 20 node -v # 应该输出 v20.x.x npm -v装完之后验证一下node -v和npm -v都能正常输出版本号这一步过了后面装 Claude Code 和 Codex 才有基础。2.3 把工具链拆成“配置层 运行时层 工具层”我把openrig这套东西的心智模型总结成三层理解了这三层后面所有操作都是顺理成章的层级职责对应组件配置层声明供应商、模型、工具映射关系YAML 文件运行时层提供命令行程序执行环境Node.js npm工具层实际干活的 AI 编码助手Claude Code、Codex CLI配置层是“意图”运行时层是“地基”工具层是“执行者”。很多人出问题是因为分不清自己卡在哪一层。比如cc switch local proxy failed while handling codex endpoint /responses这种报错表面看是工具层的问题实际上往往是配置层里端点路径写错了或者运行时层的某个依赖版本不对。分层之后排查就有了方向先确认 Node 版本对不对再确认 YAML 能不能解析最后才去看工具本身的日志。3. 核心细节解析Claude Code 与 Codex 的接入要点3.1 Claude Code 的安装与本地模型接入Claude Code 的安装本身不复杂npm 全局装一下就行npm install -g anthropic-ai/claude-code装完之后在终端里敲claude第一次运行会引导你做认证。这里有个热搜词值得单独拎出来说your organization has disabled claude subscription access for claude code。这个报错的意思是你当前登录的账号所属组织把 Claude Code 的订阅访问权限关掉了。遇到这个不是你的配置问题是账号权限问题得找组织管理员开权限或者换一个个人账号。另一个高频需求是claude code 调用 lmstudio 的本地模型。这个场景很实际不想把代码发到远端想用本地跑的小模型。做法是通过环境变量把 Claude Code 的请求指向本地兼容端点。LM Studio 默认会在http://127.0.0.1:1234/v1起一个 OpenAI 兼容的服务你只要把 base URL 和 key 指过去就行export ANTHROPIC_BASE_URLhttp://127.0.0.1:1234/v1 export ANTHROPIC_API_KEYlocal claude提示本地模型对上下文长度的支持往往不如云端模型Claude Code 默认会塞比较长的上下文进去本地小模型很容易爆上下文。建议在 LM Studio 里把模型的 context length 调大或者用openrig的配置层给不同工具指定不同的上下文预算。在 VS Code 里用 Claude Code 也是热搜里的高频需求vscode配置claude code、claude code for vs code。官方有对应的扩展装完之后在 VS Code 的集成终端里跑claude就能用好处是它能直接读取当前打开的项目文件改代码的时候不用来回切窗口。Ubuntu 用户ubuntu配置claude code注意一下如果 npm 全局安装报权限错误别用sudo npm install -g正确做法是配置 npm 的全局目录到用户目录下避免污染系统目录。3.2 Codex 的安装与第三方端点接入Codex CLI 的安装同样是 npm 路线npm install -g openai/codexCodex 的配置比 Claude Code 稍微灵活一点它支持通过配置文件指定模型和端点。热搜里codex接入deepseek、codex接入第三方api这类需求核心就是改配置文件里的 base URL 和模型名。Codex 的配置文件一般在用户目录下的.codex/config.toml或者通过环境变量注入。这里要重点讲一个热搜里出现的报错{detail:the gpt-5.6-sol model is not supported when using codex with a...}。这个报错的意思是你在配置里指定的模型名当前端点不认。原因通常是模型名拼错了或者你用的第三方端点根本没有这个模型。解决办法很简单把模型名改成端点实际支持的名称。第三方兼容端点一般会提供一份模型列表照着列表里的名字填别自己臆想。codex无法加载组织设置这个报错也常见多半是认证信息过期或者配置文件路径不对。Codex 会按优先级从多个位置读配置环境变量 项目级配置 用户级配置。排查的时候先确认环境变量有没有覆盖掉你想要的配置。3.3 用 openrig 把两者统一管起来单独配 Claude Code 和单独配 Codex 都不难难的是两者共存的时候不打架。比如你想让 Claude Code 走本地模型、Codex 走远端模型两套环境变量如果都写在 shell 的 profile 里很容易互相覆盖。openrig的价值就在这儿它把两套配置放在一份 YAML 里通过工具名区分启动的时候按需注入对应的环境变量。我自己的做法是给每个项目目录放一份openrig.yaml里面声明这个项目要用哪个工具、哪个模型。切换项目的时候配置跟着项目走不用去动全局环境变量。这种“配置跟着项目走”的模式比全局配置干净得多尤其是你同时维护好几个不同技术栈的项目时。4. 实操过程从零把 openrig 跑起来4.1 环境准备与版本核对第一步永远是核对环境。我见过太多人跳过这步结果在后面的报错里绕圈子。按顺序执行node -v npm -v git --versionNode 版本建议 20 LTS 或 22 LTS。如果版本不对用 nvm 切一下。npm 版本一般跟着 Node 走不用单独管。git 是很多工具拉取依赖时需要的顺手确认一下。第二步确认 npm 的全局安装目录在用户目录下避免权限问题npm config get prefix如果输出的是/usr/local或者/usr这种系统目录建议改到用户目录npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后这行加到你的 shell 配置文件.bashrc或.zshrc里重开终端生效。4.2 安装 Claude Code 与 Codex环境确认无误后两个工具一起装npm install -g anthropic-ai/claude-code npm install -g openai/codex装完分别验证claude --version codex --version能输出版本号就说明安装成功。如果某个工具报“command not found”八成是 PATH 没配好回头检查上一步的npm config get prefix和 PATH 设置。4.3 编写 openrig 配置文件在项目根目录建一个openrig.yaml内容参考前面第 2.1 节的示例。这里我把关键字段再解释一遍方便你按自己的情况改providers定义模型供应商。type一般填openai-compatible因为绝大多数第三方端点和本地推理服务都兼容 OpenAI 的接口格式。base_url端点地址。本地服务一般是http://127.0.0.1:端口/v1远端服务看供应商文档。api_key密钥。强烈建议用环境变量占位符不要明文写。models该供应商下可用的模型列表name必须和端点实际支持的名称一致。tools把工具映射到具体的供应商和模型。写完配置后先做一次语法校验。YAML 的语法错误很隐蔽用 Node.js 自带的解析能力快速验一下node -e const yamlrequire(js-yaml);const fsrequire(fs);yaml.load(fs.readFileSync(openrig.yaml,utf8));console.log(YAML OK)如果没装js-yaml先npm install js-yaml。这行命令能解析成功说明 YAML 语法没问题剩下的就是逻辑问题了。4.4 启动与验证配置就绪后按工具分别启动验证。先验证 Claude Code 能不能连上你指定的模型claude进去之后随便问一句看它有没有正常返回。如果卡住不动或者报连接错误先检查base_url能不能通curl http://127.0.0.1:1234/v1/models这个命令能列出模型说明端点活着列不出来说明本地推理服务没起来或者端口不对。再验证 Codexcodex同样问一句看返回。Codex 的日志比 Claude Code 详细一些出问题的时候它会打印请求的端点和模型名对着日志排查效率很高。4.5 参数选择与计算上下文预算怎么定上下文长度这个参数很多人是拍脑袋填的其实可以算。一个粗略的估算公式是可用上下文 模型最大上下文 - 系统提示占用 - 预留输出空间假设模型最大上下文是 32768系统提示大概占 2000你想让模型一次输出最多 4000 token那么留给代码内容的预算就是32768 - 2000 - 4000 26768。如果你的项目单文件就超过这个数要么换更大上下文的模型要么把任务拆小。本地模型尤其要注意这点。很多本地小模型的标称上下文是 32K但实际有效上下文可能只有一半超过之后输出质量断崖式下跌。我的经验是本地模型按标称值的 60% 来用比较稳。5. 常见问题与排查技巧实录5.1 高频报错速查表报错关键词可能原因排查方向cc switch local proxy failed端点路径或端口错误用 curl 测端点连通性model is not supported模型名与端点不匹配查端点模型列表改配置organization has disabled账号权限被限制换账号或找管理员node.js vXX is not yet released版本号不存在改用 LTS 版本无法加载组织设置认证过期或配置路径错检查环境变量优先级command not foundPATH 未配置检查 npm prefix 和 PATH5.2 我踩过的三个坑第一个坑是 YAML 缩进。有次我从网上抄了一份配置看着没问题跑起来一直报解析错误。后来用编辑器打开“显示空白字符”发现混了 Tab。YAML 对 Tab 零容忍这个坑几乎每个新手都会踩一次。第二个坑是环境变量覆盖。我在 shell profile 里设了ANTHROPIC_BASE_URL又在项目配置里设了另一个结果工具读的是 profile 里那个怎么改项目配置都不生效。后来才搞明白环境变量的优先级高于项目配置。解决办法是把 profile 里的全局设置清掉全部交给项目级配置管。第三个坑是本地模型上下文爆掉。我用一个标称 32K 上下文的本地模型跑 Claude Code稍微大一点的文件就报错或者输出乱码。后来把上下文预算降到 20K 以内稳定多了。本地模型别太相信标称值留足余量。5.3 排查的通用思路遇到问题按“运行时 → 配置 → 工具”的顺序查。先确认 Node 版本和 npm 全局路径没问题再确认 YAML 能解析、端点能连通最后才去看工具本身的日志。这个顺序能帮你快速定位问题在哪一层避免在错误的层面上浪费时间。具体到命令层面我常用的三板斧是node -v # 运行时层 curl base_url/models # 配置层端点连通性 tool --version # 工具层安装是否成功这三条命令覆盖了绝大多数入门级问题。如果三条都正常但工具还是跑不起来那问题多半在认证或者模型名上去看工具的详细日志。5.4 关于第三方 API 的使用技巧热搜里第三方api使用技巧出现频率不低这里补几句。第三方兼容端点最大的价值是让你用一份代码适配多个模型供应商。但要注意几点一是模型名必须严格对齐别自己造名字二是有些端点对请求频率有限制批量任务要加退避重试三是密钥管理要规范用环境变量或者密钥管理工具别写死在配置里。这几点做到了第三方端点的稳定性其实相当可观。6. 一些实操之外的体会openrig这类工具真正解决的不是某个具体的技术难题而是“配置散落各处、换环境就重来一遍”这种低效状态。我自己的项目目录里现在每个都有一份openrig.yaml换电脑、换同事接手把配置一拉环境基本就齐了。这种“配置即文档”的做法比写一堆 README 说明谁用哪个模型靠谱得多。如果你刚开始接触 Claude Code 和 Codex我的建议是先别急着上复杂配置把单个工具跑通再引入openrig做统一管理。顺序反了容易一头雾水。等两个工具都能单独跑起来你会发现把它们收敛到一份 YAML 里是水到渠成的事。最后分享一个小技巧把openrig.yaml里的密钥占位符和实际的密钥文件分开管理密钥文件加进.gitignore配置模板进仓库。这样团队协作的时候新人拉下代码照着模板填自己的密钥就能跑既安全又省事。这个习惯养成之后后面接多少个模型、换多少个工具都不会乱。
