Gateway 运维

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

协议字段、错误语义、模型发现和缓存验收清单见 Gateway 协议上线清单。用户侧 provider 选择和认证变量见 Provider 认证与云平台接入。

#官方 Claude apps gateway

管理员用 claude binary 自托管 gateway:

claude gateway --config gateway.yaml

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

#gateway.yaml 示例

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

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-4"

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

#通用 LLM gateway 协议

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

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

#system array 与 attribution

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

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

#模型发现

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

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

发现请求是:

GET /v1/models?limit=1000

运维约束:

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

#Prompt cache 与 1h TTL

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

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

#Spend limits

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

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

#Server-managed settings 限制

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

#Passion8 / 自定义网关清单

#curl 自检

先确认环境变量:

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

Messages JSON:

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:

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 自检:

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:

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" }
    ]
  }'

自检结果应满足:

#官方参考

• Claude apps gateway deployment and operations
• Deploy Claude apps gateway on Google Cloud
• Run Claude Code through a gateway

#相关页面