企业官网建设流程全解析

1. 为什么 Claude Code 接本地模型总卡在格式上

Claude Code 的请求体是 Anthropic Messages 格式，而你在本地用 Ollama、vLLM 拉起来的模型，暴露的接口基本是 OpenAI 的/v1/chat/completions。这两套格式的字段名、消息结构、工具调用写法都不一样，直接把本地地址填进 Claude Code 的ANTHROPIC_BASE_URL，请求发出去就会被拒或者返回一堆解析错误。我试过最原始的办法：手写一个转换层，把 Anthropic 的messages、system、tools逐字段映射成 OpenAI 格式，再转发给本地端口。能跑，但每次换模型、换端口都要改代码，调试成本高得离谱。

CC-Switch 解决的就是这个中间层问题。它是一个桌面应用，统一管理 Claude Code、Codex、Gemini CLI 等 CLI 工具的供应商配置，核心能力是路由模式：把 Claude Code 发出的 Anthropic 格式请求，在本地转成 OpenAI 格式，再打到你的本地部署模型上。对开发者来说，这意味着你不需要改 Claude Code 源码，也不需要自己维护转换脚本，只要在图形界面里填好 Base URL、API Key、Model ID，打开路由开关，就能让 Claude Code 用上 Ollama 或 vLLM 里的模型。

这篇文章面向的是已经在本地跑起模型、想让 Claude Code 接进来的开发者。我会从环境准备讲到settings.json的实际写法，给出可复制的配置片段，演示一次完整的请求验证，最后把常见的 401、连接失败、reading choices报错逐个拆开排查。全程围绕 CC-Switch 的配置路径展开，不涉及任何网络加速工具，本地模型和远程 API 都按标准 HTTP 接口处理。

适合谁看：手里有 Ollama 或 vLLM 实例、想用 Claude Code 的交互体验但不想被 Anthropic 格式绑死的人；或者你已经在用第三方 OpenAI 兼容服务，想统一到 CC-Switch 里管理多套配置。下面按步骤走，每一步都有对应的文件和命令。

2. CC-Switch 安装与路由模式前置准备

CC-Switch 的安装本身不复杂，但路由模式能不能跑通，取决于几个前置条件是否满足。先把这些确认清楚，后面配置会顺很多。

2.1 安装 CC-Switch 并确认版本

Windows 用户从 Releases 页面下载CC-Switch-v{版本号}-Windows.msi安装包，或者用 Portable 绿色版解压即用。macOS 用户推荐 Homebrew：

brew tap farion1231/ccswitch brew install --cask cc-switch

安装完成后打开应用，默认界面里没有「路由」这一栏，这是正常的——路由模式需要手动开启后才会显示。先确认你装的是较新版本，旧版本可能没有路由功能。可以在关于页面看版本号，或者在 GitHub Releases 里对照更新日志。

2.2 本地模型服务要先能独立访问

在配置 CC-Switch 之前，先用 curl 确认你的本地模型服务是通的。以 Ollama 为例，默认监听11434端口：

curl http://127.0.0.1:11434/v1/models

如果返回模型列表 JSON，说明服务正常。vLLM 默认端口通常是8000，启动命令类似：

python -m vllm.entrypoints.openai.api_server \ --model Qwen/Qwen2.5-7B-Instruct \ --host 0.0.0.0 \ --port 8000

启动后用curl http://127.0.0.1:8000/v1/models验证。这一步很关键：如果本地服务本身没起来，CC-Switch 里怎么填都是连不上的，后面排查会白费功夫。

2.3 确认模型 ID 和 API Key 规则

OpenAI 兼容接口一般要求Authorization: Bearer <key>头。Ollama 默认不校验 Key，但为了兼容 Claude Code 的请求头，你可以在 CC-Switch 里随便填一个非空字符串，比如ollama。vLLM 如果启动时加了--api-key参数，就要填对应的值。

模型 ID 必须和/v1/models返回的id字段完全一致。Ollama 里ollama list看到的名称就是模型 ID，比如qwen2.5:7b。vLLM 的模型 ID 通常是你启动时--model参数的值。这个 ID 后面要填进 CC-Switch 的高级选项里，填错会直接导致model not found。

2.4 开启路由模式

打开 CC-Switch 设置，找到路由开关并打开。开启后主界面会出现「路由」一栏。路由模式的作用是在本地起一个转换服务，Claude Code 把请求发给这个本地服务，它再转成 OpenAI 格式转发给你的本地模型。所以路由开启后，Claude Code 的ANTHROPIC_BASE_URL指向的其实是 CC-Switch 的本地路由地址，而不是模型地址本身。这个链路关系要先理清楚，否则配置时容易把两个地址搞混。

前置准备做到这里就够了：CC-Switch 装好、本地模型能 curl 通、模型 ID 确认、路由开关打开。接下来进入实际配置。

3. 可复制的 settings.json 与 Base URL 改写示例

这一节是核心操作区。CC-Switch 的图形界面会帮你写配置文件，但理解它到底改了什么，出问题时你才能自己定位。Claude Code 的配置文件在用户目录下的.claude/settings.json，CC-Switch 切换供应商时会更新这个文件。

3.1 添加 OpenAI 格式供应商

在 CC-Switch 主界面点击「添加供应商」，选择「自定义」。填写三个关键字段：

Base URL 填你的本地模型地址加/v1，比如http://127.0.0.1:11434/v1。注意这里不要填 CC-Switch 路由地址，路由地址是 CC-Switch 自己管理的，你填的是最终模型服务地址。API Key 按 2.3 的规则填。然后在高级选项里填模型 ID。

保存后点击「启用」，此时会弹出提示需要配置路由——这是预期行为，因为 Claude Code 默认只认 Anthropic 格式，OpenAI 格式必须走路由转换。回到设置确认路由已开启，再重新点一次「启用」，显示「切换成功」即可。

3.2 settings.json 的实际内容

CC-Switch 写入的~/.claude/settings.json结构大致如下。不同版本字段可能略有差异，但核心是env块里的两个地址：

{ "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:xxxx", "ANTHROPIC_API_KEY": "your-key-here", "ANTHROPIC_MODEL": "qwen2.5:7b" } }

这里的ANTHROPIC_BASE_URL指向的是 CC-Switch 路由服务监听的本地端口，不是你的 Ollama 端口。CC-Switch 会在内部把 Anthropic 格式请求转成 OpenAI 格式，再转发到你在供应商里填的 Base URL。所以你在供应商配置里填http://127.0.0.1:11434/v1，而 settings.json 里看到的是另一个端口，这是正常的，不要手动去改 settings.json 里的地址，改了会绕过路由导致格式不匹配。

如果你要手动核对，可以打开这个文件对照。但建议通过 CC-Switch 界面操作，避免手改出错。CC-Switch 还支持「通用配置片段」，把 Key 和地址之外的通用数据（比如插件配置）在供应商之间传递，切换时不会丢。

3.3 多套配置的切换逻辑

CC-Switch 的价值在多供应商场景下最明显。你可以同时配好 Ollama 本地、vLLM 本地、以及一个远程 OpenAI 兼容服务，每个供应商一套 Base URL + Key + Model ID。切换时点「启用」，CC-Switch 会重写 settings.json 并重启路由指向。Claude Code 支持热切换，不用重启终端，这点比 Codex 方便——Codex 改完配置通常要重开终端。

如果你用 Codex，它的配置在~/.codex/auth.json和config.toml里，CC-Switch 也能统一管理。三件套同样是 Base URL、Key、Model ID，只是文件格式不同。Cline 的 MCP 配置也是类似思路，把供应商信息集中到 CC-Switch 里管，避免每个工具各配一套。

配置写完后，下一步就是发一次真实请求验证链路。

4. 一次请求验证与日志排查动作

配置保存不等于链路通。这一节用一次完整的请求，把 Claude Code 到本地模型的整条路径跑通，并给出日志排查的具体动作。

4.1 发起验证请求

打开终端，进入一个项目目录，启动 Claude Code：

claude

然后在交互界面里输入一句简单的话，比如「用一句话说明这个目录里有什么文件」。Claude Code 会把请求发给 settings.json 里的ANTHROPIC_BASE_URL，也就是 CC-Switch 路由服务，路由转成 OpenAI 格式后打到你的本地模型。

如果一切正常，你会看到模型返回的内容。第一次请求可能稍慢，因为本地模型要加载或预热。观察返回内容是否符合预期，如果返回的是乱码或空内容，说明格式转换或模型输出有问题，进入排查环节。

4.2 用 curl 直接验证路由层

为了区分是 Claude Code 的问题还是路由层的问题，可以绕过 Claude Code，直接对 CC-Switch 路由地址发一个 Anthropic 格式请求。先从 settings.json 里拿到ANTHROPIC_BASE_URL的值，假设是http://127.0.0.1:xxxx：

curl -X POST http://127.0.0.1:xxxx/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: your-key-here" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "qwen2.5:7b", "max_tokens": 100, "messages": [{"role": "user", "content": "hello"}] }'

如果这个请求返回正常的 JSON 响应，说明路由层和本地模型都通，问题在 Claude Code 侧。如果这个请求也失败，看返回的错误信息：连接拒绝说明路由服务没起来，401 说明 Key 不对，model not found说明模型 ID 填错。

4.3 查看 CC-Switch 日志

CC-Switch 的日志是排查的关键。在应用界面里找到日志面板，或者查看数据目录下的日志文件。数据存储路径大致是：

~/.cc-switch/cc-switch.db # 数据库 ~/.cc-switch/settings.json # 本地设置 ~/.cc-switch/backups/ # 备份 ~/.cc-switch/skills/ # Skills

日志里会记录每次请求的转发目标、状态码、耗时。如果看到请求打到了错误的端口，或者转换过程中字段丢失，日志里会有线索。重点看转发目标 URL 是否和你填的 Base URL 一致，以及响应状态码。

4.4 确认本地模型侧收到请求

如果路由日志显示请求已发出但模型没响应，去本地模型服务侧看日志。Ollama 的日志在启动终端里直接输出，vLLM 也是。确认模型服务收到了/v1/chat/completions请求，并且返回了 200。如果模型侧报context length exceeded或invalid request，说明转换后的请求体有问题，可能是max_tokens或消息格式不兼容。

走完这四步，链路基本就清晰了：Claude Code → CC-Switch 路由 → 本地模型，哪一段断了都能定位。下面把常见报错集中拆解。

5. 常见报错排查：401、连接失败与 reading choices

这一节对照真实报错逐个处理。这些错误我在配置本地模型时基本都遇到过，按顺序排查能省不少时间。

5.1 401 Unauthorized

报错长这样：

API Error: 401 Unauthorized - invalid api key

原因通常是 Key 不匹配。分两种情况：本地模型不校验 Key 时，CC-Switch 里填的 Key 必须非空，随便填一个字符串即可，但空字符串会导致请求头缺失被拒。vLLM 如果启动时带了--api-key，CC-Switch 里必须填完全一致的值。另外检查请求头字段：Anthropic 用x-api-key，OpenAI 用Authorization: Bearer，路由层负责转换，如果转换没生效，模型侧收到的是错误的头字段，也会 401。确认路由开关是打开的。

5.2 local proxy failed / 连接被拒绝

报错类似：

local proxy failed: connect ECONNREFUSED 127.0.0.1:xxxx

这说明 CC-Switch 路由服务没起来，或者端口被占用。先确认路由开关是开的，然后检查端口是否被其他进程占用。macOS/Linux 用lsof -i :端口号，Windows 用netstat -ano | findstr 端口号。如果端口冲突，在 CC-Switch 设置里换一个端口。还有一种情况是本地模型服务没启动，路由转发时连不上模型端口，也会报连接失败，这时去 curl 一下模型地址确认。

5.3 reading choices 报错

报错长这样：

failed to parse response: reading 'choices'

这是格式转换的典型问题。路由层期望模型返回 OpenAI 格式的choices数组，但模型返回的结构不对。常见原因：模型服务不是标准的 OpenAI 兼容接口，或者返回了错误信息而不是正常响应。先用 4.2 的 curl 直接打模型地址，看返回的 JSON 里有没有choices字段。如果没有，说明模型服务本身不兼容 OpenAI 格式，需要换用支持该格式的部署方式。Ollama 和 vLLM 默认都返回标准格式，如果用了自定义封装层，要检查封装层是否透传了原始响应。

5.4 OAuth 与官方登录切换

如果你之前用官方登录，切到第三方供应商后想切回去，在预设里添加一个「官方登录」供应商，切换过去后执行一遍 Log out / Log in 流程。之后就能在官方和第三方之间随意切换。注意 OAuth 相关的报错通常和登录态有关，切换供应商后如果 Claude Code 提示认证失败，先确认当前启用的是哪个供应商，再检查是否需要重新登录。

5.5 模型 ID 不匹配

报错：

model not found: qwen2.5:7b

模型 ID 必须和/v1/models返回的完全一致，大小写、冒号、版本号都不能差。Ollama 里用ollama list确认，vLLM 用启动参数确认。CC-Switch 高级选项里填的模型 ID 会写进 settings.json 的ANTHROPIC_MODEL，如果这里填错，Claude Code 发出的请求里模型名就是错的，路由转发后模型侧找不到对应模型。

排查顺序建议：先 curl 模型地址确认服务通，再 curl 路由地址确认转换通，最后看 Claude Code 的 settings.json 确认地址和模型 ID 正确。三步走完，大部分问题都能定位。

6. 把本地模型接进 Claude Code 的稳定用法

配置跑通之后，日常使用还有几个细节值得注意。CC-Switch 的通用配置片段功能建议开启，这样切换供应商时插件、Skills 等通用数据不会丢。如果你同时用 Claude Code 和 Codex，可以在 CC-Switch 里统一管理两套配置，Codex 的auth.json和config.toml也按 Base URL、Key、Model ID 三件套填，切换逻辑一致。

本地模型的上下文长度和并发能力有限，Claude Code 在处理大文件时可能触发context length exceeded。这时可以在 CC-Switch 的高级选项里调小max_tokens，或者换用上下文更长的模型。vLLM 启动时可以用--max-model-len控制上限，和 Claude Code 的请求参数对齐。

如果你需要更稳定的远程模型服务作为补充，可以在 CC-Switch 里再加一个 OpenAI 兼容供应商，Base URL 填https://taotoken.net/api，Key 和模型 ID 按服务商文档填。这样本地模型和远程服务可以在同一个界面里切换，Claude Code 侧不用改任何配置。模型对话验证可以走 模型对话，长期编码和 Agent 场景可以看 Coding Plan，Key 的管理在 API Keys，接入细节参考 接入文档。

最后提醒一点：CC-Switch 的备份目录~/.cc-switch/backups/会保留配置历史，改坏了可以从这里恢复。配置文件不要手动改 settings.json 里的路由地址，所有变更走 CC-Switch 界面，避免路由层和配置文件不一致。本地模型服务建议用 systemd 或 supervisor 托管，保证开机自启，不然每次重启机器都要手动拉起模型，Claude Code 会连不上。