Docker Sandboxes

本页介绍的是本地沙箱。有关云端行为及其限制，请参阅对比本地沙箱与云沙箱。

本指南介绍在沙箱环境中对 OpenCode 进行身份验证、配置和使用的方法。

官方文档：OpenCode

快速开始 ​

创建沙箱，并为项目目录运行 OpenCode：

console
$ sbx run opencode ~/my-project

sbx run 默认把工作区设为当前目录：

console
$ cd ~/my-project
$ sbx run opencode

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

OpenCode 会启动一个 TUI（文本用户界面），你可以在其中选择偏好的 LLM 提供商，并与 智能体交互。

身份验证 ​

OpenCode 支持多家提供商。用存储的密钥 保存你想使用的提供商的密钥：

console
$ sbx secret set openai
$ sbx secret set anthropic
$ sbx secret set google
$ sbx secret set xai
$ sbx secret set groq
$ sbx secret set aws
$ sbx secret set openrouter

你只需配置想使用的提供商。OpenCode 会检测可用的凭据，并在 TUI 中提供这些提供商。

GitHub Copilot ​

要在 OpenCode 中使用 GitHub Copilot 模型，请为一个拥有 Copilot 访问权限的账户配置 GitHub 凭据。OpenCode 启动时，Docker Sandboxes 会用该凭据配置它的 GitHub Copilot 提供商。你无需在 OpenCode 内部单独 进行设备登录。

OpenCode Zen API 密钥 ​

OpenCode Zen API 密钥不属于 sbx secret set 支持的内置 OpenCode 凭据。要使用 OpenCode Zen API 密钥，请将其保存为自定义密钥：

在宿主机上设置 OPENCODE_API_KEY 环境变量，然后保存它：

console
$ printf '%s' "$OPENCODE_API_KEY" | sbx secret set-custom \
    --host opencode.ai \
    --env OPENCODE_API_KEY \
    --value-stdin

自定义密钥会把真实密钥保留在宿主机的密钥存储中。沙箱收到的是 OPENCODE_API_KEY 占位符，宿主机侧的代理会在发往 opencode.ai 的请求中用真实密钥替换该占位符。

OpenCode Zen 还需要访问 opencode.ai 的网络权限：

console
$ sbx policy allow network opencode.ai:443

如果你添加了全局自定义密钥，请重建现有的 OpenCode 沙箱，让新的环境变量在沙箱内 生效。

模型选择 ​

要用 sbx run --model 选择本地模型或推理端点，请参阅 使用本地模型和托管模型。

使用 --model 时，该模型支持的思考级别会作为 OpenCode 的各个变体提供。按 Ctrl+T 可以在它们之间切换。

配置 ​

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

OpenCode 使用 TUI 界面，不需要大量配置文件。智能体启动时会提示你选择提供商，你 也可以在会话过程中切换提供商。

默认启动命令 ​

沙箱运行 opencode 时不带任何隐式标志。-- 之后的参数会原样透传。例如，要恢复 已有会话：

console
$ sbx run --name <sandbox-name> -- -s <session-id>

TUI 模式 ​

OpenCode 默认以 TUI 模式启动。该界面会显示：

  • 可用的 LLM 提供商（取决于已配置的凭据）
  • 当前的对话历史
  • 文件操作和工具使用情况
  • 智能体的实时响应

使用键盘快捷键在界面中导航并与智能体交互。

基础镜像 ​

模板：docker/sandbox-templates:opencode

OpenCode 支持多家 LLM 提供商，密钥会通过沙箱代理自动注入。

有关预装工具或自定义此环境，请参阅自定义。