# 使用 Claude 应用程序网关设置 Claude Code
<a name="coding-agents-claude-code-gateway"></a>

Claude 应用程序网关是一项自托管服务，其位于开发人员的 Claude Code 客户端和模型提供商之间。开发人员使用公司身份提供者（IdP）登录，而不是持有 API 密钥或云凭证。网关持有上游凭证，按 IdP 组强制执行模型访问和托管设置，并将使用情况遥测数据中继到可观测性堆栈（包括 Amazon CloudWatch）。

网关包含在 `claude` 二进制文件中。当您使用配置文件传递 `gateway` 子命令时，运行 Claude Code 的同一个可执行文件会运行网关。

## 关键功能
<a name="coding-agents-claude-code-gateway-capabilities"></a>

Claude 应用程序网关跨多个维度提供集中控制。
+ **凭证**：上游 API 密钥仅存在于基础设施中。开发人员通过 SSO 使用短期令牌进行身份验证。
+ **访问控制**：IdP 组映射到模型允许列表和托管设置策略。
+ **设置传输**：网关向登录的客户端传输托管设置。
+ **遥测**：将 OTLP 指标（令牌计数、模型、用户身份、延迟）路由到收集器。您可以扇出到多个目标（包括 CloudWatch、Datadog、Splunk 和 ClickHouse）。
+ **上游路由**：客户端使用 Anthropic 消息 API。网关通过失效转移针对每个上游进行转换。支持的上游包括 Amazon Bedrock、Amazon 云端 Claude Platform、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Anthropic API。

## 先决条件
<a name="coding-agents-claude-code-gateway-prereqs"></a>

在部署网关之前，请确认满足下面的要求。


| 要求 | 说明 | 
| --- | --- | 
| Claude Code 版本 | v2.1.195 或更高版本 | 
| 身份提供者 | OpenID Connect（OIDC）提供商，例如 Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex | 
| 数据库 | PostgreSQL 14 或更高版本 | 
| 模型上游 | Amazon Bedrock 凭证、Amazon 云端 Claude Platform、Google Cloud、Microsoft Foundry 或 Anthropic API 密钥 | 
| TLS | HTTPS 证书或 TLS 终止入口 | 
| Network | 专用网络地址（RFC 1918、链路本地、CGNAT、IPv6 ULA 或环回） | 
| 运行时 | Linux 适用于生产环境（macOS 仅适用于本地开发） | 

## 部署网关
<a name="coding-agents-claude-code-gateway-quickstart"></a>

以下过程总结了快速入门步骤。有关详细说明，请参阅 [Claude 应用程序网关文档](https://code.claude.com/docs/en/claude-apps-gateway)。

**部署 Claude 应用程序网关**

1. 在 IdP 中注册 OAuth 客户端。将重定向 URI 设置为 `https://{{claude-gateway.your-domain}}/oauth/callback`。

1. 预置 PostgreSQL 数据库（任何 PostgreSQL 14 或更高版本的实例）。网关会在启动时运行架构迁移。

1. 编写 `gateway.yaml` 配置文件。以下示例展示了使用 Amazon Bedrock 作为上游的最低配置。

   ```
   listen:
     host: 0.0.0.0
     port: 8080
     public_url: https://{{claude-gateway.internal.example.com}}
   
   oidc:
     issuer: https://{{login.example.com}}
     client_id: {{0oa1example2}}
     client_secret: ${OIDC_CLIENT_SECRET}
     allowed_email_domains: [{{example.com}}]
     userinfo_fallback: true
   
   session:
     jwt_secret: ${GATEWAY_JWT_SECRET}
     ttl_hours: 1
   
   store:
     postgres_url: ${GATEWAY_POSTGRES_URL}
   
   upstreams:
     - provider: bedrock
       region: {{us-east-1}}
       auth: {}
   
   auto_include_builtin_models: true
   ```

1. 运行网关。您可以使用 Docker Compose，也可以直接运行二进制文件。

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

1. 验证身份验证界面。获取发现文档，请求设备授权，并在网关 URL 上测试浏览器登录。

1. 让开发人员登录以确认端到端连接。

## 将开发人员连接到网关
<a name="coding-agents-claude-code-gateway-connect"></a>

要将开发人员计算机指向网关，请通过移动设备管理（MDM）或配置管理工具分发以下托管设置密钥。

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

分发设置后，每位开发人员都需要完成下面的步骤。

**通过网关登录**

1. 在 Claude Code 中运行 `/login` 命令。

1. 在云网关屏幕上按 Enter。

1. 使用公司 IdP 完成浏览器登录。

登录后，Claude Code 会通过网关路由推理，网关会将遥测导出到配置的目标。

## 将遥测路由到 Amazon CloudWatch
<a name="coding-agents-claude-code-gateway-telemetry"></a>

网关支持 OTLP/HTTP 扇出到多个收集器，并采用带有身份戳记的导出。在 `gateway.yaml` 文件中配置遥测目标。每个目标都可以接收指标、日志或跟踪。

当您将 CloudWatch 配置为遥测目标时，网关会使用来自 IdP 的开发人员身份标记每次导出。指标随用户、团队和组织属性一起到达，因此会填充相同的编程代理洞察控制面板。

有关完整的遥测配置选项，请参阅[配置参考](https://code.claude.com/docs/en/claude-apps-gateway-config)。

## 可用性和限制
<a name="coding-agents-claude-code-gateway-limitations"></a>

下表总结了网关支持的内容和当前限制。


| Item | Status | 
| --- | --- | 
| 支持的上游 | Amazon Bedrock、Amazon 云端 Claude Platform、Google Cloud 的 Agent Platform、Microsoft Foundry、Anthropic API | 
| 支持的 IdP | Okta、Microsoft Entra ID、Google Workspace、Keycloak、Dex 以及其他符合 OIDC 标准的提供商 | 
| 遥测协议 | OTLP/HTTP，可扇出到多个目标 | 
| 运行时 | Linux 用于生产部署。macOS 仅支持本地开发。 | 
| 最低 Claude Code 版本 | v2.1.195 | 

## 后续步骤
<a name="coding-agents-claude-code-gateway-next"></a>

请使用下面的资源获取详细的部署说明、配置选项和操作指导。
+ [Claude 应用程序网关文档](https://code.claude.com/docs/en/claude-apps-gateway)：完整的设置指南，包括 Docker Compose 模板和 IdP 注册演练。
+ [配置参考](https://code.claude.com/docs/en/claude-apps-gateway-config)：所有 `gateway.yaml` 选项的完整参考，包括遥测目标、上游路由和访问策略。
+ [部署指南](https://code.claude.com/docs/en/claude-apps-gateway-deploy)：生产部署模式、扩展和运营最佳实践。

在网关向 CloudWatch 发送指标后，请按照 [查看控制面板](coding-agents-insights.md#coding-agents-insights-view) 中所述查看控制面板。