Documentation 2026-10-06 23:59 UTC to 2026-10-07 03:58 UTC

64</Note>64</Note>

65 65 

66<h3 id="prerequisites">66<h3 id="prerequisites">

67 前置条件67 前提条件

68</h3>68</h3>

69 69 

70在开始之前，请准备好以下内容：70在开始之前，请准备好以下内容：

73| - | - |73| - | - |

74| Claude Code v2.1.195 或更高版本 | `claude gateway` 子命令和网关登录流在 v2.1.195 中发布。早期的公开版本不包含它们。运行网关服务器的机器和每个开发人员的机器都必须是 v2.1.195 或更高版本；运行 `claude update` 获取最新版本。[Claude Platform on AWS 上游](/docs/zh-CN/claude-apps-gateway-config#claude-platform-on-aws)在网关服务器上需要 Claude Code v2.1.198 或更高版本。 |74| Claude Code v2.1.195 或更高版本 | `claude gateway` 子命令和网关登录流在 v2.1.195 中发布。早期的公开版本不包含它们。运行网关服务器的机器和每个开发人员的机器都必须是 v2.1.195 或更高版本；运行 `claude update` 获取最新版本。[Claude Platform on AWS 上游](/docs/zh-CN/claude-apps-gateway-config#claude-platform-on-aws)在网关服务器上需要 Claude Code v2.1.198 或更高版本。 |

75| OpenID Connect (OIDC) 身份提供商 | Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex，或任何其他符合 OIDC 的 IdP，如 PingFederate。网关针对它运行标准 OIDC 发现和授权代码流。不支持 SAML 和 LDAP。 |75| OpenID Connect (OIDC) 身份提供商 | Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex，或任何其他符合 OIDC 的 IdP，如 PingFederate。网关针对它运行标准 OIDC 发现和授权代码流。不支持 SAML 和 LDAP。 |

76| PostgreSQL 14 或更高版本 | 支持设备登录流，其中浏览器回调写入，轮询 CLI 读取，加上速率限制计数器。任何托管 Postgres 都可以，包括最小层级。在没有配置支出限制的情况下，网关存储几 KB 的短期身份验证状态；使用[支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits)，它还保存应备份的持久支出、审计和身份表。建议通过 `?sslmode=require` 使用 TLS。 |76| PostgreSQL 11 或更高版本 | 支持设备登录流和速率限制计数器。托管 PostgreSQL 服务均可使用，包括最小层级；请参阅[支持哪些数据库](/docs/zh-CN/claude-apps-gateway-deploy#postgres)。使用[支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits)时，它还保存应备份的持久支出、审计和身份表。建议通过 `?sslmode=require` 使用 TLS。PostgreSQL 11、12 和 13 要求网关服务器上的 Claude Code 为 v2.1.290 或更高版本。PostgreSQL 项目已不再维护这些版本，因此请尽可能使用更新的版本。 |

77| 模型上游 | Amazon Bedrock 凭证、Claude Platform on AWS 凭证、Google Cloud 凭证、Microsoft Foundry 资源或 Anthropic API 密钥。支持多个上游和故障转移。 |77| 模型上游 | Amazon Bedrock 凭据、Claude Platform on AWS 凭据、Google Cloud 凭据、Microsoft Foundry 资源或 Anthropic API 密钥。支持多个上游和故障转移。 |

78| HTTPS | 网关必须可从开发人员笔记本电脑和用于登录的任何浏览器通过 `https://` 访问；网关在同一侦听器上提供设备验证页面。通过 `listen.tls` 提供 TLS 证书，或在 TLS 终止入口后运行并设置 `listen.public_url` 为外部源，两种情况都是如此。纯 `http://` 源仅在网关主机是环回时接受：`localhost`、`127.0.0.1` 或 `::1`。 |78| HTTPS | 网关必须可从开发人员笔记本电脑和用于登录的任何浏览器通过 `https://` 访问；网关在同一侦听器上提供设备验证页面。通过 `listen.tls` 提供 TLS 证书，或在 TLS 终止入口后运行，两种情况下都要将 `listen.public_url` 设置为外部源。在 `/login` 处，Claude Code 仅在网关主机是环回时才接受纯 `http://` 源：`localhost`、`127.0.0.1` 或 `::1`。 |

79| 私有网络地址 | 在 `/login` 处，Claude Code 要求网关的主机名或 IP 地址仅解析为私有地址：RFC 1918、链路本地、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7` 或环回。对于您托管的网关，任何公共地址都被拒绝；请参阅部署指南中的[威胁模型](/docs/zh-CN/claude-apps-gateway-deploy#threat-model-summary)。如果开发人员机器通过公司代理路由 HTTPS，登录还要求代理主机解析为私有地址；如果不是，将网关主机添加到 `NO_PROXY`，以便 CLI 直接连接。如果您的内部网络使用您的组织拥有的公共 IPv4 空间编号，[声明这些块](#allow-a-gateway-on-public-address-space-you-own)，以便 `/login` 接受那里的网关。 |79| 私有网络地址 | 在 `/login` 处，Claude Code 要求网关的主机名或 IP 地址仅解析为私有地址：RFC 1918、链路本地、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7` 或环回。对于您托管的网关，任何不在您所声明地址块内的公共地址都会被拒绝；请参阅部署指南中的[威胁模型](/docs/zh-CN/claude-apps-gateway-deploy#threat-model-summary)。如果开发人员机器通过公司代理路由 HTTPS，登录还要求代理主机解析为私有地址；如果不是，将网关主机添加到 `NO_PROXY`，以便 CLI 直接连接。如果您的内部网络使用您的组织拥有的公共 IPv4 空间编号，[声明这些块](#allow-a-gateway-on-public-address-space-you-own)，以便 `/login` 接受那里的网关。 |

80| Linux 运行时 | 网关服务器仅在本机 Linux 二进制文件上运行。macOS 适用于本地开发。Windows 不支持作为服务器平台。 |80| Linux 运行时 | 网关服务器仅在本机 Linux 二进制文件上运行。macOS 适用于本地开发。Windows 不支持作为服务器平台。 |

81 81 

82<h3 id="steps">82<h3 id="steps">

89 </Step>89 </Step>

90 90 

91 <Step title="配置 PostgreSQL 数据库">91 <Step title="配置 PostgreSQL 数据库">

92 任何 Postgres 14 或更高版本都可以，包括最小的托管层级。网关在启动时运行自己的架构迁移，因此数据库角色需要创建和修改表的权限；请参阅 [`store`](/docs/zh-CN/claude-apps-gateway-config#store)。92 使用 PostgreSQL 11 或更高版本。最小的托管层级就足够了。网关在启动时运行自己的 schema 迁移，因此数据库角色需要创建和修改表的权限；请参阅 [`store`](/docs/zh-CN/claude-apps-gateway-config#store)。

93 </Step>93 </Step>

94 94 

95 <Step title="编写 gateway.yaml">95 <Step title="编写 gateway.yaml">

120 upstreams:120 upstreams:

121 - provider: bedrock121 - provider: bedrock

122 region: us-east-1122 region: us-east-1

123 auth: {} # 空：AWS 默认凭证链123 auth: {} # 空：AWS 默认凭据链

124 # (IRSA, EC2/ECS task role, env vars, ~/.aws)124 # (IRSA, EC2/ECS task role, env vars, ~/.aws)

125 125 

126 # 模型会自动按上游转换。内置目录126 # 模型会自动按上游转换。内置目录

133 此配置足以使用默认 Amazon Bedrock 模型目录进行工作登录循环。运行后，通过 [`managed.policies`](/docs/zh-CN/claude-apps-gateway-config#managed) 添加按组 RBAC 和托管设置，通过 [`telemetry`](/docs/zh-CN/claude-apps-gateway-config#telemetry) 添加遥测扇出，以及通过 [`models`](/docs/zh-CN/claude-apps-gateway-config#models) 添加多上游故障转移、预配置吞吐量 ARN 或非美国地区。133 此配置足以使用默认 Amazon Bedrock 模型目录进行工作登录循环。运行后，通过 [`managed.policies`](/docs/zh-CN/claude-apps-gateway-config#managed) 添加按组 RBAC 和托管设置，通过 [`telemetry`](/docs/zh-CN/claude-apps-gateway-config#telemetry) 添加遥测扇出，以及通过 [`models`](/docs/zh-CN/claude-apps-gateway-config#models) 添加多上游故障转移、预配置吞吐量 ARN 或非美国地区。

134 134 

135 <Note>135 <Note>

136 Amazon Bedrock 上游需要一个 AWS 主体，具有对 `inference-profile/us.anthropic.*` ARN 和底层 `foundation-model/anthropic.*` ARN 的 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream`，以及在 Bedrock 控制台的模型目录中为该账户提交的 Anthropic 一次性用例表单。使用 EKS 上的 IRSA、ECS 任务角色或 EC2 实例配置文件提供凭证，而不是静态密钥。[`upstreams` 参考](/docs/zh-CN/claude-apps-gateway-config#upstreams)具有完整的 IAM 详情、跨云凭证矩阵以及其他提供商的 `auth` 块。136 Amazon Bedrock 上游需要一个 AWS 主体，具有对 `inference-profile/us.anthropic.*` ARN 和底层 `foundation-model/anthropic.*` ARN 的 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream` 权限。它还需要在 Bedrock 控制台的模型目录中为该账户提交 Anthropic 的一次性用例表单。

137 

138 使用 EKS 上的 IRSA、ECS 任务角色或 EC2 实例配置文件提供凭据，而不是静态密钥。[`upstreams` 参考](/docs/zh-CN/claude-apps-gateway-config#upstreams)具有完整的 IAM 详情、跨云凭据矩阵以及其他提供商的 `auth` 块。

137 </Note>139 </Note>

138 </Step>140 </Step>

139 141 

150 OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}152 OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}

151 GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}153 GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}

152 GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway154 GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway

153 # AWS 凭证：在生产中，省略这些并使用实例155 # AWS 凭据：在生产中，省略这些并使用实例

154 # 角色。对于本地 Compose 测试，传递您自己的：156 # 角色。对于本地 Compose 测试，传递您自己的：

155 AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}157 AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}

156 AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}158 AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}

168 volumes: { pgdata: }170 volumes: { pgdata: }

169 ```171 ```

170 172 

171 网关是一个单一的 Linux 二进制文件，读取配置，连接到 Postgres 并应用其架构迁移，针对您的 IdP 运行 OIDC 发现，构建上游客户端，并开始侦听。启动对配置、Postgres 连接、OIDC 发现和上游客户端构造是失败关闭的。如果其中任何一个无法访问或配置错误，网关会以错误退出，而不是以降级状态提供流量。173 网关是一个单一的 Linux 二进制文件，读取配置，连接到 Postgres 并应用其 schema 迁移，针对您的 IdP 运行 OIDC 发现，构建上游客户端，并开始侦听。

174 

175 启动对配置、Postgres 连接、OIDC 发现和上游客户端构造是失败关闭的。如果其中任何一个无法访问或配置错误，网关会以错误退出，而不是以降级状态提供流量。

172 176 

173 成功启动不会验证推理路径，因为 Amazon Bedrock 和 Google Cloud 的 Agent Platform 实例凭证在第一个请求时解析，而不是在启动时。177 成功启动不会验证推理路径，因为 Amazon Bedrock 和 Google Cloud 的 Agent Platform 实例凭据在第一个请求时解析，而不是在启动时。

174 178 

175 监视 stderr 以获取启动序列。日志行使用格式 `[gateway] <timestamp> <level> <message>`，审计事件是带有 `evt` 字段的单行 JSON，启动横幅（下面省略）在迁移和侦听行之间打印。新数据库每个架构迁移打印一行 `migration N applied`；已迁移的数据库不打印任何内容。您应该按顺序看到：179 监视 stderr 以获取启动序列。日志行使用格式 `[gateway] <timestamp> <level> <message>`，审计事件是带有 `evt` 字段的单行 JSON，启动横幅（下面省略）在迁移和侦听行之间打印。新数据库每个 schema 迁移打印一行 `migration N applied`；已迁移的数据库不打印任何内容。您应该按顺序看到：

176 180 

177 ```text theme={null}181 ```text theme={null}

178 {"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}182 {"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}

190 * 无法访问的 Postgres194 * 无法访问的 Postgres

191 * 没有 DDL 权限的 Postgres 角色195 * 没有 DDL 权限的 Postgres 角色

192 * 无法访问或无效的 OIDC 发现文档196 * 无法访问或无效的 OIDC 发现文档

193 * 配置架构违规，带有违规字段路径197 * 配置 schema 违规，带有违规字段路径

194 198 

195 修复它并重新启动。199 修复它并重新启动。

196 200 

249 </Step>253 </Step>

250 254 

251 <Step title="登录开发人员">255 <Step title="登录开发人员">

252 最后一步发生在开发人员机器上，而不是服务器上。在该机器的[托管设置文件](/docs/zh-CN/managed-settings#delivery-mechanisms)中将 `forceLoginMethod` 设置为 `"gateway"` 并将 `forceLoginGatewayUrl` 设置为您的网关的 `public_url`，然后运行 `/login`，在**Cloud gateway** 屏幕上按 Enter，并完成浏览器登录。下面的[设置网关 URL](#set-the-gateway-url)涵盖大规模分发两个密钥。256 最后一步发生在开发人员机器上，而不是服务器上。在该机器的[托管设置文件](/docs/zh-CN/managed-settings#delivery-mechanisms)中将 `forceLoginMethod` 设置为 `"gateway"` 并将 `forceLoginGatewayUrl` 设置为您的网关的 `public_url`，然后运行 `/login`，在**Cloud gateway** 屏幕上按 Enter，并完成浏览器登录。下面的[设置网关 URL](#set-the-gateway-url)介绍如何将这两个键分发到每台开发人员机器。

253 </Step>257 </Step>

254</Steps>258</Steps>

255 259 

158网关在启动时读取一次密钥和证书，因此更改后的文件仅在重启后生效。请按以下顺序轮换，以确保任何令牌请求都不会出示 IdP 中不存在的证书：158网关在启动时读取一次密钥和证书，因此更改后的文件仅在重启后生效。请按以下顺序轮换，以确保任何令牌请求都不会出示 IdP 中不存在的证书：

159 159 

1601. 将新证书与旧证书一起上传到 IdP。1601. 将新证书与旧证书一起上传到 IdP。

1612. 替换 `gateway.yaml` 加载的密钥和证书文件，然后重启网关。1612. 替换 `gateway.yaml` 加载的密钥和证书文件，然后重启网关。如果您运行多个副本，可以使用[滚动重启](/docs/zh-CN/claude-apps-gateway-deploy#upgrades)，因为在您删除旧证书之前，IdP 同时拥有这两个证书。

1623. 从 IdP 中删除旧证书。1623. 在每个副本都重启之后，从 IdP 中删除旧证书。

163 163 

164<h4 id="idp-requests-through-a-forward-proxy">164<h4 id="idp-requests-through-a-forward-proxy">

165 通过前向代理的 IdP 请求165 通过前向代理的 IdP 请求

227 227 

228| 字段 | 必需 | 描述 |228| 字段 | 必需 | 描述 |

229| - | - | - |229| - | - | - |

230| `postgres_url` | 是 | `postgres://` 或 `postgresql://` URL。必需：设备授权集合点，浏览器回调写入和轮询 CLI 读取，需要跨副本状态。网关在启动和升级时运行自己的 schema 迁移，因此角色需要在目标 schema 上创建和更改表的权限。请参阅[升级](/docs/zh-CN/claude-apps-gateway-deploy#upgrades)和 [Postgres](/docs/zh-CN/claude-apps-gateway-deploy#postgres)。 |230| `postgres_url` | 是 | `postgres://` 或 `postgresql://` URL，只能包含一个主机，不能是逗号分隔的列表。网关在启动和升级时运行自己的 schema 迁移，因此角色需要在目标 schema 上创建和更改表的权限。请参阅[升级](/docs/zh-CN/claude-apps-gateway-deploy#upgrades)和 [Postgres](/docs/zh-CN/claude-apps-gateway-deploy#postgres)。 |

231| `username` | 否 | 覆盖 `postgres_url` 中的用户 |231| `username` | 否 | 覆盖 `postgres_url` 中的用户 |

232| `password` | 否 | 数据库凭据。在此设置而不是在 `postgres_url` 中，以便凭据保持在 URL 之外。接受任何字符并优先于 URL 凭据。 |232| `password` | 否 | 数据库凭据。在此设置而不是在 `postgres_url` 中，以便凭据保持在 URL 之外。接受任何字符并优先于 URL 凭据。 |

233| `max_connections` | 否 | 每个副本的 Postgres 连接池大小。默认 `5`，保守且对共享数据库友好。启用[支出限制](#admin)后，热路径每个推理请求执行几个操作，因此在负载下为专用数据库提高它，并保持副本 × 此值低于数据库的 `max_connections`。 |233| `max_connections` | 否 | 每个副本的 Postgres 连接池大小。默认 `5`，保守且对共享数据库友好。启用[支出限制](#admin)后，热路径每个推理请求执行几个操作，因此在负载下为专用数据库提高它，并保持副本 × 此值低于数据库的 `max_connections`。 |

249 Postgres249 Postgres

250</h3>250</h3>

251 251 

252网关将其状态存储在 PostgreSQL 数据库中：

253 

254* **数据库**：PostgreSQL 本身，自托管或托管均可，版本为[最低版本](/docs/zh-CN/claude-apps-gateway#prerequisites)或更高。仅实现 Postgres 协议的数据库（例如分布式 SQL 数据库）不受支持。

255* **地址**：`store.postgres_url` 接受一个主机。如果数据库有多个节点，请使用位于它们前面的地址，例如您的托管服务的端点、负载均衡器或虚拟 IP。设置一个比故障转移所需时间更长的[就绪宽限期](#readiness-grace-period)。

256 

252网关持有五个数据表加上一个 `_migrations` 表，全部由其启动时迁移创建：257网关持有五个数据表加上一个 `_migrations` 表，全部由其启动时迁移创建：

253 258 

254| 表 | 内容 | 保留 |259| 表 | 内容 | 保留 |

396| CLI `/login`：`Could not resolve the configured HTTP proxy` | `HTTPS_PROXY` 或 `HTTP_PROXY` 中的主机名无法从开发者的机器解析，通常是因为它未连接到公司网络 | 让开发者连接到您的网络或 VPN 并重试，或修复代理 URL |401| CLI `/login`：`Could not resolve the configured HTTP proxy` | `HTTPS_PROXY` 或 `HTTP_PROXY` 中的主机名无法从开发者的机器解析，通常是因为它未连接到公司网络 | 让开发者连接到您的网络或 VPN 并重试，或修复代理 URL |

397| CLI `/login`：`Could not resolve gateway host <host>` | 机器无法解析网关的内部 DNS 名称，通常是因为它不在公司网络上 | 让开发者连接到您的网络或 VPN，然后重试 `/login` |402| CLI `/login`：`Could not resolve gateway host <host>` | 机器无法解析网关的内部 DNS 名称，通常是因为它不在公司网络上 | 让开发者连接到您的网络或 VPN，然后重试 `/login` |

398| 启动退出，显示配置验证错误，命名 `store.postgres_url` | 未配置 Postgres；网关需要 Postgres | 设置 `store.postgres_url`。对于本地开发，使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |403| 启动退出，显示配置验证错误，命名 `store.postgres_url` | 未配置 Postgres；网关需要 Postgres | 设置 `store.postgres_url`。对于本地开发，使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |

404| 启动退出：`store.postgres_url in <path> is not a URL the gateway can read`，或在 v2.1.290 之前仅显示 `Invalid URL` 或 `URI error` | 无法解析该 URL，例如因为它列出了多个主机，或其密码包含未编码的 `/`、`?`、`#` 或 `%` | 仅指定[一个主机](#postgres)，并将密码移到 [`store.password`](/docs/zh-CN/claude-apps-gateway-config#store) 中 |

399| 启动退出：`requires the native binary` | 在 Node 下运行而不是本地二进制 | 使用[独立安装方法](/docs/zh-CN/setup)之一安装 Claude Code |405| 启动退出：`requires the native binary` | 在 Node 下运行而不是本地二进制 | 使用[独立安装方法](/docs/zh-CN/setup)之一安装 Claude Code |

400| 启动退出，在 `config.load` 后显示 OIDC 发现错误 | `oidc.issuer` 无法访问，或 TLS 链不受信任 | 检查发行者是否可从 pod 访问并提供 `/.well-known/openid-configuration`。为私有 PKI 设置 `ca_cert_pem`。如果 pod 仅通过前向代理到达 IdP，设置 [`oidc.use_proxy: true`](/docs/zh-CN/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)；在 v2.1.227 之前的版本上，改为给 pod 一条到 IdP 每个端点的直接路由。如果 pod 也无法解析 IdP 的主机名，或代理拒绝 `CONNECT` 到 IP 地址，请参阅[仅代理出口](/docs/zh-CN/claude-apps-gateway-config#proxy-only-egress)，这需要 v2.1.277 或更高版本。 |406| 启动退出，在 `config.load` 后显示 OIDC 发现错误 | `oidc.issuer` 无法访问，或 TLS 链不受信任 | 检查发行者是否可从 pod 访问并提供 `/.well-known/openid-configuration`。为私有 PKI 设置 `ca_cert_pem`。如果 pod 仅通过前向代理到达 IdP，设置 [`oidc.use_proxy: true`](/docs/zh-CN/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)；在 v2.1.227 之前的版本上，改为给 pod 一条到 IdP 每个端点的直接路由。如果 pod 也无法解析 IdP 的主机名，或代理拒绝 `CONNECT` 到 IP 地址，请参阅[仅代理出口](/docs/zh-CN/claude-apps-gateway-config#proxy-only-egress)，这需要 v2.1.277 或更高版本。 |

401| 启动退出，显示 Postgres 权限错误 | 数据库角色在其 schema 上缺少 DDL 权限 | 授予角色对网关 schema 的 `CREATE` 权限，以便它可以在启动时创建和修改其表 |407| 启动退出，显示 Postgres 权限错误 | 数据库角色在其 schema 上缺少 DDL 权限 | 授予角色对网关 schema 的 `CREATE` 权限，以便它可以在启动时创建和修改其表 |

402| 日志：`could not connect to Postgres at boot, attempt 1 of 3` | 当网关启动时数据库无法访问，例如在网络仍在启动的冷实例上 | 如果网关随后完成启动，无需采取任何措施。当数据库无法访问时，网关在退出前尝试连接三次，间隔两秒。如果它以 `could not connect to Postgres` 退出，检查 `store.postgres_url` 和到数据库的网络路径。如果尝试超时而不是被拒绝，提高 [`store.connect_timeout_seconds`](/docs/zh-CN/claude-apps-gateway-config#store) 以给每个尝试更长的时间。 |408| 日志：`could not connect to Postgres at boot, attempt 1 of 3` | 当网关启动时数据库无法访问，例如在网络仍在启动的冷实例上 | 如果网关随后完成启动，无需采取任何措施。当数据库无法访问时，网关在退出前尝试连接三次，间隔两秒。如果它以 `could not connect to Postgres` 退出，检查 `store.postgres_url`（包括它是否只指定了一个主机）以及到数据库的网络路径。如果尝试超时而不是被拒绝，提高 [`store.connect_timeout_seconds`](/docs/zh-CN/claude-apps-gateway-config#store) 以给每个尝试更长的时间。 |

403| `/oauth/callback` 显示"Sign-in could not be completed" | 电子邮件域被拒绝、id\_token 验证失败，或 `email_verified` 显式为 `false`，网关总是拒绝且无覆盖 | 检查 `allowed_email_domains` 和 IdP 是否返回已验证的 `email` 声明。对于 `email_verified: false`，修复 IdP 端验证。如果您的 IdP 在不同的声明名称下发出电子邮件，设置 `oidc.email_claim`。 |409| `/oauth/callback` 显示"Sign-in could not be completed" | 电子邮件域被拒绝、id\_token 验证失败，或 `email_verified` 显式为 `false`，网关总是拒绝且无覆盖 | 检查 `allowed_email_domains` 和 IdP 是否返回已验证的 `email` 声明。对于 `email_verified: false`，修复 IdP 端验证。如果您的 IdP 在不同的声明名称下发出电子邮件，设置 `oidc.email_claim`。 |

404| 日志：`token exchange failed request_id=<id>: id_token missing email claim` | IdP 默认不在 id\_token 中包含 `email`。此拒绝仅在设置 `allowed_email_domains` 时触发；没有它，缺少的电子邮件会创建没有电子邮件的会话 | 配置 IdP 在 id\_token 中发出 `email`。Okta：将 `email` 添加到自定义授权服务器的 ID 令牌声明。Entra：在应用注册上添加 `email` 作为可选声明。PingFederate：启用发出 `email` 的 OpenID Connect 策略。如果 IdP 从 userinfo 端点提供 `email` 但不会在 id\_token 中包含它，例如 Okta 组织授权服务器，设置 `oidc.userinfo_fallback: true`。 |410| 日志：`token exchange failed request_id=<id>: id_token missing email claim` | IdP 默认不在 id\_token 中包含 `email`。此拒绝仅在设置 `allowed_email_domains` 时触发；没有它，缺少的电子邮件会创建没有电子邮件的会话 | 配置 IdP 在 id\_token 中发出 `email`。Okta：将 `email` 添加到自定义授权服务器的 ID 令牌声明。Entra：在应用注册上添加 `email` 作为可选声明。PingFederate：启用发出 `email` 的 OpenID Connect 策略。如果 IdP 从 userinfo 端点提供 `email` 但不会在 id\_token 中包含它，例如 Okta 组织授权服务器，设置 `oidc.userinfo_fallback: true`。 |

405| 日志：`refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`，开发者每 `session.ttl_hours` 看到 `Cloud gateway session expired` | IdP 接受了刷新令牌但没有随之返回 id\_token，所以网关询问了 IdP 的 userinfo 端点以获取用户的声明。IdP 在那里拒绝了刷新的访问令牌。网关回答 `temporarily_unavailable`，所以 Claude Code 保留刷新令牌但无法续订会话。v2.1.260 之前的网关版本记录相同的行但没有 `(at …)` 详情。 | 设置 [`oidc.scope_on_refresh: true`](/docs/zh-CN/claude-apps-gateway-config#oidc)，在网关 v2.1.260 或更高版本中可用，以便刷新请求再次请求 `openid`。某些 IdP（如 Okta）仅在被要求时在刷新时返回 id\_token。在 PingFederate 上，改为在 **Applications > OAuth > OpenID Connect Policy Management** 下启用 **Return ID Token On Refresh Grant**。该设置项不会改变 PingFederate 的行为。对于仍然省略它的其他 IdP，检查 userinfo 端点是否接受由刷新发出的访问令牌。作为临时措施，提高 [`session.ttl_hours`](/docs/zh-CN/claude-apps-gateway-config#session)。请参阅[身份提供者设置](#identity-provider-setup)了解取消配置权衡。 |411| 日志：`refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`，开发者每 `session.ttl_hours` 看到 `Cloud gateway session expired` | IdP 接受了刷新令牌但没有随之返回 id\_token，所以网关询问了 IdP 的 userinfo 端点以获取用户的声明。IdP 在那里拒绝了刷新的访问令牌。网关回答 `temporarily_unavailable`，所以 Claude Code 保留刷新令牌但无法续订会话。v2.1.260 之前的网关版本记录相同的行但没有 `(at …)` 详情。 | 设置 [`oidc.scope_on_refresh: true`](/docs/zh-CN/claude-apps-gateway-config#oidc)，在网关 v2.1.260 或更高版本中可用，以便刷新请求再次请求 `openid`。某些 IdP（如 Okta）仅在被要求时在刷新时返回 id\_token。在 PingFederate 上，改为在 **Applications > OAuth > OpenID Connect Policy Management** 下启用 **Return ID Token On Refresh Grant**。该设置项不会改变 PingFederate 的行为。对于仍然省略它的其他 IdP，检查 userinfo 端点是否接受由刷新发出的访问令牌。作为临时措施，提高 [`session.ttl_hours`](/docs/zh-CN/claude-apps-gateway-config#session)。请参阅[身份提供者设置](#identity-provider-setup)了解取消配置权衡。 |

136 --policy-name bedrock-invoke --policy-document file://bedrock-invoke.json136 --policy-name bedrock-invoke --policy-document file://bedrock-invoke.json

137 ```137 ```

138 138 

139 ECS 还需要一个执行角色，ECS 代理本身使用它从 ECR 拉取镜像并注入稍后创建的 Secrets Manager 值。它与 gateway 的 AWS SDK 在运行时使用的任务角色分开：139 ECS 还需要一个执行角色，ECS Agent 本身使用它从 ECR 拉取镜像并注入稍后创建的 Secrets Manager 值。它与 gateway 的 AWS SDK 在运行时使用的任务角色分开：

140 140 

141 ```bash theme={null}141 ```bash theme={null}

142 aws iam create-role --role-name claude-gateway-execution \142 aws iam create-role --role-name claude-gateway-execution \

169 </Step>169 </Step>

170 170 

171 <Step title="配置 Amazon RDS for PostgreSQL">171 <Step title="配置 Amazon RDS for PostgreSQL">

172 该实例在私有子网中运行，没有公共地址，存储加密打开。引擎版本固定为 Postgres 16，满足 gateway 支持的 PostgreSQL 14 下限，并保证下面的参数组系列与实例匹配。172 该实例在私有子网中运行 Postgres 16，没有公共地址，存储加密打开。

173 173 

174 首先，创建将数据库放在私有子网中的子网组，以及具有 `rds.force_ssl=1` 的参数组，以便服务器拒绝明文连接。引擎版本固定一次，因为参数组的系列必须与实例运行的引擎主版本匹配：174 首先，创建将数据库放在私有子网中的子网组，以及具有 `rds.force_ssl=1` 的参数组，以便服务器拒绝明文连接。引擎版本固定一次，因为参数组的系列必须与实例运行的引擎主版本匹配：

175 175 

218 </Step>218 </Step>

219 219 

220 <Step title="编写 gateway.yaml">220 <Step title="编写 gateway.yaml">

221 `upstreams` 块使用 `auth: {}` 指向 Bedrock，因此 gateway 通过 ECS 上的任务角色或 EKS 上的 IRSA 角色从 AWS 默认凭证链进行身份验证。有关每个字段，请参阅[配置参考](/docs/zh-CN/claude-apps-gateway-config)。221 `upstreams` 块使用 `auth: {}` 指向 Bedrock，因此 gateway 通过 ECS 上的任务角色或 EKS 上的 IRSA 角色从 AWS 默认凭据链进行身份验证。有关每个字段，请参阅[配置参考](/docs/zh-CN/claude-apps-gateway-config)。

222 222 

223 两个 `listen` 字段描述什么位于 gateway 前面：223 两个 `listen` 字段描述什么位于 gateway 前面：

224 224 

255 255 

256 store:256 store:

257 postgres_url: ${GATEWAY_POSTGRES_URL} # EKS: ${file:/secrets/postgres-url}257 postgres_url: ${GATEWAY_POSTGRES_URL} # EKS: ${file:/secrets/postgres-url}

258 # readiness_grace_seconds: 300 # 通过 RDS 故障转移保持通过健康检查258 # readiness_grace_seconds: 300 # 在 RDS 故障转移期间

259 # 保持通过健康检查

259 260 

260 upstreams:261 upstreams:

261 - provider: bedrock262 - provider: bedrock

262 region: <your-region> # 匹配 $AWS_REGION 以便 IAM263 region: <your-region> # 匹配 $AWS_REGION 以便 IAM

263 # 策略的 ARN 涵盖它264 # 策略的 ARN 涵盖它

264 auth: {} # AWS 默认凭证链：265 auth: {} # AWS 默认凭据链：

265 # ECS 任务角色，或 EKS 上的 IRSA266 # ECS 任务角色，或 EKS 上的 IRSA

266 ```267 ```

267 268 

288 字面 `--secret-string` 参数在每个命令运行时在进程表和审计/EDR 日志中可见。在共享或受监控的主机上，将值放在 `0600` 文件中，改为传递 `--secret-string file://<path>`。bundle 的 `setup.sh` 以相同的方式将机密值保持在进程 argv 之外，将 `0600` 临时文件传递给 `--cli-input-json`。289 字面 `--secret-string` 参数在每个命令运行时在进程表和审计/EDR 日志中可见。在共享或受监控的主机上，将值放在 `0600` 文件中，改为传递 `--secret-string file://<path>`。bundle 的 `setup.sh` 以相同的方式将机密值保持在进程 argv 之外，将 `0600` 临时文件传递给 `--cli-input-json`。

289 </Note>290 </Note>

290 291 

291 与机密不同，`gateway.yaml` 本身不包含机密值，因为每个凭证在启动时通过 [`${VAR}` 或 `${file:...}` 扩展](/docs/zh-CN/claude-apps-gateway-config#secret-expansion)解析。一切如何到达容器因轨道而异：292 与机密不同，`gateway.yaml` 本身不包含机密值，因为每个凭据在启动时通过 [`${VAR}` 或 `${file:...}` 扩展](/docs/zh-CN/claude-apps-gateway-config#secret-expansion)解析。一切如何到达容器因轨道而异：

292 293 

293 * 在 ECS 上，下一步的构建将 `gateway.yaml` 复制到镜像中的 `/etc/claude/gateway.yaml`，任务定义通过其 `secrets` 字段将三个机密作为环境变量注入，因此 YAML 引用 `${GATEWAY_JWT_SECRET}`、`${OIDC_CLIENT_SECRET}` 和 `${GATEWAY_POSTGRES_URL}`。294 * 在 ECS 上，下一步的构建将 `gateway.yaml` 复制到镜像中的 `/etc/claude/gateway.yaml`，任务定义通过其 `secrets` 字段将三个机密作为环境变量注入，因此 YAML 引用 `${GATEWAY_JWT_SECRET}`、`${OIDC_CLIENT_SECRET}` 和 `${GATEWAY_POSTGRES_URL}`。

294 * 在 EKS 上，从 ConfigMap 挂载 `gateway.yaml` 并将机密作为文件挂载在 `/secrets`，引用为 `${file:/secrets/...}`。使用 External Secrets Operator 或 Secrets Store CSI 驱动程序的 AWS 提供程序从 Secrets Manager 获取 Kubernetes Secrets，或使用 `kubectl` 直接创建它们。295 * 在 EKS 上，从 ConfigMap 挂载 `gateway.yaml` 并将机密作为文件挂载在 `/secrets`，引用为 `${file:/secrets/...}`。使用 External Secrets Operator 或 Secrets Store CSI 驱动程序的 AWS 提供程序从 Secrets Manager 获取 Kubernetes Secrets，或使用 `kubectl` 直接创建它们。

311 ENV NODE_EXTRA_CA_CERTS=/etc/claude/rds-global-bundle.pem312 ENV NODE_EXTRA_CA_CERTS=/etc/claude/rds-global-bundle.pem

312 ```313 ```

313 314 

314 创建 ECR 存储库并将 Docker 登录到它。不可变标签意味着部署步骤固定的 `<version>` 标签以后不能被无声地重新指向不同的镜像：315 创建 ECR 仓库并将 Docker 登录到它。不可变标签意味着部署步骤固定的 `<version>` 标签以后不能被无声地重新指向不同的镜像：

315 316 

316 ```bash theme={null}317 ```bash theme={null}

317 aws ecr create-repository --repository-name claude-gateway \318 aws ecr create-repository --repository-name claude-gateway \

424 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"425 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"

425 ```426 ```

426 427 

427 60 秒的宽限期给冷任务时间拉取镜像、连接到存储并在 ECS 开始计算针对部署的失败之前回答其第一个健康检查。目标组对 `GET /readyz` 的健康检查验证存储是否可达，因此无法到达 Postgres 的任务永远不会进入轮换。要通过短数据库中断（例如 RDS 故障转移）保持任务通过检查，请按照[中断行为](/docs/zh-CN/claude-apps-gateway-deploy#outage-behavior)中所述设置 `store.readiness_grace_seconds`，其中也涵盖了 `/healthz` 替代方案。428 60 秒的宽限期给冷任务时间拉取镜像、连接到存储并在 ECS 开始计算针对部署的失败之前回答其第一个健康检查。

429 

430 目标组对 `GET /readyz` 的健康检查验证存储是否可达，因此无法到达 Postgres 的任务永远不会进入轮换。要通过短数据库中断（例如 RDS 故障转移）保持任务通过检查，请按照[中断行为](/docs/zh-CN/claude-apps-gateway-deploy#outage-behavior)中所述设置 `store.readiness_grace_seconds`，其中也涵盖了 `/healthz` 替代方案。

428 431 

429 任务在私有子网中运行，没有公共 IP，因此所有出站（到 Bedrock、您的 IdP、Secrets Manager、ECR 和 CloudWatch Logs）都通过 NAT 网关。要将 Bedrock 流量保持在公共路径之外，创建一个 `bedrock-runtime` 接口 VPC 端点并将上游的 `base_url` 指向它，如 [Bedrock 上游参考](/docs/zh-CN/claude-apps-gateway-config#amazon-bedrock)所示；IdP 仍然需要互联网出站。432 任务在私有子网中运行，没有公共 IP，因此所有出站（到 Bedrock、您的 IdP、Secrets Manager、ECR 和 CloudWatch Logs）都通过 NAT 网关。要将 Bedrock 流量保持在公共路径之外，创建一个 `bedrock-runtime` 接口 VPC 端点并将上游的 `base_url` 指向它，如 [Bedrock 上游参考](/docs/zh-CN/claude-apps-gateway-config#amazon-bedrock)所示；IdP 仍然需要互联网出站。

430 433 

431 通过在 Route 53 私有托管区域中为 gateway 的内部 DNS 名称别名到 ALB，并将 `listen.public_url` 设置为该主机名，为开发人员完成私有可解析主机名。ALB 自己的 `*.elb.amazonaws.com` 名称在内部 ALB 上解析为私有地址，但它不能携带您的 ACM 证书，因此使用您自己的名称。434 最后，为开发人员提供一个可私有解析的主机名：在 Route 53 私有托管区域中，将 gateway 的内部 DNS 名称别名到 ALB，并将 `listen.public_url` 设置为该主机名。ALB 自己的 `*.elb.amazonaws.com` 名称在内部 ALB 上解析为私有地址，但它不能携带您的 ACM 证书，因此使用您自己的名称。

432 435 

433 在第一次登录之前，将 OAuth 客户端的授权重定向 URI 更新为 `<public_url>/oauth/callback`。更改 `public_url` 后，在新标签下重建并推送镜像，注册新的任务定义修订版本，然后重新部署。在 ECS 上，该设置位于镜像的嵌入式 `gateway.yaml` 中，gateway 仅从该设置构建其公共源，忽略 `X-Forwarded-Host` 和 `X-Forwarded-Proto`。`X-Forwarded-For` 仅在设置 `listen.trusted_proxies` 时才被遵守用于客户端 IP。436 在第一次登录之前，将 OAuth 客户端的授权重定向 URI 更新为 `<public_url>/oauth/callback`。更改 `public_url` 后，在新标签下重建并推送镜像，注册新的任务定义修订版本，然后重新部署。在 ECS 上，该设置位于镜像的嵌入式 `gateway.yaml` 中，gateway 仅从该设置构建其公共源，忽略 `X-Forwarded-Host` 和 `X-Forwarded-Proto`。`X-Forwarded-For` 仅在设置 `listen.trusted_proxies` 时才被遵守用于客户端 IP。

434 </Tab>437 </Tab>

436 <Tab title="EKS">439 <Tab title="EKS">

437 此轨道需要本地安装 `kubectl` 和 `eksctl`，以及具有 IAM OIDC 提供程序和已安装 AWS Load Balancer Controller 的现有 EKS 集群。集群必须在 `$VPC_ID` 上，以便 pod 可以到达 RDS 私有端点，`claude-gateway-db` 安全组必须允许集群的 pod 或节点安全组而不是 `$GW_SG`。440 此轨道需要本地安装 `kubectl` 和 `eksctl`，以及具有 IAM OIDC 提供程序和已安装 AWS Load Balancer Controller 的现有 EKS 集群。集群必须在 `$VPC_ID` 上，以便 pod 可以到达 RDS 私有端点，`claude-gateway-db` 安全组必须允许集群的 pod 或节点安全组而不是 `$GW_SG`。

438 441 

439 在 EKS 上，gateway 通过 IRSA 而不是 ECS 角色获得其 Bedrock 凭证。IAM 步骤中的 `ecs-tasks.amazonaws.com` 信任策略在这里不适用；IRSA 需要一个信任策略在集群的 OIDC 提供程序上联合的角色，范围为 `system:serviceaccount:claude-gateway:gateway`。`eksctl create iamserviceaccount` 在一个步骤中创建该角色、附加策略并使用角色 ARN 注解 Kubernetes 服务账户。将 IAM 步骤中的两个策略文档转换为它可以附加的托管策略：442 在 EKS 上，gateway 通过 IRSA 而不是 ECS 角色获得其 Bedrock 凭据。IAM 步骤中的 `ecs-tasks.amazonaws.com` 信任策略在这里不适用；IRSA 需要一个信任策略在集群的 OIDC 提供程序上联合的角色，范围为 `system:serviceaccount:claude-gateway:gateway`。`eksctl create iamserviceaccount` 在一个步骤中创建该角色、附加策略并使用角色 ARN 注解 Kubernetes 服务账户。将 IAM 步骤中的两个策略文档转换为它可以附加的托管策略：

440 443 

441 ```bash theme={null}444 ```bash theme={null}

442 BEDROCK_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-bedrock-invoke \445 BEDROCK_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-bedrock-invoke \

475 </Step>478 </Step>

476 479 

477 <Step title="将 gateway URL 推送到开发人员机器">480 <Step title="将 gateway URL 推送到开发人员机器">

478 gateway 现在正在运行，但开发人员在通过 MDM 部署的[托管设置文件](/docs/zh-CN/claude-apps-gateway#set-the-gateway-url)中设置 `forceLoginMethod` 和 `forceLoginGatewayUrl` 之前无法从 `/login` 到达它。开发人员无法手动在登录选择器中选择 gateway 选项。481 gateway 现在正在运行，但在 gateway URL 出现在开发人员的机器上之前，开发人员无法从 `/login` 到达它。在通过 MDM 部署到每台设备的[托管设置文件](/docs/zh-CN/claude-apps-gateway#set-the-gateway-url)中设置 `forceLoginMethod` 和 `forceLoginGatewayUrl`。登录选择器中没有可供开发人员手动选择的 gateway 选项。

479 </Step>482 </Step>

480</Steps>483</Steps>

481 484 

83* 终端：`claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（当名称与一个会话匹配时），不带 `-p`。Claude Code 恢复会话所在的权限模式，除了表中的情况。传递 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆盖恢复的模式。83* 终端：`claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（当名称与一个会话匹配时），不带 `-p`。Claude Code 恢复会话所在的权限模式，除了表中的情况。传递 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆盖恢复的模式。

84* 非交互式：`claude -p --resume` 或 `claude -p --continue`。Claude Code 在新 `claude -p` 运行会启动的权限模式中启动运行，除了在[下面的条件](#resume-in-plan-mode-with-p)下以计划模式结束的会话在计划模式中恢复。84* 非交互式：`claude -p --resume` 或 `claude -p --continue`。Claude Code 在新 `claude -p` 运行会启动的权限模式中启动运行，除了在[下面的条件](#resume-in-plan-mode-with-p)下以计划模式结束的会话在计划模式中恢复。

85* VS Code：扩展的对话面板。该表仅涵盖以计划模式结束的对话；对于其余部分，请参阅[恢复过去的对话](/docs/zh-CN/vs-code#resume-past-conversations)。85* VS Code：扩展的对话面板。该表仅涵盖以计划模式结束的对话；对于其余部分，请参阅[恢复过去的对话](/docs/zh-CN/vs-code#resume-past-conversations)。

86* 启动时的会话选择器：您从[会话选择器](#use-the-session-picker)中选择的会话，无论您是使用 `claude --resume` 单独打开它、`claude --from-pr` 还是与多个会话匹配的名称。Claude Code 不恢复存储的权限模式。它在从同一命令行启动新会话的权限模式中启动会话。86* 启动时的会话选择器：您从[会话选择器](#use-the-session-picker)中选择的会话，无论您是单独使用 `claude --resume`、使用 `claude --from-pr`，还是使用与多个会话匹配的名称打开它。Claude Code 以从同一命令行启动新会话时的权限模式启动该会话，但以计划模式结束的会话会以计划模式恢复，除非您传递 `--permission-mode`、`--dangerously-skip-permissions` 或 `--fork-session`。不会恢复其他存储的权限模式。

87* 会话内的 `/resume`，带或不带参数：Claude Code 不恢复存储的权限模式。您切换到的对话继续在您当前会话所在的权限模式中。87* 会话内的 `/resume`，带或不带参数：您切换到的对话继续使用您当前会话所在的权限模式，但以计划模式结束的对话会以计划模式恢复，即使您使用 `--permission-mode` 或 `--dangerously-skip-permissions` 启动了 Claude Code。如果该对话在本次运行 Claude Code 期间已经打开过，例如您开始时的对话，或您通过 `/clear` 或 `/resume` 离开的对话，则它会改为继续使用您当前的权限模式。

88 88 

89在非交互式和 VS Code 路径上恢复计划模式需要 Claude Code v2.1.246 或更高版本。每一行命名会话结束的权限模式、您通过哪个终端、非交互式和 VS Code 路径恢复它，以及 Claude Code 启动恢复会话的权限模式。89在非交互式和 VS Code 路径上恢复计划模式需要 Claude Code v2.1.246 或更高版本。每一行命名会话结束的权限模式、您通过哪个终端、非交互式和 VS Code 路径恢复它，以及 Claude Code 启动恢复会话的权限模式。

90 90 

91| 会话结束于 | 您如何恢复 | 恢复后的权限模式 |91| 会话结束于 | 您如何恢复 | 恢复后的权限模式 |

92| :- | :- | :- |92| :- | :- | :- |

93| `bypassPermissions` | 终端 | 新会话会启动的权限模式。要再次[绕过权限](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)，在启动时使用其启动标志之一或[用户、`--settings` 或托管设置](/docs/zh-CN/settings-reference#permissions-defaultmode)中的 `permissions.defaultMode: "bypassPermissions"` 启用它 |93| `bypassPermissions` | 终端 | 新会话会启动的权限模式。要再次[绕过权限](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)，在启动时使用其启动标志之一或[用户、`--settings` 或托管设置](/docs/zh-CN/settings-reference#permissions-defaultmode)中的 `permissions.defaultMode: "bypassPermissions"` 启用它 |

94| `plan` | 终端 | 新会话会启动的权限模式 |94| `plan` | 终端 | 计划模式。使用 `--fork-session` 时，为新会话会启动的权限模式 |

95| `auto` | 终端 | `auto`，仅当您的帐户仍然满足[自动模式要求](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)时 |95| `auto` | 终端 | `auto`，仅当您的帐户仍然满足[自动模式要求](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)时 |

96| Manual | 终端 | 当新会话会从[内置默认值](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)以自动模式启动时，手动模式。当来自设置文件的 `defaultMode` [生效](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)时，Claude Code 在该模式中启动恢复的会话 |96| Manual | 终端 | 当新会话会从[内置默认值](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)以自动模式启动时，手动模式。当来自设置文件的 `defaultMode` [生效](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)时，Claude Code 在该模式中启动恢复的会话 |

97| `plan` | 非交互式，在[下面的条件](#resume-in-plan-mode-with-p)下 | 计划模式 |97| `plan` | 非交互式，在[下面的条件](#resume-in-plan-mode-with-p)下 | 计划模式 |