# Claude Code 网关与协议

> Claude Code 通过 Passion8 或其他 LLM gateway 运行时的 Base URL、鉴权、headers/body 透传、模型发现、prompt cache、tool search 和常见 400/401 问题。

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

Claude Code 可以通过 `ANTHROPIC_BASE_URL` 接入 LLM gateway。Passion8 就属于这类 Claude Code 入口:本地 CLI 仍按 Anthropic Messages 格式发请求,网关负责转发、鉴权、模型路由、计费和观测。




Claude Code 使用 `https://passion8.cc`,不带 `/v1`。OpenAI 兼容客户端和 Codex 才使用 `https://passion8.cc/v1`。




如果你只是配置客户端,看本页和 Provider 认证与云平台接入。如果你要实现或验收网关,看 [Gateway 协议上线清单](https://docs.passion8.cc/docs/claude-code/gateway-protocol)。

## 最小接入

```bash
export ANTHROPIC_BASE_URL="https://passion8.cc"
export ANTHROPIC_AUTH_TOKEN="sk-你的 Passion8 API Key"
claude -p "只回答 ok"
```

Windows PowerShell:

```powershell
$env:ANTHROPIC_BASE_URL = "https://passion8.cc"
$env:ANTHROPIC_AUTH_TOKEN = "sk-你的 Passion8 API Key"
claude -p "只回答 ok"
```

推荐把 Key 放在用户级 settings 或本机环境变量,不要提交到项目仓库:

```json title="~/.claude/settings.json"
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://passion8.cc",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的 Passion8 API Key"
  }
}
```

## 请求格式

Claude Code 对 `ANTHROPIC_BASE_URL` 使用 Anthropic Messages 格式:

| 项目 | 说明 |
| --- | --- |
| 主要端点 | `/v1/messages` |
| 可选端点 | `/v1/messages/count_tokens` |
| 认证 | `Authorization: Bearer ...` 或 `x-api-key` |
| 流式 | 必须支持 SSE 流式转发 |
| 模型列表 | 可选 `/v1/models?limit=1000` |

如果网关把 Anthropic Messages 请求转到 Bedrock、Vertex 或其他 schema,转换是网关责任。客户端不要把 Claude Code 的 Base URL 写成 OpenAI `/v1`。

## 必须透传的内容

官方协议强调 gateway 不应该用固定白名单剥字段。Claude Code 的能力会随版本增加,字段和 beta header 会变。

| 内容 | 为什么重要 |
| --- | --- |
| `anthropic-version` | 上游 API 版本 |
| `anthropic-beta` | tool search、context management、extended context、beta tool fields 等能力 |
| `system` array 顺序 | attribution block、system prompt 和缓存 key 依赖它 |
| `tools` / tool schema | MCP、内置工具、deferred tool loading |
| `thinking` | adaptive reasoning |
| `output_config` | effort、structured output、task budget |
| `context_management` | 自动上下文管理能力 |
| 错误 body | Claude Code 会根据上游错误文字做自动 retry 或能力降级 |




如果网关要做安全审计,应读取但不要重写 request body。剥 header、改 system array、把 system 合并成字符串,都会影响能力或 prompt cache。




## Attribution block 与缓存

Claude Code 会在 system prompt 前放一个 attribution block。直接发到 Anthropic API 时,官方 endpoint 会在位置正确时剥掉它,避免影响 first-party prompt cache。

自定义网关要注意:

| 做法 | 结果 |
| --- | --- |
| 原样转发 `system` array,保持 attribution block 第一项 | 最稳 |
| 在前面插入自己的 system block | 可能导致 attribution block 进入模型 prompt 和 cache key |
| 把 system array 合并成字符串 | 可能破坏 strip 和缓存 |
| 网关必须改写 system | 客户端可考虑 `CLAUDE_CODE_ATTRIBUTION_HEADER=0` |

官方说明从 Claude Code v2.1.181 起,自定义 Base URL 下 attribution block 在一个 conversation 生命周期内更稳定,对 gateway-side full body cache 更友好。旧版本如果网关自己按请求体做缓存,可能需要禁用 attribution header。

## Prompt Cache 与 Passion8

Passion8 下排查缓存,看三层:

| 层 | 检查 |
| --- | --- |
| Claude Code 客户端 | 是否频繁 `/model`、`/effort`、`/fast`、`/compact`、升级 CLI |
| 网关 | 是否透传 cache-control、beta headers、tools、usage 字段 |
| 上游模型 | 是否支持 prompt caching、tool search、1h TTL、context window |

usage 字段:

| 字段 | 含义 |
| --- | --- |
| `cache_creation_input_tokens` | 本轮写入缓存的输入 token |
| `cache_read_input_tokens` | 本轮从缓存读取的输入 token |

读写比越高,缓存越健康。如果每轮 creation 都高,优先检查模型、effort、fast mode、MCP 工具定义、插件 MCP、整工具 deny 和 `/compact`。

## 模型发现

如果网关实现 `/v1/models`,Claude Code 可以把网关返回模型加入 `/model` picker。

启用:

```bash
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
```

注意:

| 条件 | 说明 |
| --- | --- |
| 只适用于 `ANTHROPIC_BASE_URL` | Bedrock/Vertex/Foundry provider 变量优先时不会走这里 |
| 请求超时很短 | `/v1/models` 慢或重定向会静默失败 |
| 结果会缓存 | 本机缓存文件在 `~/.claude/cache/gateway-models.json` |
| 自定义模型能力 | 模型出现在 picker 不代表 effort、tool search、1M context 都可用 |

## 常见错误

| 现象 | 可能原因 | 修复 |
| --- | --- | --- |
| `401` | Key 错、header 不匹配、旧登录冲突 | 确认 `ANTHROPIC_AUTH_TOKEN`,必要时 `/logout` |
| `ConnectionRefused` | Base URL 错、VPN/防火墙拦截 | 用 curl 直接测网关 |
| HTTP 200 但响应 malformed | 网关返回 HTML 登录页或代理错误页 | 修正路由,确保 `/v1/messages` 返回 API JSON/SSE |
| `400 context_management` | 网关转发到不支持该字段的上游 | 透传到支持上游,或临时 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |
| `400 thinking` / `adaptive` | 上游模型不支持 adaptive reasoning | 升级上游或按官方变量禁用对应能力 |
| 模型列表缺失 | `/v1/models` 未实现或发现未开启 | 开启 discovery 或手动写模型 |
| Remote Control 不可用 | 自定义 gateway credential 或非 Anthropic base URL | 见 [网页与远程控制](https://docs.passion8.cc/docs/claude-code/remote-web) |
| 官方账号能力不出现 | 当前 provider 不是 claude.ai subscription 或 Anthropic API | 见 [功能可用性](https://docs.passion8.cc/docs/claude-code/feature-availability) |
| `/context` 估算不准 | `count_tokens` 端点缺失 | 实现 token counting 或接受本地估算 |

## 企业配置

企业/团队可以用:

| 能力 | 用途 |
| --- | --- |
| Managed settings | 下发 Base URL、模型 allowlist、permissions、hooks |
| Server-managed settings | 让 web/cloud/desktop cloud sessions 也接收组织策略 |
| `apiKeyHelper` | 动态取网关 token,避免静态 Key |
| `ANTHROPIC_CUSTOM_HEADERS` | 加租户、路由、审计 header |
| OpenTelemetry | 观测 Claude Code usage、tool、hook 和 cost |
| 网关 spend limits | 网关侧限制个人日/周/月用量 |

`apiKeyHelper` 输出通常会缓存一段时间。官方示例可以用 `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 调整缓存时长。

如果要自托管 Claude apps gateway 或运维通用 Anthropic-compatible gateway,继续看 [Gateway 运维](https://docs.passion8.cc/docs/claude-code/gateway-operations) 和 [Claude apps gateway 部署](https://docs.passion8.cc/docs/claude-code/gateway-cloud-deployment)。那里单独展开 OIDC、Postgres、spend limits、模型发现、协议透传和 1 小时缓存 TTL 的网关边界。

## Passion8 建议清单

1. Base URL 写 `https://passion8.cc`,不要 `/v1`。
2. 用 `ANTHROPIC_AUTH_TOKEN`,不要混用多个认证变量。
3. 长任务开局先定 `/model`、`/effort`、是否 `/fast`。
4. 如果 MCP 多,优先确认 tool search 和 deferred tools。
5. 如果 cache read 一直为 0,先用无 MCP、固定模型、固定 effort 的长会话复测。
6. 如果模型不在 picker,先确认后台实际模型 ID,再考虑 gateway model discovery。
7. 如果 Remote Control 或 voice dictation 不可用,先暂时移除 gateway 变量确认边界。

## 官方参考

- [Run Claude Code through a gateway](https://code.claude.com/docs/en/gateways.md)
- [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)
- [Other LLM gateways](https://code.claude.com/docs/en/llm-gateway.md)
- [Prompt caching](https://code.claude.com/docs/en/prompt-caching.md)
- [Environment variables](https://code.claude.com/docs/en/env-vars.md)
- [Feature availability](https://code.claude.com/docs/en/feature-availability.md)

## 相关页面



- [Claude apps gateway 部署](https://docs.passion8.cc/docs/claude-code/gateway-cloud-deployment): 私网入口、OIDC、Kubernetes、Cloud Run、GCP、Postgres 和升级。
- [Gateway 运维](https://docs.passion8.cc/docs/claude-code/gateway-operations): 官方 apps gateway、通用协议、spend limits、模型发现和缓存透传。
- [企业部署总览](https://docs.passion8.cc/docs/claude-code/enterprise-deployment-overview): provider、认证、managed settings、权限和数据边界。