1. 从 openrig 这个名字说起它到底想解决什么问题第一次看到openrig这个词我下意识把它拆成了两半open和rig。rig在工程语境里通常指“装配好的整套装置”比如一台调试好的测试台、一套搭好的实验设备。把它放到 AI 编程工具这个圈子里openrig大概率指的是“一套开放、可自由拼装的工具装配方案”——不是某个单一软件而是把命令行 AI 助手、模型接入、配置文件、运行环境这几样东西组合成一个能跑起来的工作台。这个判断不是凭空来的。结合热搜词里高频出现的claude code、codex、yaml、node.js以及“cc switch 接入 deepseek、qwen、glm 等模型”“codex 接入 deepseek”这类具体诉求可以还原出真实场景很多人手里有多个 AI 编程助手Claude Code、Codex CLI 等也有多个模型来源官方订阅、第三方 API、本地模型但把它们各自装好、配好、切换顺畅是一件相当折腾的事。openrig要做的就是把这套“装配”过程标准化、可复现化。所以这篇内容适合谁看三类人最对口。第一类是想把 Claude Code 或 Codex 真正用起来、但卡在安装和配置环节的开发者第二类是需要频繁在不同模型之间切换、想搞一套稳定本地配置的人第三类是喜欢折腾工具链、愿意用 YAML 和 Node.js 把环境管起来的效率型选手。哪怕你只是刚听说claude code和codex跟着往下看也能把整套逻辑理顺。我先把结论摆前面openrig这类方案的核心价值不在“装了什么”而在“怎么组织”。工具本身都是现成的真正拉开差距的是配置文件结构、模型切换策略、以及环境隔离方式。下面我会按“环境底座 → 配置骨架 → 模型接入 → 切换与排错”这条线把整套东西讲透。2. Node.js 是整个装配台的地基别在这一步偷懒2.1 为什么这类工具几乎都绕不开 Node.jsClaude Code、Codex CLI 这类命令行 AI 助手绝大多数是用 Node.js 写的通过 npm 全局安装。原因很实际Node.js 的跨平台一致性做得好Windows、macOS、Ubuntu 上一条npm install -g就能装开发者不用为每个系统单独打包。所以你会看到热搜里node.js、node.js安装、node.js官网下载、node.js LTS下载、安装node.js反复出现——这不是巧合这是所有后续步骤的前置条件。这里有个很多人踩过的坑热搜词里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是典型。有人看到版本号大就想去装最新的结果那个版本根本还没正式发布或者对应的二进制包还没上传安装脚本直接报错。我的建议很明确装 LTS 版本不要追最新奇数版。LTS 是长期支持版稳定性和生态兼容性都经过验证AI 工具链对 Node 版本通常有最低要求但很少要求你必须用最新版。2.2 安装 Node.js 的稳妥路径不同系统我给的方案不一样因为踩过的坑不同。Windows 用户直接去 Node.js 官网下载 LTS 的.msi安装包双击一路下一步。安装时注意勾选“Add to PATH”否则后面在终端里敲node -v会提示找不到命令。装完打开 PowerShell 或 CMD敲node -v npm -v两条都能输出版本号说明装好了。如果node -v有输出但npm -v报错多半是 PATH 没配全重装一遍并确认勾选项。macOS 用户如果你装了 Homebrew一条命令搞定brew install node20我特意指定node20而不是裸node因为 Homebrew 的裸node会跟着最新版走哪天自动升级到新大版本可能把你原来的工具链搞崩。指定 LTS 大版本升级可控。Ubuntu 用户别用apt install nodejs系统源里的版本往往很旧。用 NodeSource 的源curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完同样用node -v和npm -v验证。提示如果你之前装过旧版本 Node先卸载干净再装新的。Windows 上残留的 npm 全局目录会导致新装的工具找不到macOS 和 Ubuntu 上残留的/usr/local/lib/node_modules也会捣乱。2.3 npm 全局目录的权限问题这是新手最容易卡住的地方。在 macOS 和 Ubuntu 上直接npm install -g经常报EACCES权限错误。很多人第一反应是加sudo这能装上但会埋下隐患用 sudo 装的全局包属于 root之后普通用户身份运行或升级时又会权限不足来回折腾。正确做法是把 npm 的全局目录改到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到 PATH 里写进~/.bashrc或~/.zshrc。这样以后所有全局安装都不需要 sudo升级、卸载都干净。这一步花五分钟能省掉后面无数次权限报错。3. YAML 配置文件openrig 真正的“装配图纸”3.1 为什么是 YAML而不是 JSON 或 TOML热搜里yaml、yaml文件、yolov10 yaml文件怎么创建、rstudio的yaml在哪里这些词混在一起说明很多人对 YAML 的定位是模糊的。我先把这个概念钉死YAML 是一种人类可读的数据序列化格式用缩进表示层级用key: value表示键值对。它比 JSON 好读不用满屏引号和括号比 TOML 表达嵌套结构更自然。AI 工具链偏爱 YAML是因为配置里经常要描述“多个模型、每个模型有多个参数、参数下面还有子项”这种嵌套结构。用 YAML 写出来层次一目了然改起来也不容易出错。openrig这类装配方案核心配置文件基本就是 YAML。YAML 的语法规则不多但每一条都必须严格遵守否则解析直接失败缩进只能用空格不能用 Tab。这是第一大坑编辑器里看着对齐了实际一个是 Tab 一个是空格解析器直接报错。冒号后面必须跟一个空格key:value是错的key: value才对。层级靠缩进表示同一层级缩进量必须一致通常用 2 个空格。字符串一般不用加引号但如果值里包含冒号、井号等特殊字符就得用引号包起来。3.2 一份可复用的 openrig 配置骨架下面这份配置是我按常见实践整理出来的骨架你可以直接拿去改。它描述的是“有哪些模型来源、每个来源怎么连、默认用哪个”# openrig 配置骨架 version: 1 # 默认使用的模型配置名 default: deepseek # 模型来源列表 providers: deepseek: type: openai-compatible base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} model: deepseek-chat timeout: 60 qwen: type: openai-compatible base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: ${QWEN_API_KEY} model: qwen-plus timeout: 60 local: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed model: local-model timeout: 120 # 工具行为配置 runtime: log_level: info retry: 2 stream: true这份配置有几个设计点值得说清楚。第一api_key用${DEEPSEEK_API_KEY}这种环境变量占位符而不是把密钥明文写进文件。这是硬性安全习惯。配置文件经常会被同步、备份、甚至误传到代码仓库明文密钥一旦泄露就是事故。把密钥放在环境变量里配置文件本身就可以放心共享。第二type: openai-compatible这个字段很关键。现在大量第三方模型服务都提供“兼容 OpenAI 接口”的端点只要 base_url 和 model 填对同一套客户端代码就能通吃 DeepSeek、Qwen、GLM 以及本地模型。这就是为什么cc switch 接入 deepseek、qwen、glm 等模型能成立——底层接口协议统一了。第三timeout单独给本地模型设了 120 秒比云端模型长。因为本地模型跑在你自己机器上推理速度取决于显卡和内存首次加载模型还特别慢超时设短了会频繁中断。3.3 环境变量怎么设才不出错配置文件里用了环境变量就得保证运行时这些变量真的存在。设置方式分系统macOS / Ubuntu写进 shell 配置文件export DEEPSEEK_API_KEY你的密钥 export QWEN_API_KEY你的密钥改完执行source ~/.zshrc或source ~/.bashrc让它生效。Windows用系统环境变量界面添加或者在 PowerShell 里临时设$env:DEEPSEEK_API_KEY你的密钥注意临时设置只对当前终端窗口有效关掉就没了。要长期生效得用系统环境变量界面或者写进 PowerShell 的 profile 文件。验证环境变量是否生效敲echo $DEEPSEEK_API_KEYWindows 用echo $env:DEEPSEEK_API_KEY能打印出密钥就对了。如果打印出来是空的说明变量没设上后面工具启动时就会报“api key missing”之类的错。4. Claude Code 与 Codex 的接入差异别用一套思路硬套4.1 两者的定位区别决定了配置方式不同热搜里claude code和codex出现的频率几乎一样高但很多人把它们当成同一类东西配置时用同一套思路结果两边都不顺。我先把区别讲清楚。Claude Code 是 Anthropic 推出的命令行编程助手它的强项是理解大段代码上下文、执行终端命令、按自然语言指令改代码。它的配置重点在“怎么让它连上模型、怎么控制它的行为边界”。Codex 是 OpenAI 系的命令行工具配置重点在“模型端点、组织设置、认证方式”。两者虽然都是 CLI但配置文件格式、认证流程、报错信息都不一样。热搜里your organization has disabled claude subscription access for claude code这条说的是账号层面的订阅权限被组织策略限制了这跟本地配置无关属于账号侧问题本地怎么改配置都绕不过去。而codex无法加载组织设置则是 Codex 在读取组织级配置时失败通常跟网络请求或认证令牌有关。这两类问题的排查方向完全不同不能混为一谈。4.2 Claude Code 的安装与基础配置安装本身不复杂前提是 Node.js 已经就位npm install -g anthropic-ai/claude-code装完敲claude启动。第一次运行会引导你完成认证。如果你用的是官方订阅按提示走浏览器授权流程即可。如果你要接入第三方模型或本地模型就需要通过配置把请求指向自定义端点。热搜里claude code 调用lmstudio的本地模型和vscode配置claude code、vscode接入claude code这几条反映的是两个高频需求一是接本地模型二是和编辑器集成。接本地模型的关键是让 Claude Code 的请求走一个兼容层把 Anthropic 的接口格式转换成 OpenAI 兼容格式因为 LM Studio 这类本地服务通常只提供 OpenAI 兼容接口。这个转换层就是cc switch这类工具存在的原因。VS Code 集成方面装官方扩展后在设置里指定 Claude Code 的可执行文件路径即可。如果扩展找不到命令多半是 VS Code 启动时没继承 shell 的 PATH重启 VS Code 或者从终端里用code .启动通常能解决。4.3 Codex 的安装与常见报错Codex 的安装同样走 npmnpm install -g openai/codex热搜里codex安装、codex安装教程、codex安装包、codex安装 windows桌面版、codex官网下载这些词说明安装环节的困惑很多。我的经验是优先用 npm 装别去第三方站点下所谓的“安装包”来源不明的包风险高而且版本可能对不上。Codex 配置里最容易出问题的是模型名称。热搜里{detail:the gpt-5.6-sol model is not supported when using codex with a...}这条报错本质是你配置里写的模型名服务端不认。模型名称必须和服务商文档里列出的完全一致多一个字符、少一个字符都不行。遇到这类报错第一件事是去核对模型名拼写而不是怀疑网络。codex接入deepseek这类需求思路和 Claude Code 接第三方模型一样把 Codex 的请求端点指向一个兼容层由兼容层转发到 DeepSeek 的 OpenAI 兼容接口。配置时重点确认三件事base_url 末尾有没有多余的斜杠、model 名是否准确、api_key 是否有效。4.4 一张对照表理清两者差异维度Claude CodeCodex安装命令npm install -g anthropic-ai/claude-codenpm install -g openai/codex启动命令claudecodex认证方式浏览器授权 / 自定义端点令牌 / 自定义端点接第三方模型需兼容层转换接口格式需兼容层转换接口格式典型报错订阅权限被组织限制模型名不支持、组织设置加载失败编辑器集成VS Code 扩展VS Code 扩展 / 终端这张表不是让你背而是让你在遇到问题时能快速定位是安装层、认证层还是模型配置层的问题。分层排查比盲目重装高效得多。5. 模型切换的实战逻辑cc switch 到底在做什么5.1 切换的本质是改端点不是改工具很多人以为“切换模型”是个很玄的功能其实拆开看非常简单AI 编程助手在发请求时会往一个固定的 API 端点发数据。所谓切换模型就是把这个端点、密钥、模型名这三个参数换掉。cc switch这类工具做的事情就是帮你管理多组参数并在需要时快速替换。热搜里使用cc switch 接入 deepseek v4, qwen, glm等模型和cc switch local proxy failed while handling codex endpoint /responses这两条一条讲怎么用一条讲用出错了。后者这个报错信息值得细看local proxy failed while handling codex endpoint /responses意思是本地代理在处理 Codex 的/responses端点请求时失败了。这通常有三个原因代理服务没启动、代理配置的转发目标地址写错了、或者请求格式和代理期望的不匹配。5.2 本地代理的工作流程我用生活化的方式解释一下本地代理。假设 Claude Code 只会说“Anthropic 方言”而 DeepSeek 只听得懂“OpenAI 方言”。本地代理就是个翻译官坐在中间Claude Code 把“Anthropic 方言”的话说给翻译官翻译官转成“OpenAI 方言”说给 DeepSeekDeepSeek 的回复再由翻译官转回去。这个流程里任何一环出问题都会报错。翻译官没上班代理没启动请求发不出去翻译官记错了 DeepSeek 的地址转发目标写错请求发到了错误的地方Claude Code 说的话翻译官听不懂请求格式不匹配翻译直接失败。排查顺序就按这个来先确认代理进程在跑再确认转发目标地址正确最后确认请求格式匹配。热搜里那个local proxy failed的报错九成是前两个原因。5.3 一份可用的切换配置示例下面这份配置演示如何在一个文件里管理多个模型来源并通过一个字段切换switch: active: deepseek profiles: deepseek: endpoint: http://127.0.0.1:8080/proxy target: https://api.deepseek.com/v1 model: deepseek-chat qwen: endpoint: http://127.0.0.1:8080/proxy target: https://dashscope.aliyuncs.com/compatible-mode/v1 model: qwen-plus glm: endpoint: http://127.0.0.1:8080/proxy target: https://open.bigmodel.cn/api/paas/v4 model: glm-4切换时只改active字段的值从deepseek改成qwen重启工具即可。这种设计的价值在于所有模型配置集中在一个文件里切换成本极低而且不容易漏改参数。提示改完配置后一定要重启工具进程。很多工具在启动时读取一次配置就缓存了运行中改文件不会生效这是新手常犯的错。5.4 本地模型接入的特殊处理接本地模型比如通过 LM Studio 跑起来的模型和接云端模型有个关键区别本地模型的响应速度不稳定首次请求可能因为加载模型而卡很久。所以配置里要把超时时间调大并且关掉过于激进的流式超时检测。另外本地模型的上下文窗口通常比云端小如果工具默认发送很长的上下文本地模型可能直接拒绝或截断。遇到这种情况要么换上下文更大的本地模型要么在工具配置里限制发送的上下文长度。这个参数在不同工具里叫法不同有的叫max_tokens有的叫context_limit需要查对应工具的文档。6. 排错链路从报错信息反推问题层级6.1 先分层再动手遇到报错最忌讳的就是“看到什么改什么”。我习惯先把问题分层AI 工具链的报错基本落在四层环境层Node.js 没装、版本不对、PATH 没配好。安装层npm 全局安装失败、权限不足、包名写错。配置层YAML 语法错误、字段名拼错、环境变量没设。运行层代理没启动、端点不通、模型名不支持、认证失败。分层之后排查就有了方向。环境层的错报错信息里通常带command not found或版本号安装层的错带EACCES或404配置层的错带parse error或missing field运行层的错带具体的 HTTP 状态码或端点路径。6.2 几个高频报错的定位过程拿热搜里的几个真实报错走一遍排查。error installing 24.21.0: node.js v24.21.0 is not yet released or is not available——这是环境层。你指定的 Node 版本不存在或没发布。解决方式是改用 LTS 版本别指定一个不存在的版本号。your organization has disabled claude subscription access for claude code——这是账号层不是本地配置能解决的。说明你的账号所属组织关闭了订阅访问权限。这种情况要么换账号要么联系组织管理员本地怎么改都没用。识别出这一点能省下大量无效折腾。codex无法加载组织设置——这是运行层。Codex 在启动时尝试拉取组织级配置失败通常是网络请求超时或认证令牌失效。先检查网络连通性再检查令牌是否过期。cc switch local proxy failed while handling codex endpoint /responses——这是运行层。按前面说的顺序查代理进程在不在、转发目标对不对、请求格式匹配不匹配。{detail:the gpt-5.6-sol model is not supported...}——这是配置层。模型名写错了去服务商文档核对准确名称。6.3 一个通用的验证方法配置改完别急着上真实任务先用一个最小请求验证链路通不通。比如用 curl 直接打你的代理端点curl -X POST http://127.0.0.1:8080/proxy/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的密钥 \ -d {model:deepseek-chat,messages:[{role:user,content:hi}]}能返回正常响应说明代理和转发链路是通的问题在工具侧返回错误说明问题在代理或目标服务侧。这一步能把问题范围砍掉一半非常值得养成习惯。7. 把 openrig 用顺手的几个经验配置这东西跑通一次不难难的是长期稳定。我分享几个实际用下来觉得最有价值的习惯。第一配置文件纳入版本管理但密钥绝不入库。把 YAML 配置文件放进 Git 仓库每次改动都有记录出问题能回滚。但密钥用环境变量占位仓库里只存占位符。这样既享受了版本管理的好处又不担心泄露。第二给每个模型来源单独建一个 profile不要临时改参数。临时改参数最容易忘改完这个忘了改回来下次用就出错。用 profile 管理切换只改一个active字段清晰且可追溯。第三本地模型和云端模型分开配置超时和重试策略。云端模型网络稳定超时可以设短一点重试次数少一点本地模型启动慢超时要设长重试要谨慎因为重试可能触发重复加载。混在一起配两边都不舒服。第四升级 Node.js 大版本前先备份全局包列表。用npm list -g --depth0导出当前全局安装的包升级后对照重装。Node 大版本升级有时会清掉全局目录没备份就得凭记忆重装很痛苦。第五遇到报错先看完整信息别只看最后一行。很多报错的根因在中间几行最后一行只是表象。比如权限错误最后一行说“安装失败”中间才说“EACCES”。养成看完整输出的习惯排查效率翻倍。这套东西搭起来之后你会发现真正花时间的不是安装而是理解每一层在做什么。一旦理解了环境层、配置层、运行层各自负责什么后面无论换什么工具、接什么模型都是同一套逻辑的复用。我自己从最早手动改配置到后来用 YAML 统一管理最大的体会就是把配置当成代码来对待稳定性和可维护性完全是两个量级。
openrig 装配指南：用 YAML 和 Node.js 统一管理 Claude Code 与 Codex 多模型接入
1. 从 openrig 这个名字说起它到底想解决什么问题第一次看到openrig这个词我下意识把它拆成了两半open和rig。rig在工程语境里通常指“装配好的整套装置”比如一台调试好的测试台、一套搭好的实验设备。把它放到 AI 编程工具这个圈子里openrig大概率指的是“一套开放、可自由拼装的工具装配方案”——不是某个单一软件而是把命令行 AI 助手、模型接入、配置文件、运行环境这几样东西组合成一个能跑起来的工作台。这个判断不是凭空来的。结合热搜词里高频出现的claude code、codex、yaml、node.js以及“cc switch 接入 deepseek、qwen、glm 等模型”“codex 接入 deepseek”这类具体诉求可以还原出真实场景很多人手里有多个 AI 编程助手Claude Code、Codex CLI 等也有多个模型来源官方订阅、第三方 API、本地模型但把它们各自装好、配好、切换顺畅是一件相当折腾的事。openrig要做的就是把这套“装配”过程标准化、可复现化。所以这篇内容适合谁看三类人最对口。第一类是想把 Claude Code 或 Codex 真正用起来、但卡在安装和配置环节的开发者第二类是需要频繁在不同模型之间切换、想搞一套稳定本地配置的人第三类是喜欢折腾工具链、愿意用 YAML 和 Node.js 把环境管起来的效率型选手。哪怕你只是刚听说claude code和codex跟着往下看也能把整套逻辑理顺。我先把结论摆前面openrig这类方案的核心价值不在“装了什么”而在“怎么组织”。工具本身都是现成的真正拉开差距的是配置文件结构、模型切换策略、以及环境隔离方式。下面我会按“环境底座 → 配置骨架 → 模型接入 → 切换与排错”这条线把整套东西讲透。2. Node.js 是整个装配台的地基别在这一步偷懒2.1 为什么这类工具几乎都绕不开 Node.jsClaude Code、Codex CLI 这类命令行 AI 助手绝大多数是用 Node.js 写的通过 npm 全局安装。原因很实际Node.js 的跨平台一致性做得好Windows、macOS、Ubuntu 上一条npm install -g就能装开发者不用为每个系统单独打包。所以你会看到热搜里node.js、node.js安装、node.js官网下载、node.js LTS下载、安装node.js反复出现——这不是巧合这是所有后续步骤的前置条件。这里有个很多人踩过的坑热搜词里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是典型。有人看到版本号大就想去装最新的结果那个版本根本还没正式发布或者对应的二进制包还没上传安装脚本直接报错。我的建议很明确装 LTS 版本不要追最新奇数版。LTS 是长期支持版稳定性和生态兼容性都经过验证AI 工具链对 Node 版本通常有最低要求但很少要求你必须用最新版。2.2 安装 Node.js 的稳妥路径不同系统我给的方案不一样因为踩过的坑不同。Windows 用户直接去 Node.js 官网下载 LTS 的.msi安装包双击一路下一步。安装时注意勾选“Add to PATH”否则后面在终端里敲node -v会提示找不到命令。装完打开 PowerShell 或 CMD敲node -v npm -v两条都能输出版本号说明装好了。如果node -v有输出但npm -v报错多半是 PATH 没配全重装一遍并确认勾选项。macOS 用户如果你装了 Homebrew一条命令搞定brew install node20我特意指定node20而不是裸node因为 Homebrew 的裸node会跟着最新版走哪天自动升级到新大版本可能把你原来的工具链搞崩。指定 LTS 大版本升级可控。Ubuntu 用户别用apt install nodejs系统源里的版本往往很旧。用 NodeSource 的源curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完同样用node -v和npm -v验证。提示如果你之前装过旧版本 Node先卸载干净再装新的。Windows 上残留的 npm 全局目录会导致新装的工具找不到macOS 和 Ubuntu 上残留的/usr/local/lib/node_modules也会捣乱。2.3 npm 全局目录的权限问题这是新手最容易卡住的地方。在 macOS 和 Ubuntu 上直接npm install -g经常报EACCES权限错误。很多人第一反应是加sudo这能装上但会埋下隐患用 sudo 装的全局包属于 root之后普通用户身份运行或升级时又会权限不足来回折腾。正确做法是把 npm 的全局目录改到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到 PATH 里写进~/.bashrc或~/.zshrc。这样以后所有全局安装都不需要 sudo升级、卸载都干净。这一步花五分钟能省掉后面无数次权限报错。3. YAML 配置文件openrig 真正的“装配图纸”3.1 为什么是 YAML而不是 JSON 或 TOML热搜里yaml、yaml文件、yolov10 yaml文件怎么创建、rstudio的yaml在哪里这些词混在一起说明很多人对 YAML 的定位是模糊的。我先把这个概念钉死YAML 是一种人类可读的数据序列化格式用缩进表示层级用key: value表示键值对。它比 JSON 好读不用满屏引号和括号比 TOML 表达嵌套结构更自然。AI 工具链偏爱 YAML是因为配置里经常要描述“多个模型、每个模型有多个参数、参数下面还有子项”这种嵌套结构。用 YAML 写出来层次一目了然改起来也不容易出错。openrig这类装配方案核心配置文件基本就是 YAML。YAML 的语法规则不多但每一条都必须严格遵守否则解析直接失败缩进只能用空格不能用 Tab。这是第一大坑编辑器里看着对齐了实际一个是 Tab 一个是空格解析器直接报错。冒号后面必须跟一个空格key:value是错的key: value才对。层级靠缩进表示同一层级缩进量必须一致通常用 2 个空格。字符串一般不用加引号但如果值里包含冒号、井号等特殊字符就得用引号包起来。3.2 一份可复用的 openrig 配置骨架下面这份配置是我按常见实践整理出来的骨架你可以直接拿去改。它描述的是“有哪些模型来源、每个来源怎么连、默认用哪个”# openrig 配置骨架 version: 1 # 默认使用的模型配置名 default: deepseek # 模型来源列表 providers: deepseek: type: openai-compatible base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} model: deepseek-chat timeout: 60 qwen: type: openai-compatible base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: ${QWEN_API_KEY} model: qwen-plus timeout: 60 local: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed model: local-model timeout: 120 # 工具行为配置 runtime: log_level: info retry: 2 stream: true这份配置有几个设计点值得说清楚。第一api_key用${DEEPSEEK_API_KEY}这种环境变量占位符而不是把密钥明文写进文件。这是硬性安全习惯。配置文件经常会被同步、备份、甚至误传到代码仓库明文密钥一旦泄露就是事故。把密钥放在环境变量里配置文件本身就可以放心共享。第二type: openai-compatible这个字段很关键。现在大量第三方模型服务都提供“兼容 OpenAI 接口”的端点只要 base_url 和 model 填对同一套客户端代码就能通吃 DeepSeek、Qwen、GLM 以及本地模型。这就是为什么cc switch 接入 deepseek、qwen、glm 等模型能成立——底层接口协议统一了。第三timeout单独给本地模型设了 120 秒比云端模型长。因为本地模型跑在你自己机器上推理速度取决于显卡和内存首次加载模型还特别慢超时设短了会频繁中断。3.3 环境变量怎么设才不出错配置文件里用了环境变量就得保证运行时这些变量真的存在。设置方式分系统macOS / Ubuntu写进 shell 配置文件export DEEPSEEK_API_KEY你的密钥 export QWEN_API_KEY你的密钥改完执行source ~/.zshrc或source ~/.bashrc让它生效。Windows用系统环境变量界面添加或者在 PowerShell 里临时设$env:DEEPSEEK_API_KEY你的密钥注意临时设置只对当前终端窗口有效关掉就没了。要长期生效得用系统环境变量界面或者写进 PowerShell 的 profile 文件。验证环境变量是否生效敲echo $DEEPSEEK_API_KEYWindows 用echo $env:DEEPSEEK_API_KEY能打印出密钥就对了。如果打印出来是空的说明变量没设上后面工具启动时就会报“api key missing”之类的错。4. Claude Code 与 Codex 的接入差异别用一套思路硬套4.1 两者的定位区别决定了配置方式不同热搜里claude code和codex出现的频率几乎一样高但很多人把它们当成同一类东西配置时用同一套思路结果两边都不顺。我先把区别讲清楚。Claude Code 是 Anthropic 推出的命令行编程助手它的强项是理解大段代码上下文、执行终端命令、按自然语言指令改代码。它的配置重点在“怎么让它连上模型、怎么控制它的行为边界”。Codex 是 OpenAI 系的命令行工具配置重点在“模型端点、组织设置、认证方式”。两者虽然都是 CLI但配置文件格式、认证流程、报错信息都不一样。热搜里your organization has disabled claude subscription access for claude code这条说的是账号层面的订阅权限被组织策略限制了这跟本地配置无关属于账号侧问题本地怎么改配置都绕不过去。而codex无法加载组织设置则是 Codex 在读取组织级配置时失败通常跟网络请求或认证令牌有关。这两类问题的排查方向完全不同不能混为一谈。4.2 Claude Code 的安装与基础配置安装本身不复杂前提是 Node.js 已经就位npm install -g anthropic-ai/claude-code装完敲claude启动。第一次运行会引导你完成认证。如果你用的是官方订阅按提示走浏览器授权流程即可。如果你要接入第三方模型或本地模型就需要通过配置把请求指向自定义端点。热搜里claude code 调用lmstudio的本地模型和vscode配置claude code、vscode接入claude code这几条反映的是两个高频需求一是接本地模型二是和编辑器集成。接本地模型的关键是让 Claude Code 的请求走一个兼容层把 Anthropic 的接口格式转换成 OpenAI 兼容格式因为 LM Studio 这类本地服务通常只提供 OpenAI 兼容接口。这个转换层就是cc switch这类工具存在的原因。VS Code 集成方面装官方扩展后在设置里指定 Claude Code 的可执行文件路径即可。如果扩展找不到命令多半是 VS Code 启动时没继承 shell 的 PATH重启 VS Code 或者从终端里用code .启动通常能解决。4.3 Codex 的安装与常见报错Codex 的安装同样走 npmnpm install -g openai/codex热搜里codex安装、codex安装教程、codex安装包、codex安装 windows桌面版、codex官网下载这些词说明安装环节的困惑很多。我的经验是优先用 npm 装别去第三方站点下所谓的“安装包”来源不明的包风险高而且版本可能对不上。Codex 配置里最容易出问题的是模型名称。热搜里{detail:the gpt-5.6-sol model is not supported when using codex with a...}这条报错本质是你配置里写的模型名服务端不认。模型名称必须和服务商文档里列出的完全一致多一个字符、少一个字符都不行。遇到这类报错第一件事是去核对模型名拼写而不是怀疑网络。codex接入deepseek这类需求思路和 Claude Code 接第三方模型一样把 Codex 的请求端点指向一个兼容层由兼容层转发到 DeepSeek 的 OpenAI 兼容接口。配置时重点确认三件事base_url 末尾有没有多余的斜杠、model 名是否准确、api_key 是否有效。4.4 一张对照表理清两者差异维度Claude CodeCodex安装命令npm install -g anthropic-ai/claude-codenpm install -g openai/codex启动命令claudecodex认证方式浏览器授权 / 自定义端点令牌 / 自定义端点接第三方模型需兼容层转换接口格式需兼容层转换接口格式典型报错订阅权限被组织限制模型名不支持、组织设置加载失败编辑器集成VS Code 扩展VS Code 扩展 / 终端这张表不是让你背而是让你在遇到问题时能快速定位是安装层、认证层还是模型配置层的问题。分层排查比盲目重装高效得多。5. 模型切换的实战逻辑cc switch 到底在做什么5.1 切换的本质是改端点不是改工具很多人以为“切换模型”是个很玄的功能其实拆开看非常简单AI 编程助手在发请求时会往一个固定的 API 端点发数据。所谓切换模型就是把这个端点、密钥、模型名这三个参数换掉。cc switch这类工具做的事情就是帮你管理多组参数并在需要时快速替换。热搜里使用cc switch 接入 deepseek v4, qwen, glm等模型和cc switch local proxy failed while handling codex endpoint /responses这两条一条讲怎么用一条讲用出错了。后者这个报错信息值得细看local proxy failed while handling codex endpoint /responses意思是本地代理在处理 Codex 的/responses端点请求时失败了。这通常有三个原因代理服务没启动、代理配置的转发目标地址写错了、或者请求格式和代理期望的不匹配。5.2 本地代理的工作流程我用生活化的方式解释一下本地代理。假设 Claude Code 只会说“Anthropic 方言”而 DeepSeek 只听得懂“OpenAI 方言”。本地代理就是个翻译官坐在中间Claude Code 把“Anthropic 方言”的话说给翻译官翻译官转成“OpenAI 方言”说给 DeepSeekDeepSeek 的回复再由翻译官转回去。这个流程里任何一环出问题都会报错。翻译官没上班代理没启动请求发不出去翻译官记错了 DeepSeek 的地址转发目标写错请求发到了错误的地方Claude Code 说的话翻译官听不懂请求格式不匹配翻译直接失败。排查顺序就按这个来先确认代理进程在跑再确认转发目标地址正确最后确认请求格式匹配。热搜里那个local proxy failed的报错九成是前两个原因。5.3 一份可用的切换配置示例下面这份配置演示如何在一个文件里管理多个模型来源并通过一个字段切换switch: active: deepseek profiles: deepseek: endpoint: http://127.0.0.1:8080/proxy target: https://api.deepseek.com/v1 model: deepseek-chat qwen: endpoint: http://127.0.0.1:8080/proxy target: https://dashscope.aliyuncs.com/compatible-mode/v1 model: qwen-plus glm: endpoint: http://127.0.0.1:8080/proxy target: https://open.bigmodel.cn/api/paas/v4 model: glm-4切换时只改active字段的值从deepseek改成qwen重启工具即可。这种设计的价值在于所有模型配置集中在一个文件里切换成本极低而且不容易漏改参数。提示改完配置后一定要重启工具进程。很多工具在启动时读取一次配置就缓存了运行中改文件不会生效这是新手常犯的错。5.4 本地模型接入的特殊处理接本地模型比如通过 LM Studio 跑起来的模型和接云端模型有个关键区别本地模型的响应速度不稳定首次请求可能因为加载模型而卡很久。所以配置里要把超时时间调大并且关掉过于激进的流式超时检测。另外本地模型的上下文窗口通常比云端小如果工具默认发送很长的上下文本地模型可能直接拒绝或截断。遇到这种情况要么换上下文更大的本地模型要么在工具配置里限制发送的上下文长度。这个参数在不同工具里叫法不同有的叫max_tokens有的叫context_limit需要查对应工具的文档。6. 排错链路从报错信息反推问题层级6.1 先分层再动手遇到报错最忌讳的就是“看到什么改什么”。我习惯先把问题分层AI 工具链的报错基本落在四层环境层Node.js 没装、版本不对、PATH 没配好。安装层npm 全局安装失败、权限不足、包名写错。配置层YAML 语法错误、字段名拼错、环境变量没设。运行层代理没启动、端点不通、模型名不支持、认证失败。分层之后排查就有了方向。环境层的错报错信息里通常带command not found或版本号安装层的错带EACCES或404配置层的错带parse error或missing field运行层的错带具体的 HTTP 状态码或端点路径。6.2 几个高频报错的定位过程拿热搜里的几个真实报错走一遍排查。error installing 24.21.0: node.js v24.21.0 is not yet released or is not available——这是环境层。你指定的 Node 版本不存在或没发布。解决方式是改用 LTS 版本别指定一个不存在的版本号。your organization has disabled claude subscription access for claude code——这是账号层不是本地配置能解决的。说明你的账号所属组织关闭了订阅访问权限。这种情况要么换账号要么联系组织管理员本地怎么改都没用。识别出这一点能省下大量无效折腾。codex无法加载组织设置——这是运行层。Codex 在启动时尝试拉取组织级配置失败通常是网络请求超时或认证令牌失效。先检查网络连通性再检查令牌是否过期。cc switch local proxy failed while handling codex endpoint /responses——这是运行层。按前面说的顺序查代理进程在不在、转发目标对不对、请求格式匹配不匹配。{detail:the gpt-5.6-sol model is not supported...}——这是配置层。模型名写错了去服务商文档核对准确名称。6.3 一个通用的验证方法配置改完别急着上真实任务先用一个最小请求验证链路通不通。比如用 curl 直接打你的代理端点curl -X POST http://127.0.0.1:8080/proxy/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的密钥 \ -d {model:deepseek-chat,messages:[{role:user,content:hi}]}能返回正常响应说明代理和转发链路是通的问题在工具侧返回错误说明问题在代理或目标服务侧。这一步能把问题范围砍掉一半非常值得养成习惯。7. 把 openrig 用顺手的几个经验配置这东西跑通一次不难难的是长期稳定。我分享几个实际用下来觉得最有价值的习惯。第一配置文件纳入版本管理但密钥绝不入库。把 YAML 配置文件放进 Git 仓库每次改动都有记录出问题能回滚。但密钥用环境变量占位仓库里只存占位符。这样既享受了版本管理的好处又不担心泄露。第二给每个模型来源单独建一个 profile不要临时改参数。临时改参数最容易忘改完这个忘了改回来下次用就出错。用 profile 管理切换只改一个active字段清晰且可追溯。第三本地模型和云端模型分开配置超时和重试策略。云端模型网络稳定超时可以设短一点重试次数少一点本地模型启动慢超时要设长重试要谨慎因为重试可能触发重复加载。混在一起配两边都不舒服。第四升级 Node.js 大版本前先备份全局包列表。用npm list -g --depth0导出当前全局安装的包升级后对照重装。Node 大版本升级有时会清掉全局目录没备份就得凭记忆重装很痛苦。第五遇到报错先看完整信息别只看最后一行。很多报错的根因在中间几行最后一行只是表象。比如权限错误最后一行说“安装失败”中间才说“EACCES”。养成看完整输出的习惯排查效率翻倍。这套东西搭起来之后你会发现真正花时间的不是安装而是理解每一层在做什么。一旦理解了环境层、配置层、运行层各自负责什么后面无论换什么工具、接什么模型都是同一套逻辑的复用。我自己从最早手动改配置到后来用 YAML 统一管理最大的体会就是把配置当成代码来对待稳定性和可维护性完全是两个量级。
