云端密钥与运行阶段

在 Cloud Agents dashboard 的 Secrets 管理运行所需凭据。它们以环境变量提供，但不同范围和阶段的可见性不同。

范围与时机

范围	可用场景
Team secrets	可用于 Build 和对应团队 Agent
Environment secrets	仅该环境，包含环境内所有仓库，可用于 Build
User secrets	Agent 启动时加入，不用于共享 Build

Environment secrets 不进入其他环境，也不会传给 Self-Hosted Machines。个人 secrets 在启动时注入，新增后已运行 Agent 不会自动收到，应启动新任务验证。

应用配置

Monorepo 的多个 .env.local 若含同名键，可为不同应用设置唯一变量名，再由应用配置引用。快照若包含 .env.local，该文件也会被保存；不要以为它天然排除在快照之外，集中使用 Secrets 更容易管理。

需要 TOTP 登录时，官方支持把共享 TOTP secret 放入 Secrets，再由工具生成当前验证码。凭据范围应与实际测试环境一致，避免把无关账号访问能力加入环境。

AWS 角色方式

官方支持用 CURSOR_AWS_ASSUME_IAM_ROLE_ARN 指定客户 IAM role，并用团队生成的 external ID 配置角色信任。完整 trust policy 与 Cursor role assumer ARN 以官方设置页为准。

配置成功后，AWS_CONFIG_FILE 指向托管文件，AWS_PROFILE 为 cursor-cloud-agent，AWS_SDK_LOAD_CONFIG 为 1；默认凭据链的 AWS CLI/SDK 可使用该 profile，无需手动导出 access key。

STS 凭据有效期为 1 小时，Agent 唤醒时对缺失、失效或距到期不足 15 分钟的凭据刷新。另一种方式是从 VM 本地 socket 获取短期 OIDC token，详见官方 Identity 文档。

找不到凭据

检查使用的账号、团队、环境和注入阶段。Build 无法读取用户 secret 是预期行为；自托管机器也不会继承环境 secrets。不要先把密钥硬编码进仓库来绕开范围问题。

密钥类型不同于作用范围

Team、Environment、User 描述谁使用；Environment Variable、Runtime Secret、Build Secret 描述如何暴露。

• Environment Variable：值可被 Agent 看见，适合标志和公开 URL 等配置。
• Runtime Secret：仍作为环境变量提供，但工具结果、transcript、commit 和 commit message 中替换为 [REDACTED]；使用环境终端的人仍可读取真实变量。
• Build Secret：只用于 Docker build，不暴露给正在运行的 Agent。Dockerfile 中通过 RUN --mount=type=secret 引用。

不要把“团队 secret 可用于 Build”与“Build Secret 类型只用于 Docker build”混为一谈，也不要把日志脱敏当作终端内没有凭据。