Docker Sandboxes

这些凭据存储和身份验证流程适用于本地沙箱。云凭据需要单独设置：请参阅 为云智能体配置身份验证。

大多数智能体都需要为其模型提供商准备一个 API 密钥。宿主机上的 HTTP/HTTPS 代理会 拦截来自沙箱的出站请求，在宿主机上查找对应的凭据，并在转发前覆写认证请求头。启用 代理管理时，真实凭据始终留在宿主机上，沙箱看到的只是一个哨兵值。关于凭据隔离如何 融入整体的沙箱安全模型，请参阅信任边界。

凭据注入的原理 ​

当沙箱发出出站请求时，宿主机侧的代理会决定三件事：该请求是否匹配kit（或内置 智能体）声明的服务、要写入哪个请求头，以及要注入什么值。匹配关系和请求头由 kit 声明；值则由你在宿主机上提供。对于由代理管理的凭据，真实值永远不进入沙箱—— 智能体看到的只是像 proxy-managed 这样的哨兵值。

kit 可以设置 OAuth 的 passthrough: true 来选择不使用哨兵遮蔽。这会把真实的令牌 响应送入沙箱，削弱凭据隔离。请参阅 oauth kit 字段。

提供这个值有多种方式。当多个来源都为同一个服务提供值时，已存储的密钥优先。

形式它是什么何时使用
已存储的密钥（sbx secret set）操作系统密钥链中按服务标识存放的值或动态来源任何内置服务或 kit 声明的服务的默认方式
自定义密钥（sbx secret set-custom）按域名和环境变量绑定的值服务模型不适用，或智能体会校验该变量的格式
OAuth宿主机侧的登录流程；令牌永不进入沙箱智能体支持 OAuth 时，例如 Claude Code、Codex、Cursor 或 Droid
镜像仓库凭据（sbx secret set --registry）拉取镜像和 kit 时的身份验证从私有镜像仓库拉取模板或 kit 时

提供值和批准使用它是两个独立的步骤。 凭据绑定记录你授权 kit 使用的机制和域名，它们本身不存储凭据值。

对于多提供商的智能体（OpenCode、Docker Agent），代理会根据所调用的 API 端点来选择 凭据。有关各提供商的细节，请参阅各个智能体页面。

已存储的密钥 ​

sbx secret set 把凭据值或动态密钥来源存入操作系统的密钥链，以服务标识为键。内置 智能体声明一组固定的服务，自定义 kit 可以声明自己的服务。两者使用同样的 sbx secret set 流程。

名称以 mcp: 开头的密钥保留给宿主机的 MCP 网关。关于它们与智能体和提供商凭据的区别，请参阅 MCP 密钥。

密钥的存储位置 ​

支撑 sbx secret set 的存储取决于你的操作系统：

  • macOS：系统钥匙串。
  • Windows：Windows 凭据管理器。
  • Linux：桌面钥匙环提供的 Secret Service，例如 GNOME Keyring 或 KDE Wallet。

Ubuntu 软件包推荐使用 GNOME Keyring 并默认安装它。在没有桌面钥匙环的宿主机上安装该 软件包时，可以省略 GNOME Keyring。

在没有运行 Secret Service 的 Linux 宿主机上——无头服务器和某些 WSL 配置——sbx 会 回退到用户配置目录 $XDG_CONFIG_HOME/com.docker.sandboxes 下的文件，当 $XDG_CONFIG_HOME 未设置时默认为 ~/.config/com.docker.sandboxes。这种回退是自动 的，无需配置。当你以这种方式存储密钥时，sbx 会打印一条提示：

text
No keychain detected - this secret will be stored on disk, protected by file permissions rather than a password

sbx 把该文件保存在权限为 0700 的目录中，与 ~/.docker/config.json 使用的文件 权限模型相同。任何能够读取该文件的用户或进程都能取回已存储的凭据，因此请把该目录 视为敏感目录。在可用的情况下，优先使用钥匙串，因为它按应用来中介访问。

如果你之后在宿主机上启动了 Secret Service，sbx 会再次把新密钥存入钥匙串。关于在 没有桌面钥匙环的情况下运行沙箱的更多信息，请参阅 我可以在无头 Linux 上使用 Docker Sandboxes 吗？

存储密钥 ​

console
$ sbx secret set anthropic

该命令会以交互方式提示你输入密钥值。服务密钥默认是全局的，因此该密钥对所有沙箱 都可用。要把密钥限定到特定的某个沙箱：

console
$ sbx secret set openai --sandbox my-sandbox

添加、更新或删除服务密钥会立即对已有的本地沙箱生效，无需重启，包括用 --command 或 --ref 配置的密钥。沙箱级作用域的密钥优先于全局密钥。

MCP 密钥 ​

MCP 网关使用同一个宿主机凭据存储来保存 OAuth 客户端密钥和自定义请求头密钥。这些 记录的名称以 mcp: 开头，会出现在 sbx secret ls 中。它们留在宿主机上，不会被注入 到沙箱中。网关用它们代表沙箱中的智能体向 MCP 服务器发起身份验证。

关于配置步骤，请参阅 OAuth 客户端密钥和 自定义请求头。请求头密钥使用全局作用域， 并有各自的重启要求。

使用动态密钥来源 ​

动态密钥来源让 sbx 能在代理需要凭据时，从宿主机上一个已完成身份验证的工具中获取 它。密钥存储中保存的是引用或命令，而不是凭据值。解析和缓存都发生在宿主机上，沙箱 收到的仍然只是由代理管理的占位符。

把 --ref 与 1Password 密钥引用或 AWS Secrets Manager ARN 一起使用：

console
$ sbx secret set anthropic --ref 'op://Work/Anthropic/credential'
$ sbx secret set openai \
    --ref 'arn:aws:secretsmanager:us-west-2:123456789012:secret:openai-api-key'

对应的 op 或 aws CLI 必须已安装并在宿主机上完成身份验证，并且它的安装目录要以 绝对路径的形式列在宿主机的 PATH 中。内置的引用提供商会忽略空的和相对的 PATH 条目。

每次解析引用时，提供商 CLI 都会在宿主机上一个全新的临时目录中运行，该目录位于项目 目录之外。请为你指定的任何提供商配置文件使用绝对路径。如果你使用 asdf 或 mise 之类 的版本管理器，请全局配置提供商版本，而不要依赖仅针对项目的选择。请让提供商工具、 它们的依赖以及宿主机的临时目录都位于可写沙箱挂载点之外。

NOTE

要用特定的 1Password 账户或 AWS 配置文件解析引用，请在运行 sbx secret set 时设置 OP_ACCOUNT 或 AWS_PROFILE。sbx 每次解析该密钥时都会使用该账户或配置文件。如果 两个变量都没有设置，提供商 CLI 使用其默认配置。

把 --command 用于另一个能把密钥打印到标准输出的宿主机工具：

console
$ sbx secret set github --command 'gh auth token'

sbx 通过宿主机 shell 运行该命令，并去除其输出中的空白。命令文本会被存储，由守护 进程重放。不要把密钥直接嵌进命令里，因为该文本可能出现在 shell 历史记录和进程列表中。

密钥命令在验证和刷新期间，会在宿主机上一个全新的临时目录中运行。因此像 ./credential-helper 这样的相对路径会相对于该临时目录解析。这同时适用于 sbx secret set --command 和 sbx secret set-custom --command。

请把辅助工具以及它们加载的任何代码或配置放在可写沙箱挂载点之外。通过宿主机 PATH 中的名称运行辅助工具时，请使用其绝对路径，或者在命令中显式切换到它的私有目录。 同时请让宿主机的临时目录也位于可写沙箱挂载点之外。

默认情况下，sbx 在注册来源时验证它，并在出错时报告错误但不暴露解析器的标准错误。 要注册一个在注册期间无法解析的来源，使用 --no-verify。要排查初次验证失败，使用 --show-error。提供商的错误输出可能包含敏感信息。--show-error 不能与 --no-verify 组合使用。

解析后的服务密钥默认缓存 55 分钟。要改变缓存时长，使用 --refresh <duration>。要 每次使用凭据时都重新解析来源而不缓存，传入 --refresh on-demand：

console
$ sbx secret set anthropic \
    --ref 'op://Work/Anthropic/credential' \
    --refresh 30m
$ sbx secret set github --command 'gh auth token' --refresh on-demand

--ref 和 --command 互斥。它们不能与 --token、--oauth 或 --registry 组合使用。

从环境变量导入 ​

如果你已经在 shell 中设置了 API 密钥，sbx secret import 会读取它们并存入密钥链， 无需逐个手动输入：

console
$ sbx secret import

该命令会扫描当前会话中内置服务表里列出的环境变量，并在写入 之前逐个提示你确认。要导入单个服务：

console
$ sbx secret import openai

传入 --all 可在不提示的情况下导入全部内容（仅新增条目；已有条目保持不变），传入 --force 则覆盖已有条目：

console
$ sbx secret import --all
$ sbx secret import openai --force

传入 --dry-run 可以预览将要导入的内容而不写入任何东西。运行 sbx secret ls 确认 已存储的内容。关于在 CI 中配置凭据，请参阅 CI 与无界面使用。

内置服务 ​

每个内置服务名都对应一组 sbx secret import 读取的环境变量，以及代理注入凭据的 API 域名：

服务环境变量API 域名
anthropicANTHROPIC_API_KEYapi.anthropic.com、console.anthropic.com、claude.ai、mcp-proxy.anthropic.com
cursorCURSOR_API_KEYapi2.cursor.sh、api3.cursor.sh、repo42.cursor.sh、cursor.com
droidFACTORY_API_KEYapi.factory.ai、app.factory.ai、relay.factory.ai
githubGH_TOKEN、GITHUB_TOKENapi.github.com、github.com、raw.githubusercontent.com、gist.github.com、copilot.github.com、api.githubcopilot.com
googleGOOGLE_API_KEYgenerativelanguage.googleapis.com、oauth2.googleapis.com、aiplatform.googleapis.com、vertexai.googleapis.com
groqGROQ_API_KEYapi.groq.com
mistralMISTRAL_API_KEYapi.mistral.ai
nebiusNEBIUS_API_KEYapi.studio.nebius.com、api.tokenfactory.nebius.com
openaiOPENAI_API_KEYapi.openai.com、openai.com、chatgpt.com、www.chatgpt.com
openrouterOPENROUTER_API_KEYopenrouter.ai
xaiXAI_API_KEYapi.x.ai

当你用 sbx secret set <service> 存储密钥时，代理会把它注入到发往上述 API 域名的 请求中。

由 kit 声明的服务 ​

存储 kit 的凭据时，请使用其文档中的服务标识。对于声明了 my-service 的 kit，运行：

console
$ sbx secret set my-service

没有单独的注册步骤。已存储的值和 kit 的请求使用同一个标识。出现提示时，批准该 kit 的凭据请求。请参阅凭据绑定。

编写 kit 时，请声明它如何使用该服务。v3 使用凭据能力（capability），v2 使用顶层 的 credentials 列表。两个示例都声明了服务并允许访问它的 API 主机：

::: tabs ::: tab v3

yaml
capabilities:
  - type: com.docker.sandbox/network-policy@1
    config:
      runtime:
        allow: [api.my-service.com]
  - type: com.docker.sandbox/credential@1
    config:
      service: my-service
      phase: runtime
      apiKey:
        name: MY_SERVICE_TOKEN
        proxyManaged: true
        inject:
          - domain: api.my-service.com
            header: Authorization
            format: "Bearer %s"

对于 API 密钥，请像示例中那样同时指定 HTTP 请求头及其值格式。sbx 在 v3 kit 中 不使用 apiKey.inject[].scheme。

对于 OAuth，请使用 JSON 凭据文件，并使用在 refresh_token 中返回刷新令牌的提供商。 sbx 不支持 TOML 凭据文件，也不支持其他刷新令牌字段。

为 install 阶段声明的凭据在 install 钩子执行期间可用。请把接收这些凭据的域名加入 网络策略的 install.allow 列表。仅在 runtime.allow 中列出，并不能在安装期间授予 访问权限。如果钩子读取某个凭据环境变量，请把该名称包含在它的 env 列表中。

在 sbx 中，代理会在智能体启动之前停止向仅用于 install 的域名注入凭据。如果有任何 运行时凭据以该域名为目标，即便使用的是另一个服务名称，该域名仍可用于凭据注入。 如果你为两个阶段声明了同一个服务，sbx 会在两个阶段都使用运行时声明中的凭据设置。

::: ::: tab v2

yaml
credentials:
  - service: my-service
    apiKey:
      name: MY_SERVICE_TOKEN
      proxyManaged: true
      inject:
        - domain: api.my-service.com
          scheme: bearer

permissions:
  network:
    allow: [api.my-service.com]

::: :::

每个服务声明 apiKey、oauth 或两者。当两者在运行时都能解析时，API 密钥优先， OAuth 作为后备。完整的 kit 端配置，请参阅 V3 凭据定义 或 V2 凭据。

列出和删除密钥 ​

列出所有已存储的密钥：

console
$ sbx secret ls
SCOPE      SERVICE   SECRET
(global)   github    gho_GCaw4o****...****43qy

删除一个密钥：

console
$ sbx secret rm github

要删除沙箱级作用域的密钥，传入 --sandbox：

console
$ sbx secret rm github --sandbox my-sandbox

删除沙箱级作用域的密钥后，如果该服务存在全局密钥，则会恢复为该全局密钥。

NOTE

运行 sbx reset 会删除所有已存储的密钥以及所有沙箱状态。重置之后，你需要重新添加 你的密钥。

GitHub 令牌 ​

github 服务让智能体可以在沙箱内访问 gh CLI。在宿主机上解析你已有的 GitHub CLI 令牌：

console
$ sbx secret set github --command 'gh auth token'

默认缓存期结束后，守护进程会通过宿主机命令刷新该令牌。这对于需要代你创建拉取请求、 提交 issue 或与 GitHub API 交互的智能体很有用。

SSH 智能体 ​

SSH 智能体转发默认启用。v3 kit 还必须为需要它的阶段请求 ssh-agent@1。 没有该请求时，不会向 v3 沙箱转发任何智能体套接字。

当设置了 SSH_AUTH_SOCK 时，Docker Sandboxes 会使用创建、启动或加入每个沙箱的 客户端所提供的值。它会把该智能体转发进沙箱，并在沙箱中设置 SSH_AUTH_SOCK。

如果你的智能体暴露了一个稳定的套接字路径，例如 1Password SSH 智能体，请为每个 沙箱配置该路径：

console
$ sbx settings set ssh.agentSocketPath "$SSH_AUTH_SOCK"

ssh.agentSocketPath为空时（默认值），会使用每个 客户端各自提供的智能体。用 ssh.agentForwardingEnabled 开启或关闭转发。

更改转发设置或套接字选择之后，重启守护进程，让已有沙箱使用新的配置：

console
$ sbx daemon restart

私钥始终留在你的宿主机上。沙箱内的进程可以向被转发的智能体请求签名，但无法读取或 复制私钥。

对于通过 SSH 进行的 Git 操作以及基于 SSH 的提交签名，请使用 SSH 智能体转发。要让 沙箱内的提交签名生效，签名密钥必须已加载到宿主机的 SSH 智能体中。出站的 SSH 连接 仍然受沙箱网络策略约束。有关细节，请参阅 提交签名。

自定义密钥 ​

IMPORTANT

自定义密钥仍处于实验阶段。其行为、标志和占位符格式可能随时变化。

对于不适配服务标识模型的凭据——例如智能体在启动时会校验环境变量格式的情况—— 使用 sbx secret set-custom。这种密钥按一个或多个目标域名、一个环境变量名称和一个 可选的占位符字符串来绑定，而不是按服务标识。

只要可以选择，就优先使用基于服务的流程——接线工作由 kit 完成， 你只需提供值。

设置自定义密钥 ​

自定义密钥默认是全局的。传入 --sandbox 可以把它限定到特定的某个沙箱。

要从标准输入读取该值，请在宿主机环境中设置 API_KEY，并用 --value-stdin 传入：

console
$ printf '%s' "$API_KEY" | sbx secret set-custom \
    --host api.example.com \
    --env API_KEY \
    --value-stdin

这样可以让该值不出现在 sbx 命令参数中。不传 --value-stdin 则改为在提示符中输入 该值。--value-stdin 不能与 --value、--token、--ref 或 --command 组合使用。

WARNING

用 --value 或 --token 传入字面密钥会把它记录到 shell 历史记录中，并暴露在进程 参数里。用 --value "$API_KEY" 展开环境变量同样会把该值暴露在进程参数中。请改用 提示符或标准输入。

在沙箱内，API_KEY 被设置为一个生成的占位符（例如 sbx-cs-<rand>）。当沙箱内的 进程向任何已配置的主机发送请求，并且该占位符出现在 HTTP 请求头中时，代理会把它 替换为真实值。替换只作用于 HTTP 请求头，不作用于请求体。智能体永远不会看到真实的 密钥。

列出自定义密钥 ​

要按主机查找已存储的自定义密钥，使用 --host：

console
$ sbx secret ls --host api.example.com

要按环境变量名过滤，使用 --env-name：

console
$ sbx secret ls --env-name API_KEY

添加 --sandbox 可只列出为特定沙箱存储的匹配密钥：

console
$ sbx secret ls --host api.example.com --sandbox my-sandbox

指向多个主机 ​

重复使用 --host，即可用同一个密钥覆盖多个域名——当一个 API 分散在若干相关主机名 上，或两个互不相关的端点共用一份凭据时，这很有用：

console
$ sbx secret set-custom \
    --host api.example.com \
    --host uploads.example.com \
    --env API_KEY \
    --value <secret>

--host 的值也可以使用通配符，语法与 网络规则主机名模式相同： * 匹配单个标签（*.example.com 覆盖 api.example.com），** 匹配任意数量 （**.example.com 覆盖 api.example.com 和 v2.api.example.com）。

动态解析自定义密钥 ​

自定义密钥同样接受动态密钥来源。把 --value 替换为 --ref 或 --command：

console
$ sbx secret set-custom \
    --host api.example.com \
    --env API_KEY \
    --ref 'op://Work/Example/credential'

动态自定义密钥默认按需解析。传入 --refresh 加一个时长可以缓存解析出的值。验证 和错误输出标志的行为与服务密钥相同。--ref 和 --command 不能与 --value 或 --token 组合使用。

从 GitHub Packages 安装 npm 包 ​

内置的 github 服务不会向 npm.pkg.github.com 的请求注入凭据。要从 GitHub Packages 安装私有 npm 包，请为该主机添加一个自定义密钥。

在宿主机上，用一个能读取该包的令牌对 GitHub CLI 进行身份验证。GitHub 的文档建议 在这种用途下使用至少具备 read:packages 权限的个人访问令牌（classic）。请参阅 对 GitHub Packages 进行身份验证。 然后注册令牌来源，把 my-sandbox 替换为你的沙箱名称：

console
$ sbx secret set-custom \
    --sandbox my-sandbox \
    --host npm.pkg.github.com \
    --env NODE_AUTH_TOKEN \
    --command 'gh auth token'

该命令会打印一个生成的占位符。对于已有沙箱，用 sbx run -e 在智能体会话中把 NODE_AUTH_TOKEN 设为该占位符，或在 /etc/sandbox-persistent.sh 中为后续会话设置。 请参阅设置环境变量。请使用占位符，而不是 真正的 GitHub 令牌。

在沙箱内，把以下条目加入项目的 .npmrc，把 @my-org 替换为该包的作用域。保持 ${NODE_AUTH_TOKEN} 为字面量，以便 npm 读取该环境变量：

ini
@my-org:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

在沙箱内安装该包：

console
$ npm install @my-org/my-package

把 @my-org/my-package 替换为你的包名。npm 会把占位符发送到 npm.pkg.github.com，代理会把它替换为宿主机上 gh auth token 取回的令牌。

凭据绑定 ​

凭据绑定文件记录你为每个服务批准了哪些凭据机制和域名。它位于 ~/.config/sbx/credentials.yaml，在 Windows 上位于 %APPDATA%\sbx\credentials.yaml。

第三方 kit 需要为它使用的每一项凭据都有一条已批准的绑定，无论 schema 版本如何。 你首次运行这类 kit 时，sbx 会以交互方式创建绑定（请参阅 首次运行时的批准）；你也可以手动写入条目。仅由 sbx 随附的 内置 kit 请求的凭据不需要绑定。

bindings 下的每个条目以 服务标识为键，批准一种或两种凭据机制：

  • apiKey——批准注入该服务已存储的 API 密钥。值来自 密钥存储（sbx secret set <service>）；绑定只记录批准行为， 它既不保存也不定位该值。
  • oauth——批准该服务的 OAuth 流程。你在宿主机上登录，代理负责令牌刷新和路由。 OAuth 域名包括令牌端点主机以及 kit 声明的任何资源主机。

每种机制都有一个 domains 列表，记录你批准的域名。当 kit 请求的域名不被现有绑定 覆盖时，sbx 会请求批准。

yaml
bindings:
  anthropic:
    apiKey:
      domains: [api.anthropic.com]
  github:
    apiKey:
      domains: [api.github.com, github.com]

绑定只是一份批准记录：出现 apiKey 或 oauth 就代表授权了该机制。拒绝某项凭据 时不会写入任何条目。真实凭据不会保存在这个文件中。

首次运行时的批准 ​

当第三方 kit 需要一项没有绑定的凭据时，sbx 会引导你完成批准。对于 API 密钥， 你可以使用密钥存储中已有的值，或在提示时输入一个。对于 OAuth，你批准登录流程。 两种情况下，你都要批准 kit 声明的域名。sbx 会把该条目写入 credentials.yaml。

在非交互式环境中（CI 或 --detach），没有人可以回答提示。在 sbx 中，没有绑定 时沙箱会以扣留该凭据的方式启动。对于必需的凭据，sbx 会打印一条警告，而不是让 沙箱创建失败。这是 sbx 强制机制的一个限制：kit 作者不应仅凭沙箱启动了就认为 必需的凭据一定可用。

请先以交互方式运行一次该 kit，或者在无人值守运行之前直接写入 credentials.yaml， 预先创建绑定。

绑定文件决定第三方 kit 能否使用某项服务凭据。kit 的凭据注入规则和网络权限仍然 约束着哪些请求可以携带该凭据。

需要绑定的 kit ​

第三方 kit 无论 schema 版本如何，都需要你批准才能使用凭据。sbx 随附的内置 kit 可以使用它们请求的凭据，无需绑定。如果第三方 v2 kit 扩展了某个内置智能体，你必须 批准它对继承凭据的使用。你还必须批准一个自行请求同一服务的第三方 kit。

镜像仓库凭据 ​

镜像仓库凭据用于在拉取模板或 kits时向私有 OCI 镜像仓库进行身份验证， 也可以让智能体通过宿主机侧的代理在沙箱内拉取和推送镜像。用 sbx secret set --registry <host> 存储它们。对于 Docker Hub，sbx 会复用你的 sbx login 会话——不需要镜像仓库密钥。对于其他镜像仓库（GitHub Container Registry、ECR、ACR、自建 Nexus 等），用 sbx secret set --registry 存储凭据。

通过添加 --all-sandboxes、添加 --sandbox SANDBOX 或两者都不传来选择作用域：

text
sbx secret set [--all-sandboxes | --sandbox SANDBOX] --registry HOST
  • 仅宿主机（不加作用域标志）：sbx 用它来在创建沙箱时拉取模板和 kit。 该凭据留在宿主机上，在沙箱内永远不可用。
  • 所有沙箱（--all-sandboxes）：与仅宿主机相同，另外代理会对来自沙箱的镜像 仓库登录请求进行身份验证。该凭据留在宿主机上，永远不会写入沙箱文件系统。当 智能体需要构建和发布容器镜像时使用它。
  • 沙箱级作用域（--sandbox SANDBOX）：代理行为与 --all-sandboxes 相同，但 仅对具名沙箱生效。当只有一个沙箱需要镜像仓库访问权限时使用它。

存储镜像仓库凭据 ​

从标准输入传入令牌，并指定镜像仓库主机名：

console
$ gh auth token | sbx secret set --registry ghcr.io --password-stdin

对于需要用户名的镜像仓库（例如使用管理员账户的 ACR），添加 --username：

console
$ echo "$ACR_PASSWORD" | sbx secret set \
    --registry myregistry.azurecr.io \
    --username myuser \
    --password-stdin

添加 --all-sandboxes 可让该凭据对每个新沙箱都可用：

console
$ gh auth token | sbx secret set --all-sandboxes --registry ghcr.io --password-stdin
$ sbx run claude

请在创建沙箱之前存储所有沙箱通用的镜像仓库凭据。已有沙箱不会获取之后添加的 所有沙箱通用镜像仓库凭据。要给已有沙箱添加镜像仓库访问权限，请改用沙箱级作用域 的凭据。

要把凭据限定到单个沙箱，用该沙箱的名称存储：

console
$ gh auth token | sbx secret set --sandbox my-app --registry ghcr.io --password-stdin

对于 Docker Hub 上的 v2 kit，sbx kit pull 和 sbx kit push 使用 sbx login 的 会话。对于其他镜像仓库，这两个命令使用上述凭据。两个命令都会回退到 Docker 凭据 存储，因此通过 docker login 获得的凭据同样可用。v3 kit 使用 Docker Buildx 发布， 它使用 docker login 的凭据。

信任私有镜像仓库的身份验证端点 ​

当自建镜像仓库通过独立的主机对沙箱请求进行身份验证时，把 --registry-auth-endpoint 与 --registry 一起使用。例如，位于 registry.example.com 的自建 GitLab 镜像仓库 可能在其 Registry v2 的 WWW-Authenticate: Bearer 质询中，把 https://gitlab.example.com/jwt/auth 声明为 realm。

存储该凭据，并为特定沙箱信任该端点：

console
$ echo "$GITLAB_PAT" | sbx secret set --sandbox my-app \
    --registry registry.example.com \
    --username "$GITLAB_USER" \
    --registry-auth-endpoint https://gitlab.example.com/jwt/auth \
    --password-stdin

把示例中的主机替换为你的镜像仓库主机和身份验证主机，并把 GITLAB_USER 和 GITLAB_PAT 设为你的 GitLab 用户名和个人访问令牌。

这授权代理把已存储的镜像仓库凭据发送到 https://gitlab.example.com/jwt/auth，用它 换取镜像仓库令牌。所声明的 realm 必须使用 HTTPS，并且与配置的主机和路径完全一致。 该主机上的其他路径，包括 /jwt/auth/，不在覆盖范围内。端点 URL 不能包含内嵌的 凭据、查询字符串或片段。令牌请求仍然可以包含 service、scope 等协议参数。

不使用该标志时，代理只接受镜像仓库自身主机上的身份验证端点，以及内置的镜像仓库 关系，例如 Docker Hub 的身份验证主机。其他身份验证主机需要显式配置。

删除镜像仓库凭据 ​

删除某个镜像仓库的仅宿主机条目和所有沙箱通用条目：

console
$ sbx secret rm --registry ghcr.io -f

要只删除所有沙箱通用条目而保留仅宿主机凭据，传入 --all-sandboxes：

console
$ sbx secret rm --all-sandboxes --registry ghcr.io -f

要删除沙箱级作用域的凭据，传入沙箱名称：

console
$ sbx secret rm --sandbox my-sandbox --registry ghcr.io -f

最佳实践 ​

  • 用已存储的密钥提供凭据。操作系统密钥链会在静态存储时保护 它们；在没有密钥链的 Linux 宿主机上，它们改为保存在受权限保护的文件中。请参阅 密钥的存储位置。
  • 不要在沙箱内手动设置 API 密钥。沙箱中的智能体已预先配置为使用由代理管理的凭据。
  • 镜像仓库凭据留在宿主机上，并在沙箱向镜像仓库进行身份验证时由代理注入。请只把 它们分配给确实需要镜像仓库访问权限的沙箱，并优先使用沙箱作用域而不是 --all-sandboxes，以限制暴露范围。
  • 多个智能体还支持 OAuth 这一安全选项：流程在宿主机上运行，因此令牌不会在沙箱内 暴露。如果你没有存储凭据，智能体会提示你进行身份验证——Codex 会在你运行 sbx run codex 时在宿主机上提示，而 Claude Code、Cursor 和 Droid 则在沙箱内以 交互方式提示。要提前完成身份验证，对 Codex 运行 sbx secret set openai --oauth，或在 Claude Code 内使用 /login；Cursor 和 Droid 没有提前认证的选项，它们的登录提示会在智能体启动时出现。关于每个智能体的流程， 请参阅各自的智能体页面。
  • 如果你把凭据存储在 1Password 或 AWS Secrets Manager 中，请参阅 从 1Password 获取凭据 和从 AWS Secrets Manager 获取凭据。

自定义模板和占位符值 ​

在构建自定义模板或在 shell 沙箱中手动安装智能体时，有些智能体要求在启动前设置 OPENAI_API_KEY 之类的环境变量。必要时把这些变量设为占位符值（例如 proxy-managed）。无论环境变量的值是什么，代理注入的都是真实凭据。