Claude Code 接入¶

文档版本: 1.1.0 最后更新: 2026-09-14 适用版本: 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/** 同时接受 X-API-Key（API Key）与 Jairouter_Token（JWT）， 两者同存时 JWT 优先。JWT 需已启用（jairouter.security.jwt.enabled）且 token 未过期、未被拉黑。 Claude Code 场景下使用 ANTHROPIC_API_KEY（即 x-api-key）最简单；如需使用 JWT， 请确保上述前提满足。控制台面 /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。

工具调用（Tools）¶

前提：下游（OpenAI / DeepSeek / vLLM / 其他 OpenAI 兼容服务）必须支持 function calling。 下游不支持时不会报错——网关仍按协议把 tools 转发到下游，下游忽略后返回纯文本，本入口自动退化为纯文本对话 （content 只有 text 块、stop_reason 为 end_turn）。

请求侧映射（Anthropic → 下游 OpenAI 兼容 wire）：

顺序约定：

• assistant 同一条消息内：text 块进 content，多个 tool_use 按块序进 tool_calls （OpenAI 结构上 content 在前、tool_calls 在后，无法再细分交替顺序）；
• user 同一条消息内：tool_result 生成的 role:"tool" 消息先于文本消息发出， 保证它紧跟带 tool_calls 的 assistant 消息（OpenAI / DeepSeek 的硬性要求）。

非流式示例¶

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": 512,
    "messages": [{"role": "user", "content": "北京今天天气怎么样？"}],
    "tools": [{
      "name": "get_weather",
      "description": "查询指定城市天气",
      "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
    }],
    "tool_choice": {"type": "auto"}
  }'

响应（content 按下游顺序产出「文本块 + 各 tool_use 块」，stop_reason 为 tool_use）：

{
  "id": "chatcmpl-tool-1",
  "type": "message",
  "role": "assistant",
  "model": "deepseek-chat",
  "content": [
    {"type": "text", "text": "我来查询北京的天气。"},
    {"type": "tool_use", "id": "call_0", "name": "get_weather", "input": {"city": "北京"}}
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {"input_tokens": 88, "output_tokens": 24}
}

客户端执行完工具后，把结果以 tool_result 块回填到 user 消息即可继续（Claude Code 自动完成，无需手工构造）：

{"role": "user", "content": [{"type": "tool_result", "tool_use_id": "call_0", "content": "晴，25℃"}]}

流式事件序列¶

工具调用以 tool_use 内容块下发，入参通过 input_json_delta 分片累积：文本块恒为 index: 0， 工具块下标按出现顺序递增（1、2…），每个块的 start / delta / stop 三件套不交叉。

实际输出样例（真实序列化器产出，10 个事件；下游先回文本「我来查询北京的天气。」，再流式给出 get_weather 的入参 {"city":"北京"}，arguments 分两片到达）：

event:message_start
data:{"type":"message_start","message":{"id":"msg_ec73908348944d82b34dfd2ef5516f71","type":"message","role":"assistant","model":"deepseek-chat","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":88,"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":"我来查询北京的天气。"}}

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

event:content_block_start
data:{"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"call_0","name":"get_weather"}}

event:content_block_delta
data:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"city\":"}}

event:content_block_delta
data:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\"北京\"}"}}

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

event:message_delta
data:{"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":24}}

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

stop_reason 规则：下游 finish_reason 为 tool_calls → tool_use；本次流产出过工具块但下游结束原因为 stop / 缺失 → 也上修为 tool_use（Claude Code 依此决定是否执行工具）；下游为 length 时保留 max_tokens（截断语义优先）。usage.output_tokens 口径不变——下游给出 usage 时优先，否则按 「累计文本 + 工具 arguments 分片」估算。

容错与降级¶

Claude Code 实测（工具能力）¶

# 1) 指向网关（模型为 JAiRouter 已注册的实例/池名，下游需支持 function calling，如 deepseek-chat）
export ANTHROPIC_BASE_URL=http://localhost:8080
export ANTHROPIC_API_KEY=<JAiRouter API Key>
export ANTHROPIC_MODEL=deepseek-chat

# 2) 非交互式触发一次工具调用（Claude Code 会自动带上 Read/Bash 等工具定义）
claude -p "用 Bash 工具执行 pwd 并原样告诉我输出" --allowedTools "Bash"

# 3) 观察是否真的落地：应答里应包含工具执行结果（如 /home/... 之类的路径），而不是「我无法执行命令」

判断是否走通的两个抓手：

• 网关日志：/v1/messages 请求体带 tools，下游请求体带 tools / tool_calls（开启链路追踪时， 下游调用的 span 属性为 adapter.api_standard=openai）；
• 事件流（curl -N 或 Claude Code 的 --verbose）：出现 content_block_start 的 "type":"tool_use" 与 message_delta 的 "stop_reason":"tool_use"。

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/** 接口说明
• 错误码对照表 — 网关错误码