Claude 应用网关配置

gateway.yaml 所有选项的参考文档：监听器与 TLS、OIDC、会话、Postgres 存储、Amazon Bedrock、Claude Platform on AWS、Google Cloud Agent Platform 和 Microsoft Foundry 上游、模型路由、托管策略以及遥测。

Claude 应用网关部署由一个 YAML 文件配置，通常命名为 gateway.yaml。网关的所有行为都在这个文件中定义：监听位置、开发者的登录方式、推理请求的去向，以及要应用的策略和遥测配置。本页是该文件中所有选项的参考文档。

要编写第一份配置，请从快速入门开始；其中会构建一份可运行的最小配置并将其启动。配置调整满意后，可参阅部署指南，了解如何将网关容器化，以及如何将其托管在 Kubernetes、Cloud Run 或您自己的平台上。

网关会在启动时通过 claude gateway --config /path/to/gateway.yaml 读取该文件一次。启动期间，每个选项都会依据 schema 进行验证，因此配置格式有误时，网关会在启动阶段报告具体字段的错误，而不会等到首次使用时才失败。

本页末尾的完整示例涵盖了所有配置部分。

文件结构

其中有五个必需部分。其他部分均为可选部分；省略时采用默认值。未知的键会导致启动失败，因此拼写错误会以明确指出键名的错误呈现，而不会被静默忽略。

必需部分：

• listen：绑定地址、公开 URL、TLS 终止
• oidc：身份提供商 (IdP)，包括颁发者、客户端、声明映射和登录资格
• session：网关签发的 bearer Token，包括密钥和有效期
• store：用于存储设备授权和限流计数器的 PostgreSQL
• upstreams：推理请求的目的地，可以是 Anthropic、Amazon Bedrock、Claude Platform on AWS、Google Cloud Agent Platform 或 Microsoft Foundry

可选部分：

• admin：Admin API 身份验证和消费限额数据保留
• enforcement：消费限额的故障开放或故障关闭行为
• models 和 auto_include_builtin_models：管理员选定的模型列表及各上游对应的 ID
• managed：按 IdP 组划分的托管设置策略
• telemetry：将 OTLP 数据转发到可观测性技术栈
• access_control、limits、timeouts、rate_limits：IP 允许/拒绝规则、请求大小上限、上游首字节响应时间，以及按 IP 统计的登录限流

密钥展开

不要将 client_secret、jwt_secret 或 postgres_url 等密钥直接写入 gateway.yaml。请使用以下任一形式引用密钥，网关会在启动时从环境变量或文件中解析其值：

必需部分

listen

listen 块控制网关在何处提供服务：绑定地址和端口、外部可见的源，以及可选的 TLS 终止。

oidc

oidc 块将网关连接到您的身份提供商，并决定哪些用户可以登录。它指定颁发者和 OAuth 客户端，映射承载电子邮件地址和组信息的声明，并可按电子邮件域或组限制登录。

OpenID Connect (OIDC) 是网关与身份提供商配合使用的 SSO 协议。有关需要在 IdP 端注册的内容，请参阅身份提供商设置。

session

session 块定义网关在登录后签发的 bearer Token：用于签名的密钥及其有效期。

store

store 块将网关连接到 PostgreSQL 数据库，用于保存设备授权和限流计数器。

本地开发时，可将 postgres_url 指向一个用完即弃的 Postgres 容器，例如 docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres。

upstreams

upstreams 是一个有序列表。网关会将推理请求转发到第一个能够解析所请求模型的上游。遇到 5xx、429、401、403、404 或超时时，会故障转移到下一个上游；其他 4xx 不会触发故障转移，因为这类错误应归因于请求本身，而不是上游。401 或 403 表示网关自身的凭据未能通过该上游的验证；404 表示该上游不提供所请求的模型，因此列表中后续的上游仍可能处理请求。

在 404 时进行故障转移需要网关 v2.1.198 或更高版本。早期版本即使列表中的后续上游提供该模型，也会把第一个 404 返回给客户端。

同一提供商的多个上游必须分别设置不同的 name:。

Amazon Bedrock、Claude Platform on AWS、Google Cloud Agent Platform 和 Microsoft Foundry 客户端在启动时创建一次，其 SDK 会在内部刷新凭据，因此轮换云凭据无需重启。静态 Anthropic API 密钥和 bearer Token 会在启动时读取；请参阅 Anthropic API。

Anthropic API

最小的 Anthropic 上游配置只需一个来自 Claude Console 的 API 密钥：

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}
    # 或使用 OAuth bearer Token（例如，通过 Workload Identity Federation 交换获得的 Token）：
    #   oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
    # base_url: https://api.anthropic.com   # 默认值；如使用正向代理可覆盖

两种凭据形式发送的标头不同：

• api_key：发送 x-api-key。请在 Claude Console 中轮换密钥，并更新环境变量。
• oauth_token：发送 Authorization: Bearer。如果组织签发的是短期 Token，而不是长期 API 密钥，请使用 bearer 形式。bearer 只在启动时读取一次，因此需要重新挂载密钥并重启才能刷新。

除静态密钥或 bearer 外，还可以使用 Workload Identity Federation。按照 Workload Identity Federation 指南创建联合规则，然后将工作负载的 OIDC JWT 以文件形式挂载，例如 Kubernetes 投射的服务账号 Token 或 CI 平台的 id-token。网关会将该 JWT 交换为短期 bearer，并自动刷新。每次交换都会重新读取 Token 文件，因此轮换后的投射 Token 无需重启即可生效。

upstreams:
  - provider: anthropic
    auth:
      federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
      organization_id: ${ANTHROPIC_ORGANIZATION_ID}
      identity_token_file: /var/run/secrets/anthropic/id-token
      # workspace_id: wrkspc_...       # 规则涵盖多个 workspace 时必填
      # service_account_id: svac_...   # 可选的预期目标校验

Amazon Bedrock

有关网关所替代或位于其前方的客户端 Amazon Bedrock 部署，请参阅 Amazon Bedrock 上的 Claude Code。网关侧的上游配置如下：

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # 首选：AWS 默认凭证链
    # 或显式指定凭证：
    # auth:
    #   aws_access_key_id: ${AWS_AKID}
    #   aws_secret_access_key: ${AWS_SK}
    #   aws_session_token: ${AWS_ST}
    # 或使用 Bedrock API bearer Token：
    # auth:
    #   aws_bearer_token: ${AWS_BEARER_TOKEN}
    # 针对 FIPS 或 VPC endpoint 部署覆盖 bedrock-runtime 端点：
    # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

空的 auth 块会使用 AWS SDK 的默认凭据链：环境变量、~/.aws/credentials、ECS 任务角色、EC2 实例元数据或 EKS 上的 IRSA。在生产环境中，应为网关 Pod 分配 IAM 角色，而不要将静态密钥嵌入容器镜像。

Claude Platform on AWS

Claude Platform on AWS 在 AWS 基础设施上的 aws-external-anthropic.<region>.api.aws 提供 Anthropic 第一方 API。它使用第一方模型 ID，按原样处理 anthropic-beta 标头，并提供 count_tokens，因此不需要进行任何 Bedrock 特有的转换。anthropicAws 提供商要求 Claude Code v2.1.198 或更高版本；较早的网关版本会在启动时拒绝它。

有关同一平台的客户端部署，请参阅 Claude Platform on AWS 上的 Claude Code。网关侧的上游配置如下：

upstreams:
  - provider: anthropicAws
    region: us-east-1
    workspace_id: wrkspc_...
    auth:
      api_key: ${ANTHROPIC_AWS_API_KEY}   # 作为 x-api-key 发送
    # 或通过 AWS 默认凭证链使用 SigV4：
    # auth: {}
    # 或显式指定 SigV4 凭证：
    # auth:
    #   aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    #   aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    # 覆盖推导出的端点：
    # base_url: https://aws-external-anthropic.us-east-1.api.aws

该平台与 Amazon Bedrock 运行在不同的 AWS 账号中，并使用自己的服务名称 aws-external-anthropic 对 SigV4 请求进行签名，因此仅限 Bedrock 的 IAM 角色无法授权访问它。如果同时设置了 SigV4 凭据，auth.api_key 中的 API 密钥优先。空的 auth 块使用 AWS SDK 的默认凭据链，与 Amazon Bedrock 上游使用的凭据链相同。

由于平台可解析第一方模型 ID，因此内置目录不需要 models: 块即可路由到该平台。自行指定 models: 列表时，请使用 anthropicAws: 作为条目键，并将第一方 ID 设为其值。

Google Cloud Agent Platform

有关等效的客户端设置，请参阅 Google Cloud 上的 Claude Code。网关侧的上游配置如下：

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    auth: {}                           # 首选：Application Default Credentials
    # 或使用服务账号密钥文件：
    # auth: { service_account_json: /secrets/sa.json }
    # 覆盖用于 Private Service Connect 的 aiplatform 端点：
    # base_url: https://us-east5-aiplatform.p.googleapis.com

空的 auth 块使用应用默认凭据：GOOGLE_APPLICATION_CREDENTIALS、GCE 元数据或 GKE Workload Identity。虽然也支持服务账号 JSON 密钥文件，但不建议使用；请优先使用 Workload Identity，或将服务账号附加到 GCE 或 Cloud Run 实例。

将 region: global 设为使用 Google Cloud Agent Platform 的全球端点，而不是区域端点。随后 Google 会将每个请求路由到可用区域，您无需跟踪各区域的模型可用性。指定具体区域则会将每个请求固定到该区域。

Microsoft Foundry

有关客户端 Microsoft Foundry 部署，请参阅 Microsoft Foundry 上的 Claude Code。网关侧的上游配置如下：

upstreams:
  - provider: foundry
    resource: example-foundry              # https://example-foundry.services.ai.azure.com
    auth: { use_azure_ad: true }        # 首选：DefaultAzureCredential / Managed Identity
    # 或使用 API key：
    # auth:
    #   api_key: ${FOUNDRY_API_KEY}

use_azure_ad: true 通过 DefaultAzureCredential 解析凭据：AKS、ACI 或 App Service 上的 Managed Identity、Azure CLI，或环境凭据。API 密钥也可用，但作用于整个项目，且不会自动轮换。Microsoft Foundry 的端点根据 resource: 推导；对于 Azure Government 等主权云，可设置可选的 base_url 来覆盖该端点。

多个上游

同一提供商可以出现多次，但各项必须使用不同的 name:。这适用于不同区域、通过不同凭据链访问的不同账号、预置吞吐量与按需容量，以及跨提供商回退等场景。

网关按顺序尝试上游。5xx、429、401、403、404、超时和缺少端点 (501) 会触发故障转移；其他 4xx 不会。

429 表示单个上游的容量问题，因此预置吞吐量 (PT) 耗尽时会故障转移到按需容量。404 表示单个上游的模型可用性问题，因此尚未启用某个模型的上游不会阻止后续可提供该模型的上游。无法解析所请求模型的上游会被跳过，不会发生网络往返。

以下示例首先将请求路由到 Amazon Bedrock 预置吞吐量配额；容量溢出后，依次转移到按需容量和另一个账号，最后回退到 Anthropic API：

upstreams:
  # 主上游：本地区域内的预置吞吐量。
  - name: bedrock-pt
    provider: bedrock
    region: us-east-1
    auth: {}
  # 溢出上游：跨区域按需容量。
  - name: bedrock-od
    provider: bedrock
    region: us-west-2
    auth: {}
  # 其他账户：通过 assumed-role 凭证使用单独的 Bedrock 配额。
  - name: bedrock-acct2
    provider: bedrock
    region: us-east-1
    auth:
      aws_access_key_id: ${ACCT2_AKID}
      aws_secret_access_key: ${ACCT2_SK}
  # 最后选择：直连 Anthropic API。
  - name: anthropic-fallback
    provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

# 每个上游的模型 ID 以该上游的 `name:` 为键；没有 `name:` 的上游
# 默认使用其提供商字符串（例如 `bedrock`）。模型配置中未列出的任何
# 上游都会被跳过。借此可以将某个模型路由到预置吞吐量，同时让其他
# 所有模型继续使用按需容量。
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
      bedrock-od: us.anthropic.claude-opus-4-8
      bedrock-acct2: us.anthropic.claude-opus-4-8
      anthropic-fallback: claude-opus-4-8

在不同云提供商之间进行故障转移，或回退到直接使用 Anthropic API，会改变请求适用的协议、地理区域及其他条款。

无论处理某个请求的是哪个上游，CLI 都会对网关应用相同的功能门控，因此故障转移不会向上游发送其无法接受的请求正文字段。

可选部分

admin

可选。启用 /v1/organizations/spend_limits（与 Anthropic 的公共 Admin API 对应）以及 /v1/messages 上按开发者执行的消费限额。有关限额的设置和执行方式，请参阅消费限额；本节介绍用于启用和调整该功能的 gateway.yaml 键。

admin:
  # 管理端点使用的具名静态 API key，通过 x-api-key 发送。
  # id 会以 admin-key:<id> 形式出现在审计日志中，从而可以
  # 追溯每个 key。此数组用于轮换：添加新 key、更新客户端，
  # 再移除旧 key。
  write_keys:
    - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
    - { id: ci,        key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
  read_keys:
    - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
  # 通过常规网关 JWT 获得完整管理员权限的 IdP 组（无需 API key）。
  admin_groups: [platform-finops]
  blocked_message: 如需提高限额，请访问 https://go.example.com/claude-limits

enforcement

enforcement 块控制存储不可用时消费限额检查的行为。

models

models 块是可选的管理员精选模型列表，由 /v1/models 提供，并用于转换各上游的模型 ID。对于美国以外的 Amazon Bedrock 区域、Amazon Bedrock 预置吞吐量 ARN 和 Microsoft Foundry 部署名称，此块为必需。

auto_include_builtin_models: true   # false：仅公开下方列表
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    # description: 显示在支持该字段的客户端中的可选文本
    upstream_model:
      anthropic: claude-opus-4-8
      bedrock: us.anthropic.claude-opus-4-8   # 或 inference profile ARN
      foundry: your-opus-deployment-name

managed

managed 块定义基于角色的访问策略，以 IdP 组或电子邮件域为匹配条件。策略按顺序求值：先选择第一个匹配项，再将其合并到下文所述的 match: {} 全匹配基础策略之上。系统通过 GET /managed/settings 按用户提供策略，并使用 ETag/304 缓存。

managed:
  policies:
    # 先列出特定组。
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    # 最后列出默认兜底规则：匹配所有已通过身份验证的用户。
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

通常列在最后的 match: {} 全匹配策略会被视为基础层。其他每项策略都会从全匹配策略继承自身未设置的键，因此按角色配置的条目只需列出与组织默认值不同的部分。合并规则取决于键的类型：

• 允许列表：availableModels 和 permissions.allow。具体策略的列表会完全替换基础列表。
• 拒绝列表和 Hook 数组：permissions.deny、permissions.ask、disabledMcpjsonServers、deniedMcpServers、blockedMarketplaces，以及 hooks 各事件类型的数组。这些值取基础策略与具体策略的并集，因此组织级拒绝规则或审计 Hook 不会被按角色的覆盖意外移除。
• 记录类型的键：env、modelOverrides 和 skillOverrides。这些键进行浅合并，因此按角色配置的 env 块会覆盖自身设置的键，同时继承基础策略中的其余键。

availableModels 还会在服务器端的 /v1/messages 强制执行，因此无论客户端发送什么内容，被拒绝的模型都会返回 400。

已通过身份验证但未匹配任何策略的用户会获得网关默认配置，即可使用目录中的所有模型，且没有托管设置。如果要保证始终存在默认策略，请在最后添加 match: {} 全匹配项。

cli 中可以包含的内容

每个 cli 值都是一份完整的 Claude Code managed-settings.json 文档，其 schema 与通过 MDM 或 /etc/claude-code/managed-settings.json 部署的文档相同，只是在此处以 YAML 表示。CLI 会在托管层级应用下发的文档，其优先级高于用户和项目设置。

网关启动时会依据 CLI 的设置 schema 验证每份文档。如果存在无法识别的顶层键，或已识别键的值格式错误，启动就会失败，并在错误中列出所有有问题的键。schema 中有意保持开放的部分仍接受任意值，因为较新的客户端可能会识别网关 schema 尚不了解的条目。这些开放键包括 env、pluginConfigs，以及 permissions 下嵌套的键。

由于验证使用网关安装版本所附带的 schema，如果要在托管配置中加入较新 Claude Code 版本引入的顶层设置键，必须先升级网关。全面推广新策略前，请先在一台客户端上进行冒烟测试。

完整的键参考请参阅 Claude Code 设置。运维人员最常用的键如下：

managed:
  policies:
    - match: {}
      cli:
        # 模型访问权限（服务器端也会在 /v1/messages 强制执行）
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

        # 权限策略
        permissions:
          deny:
            - "WebFetch"
            - "Read(./.env)"
            - "Read(./secrets/**)"
          disableBypassPermissionsMode: disable   # 阻止 --dangerously-skip-permissions
        allowManagedPermissionRulesOnly: true     # 忽略用户/项目权限规则

        # 注入 CLI 进程的环境变量。DISABLE_UPDATES 会阻止
        # 后台和手动更新；DISABLE_AUTOUPDATER 仅阻止
        # 后台更新。
        env:
          DISABLE_UPDATES: "1"                    # 通过你自己的分发渠道固定版本

        # 组织范围的 Hook。Hook 命令在开发者机器上运行，而非
        # 网关，因此该路径必须存在于策略覆盖的每种客户端 OS 上。
        hooks:
          PostToolUse:
            - matcher: "Edit|Write"
              hooks:
                - { type: command, command: /usr/local/bin/audit-edit.sh }

由于这些设置经由网络传送，CLI 会在首次应用任何能够执行 shell 命令或改变流量目的地的设置前，向每位开发者显示一次安全审批对话框。该对话框涵盖：

• hooks
• 不在 CLI 内置安全列表中的 env 变量
• apiKeyHelper 和 statusLine 等执行 shell 的设置
• 托管的 CLAUDE.md 内容

以下安全列表决定哪些 env 变量无需批准即可应用：

• 在安全列表中：自动更新变量和模型名称变量
• 不在安全列表中：代理变量、基础 URL 变量和 OTEL_EXPORTER_OTLP_ENDPOINT

网关的遥测配置会推送 OTEL_EXPORTER_OTLP_ENDPOINT，因此设置 telemetry.forward_to 会在每个交互式客户端上触发该对话框。使用 -p 标志的非交互式运行会跳过对话框，并直接应用设置。该对话框旨在保护开发者的计算机免受已遭入侵或恶意网关的影响，而不是保护组织免受开发者影响，因此允许 -p 跳过是有意设计，并非漏洞。

如果开发者拒绝，Claude Code 会直接退出，而不会应用策略。因此，如果向覆盖范围广的策略推送新的 Hook 或非安全环境变量，每个匹配该策略的开发者都会在下次启动时看到审批提示。

早期版本将 cli 键命名为 settings。该拼写仍可作为别名使用，但新部署应使用 cli。

与其他托管来源之间的优先级

如果设备上还存在本地 managed-settings.json 或通过 MDM 下发的策略，各托管来源不会合并。优先级最高的来源提供全部策略设置，优先级从高到低如下：

1. 策略辅助程序
2. 网关下发的设置
3. MDM；在 Windows 上通过 HKLM 注册表，在 macOS 上通过 plist
4. managed-settings.json 文件
5. HKCU 注册表（仅限 Windows）

嵌入式宿主可以通过 SDK 的 managedSettings 选项提供策略。默认情况下该策略会被忽略；仅当某个托管来源通过 parentSettingsBehavior: "merge" 选择加入时才会应用，并且会经过筛选，只能收紧策略，不能放宽策略。

唯一的例外是以下键：只要用户可写的 HKCU 层级之上的任一管理员来源设置了这些键，无论其余策略来自何处，它们都会生效：

• sandbox.network.allowManagedDomainsOnly 和 sandbox.filesystem.allowManagedReadPathsOnly：锁定后，会合并各来源中相应允许列表的并集
• allowAllClaudeAiMcps：仅允许型的 claude.ai MCP 服务器允许列表覆盖
• sandbox.bwrapPath 和 sandbox.socatPath：沙箱辅助二进制文件的文件系统路径
• forceRemoteSettingsRefresh：在远程托管设置获取到最新版本前阻止启动。因此，即使不含此键的缓存远程负载是最高优先级来源，由 MDM 或文件策略设置的该键仍会生效

其他所有键（包括 allowManagedPermissionRulesOnly 和 disableBypassPermissionsMode）都只取自最高优先级来源。有关设置页中的同一规则，请参阅设置优先级。

网关策略适用于计算机上的每次 Claude Code 调用，包括非交互式 claude -p 运行和 Agent SDK 启动的会话。如果启动时网关不可达，已登录的会话会报错退出，而不会在缺少策略的情况下运行。

telemetry

CLI 会通过 HTTP 发送 OpenTelemetry Protocol (OTLP) 指标、日志，以及启用后的跟踪数据；网关会将这些数据原样转发到各个已配置的目的地。有关 CLI 发出的指标和事件，请参阅监控用量。

CLI 会在每次导出中附加已通过身份验证的用户身份，该身份从网关签发的 JWT 中读取，包括 user.id、user.email 和 user.groups 属性。因此，无需开发者侧配置即可按开发者归属成本和用量。

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      # 按信号选择启用。默认：仅指标。
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}

CLI 默认关闭遥测。同时配置 telemetry.forward_to 和 listen.public_url 会将其开启。网关会通过 /managed/settings 向每个已连接的客户端推送五个环境变量：

• CLAUDE_CODE_ENABLE_TELEMETRY=1
• OTEL_METRICS_EXPORTER=otlp
• OTEL_LOGS_EXPORTER=otlp
• OTEL_TRACES_EXPORTER=otlp
• OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>

推送的端点根据公开 URL 构造，因此开发者或策略无需为指标和日志提供任何 OTEL 配置。推送的配置在托管层级应用，会覆盖开发者在本地设置的 OTEL_* 变量。

跟踪数据还要求每个客户端设置 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1。网关不会推送该变量，因此请通过托管策略的 env 块设置。该变量不在 CLI 安全列表中，因此通过策略下发时，也会触发推送 OTLP 端点时已会触发的同一个安全审批对话框。

网关会中继 protobuf 和 JSON 两种 OTLP 编码，任何兼容 OpenTelemetry 的后端均可作为目的地。

HTTP 调优

四个可选顶层块 access_control、limits、timeouts 和 rate_limits 用于调整 HTTP 接口。默认值适合大多数部署。

完整示例

以下完整参考配置涵盖所有核心部分；HTTP 调优块保持默认值。复制该配置，删除不需要的部分，然后填入您自己的值。快速入门中的配置是此示例的最小版本。

# 运行命令：
#   claude gateway --config gateway.yaml
#
# 运行日志详细程度由 CLAUDE_GATEWAY_LOG_LEVEL
# 环境变量控制（info | warn | error；默认为 info）。这不会
# 影响审计事件，审计事件始终会发出。

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
  # 在终止 TLS 的 ingress 后运行时，请省略 tls 块。
  # tls:
  #   cert: /certs/gateway.crt
  #   key: /certs/gateway.key
  # trusted_proxies:
  #   - 10.0.0.0/8

oidc:
  issuer: https://example.okta.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains:
    - example.com
  # 当 issuer 是 Okta org server 时必须启用，因为其 id_tokens
  # 可能省略 email 和 groups；网关会从 /userinfo 补全。
  userinfo_fallback: true
  # allowed_groups: [claude-code-users]
  # 只有请求 `groups` scope 且应用的 groups claim 筛选器允许时，
  # Okta 才会发出 groups。下方 contractors 策略按 groups 匹配，
  # 因此此处请求了该 scope。
  scopes: [openid, profile, email, offline_access, groups]
  # extra_auth_params: { access_type: offline, prompt: consent }  # Google
  # groups_claim: groups          # Entra 应用角色：使用 `roles`
  # email_claim: email

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}   # openssl rand -base64 32
  # ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}
  # max_connections: 5

# 启用 /v1/organizations/spend_limits（与 Anthropic Admin API 一致）
# 以及 /v1/messages 上按开发者执行的消费限额。省略此部分即可禁用。
# 限额本身通过 admin API 设置，而不是在这里设置。
# admin:
#   write_keys:
#     - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
#   read_keys:
#     - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
#   admin_groups: [platform-finops]
#   blocked_message: 如需提高限额，请访问 https://go.example.com/claude-limits
#   # audit_retention_days: 365
#   # spend_retention_months: 13
#   # identity_retention_days: 90
#   # group_limit_mode: min

# enforcement:
#   fail_closed_on_error: false

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

  # - provider: bedrock
  #   region: us-east-1
  #   auth: {}

  # - provider: anthropicAws
  #   region: us-east-1
  #   workspace_id: wrkspc_...
  #   auth:
  #     api_key: ${ANTHROPIC_AWS_API_KEY}

  # - provider: vertex
  #   region: us-east5
  #   project_id: example-prod
  #   auth: {}

  # - provider: foundry
  #   resource: example-foundry
  #   auth: { use_azure_ad: true }

auto_include_builtin_models: true
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      anthropic: claude-opus-4-8
      # bedrock: us.anthropic.claude-opus-4-8
      # anthropicAws: claude-opus-4-8
      # vertex: claude-opus-4-8
      # foundry: <your-opus-deployment-name>
  - id: claude-sonnet-4-6
    label: Claude Sonnet 4.6
    upstream_model:
      anthropic: claude-sonnet-4-6
  - id: claude-haiku-4-5
    label: Claude Haiku 4.5
    upstream_model:
      anthropic: claude-haiku-4-5

managed:
  policies:
    - match: { groups: [contractors] }
      cli:
        availableModels: [claude-haiku-4-5]
        # 将 Default 选择器选项限制为 availableModels，而不是
        # tier 默认值，以免 contractors 使用默认选项时遇到 400。
        enforceAvailableModels: true
        # allow 会自动批准这些工具，但不会阻止其余工具。
        # 添加 deny 规则以限制工具。
        permissions: { allow: [Read, Grep] }
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        permissions:
          allow: [Read, Grep, Bash, Edit]
          deny: ["WebFetch"]
        env: { HTTP_PROXY: http://proxy.example.com:8080 }

telemetry:
  forward_to:
    - url: https://otel.internal.example.com:4318
      headers:
        Authorization: Bearer ${OTEL_TOKEN}

客户端托管设置

以上内容用于配置网关服务器。开发者计算机如何连接网关则需要在每台设备上单独配置，具体通过 Claude Code 的托管设置完成。网关无法自行推送这些键，因为正是这些键告诉客户端网关位于何处。

对于 CLI，请在各操作系统的 managed-settings.json 中设置以下两个键：

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
}

将该文件部署到每台设备，通常可通过 MDM 平台完成。不同平台使用不同的文件路径：

forceLoginGatewayUrl 和 forceLoginMethod 的 "gateway" 值仅在管理员控制的托管层级中生效。开发者在自己的 ~/.claude/settings.json 中设置这些值不起作用。

相关内容

• Claude 应用网关概览：快速入门和开发者连接
• 部署指南：IdP 设置、容器镜像、Kubernetes 和 Cloud Run，以及运维
• 消费限额：按开发者设置的限额和 Admin API