★ FEATURED ARTICLE 1. 为什么要在内网把 Claude Code 接到魔搭私有化模型Claude Code 本身是个命令行里的编码 Agent能读你当前目录的文件、跑命令、改代码默认走 Anthropic 官方接口。但很多团队的真实情况是代码不能出内网模型必须跑在自己的机器或公司集群上公网 API 根本用不了。这时候就需要一条「Claude Code → 本地路由 → 私有化模型」的链路而 CC Switch 正好是这条链路里最省事的一环。魔搭ModelScope这边有两种用法一种是直接用它的在线推理接口另一种是把模型权重拉到本地或内网机器上用 vLLM、SGLang 之类的框架起一个 OpenAI 兼容服务。后者就是所谓的私有化部署服务地址通常长这样http://10.0.0.23:8000/v1/chat/completions只在内网可达。问题在于Claude Code 说的是 Anthropic 的/v1/messages协议而你的私有化服务说的是 OpenAI 的/chat/completions协议两边对不上直接填地址必然报错。CC Switch 的价值就在这它在本地起一个小路由把 Claude Code 发出来的 Anthropic 格式请求翻译成 OpenAI 格式再转发给你的私有化服务回来的结果再翻译回去。你不需要改 Claude Code 的源码也不用自己写中间层。这篇就按「装 Claude Code → 装 CC Switch → 配魔搭在线模型 → 配内网私有化模型 → 验证一次对话 → 排错」的顺序走一遍每一步都给可复制的配置片段。适合谁看手上已经有内网模型服务、想让 Claude Code 用起来的开发者或者想先用魔搭在线模型跑通链路、再换成私有化地址的人。前置条件就三个Node.js 18 以上、一个能访问的模型服务地址、以及对应的 API Key私有化场景下很多服务不校验 Key随便填也行但字段不能空。我试过在 Windows 上用 Windows Terminal 操作比默认 PowerShell 顺手中文不会乱码。下面命令在 macOS / Linux 的 bash 里同样适用路径换成~/.claude/即可。2. 装好 Claude Code 与 CC Switch 这两件工具先说 Claude Code 的安装。它是个 npm 全局包一条命令搞定npm install -g anthropic-ai/claude-code装完验证版本claude --version能打印出版本号就说明 CLI 可用了。如果提示claude: command not found多半是 npm 全局 bin 目录没进 PATH用npm config get prefix看一下路径把它加到环境变量里。接着装 CC Switch。它的作用是图形化管理多个 provider 配置省得你手动改settings.json。到 GitHub Releases 页面下载对应平台的安装包Windows 选.msi一路 NextmacOS 选.dmg拖进 Applications。装完打开界面左侧是供应商列表右侧是配置表单。这里有个概念要先理清CC Switch 管的是「Claude Code 该往哪个地址发请求」。它最终会写进C:\Users\你的用户名\.claude\settings.jsonmacOS/Linux 是~/.claude/settings.json。这个文件是 Claude Code 启动时读的里面有个env段指定ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。CC Switch 帮你把这两个值填好你就不用记路径了。装完先别急着配模型确认一下 Claude Code 能启动。第一次运行claude会要求登录 Anthropic 账号但我们走的是自定义接口不需要登录。跳过登录的办法是在settings.json里加一行{ hasCompletedOnboarding: true }注意这是加在顶层和已有的键值对之间要有逗号。加完再运行claude就不会弹登录了。这一步很关键很多人卡在「一直让我登录」就是因为没加这个字段。还有一点你在哪个目录下运行claude它就把那个目录当工作区能读该目录下所有文件。所以建议cd到你的项目根目录再启动别在用户主目录下跑不然它会去扫一堆无关文件。3. 可复制的 provider 配置魔搭在线与内网私有化这一节是核心分两种场景给配置。先看魔搭在线推理接口适合先跑通链路。在 CC Switch 里点「新增供应商」预设选「自定义配置」然后填字段值供应商名称modelscope-online随便起请求地址https://api-inference.modelscope.cnAPI Key魔搭生成的 Access Token去掉ms-前缀实际请求模型模型库里的 Model ID如Qwen/Qwen2.5-7B-Instruct注意请求地址后面不要加/v1CC Switch 会自己拼。API Key 那个ms-前缀要去掉这是魔搭的约定带着会 401。配完保存CC Switch 会往settings.json写类似这样的内容{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:xxxx, ANTHROPIC_AUTH_TOKEN: your-token }, hasCompletedOnboarding: true }那个127.0.0.1:xxxx是 CC Switch 本地路由的地址端口它自己分配。也就是说 Claude Code 的请求先到本地路由路由再转发到魔搭。现在说私有化部署。你的内网服务是 OpenAI 兼容格式地址类似http://10.0.0.23:8000接口是/v1/chat/completions。CC Switch 期望的是 Anthropic 格式所以必须开启路由转换。在 CC Switch 里编辑供应商服务端地址填完整的 OpenAI 兼容地址不要以/结尾并打开「完整 URL」开关。高级选项里API 格式选OpenAI Chat Completions需开启路由。实际请求模型按你服务加载的模型名填比如 vLLM 启动时--served-model-name default这里就填default。API Key 如果内网服务不校验随便填个非空字符串。对应的settings.json会长这样{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:xxxx, ANTHROPIC_AUTH_TOKEN: sk-local-anything }, hasCompletedOnboarding: true }关键点在于ANTHROPIC_BASE_URL指向的永远是 CC Switch 的本地路由不是你的内网服务地址。内网地址是填在 CC Switch 的 provider 表单里的由它去转发。很多人搞混这一点直接把内网地址写进settings.json结果协议不匹配报reading choices之类的错。如果你不用 CC Switch想手动配那settings.json里就得直接写内网地址但那样就没有协议转换除非你的服务本身支持 Anthropic 格式。所以私有化场景下 CC Switch 基本是必需的。4. 发一次对话请求验证链路是否通配置写完验证分两步先确认本地路由活着再确认端到端能出结果。第一步看settings.json是否被正确写入。打开C:\Users\你的用户名\.claude\settings.json确认ANTHROPIC_BASE_URL指向127.0.0.1的某个端口且hasCompletedOnboarding为true。如果这个文件里还是官方地址说明 CC Switch 没保存成功回去检查表单。第二步在项目目录下启动 Claude Codecd /path/to/your/project claude进去之后用/model命令看当前模型。如果你配了多个 provider这里会列出来选你刚配的那个。然后直接输入一句话测试比如「读一下当前目录的 README用一句话总结」。如果链路通它会去读文件并返回总结。想更纯粹地验证接口连通性可以绕过 Claude Code直接用 curl 打你的内网服务确认服务本身没问题curl http://10.0.0.23:8000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-local-anything \ -d { model: default, messages: [{role: user, content: ping}], max_tokens: 16 }能返回 JSON 且choices[0].message.content有内容说明内网服务正常。这一步排除了服务端问题剩下的错就都在 CC Switch 或 Claude Code 侧。再验证 CC Switch 的本地路由。找到它监听的端口在 CC Switch 界面或settings.json里能看到直接打curl http://127.0.0.1:xxxx/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-local-anything \ -H anthropic-version: 2023-06-01 \ -d { model: default, max_tokens: 16, messages: [{role: user, content: ping}] }注意这里用的是 Anthropic 格式/v1/messages、x-api-key、anthropic-version如果 CC Switch 路由正常它会翻译成 OpenAI 格式转发出去返回 Anthropic 格式的响应。这一步通了Claude Code 里基本就没问题。实测下来最容易出问题的是模型名对不上。内网 vLLM 启动时--served-model-name是什么CC Switch 里「实际请求模型」就得填什么差一个字符都会 404。5. 常见报错排查清单401、local proxy failed、reading choices这一节按真实报错来对。遇到问题先看 Claude Code 终端里的报错再对照下面。401 Unauthorized。两种可能一是魔搭在线场景下 API Key 没去掉ms-前缀或者 Token 过期二是私有化场景下内网服务其实校验了 Key而你填的是随便的字符串。排查办法先用第 4 节的 curl 直接打上游服务确认 Key 对不对。如果 curl 通但 Claude Code 报 401那就是 CC Switch 里 Key 字段没填对或者settings.json里的ANTHROPIC_AUTH_TOKEN和 CC Switch 表单不一致。local proxy failed / connection refused。这是 CC Switch 的本地路由没起来或者端口被占。表现是 Claude Code 连127.0.0.1:xxxx直接失败。先确认 CC Switch 进程还在跑没被关掉再看端口有没有被别的程序占用换个端口重启 CC Switch。还有一种情况是settings.json里的端口和 CC Switch 实际监听的不一致手动对齐一下。reading choices / unexpected response shape。这个错通常出现在协议没转换成功的时候。Claude Code 期望 Anthropic 格式的响应结果收到了 OpenAI 格式的原始 JSON解析choices字段就崩了。根因是 CC Switch 里「API 格式」没选OpenAI Chat Completions需开启路由或者「完整 URL」开关没打开。回去把这两个开关确认一遍。另外如果你的内网服务返回的是流式 SSE而 CC Switch 版本较老不支持流式转换也会出这个错升级 CC Switch 到较新版本。OAuth / 一直要求登录。就是第 2 节说的hasCompletedOnboarding没加或者加错了位置。它必须在settings.json顶层不能嵌在env里面。加完保存重开终端再运行claude。模型返回空 / 一直转圈。多半是上游服务超时或模型没加载完。先用 curl 打上游确认能出结果再看 CC Switch 日志界面上一般有日志入口。如果上游是 vLLM确认--max-model-len够大Claude Code 发的 prompt 可能很长超了会被截断或报错。排查顺序建议固定成先 curl 上游 → 再 curl 本地路由 → 最后看 Claude Code。这样能快速定位是服务端、路由层还是客户端的问题别一上来就改settings.json。6. 把链路固定下来长期编码与多模型切换链路跑通之后日常用起来还有几个点值得固化。第一CC Switch 支持多 provider 并存你可以同时配「魔搭在线」和「内网私有化」两个用/model随时切。在线那个用来做轻量问答内网那个用来处理敏感代码互不干扰。切换时 CC Switch 会重写settings.json不用手动改。第二如果你团队里多人共用一套内网模型服务把 CC Switch 的 provider 配置导出成 JSON 发给同事他们导入即可省得每人重填。注意导出文件里可能含 API Key内网场景下 Key 通常不敏感但魔搭在线的 Token 别外传。第三长期跑编码任务的话建议把 Claude Code 的工作目录固定成项目根配合.claude/settings.json做项目级配置。CC Switch 写的是用户级~/.claude/settings.json项目级配置会覆盖它两者别冲突。第四如果你想让 Claude Code 走一个更稳定的中转来管理多个模型出口可以了解下 TaoToken 的 Coding Plan它把模型接入和额度管理放在一起适合需要长期跑 Agent 的场景。接入文档在 https://taotoken.net/api API Key 在 https://taotoken.net/api-keys 管理模型对话入口在 https://taotoken.net/chat 。配置方式和上面 CC Switch 的思路一致Base URL 填 TaoToken 的地址Key 填生成的 TokenModel ID 填你要用的模型名三件套对齐就能通。最后提醒一句私有化部署的模型能力参差不齐7B 级别的模型在 Claude Code 里做复杂重构会比较吃力建议至少上到能稳定输出结构化内容的尺寸。链路本身是通的效果取决于你后端挂的是什么模型。
阅读完成 · 觉得有帮助？
