云智能体使用云密钥存储中的凭据进行身份验证。启动智能体之前先配置好这些凭据， 这样身份验证就不依赖沙箱内部存储的文件。

使用云密钥存储

以下几种密钥接口彼此独立：

• sbx secret 管理本地沙箱的密钥
• sbx --cloud secret 管理由 CLI 创建的云沙箱的密钥
• Docker Agentic Platform 通过自己的 Web 界面管理一组独立的密钥名称

通过某个接口创建的凭据，无法通过其他接口使用。启动云沙箱之前，请用下列方式之一 配置云凭据。

选择身份验证方式

对于 Claude Code，使用 Anthropic API 密钥。对于 Codex，使用 OpenAI API 密钥或 账户级作用域的 OpenAI OAuth 凭据。

用对应的命令配置你的智能体：

智能体或提供商	推荐命令	身份验证
Claude Code	sbx --cloud secret set anthropic	提示输入 Anthropic API 密钥
Codex 配合 OpenAI OAuth	sbx --cloud secret set openai --oauth	打开 OpenAI OAuth 流程，并把生成的凭据存储在账户作用域
服务 API 密钥	sbx --cloud secret set <service>	提示输入 API 密钥或令牌

对于 Codex，你可以使用账户级作用域的 OpenAI OAuth，也可以用 sbx --cloud secret set openai 存储 OpenAI API 密钥。

存储 Anthropic API 密钥之后，启动 Claude Code：

$ sbx --cloud run claude --name cloud-project

让凭据留在沙箱文件系统之外

用 sbx --cloud secret 配置的凭据保存在云密钥存储中，位于沙箱文件系统之外。

智能体的交互式登录可能会把凭据写入沙箱内部。这些文件可能被包含进模板和 sbx move 快照。如果你在智能体内部登录过，请按照对应提供商的退出登录指引操作，并在捕获或迁移 沙箱之前删除这些凭据。

设置凭据作用域

凭据默认使用账户作用域。账户级作用域的凭据可用于该 Docker 账户下的云沙箱：

$ sbx --cloud secret set github

把 API 密钥或令牌限定到某个具名沙箱：

$ sbx --cloud secret set openai --sandbox cloud-project

对于同一个服务，沙箱级作用域的密钥优先于账户级作用域的密钥。在创建沙箱之前设置好， 这样 CLI 才能在沙箱启动时把它包含进去。OAuth 凭据不能使用沙箱作用域。

服务标识符

下表列出云密钥对 本地沙箱中记录的内置服务的支持情况：

服务	云密钥身份验证
anthropic	API 密钥
cursor	API 密钥
droid	API 密钥；不支持云端托管的 OAuth
github	令牌
google	API 密钥
groq	API 密钥
mistral	API 密钥
nebius	API 密钥
openai	API 密钥或 OAuth
openrouter	使用自定义密钥
xai	API 密钥

要配置受支持的服务，运行 sbx --cloud secret set <service>。对于 OpenAI OAuth， 添加 --oauth 并使用账户作用域。

对于其他服务，请配置自定义密钥。

云密钥命令不支持镜像仓库凭据，也不支持动态的 --ref 和 --command 解析器。 环境文件可以用 snapshot: true 一次性解析宿主机命令或 vault 引用，并把结果作为字面量云密钥上传。

配置自定义密钥

对于非内置服务的 API，使用 set-custom：

$ sbx --cloud secret set-custom --name project-api \
    --host api.example.com --env PROJECT_API_TOKEN

该命令会提示输入值。使用此密钥的沙箱会在 PROJECT_API_TOKEN 中收到一个占位符。 云代理会在发往 api.example.com 的请求上设置 Authorization: Bearer <secret>。 与本地自定义密钥不同，云端注入会根据目标主机设置请求头，无需请求中存在对应的占位符。

如果想从标准输入读取值，而不使用提示交互，请在宿主环境中设置 PROJECT_API_TOKEN， 并用 --value-stdin 传入：

$ printf '%s' "$PROJECT_API_TOKEN" | sbx --cloud secret set-custom \
    --name project-api --host api.example.com --env PROJECT_API_TOKEN \
    --value-stdin

这样可以让该值不出现在 sbx 命令参数中。--value-stdin 不能与 --value 或 --token 组合使用。

使用 --header 选择其他请求头。指定请求头时，默认值是原始密钥值。使用 --format 配合一个 %s 占位符可以添加前缀，例如 --header Authorization --format 'Bearer %s'。

每个 --host 都必须是精确的 DNS 名称，不带协议、端口或路径。多个主机请重复该标志。 不支持 IP 地址和通配符。添加 --sandbox cloud-project 可以把密钥限定到该沙箱， 请在创建沙箱之前设置好。自定义密钥名称不能与内置服务名称相同。

列出和删除凭据

列出云密钥的元数据，不显示具体值：

$ sbx --cloud secret ls

从匹配的作用域中删除凭据：

$ sbx --cloud secret rm github
$ sbx --cloud secret rm openai --sandbox cloud-project
$ sbx --cloud secret rm project-api

也可以按自定义密钥所服务的主机来删除它，使用 sbx --cloud secret rm --host api.example.com。删除操作会请求确认。在脚本中使用 --force。云模式不支持一次性删除全部密钥。