跳到主要内容

Claude Code

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

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

前置条件​

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

  • 安装 Claude Code。
  • 一个代理监听器可用的运行中 AISIX 网关。
  • 一个 AISIX 调用方 API Key。
  • 一个可用于 Anthropic Messages 的 AISIX 模型别名。对于 Claude Code，使用 Anthropic 支持的别名最稳妥，因为它最直接保留 Anthropic 特有的请求和响应行为。

配置 Claude Code​

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

# Replace with your values
export ANTHROPIC_BASE_URL="http://127.0.0.1:3000"
export ANTHROPIC_AUTH_TOKEN="YOUR_CALLER_API_KEY"
export ANTHROPIC_MODEL="claude-demo"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-demo"

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-demo",
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:3000",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_CALLER_API_KEY",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-demo"
  }
}

验证路由​

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

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

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

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

如果使用 AISIX Cloud 或私有化部署的托管控制面，请在托管网关日志中验证请求。对于自托管网关，请使用已配置的日志、指标或上游服务提供方请求日志。

处理兼容性问题​

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。

后续步骤​