跳到主要内容

Claude Code

Claude Code 可以从环境变量或设置文件读取端点和认证设置。当 Claude Code 需要通过兼容 Anthropic 的 AISIX 网关而非直接调用 Anthropic 时，可使用这些设置。

本指南将 Claude Code 指向 AISIX，并使用 AISIX 调用方 API Key 认证。你还需要选择一个可通过 Anthropic Messages 路由访问的 AISIX 模型别名。

前置条件​

开始前，请准备以下内容：

  • 安装 Claude Code。
  • 一个正在运行且 Claude Code 可以访问的 AISIX 网关。
  • 一个 AISIX 调用方 API Key。
  • 一个调用方 API Key 可以通过 Anthropic Messages 访问的 AISIX 模型别名。请使用 Anthropic 支持的别名，以保留 Anthropic 特有的请求和响应行为。

如果你的组织已经部署 AISIX，请向管理团队获取网关 URL、模型别名和调用方 API Key。否则，请按照开源 AISIX 网关快速上手或 AISIX Cloud 快速上手完成部署，也可以联系 API7申请 Hybrid Cloud 访问权限。

配置 Claude Code​

启动 Claude Code 前，设置端点、调用方 API Key 和模型别名：

# 请替换为实际值
export ANTHROPIC_BASE_URL="http://127.0.0.1:3000"
export ANTHROPIC_AUTH_TOKEN="YOUR_CALLER_API_KEY"
export ANTHROPIC_MODEL="claude-sonnet-prod"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-sonnet-prod"

claude

ANTHROPIC_BASE_URL 将 Claude Code 指向 AISIX。Claude Code 会把 ANTHROPIC_AUTH_TOKEN 作为 Bearer Token 发送，因此 AISIX 将其作为调用方 API Key 接收。ANTHROPIC_MODEL 和 ANTHROPIC_DEFAULT_HAIKU_MODEL 应填写 AISIX 模型别名，而不是上游服务提供方模型 ID。两个变量可以指向同一别名，也可以为 Claude Code 的后台行为配置一个独立的快速别名。

若要让这些设置在每次启动 Claude Code 时生效，请将其写入 Claude Code 设置文件的 env 块：

~/.claude/settings.json
{
  "model": "claude-sonnet-prod",
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:3000",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_CALLER_API_KEY",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-sonnet-prod"
  }
}

验证集成​

启动 Claude Code 并发送一条简短提示词。

请求成功后，请确认以下结果：

  • Claude Code 输出模型响应。
  • AISIX 为所选模型别名记录一条成功的 POST /v1/messages 请求。

AISIX 会验证调用方 API Key、检查模型访问权限、解析模型别名、应用策略，并将请求分发到别名背后的上游服务提供方。

请在 AISIX 网关日志中验证请求。也可以使用已配置的指标或上游服务提供方日志。

排查 Claude Code 请求​

Claude Code 可能发送 Anthropic 特有字段和 Beta 请求头。请使用由 Anthropic 支持的 AISIX 模型别名以获得直接的协议兼容性，并验证团队计划部署的 Claude Code 工作流。

如果 Claude Code 报告端点、认证或模型错误，请检查以下内容：

现象检查项
认证失败确认 ANTHROPIC_AUTH_TOKEN 是 AISIX 调用方 API Key，且该 Key 可以访问所选模型别名。
找不到模型确认 ANTHROPIC_MODEL 与 ANTHROPIC_DEFAULT_HAIKU_MODEL 是该调用方 API Key 可访问的 AISIX 模型别名。
请求到达 AISIX 但上游失败确认别名指向兼容的上游模型和服务提供方 Key。
工具或 Beta 行为失败确认所选 AISIX 路由和上游服务提供方是否支持相应 Anthropic 特性。

有关端点行为，请参阅 Anthropic Messages。

后续步骤​