Docker Sandboxes

用 sbx run --model 选择响应你的智能体请求的模型和服务。智能体运行在本地沙箱内， 模型则可以运行在你的宿主机上、托管提供商处，或者你配置的推理端点上。

本页介绍内置的 claude、codex 和 opencode 智能体。请选择支持你的智能体所需的 工具调用和上下文长度的模型。--model 不支持云沙箱。

NOTE

模型选择仍处于实验阶段。按照这些示例操作之前，请先启用它。

内置的模型服务 ​

Docker Sandboxes 包含 llmman，这是一个与 sbx 一同安装的模型管理工具。它提供本地 模型服务，并把请求转发到托管提供商或自定义端点。你不需要单独安装它。

默认情况下，Docker Sandboxes 守护进程会在你的宿主机上启动 llmman，并在守护进程停止时把它停止。 启动时，如果需要，llmman 会下载它的 llama.cpp 运行时，因此首次启动需要网络访问以 完成该下载。即使你还没有使用过 --model，该服务也会启动。

在沙箱或 CLI 退出之后，该服务会继续运行。各个沙箱共享它的模型仓库和已加载的模型。

在 Linux 上，llmman 会先尝试用 Docker 或 Podman 在容器中运行推理服务器。如果两者 都不可用，它会尝试下载的二进制文件，然后是宿主机 PATH 上的 llama-server。

禁用内置服务 ​

如果你不使用内置的模型服务，可以把它关掉，以跳过它的运行时下载：

console
$ sbx settings set model.server.enabled false
$ sbx daemon restart

请重启守护进程以应用该更改。如果守护进程当时没有运行，设置命令会先启动它，因此 该服务可能已经启动并开始下载，然后你才重启它。

关闭内置服务后，你仍然可以使用 Ollama。对于由 llmman 管理的本地 模型、托管提供商和自定义端点，请重新开启该服务。

要重新启用内置服务：

console
$ sbx settings set model.server.enabled true
$ sbx daemon restart

启用模型选择 ​

在你的宿主机上运行以下命令：

console
$ sbx settings set platform.allowExperimentalFeatures true
$ sbx settings set feature.model true

--provider 标志决定模型运行在哪里：

提供商模型运行位置
省略，或 llmman由 llmman 管理的本地模型
ollama你宿主机上已有的 Ollama 安装
托管提供商 IDllmman 支持的提供商，例如 openai 或 anthropic
model.providers 中的 ID你自己配置的端点

运行本地模型 ​

向 --model 传入一个 GGUF 模型引用或短名称：

console
$ sbx run --model gemma4 claude

如果需要，Docker Sandboxes 会下载该模型。模型运行在宿主机上，因此它的内存和计算 需求与沙箱的资源上限相互独立。把 claude 替换为 codex 或 opencode，即可用同一个 模型搭配其他智能体。

使用 Ollama ​

在宿主机上安装并启动 Ollama，然后用 --provider 选中它：

console
$ sbx run --model gemma4 --provider ollama claude

Docker Sandboxes 会连接 localhost:11434 上的 Ollama。它不会安装、启动或管理 Ollama 进程。

关于 Docker Model Runner，请参阅 使用 Docker Model Runner 在 Docker Sandbox 中运行 Claude Code。

使用托管提供商 ​

选择一个 llmman 支持的提供商，以及该提供商提供的模型。例如，先在宿主机上存储你的 OpenAI API 密钥，然后用一个 OpenAI 模型运行 Codex：

console
$ sbx secret set openai
$ sbx run --provider openai --model gpt-5-nano codex

宿主机的 llmman 服务把请求转发给该提供商。它不会下载或运行托管模型。关于可用提供商 及其 API 密钥变量名，请参阅 llmman 提供商文档。

提供商身份验证 ​

用 sbx secret set <PROVIDER_ID> 存储 API 密钥，ID 与 --provider 或 --overflow-provider 使用的相同。这同样适用于在 model.providers 中定义的自定义 提供商 ID。沙箱级作用域的密钥优先于全局密钥。

沙箱会用一个占位符代替密钥发出请求。只有在发往宿主机 llmman 服务的请求的 身份验证请求头中，宿主机代理才会把它替换为存储的密钥。该服务使用此密钥向选定的 提供商认证请求。真正的密钥始终留在沙箱之外。

当你选择提供商时，Docker Sandboxes 会自动配置这种注入方式。这个工作流不需要 sbx secret set-custom，也不需要域名注入规则。

WARNING

模型提供商的凭据保护方式与其他沙箱凭据不同。对于其他凭据，代理会把注入限制在 它们配置的域名上。对于模型提供商，代理会把密钥交给宿主机的 llmman 服务。该服务 可能把密钥转发到它支持的其他端点；选择 --provider 并不会把密钥限制在该提供商的 端点上。

如果没有可用的已存储密钥，请在启动守护进程的那个宿主机 shell 中让密钥可用。对于自定义 端点，用 apiKeyEnv 选择变量名。

llmman 会继承守护进程的环境。在该环境中设置或更改密钥之后，请在包含更新后变量的 shell 中运行 sbx daemon restart。 这会重启模型服务，并中断正在使用它的沙箱发出的模型请求。只在运行 sbx run --model 的那个 shell 中设置变量，并不会更新已在运行的服务。

使用已存储的密钥可以避免为了从环境中加载密钥而重启守护进程。关于智能体的默认身份 验证流程，请参阅管理凭据。

连接自定义端点 ​

用 model.providers 连接兼容 OpenAI 或 Anthropic 的推理端点，例如内部的 GPU 服务器。 该端点必须能从你的宿主机访问。

该设置是一个以提供商 ID 为键的 JSON 对象。修改之前先查看它当前的值：

console
$ sbx settings get model.providers

对于兼容 OpenAI 的端点，定义一个名为 company 的提供商：

console
$ sbx settings set model.providers '{"company":{"url":"https://inference.example.com/v1","wire":"openai"}}'

请把 URL 替换为你的端点的基础 URL。设置 model.providers 会替换整个对象，因此要 包含你想保留的任何已有提供商。

字段说明
url必填的 HTTP 或 HTTPS 基础 URL，通常以 /v1 结尾。请使用基础 URL，不要带 /chat/completions 或 /messages。
wire端点的 API 格式：openai（默认）或 anthropic。它描述的是端点本身，与你运行哪个智能体无关。
apiKeyEnv一个可选的宿主机环境变量名称，其中包含 API 密钥。当没有已存储的提供商密钥时作为备用。
name可选的显示名称。默认为提供商 ID。

如果该端点需要 API 密钥，请用提供商 ID（company）存储它。当你用 --provider 选中 该提供商时，Docker Sandboxes 会配置身份验证：

console
$ sbx secret set company
$ sbx run --provider company --model <MODEL_NAME> claude

当你用 --model 运行时，Docker Sandboxes 会应用该提供商配置。你可以用同一个提供商 搭配 codex 或 opencode。

更改已有沙箱的模型 ​

传入沙箱名称和你的模型选择：

console
$ sbx run --name <SANDBOX_NAME> --model <MODEL_NAME> --provider <PROVIDER_ID>

更改模型会重新创建沙箱容器。工作区和 kit 所属的卷会保留。省略 --provider 可选择 由 llmman 管理的本地模型。

选择推理级别 ​

把 --variant 与 --model 一起使用，选择你的模型支持的推理级别。例如，把 <MODEL_NAME> 替换为一个支持 high 推理强度的 OpenAI 模型，即可让 Codex 以该级别 启动：

console
$ sbx run --provider openai --model <MODEL_NAME> --variant high codex

可用取值取决于模型和智能体。推理级别包括 minimal、low、medium、high、 xhigh 和 max。有些模型支持用 none 关闭思考，或用 thinking 开启思考。省略 --variant 则使用默认值。

Claude Code 不支持 none 和 minimal。对于 Claude Code 和 Codex，--variant 要求 有已连接的会话，且不能与 --detach 组合使用。在 OpenCode 中，它决定初始的 variant， 你可以在 OpenCode 内部更改。

用另一个提供商处理更大的请求 ​

把本地模型与另一个提供商搭配，用于处理超出本地模型上下文容量的请求：

console
$ sbx run --model gemma4 \
    --overflow-provider openai --overflow-model gpt-5-nano claude

启动模型服务之前，请配置提供商身份验证。你也可以使用 在 model.providers 中定义的提供商。两个溢出标志都是必需的，而且本地模型必须使用 默认的 llmman 提供商。该选项不能与 --provider ollama 或通过 --provider 选中的 托管提供商组合使用。

能放进本地模型的请求会留在本地。被路由到溢出提供商的请求会把其内容发送到该端点， 并可能产生提供商费用。