Claude Code 如何配置第三方 API

为什么要给 Claude Code 配置第三方 API

Claude Code 是面向终端和代码仓库的智能编程助手。默认情况下，它会连接 Anthropic 官方服务；但在企业团队、跨模型调度、统一账单或网络出口受限的场景里，把 Claude Code 接到第三方 API 网关会更方便。

第三方 API 通常会提供一个 Anthropic 兼容的入口，让你继续使用 Claude Code 的交互方式，同时把请求统一路由到团队指定的模型服务、代理或 AI 网关。这样做的核心价值不是“多写几个环境变量”，而是把模型访问、鉴权、审计和成本治理收敛到同一层。

Claude Code 支持哪些配置入口

根据 Claude Code 官方文档，环境变量可以直接在 shell 中设置，也可以写入 settings.json 的 env 字段中，让每次启动自动生效。常用配置包括：

• ANTHROPIC_BASE_URL：覆盖默认 API endpoint，用于把请求路由到代理或网关。
• ANTHROPIC_API_KEY：作为 X-Api-Key 发送的 API key。
• ANTHROPIC_AUTH_TOKEN：作为 Authorization: Bearer ... 发送的自定义 token。
• ANTHROPIC_MODEL 或默认模型相关变量：用于指定希望 Claude Code 使用的模型。
• ANTHROPIC_CUSTOM_HEADERS：当网关要求额外 header 时使用。

如果你只是临时验证，推荐先在当前终端 session 里导出环境变量；如果确认稳定，再写入 ~/.claude/settings.json 或项目级 .claude/settings.local.json。

方式一：临时通过环境变量启动

macOS、Linux 或 WSL 可以这样配置：

export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
export ANTHROPIC_API_KEY="sk-your-third-party-key"

claude

如果你的第三方服务要求 Bearer token，而不是 X-Api-Key，可以改用：

export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="your-gateway-token"

claude

注意：ANTHROPIC_AUTH_TOKEN 的值会被 Claude Code 加上 Bearer 前缀，不需要自己再写一遍 Bearer。

方式二：写入 settings.json 持久化

个人全局配置可以放在：

~/.claude/settings.json

示例：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway.example.com",
    "ANTHROPIC_API_KEY": "sk-your-third-party-key",
    "ANTHROPIC_MODEL": "claude-sonnet-4-5"
  }
}

如果只想对某个项目生效，可以放在项目目录下的：

.claude/settings.local.json

这个文件适合保存个人实验配置和本地密钥，不建议提交到 Git。团队共享的非敏感配置可以放在 .claude/settings.json，但 API key、token、网关密钥这类信息应始终留在本地或密钥管理系统中。

方式三：用 apiKeyHelper 避免明文密钥

如果不希望把 key 写进配置文件，可以使用 apiKeyHelper。它会执行一个脚本，并把脚本输出作为认证值发送。

{
  "apiKeyHelper": "security find-generic-password -s claude-code-gateway -w",
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway.example.com"
  }
}

在团队环境里，这种方式比把密钥写进 settings.json 更稳妥。你也可以把它换成读取 Vault、1Password CLI、AWS Secrets Manager 或内部密钥服务的脚本。

配置第三方 API 时最容易踩的坑

第一，确认网关到底兼容 Anthropic API 还是 OpenAI API。Claude Code 使用的是 Anthropic 风格的请求；如果你的网关只提供 OpenAI 兼容接口，通常还需要网关侧做协议转换。

第二，确认 ANTHROPIC_BASE_URL 是否需要包含版本路径。有些网关要求只填域名根路径，有些网关要求带 /v1。这里没有通用答案，应该以网关文档为准。

第三，不要把 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 混着乱配。前者走 X-Api-Key，后者走 Authorization。如果网关只识别其中一种 header，配错后就会出现 401 或 403。

第四，模型名要使用网关支持的模型名。可以先配置一个网关确认支持的 Sonnet 或 Opus 等价模型，再逐步扩展到不同任务的默认模型。

第五，如果公司网络需要代理，可以同时配置 HTTPS_PROXY 或 HTTP_PROXY。这和 ANTHROPIC_BASE_URL 不是一回事：代理负责网络出口，Base URL 负责模型请求路由。

建议的验证步骤

配置完成后，不要马上在生产仓库里做大规模改动。建议先做三个小测试：

1. 运行 claude --version，确认本地 Claude Code 正常安装。
2. 在空目录里启动 claude，问一个简单问题，确认能收到回复。
3. 在测试项目里让 Claude Code 读取一个无敏感信息的小文件，确认工具调用、模型响应和网络延迟都符合预期。

如果遇到鉴权失败，优先检查 key、header 类型、Base URL 路径和网关模型名。如果遇到连接失败，再检查本地代理、公司网络策略和证书配置。

安全建议

第三方 API 配置最重要的是密钥边界。不要把真实 key 写进仓库，也不要把 .env、.claude/settings.local.json 或密钥目录提交到 Git。

可以在 Claude Code 的权限设置里显式拒绝读取敏感文件，例如：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

这样即使在自动化或多人协作环境中，也能减少密钥被误读、误贴或误提交的风险。

小结

Claude Code 配置第三方 API 的主线很清楚：用 ANTHROPIC_BASE_URL 指向网关，用 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN 完成鉴权，再根据需要设置模型和自定义 header。

对个人开发者来说，环境变量足够快速；对团队来说，settings.json、apiKeyHelper 和统一 API 网关会更适合长期维护。只要把密钥管理、模型名、Base URL 路径和验证步骤处理好，Claude Code 就可以比较自然地接入第三方模型服务。