| name | claude-code-llm-gateway |
| description | Use when implementing a server-side Anthropic-compatible LLM gateway for Claude Code, including /v1/messages, SSE streaming, count_tokens, files, models, tool_use/tool_result, beta headers, and gateway error compatibility. |
Claude Code 大模型请求网关
目标
根据本 skill，实现一个 Claude Code 可通过 ANTHROPIC_BASE_URL 接入的大模型请求网关。你的任务是写服务端接口，不是复刻 Claude Code 源码里的 SDK 调用函数。
优先实现 Anthropic Messages API 兼容面。不要把 Claude.ai OAuth、bootstrap、Remote/CCR session、session ingress、team memory sync 当成这个网关的必需接口。
接口优先级
| 优先级 | 接口 | 用途 | 最小要求 |
|---|
| P0 | POST /v1/messages | 主模型完成请求 | 支持 stream:true/false、messages、system、tools、thinking、betas |
| P0 | SSE event stream | 流式输出 | 输出 Anthropic raw SSE 事件序列 |
| P0 | tool round-trip | 工具调用回合 | 返回 tool_use，接收下一轮 tool_result |
| P1 | POST /v1/messages/count_tokens | 上下文估算 | 返回 { "input_tokens": number } |
| P1 | POST /v1/files | 文件上传 | multipart，返回 file metadata |
| P1 | GET /v1/files | 文件列表 | 支持 after_created_at、after_id 分页 |
| P1 | GET /v1/files/{file_id}/content | 文件下载 | 返回二进制内容 |
| P2 | GET /v1/models | 模型能力/校验 | 返回 Anthropic models list 兼容结构 |
完整字段合同见 references/gateway-interface-contract.md。实现单个子协议时再读取对应专题 skill：
claude-code-api-request：/v1/messages、count_tokens、files、models 的 HTTP 合同。claude-code-api-streaming：SSE 事件与非流式 fallback。claude-code-api-tools：tools、tool_use、tool_result、工具参数分片。claude-code-api-conversation：messages、content blocks、配对校验。claude-code-api-compaction：context_management、cache_edits 兼容处理。
实现顺序
- 实现认证与公共头解析：接受
Authorization: Bearer ...、x-api-key、anthropic-version、anthropic-beta、x-app、User-Agent、X-Claude-Code-Session-Id、x-client-request-id。未知 x-* 头应透传或忽略，不要报错。
- 实现
POST /v1/messages 非流式：校验基础 body，路由到你的上游模型，返回完整 assistant message。
- 实现
POST /v1/messages 流式：返回 text/event-stream，按 Anthropic raw event 顺序输出。
- 实现工具回合：当模型需要工具时返回
stop_reason:"tool_use" 和 tool_use block；客户端下一轮会把结果以 tool_result block 放在 user message 里。
- 实现
count_tokens：优先真实统计；做不到时返回稳定估算，但字段必须是 input_tokens。
- 实现 Files API：用于 Claude Code 持久化或引用大文件；没有文件能力时返回明确 404/403，不要让
/v1/messages 失败。
- 实现
GET /v1/models：没有动态模型能力时返回静态列表。
兼容规则
stream:true 是主路径。即使网关内部调用非流式模型，也要能合成 SSE 事件。stream:false 是 fallback 和后台任务路径，必须能返回完整 JSON。- 请求体中的未知扩展字段默认忽略或透传：
anthropic_beta、anti_distillation、anthropic_internal、context_management、output_config、speed。
thinking.budget_tokens 必须严格小于 max_tokens；无法支持 thinking 时可以忽略字段，但不要因为字段存在直接 400。- 支持 prompt cache 字段的透传：
cache_control、cache_reference、cache_edits。不支持真实缓存时按普通内容处理。
- 返回错误时使用 Anthropic 风格 JSON，并设置可重试语义：429/529/5xx 可重试，401/403 通常不可重试，408/409 可重试。
验收用例
实现完成后至少用这些请求验证：
POST /v1/messages + stream:true，只返回 text。POST /v1/messages + stream:false，返回完整 assistant message。POST /v1/messages 带 tools，返回 tool_use；下一轮带 tool_result，返回最终 text。POST /v1/messages/count_tokens，返回 input_tokens。POST /v1/files 上传后，通过 GET /v1/files 和 GET /v1/files/{id}/content 取回。GET /v1/models 返回至少一个 Claude Code 可选模型。
