Claude Code 接入第三方 API：先验证，再配置

更新于 2026-10-31 · onehop.cyou

简答：可以，但前提是服务提供 Anthropic Messages API 兼容端点，而不是只有 OpenAI Compatible 的 `/v1/chat/completions`。最短路径是：确认 Base URL、认证类型和模型 ID，先用临时环境变量发送 `/v1/messages` 请求，再启动 Claude Code 运行 `/status`；CLI、VS Code 和桌面版的配置入口并不完全相同。本文按 2026-10-31 核验到的 Claude Code 官方文档整理。

定义：Claude Code 配置第三方 API，是通过 `ANTHROPIC_BASE_URL` 指向兼容 Anthropic 请求格式的网关，并使用 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY` 或 `apiKeyHelper` 完成认证。

先判断是否适用：你需要准备什么

本文适用于已经拿到 API 网关或兼容服务配置的开发者，重点是 Claude Code CLI、VS Code 扩展和桌面版的 API 接入。本站是第三方 AI API 接入指南，不是 Claude Code 官方站；具体网关的地址、模型、计费、限速和数据处理规则，应以该网关当前文档和实际响应为准。

Claude Code 需要服务端提供 Anthropic 格式的消息接口。官方文档说明，网关应公开支持的 API 格式；如果服务只提供 OpenAI 的 Chat Completions 接口，不能仅靠修改 `ANTHROPIC_BASE_URL` 就保证兼容。网关还需要持续转发 Claude Code 新版本使用的请求字段和功能。

配置前向服务商确认四项信息：基础 URL、认证类型、模型 ID，以及是否需要额外请求头。官方接入文档列出的认证选择是：Bearer Token 或 Authorization header 使用 `ANTHROPIC_AUTH_TOKEN`；API key 或 `x-api-key` 使用 `ANTHROPIC_API_KEY`；需要轮换或从密钥库取值时使用 `apiKeyHelper`。可参考 Claude Code 连接 LLM 网关官方说明。

配置前自查表

项目	应向服务商确认的内容	缺失时先检查
Base URL	基础地址是否应拼接 `/v1/messages`	404、路径重复、请求地址错误
认证	Bearer Token 还是 API Key	401、请求头不匹配
模型 ID	API 实际接受的完整字符串	模型不存在或无权限
接口格式	是否兼容 Anthropic Messages API	请求体、工具调用或流式响应不兼容

第一步：临时配置并发送最小请求

首次配置建议只在当前终端设置变量，验证通过后再写入设置文件。官方文档说明，shell 变量只对当前终端及其启动的程序有效；从 Dock、开始菜单或其他主管程序启动的编辑器，可能看不到这些变量。

macOS、Linux、WSL：Bearer Token

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"

export ANTHROPIC_AUTH_TOKEN="YOUR_GATEWAY_TOKEN"

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d '{"model":"YOUR_MODEL_ID","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

macOS、Linux、WSL：x-api-key

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"

export ANTHROPIC_API_KEY="YOUR_GATEWAY_KEY"

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d '{"model":"YOUR_MODEL_ID","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

Windows PowerShell：x-api-key

$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"

$env:ANTHROPIC_API_KEY = "YOUR_GATEWAY_KEY"

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" -Headers @{ "x-api-key" = "$env:ANTHROPIC_API_KEY"; "anthropic-version" = "2023-06-01" } -ContentType "application/json" -Body '{"model":"YOUR_MODEL_ID","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

如果网关要求 Bearer Token，PowerShell 中将 `x-api-key` 改为 `Authorization`，值改为 `Bearer $env:ANTHROPIC_AUTH_TOKEN`。官方最小验证请求使用 `/v1/messages`；成功时通常应看到以消息 ID 开头并包含 `content` 字段的 JSON。若返回“未知模型”，仍可能说明 URL 和凭证已经通过前置验证，下一步核对模型 ID。命令格式和成功判定可对照官方网关连接与验证文档。

这里的域名、密钥和模型均为占位符。某些网关还要求租户、路由或版本请求头，不能根据本文自行添加；应按网关文档设置 `ANTHROPIC_CUSTOM_HEADERS` 或对应的额外参数。

第二步：进入 Claude Code 并确认实际配置

从执行环境变量的同一个终端运行 claude。
发送一个简短提示，确认能返回正常文本。
运行 /status，检查是否显示网关的 Anthropic base URL。
检查状态中显示的是 Auth token、API key 或其他凭证来源，而不是仍使用保存的账户登录。
再测试代码读取、工具调用和较长输出，不要把第一次成功的短请求直接视为所有功能都兼容。

官方文档明确建议通过 `/status` 检查基础 URL 和活动凭证来源；如果没有显示网关地址，说明变量没有到达当前会话。参考官方“在 Claude Code 中确认”部分。

如果只设置了 `ANTHROPIC_BASE_URL` 而没有设置网关凭证，保存的登录可能仍会参与认证。网关凭证变量优先于保存的 claude.ai 登录或 Console 密钥：`ANTHROPIC_AUTH_TOKEN` 会立即优先；交互模式下首次使用 `ANTHROPIC_API_KEY` 可能需要确认。要清除保存的登录，可在 Claude Code 中运行 /logout；要恢复原登录，则取消设置网关凭证变量。

临时、持久化、清理：四种配置方式怎么选

不同入口的作用范围与清理方法

方式	适用场景	生效范围	清理或回滚
当前 shell	第一次验证、临时切换网关	当前终端及其子进程	macOS/Linux/WSL 用 `unset`；PowerShell 用 `Remove-Item Env:变量名`
用户级设置	个人所有项目长期使用	`~/.claude/settings.json`；Windows 为 `%USERPROFILE%\.claude\settings.json`	删除 `env` 中相关键，重新启动 Claude Code
项目本地设置	仅当前项目测试或个人覆盖	`.claude/settings.local.json`	删除文件或相关键，并确认已加入 `.gitignore`
VS Code 用户设置	VS Code 扩展启动检查	`claudeCode.environmentVariables`	从 VS Code 用户设置 JSON 删除对应对象并重启扩展
桌面版本地环境	桌面版本地会话	桌面版的本地环境编辑器	编辑或删除保存的环境变量，再重新启动会话

shell 示例：

unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY

Remove-Item Env:ANTHROPIC_BASE_URL,Env:ANTHROPIC_AUTH_TOKEN,Env:ANTHROPIC_API_KEY

设置文件示例：

{ "env": { "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com", "ANTHROPIC_AUTH_TOKEN": "YOUR_GATEWAY_TOKEN", "ANTHROPIC_MODEL": "YOUR_MODEL_ID" } }

官方文档说明，shell 与设置文件同时设置相同变量时，通常由设置文件的值覆盖继承自 shell 的值；运行中的会话不会因为从文件删除变量就立即取消设置，通常要重新启动 Claude Code。项目共享的 `.claude/settings.json` 会进入代码仓库，不应放个人密钥；本地文件应加入 `.gitignore`。详细作用域和优先级见设置文件和优先级官方文档以及环境变量官方参考。

如果密钥曾出现在 shell 历史、提交记录或公开日志中，删除文本并不足够，应在网关控制台撤销旧密钥、生成新密钥，再更新配置。不要把完整 Authorization 头、Cookie 或密钥复制到问题报告。

认证冲突的完整判断：两个变量不要同时猜着填

`ANTHROPIC_AUTH_TOKEN` 和 `ANTHROPIC_API_KEY` 不是同一个变量的两个别名：前者发送 `Authorization: Bearer`，后者发送 `x-api-key`。如果两个变量同时存在，不能把它们当成冗余备份；应只保留服务商明确要求的一种，并用 `/status` 和最小请求确认实际结果。官方文档明确了两类变量的请求头映射以及它们与已保存登录之间的冲突处理。

认证来源判断顺序

检查项	判断	处理
网关团队说明 Bearer	使用 `ANTHROPIC_AUTH_TOKEN`	清除不需要的 `ANTHROPIC_API_KEY`
网关团队说明 x-api-key	使用 `ANTHROPIC_API_KEY`	清除不需要的 `ANTHROPIC_AUTH_TOKEN`
两者均无	不能凭 Key 外观判断	先向服务商确认；官方建议可先尝试 Auth Token，再根据 401 切换
设置文件与 shell 不同	设置文件值通常覆盖 shell 值	检查用户级和项目本地文件，再重启会话
变量与保存登录同时存在	网关凭证优先于保存登录	运行 `/status`；需要时 `/logout`

这里的“先尝试再根据 401 切换”是本文的排查建议，不应理解为所有网关都支持两种认证。最终以网关团队给出的认证类型和实际响应为准。

VS Code、桌面版和 CLI：配置入口不能混用

CLI

CLI 可以读取 shell 环境变量和 Claude Code 设置文件。若需要后台代理也始终走网关，官方建议使用设置文件，而不要只依赖当前 shell。

VS Code 扩展

VS Code 扩展的启动检查使用 VS Code 用户设置中的 claudeCode.environmentVariables。示例：

{ "claudeCode.environmentVariables": [ { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" }, { "name": "ANTHROPIC_AUTH_TOKEN", "value": "YOUR_GATEWAY_TOKEN" } ] }

仅写入 ~/.claude/settings.json 可能能影响生成的进程，但不一定通过扩展自己的登录检查；因此 CLI 能用而 VS Code 仍提示登录时，先检查 VS Code 用户设置，保存后重启扩展。

桌面版 Claude Code

桌面版不是简单复用 CLI 的 `ANTHROPIC_BASE_URL` 入口。官方文档说明，桌面版通过“第三方推理配置”读取网关路由，而不是从 `ANTHROPIC_BASE_URL` 或 `settings.json` 读取。没有组织下发配置时，可在“帮助 → 故障排除 → 启用开发者模式”后，进入“开发者 → 配置第三方推理”，填写网关基础 URL；组织下发的配置优先级更高。

桌面版还可以在本地环境编辑器中为本地会话设置环境变量，但这与桌面版的第三方推理路由配置不是完全相同的入口。启用网关配置后，部分依赖 claude.ai 身份的功能可能不可用；如果桌面版提示网关不可达，先用上面的最小请求检查 URL 和网络路径。具体入口以当前桌面版界面和桌面版官方文档为准。

模型 ID、/v1 和版本升级后的复核清单

`ANTHROPIC_MODEL` 用于指定 Claude Code 请求使用的模型字符串，但它不是把服务商展示名称自动转换成 API 模型 ID。模型名应使用网关文档、模型列表或实际错误响应中给出的精确字符串。若网关启用了模型发现，可按官方说明设置 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1，再用 /model 检查发现结果；没有模型列表时，不要自行猜测别名。

Base URL 也不能机械地统一写成“必须带 `/v1`”或“绝对不能带 `/v1`”。本文示例把 Base URL 设为可以拼接出 /v1/messages 的地址；如果服务商给的是完整端点或已经包含版本路径，应以其文档定义为准，并直接检查最终请求地址，避免形成 `/v1/v1/messages`。

升级 Claude Code 后，重新执行以下清单：

运行 claude --version，记录当前版本。
确认 shell、用户设置、项目本地设置和 VS Code 用户设置中没有旧的重复变量。
核对 Base URL 是否仍能拼接出正确的消息端点。
核对模型 ID 是否仍被网关接受。
分别用 Bearer 或 x-api-key 的最小请求复测，不要同时发送两套猜测凭证。
从实际使用的入口启动 Claude Code、VS Code 或桌面版。
运行 `/status`，检查基础 URL 和活动凭证来源。
最后再测试工具调用、流式输出和较长请求。

官方网关文档提醒，Claude Code 会持续增加功能；如果网关没有转发新请求字段，升级后可能出现兼容性问题。因此，升级复核应以实际请求和状态信息为准，而不是只看客户端能否启动。

401、403、404、429、超时：固定排错闭环

错误分流速查

现象	先核对	下一步
401	认证变量和请求头	确认 Bearer 与 x-api-key 类型，清理另一套变量后重试
403	Key 权限、模型权限、来源限制	让网关提供方确认账户和目标模型权限
404	最终 URL、`/v1` 拼接、消息路径	直接打印或复现最终请求地址
429	限速、余额、并发和服务端策略	查看响应体与网关控制台，不把网关结果泛化成 Claude Code 规则
超时	网络、代理、网关处理时间	先用 `max_tokens: 1` 的短请求复现，再查看网关日志
流式中断	SSE 转发、代理缓冲、超时设置	先测试短输出和非流式路径，再核对网关兼容性
模型不存在	模型 ID 是否为 API 接受的字符串	使用服务商文档、模型列表或错误响应中的精确名称

固定闭环是：确认 Key → 确认 Base URL → 确认最终请求地址 → 确认模型 ID → 发最小请求 → 再启动 Claude Code → 用 `/status` 检查实际配置。响应不是 JSON 时，保留 HTTP 状态码、request ID 和脱敏正文；不要把完整密钥复制到日志。

结论：配置成功的最小判定

服务端明确支持 Anthropic Messages API 格式。
Base URL 能拼接出正确的 `/v1/messages` 或服务商定义的消息端点。
认证类型与请求头匹配，只保留实际需要的认证变量。
最小请求返回可识别的消息 JSON，或至少能区分认证通过与模型不存在。
Claude Code 的 `/status` 显示网关 Base URL 和活动凭证来源。
VS Code 使用自己的 `claudeCode.environmentVariables` 检查入口。
桌面版使用第三方推理配置或本地环境编辑器，不把 CLI 变量入口直接当成桌面版入口。
升级后重新核对版本、变量、地址、模型、最小请求和 `/status`。

如果具体网关的模型、价格、限速、数据保留或可用状态没有公开可核验资料，应标记为“未核实”，并以该服务当前文档和实际响应为准。

常见问题

Claude Code 可以直接连接 OpenAI Compatible API 吗？

不能仅靠修改 Base URL 保证连接。服务端需要提供 Claude Code 可用的 Anthropic Messages API 兼容入口；如果只有 OpenAI Chat Completions 接口，应先确认是否另有 Anthropic 格式端点。

ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 同时存在时怎么办？

不要把两者当成自动切换的备用 Key。前者对应 Authorization: Bearer，后者对应 x-api-key；应按网关文档只保留需要的一种，再用最小请求和 `/status` 检查。网关凭证变量会优先于保存的账户登录。

为什么 CLI 能用，VS Code 仍然提示登录？

CLI 的 shell 环境变量不一定通过 VS Code 扩展的启动检查。将 Base URL 和凭证放入 VS Code 用户设置的 `claudeCode.environmentVariables`，保存后重启扩展，再检查会话状态。

桌面版能直接读取 ~/.claude/settings.json 吗？

不能把 CLI 的入口直接等同于桌面版入口。官方文档说明，桌面版网关路由通过第三方推理配置读取；本地会话的环境变量则使用桌面版环境编辑器。具体入口以当前桌面版界面为准。

Base URL 应该写域名根路径还是带 /v1？

取决于服务商定义。本文示例要求最终形成 `Base URL/v1/messages`，但如果服务商提供的地址已包含版本路径，应避免重复拼接。最可靠的方法是查看实际请求地址并发送最小请求。

模型不存在但 URL 和 Key 看起来正确，下一步做什么？

使用服务商提供的精确 API 模型 ID，不要把展示名称自行改写。若网关支持模型发现，可按官方文档启用模型发现并在 `/model` 中查看结果；否则以网关模型列表或错误响应为准。

参考资料

将 Claude Code 连接到 LLM 网关｜Claude Code 官方文档（code.claude.com）
其他 LLM 网关｜Claude Code 官方文档（code.claude.com）