最近折腾 Claude Code 接三方模型网关，发现这件事看着像是填几个环境变量，实际最容易在协议、地址和模型名上互相打架。

我们把 Claude Code、Claude Code Router，也就是 CCR，再到三方网关的链路捋清楚。

参考环境是 Windows，三方网关以 Box （脱敏，译名）为例，它对外提供 OpenAI Chat Completions 接口。

先记住一个结论：Claude Code 不直接连接 Box，中间要经过 CCR。

调用链

Claude Code 说的是 Anthropic Messages 协议，Box 这边接的是 OpenAI Chat Completions 协议。两边像是在说不同方言，直接对话自然容易尴尬。

CCR 就是中间那个翻译、分流和接待请求的本地网关。

完整链路可以这样理解：

1. Claude Code 把请求发给本机的 CCR。
2. 请求进入 CCR 后，由 Provider 和 Router 决定往哪里走。
3. CCR 把 Anthropic Messages 请求转换成三方网关能识别的 OpenAI Chat Completions 请求。
4. Box 再把请求转给下游模型。
5. 返回结果沿原路回来，CCR 负责把响应接回 Claude Code 能使用的形态。

所以排查时别只盯着 Claude Code。它能不能工作，至少取决于 Claude Code、CCR、Provider、三方网关和模型 ID 这几处能不能对上。

安装前先看环境

Claude Code

先按官方快速开始文档安装 Claude Code CLI。

安装完成后，新开一个 PowerShell 或 CMD，确认命令已经进入 PATH。

# 查看 Claude Code 是否已经安装
claude --version

# 如果命令找不到，查看系统实际能不能找到它
where.exe claude
​

这里建议新开终端再试一次。Windows 的 PATH 刚改完，旧窗口不一定立刻认账。

CCR 和 Node.js

CCR CLI 需要 Node.js 22 或更高版本。

我们先看版本，再安装 CCR。

# CCR 的运行基础是 Node.js 22 或更高版本
node --version
npm --version

# 全局安装 Claude Code Router
npm install -g @musistudio/claude-code-router

# 确认 CCR 命令可用
ccr --version
​

到这里，Claude Code 是客户端，CCR 是本地网关，三方网关是上游服务。角色不要混了，后面配置时会少走不少弯路。

配好 CCR 网关

CCR 有管理界面和配置文件两种方式。个人更习惯先用管理界面把 Provider 配起来，想精确控制时再看 config.json。

启动管理界面

# 启动 CCR 管理界面
ccr ui

# 不想自动打开浏览器时使用这个
ccr ui --no-open
​

默认管理地址是 http://127.0.0.1:3456/ui，模型网关地址是 http://127.0.0.1:3456。

排查启动问题时，可以让 CCR 以前台方式运行。

# 前台启动，方便直接看启动输出
ccr serve --no-open
​

配置 Provider

如果 Box 提供的是 OpenAI Chat Completions 接口，CCR 的 Provider 可以按下面的结构配置。

{
  "LOG": true,
  "LOG_LEVEL": "debug",
  "CLAUDE_PATH": "",
  "HOST": "127.0.0.1",
  "PORT": 3456,
  "APIKEY": "给ClaudeCode用的API",
  "API_TIMEOUT_MS": "600000",
  "PROXY_URL": "",
  "transformers": [],
  "Providers": [
    {
      "name": "Box",
      "api_base_url": "https://Box.com/oneapi/v1/chat/completions",
      "api_key": "sk-your-key",
      "models": [
        "DeepSeek V4 Flash"
      ],
      "transformer": {
        "use": [
          "OpenAI"
        ]
      }
    }
  ],
  "Router": {
    "default": "Box,DeepSeek V4 Flash",
    "background": "Box,DeepSeek V4 Flash",
    "think": "Box,DeepSeek V4 Flash",
    "longContext": "Box,DeepSeek V4 Flash",
    "longContextThreshold": 60000,
    "webSearch": "DeepSeek V4 Flash,DeepSeek V4 Flash",
    "image": ""
  },
  "CUSTOM_ROUTER_PATH": ""
}
​

这里有几个位置我会重点检查。

• api_base_url 要写三方网关真正提供的完整接口地址。参考配置使用的是 /oneapi/v1/chat/completions。
• api_key 是三方网关的 Key，示例里只写占位符，实际值不要贴进文章、日志或截图。
• models 里的模型名要和三方网关接受的模型 ID 一致。
• transformer.use 写 OpenAI，表示 CCR 要把请求转成 OpenAI Chat Completions 这一侧的格式。
• Router 里的目标要写成 Provider 名和模型名的组合。

配置里的 APIKEY 是给 Claude Code 使用的 CCR Client Key，不是 Box 的上游 Key。两把钥匙服务不同位置，别图省事填成同一个。

模型路由怎么理解

default 是普通请求使用的默认路由，background、think 和 longContext 分别对应不同请求场景。

这几项示例里都指向 Box,DeepSeek V4 Flash，意思是交给名为 Box 的 Provider，再使用它提供的 DeepSeek V4 Flash 模型。

longContextThreshold 是长上下文阈值，参考配置里是 60000。webSearch 和 image 也有自己的路由位置，当前资料里的图片路由为空。

路由名字看起来只是字符串，实际上它要同时匹配 Provider 和模型配置。只要其中一个拼错，后面就可能冒出 Missing model。

让 Claude Code 连上 CCR

CCR 配好了，还要告诉 Claude Code：不要找默认服务，去访问本机这个网关。

在 Windows 下可以创建 start-claude-gateway.bat，把网关配置限制在这次启动的进程里。

@echo off
setlocal

rem 这里只配置当前启动过程使用的网关
rem 地址、凭据和模型名按实际环境替换
set "ANTHROPIC_BASE_URL=http://127.0.0.1:3456"
set "ANTHROPIC_AUTH_TOKEN=ccr-client-key"
set "ANTHROPIC_MODEL=DeepSeek V4 Flash"

rem 不要把三方网关的上游 Key 填到这里
set "ANTHROPIC_API_KEY="

echo Claude Code gateway: %ANTHROPIC_BASE_URL%
echo Claude Code model: %ANTHROPIC_MODEL%

claude %*

set "EXIT_CODE=%ERRORLEVEL%"
endlocal & exit /b %EXIT_CODE%
​

这几个环境变量的职责要分开看。

• ANTHROPIC_BASE_URL 指向 CCR，本例是 http://127.0.0.1:3456。
• ANTHROPIC_AUTH_TOKEN 使用 CCR 管理界面里创建的 Client Key。
• ANTHROPIC_MODEL 写三方网关接受的模型 ID。
• ANTHROPIC_API_KEY 留空，不要把 Box 的上游 Key 填进来。

脚本的好处是不会把变量永久写入系统环境，也不容易影响其他项目。要换模型或换网关，改脚本再启动就行。

验证

我们不要一上来就进入 Claude Code 里反复试请求。先确认 CCR 本身活着。

# 启动 CCR 管理界面和本地网关
ccr ui

# 检查本地健康状态
curl.exe http://127.0.0.1:3456/health
​

健康检查通过后，再运行启动脚本。

.\start-claude-gateway.bat
​

如果 Claude Code 能正常启动，但调用模型失败，就说明问题大概率已经从本地进程启动，转移到了认证、路由、协议或上游地址。这个判断很重要，排查范围能立刻缩小。

常见问题怎么查

本地无法连接

先请求健康检查地址。

curl.exe http://127.0.0.1:3456/health
​

然后逐项确认：

• CCR 是否真的启动。
• ANTHROPIC_BASE_URL 是否是 http://127.0.0.1:3456。
• Claude Code 用的是否是 CCR Client Key。
• ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 是否同时配置成了互相冲突的值。

200 但格式不对

HTTP 200 不等于 Claude Code 能读懂响应。

如果 Box 只有 /chat/completions 接口，Provider 就必须启用 OpenAI Chat 转换。

可以按这个顺序看：

Claude Code  →  Anthropic Messages
CCR          →  Box 的实际协议
​

也就是说，问题不一定在“有没有返回”，而可能在“返回是不是对的协议”。这类问题很像快递已经送到，但收件人拿到的是另一种格式的单据，签收不了。

路径不存在

检查 CCR 日志里的实际请求地址。

参考资料里的 Box OneAPI 地址是：

https://Box.ipay.so/oneapi/v1/chat/completions
​

/api/v1 和 /oneapi/v1 不要混用。地址只差一小段，结果却可能直接变成 404，离离原上谱。

Missing model

遇到 Missing model，重点看四个地方：

1. CCR Provider 里的模型 ID。
2. Claude Code 的 ANTHROPIC_MODEL。
3. CCR Agent Config 是否已经 Apply。
4. CCR 日志里的 resolved provider/model。

还要确认 Box 是否要求另外一套内部模型 ID。模型展示名和真正请求名不一致，是这类问题里很常见的一根刺。

日志怎么留

CCR 日志可能包含 Prompt、系统上下文、工具定义和响应摘要。

排查时只查看必要字段，不要把完整日志公开，更不要上传 Key、Token、代码、请求体或响应体。

我一般先看请求地址、Provider、模型名和错误状态，能定位问题就收手，没必要把整段上下文都摊出去。

小结

这套链路的关键不是把三个工具都装上，而是让每一层各司其职。

Claude Code 负责发起 Anthropic Messages 请求，CCR 在本地做接入、认证、模型路由和协议转换，三方网关再通过 OpenAI Chat Completions 接口把请求送到下游模型。

真正配置时，优先检查四件事：本地地址、两类 Key、模型 ID、Provider 的转换器。

启动后先查 /health，再进 Claude Code 验证；出现错误时按本地连接、路径、协议、模型和日志边界逐层排查。

链路看清楚了，剩下就是把占位符换成自己的配置。

别把真实密钥贴出来，这条规矩看着老生常谈，真踩一次就不想再谈了。

那就开始尝试吧。