Docker 是可选的<\/strong>。仅当你想要容器化的 Gateway 网关或验证 Docker 流程时才使用它。<\/p>\n 本指南涵盖：<\/p>\n 沙箱隔离详情：沙箱隔离<\/a><\/p>\n 从仓库根目录：<\/p>\n “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} 注意：从仓库根目录运行 “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} 更多详情：仪表板<\/a>，设备<\/a>。<\/p>\n 如果你想将额外的主机目录挂载到容器中，在运行 示例：<\/p>\n “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} 你可以将其与额外挂载结合使用：<\/p>\n “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} 注意：<\/p>\n 默认的 Docker 镜像是安全优先<\/strong>的，以非 root 的 如果你想要功能更完整的容器，使用这些选择加入选项：<\/p>\n “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} 如果你选择以 root 运行以方便使用，你接受了安全权衡。<\/p>\n 要加速重建，排序你的 Dockerfile 以便依赖层被缓存。这避免了除非锁文件更改否则重新运行 “`dockerfile theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} RUN curl -fsSL https:\/\/bun.sh\/install | bash RUN corepack enable<\/p>\n WORKDIR \/app<\/p>\n COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc .\/ RUN pnpm install –frozen-lockfile<\/p>\n COPY . . ENV NODE_ENV=production<\/p>\n CMD [“node”,”dist\/index.js”]<\/p>\n Telegram（bot token）：<\/p>\n “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} 文档：WhatsApp<\/a>，Telegram<\/a>，Discord<\/a><\/p>\n 如果你在向导中选择 OpenAI Codex OAuth，它会打开浏览器 URL 并尝试在 “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} 加固选项位于 多智能体：通过 “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} 这构建 “`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} 这使用 注意：<\/p>\n 使用配置：<\/p>\n “`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} 启用后，智能体接收：<\/p>\n 记住：如果你使用工具允许列表，添加 构建你自己的镜像并将配置指向它：<\/p>\n “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} 两个选项：<\/p>\n 示例：<\/p>\nDocker 适合我吗？<\/h2>\n
\n
\n
要求<\/h2>\n
\n
容器化 Gateway 网关（Docker Compose）<\/h2>\n
快速开始（推荐）<\/h3>\n
\n.\/docker-setup.sh<\/p>\n\n此脚本：\n\n* 构建 Gateway 网关镜像\n* 运行新手引导向导\n* 打印可选的提供商设置提示\n* 通过 Docker Compose 启动 Gateway 网关\n* 生成 Gateway 网关令牌并写入 `.env`\n\n可选环境变量：\n\n* `OPENCLAW_DOCKER_APT_PACKAGES` — 在构建期间安装额外的 apt 包\n* `OPENCLAW_EXTRA_MOUNTS` — 添加额外的主机绑定挂载\n* `OPENCLAW_HOME_VOLUME` — 在命名卷中持久化 `\/home\/node`\n\n完成后：\n\n* 在浏览器中打开 `http:\/\/127.0.0.1:18789\/`。\n* 将令牌粘贴到控制 UI（设置 → token）。\n* 需要再次获取带令牌的 URL？运行 `docker compose run --rm openclaw-cli dashboard --no-open`。\n\n它在主机上写入配置\/工作区：\n\n* `~\/.openclaw\/`\n* `~\/.openclaw\/workspace`\n\n在 VPS 上运行？参阅 [Hetzner（Docker VPS）](\/install\/hetzner)。\n\n### 手动流程（compose）\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\ndocker build -t openclaw:local -f Dockerfile .\ndocker compose run --rm openclaw-cli onboard\ndocker compose up -d openclaw-gateway\n<\/code><\/pre>\ndocker compose ...<\/code>。如果你启用了 OPENCLAW_EXTRA_MOUNTS<\/code> 或 OPENCLAW_HOME_VOLUME<\/code>，设置脚本会写入 docker-compose.extra.yml<\/code>；在其他地方运行 Compose 时包含它：<\/p>\n
\ndocker compose -f docker-compose.yml -f docker-compose.extra.yml <\/p>\n\n### 控制 UI 令牌 + 配对（Docker）\n\n如果你看到\"unauthorized\"或\"disconnected (1008): pairing required\"，获取新的仪表板链接并批准浏览器设备：\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\ndocker compose run --rm openclaw-cli dashboard --no-open\ndocker compose run --rm openclaw-cli devices list\ndocker compose run --rm openclaw-cli devices approve <requestId>\n<\/code><\/pre>\n额外挂载（可选）<\/h3>\n
docker-setup.sh<\/code> 之前设置 OPENCLAW_EXTRA_MOUNTS<\/code>。这接受逗号分隔的 Docker 绑定挂载列表，并通过生成 docker-compose.extra.yml<\/code> 将它们应用到 openclaw-gateway<\/code> 和 openclaw-cli<\/code>。<\/p>\n
\nexport OPENCLAW_EXTRA_MOUNTS=”$HOME\/.codex:\/home\/node\/.codex:ro,$HOME\/github:\/home\/node\/github:rw”
\n.\/docker-setup.sh<\/p>\n\n注意：\n\n* 路径必须在 macOS\/Windows 上与 Docker Desktop 共享。\n* 如果你编辑 `OPENCLAW_EXTRA_MOUNTS`，重新运行 `docker-setup.sh` 以重新生成额外的 compose 文件。\n* `docker-compose.extra.yml` 是生成的。不要手动编辑它。\n\n### 持久化整个容器 home（可选）\n\n如果你想让 `\/home\/node` 在容器重建后持久化，通过 `OPENCLAW_HOME_VOLUME` 设置一个命名卷。这会创建一个 Docker 卷并将其挂载到 `\/home\/node`，同时保持标准的配置\/工作区绑定挂载。这里使用命名卷（不是绑定路径）；对于绑定挂载，使用 `OPENCLAW_EXTRA_MOUNTS`。\n\n示例：\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\nexport OPENCLAW_HOME_VOLUME=\"openclaw_home\"\n.\/docker-setup.sh\n<\/code><\/pre>\n
\nexport OPENCLAW_HOME_VOLUME=”openclaw_home”
\nexport OPENCLAW_EXTRA_MOUNTS=”$HOME\/.codex:\/home\/node\/.codex:ro,$HOME\/github:\/home\/node\/github:rw”
\n.\/docker-setup.sh<\/p>\n\n注意：\n\n* 如果你更改 `OPENCLAW_HOME_VOLUME`，重新运行 `docker-setup.sh` 以重新生成额外的 compose 文件。\n* 命名卷会持久化直到使用 `docker volume rm <name>` 删除。\n\n### 安装额外的 apt 包（可选）\n\n如果你需要镜像内的系统包（例如构建工具或媒体库），在运行 `docker-setup.sh` 之前设置 `OPENCLAW_DOCKER_APT_PACKAGES`。这会在镜像构建期间安装包，因此即使容器被删除它们也会持久化。\n\n示例：\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\nexport OPENCLAW_DOCKER_APT_PACKAGES=\"ffmpeg build-essential\"\n.\/docker-setup.sh\n<\/code><\/pre>\n\n
OPENCLAW_DOCKER_APT_PACKAGES<\/code>，重新运行 docker-setup.sh<\/code> 以重建镜像。<\/li>\n<\/ul>\n高级用户\/功能完整的容器（选择加入）<\/h3>\n
node<\/code> 用户运行。这保持了较小的攻击面，但这意味着：<\/p>\n\n
\n
\/home\/node<\/code><\/strong> 以便浏览器下载和工具缓存能够保留：<\/li>\n<\/ol>\n
\nexport OPENCLAW_HOME_VOLUME=”openclaw_home”
\n.\/docker-setup.sh<\/p>\n\n2. **将系统依赖烘焙到镜像中**（可重复 + 持久化）：\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\nexport OPENCLAW_DOCKER_APT_PACKAGES=\"git curl jq\"\n.\/docker-setup.sh\n<\/code><\/pre>\n\n
npx<\/code> 安装 Playwright 浏览器<\/strong>（避免 npm 覆盖冲突）：<\/li>\n<\/ol>\n
\ndocker compose run –rm openclaw-cli
\n node \/app\/node_modules\/playwright-core\/cli.js install chromium<\/p>\n\n如果你需要 Playwright 安装系统依赖，使用 `OPENCLAW_DOCKER_APT_PACKAGES` 重建镜像，而不是在运行时使用 `--with-deps`。\n\n4. **持久化 Playwright 浏览器下载**：\n\n* 在 `docker-compose.yml` 中设置 `PLAYWRIGHT_BROWSERS_PATH=\/home\/node\/.cache\/ms-playwright`。\n* 确保 `\/home\/node` 通过 `OPENCLAW_HOME_VOLUME` 持久化，或通过 `OPENCLAW_EXTRA_MOUNTS` 挂载 `\/home\/node\/.cache\/ms-playwright`。\n\n### 权限 + EACCES\n\n镜像以 `node`（uid 1000）运行。如果你在 `\/home\/node\/.openclaw` 上看到权限错误，确保你的主机绑定挂载由 uid 1000 拥有。\n\n示例（Linux 主机）：\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\nsudo chown -R 1000:1000 \/path\/to\/openclaw-config \/path\/to\/openclaw-workspace\n<\/code><\/pre>\n更快的重建（推荐）<\/h3>\n
pnpm install<\/code>：<\/p>\n
\nFROM node:22-bookworm<\/p>\n安装 Bun（构建脚本需要）<\/h1>\n
\nENV PATH=”\/root\/.bun\/bin:${PATH}”<\/p>\n缓存依赖，除非包元数据更改<\/h1>\n
\nCOPY ui\/package.json .\/ui\/package.json
\nCOPY scripts .\/scripts<\/p>\n
\nRUN pnpm build
\nRUN pnpm ui:install
\nRUN pnpm ui:build<\/p>\n\n### 渠道设置（可选）\n\n使用 CLI 容器配置渠道，然后在需要时重启 Gateway 网关。\n\nWhatsApp（QR）：\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\ndocker compose run --rm openclaw-cli channels login\n<\/code><\/pre>\n
\ndocker compose run –rm openclaw-cli channels add –channel telegram –token “”<\/p>\n\nDiscord（bot token）：\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\ndocker compose run --rm openclaw-cli channels add --channel discord --token \"<token>\"\n<\/code><\/pre>\nOpenAI Codex OAuth（无头 Docker）<\/h3>\n
http:\/\/127.0.0.1:1455\/auth\/callback<\/code> 捕获回调。在 Docker 或无头设置中，该回调可能显示浏览器错误。复制你到达的完整重定向 URL 并将其粘贴回向导以完成认证。<\/p>\n健康检查<\/h3>\n
\ndocker compose exec openclaw-gateway node dist\/index.js health –token “$OPENCLAW_GATEWAY_TOKEN”<\/p>\n\n### E2E 冒烟测试（Docker）\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\nscripts\/e2e\/onboard-docker.sh\n<\/code><\/pre>\nQR 导入冒烟测试（Docker）<\/h3>\n
\npnpm test:docker:qr<\/p>\n\n### 注意\n\n* Gateway 网关绑定默认为 `lan` 用于容器使用。\n* Dockerfile CMD 使用 `--allow-unconfigured`；挂载的配置如果 `gateway.mode` 不是 `local` 仍会启动。覆盖 CMD 以强制执行检查。\n* Gateway 网关容器是会话的真实来源（`~\/.openclaw\/agents\/<agentId>\/sessions\/`）。\n\n## 智能体沙箱（主机 Gateway 网关 + Docker 工具）\n\n深入了解：[沙箱隔离](\/gateway\/sandboxing)\n\n### 它做什么\n\n当启用 `agents.defaults.sandbox` 时，**非主会话**在 Docker 容器内运行工具。Gateway 网关保持在你的主机上，但工具执行是隔离的：\n\n* scope：默认为 `\"agent\"`（每个智能体一个容器 + 工作区）\n* scope：`\"session\"` 用于每会话隔离\n* 每作用域工作区文件夹挂载在 `\/workspace`\n* 可选的智能体工作区访问（`agents.defaults.sandbox.workspaceAccess`）\n* 允许\/拒绝工具策略（拒绝优先）\n* 入站媒体被复制到活动沙箱工作区（`media\/inbound\/*`），以便工具可以读取它（使用 `workspaceAccess: \"rw\"` 时，这会落在智能体工作区中）\n\n警告：`scope: \"shared\"` 禁用跨会话隔离。所有会话共享一个容器和一个工作区。\n\n### 每智能体沙箱配置文件（多智能体）\n\n如果你使用多智能体路由，每个智能体可以覆盖沙箱 + 工具设置：`agents.list[].sandbox` 和 `agents.list[].tools`（加上 `agents.list[].tools.sandbox.tools`）。这让你可以在一个 Gateway 网关中运行混合访问级别：\n\n* 完全访问（个人智能体）\n* 只读工具 + 只读工作区（家庭\/工作智能体）\n* 无文件系统\/shell 工具（公共智能体）\n\n参阅[多智能体沙箱与工具](\/tools\/multi-agent-sandbox-tools)了解示例、优先级和故障排除。\n\n### 默认行为\n\n* 镜像：`openclaw-sandbox:bookworm-slim`\n* 每个智能体一个容器\n* 智能体工作区访问：`workspaceAccess: \"none\"`（默认）使用 `~\/.openclaw\/sandboxes`\n * `\"ro\"` 保持沙箱工作区在 `\/workspace` 并将智能体工作区只读挂载在 `\/agent`（禁用 `write`\/`edit`\/`apply_patch`）\n * `\"rw\"` 将智能体工作区读写挂载在 `\/workspace`\n* 自动清理：空闲 > 24h 或 年龄 > 7d\n* 网络：默认为 `none`（如果需要出站则明确选择加入）\n* 默认允许：`exec`、`process`、`read`、`write`、`edit`、`sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`session_status`\n* 默认拒绝：`browser`、`canvas`、`nodes`、`cron`、`discord`、`gateway`\n\n### 启用沙箱隔离\n\n如果你计划在 `setupCommand` 中安装包，请注意：\n\n* 默认 `docker.network` 是 `\"none\"`（无出站）。\n* `readOnlyRoot: true` 阻止包安装。\n* `user` 必须是 root 才能运行 `apt-get`（省略 `user` 或设置 `user: \"0:0\"`）。\n 当 `setupCommand`（或 docker 配置）更改时，OpenClaw 会自动重建容器，除非容器是**最近使用的**（在约 5 分钟内）。热容器会记录警告，包含确切的 `openclaw sandbox recreate ...` 命令。\n\n```json5 theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\n{\n agents: {\n defaults: {\n sandbox: {\n mode: \"non-main\", \/\/ off | non-main | all\n scope: \"agent\", \/\/ session | agent | shared（默认为 agent）\n workspaceAccess: \"none\", \/\/ none | ro | rw\n workspaceRoot: \"~\/.openclaw\/sandboxes\",\n docker: {\n image: \"openclaw-sandbox:bookworm-slim\",\n workdir: \"\/workspace\",\n readOnlyRoot: true,\n tmpfs: [\"\/tmp\", \"\/var\/tmp\", \"\/run\"],\n network: \"none\",\n user: \"1000:1000\",\n capDrop: [\"ALL\"],\n env: { LANG: \"C.UTF-8\" },\n setupCommand: \"apt-get update && apt-get install -y git curl jq\",\n pidsLimit: 256,\n memory: \"1g\",\n memorySwap: \"2g\",\n cpus: 1,\n ulimits: {\n nofile: { soft: 1024, hard: 2048 },\n nproc: 256,\n },\n seccompProfile: \"\/path\/to\/seccomp.json\",\n apparmorProfile: \"openclaw-sandbox\",\n dns: [\"1.1.1.1\", \"8.8.8.8\"],\n extraHosts: [\"internal.service:10.0.0.5\"],\n },\n prune: {\n idleHours: 24, \/\/ 0 禁用空闲清理\n maxAgeDays: 7, \/\/ 0 禁用最大年龄清理\n },\n },\n },\n },\n tools: {\n sandbox: {\n tools: {\n allow: [\n \"exec\",\n \"process\",\n \"read\",\n \"write\",\n \"edit\",\n \"sessions_list\",\n \"sessions_history\",\n \"sessions_send\",\n \"sessions_spawn\",\n \"session_status\",\n ],\n deny: [\"browser\", \"canvas\", \"nodes\", \"cron\", \"discord\", \"gateway\"],\n },\n },\n },\n}\n<\/code><\/pre>\nagents.defaults.sandbox.docker<\/code> 下：network<\/code>、user<\/code>、pidsLimit<\/code>、memory<\/code>、memorySwap<\/code>、cpus<\/code>、ulimits<\/code>、seccompProfile<\/code>、apparmorProfile<\/code>、dns<\/code>、extraHosts<\/code>。<\/p>\nagents.list[].sandbox.{docker,browser,prune}.*<\/code> 按智能体覆盖 agents.defaults.sandbox.{docker,browser,prune}.*<\/code>（当 agents.defaults.sandbox.scope<\/code> \/ agents.list[].sandbox.scope<\/code> 是 \"shared\"<\/code> 时忽略）。<\/p>\n构建默认沙箱镜像<\/h3>\n
\nscripts\/sandbox-setup.sh<\/p>\n\n这使用 `Dockerfile.sandbox` 构建 `openclaw-sandbox:bookworm-slim`。\n\n### 沙箱通用镜像（可选）\n\n如果你想要一个带有常见构建工具（Node、Go、Rust 等）的沙箱镜像，构建通用镜像：\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\nscripts\/sandbox-common-setup.sh\n<\/code><\/pre>\nopenclaw-sandbox-common:bookworm-slim<\/code>。要使用它：<\/p>\n
\n{
\n agents: {
\n defaults: {
\n sandbox: { docker: { image: “openclaw-sandbox-common:bookworm-slim” } },
\n },
\n },
\n}<\/p>\n\n### 沙箱浏览器镜像\n\n要在沙箱内运行浏览器工具，构建浏览器镜像：\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\nscripts\/sandbox-browser-setup.sh\n<\/code><\/pre>\nDockerfile.sandbox-browser<\/code> 构建 openclaw-sandbox-browser:bookworm-slim<\/code>。容器运行启用 CDP 的 Chromium 和可选的 noVNC 观察器（通过 Xvfb 有头）。<\/p>\n\n
agents.defaults.sandbox.browser.headless=true<\/code> 仍然可以使用无头模式。<\/li>\n
\n{
\n agents: {
\n defaults: {
\n sandbox: {
\n browser: { enabled: true },
\n },
\n },
\n },
\n}<\/p>\n\n自定义浏览器镜像：\n\n```json5 theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\n{\n agents: {\n defaults: {\n sandbox: { browser: { image: \"my-openclaw-browser\" } },\n },\n },\n}\n<\/code><\/pre>\n\n
browser<\/code> 工具）<\/li>\nbrowser<\/code>（并从拒绝中移除它）否则工具仍然被阻止。
\n清理规则（agents.defaults.sandbox.prune<\/code>）也适用于浏览器容器。<\/p>\n自定义沙箱镜像<\/h3>\n
\ndocker build -t my-openclaw-sbx -f Dockerfile.sandbox .<\/p>\n\n```json5 theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\n{\n agents: {\n defaults: {\n sandbox: { docker: { image: \"my-openclaw-sbx\" } },\n },\n },\n}\n<\/code><\/pre>\n工具策略（允许\/拒绝）<\/h3>\n
\n
deny<\/code> 优先于 allow<\/code>。<\/li>\nallow<\/code> 为空：所有工具（除了 deny）都可用。<\/li>\nallow<\/code> 非空：只有 allow<\/code> 中的工具可用（减去 deny）。<\/li>\n<\/ul>\n清理策略<\/h3>\n
\n
prune.idleHours<\/code>：移除 X 小时未使用的容器（0 = 禁用）<\/li>\nprune.maxAgeDays<\/code>：移除超过 X 天的容器（0 = 禁用）<\/li>\n<\/ul>\n\n
\n idleHours: 24<\/code>、maxAgeDays: 7<\/code><\/li>\n
\n idleHours: 0<\/code>、maxAgeDays: 0<\/code><\/li>\n<\/ul>\n安全注意事项<\/h3>\n