Claude Code 接入¶

文档版本: 1.0.0 最后更新: 2026-09-13 适用版本: v3.1+ Git 提交: - 作者: Lincoln

概述¶

JAiRouter 从 v3.1 起提供 Anthropic Messages 协议入口（POST /v1/messages），Claude Code 只需把 ANTHROPIC_BASE_URL 指向 JAiRouter 即可零改造直连：请求经网关的 API Key 鉴权 → 配额 → 限流/熔断 → 负载均衡落到任意下游实例（OpenAI / DeepSeek / vLLM / Ollama / Claude …），响应再翻译回 Anthropic 形状。

一句话理解：/api/v1/**（控制台面）返回 RouterResponse 包裹体；/v1/**（原生面）返回下游原生/协议原生形状，供 Claude Code、OpenAI SDK 等客户端直接使用。

前置条件¶

1. JAiRouter 已启动（默认 http://localhost:8080）。
2. 已在控制台创建 API Key（/api/** 与 /v1/** 都用它做网关鉴权）。
3. 目标模型已注册为实例或池（chat 服务类型），例如 deepseek-chat、qwen2:7b。
4. 下游 AI 服务的凭据已配置好（推荐放在实例 headers 里，见下文「认证分层」）。

快速开始¶

# 1) 网关地址：ANTHROPIC_BASE_URL=http://<host>:8080（不要带 /v1 后缀；<host> 换成网关所在主机/IP）
export ANTHROPIC_BASE_URL=http://localhost:8080

# 2) 网关凭据（JAiRouter 控制台创建的 API Key）
export ANTHROPIC_API_KEY=<JAiRouter API Key>

# 3) 使用已在 JAiRouter 注册的模型名（必须与实例/池名称一致，无别名）
export ANTHROPIC_MODEL=deepseek-chat

# 4) 启动 Claude Code
claude

PowerShell：

$env:ANTHROPIC_BASE_URL = "http://localhost:8080"
$env:ANTHROPIC_API_KEY  = "<JAiRouter API Key>"
$env:ANTHROPIC_MODEL    = "deepseek-chat"
claude

Claude Code 会把 ANTHROPIC_API_KEY 放进 x-api-key 请求头。HTTP 头名本身大小写不敏感， 所以 x-api-key 与 X-API-Key 等价（网关侧均已实测可用）。

重要：x-api-key 在 JAiRouter 里是网关凭据，由安全层消费后不会转发给下游。 下游 AI 服务的密钥必须另行配置，见下一节。

认证分层（务必先读）¶

一次 /v1/messages 请求会经过两层认证，两个密钥的用途完全不同：

三条必须记住的规则：

1. x-api-key = 网关凭据，不会透传下游。 把下游密钥放在 x-api-key 上，下游会收到没有任何凭据的请求 → 401 / 无凭据失败。
2. 下游密钥配在实例 headers（推荐），或由客户端用 Authorization: Bearer <下游密钥> 按请求携带。 两者同时存在时实例级 headers 优先（实例配置覆盖请求传入的 Authorization）。
3. 认证优先级：Jairouter_Token（JWT） > X-API-Key（API Key）。Authorization 与网关认证无关，它只影响下游。

原生面限制（当前版本）：/v1/** 的服务调用链只放行 API Key 认证（ApiKeyAuthentication）。 只带 Jairouter_Token、不带 x-api-key 的原生面请求会拿到空响应（无内容），无法调用下游。 请在 Claude Code 场景下始终使用 ANTHROPIC_API_KEY（即 x-api-key）。控制台面 /api/** 不受此限制。

三种下游凭据配置方案¶

方案 A：下游密钥配在实例 headers（推荐）¶

# 以 DeepSeek 为例：下游密钥配置在实例 headers 上（网关注入，客户端不持有）
curl -X POST "http://localhost:8080/api/config/instance/add/chat" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <JAiRouter API Key>" \
  -d '{
    "name": "deepseek-chat",
    "baseUrl": "https://api.deepseek.com",
    "path": "/v1/chat/completions",
    "adapter": "normal",
    "headers": {
      "Authorization": "Bearer <DeepSeek API Key>"
    }
  }'

之后 Claude Code 只需 ANTHROPIC_API_KEY=<JAiRouter API Key> 即可，客户端不保存也不发送下游密钥。

方案 B：按请求携带下游密钥（透传 Authorization）¶

不改实例配置，客户端自己带下游密钥：

curl -N -X POST "http://localhost:8080/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <JAiRouter API Key>" \
  -H "Authorization: Bearer <DeepSeek API Key>" \
  -d '{"model":"deepseek-chat","max_tokens":64,"messages":[{"role":"user","content":"hi"}]}'

实例若已配置 Authorization，则以实例配置为准（请求头被覆盖）。

方案 C：自定义下游请求头¶

curl -X POST "http://localhost:8080/api/config/instance/add/chat" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <JAiRouter API Key>" \
  -d '{
    "name": "claude-sonnet",
    "baseUrl": "https://api.anthropic.com",
    "path": "/v1/messages",
    "adapter": "claude",
    "headers": {
      "x-api-key": "<Anthropic API Key>"
    }
  }'

注意：这里的 x-api-key 位于实例 headers，是给下游 Anthropic 用的；它与客户端发给网关的 x-api-key 是两回事，互不干扰。选择 claude 适配器时 anthropic-version 头会自动注入。

接口示例¶

以下示例统一使用 x-api-key: <JAiRouter API Key> 作为网关凭据。

非流式对话¶

curl -X POST "http://localhost:8080/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <JAiRouter API Key>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "deepseek-chat",
    "max_tokens": 128,
    "system": "你是一个简洁的助手",
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}]
  }'

响应（Anthropic Message 形状）：

{
  "id": "chatcmpl-xxxxxxxx",
  "type": "message",
  "role": "assistant",
  "model": "deepseek-chat",
  "content": [{"type": "text", "text": "我是一个 AI 助手……"}],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {"input_tokens": 10, "output_tokens": 15}
}

usage.input_tokens / output_tokens 来自下游 usage；下游未提供时为 0。

流式对话¶

curl -N -X POST "http://localhost:8080/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <JAiRouter API Key>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "deepseek-chat",
    "max_tokens": 128,
    "stream": true,
    "messages": [{"role": "user", "content": "数到三"}]
  }'

Content-Type: text/event-stream;charset=UTF-8，事件序列如下（每事件 = event:<name> 行 + data:<json> 行 + 空行；SSE 规范允许冒号后跟一个空格，网关实际输出不带空格，客户端两种都能解析）：

实际输出样例（真实序列化器产出，7 个事件；模型回包 "1" + "、2、3"）：

event:message_start
data:{"type":"message_start","message":{"id":"msg_4976714626ba4577a486e0772f604a87","type":"message","role":"assistant","model":"deepseek-chat","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":6,"output_tokens":0}}}

event:content_block_start
data:{"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event:content_block_delta
data:{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"1"}}

event:content_block_delta
data:{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"、2、3"}}

event:content_block_stop
data:{"type":"content_block_stop","index":0}

event:message_delta
data:{"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":2}}

event:message_stop
data:{"type":"message_stop"}

流中途失败（HTTP 200 已建立、SSE 已开始）时，网关以 event:error 收尾，避免客户端只看到「流被截断」：

event:error
data:{"type":"error","error":{"type":"api_error","message":"…"}}

其中 error.type 依下游状态映射：401/403 → authentication_error、429 → rate_limit_error、 400/404/422 → invalid_request_error，其余为 api_error。

Token 计数¶

curl -X POST "http://localhost:8080/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <JAiRouter API Key>" \
  -d '{
    "model": "deepseek-chat",
    "system": "你是一个简洁的助手",
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}]
  }'

{"input_tokens": 10}

• 入参与 /v1/messages 相同，但忽略 max_tokens / stream / tools：只统计 system 与 messages 中的文本块体量。
• 由网关本地估算（表意文字约 2 字符/token、其余非空白约 4 字符/token），不触达下游、不消耗配额， 与流式 message_start.usage.input_tokens 同源。
• 估算值用于预算/裁剪，不等于 Anthropic 官方分词结果。

模型目录¶

curl -H "x-api-key: <JAiRouter API Key>" "http://localhost:8080/v1/models"

返回 OpenAI 形状 {"object":"list","data":[{"id":"deepseek-chat","object":"model",…}]}， id 即可用于 model 字段。

当前限制¶

故障排查¶

相关文档¶

• 快速开始 — 启动网关、配置第一个实例
• API Key 管理 — 创建与轮换网关凭据
• 常用服务配置示例 — 各下游（含 Claude 适配器）配置模板
• 统一 API — 控制台面 /api/v1/** 接口说明
• 错误码对照表 — 网关错误码