Claude Code接入国产模型先看协议

作者:php是最好的2026.11.17 03:20浏览量:0

简介:Claude Code默认使用Anthropic协议,国产模型多数只提供OpenAI兼容接口,直接填写会失败。本文说明两条可行路径:使用厂商的Anthropic兼容地址,或借助第三方路由转换协议。文中还给出环境变量配置、curl验证步骤、常见故障排查方法和选型核验维度,帮你少走弯路。

先弄清协议

Claude Code默认使用Anthropic的Messages接口。国产大模型多数提供的是OpenAI兼容接口,两者的请求格式、鉴权头和返回结构都不同。把OpenAI兼容地址直接填进Claude Code,通常会出现协议不匹配、流式输出异常或工具调用失败。

接入国产模型有两条路径:

  1. 使用厂商提供的Anthropic兼容接口,让Claude Code直接连接。
  2. 使用第三方路由或网关,把Claude Code发出的Anthropic请求转换为OpenAI格式,再转发给国产模型。

配置前先到厂商文档中查找是否提供Anthropic兼容地址。能直接连接的方案配置最简单,应优先考虑。

路径一:直接使用Anthropic兼容接口

Claude Code支持通过环境变量指定接口地址和密钥,常用变量如下:

  • ANTHROPIC_BASE_URL:接口地址,填写厂商文档给出的根地址。
  • ANTHROPIC_AUTH_TOKEN:鉴权令牌,填写厂商分配的密钥。
  • ANTHROPIC_MODEL:默认使用的模型ID。

示例中的密钥应从环境变量或密钥管理服务读取,不要写死在脚本里:

  1. export ANTHROPIC_BASE_URL="<厂商提供的Anthropic兼容地址>"
  2. export ANTHROPIC_AUTH_TOKEN="<从密钥管理服务读取的值>"
  3. export ANTHROPIC_MODEL="<控制台中复制的模型ID>"
  4. claude

也可以把同样的变量写入用户级配置文件 ~/.claude/settings.json 的env字段:

  1. {
  2. "env": {
  3. "ANTHROPIC_BASE_URL": "<厂商提供的Anthropic兼容地址>",
  4. "ANTHROPIC_AUTH_TOKEN": "<从密钥管理服务读取>",
  5. "ANTHROPIC_MODEL": "<模型ID>"
  6. }
  7. }

部分国产厂商已在官网发布Anthropic兼容接入说明,例如智谱、月之暗面、DeepSeek等。这些地址和可用模型会调整,请以各平台当前文档为准,逐一核验后再配置。

配置文件中若含有真实密钥,切勿放入会被提交到代码仓库的项目目录。个人密钥应保存在用户目录下,并确保不进入版本控制。

路径二:借助第三方路由转换协议

如果某个模型只提供OpenAI兼容接口,可以安装协议转换工具。这类工具对外模拟Anthropic接口,对内按OpenAI格式调用模型。LiteLLM代理、claude-code-router等开源项目属于这一类,具体以其官方文档为准。

使用前需确认以下三点:

  • 工具支持你所用的Claude Code版本。
  • 工具能转换工具调用(tool use)和流式输出。否则Claude Code读取文件、执行命令等功能会受限。
  • 工具配置文件中的provider、base_url、api_key、model字段,按其官方文档填写。

这些工具不属于Claude Code官方功能。Claude Code或工具升级后,协议细节可能变化,需要重新测试。

用curl验证接口

配置Claude Code之前,先测试接口本身。以下示例使用Anthropic兼容格式:

  1. curl "$ANTHROPIC_BASE_URL/v1/messages" \
  2. -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  3. -H "anthropic-version: 2023-06-01" \
  4. -H "content-type: application/json" \
  5. -d '{"model": "<模型ID>", "max_tokens": 64, "messages": [{"role": "user", "content": "你好"}]}'

如果厂商地址已经包含/v1,需要去掉路径中重复的部分。部分厂