本页关于宿主机集成和工作区的说明描述的是本地沙箱。在把这些工作流改造到云端之前， 请先阅读本地与云端的差异。
Docker Sandboxes 免费吗？可以商用吗？
sbx CLI 和本地沙箱计算资源可免费使用，包括用于商业和专业用途。云端沙箱计算 资源采用按量付费订阅。模型提供商的 费用与沙箱计算费用分开计算。
针对本地沙箱的组织治理功能包括集中管理的网络、文件系统和 MCP 策略、 登录强制要求以及 审计日志。这些 组织治理功能需要单独购买付费 订阅 —— 请联系 Docker 销售 开始使用。
为什么我需要登录？
Docker Sandboxes 的设计理念是你和你的智能体是一个团队。登录会给每个沙箱一个 经过验证的身份，从而让 Docker 能够：
- 把沙箱与真实的人绑定。 当智能体能够构建容器、安装软件包和推送代码时， 治理就变得很重要。你的 Docker 身份就是锚点。
- 启用团队功能。 组织治理、共享环境和审计日志等团队级功能 需要"谁"这个概念，事后再补上对所有人都更糟糕。
- 针对 Docker 基础设施进行身份验证。 沙箱会拉取镜像、运行守护进程并与 Docker 服务通信。Docker 账户为这些请求完成身份验证。
你的 Docker 账户邮箱仅用于身份验证，不用于营销。
我能在整个组织范围内强制执行沙箱策略吗？
可以。管理员可以集中管理网络、文件系统和 MCP 策略。这些管控适用于组织内的本地 沙箱。当组织治理处于启用状态时，只有组织的允许规则才授予访问权限：使用 sbx policy 设置的本地允许规则不再参与评估，而本地拒绝规则仍会叠加生效。
请参阅组织策略如何与本地规则和 Kit 规则相互关联。 该功能需要单独购买付费订阅 —— 请联系 Docker 销售 开始使用。
云端沙箱使用单独的网络策略配置。有关云端管控，请参阅云端网络策略。
Docker Sandboxes 需要允许哪些域名才能正常工作？
如果你的组织使用防火墙或代理限制出站网络访问，请把以下域名加入允许列表，以便 sbx 能够完成身份验证、拉取镜像，并为本地沙箱上报诊断信息。云端操作还会连接到 https://api.sandboxes-cloud.docker.com。
| 域名 | 说明 |
|---|---|
| https://login.docker.com | 身份验证 |
| https://hub.docker.com | Docker Hub |
| https://api.docker.com | Docker API |
| https://marlin-2.docker.com | 遥测 |
| https://marlin-api.docker.com | 遥测 |
| https://registry-1.docker.io | Docker 拉取/推送 |
| https://auth.docker.io | 镜像仓库身份验证 |
| https://dhi.io | Docker Hardened Images |
| https://sbx-diagnostics.s3.us-east-1.amazonaws.com | 诊断信息上传 |
CLI 会收集遥测数据吗？
sbx CLI 会收集有关 CLI 调用的基础使用数据：
- 你运行了哪个命令
- 命令是成功还是失败
- 耗时多长
- 如果你已登录，还会包含你的 Docker 用户名
CLI 使用遥测不包含你的提示词或代码。云端沙箱运行在 Docker 托管的基础设施上， 因此你传输给它们的文件会存储在云端。
如需为本地 CLI 和守护进程持久关闭遥测，请将 telemetry.disabled设置为 true：
$ sbx settings set telemetry.disabled true
$ sbx daemon restart下一次 CLI 调用会使用已保存的偏好设置。正在运行的守护进程会保留之前的遥测设置， 直到你重启它。设置 SBX_NO_TELEMETRY=0 无法覆盖已保存的退出选择。
你也可以使用 SBX_NO_TELEMETRY 环境变量退出：
$ export SBX_NO_TELEMETRY=1如何在沙箱内设置自定义环境变量？
从 sbx 0.39.0 版本开始，在 sbx run 和 sbx create 中使用 -e/--env 或 --env-file。语法、优先级规则、已有沙箱的持久化配置以及凭据相关的建议，请参阅 设置环境变量。
/etc/sandbox-persistent.sh 中的变量对交互式会话和通过 sbx run 启动的智能体 可用。变量只在添加之后新启动的会话和智能体中生效。重启正在运行的智能体，或停止 并重新启动沙箱，即可应用新的值。
为什么智能体运行时没有审批提示？
沙箱本身就是安全边界。由于智能体运行在隔离的 microVM 中，具备网络隔离、 凭据隔离，且无法访问显式共享路径之外的 宿主机系统，通常需要审批提示的那些场景（防止破坏性命令、网络访问、文件修改） 已经由沙箱的隔离层来处理。
如果你更希望重新启用审批提示，请在会话内更改权限模式。大多数智能体都允许在启动 后切换权限模式。在 Claude Code 中，使用 /permissions 命令交互式更改模式。
如需让审批提示成为每个会话的默认行为，请在 环境文件或工作负载的 Dockerfile 中设置启动命令。参见 构建智能体 Kit。
我怎么知道我的智能体是否运行在沙箱中？
问智能体即可。智能体能看到自己是否运行在沙箱内部。在 Claude Code 中，使用 /btw 斜杠命令，可以在不打断进行中任务的情况下提问：
/btw are you running in a sandbox?为什么沙箱没有使用我的用户级智能体配置？
本地沙箱不会导入你完整的用户级智能体配置。~/.claude 等目录下的 hooks、 settings 和其他文件仍留在宿主机上。工作目录中的项目级配置在沙箱内依然可用。
共享的智能体技能是一个例外。使用 sbx skills add 从 Git 仓库安装技能，或运行 sbx skills import 从受支持的宿主机目录复制技能。sbx 会把技能保存在一个 与沙箱共享的持久化存储中。有关仓库管理、受支持的宿主机目录、挂载行为以及按 沙箱选择退出的方式，请参阅共享智能体技能。
请把项目专用的技能和其他智能体配置保留在项目本身中。这样配置就能与代码一起 纳入版本控制。不要使用指向宿主机路径的符号链接，因为沙箱中的智能体无法跟随 它们走出沙箱。
我能把图片粘贴给智能体吗？
在本地沙箱中，图片粘贴默认关闭。文本粘贴可以正常工作，因为终端会直接发送它。 用 Ctrl+V 粘贴图片或截图则不同：智能体是从你的宿主机剪贴板读取该图片的， 除非你主动选择加入，否则沙箱会阻止这种访问。
$ sbx settings set clipboard.imagePaste true此后 Ctrl+V 就能把宿主机图片粘贴给会读取剪贴板的智能体，包括 Claude Code 和 Codex。该设置会在几秒内生效，即使沙箱正在运行也是如此。
大于 64 MiB 的剪贴板图片会被忽略，智能体只会收到一个空剪贴板。
之所以采用选择加入的方式，是因为它放宽了沙箱的隔离：启用后，沙箱内的进程可以 通过宿主机侧的代理读取你的宿主机剪贴板。暴露范围很有限 —— 只在粘贴时读取， 只返回图片数据（image/png），剪贴板内容绝不缓存或记录日志 —— 但这终究是宿主机 数据进入沙箱，因此在你主动打开之前它始终保持关闭。
要重新关闭：
$ sbx settings set clipboard.imagePaste false能在无图形界面的 Linux 上使用 Docker Sandboxes 吗？
可以。在 Linux 上运行本地沙箱时，sbx 会把密钥存储在桌面密钥环（如 GNOME Keyring 或 KDE Wallet）提供的 Secret Service 中。无头服务器和某些 WSL 环境没有运行中的 Secret Service，因此 sbx 会回退到 $XDG_CONFIG_HOME/com.docker.sandboxes 下的 一个文件；当 $XDG_CONFIG_HOME 未设置时，该路径默认为 ~/.config/com.docker.sandboxes。无需任何配置。在这类宿主机上存储密钥时， sbx 会打印一条提示：
No keychain detected - this secret will be stored on disk, protected by file permissions rather than a passwordsbx 会把该文件存放在权限为 0700 的目录中，这与 ~/.docker/config.json 使用的是同一套文件权限模型。任何能读取该文件的用户或进程都能取回所存储的凭据， 因此请把该目录视为敏感资源。如果有密钥环可用，请优先使用密钥环 —— 它按应用 来管控访问。
如需把密钥保留在密钥环中，请在存储之前先在宿主机上运行 Secret Service：安装 gnome-keyring 并启动 dbus-run-session，或者在能够解锁它的登录会话下运行 密钥环守护进程。一旦有了可用的 Secret Service，sbx 就会重新把新的密钥存储到 密钥环中。各平台把密钥保存在何处，请参阅密钥的存储位置。