Claude Code 接入自定义第三方 Anthropic API 网关的完整配置与排错

很多开发者在配置 Claude Code 时，真正卡住的不是安装命令，而是 API 配置：

• ANTHROPIC_BASE_URL到底填什么？
• ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY有什么区别？
• CLI 能用，为什么 VSCode 插件没反应？
• 模型名复制过来后，为什么还是model not found？
• 自定义 API 网关、第三方兼容服务、OpenAI 兼容接口是不是一回事？

Claude Code 接入 Anthropic API 或 Anthropic API 兼容网关，本质上只需要先搞清楚三件事：

1. 请求发到哪里：Endpoint / Base URL；
2. 用什么身份访问：Token / API Key；
3. 调用哪个模型：Model ID。

本文按实际配置顺序整理 Claude Code 接入自定义 Anthropic API 网关的配置方法、验证流程和常见报错排查，适合正在配置 CLI 或 VSCode 插件的开发者参考。

一、Claude Code API 配置的三个核心变量

Claude Code 读取 API 配置时，最常见、最关键的是下面三类变量。

新手配置时，不建议一开始就堆很多高级环境变量。先用这三项跑通，再考虑模型分层、子代理模型、流量控制等配置。

二、ANTHROPIC_BASE_URL：配置 API 请求地址

ANTHROPIC_BASE_URL决定 Claude Code 把请求发送到哪里。

如果你使用 Anthropic 官方 Claude API，通常按照官方文档配置即可，不一定需要额外改 Base URL。

如果你使用的是自定义 Anthropic API 网关或第三方 Claude API 兼容服务，一般需要把ANTHROPIC_BASE_URL改成服务商提供的兼容接口地址。

示例：

export ANTHROPIC_BASE_URL="https://你的-api-地址"

这里有两个常见坑。

1. Base URL 是否需要带/v1

不同服务的接口路径设计可能不一样。

有的服务商给出的地址可能是：

https://example.com

有的可能是：

https://example.com/v1

不要凭经验随便加或删/v1，应该以你正在使用的 API 服务文档为准。

如果 Base URL 路径错误，可能出现：

• 连接失败；
• 404；
• 请求被转发到错误路径；
• Claude Code 提示无法连接 Anthropic。

2. OpenAI 兼容接口不等于 Claude Code 一定能用

很多模型平台提供 OpenAI 兼容接口，例如：

/v1/chat/completions

但 Claude Code 面向的是 Anthropic / Claude 相关协议和交互方式，不能简单理解为：

只要平台兼容 OpenAI，就一定能接 Claude Code。

判断一个 API 能不能给 Claude Code 使用，重点看两点：

• 是否明确支持 Anthropic API / Claude API 兼容；
• 是否提供 Claude Code 对应的配置说明。

如果平台只写了 OpenAI 兼容，没有说明 Anthropic API 兼容，就不建议直接套用 Claude Code 配置。

三、ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY怎么选

很多教程里会同时出现：

ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY

这也是新手最容易混淆的地方。

一般来说：

• ANTHROPIC_API_KEY更常见于 Anthropic 官方 API Key 配置；
• ANTHROPIC_AUTH_TOKEN经常出现在部分 Claude Code 配置方式，或者一些 Anthropic API 兼容网关的 Token 配置中。

但实际使用时，不同版本、不同插件、不同网关平台，对变量名的要求可能不完全一致。

最稳妥的原则是：

服务商文档要求你用哪个变量名，就用哪个变量名，不要自行替换。

例如文档明确要求：

export ANTHROPIC_AUTH_TOKEN="你的-api-key"

那就不要擅自改成：

export ANTHROPIC_API_KEY="你的-api-key"

很多配置不生效，并不是 Key 本身错误，而是变量名写错了。

四、ANTHROPIC_MODEL：模型名必须使用当前平台支持的 ID

ANTHROPIC_MODEL用于指定 Claude Code 默认调用的模型。

示例：

export ANTHROPIC_MODEL="你的模型名"

这里最常见的问题是复制旧教程里的模型名。

模型 ID 可能随着平台更新而变化，不同服务的模型路由名称也可能不一样。你在 A 平台能用的模型名，换到 B 平台未必还能使用。

如果遇到：

model not found

或者请求返回 404，不要第一时间怀疑 Token，也不要反复重填 Key。

更合理的排查顺序是：

1. 打开服务商后台或文档；
2. 找到当前实际可用的模型列表；
3. 复制完整模型 ID；
4. 更新ANTHROPIC_MODEL；
5. 重新启动 Claude Code 或相关终端会话。

五、Claude Code 常见配置入口

Claude Code 的配置失败，很多时候不是 API 不可用，而是配置写错了位置。

常见配置方式大致有三类。

需要特别注意：

Claude Code CLI 的配置文件，不一定会影响 VSCode 插件；VSCode 的settings.json，也不等于 Claude Code CLI 的settings.json。

如果你主要在终端执行：

claude

优先检查 Claude Code CLI 配置。

如果你主要通过 VSCode 插件入口、Spark 图标或侧边栏使用 Claude Code，优先检查 VSCode 插件配置。

六、方式一：使用环境变量临时配置 Claude Code

这是最适合新手验证 API 是否可用的方式。

macOS / Linux

export ANTHROPIC_BASE_URL="https://你的-api-地址" export ANTHROPIC_AUTH_TOKEN="你的-api-key" export ANTHROPIC_MODEL="你的模型名" claude

如果你的服务要求使用ANTHROPIC_API_KEY，则按文档改为：

export ANTHROPIC_BASE_URL="https://你的-api-地址" export ANTHROPIC_API_KEY="你的-api-key" export ANTHROPIC_MODEL="你的模型名" claude

Windows PowerShell

$env:ANTHROPIC_BASE_URL="https://你的-api-地址" $env:ANTHROPIC_AUTH_TOKEN="你的-api-key" $env:ANTHROPIC_MODEL="你的模型名" claude

如果服务要求使用ANTHROPIC_API_KEY：

$env:ANTHROPIC_BASE_URL="https://你的-api-地址" $env:ANTHROPIC_API_KEY="你的-api-key" $env:ANTHROPIC_MODEL="你的模型名" claude

这种方式的优点是简单直接，适合验证配置是否正确。

缺点是环境变量通常只在当前终端窗口有效，关闭窗口后就会失效。

七、方式二：写入 Claude Codesettings.json

如果你准备长期在命令行中使用 Claude Code，可以把环境变量写入 Claude Code 的配置文件。

macOS / Linux 常见路径：

~/.claude/settings.json

Windows 常见路径：

%USERPROFILE%\.claude\settings.json

最小可用配置示例：

{ "env": { "ANTHROPIC_BASE_URL": "https://你的-api-地址", "ANTHROPIC_AUTH_TOKEN": "你的-api-key", "ANTHROPIC_MODEL": "你的模型名" } }

如果你的服务要求使用ANTHROPIC_API_KEY，则写成：

{ "env": { "ANTHROPIC_BASE_URL": "https://你的-api-地址", "ANTHROPIC_API_KEY": "你的-api-key", "ANTHROPIC_MODEL": "你的模型名" } }

错误示例：不要重复嵌套env

下面这种写法是错误的：

{ "env": { "env": { "ANTHROPIC_BASE_URL": "..." } } }

正确结构应该只有一层env：

{ "env": { "ANTHROPIC_BASE_URL": "..." } }

如果 JSON 结构写错，Claude Code 可能完全读不到配置。

八、方式三：配置 VSCode Claude Code 插件

如果你使用的是 Claude Code for VSCode，通常需要在 VSCode 用户设置 JSON 中配置环境变量。

打开方式：

1. 打开 VSCode；
2. 使用命令面板；
3. 搜索并执行：

Preferences: Open User Settings (JSON)

常见写法示例：

{ "claudeCode.environmentVariables": { "ANTHROPIC_BASE_URL": "https://你的-api-地址", "ANTHROPIC_AUTH_TOKEN": "你的-api-key", "ANTHROPIC_MODEL": "你的模型名" } }

如果服务要求使用ANTHROPIC_API_KEY，则改为：

{ "claudeCode.environmentVariables": { "ANTHROPIC_BASE_URL": "https://你的-api-地址", "ANTHROPIC_API_KEY": "你的-api-key", "ANTHROPIC_MODEL": "你的模型名" } }

注意，不同版本插件字段可能会变化，具体字段名以插件文档为准。

常见误区是：

• 把 VSCode 插件配置写进~/.claude/settings.json；
• 把 CLI 配置写进 VSCode 用户设置；
• 以为 CLI 能用，插件就一定能用；
• 以为插件能用，终端里的claude命令就一定能用。

CLI 和 VSCode 插件的配置入口要分开排查。

九、最小验证流程：不要一上来测试复杂项目

配置完成后，建议先用最小流程验证，而不是直接让 Claude Code 分析大型项目。

1. CLI 验证

在终端运行：

claude

进入会话后，先输入：

请回复 ok

如果能正常回复，说明至少以下几项大概率没问题：

• API 地址可达；
• 鉴权信息有效；
• 模型名可用；
• Claude Code 能完成基础调用。

接着可以继续测试项目读取能力：

请概括当前项目的目录结构，并指出主要入口文件。

如果 Claude Code 能读取当前项目并给出合理说明，基础配置基本可用。

2. VSCode 插件验证

如果你使用 VSCode 插件，可以按下面顺序检查：

1. 打开一个项目目录；
2. 打开一个具体代码文件；
3. 确认插件入口、Spark 图标或状态栏是否出现；
4. 输入一个简单问题，确认能回复；
5. 让它针对当前文件提出修改建议；
6. 检查是否出现 diff 和授权提示。

如果 CLI 能用，但 VSCode 插件没有反应，优先检查：

• VSCode 用户设置是否写对；
• 插件版本是否兼容；
• 插件字段名是否发生变化；
• 插件是否启用；
• 是否打开了工作区或文件。

不要一开始就急着更换 API Key。

十、进阶配置：Opus、Sonnet、Haiku 和 Subagent 模型

当最小配置跑通后，再考虑模型分层会更稳。

Claude Code 中常见的进阶模型相关变量包括：

示例配置：

{ "env": { "ANTHROPIC_BASE_URL": "https://你的-api-地址", "ANTHROPIC_AUTH_TOKEN": "你的-api-key", "ANTHROPIC_MODEL": "你的默认模型名", "ANTHROPIC_DEFAULT_SONNET_MODEL": "你的主力编码模型", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "你的轻量模型", "CLAUDE_CODE_SUBAGENT_MODEL": "你的子代理模型", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1", "CLAUDE_CODE_DISABLE_TERMINAL_TITLE": "1" } }

新手不建议一开始就把所有变量都填满。

原因很简单：

• 模型越多，排查越复杂；
• 不同模型的路由名可能不同；
• 不同模型的速度、能力、成本可能不同；
• 出错时很难判断是哪一层模型配置有问题。

更推荐的顺序是：

1. 先只配置ANTHROPIC_MODEL；
2. 确认 Claude Code 可以稳定调用；
3. 再添加ANTHROPIC_DEFAULT_SONNET_MODEL；
4. 最后根据任务类型配置 Haiku、Opus 或 Subagent 模型。

十一、常见报错与排查方向

下面是配置 Claude Code API 时比较常见的错误现象。

排查时建议先盯住三项：

Base URL Token / API Key Model ID

这三项确认无误后，再去看：

• JSON 格式；
• 配置文件路径；
• VSCode 插件字段；
• 网络环境；
• 账号权限；
• 模型权限；
• 插件版本。

十二、推荐配置顺序

如果你是第一次配置 Claude Code，建议按下面顺序来。

1. 先用终端环境变量临时测试

不要一开始就写复杂配置文件。

先执行：

export ANTHROPIC_BASE_URL="https://你的-api-地址" export ANTHROPIC_AUTH_TOKEN="你的-api-key" export ANTHROPIC_MODEL="你的模型名" claude

测试：

请回复 ok

能回复后，再继续下一步。

2. 再写入 Claude Codesettings.json

确认临时环境变量可用后，再写入：

{ "env": { "ANTHROPIC_BASE_URL": "https://你的-api-地址", "ANTHROPIC_AUTH_TOKEN": "你的-api-key", "ANTHROPIC_MODEL": "你的模型名" } }

这样更容易判断问题来自 API 本身，还是来自配置文件格式。

3. 如果使用 VSCode，再单独配置插件

VSCode 插件用户再配置：

{ "claudeCode.environmentVariables": { "ANTHROPIC_BASE_URL": "https://你的-api-地址", "ANTHROPIC_AUTH_TOKEN": "你的-api-key", "ANTHROPIC_MODEL": "你的模型名" } }

然后测试：

• 插件入口是否出现；
• 简单对话是否正常；
• 当前文件上下文是否可用；
• diff 和授权提示是否正常。

4. 最后再添加模型分层

等基础链路稳定后，再逐步添加：

ANTHROPIC_DEFAULT_SONNET_MODEL ANTHROPIC_DEFAULT_HAIKU_MODEL ANTHROPIC_DEFAULT_OPUS_MODEL CLAUDE_CODE_SUBAGENT_MODEL

不要一次性配置太多变量，否则排查成本会明显增加。

十三、安全与维护建议

Claude Code 配置里最敏感的是 API Key 或 Token。

建议注意以下几点：

• 不要把 API Key 写进项目仓库；
• 不要把个人 Key 放进团队共享配置；
• 截图、录屏、直播时记得打码；
• 定期轮换 Key；
• 一旦发现泄露，及时删除或重置；
• .claude/settings.json和项目代码最好分开管理；
• 企业使用前，需要关注服务商的日志、隐私、权限和开票规则；
• 模型名、Base URL、插件字段都可能随版本变化，建议定期查看官方或服务商文档。

总结

Claude Code 接入自定义 Anthropic API 网关时，不要先死记一长串变量名，而要先理解配置逻辑：

ANTHROPIC_BASE_URL 决定请求发到哪里 ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY 决定用什么身份访问 ANTHROPIC_MODEL 决定调用哪个模型

新手最稳的配置方式是：

1. 先用终端环境变量跑通；
2. 再写入 Claude Codesettings.json；
3. VSCode 插件单独配置；
4. 最后再做模型分层和体验优化。