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 和模型别名：

# ANTHROPIC_BASE_URL 是网关源地址，不含末尾斜杠或 /v1
# 本地快速入门使用 http://127.0.0.1:3000
export ANTHROPIC_BASE_URL="YOUR_AISIX_GATEWAY_URL"
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": "YOUR_AISIX_GATEWAY_URL",
    "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。

后续步骤

• Anthropic Messages：查看路由行为和兼容性边界。
• 指标与用量事件：查看网关指标和每次尝试的用量事件。
• 安全护栏：添加请求或响应策略检查。