# Claude Code Gateway 协议上线清单

> LLM Gateway 与 Claude apps gateway 的协议、headers/body 透传、模型发现、SSO、Postgres、spend limits、错误语义和缓存上线检查。

URL: https://docs.passion8.cc/docs/claude-code/gateway-protocol
Language: zh-CN
Publisher: Passion8

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 到网关通常用:

```bash
export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-gateway-token"
```

如果网关要求 `x-api-key`,可用:

```bash
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:

```bash
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 顺序

1. 单用户 shell exports 验证 Base URL 和 token。
2. 固定模型和 effort,无 MCP 连续追问,确认 cache read/write。
3. 加 `/v1/models`,确认 picker 和 fallback。
4. 加 MCP、tool search、plugins,观察工具 schema 是否稳定。
5. 下发用户级或 endpoint-managed settings。
6. 加 OpenTelemetry,按 session、agent、model、team 维度看 cost 和 errors。
7. 设置 spend limits 或外部预算告警。
8. 做 provider failover 演练,确认 401/403/404/429/5xx 语义。
9. 最后再推广到 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` 被原样透传 |

## 官方参考

- [Gateway protocol reference](https://code.claude.com/docs/en/llm-gateway-protocol.md)
- [Connect Claude Code to an LLM gateway](https://code.claude.com/docs/en/llm-gateway-connect.md)
- [Roll out an LLM gateway](https://code.claude.com/docs/en/llm-gateway-rollout.md)
- [Claude apps gateway configuration](https://code.claude.com/docs/en/claude-apps-gateway-config.md)
- [Claude apps gateway spend limits](https://code.claude.com/docs/en/claude-apps-gateway-spend-limits.md)