Claude Code API 路由器设置：基础 URL、模型和使用日志

Claude Code API 路由器设置与更改 OpenAI SDK 基础 URL 不同。Claude Code 使用 Anthropic Messages 网关的格式，因此重要的检查项是路由器根地址、凭证标头、Claude Code 将发送的模型名称以及证明请求已到达正确账户的使用记录。

本指南为开发人员、AI 产品团队、自动化构建者、平台工程师、财务运营人员和采购审核人员提供了一个面向生产的 Flatkey 设置。在您将日常编码工作转移到 Claude Code API 路由器之前，本指南涵盖了基础 URL、单令牌预检、模型名称、网关模型发现、使用日志和故障模式。

来源说明：本文于 2026 年 6 月 29 日根据官方 Claude Code LLM 网关文档、Claude Code 网关连接指南、网关协议参考、模型配置文档、监控文档以及当前的 Flatkey 公开页面进行了核对。没有使用特定于账户的 Flatkey 密钥进行实时的 Claude Code 冒烟测试，因此以下代码片段是供您使用自己的密钥和经批准的模型运行的模板。

快速解答：Claude Code API 路由器设置

要使用 Flatkey 设置 Claude Code API 路由器，请使用 Flatkey Claude Code 路由器根地址、一个 Flatkey 密钥以及您的账户可以调用的确切 Claude 模型名称来配置 Claude Code。然后在开始长时间的编码会话之前测试 Anthropic Messages 端点。

以上是简短版本。本 Claude Code API 路由器指南的其余部分将这些字段转化为可重复的设置操作手册。

Claude Code 官方网关文档确认了什么

Claude Code 官方网关概述将 LLM 网关定义为 Claude Code 与模型提供商之间的代理。Claude Code 将 API 流量发送到网关，网关再使用由组织控制的提供商凭证将其转发。同一页面列出了网关的优势，例如集中式凭证、使用情况跟踪、成本控制、审计日志和提供商切换。

基础 URL 规则是特定的。Claude Code 通常将请求发送到 Anthropic 的 API，但设置 ANTHROPIC_BASE_URL 会将这些请求指向网关。然后，连接指南通过向 $ANTHROPIC_BASE_URL/v1/messages 发送带有 anthropic-version: 2023-06-01 的 POST 请求来验证路由。

网关协议参考添加了操作员端的详细信息。对于 Anthropic Messages 格式，由 ANTHROPIC_BASE_URL 选择的网关必须为 /v1/messages 提供服务，并可选择为 /v1/messages/count_tokens 提供服务。它还指出，推理响应必须是流式的，因为 Claude Code 会在服务器发送事件到达时立即使用它们。

对于 Claude Code API 路由器来说，这意味着您应该验证 Anthropic Messages 路径，而不仅仅是与 OpenAI 兼容的聊天补全路径。如果缺少 /v1/messages、流式传输或必需的 Anthropic 标头，即使 OpenAI 路由对其他工具有效，Claude Code 也仍然会失败。

为此设置验证的 Flatkey 值

在 2026 年 6 月 29 日检查的 Flatkey 主页标题为 One API gateway for production AI teams，其元描述称 Flatkey 统一了模型访问、路由、计费、使用分析和操作控制。同一主页仍然显示使用 https://console.flatkey.ai/v1 和 /v1/chat/completions 的 OpenAI 风格示例，这些示例对与 OpenAI 兼容的工具有用，但不是 Claude Code 的基础 URL 模式。

当前的 Flatkey Claude Code 用例页面指出，Claude Code 配置了 https://router.flatkey.ai 和一个 Flatkey API 密钥。它还告诉用户在运行安装程序之前，在 https://console.flatkey.ai/keys 创建或复制密钥。除非您的 Flatkey 帐户为您提供了更新的值，否则请在下面的手动设置中使用该 Claude Code 特定的路由器根目录。

在 2026 年 6 月 29 日查看的 Flatkey 定价页面上，发布了来自 23 个提供商的 635 个人工智能模型的服务器端渲染定价。其端点映射包括 /v1/messages、/v1/chat/completions、/v1/responses、/v1/images/generations、/v1/video/generations 和 /v1beta/models/{model}:generateContent。本文将此视为端点覆盖范围的过时公开证据，而不是每个帐户都能调用每个模型的保证。

使用 Flatkey 的分步设置

1. 创建或选择一个 Flatkey 密钥。 使用由正确的人员、团队或环境拥有的密钥。请勿将其包含在屏幕截图、提示、代码仓库和问题评论中。
2. 从 shell 导出开始。 在单令牌预检成功之前，不要持久化设置。
3. 使用 Claude Code 路由器根目录。 对于当前的 Flatkey Claude Code 页面，该值为 https://router.flatkey.ai。
4. 选择凭证变量。 当密钥应作为 Authorization: Bearer 发送时，使用 ANTHROPIC_AUTH_TOKEN。仅当网关期望 x-api-key 时，才使用 ANTHROPIC_API_KEY。
5. 为第一次测试设置一个模型。 使用为您的 Flatkey 帐户启用的当前 Claude 模型 ID。如果该模型在 Claude Code 的选择器中不可见，请在预检成功后使用网关发现或添加自定义模型选项。
6. 运行 curl 预检。 单令牌请求将 Flatkey 路由与 Claude Code UI 状态分离开来。
7. 从同一个 shell 启动 Claude Code。 这使得命令行界面（CLI）能够继承您刚刚测试过的变量。
8. 运行 /status。 确认 Anthropic 基础 URL 行显示了 Flatkey 路由器，并且凭证行指明了您设置的变量名称。
9. 发送一个简短的提示。 然后检查 Flatkey 的使用情况和您启用的任何 Claude Code 遥测数据。

Shell 设置

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_AUTH_TOKEN="fk_replace_with_your_flatkey_key"
export ANTHROPIC_MODEL="claude-sonnet-4-6"

如果您的网关说明明确指出使用 x-api-key，请将 ANTHROPIC_AUTH_TOKEN 换成 ANTHROPIC_API_KEY 并更新预检标头。首次测试时不要同时设置两者；混合的凭证来源会使故障更难排查。

测试通过后的持久化设置

在 shell 测试成功后，您可以将相同的变量放置在 ~/.claude/settings.json 的 env 块中。不要将凭证放入已提交的项目的 .claude/settings.json 文件中。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://router.flatkey.ai",
    "ANTHROPIC_AUTH_TOKEN": "fk_replace_with_your_flatkey_key",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

在启动 Claude Code 之前预检 Messages 路由

最快的 Claude Code API 路由器 检查是发送一个单令牌的 Messages 请求。如果此请求失败，请在更改 Claude Code 设置之前，修复 Flatkey 密钥、基础 URL、网络路径或模型。

curl -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": "claude-sonnet-4-6",
    "max_tokens": 1,
    "messages": [
      {"role": "user", "content": "."}
    ]
  }'

一个以消息 ID 开头并包含 content 字段的 JSON 响应意味着路由和凭证工作正常。官方文档还指出，即使出现未知模型错误，也仍然证明了网关在拒绝模型名称之前已经对请求进行了身份验证。401 错误表示凭证被拒绝或在错误的标头中发送。

请仔细观察解析后的 URL。当 ANTHROPIC_BASE_URL=https://router.flatkey.ai 时，测试会访问 https://router.flatkey.ai/v1/messages。如果您的命令创建了 /v1/v1/messages，说明您将客户端 SDK 的基础 URL 复制到了 Claude Code 的网关字段中。

模型名称：别名、发现和自定义条目

模型名称是 Claude Code API 路由器 失败的第二个常见原因。基础 URL 将流量发送到 Flatkey，但 Claude Code 仍然需要在请求中发送一个模型值。

模型配置文档指出，Claude Code 支持内置的模型设置，例如 default、best、sonnet、opus、haiku，以及像 sonnet[1m] 和 opus[1m] 这样的长上下文变体。同一文档还指出，ANTHROPIC_MODEL 仅适用于您用它启动的会话，而 /model 可以保存交互式选择以供后续会话使用。

对于 Flatkey 路由，安全的规则是首先使用 Flatkey 已为您的密钥启用的完整 Claude 模型 ID，然后再决定是否在选择器中公开它。不要假设通用的系列名称、营销标签或提供商行标题会被接受为请求的模型 ID。

网关模型发现

当 ANTHROPIC_BASE_URL 指向 Anthropic Messages 网关且发现功能已启用时，Claude Code 可以在启动时查询网关的 /v1/models 端点。协议文档指出，请求为 GET /v1/models?limit=1000，超时时间为 3 秒，Claude Code 会从响应中读取 id 以及可选的 display_name。

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
claude --debug

发现功能默认关闭，这样共享密钥就不会向每个用户暴露所有可访问的模型。如果发现失败，Claude Code 会回退到缓存的或内置的选择器。如果您的 Flatkey 帐户通过发现功能未显示的别名提供模型，请改为添加自定义选项。

自定义模型选项

export ANTHROPIC_CUSTOM_MODEL_OPTION="claude-sonnet-4-6"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Sonnet via Flatkey"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Claude model routed through the Flatkey API router"

自定义模型选项会跳过对该模型 ID 的客户端验证，因此对于受控试点很有用。它不能替代预检请求。如果组织允许列表处于活动状态，也请将自定义模型 ID 包含在其中。

使用日志：在第一次提示后要检查什么

一个可靠的 Claude Code API 路由器 设置的最终标志是使用证据，而不仅仅是一次成功的响应。Flatkey 的公开定位是统一计费、使用分析和操作控制；Claude Code 网关文档也将使用跟踪和成本控制视为网关的优势。要有意地使用这两个层面。

对于 Claude Code 遥测，请仅在有意的隐私设置下启用 OpenTelemetry。监控文档指出，提示文本默认经过编辑处理，而诸如 OTEL_LOG_USER_PROMPTS=1、OTEL_LOG_TOOL_DETAILS=1 和 OTEL_LOG_RAW_API_BODIES 等设置会添加敏感细节。除非您的安全审查批准，否则请勿在默认的开发人员设置中包含原始正文日志记录。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

使用 OTEL_RESOURCE_ATTRIBUTES 来表示低基数的归属字段，例如部门、团队 ID 或成本中心。避免使用用户输入的项目名称或工单 ID 作为标签，除非您的可观察性后端能够处理其基数和隐私影响。

首先要调试的故障模式

团队生产清单

在团队中标准化 Claude Code API 路由器之前，请记录未来事件或财务审查将需要了解的操作事实。

内部迁移路径

如果 Flatkey 正在成为多个开发者工具的共享路由，请保持 Claude Code 设置与集成集群的其余部分保持一致。使用 OpenAI 兼容 API 迁移指南了解 SDK 基础 URL 模式，但请记住，Claude Code 使用的是 Anthropic Messages 路由，而不是 /v1/chat/completions。

对于桌面客户端设置，请比较 Cherry Studio API 设置指南。对于与 Claude Code 相邻的开发者机器路由模式，请参阅 cc-switch Claude Code 设置。在第一个提示成功后，请查看 Flatkey 模型定价，然后为任何需要单独凭据边界的额外环境获取密钥。

常见问题解答

我应该为带有 Flatkey 的 Claude Code API 路由器使用什么基础 URL？

使用您帐户显示的 Claude Code 专用的 Flatkey 路由器根地址。在 2026 年 6 月 29 日，Flatkey 的 Claude Code 用例页面指出，Claude Code 配置为 https://router.flatkey.ai。预检应精确到达一个 /v1/messages 路径。

我应该使用 ANTHROPIC_AUTH_TOKEN 还是 ANTHROPIC_API_KEY？

当网关期望在 Authorization 标头中使用持有者令牌时，请使用 ANTHROPIC_AUTH_TOKEN。当它期望 x-api-key 时，请使用 ANTHROPIC_API_KEY。如果您猜测后收到 401 错误，请切换变量并重新测试。

我可以为 Claude Code 使用与 OpenAI 兼容的 Flatkey 基础 URL 吗？

不能直接作为复制的字段使用。与 OpenAI 兼容的工具通常使用以 /v1 结尾的基础 URL，而 Claude Code 会将 /v1/messages 附加到 ANTHROPIC_BASE_URL。请使用 Flatkey Claude Code 路由器值并验证最终的 URL。

如何将 Flatkey 模型添加到 Claude Code 的模型选择器中？

当网关提供 /v1/models 服务时，启用 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1，或使用 ANTHROPIC_CUSTOM_MODEL_OPTION 添加一个手动选择器行。在这两种情况下，请确认您的 Flatkey 密钥已启用确切的模型 ID。

设置后我应该检查哪些使用日志？

检查 Flatkey 的使用情况，包括密钥、模型、端点系列、时间戳、令牌和成本（如果可用）。当组织遥测启用时，还可以使用 Claude Code /status 和 OpenTelemetry 指标，例如 claude_code.cost.usage 和 claude_code.token.usage。

结论

一个可靠的 Claude Code API 路由器设置有四个证明点：Flatkey Claude Code 基础 URL、正确的凭据标头、经过测试的模型名称，以及财务和平台团队可以审查的使用记录。从单令牌 /v1/messages 预检开始，确认 /status，然后在记录日志和回滚方案后才扩展路由。当您准备好通过共享网关路由 Claude Code 时，获取密钥并首先测试最小的提示。