Gateway 协议上线清单
LLM Gateway 与 Claude apps gateway 的协议、headers/body 透传、模型发现、SSO、Postgres、spend limits、错误语义和缓存上线检查。
Claude Code 接入网关时,最容易出问题的不是 Base URL,而是 gateway 对 headers、body、streaming、model discovery、cache usage 和错误响应的处理。这个页面把官方 Gateway protocol、LLM gateway rollout 和 Claude apps gateway 配置压成上线检查表。
Gateway 不要把当前观察到的字段写成固定 allowlist。Claude Code 的 beta header、body fields、工具 schema 和 context management 字段会随版本增加,剥掉新字段会让新能力静默降级或直接 400。
#三种网关形态
| 形态 | 客户端配置 | 你要实现什么 |
|---|---|---|
| Anthropic Messages gateway | ANTHROPIC_BASE_URL | /v1/messages SSE,可选 /v1/messages/count_tokens 和 /v1/models |
| Bedrock-format gateway | CLAUDE_CODE_USE_BEDROCK=1 + ANTHROPIC_BEDROCK_BASE_URL | Bedrock InvokeModel 与 stream invoke 路径,转换 provider dialect |
| Vertex/Agent Platform gateway | CLAUDE_CODE_USE_VERTEX=1 + ANTHROPIC_VERTEX_BASE_URL | rawPredict/streamRawPredict/count-tokens 路径 |
Passion8 和大多数 Claude Code 兼容网关走第一种,即 Anthropic Messages 格式。不要把它和 OpenAI /v1/chat/completions 混在一起。
#最小协议要求
| 项目 | 要求 | 失败表现 |
|---|---|---|
| Streaming | /v1/messages 必须 SSE 流式转发 | 客户端卡住,看起来像模型无响应 |
anthropic-version | 原样转发 | 版本或 schema 不匹配 |
anthropic-beta | 原样转发,不要按固定列表过滤 | tool search、context management、web search、extended context 等能力失效 |
system array | 保持顺序和 block 结构 | attribution strip、system prompt、cache key 被破坏 |
tools | 原样保留 schema 和 deferred/tool search 字段 | MCP/内置工具异常,缓存持续 miss |
thinking / output_config | 支持或明确桥接到上游 | effort、adaptive reasoning、structured output 异常 |
| 错误 envelope | 保留 status、type、message、request id | Claude Code 无法做正确 retry 或降级 |
| Usage | 保留 input/output/cache token 字段 | /usage 和缓存排查失真 |
#Credential 与 Base URL
Claude Code 到网关通常用:
export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-gateway-token"如果网关要求 x-api-key,可用:
export ANTHROPIC_API_KEY="sk-gateway-key"Credential 决策:
| 情况 | 推荐 |
|---|---|
| 固定个人 token | 用户级 ~/.claude/settings.json 的 env |
| 会轮换的 token | apiKeyHelper 或公司 credential helper |
| 多租户路由 | ANTHROPIC_CUSTOM_HEADERS 加租户/团队信息,同时在网关侧校验 |
| 仓库内配置 | 只放非敏感 defaults,不要提交 token |
#Attribution block 与缓存
Claude Code 会给 system prompt 加 attribution block。直连 Anthropic API 时,官方 endpoint 在位置正确时会剥掉它,避免污染 first-party prompt cache。第三方网关要么原样转发 system array,要么清楚承担缓存后果。
| 网关行为 | 缓存后果 |
|---|---|
| 原样转发 system array,保持 attribution block 第一项 | 最接近官方路径 |
| 在 system array 前插入公司策略 | 可能让 attribution block 进入模型 prompt 和 cache key |
| 把 system array 拼成字符串 | 破坏官方 strip 逻辑,也更容易 cache miss |
| 重写工具 schema 或排序 | 工具定义变动会让前缀不稳定 |
如果网关必须注入企业策略,优先用 Claude Code managed settings、CLAUDE.md、权限规则或 provider 侧 policy,不要在每个请求里动态改 system 前缀。
#Model discovery
/v1/models 是可选能力。实现后可让模型进入 /model picker:
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1上线检查:
| 检查 | 要点 |
|---|---|
| 路径 | GET /v1/models?limit=1000 能快速返回 |
| 模型 ID | 返回的是 Claude Code 可直接使用的 ID |
| 能力 | 出现在 picker 不代表支持 effort、fast mode、tool search 或 1M context |
| 缓存 | 客户端会缓存发现结果,排错时清理本机 gateway model cache |
| 错误 | 慢、重定向、HTML 登录页通常会被静默忽略 |
#Claude apps gateway 配置域
Claude apps gateway 是官方 claude gateway --config gateway.yaml 形态,面向组织 SSO、托管策略和多 cloud upstream。
| 配置域 | 作用 | 上线风险 |
|---|---|---|
server | listen、public URL、TLS | public URL 必须能被用户设备和浏览器回调访问 |
auth.oidc | IdP、client、claims、groups | 回调 URL、offline access、group claim 错会导致登录循环 |
session | gateway bearer token 签名和 TTL | TTL 太短且 IdP 无 refresh token 会频繁重新登录 |
store | Postgres 持久化 device grants、limits | 多副本必须共享数据库,迁移权限要提前规划 |
upstreams | Anthropic、Bedrock、Agent Platform、Foundry 等 | model ID 不匹配会 404 或错误 failover |
managed | 下发 settings、model policies、权限 | 第三方网关路径不要假设 server-managed settings 会自动覆盖 |
telemetry | OTLP metrics/traces/logs | 默认不要记录完整 prompt 或工具输入输出 |
admin | spend limits 和 Admin API | admin key 要分环境、分用途轮换 |
#Spend limits
Claude apps gateway 的 spend limits 是 gateway 侧 circuit breaker,不是权威账单。它按 streamed usage 和价格表估算每个开发者在 daily、weekly、monthly period 的消耗。
| 设计点 | 含义 |
|---|---|
| Scope | user、rbac_group、organization |
| Amount | 美分字符串,null 表示不限额,"0" 表示阻断 |
| Period | daily、weekly、monthly |
| Effective cap | user override 优先,再 group,再 organization |
| 超限响应 | 429、billing_error、x-should-retry: false |
count_tokens | 通常不计费,不受 cap 阻断 |
| Provider bill | 仍以云 provider 或 Anthropic 账单为准 |
如果 Postgres 不可用,官方 gateway 可配置 fail open 或 fail closed。生产环境要根据“可用性优先”还是“预算硬约束优先”选择。
#错误语义
| 错误 | 应返回/保留什么 | Claude Code 行为 |
|---|---|---|
| 401/403 | 认证失败的 clear message | 引导用户检查 credential、登录或上游权限 |
| 404 model | 模型不可用或 upstream 不服务该模型 | 可 failover 到后续 upstream,或提示换模型 |
| 429 | rate limit 或 spend limit,带 retry 语义 | 自动等待或停止重试 |
| 5xx/timeout | upstream 临时失败 | 可切 upstream 或重试 |
| 400 field unsupported | 明确指出字段,如 thinking、context_management | 用户可临时禁用 beta 或切 provider |
| HTML 登录页 | 不要返回给 Claude Code API path | 会被客户端识别成 malformed response |
#Rollout 顺序
- 单用户 shell exports 验证 Base URL 和 token。
- 固定模型和 effort,无 MCP 连续追问,确认 cache read/write。
- 加
/v1/models,确认 picker 和 fallback。 - 加 MCP、tool search、plugins,观察工具 schema 是否稳定。
- 下发用户级或 endpoint-managed settings。
- 加 OpenTelemetry,按 session、agent、model、team 维度看 cost 和 errors。
- 设置 spend limits 或外部预算告警。
- 做 provider failover 演练,确认 401/403/404/429/5xx 语义。
- 最后再推广到 Desktop、IDE、CI 和 SDK。
#缓存验收
| 验收项 | 通过标准 |
|---|---|
| 固定模型/effort 连续追问 | 第二轮开始出现 cache_read_input_tokens |
| 5 分钟停顿后追问 | API/provider 路径仍能读取短 TTL 内缓存 |
| 1 小时计划内账号 | Claude subscription 路径长间隔仍可复用 |
| MCP 工具较多 | tool search/deferred tools 不让每轮都重发完整 schema |
| 子代理 | 每个 agent 独立缓存,主 session 不被错误归因 |
| 网关 usage | cache_creation_input_tokens 和 cache_read_input_tokens 被原样透传 |
#官方参考
Support / 支持
Need help? / 需要帮助？
接入、计费与模型异常可邮件联系；服务可用性以状态页为准。
For setup, billing, or model issues, email us. Check the status page for uptime.
也可使用右下角微信 / QQ 客服 · WeChat / QQ support is available at the bottom right
