Claude apps gateway：部署与运维

本页讲运行 Claude apps gateway 的运维面：在身份提供商（IdP）里注册 OAuth 客户端、把网关作为容器部署，以及日常运行。网关在启动时读取的 gateway.yaml 的每个选项见配置参考。

生产部署按顺序分四步，下面的章节与之对应。前两步是你要做选择的地方，后两步是运行起来之后查阅的参考资料：

1. 设置身份提供商：注册 OAuth 客户端，并查看 Okta、Entra 和 Google 各自的说明
2. 部署网关：构建固定版本的容器镜像并在 Kubernetes、Cloud Run 或你自己的平台上运行；这一节还涵盖成本、绕过、多网关和无服务器方面的决定
3. 设置运维：日志、健康探针、故障行为、密钥轮换和升级；在设置监控和运行手册时查阅
4. 审查安全姿态：什么数据流向哪里、威胁模型和合规问题的答案；做安全评审时查阅

沿途如果登录或启动失败，直接看「排障」，它按你看到的错误组织。

在你的私有网络上部署。 Claude Code 只连接地址为私有的网关。这是一道安全防护，因为受信任的网关可以推送在开发者机器上运行命令的设置。把你部署的网关放在内部负载均衡器或 VPN 后面，并给它一个只解析到私有 IP 的主机名。如果你的内部网络用的是你的组织拥有的公网 IPv4 空间编号，见「允许在你拥有的公网地址空间上的网关」。

身份提供商设置

注册一个机密的 OAuth/OpenID Connect（OIDC）web 应用，只有一个重定向 URI https://<gateway>/oauth/callback，并把它分配给应有网关访问权的用户或组。任何兼容 OIDC 的 IdP 都可以：Okta、Microsoft Entra ID、Google Workspace、Keycloak、Dex、PingFederate 等。IdP 必须满足三个要求：

• 提供 /.well-known/openid-configuration，生产环境用 HTTPS；网关接受 http:// 的 issuer，环回 issuer 另外要求 CLAUDE_GATEWAY_ALLOW_LOOPBACK=1
• 支持授权码流程。PKCE（Proof Key for Code Exchange）默认开启，对不支持它的 IdP 用 oidc.use_pkce: false 关闭
• 在 id_token 里返回 email（以及可选的 groups），或在设了 oidc.userinfo_fallback: true 时从 userinfo 端点提供它们

对私有 PKI，设置 oidc.ca_cert_pem。少数提供商处理邮箱和组声明的方式不同：

• Okta：https://example.okta.com 上的组织授权服务器返回的 id_token 很薄，省略 email 和 groups，所以用它作 issuer 时总要设 oidc.userinfo_fallback: true。像 https://example.okta.com/oauth2/default 这样在 id_token 里包含 email（以及可选 groups）的自定义授权服务器直接发出它们，不需要回退。Okta 只在 oidc.scopes 里请求了 groups scope 且应用的组声明过滤器允许时才发出 groups；userinfo_fallback 无法补全 IdP 没被请求的声明。
• Microsoft Entra ID：issuer = https://login.microsoftonline.com/<tenant-id>/v2.0。Entra 发出组的对象 ID 而不是名字，所以在 managed.policies.match.groups 里用 GUID，或用 App Roles 得到人类可读的名字。如果你的租户把角色放在 roles 而不是 groups 下发出，设 oidc.groups_claim: roles。
• Google Workspace：issuer = https://accounts.google.com。Google 的 id_token 不带组。要在以 Google 作 IdP 时使用基于组的 allowed_groups 或 managed.policies，配置 oidc.google_groups，它用带域范围委派的服务账号经 Admin SDK Directory API 查找每个用户的组；没有它时，用 oidc.allowed_email_domains 做成员把关，用 managed.policies.match.email_domain 做策略分配。Google 还忽略标准的 offline_access scope；要得到刷新令牌，设 oidc.scopes: [openid, profile, email] 和 oidc.extra_auth_params: { access_type: offline, prompt: consent }。

注意：刷新令牌让网关能静默续期开发者的会话，不必把开发者送回浏览器。它们还驱动取消预配：IdP 禁用用户后，下一次刷新失败，会话在 ttl_hours 内结束。网关默认请求 offline_access 来获得刷新令牌；如果你的 IdP 要求对离线访问显式同意，要把 OAuth 客户端配置为允许它。如果你的 IdP 完全无法签发刷新令牌，网关仍能工作，但没有静默续期，开发者要在会话过期时重新运行浏览器登录；要避免这每小时发生，把 session.ttl_hours 调高到 8 或 12，代价是取消预配的延迟，因为没有刷新令牌时，被禁用的用户在更长的 TTL 过去之前仍保有访问。

部署

网关是一个通过 Postgres 协调的无状态 Linux 二进制，所以按你环境里部署其他无状态服务的方式部署它。把它放在你的网络内，让开发者和 IdP 能通过 HTTPS 到达，并把它当作任何持有生产凭据的服务来对待。除了运行在哪里，还有几个决定塑造部署：

• 成本：没有单独的许可证或按席位收费。网关是 claude 二进制的一部分，所以你按现有承诺为推理付费，加上它运行所用的计算。
• 绕过：网关不强制通往模型的唯一路由要经过它。持有自己凭据的开发者仍然可以直接调用提供商，所以关闭这条路径是网络策略的决定，例如阻止除网关之外的、到 api.anthropic.com 的出口。阻止该出口也会破坏 WebFetch 域名安全检查（它从每个开发者的机器调用 api.anthropic.com）；在托管策略里设 skipWebFetchPreflight: true 可禁用它。
• 多个网关：每个是单独的部署，有自己的配置，CLI 按网关主机名存储信任和凭据，所以团队能使用不同的网关而不冲突。要服务多个 OIDC issuer，就运行单独的实例。
• 无服务器：Cloud Run 可行，只要设 min-instances: 1 以避免冷启动的 OIDC 发现；Lambda 和 Cloud Functions 不行，因为网关是长期运行的 HTTP 服务器。

这里每个生产拓扑都在纯 HTTP 副本前面放一个 L7 代理（如 Ingress、Cloud Run 的前端或 ALB）。把 listen.trusted_proxies 设为代理的源范围，让网关从 X-Forwarded-For 读取客户端 IP；网关只在 TCP 对端受信任时才采信该头。Google Cloud 和 AWS 的工作示例里有每种拓扑的具体值。没有受信任的代理时，每个请求看起来都来自代理的 IP，这会让每 IP 的速率限制塌缩成一个。不要重定向到网关设备授权和令牌端点的请求（例如在入口处做 HTTP 到 HTTPS 或主机名规范化的重写）：Claude Code 对这些请求不跟随重定向，所以重定向它们的入口规则会破坏登录和令牌刷新。要给代理设置比网关的 keepalive 间隔更长的任何空闲超时，该间隔取决于上游：在 provider: anthropic 之外的每个上游上，流静默约 15 秒后网关写一个 SSE ping；在 provider: anthropic 上，网关原样透传响应，包括 Anthropic API 自己的 ping。ALB 的 60 秒这样的默认值足以让安静的流保持打开；AWS 工作示例仍把它调高到一小时，其排障行涵盖 v2.1.229 之前的网关（它们在现在已有 ping 的上游上的安静期间什么都不发）。

容器镜像

围绕标准 Claude Code 发布的原生 claude 二进制构建你自己的镜像：从固定版本的发布下载你镜像架构的 Linux 构建（下载 URL 见「安装特定版本」）；对照发布的 GPG 签名 manifest.json 验证（见「二进制完整性与代码签名」）；把它复制进构建上下文。如果你的构建无法访问发布主机，就把发布镜像到你的内部仓库，并固定你的机队运行的版本。除二进制外，镜像还需要：

• 基于 glibc 的镜像：glibc 构建唯一的动态依赖是 glibc 库；基于 musl 的镜像需要 linux-x64-musl 或 linux-arm64-musl 构建加额外的软件包（见 Alpine Linux 设置）。
• 可写的状态目录：网关能以任何用户运行，但最小镜像没有可写的 home；把 CLAUDE_CONFIG_DIR 设为 /tmp/.claude 这样的可写路径。
• 容器命令：claude gateway --config /etc/claude/gateway.yaml，配置文件只读挂载，密钥作为环境变量提供；网关监听 listen.port，默认 8080。

Kubernetes

像任何无状态服务一样把网关作为 Deployment 运行：从 ConfigMap 挂载配置、从 Secret 挂载密钥，YAML 里通过 ${file:/path/to/secret} 或作为环境变量引用密钥；在 Ingress 终止 TLS 并把 listen.public_url 设为 Ingress 主机名；把就绪探针指向 GET /readyz，存活探针指向 GET /healthz。AWS 上的完整工作示例（涵盖 ECS Fargate 或 EKS、Amazon RDS 和 AWS Secrets Manager）见「在 AWS 上部署」。优先用平台的工作负载身份而不是静态密钥（每个平台的设置细节见 upstreams 参考）；对跨云组合（如 GKE 上的 Amazon Bedrock 上游），改在上游的 auth 块里设显式凭据。

Cloud Run

按下面配置服务：listen.port 保持默认 8080（与 Cloud Run 默认的 PORT 一致），或设 port: ${PORT}；把 public_url 设为外部可达的源——生产里这通常是内部负载均衡器的主机名，因为 /login 拒绝公网地址、而 *.run.app URL 解析到公网地址，所以单独的 Cloud Run URL 只适用于 curl 或浏览器冒烟测试；例外是 *.run.app 通过 Private Service Connect 和 Cloud DNS 私有区域私有解析的网络，在那种拓扑里 Cloud Run URL 是有效的 public_url（Google Cloud 工作示例涵盖两者）；把配置挂载为密钥卷；设 min-instances: 1 以避免首次请求时冷启动的 OIDC 发现。Google Cloud 上的完整工作示例见「在 Google Cloud 上部署」。

把网关 URL 推送到开发者机器

网关开始服务之后，通过托管设置把 forceLoginMethod、forceLoginGatewayUrl 和 parentSettingsBehavior: "merge" 推送到每个开发者的机器，经 MDM 或直接写每个操作系统的 managed-settings.json。没有这一步，/login 显示的是没有网关选项的标准账号选择器。部署这些键之后，Claude Code 不再使用机器上遗留的 API key 或 claude.ai 登录，所以要把推送与你的登录说明一起规划（开发者看到的消息见「管理员策略要求 Cloud 网关登录」）。每种机制把策略存在哪里的文件路径，以及 Claude Desktop bootstrapUrl 的等价物，见「客户端托管设置」。

大规模推广

登录按客户端 IP 地址做速率限制，默认值适合小团队：每个地址每 10 分钟 30 次登录开始和 10 次代码提交。向数千开发者推广可能在第一天早上就达到这些限制，原因有两种：

• 网关看不穿你的负载均衡器。 没有 listen.trusted_proxies，每个开发者看起来都来自负载均衡器的地址并共享一个限制。要先设它，网关在第一次忽略 X-Forwarded-For 头时会记录警告。
• 许多开发者共享少数几个 NAT 或 VPN 出口地址。 即使 trusted_proxies 正确，他们也共享这些地址的限制。要调高 rate_limits 来适应。

确定 max：用开发者数除以他们共享的出口地址数，估算其中多少人会在一个 window_seconds 周期（默认 10 分钟）内登录，再翻倍以涵盖重试和同时登录 Claude Code 与 Claude Desktop 的开发者。例如，10,000 个开发者在 4 个出口地址后面，在一小时里均匀登录：每个地址 2,500 个开发者，每 10 分钟约 420 个，翻倍并向上取整为 1,000。下面的例子把两个限制都设为 1,000：

rate_limits:
  device_authorization: { max: 1000, window_seconds: 600 }
  device_verify: { max: 1000, window_seconds: 600 }

device_verify 是阻止有人猜别的开发者登录码的东西，所以只调高到你的估算需要的程度。即使在这些限制下，码也是取自 20 个字符的字母表的 8 个字符且 10 分钟后过期，所以猜测仍不可行（见「用户码暴力破解的抵抗」）。当你的 IdP 签发刷新令牌时，Claude Code 静默续期会话，所以推广之后可以把限制调回去；没有刷新令牌时，开发者每 session.ttl_hours 再次登录，两个限制也要按这个稳态速率定大小并保持调高。达到限制时，Claude Code v2.1.274 及以上显示 The gateway is limiting sign-in attempts right now；v2.1.274 及以上的网关在验证页面上显示 Too many attempts came from your network address 并给出要检查的设置，还会写一行点名要更改的设置的 sign-in refused 日志。

运维

网关开始处理流量之后，日常运维就是读它的日志、探测它的健康，以及按你的计划轮换它的密钥。下面各小节涵盖每一项，外加 Postgres 里存什么以及升级和回滚的行为。

日志

网关向 stderr 写两个流，都对 JSON 友好：

审计事件：每个与安全相关的事件一行 JSON；把 stderr 接到你的日志聚合器。发出的事件包括 config.load、session.mint、session.refresh、device.authorize、device.verify、device.callback、auth.denied、access.denied、access.public_client、inference、managed.serve、desktop_bootstrap.serve、desktop_bootstrap.denied、spend.blocked、admin.denied、admin.limit.upsert 和 admin.limit.delete。字段随事件而异：

• 成功的 mint 和 refresh 事件携带 sub、email、client_ip 和结果
• auth.denied 和 access.denied 携带原因和客户端 IP，auth.denied 还有请求路径，因为在这些拒绝处不存在用户身份。两个 access.denied 原因会改变事件携带的内容：xff_unparseable——事件还携带无法读取的 X-Forwarded-For 条目；client_ip_unknown——事件不带客户端 IP，因为设了 access_control 列表而连接没有对端地址
• access.public_client 携带 access_control.allow_cidrs 为空时、每个进程第一个来自公网地址的请求的客户端 IP；网关照常服务该请求，事件表示网关可能能从公网到达（什么算公网以及推荐的允许列表见 access_control 参考）
• inference 记录哪个上游服务了请求以及响应状态
• desktop_bootstrap.denied 记录被拒绝的 Claude Desktop bootstrap 获取，带原因（not_configured、policy_not_opted_in 或 no_policy_matched）和用户身份
• admin.denied 记录被拒绝的管理 API 认证尝试，带客户端 IP、方法、路径和原因，不含出示的密钥材料：出示了 x-api-key 但不匹配任何已配置密钥时是 invalid_key；只出示了 Authorization 头且它没有验证为 admin.admin_groups 里的网关会话时是 bearer_rejected；两个头都没出示时是 no_credentials

运维日志：用于启动、警告和上游错误的、带 [gateway] 前缀的人类可读行。环境变量 CLAUDE_GATEWAY_LOG_LEVEL 控制详细程度，接受 debug、info、warn 或 error，默认 info。在 debug 下，每次登录和刷新还会记录 id_token 里声明的名字（不是值），以及 userinfo_fallback 提供了任何声明时的 userinfo 声明名字，使你能在不记录个人信息的情况下诊断 email_claim 和 groups_claim 设置；它不影响审计事件，审计事件总是发出。

健康

网关在 GET /healthz 提供存活探针，在 GET /readyz 提供就绪探针。/readyz 验证存储可达；如果你设了 store.readiness_grace_seconds，/readyz 在存储停止应答之后最多那么多秒内仍报告就绪。两个端点都不受 access_control.allow_cidrs 限制，所以探针在锁定的监听器上仍能工作。位于 /.well-known/oauth-authorization-server 的 OAuth 发现文档也只在配置加载、OIDC 发现、上游客户端构造和 Postgres 迁移全部成功之后才返回 200，所以它兼作端到端的启动检查。

并发上游请求

默认每个网关副本同时最多向上游发 256 个请求；流式响应在流结束前一直计入限制。副本达到限制时到达的请求在网关内等待空闲槽位，开发者看到的是启动缓慢或似乎挂起的响应。在 provider: anthropic 上游上，等待时间超过 timeouts.upstream_ttfb_ms 的请求会放弃该上游，没有后面的上游服务它时以 502 失败。启动日志里含 upstream requests: 的一行显示生效的限制；副本打开的请求多于限制时，它还会记录含 client requests are open 的警告，每分钟最多一次。要同时服务更多请求，有两个选择：增加副本；调高每个副本的限制——在网关容器上设环境变量 BUN_CONFIG_MAX_HTTP_REQUESTS 为 1 到 65535 的整数，然后重启容器。副本在约为限制除以请求平均保持打开秒数的请求速率下占满限制，例如请求平均保持打开 10 秒时，默认限制 256 的副本在约每秒 26 个请求时占满。如果你按 CPU 自动伸缩，达到限制的副本会排队请求而不触发扩容，所以要把目标设在副本记录 client requests are open 警告时所显示的 CPU 水平之下。

注意：每个打开的请求在流式传输和等待槽位期间都占用网关进程里的内存。即使把限制保持在 256，过载副本上的内存仍会增长，因为等待的请求保留着它们的请求体。要按峰值时打开的请求数给容器内存定大小，更改限制时要观察内存；内存耗尽的副本会被杀掉并丢掉它持有的每个流。

故障行为

Postgres 宕机时，网关本身继续为已登录的开发者服务，新登录失败。开发者是否真能继续工作取决于你的编排器如何处理就绪：

• 已有会话：bearer 令牌用 JWT 密钥本地验证，会话刷新不碰存储，网关进程仍能提供推理
• 新登录：失败直到 Postgres 恢复，因为设备流程和它的速率限制计数器存在 Postgres 里
• 支出限额强制：中断期间默认失败放行，所以推理仍然流动；如果你宁愿阻止也不愿不计量地运行，把它改成失败关闭
• 就绪：默认 /readyz 在 Postgres 一不可达就报告未就绪，所以每个副本同时就绪检查失败；在流量只到达通过检查的副本的地方，所有流量（包括网关本来还能服务的推理）都会失败，直到 Postgres 恢复；/healthz 上的存活探针始终通过

如果你的 IdP 宕机，已有会话在 ttl_hours 之前仍能工作，新登录失败；会话刷新得到重试的答复，IdP 恢复后成功。如果你的 IdP 有频繁的维护窗口，设更长的 ttl_hours。

就绪宽限期。 要让已登录的开发者在短暂的 Postgres 中断（如数据库故障转移）期间继续工作，把 store.readiness_grace_seconds 设为比故障转移耗时更长的值，例如 300。开启支出限额且为默认的失败放行行为时，经保持就绪的副本的请求在 Postgres 恢复前不被计量，所以要把该值保持在刚好涵盖你的故障转移的低值。如果你设了 enforcement.fail_closed_on_error: true，网关会以 429 spend limit unavailable 消息拒绝已登录开发者的推理，直到 Postgres 恢复，即使副本仍通过就绪检查。该设置需要网关服务器 Claude Code v2.1.282 及以上；更早的网关遇到该键会拒绝启动，所以要在加它之前升级每个副本（回滚见「升级」）。如果你改把就绪探针指向 /healthz，副本在中断期间也继续通过它，但 /healthz 从不报告未就绪，所以 Postgres 连接没有恢复的副本也继续通过。

JWT 密钥轮换

分阶段轮换签名密钥，使已有会话保持有效：1. 生成新密钥，前置到 session.jwt_secret 数组；2. 滚动部署（新令牌用新密钥签名，旧令牌仍能验证）；3. 在 ttl_hours 加余量之后，移除旧密钥再滚动一次。轮换也是在会话过期之前强制它们退出的唯一办法：bearer 令牌对 JWT 密钥本地验证，所以没有按会话的撤销。直接替换密钥而不把旧的留在数组里，会让所有未过期的会话立即失效。对个别人员离职，在你的 IdP 里取消预配该用户；他们的会话在 ttl_hours 内结束。

Postgres

网关持有五张数据表加一张 _migrations 表，都由启动时的迁移创建：

每 30 秒的循环让超过 TTL 的 kv 行过期，每小时的清扫在支出表上强制保留窗口，所以没有东西会无限增长；没有配置支出限额时，只写 kv。网关在启动时和每次升级时应用自己的 schema 迁移，所以它的数据库角色需要创建和修改表的权限；把它指向专用于网关的数据库或 schema，以保持该授权狭窄。使用支出限额时，丢失数据库意味着丢失支出跟踪和上限，不只是开发者重新登录，所以要做定期备份。要立即抹去一个离职的开发者而不是等保留期，直接运行 DELETE FROM principal_emails WHERE principal = '<sub>'；这移除了唯一持有其邮箱、名字和组的表；spend 和 admin_audit 行只引用假名化的 OIDC sub。

升级

副本是无状态的，所以滚动重启不丢失网关状态。网关在启动时运行 schema 迁移，这意味着部署新二进制就会让数据库自行迁移；并发的副本在 Postgres 咨询锁上串行，所以每个迁移只有一个应用它。当你的编排器用 SIGTERM 停止副本（如滚动重启或缩容）时，网关停止接受新连接，让已在进行的请求和流在退出前完成；它最多等 25 秒（称为排空窗口），然后关闭仍然打开的一切。SIGINT（如终端里的 Ctrl+C）启动同样的排空，排空期间的第二个信号会关闭打开的请求并立即退出（排空需要网关 v2.1.274 及以上）。长时间生成可能流式传输几分钟。在 Kubernetes 和 Amazon ECS 上，把这两者一起调高来给这些流更多时间：

• 排空窗口：在网关容器上把环境变量 CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS 设为毫秒数的正整数，如 120000；网关忽略任何其他形式的值（如 120s）并保持 25 秒的默认值
• 你的编排器的宽限期：Kubernetes 上的 terminationGracePeriodSeconds，或 Amazon ECS 上的 stopTimeout

宽限期在两个平台上默认 30 秒。要让它至少比排空窗口长 5 秒，否则编排器会在排空完成前杀掉网关；在 Kubernetes 上还要加上任何 preStop hook 的时长，因为宽限期在 hook 运行之前就开始计时，而不是在网关收到 SIGTERM 时。你的平台也可能限制排空能运行多久：Amazon ECS on Fargate——stopTimeout 最多允许 120 秒；Cloud Run——在 SIGTERM 之后 10 秒停止实例，所以那里打开的流最多得到 10 秒，不论排空窗口是多少。排空窗口结束时仍有请求打开，网关会记录含 drain window over after 的警告，统计它切断的请求，并点名要调高的两个设置。迁移是只追加的，所以回滚到认识更少迁移的旧二进制是安全的，它忽略多出的行。回滚还会按旧二进制的 schema 重新验证 YAML，所以采用了新版本引入的键的配置会在旧版本上启动失败；回滚前先移除新键。因为你在自己的镜像里固定网关的版本，新 Claude Code 发布里的修复（包括安全修复）只有在你更新固定版本并重新部署时才到达你的部署；要把网关纳入你对其他持有生产凭据的服务使用的同一修补节奏。

安全

本节回答安全评审会问的问题：什么数据流经网关、流向哪里，设计防御哪些攻击，以及哪些答案属于合规问卷。

数据流

威胁模型摘要

网关位于你的网络边界之内，但单个开发者笔记本不被视为受信任。设计用三种方式应对：

• 开发者持有短期 JWT 而不是原始的上游密钥。CLI 到网关这一段用 RFC 8628 设备授权，网关与 IdP 的授权码交换在默认配置下运行 PKCE，所以被截获的 IdP 授权码没用。
• 设备验证页面按 RFC 8628 §5.1 强制同源 POST 和每 IP 速率限制（见「用户码暴力破解的抵抗」）。
• 网关对你的 IdP、你的 OTLP 收集器和 provider: anthropic 上游的请求要经过服务端请求伪造（SSRF）防护：它解析 DNS，默认阻止链路本地、云元数据地址和环回，并把连接固定到解析出的 IP，所以这些受运营者影响的 URL 无法被重定向到云元数据端点；RFC 1918 私有范围被刻意允许，因为 IdP 和 OTLP 收集器常在私有 IP 上。对其他提供商，网关在加载配置时拒绝点名这些地址或元数据主机名的 base_url，提供商的 SDK 随后不带 DNS 检查地连接。开启仅代理出口时，该地址检查移到你的正向代理：网关把主机名交给它，代理的允许列表必须拒绝这些目的地。只有当网关必须合法访问的东西位于环回上（如本地开发的 IdP 或 localhost 上的 sidecar OTLP 收集器）时，才在网关环境里设 CLAUDE_GATEWAY_ALLOW_LOOPBACK=1：该变量会对每个运营者配置的 URL 放宽环回阻止，并跳过检查 pod 能否到达云元数据端点的启动警告，所以优先给收集器自己的内部地址。如果你添加自己的出口控制，网关在使用实例元数据凭据（如工作负载身份）时必须能到达元数据服务器。

两个威胁不在范围内，因为它们是你要保护的基础设施：被攻破的网关主机——该主机既持有上游凭据又向每个已连接的开发者分发托管设置，所以对网关配置的控制相当于对你的 MDM 的控制；CLI 对可执行 shell 的设置的批准对话框限制了静默更改，但不能取代主机安全；恶意的 OIDC 提供商——提供商签署网关信任的 id_token，所以它可以断言任何身份；审查并保护你的 IdP 是你的责任。

用户码暴力破解的抵抗

开发者在 /device 验证页面键入的 user_code 是取自 20 个字符的字母表的 8 个字符，即 20⁸ 或约 2.56×10¹⁰ 种组合，并在 10 分钟后过期。网关对设备授权端点应用每 IP 速率限制，可经 rate_limits 配置。如果许多开发者从单个共享的企业 NAT 地址登录，就调高限制（定大小见「大规模推广」）。这些限制只适用于登录流程，不适用于推理。

合规姿态

• 数据驻留：除非 Anthropic API 是已配置的上游，网关自己的数据平面不向 Anthropic 发送任何东西；是的话，你现有的数据处理协议适用于推理路径。遥测、审计、身份和设置只去往你配置的目的地。
• 宿主进程流量：宿主进程是 Claude Code CLI。claude gateway 遵循与 Amazon Bedrock 和 Google Cloud Agent Platform 部署相同的第三方规则，不向 Anthropic 发送任何东西。v2.1.227 之前，宿主进程会发送产品版本和平台这类启动遥测，在容器环境里设 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 可以关闭；那些版本还会在启动时向 https://api.anthropic.com（或环境设了 ANTHROPIC_BASE_URL 时向它）的 /api/hello 发一个不带正文或凭据的 HEAD 请求，除非环境还设了 HTTPS_PROXY 这类代理变量或 mTLS 客户端证书；它们忽略响应，所以在出口防火墙阻止该请求不影响网关。
• 客户端分析：CLI 在登录到网关期间禁用自己的用量分析和错误报告。第一次登录之前，CLI 仍向 Anthropic 发送启动事件，包括在托管设置强制网关登录的机器上；要把这些也关掉，把 DISABLE_TELEMETRY 放在强制网关登录的同一份客户端托管设置里下发。
• 错误报告：只要模型请求发往 Anthropic 第一方 API 之外的任何端点（如 Amazon Bedrock 或自定义 ANTHROPIC_BASE_URL），CLI 就关闭错误报告。
• 客户端机器：除非设了 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 和 skipWebFetchPreflight: true，开发者的 CLI 仍会向 Anthropic 发送 WebFetch 主机名检查和版本检查（见数据使用）。
• 调查评分：登录到网关期间，CLI 与分析流一起禁用发往 Anthropic 的评分上传，所以不向 Anthropic 发送评分。
• 记录分享：对调查的记录分享提示选择"是"，会在 ~/.claude/feedback-bundles/ 下写一个本地文件，而不是上传到 Anthropic。
• 客户端更新：更新检查与网关流量是分开的。通过你自己的分发固定版本，并在笔记本不得获取发布时设 DISABLE_UPDATES；DISABLE_AUTOUPDATER 只停止后台更新，claude update 仍能用。
• TLS：生产里经 HTTPS 提供 public_url，可以由网关自己经 listen.tls 的监听器提供，也可以由纯 HTTP 副本前面终止 TLS 的入口提供，两种情况下都要设 listen.public_url；网关不拒绝纯 HTTP。IdP 在生产里必须提供 HTTPS，Postgres 支持 ?sslmode=require；在你的入口设置 Strict-Transport-Security。
• 漏洞披露：遵循「报告安全问题」。

排障

有问题和反馈时，用 Claude Code 支持，或在 Claude Code GitHub 仓库提 issue。报告问题时要包含：

• 网关问题：相关时间窗口的网关 stderr、已脱敏密钥的 gateway.yaml、网关版本（显示在 / 的落地页上，以及 /managed/settings 上的 x-cc-gateway-version 响应头里），以及最近改了什么
• 登录问题：开发者运行 claude --debug-file ./claude-debug.txt、重现，并把该文件与同一窗口的网关审计日志一起发来
• 推理问题：请求的模型、配置的上游，以及该请求的网关审计日志（它记录哪个上游服务了它以及响应状态）

网关的 stderr 包含审计事件流，审计日志记录开发者身份，调试文件记录来自开发者机器的 hook 和 MCP 服务器输出；发到公开 issue 之前要审查并脱敏。

Cloud gateway sign-in was not completed 消息会点名网关主机名；当 Claude Code 同时有固定的指纹和出示的指纹时，消息还显示两者各自的前 16 个字符。如果 Claude Code 在网关登录之后报告 couldn't load your organization's managed settings，它会点名原因、就地重启并恢复对话；如果 Claude Code 无法重启（例如在后台会话里），它会结束会话并保留登录。

相关

• Claude apps gateway 概览：快速开始和开发者连接
• 配置参考：每个 gateway.yaml 选项