# Claude Code Gateway 运维

> Claude apps gateway、通用 LLM gateway 协议，以及 Passion8/自定义网关在认证、路由、缓存、模型发现和 spend limits 上的运维注意。

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

Gateway 运维分两类场景:官方 Claude apps gateway 和通用 LLM gateway。前者面向 Claude apps 的组织级入口,由管理员运行和管理;后者面向 Claude Code 的 `ANTHROPIC_BASE_URL`,由 Passion8 或自定义网关转发 Anthropic Messages 请求。




官方 Claude apps gateway 的登录入口必须能被用户设备在私网内访问。如果登录页、OIDC 回调或 gateway public URL 只在服务器本机可达,Claude apps 会卡在登录或策略拉取阶段。




协议字段、错误语义、模型发现和缓存验收清单见 [Gateway 协议上线清单](https://docs.passion8.cc/docs/claude-code/gateway-protocol)。用户侧 provider 选择和认证变量见 Provider 认证与云平台接入。

## 官方 Claude apps gateway

管理员用 `claude` binary 自托管 gateway:

```bash
claude gateway --config gateway.yaml
```

这个 gateway 运行在 `claude` binary 中,不需要额外部署一个独立应用框架。运维重点是把身份、策略、数据库、观测和上游模型路由配置清楚,并把登录入口放在 VPN、内网 DNS 或受控反向代理后面。

| 能力 | 运维注意 |
| --- | --- |
| OIDC | 配置 issuer、client、回调 URL、允许的 group/claim。确认用户设备能访问登录页和回调域名。 |
| Postgres | 用持久化数据库保存 gateway 状态。纳入备份、迁移、连接池和监控。 |
| Managed policies | 在 gateway 或组织策略里集中限制模型、工具、权限和默认配置。不要依赖每个用户手动设置。 |
| Telemetry | 输出请求量、延迟、错误率、模型路由、spend 和策略命中。日志里默认不要记录完整 prompt。 |
| Upstream routing | 按用户、团队、模型、成本或区域把请求路由到 Anthropic、Passion8 或其他上游。 |
| Spend limits | 设置 user/team/project 级预算和时间窗口。超限时返回明确错误,不要静默切到未知模型。 |

## gateway.yaml 示例

下面是运维结构示例,用于说明应覆盖哪些配置域。实际字段名以当前 `claude gateway` 版本的 schema 为准。

```yaml
server:
  listen: "0.0.0.0:8443"
  public_url: "https://claude-gateway.internal.example.com"

auth:
  oidc:
    issuer_url: "https://idp.internal.example.com"
    client_id: "claude-apps-gateway"
    client_secret_env: "CLAUDE_GATEWAY_OIDC_CLIENT_SECRET"
    allowed_groups:
      - "engineering"
      - "support"

database:
  postgres:
    url_env: "CLAUDE_GATEWAY_DATABASE_URL"

policies:
  managed:
    enabled: true
    default_policy: "engineering-default"

telemetry:
  otlp:
    endpoint: "https://otel.internal.example.com/v1/traces"
    headers_env: "CLAUDE_GATEWAY_OTEL_HEADERS"

upstreams:
  - name: "anthropic"
    type: "anthropic"
    base_url: "https://api.anthropic.com"
    api_key_env: "ANTHROPIC_API_KEY"
  - name: "passion8"
    type: "anthropic"
    base_url: "https://passion8.cc"
    auth_token_env: "PASSION8_API_KEY"

routing:
  default_upstream: "anthropic"
  rules:
    - group: "support"
      upstream: "passion8"
      models:
        - "claude-sonnet-5-5"

spend_limits:
  defaults:
    user_daily_usd: 10
    team_monthly_usd: 1000
  on_exceeded: "deny"
```




把 OIDC secret、Postgres URL、上游 API key 和 telemetry headers 放在环境变量或 secret manager 中。不要把真实密钥写进 `gateway.yaml`。




## 通用 LLM gateway 协议

Claude Code 接入 Passion8 或自定义网关时,客户端仍发送 Anthropic Messages 请求。Base URL 写在 `ANTHROPIC_BASE_URL`,网关需要提供 Anthropic 兼容路径。

| 项目 | 要求 |
| --- | --- |
| Base URL | `ANTHROPIC_BASE_URL` 写到 host 根路径,例如 `https://passion8.cc`,通常不要带 `/v1`。 |
| Messages | `POST /v1/messages` 必须支持。 |
| Token count | `POST /v1/messages/count_tokens` 可选,缺失时客户端会退回估算或部分功能降级。 |
| Streaming | `stream: true` 时必须返回 SSE stream,不要被反向代理缓冲成一次性响应。 |
| Headers | 原样转发 `anthropic-version` 和 `anthropic-beta`,不要按固定旧版本重写。 |
| Errors | 上游 JSON 错误应保留 status、type、message,便于 Claude Code 判断是否重试或降级。 |

自定义网关如果要校验 body,应使用开放列表而不是只允许最小字段。至少保留这些字段,并对未知 beta 字段采用灰度透传或显式拒绝:

| 字段 | 说明 |
| --- | --- |
| `model`、`max_tokens`、`messages`、`system` | Messages API 的核心字段。 |
| `stream` | 控制 SSE 流式响应。 |
| `tools`、`tool_choice` | MCP、内置工具和 deferred tool loading 依赖这些字段。 |
| `thinking` | reasoning/effort 相关能力。 |
| `metadata`、`stop_sequences` | 业务标记和停止条件。 |
| `temperature`、`top_p`、`top_k` | 采样参数。 |
| `context_management`、`output_config` | Claude Code 的上下文和输出控制能力。 |
| `cache_control` | 可能出现在 system、messages、tools 等嵌套 block 上。 |

## system array 与 attribution

Claude Code 可能把 `system` 作为 array 发送,并把 attribution block 放在固定位置。gateway 必须保持 block 顺序、类型和嵌套字段:

| 不要做 | 风险 |
| --- | --- |
| 把 `system` array 合并成字符串 | 破坏 attribution 处理、prompt cache key 和 cache_control block。 |
| 在 attribution block 前插入自定义 system | 可能让 attribution 进入实际 prompt,也会改变缓存前缀。 |
| 对 system blocks 排序、去重或重写 | 会导致缓存 miss、策略误判或上游能力异常。 |
| 删除未知 block 字段 | 新版 Claude Code 的 beta 能力可能直接失效。 |

如果网关必须插入组织提示,优先用官方 managed policies 或上游支持的策略机制。必须改写 body 时,至少保留 attribution block 的相对顺序,并把改写行为打到审计日志里。

## 模型发现

Claude Code 可以从 gateway 拉取模型列表,用于 `/model` picker。开启变量:

```bash
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
```

发现请求是:

```text
GET /v1/models?limit=1000
```

运维约束:

| 项目 | 说明 |
| --- | --- |
| 超时 | 客户端等待时间约 3s。网关慢、跳转或 OIDC 拦截都会导致静默失败。 |
| 缓存文件 | 本机缓存通常在 `~/.claude/cache/gateway-models.json`。 |
| 手动模型变量 | 可用 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_FABLE_MODEL` 固定默认模型。 |
| 能力声明 | 模型出现在列表里不代表支持 tool search、1M context、thinking 或 1h prompt cache。 |

模型列表返回要稳定、轻量、无需交互登录。不要让 `/v1/models?limit=1000` 返回 HTML 登录页或重定向到 IdP。

## Prompt cache 与 1h TTL

1 小时 prompt cache 不是只靠客户端变量就能保证。自定义 gateway 要满足这些条件才适合透传:

| 条件 | 运维检查 |
| --- | --- |
| 客户端请求 | API/provider 场景设置 `ENABLE_PROMPT_CACHING_1H=1`,且未设置 `FORCE_PROMPT_CACHING_5M` 或 `DISABLE_PROMPT_CACHING`。 |
| 上游支持 | 实际路由到支持 1h TTL 的模型和 provider。 |
| Header 透传 | `anthropic-version`、`anthropic-beta` 不被剥离或降级。 |
| Body 稳定 | 不重写 `system` array、messages、tools、cache_control 或模型参数。 |
| Usage 返回 | 保留 `cache_creation_input_tokens` 和 `cache_read_input_tokens` 等 usage 字段。 |

如果上游不支持 1h TTL,网关应明确降级为 5 分钟策略并在 telemetry 中标记。不要用 body 重写伪造缓存命中,否则成本和延迟都会失真。

## Spend limits

spend limits 应在 gateway 层和上游账号层同时考虑:

| 层级 | 建议 |
| --- | --- |
| Gateway | 按 user、team、project、model、upstream 设置日/月预算和并发限制。 |
| Upstream | 设置 provider 侧硬限额,防止 gateway bug 或凭证泄露导致无限消费。 |
| 响应 | 超限返回稳定的 402、403 或 429 JSON 错误,包含 limit、window、reset 时间。 |
| 观测 | telemetry 中记录预算消耗、拒绝次数、触发规则和 fallback 行为。 |

不要在用户超限后自动切到更便宜但能力不同的模型,除非策略和 UI 明确告知。静默 fallback 会让调试、成本归因和安全审计都变复杂。

## Server-managed settings 限制

Anthropic server-managed settings 依赖官方账号、组织和服务端策略通道。使用 Passion8 或其他 custom `ANTHROPIC_BASE_URL` 时,不要假设它会覆盖第三方 provider 场景,也不要依赖它下发自定义 Base URL 或网关 token。

| 场景 | 推荐做法 |
| --- | --- |
| 统一设置 `ANTHROPIC_BASE_URL` | 用 MDM、endpoint-managed settings、系统级 managed settings 或本地模板。 |
| 统一分发 token | 用 `apiKeyHelper`、secret manager 或短期凭证,不要把 token 放进项目仓库。 |
| 统一限制模型和预算 | 放在 gateway managed policies 和 spend limits 中。 |
| 官方 Claude apps gateway | 通过 gateway 自身的 OIDC、Postgres、managed policies 和 telemetry 管理。 |

## Passion8 / 自定义网关清单

| 检查项 | 说明 |
| --- | --- |
| Base URL | Claude Code 使用 `https://passion8.cc` 这类根路径,不要写成 OpenAI 兼容的 `/v1` 地址。 |
| 认证变量 | Passion8 通常使用 `ANTHROPIC_AUTH_TOKEN`;不要和旧的 `ANTHROPIC_API_KEY` 登录状态混在一起排查。 |
| 私网入口 | 官方 apps gateway 登录页、OIDC callback、admin health route 都应在受控网络内可达。 |
| 反向代理 | 关闭 SSE buffering,保留长连接,设置合理 idle timeout。 |
| 字段透传 | headers、system array、tools、cache_control、usage 和 error body 都要原样保留。 |
| 安全审计 | 可以记录 request id、用户、模型、token 和策略命中,默认不要记录完整 prompt/body。 |

## curl 自检

下方 `claude-sonnet-5-5` 是当前官方 ID 示例，必须先确认你的 Passion8 Key 可用，否则换成控制台实际开放的模型。

先确认环境变量:

```bash
export ANTHROPIC_BASE_URL="https://passion8.cc"
export ANTHROPIC_AUTH_TOKEN="sk-..."
export ANTHROPIC_MODEL="claude-sonnet-5-5"
```

Messages JSON:

```bash
curl -sS "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "'"$ANTHROPIC_MODEL"'",
    "max_tokens": 64,
    "messages": [
      { "role": "user", "content": "只回答 ok" }
    ]
  }'
```

SSE stream:

```bash
curl -N "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "'"$ANTHROPIC_MODEL"'",
    "max_tokens": 64,
    "stream": true,
    "messages": [
      { "role": "user", "content": "stream ok" }
    ]
  }'
```

模型发现,按客户端约束用 3s 自检:

```bash
curl -sS --max-time 3 "$ANTHROPIC_BASE_URL/v1/models?limit=1000" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01"
```

可选 token count:

```bash
curl -sS "$ANTHROPIC_BASE_URL/v1/messages/count_tokens" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "'"$ANTHROPIC_MODEL"'",
    "messages": [
      { "role": "user", "content": "count tokens" }
    ]
  }'
```

自检结果应满足:

| 项目 | 通过标准 |
| --- | --- |
| `/v1/messages` | 返回 Anthropic Messages JSON,不是 HTML、登录页或代理错误页。 |
| SSE | `curl -N` 能持续看到 event/data 行,首包不被缓冲。 |
| `/v1/models?limit=1000` | 3s 内返回模型 JSON 或明确的 401/403 JSON。 |
| `count_tokens` | 支持时返回 token count;不支持时返回明确错误,不要伪造空结果。 |
| Spend limit | 超限时返回稳定 JSON 错误,并能在 telemetry 中查到触发规则。 |

## 官方参考

- [Claude apps gateway deployment and operations](https://code.claude.com/docs/en/claude-apps-gateway-deploy.md)
- [Deploy Claude apps gateway on Google Cloud](https://code.claude.com/docs/en/claude-apps-gateway-on-gcp.md)
- [Run Claude Code through a gateway](https://code.claude.com/docs/en/gateways.md)

## 相关页面



- [Claude apps gateway 部署](https://docs.passion8.cc/docs/claude-code/gateway-cloud-deployment): 私网入口、OIDC、Kubernetes、Cloud Run、GCP、健康检查和升级。
- [网关与协议](https://docs.passion8.cc/docs/claude-code/gateway): Base URL、headers/body、模型发现、缓存和常见错误。
- [企业部署总览](https://docs.passion8.cc/docs/claude-code/enterprise-deployment-overview): provider、认证、managed settings、权限和观测的组织级决策。