Docker Sandboxes

以下说明适用于本地沙箱。有关云端身份验证和使用方式，请参阅 为云智能体配置身份验证和使用云沙箱。

官方文档：Claude Code

快速开始 ​

指向项目目录，即可在沙箱中启动 Claude Code：

console
$ sbx run claude ~/my-project

要在当前目录中用指定的提示词启动 Claude：

console
$ sbx run --name my-sandbox claude -- "Add error handling to the login function"

-- 之后的内容会直接传给 Claude Code。你也可以用 -- "$(cat prompt.txt)" 从文件传入提示词。

要创建无挂载沙箱，使用不带工作区路径的 sbx create，然后按名称连接。

身份验证 ​

使用默认的 Anthropic 模型时，Claude Code 需要 Anthropic API 密钥或 Claude 订阅。 对于其他模型，请参阅使用本地模型。

API 密钥：用存储的密钥保存你的密钥：

console
$ sbx secret set anthropic

Claude 订阅：如果未设置 API 密钥，请在 Claude Code 内使用 /login 命令， 通过 OAuth 完成身份验证。

配置 ​

沙箱不会读取宿主机的用户级配置，例如 ~/.claude。沙箱内只有工作目录中的项目级 配置可用。变通方法请参阅 沙箱为什么不用我的用户级智能体配置？。

远程控制 ​

要在沙箱内使用 Claude Code 的 /remote-control 命令，请开启 claude.remoteControl：

console
$ sbx settings set claude.remoteControl true

远程控制的环境变量和会话凭据会保留在宿主机上。Docker Sandboxes 不会把远程提供的 环境变量或 MCP 配置传入沙箱。将 claude.remoteControl 设为 false，即可阻止代理 向运行中的沙箱提供远程控制凭据。

Claude in Chrome ​

Claude in Chrome 让沙箱中的 Claude Code 能够操作宿主机浏览器里的标签页。默认关闭。 要使用它：

  1. 在宿主机浏览器中安装 Claude in Chrome 扩展并登录。扩展与 Claude Code 的订阅 OAuth 登录要使用同一个账户。你的组织必须允许该扩展。仅凭 API 密钥是不够的。

  2. 在宿主机上启用 claude.chrome：

    console
    $ sbx settings set claude.chrome true

  3. 在 Claude 沙箱中用 --chrome 启动 Claude Code：

    console
    $ sbx run --name <sandbox-name> -- --chrome

让 Claude 打开标签页、导航到某个页面或读取其内容。Docker Sandboxes 会用你保存的 Claude OAuth 登录对浏览器连接进行身份验证，而不会在沙箱内暴露令牌。

要阻止后续的浏览器连接，在宿主机上运行：

console
$ sbx settings set claude.chrome false

这会阻止运行中的沙箱建立新的连接，而无需重建沙箱。它不会终止已经建立的浏览器 连接。要撤销有效的访问权限，请结束现有的 Claude 浏览器会话。

默认启动命令 ​

不带额外参数时，沙箱运行：

text
claude --dangerously-skip-permissions

当 -- 后的第一个参数本身是标志（以 - 开头）时，其余参数会追加到默认标志之后， 因此 --dangerously-skip-permissions 会被保留：

console
$ sbx run --name <sandbox-name> -- -c   # 运行 claude --dangerously-skip-permissions -c

有关提示词和子命令，请参阅 向智能体传递参数。

可用选项请参阅 Claude Code CLI 参考。

智能体视图 ​

Claude Code 的智能体视图会启动并行 运行任务的后台会话。将它与克隆模式配合使用， 可以把它们的改动保留在沙箱内：

console
$ sbx run --clone claude . -- agents

要使用 agents 子命令并启用跳过权限模式，请显式传入该标志：

console
$ sbx run --clone claude . -- --dangerously-skip-permissions agents

要同时执行多个任务，每个后台会话都需要独立的 worktree 或克隆。仅靠分支无法隔离 同一个工作目录中的改动。Claude Code 如何管理工作目录，取决于任务、配置和项目 指令。--clone 标志无法控制这一行为。请让 Claude Code 在沙箱内为每个任务创建 独立的 worktree。

要审查某个会话创建的分支，在宿主机上抓取 sandbox-<sandbox-name> 远程：

console
$ git fetch sandbox-<sandbox-name>
$ git diff main..sandbox-<sandbox-name>/<branch>

有关克隆模式的详细信息，请参阅 Git 工作流。

基础镜像 ​

沙箱使用 docker/sandbox-templates:claude-code。要在该基础镜像之上构建自己的镜像， 请参阅基础镜像。

使用本地模型 ​

有关本地模型、托管提供商和自定义推理端点，请参阅 使用本地模型和托管模型。