| 说明 | 创建或更新密钥 |
| 用法 | sbx secret set [SERVICE] [flags] |
描述
创建或更新服务密钥或镜像仓库凭据。
服务密钥
可用服务：anthropic、copilot、cursor、devin、droid、github、google、groq、mistral、 nebius、openai、openrouter、xai
服务密钥默认全局生效。使用 --sandbox 可把密钥限定到 一个沙箱。省略 SERVICE 时，会通过交互式提示来选择。
动态密钥
使用 --ref 或 --command 可以存储密钥来源，而不是密钥值。 sbx 会在需要时在宿主机上解析该来源，并按 --refresh 策略 缓存取值。
--ref 支持 1Password op:// 引用和 AWS Secrets Manager ARN。相应的 op 或 aws CLI 必须已安装并完成认证。--command 运行一条 shell 命令，并把它的标准输出用作密钥值。
命令式密钥在主机上的全新临时目录中运行，以进行 验证和刷新。该宿主机临时目录必须是绝对路径，并且必须 位于可写沙箱挂载之外。诸如 ./helper 或 cat token 这样的相对引用 不再相对于项目目录或守护进程工作目录解析。请使用共享工作区之外的 绝对 helper 路径。sbx 不会复制 helper、检查其 依赖，也不会限制其执行。helper 及其加载的任何代码或配置 都必须位于可写沙箱挂载之外。显式指向共享工作区的路径，以及暴露宿主机配置或 宿主机临时目录的大范围挂载，仍然是不安全的，包括之后才添加到运行中沙箱上的挂载。
镜像仓库凭据
使用 --registry 可存储容器镜像仓库的拉取凭据。与 服务密钥不同，镜像仓库凭据默认仅在宿主机上使用：
- 默认情况下，凭据用于宿主机上的模板和 Kit 拉取。 它们绝不会被注入沙箱。
- 使用 --all-sandboxes 时，凭据用于宿主机拉取，并由 代理注入到每个新沙箱的镜像仓库登录中。凭据本身从不 进入沙箱。
- 使用 --sandbox 时，凭据只注入到指定的沙箱。
使用 --password-stdin 可读取密码或令牌。--registry 不支持 --token 和 --oauth。
如果某个镜像仓库的 Bearer 认证端点使用不同的主机名， 请使用 --registry-auth-endpoint 信任其精确的 HTTPS URL。
选项
| 选项 | 默认值 | 说明 |
|---|---|---|
--all-sandboxes | 将镜像仓库凭据注入每个沙箱（需要 --registry） | |
--command | 使用命令的标准输出作为密钥值 | |
-f, --force | 不经确认直接覆盖已有的 API 密钥、OAuth 或镜像仓库凭据 | |
--no-verify | 存储时跳过对 --ref 或 --command 来源的检查 | |
--oauth | 启动 OAuth 流程并存储 OAuth 令牌（仅限 openai/全局）使用 --cloud 时：支持 openai 或 anthropic，仅存储在云端（不会进入本地 secrets-engine） | |
--password-stdin | 从 stdin 读取镜像仓库密码或令牌（与 --registry 一起使用） | |
--ref | 使用 1Password 的 op:// 引用或 AWS Secrets Manager ARN 作为密钥来源 | |
--refresh | 密钥刷新策略：按需刷新或在指定时长后刷新（默认：55m） | |
--registry | 用于拉取凭据的镜像仓库主机名（例如 ghcr.io） | |
--registry-auth-endpoint | 跨主机镜像仓库域的可信 HTTPS 认证端点 | |
--sandbox | 将密钥限定到单个沙箱，而不是其默认作用域 | |
--show-error | 如果初始检查失败，显示解析器的标准错误（可能包含密钥） | |
-t, --token | 密钥值（安全性较低：会出现在 shell 历史记录中） | |
--username | 镜像仓库用户名（与 --registry 一起使用；仅用令牌认证时可省略） |
全局选项
| 选项 | 默认值 | 说明 |
|---|---|---|
--cloud | 改为调用 Docker Cloud Sandboxes API，而不是本地 sandboxd（支持的动词正在逐步增加，运行 sbx --cloud --help 查看当前列表） | |
-D, --debug | 启用调试日志 | |
--no-input | 从不提示；需要应答的命令会直接失败，并给出应当运行的命令 |
示例
# 全局存储 GitHub 令牌（所有沙箱均可使用）
sbx secret set github
# 为指定沙箱存储 OpenAI 密钥
sbx secret set openai --sandbox my-sandbox
# 通过 stdin 进行非交互式操作（例如来自密钥管理器或环境变量）
echo "$ANTHROPIC_API_KEY" | sbx secret set anthropic
# 启动 OpenAI OAuth 流程并存储全局 OAuth 令牌
sbx secret set openai --oauth
# 在使用时解析 1Password 引用（需要已完成认证的 op CLI）
sbx secret set anthropic --ref 'op://Private/Anthropic/api-key'
# 在使用时解析 AWS Secrets Manager ARN（需要已完成认证的 aws CLI）
sbx secret set anthropic --ref 'arn:aws:secretsmanager:us-west-2:123456789012:secret:anthropic-api-key'
# 使用任意命令解析密钥
sbx secret set github --command 'gh auth token'
# 镜像仓库：仅主机使用（拉取模板/Kit，不会注入沙箱）
gh auth token | sbx secret set --registry ghcr.io --password-stdin
# 镜像仓库：主机拉取 + 注入到每个新沙箱
gh auth token | sbx secret set --all-sandboxes --registry ghcr.io --password-stdin
# 镜像仓库：仅指定沙箱
gh auth token | sbx secret set --sandbox my-sandbox --registry ghcr.io --password-stdin
# 自建镜像仓库，配备跨主机认证端点
echo "$GITLAB_PAT" | sbx secret set --all-sandboxes \
--registry registry.example.com --username "$GITLAB_USER" \
--registry-auth-endpoint https://gitlab.example.com/jwt/auth \
--password-stdin参见
sbx secret— 管理已存储的密钥