AI创想

标题: OpenClaw从入门到应用——安装：Docker [打印本页]

---

作者: 米落枫    时间: 昨天 07:41
标题: OpenClaw从入门到应用——安装：Docker
作者：von  Neumann
通过OpenClaw实现副业收入：《OpenClaw赚钱实录：从“养龙虾“到可持续变现的实践指南》
Docker 适合我吗？

是的：您需要一个隔离的、可随时丢弃的网关环境，或者想在没有本地安装的主机上运行 OpenClaw。否：您在本地机器上运行，只想要最快的开发循环。请改用正常的安装流程。沙箱说明：代理沙箱也使用 Docker，但不要求整个网关都在 Docker 中运行。请参阅沙箱。

本指南涵盖：

容器化网关（Docker 中的完整 OpenClaw）按会话的代理沙箱（主机网关 + Docker 隔离的代理工具）

沙箱详情：沙箱
要求

Docker Desktop (或 Docker Engine) + Docker Compose v2至少 2 GB 内存用于镜像构建（pnpm install 在 1 GB 内存主机上可能因 OOM 被终止，退出码为 137）足够的磁盘空间用于镜像和日志如果在 VPS/公共主机上运行，请查阅
网络暴露的安全加固，
特别是 Docker 的 DOCKER-USER 防火墙策略。

容器化网关 (Docker Compose)

快速启动（推荐）

这里的 Docker 默认值假定使用绑定模式 (lan/loopback)，而不是主机别名。在 gateway.bind 中使用绑定模式值（例如 lan 或 loopback），而不是像 0.0.0.0 或 localhost 这样的主机别名。

从仓库根目录运行：

1. ./docker-setup.sh

复制代码

此脚本将：

在本地构建网关镜像（如果设置了 OPENCLAW_IMAGE，则拉取远程镜像）运行入门向导打印可选的提供商设置提示通过 Docker Compose 启动网关生成网关令牌并将其写入 .env

可选的环境变量：

OPENCLAW_IMAGE — 使用远程镜像而不是在本地构建（例如 ghcr.io/openclaw/openclaw:latest）OPENCLAW_DOCKER_APT_PACKAGES — 在构建期间安装额外的 apt 软件包OPENCLAW_EXTENSIONS — 在构建时预安装扩展依赖项（空格分隔的扩展名，例如 diagnostics-otel matrix）OPENCLAW_EXTRA_MOUNTS — 添加额外的主机绑定挂载OPENCLAW_HOME_VOLUME — 在命名卷中持久化 /home/nodeOPENCLAW_SANDBOX — 选择启用 Docker 网关沙箱引导。只有明确的真值才能启用它：1、true、yes、onOPENCLAW_INSTALL_DOCKER_CLI — 用于本地镜像构建的构建参数传递（1 在镜像中安装 Docker CLI）。当 OPENCLAW_SANDBOX=1 进行本地构建时，docker-setup.sh 会自动设置此变量。OPENCLAW_DOCKER_SOCKET — 覆盖 Docker 套接字路径（默认：DOCKER_HOST=unix://... 路径，否则为 /var/run/docker.sock）OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 — 紧急开关：允许受信任的私有网络 ws:// 目标用于 CLI/入门客户端路径（默认为仅限回环）OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 — 禁用容器浏览器加固标志 --disable-3d-apis、--disable-software-rasterizer、--disable-gpu，当您需要 WebGL/3D 兼容性时。OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 — 当浏览器流程需要时，保持扩展启用（默认在沙箱浏览器中保持扩展禁用）。OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT= — 设置 Chromium 渲染进程限制；设置为 0 以跳过该标志并使用 Chromium 的默认行为。

完成后：

在浏览器中打开 http://127.0.0.1:18789/。将令牌粘贴到控制 UI 中（设置 → 令牌）。再次需要 URL？运行 docker compose run --rm openclaw-cli dashboard --no-open。

为 Docker 网关启用代理沙箱（选择加入）

docker-setup.sh 也可以为 Docker 部署引导 agents.defaults.sandbox.*。
启用方法：

1. exportOPENCLAW_SANDBOX=1
2. ./docker-setup.sh

复制代码

自定义套接字路径（例如无根 Docker）：

1. exportOPENCLAW_SANDBOX=1exportOPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
2. ./docker-setup.sh

复制代码

注意：

脚本仅在沙箱前提条件通过后挂载 docker.sock。如果无法完成沙箱设置，脚本会将 agents.defaults.sandbox.mode 重置为 off，以避免在重新运行时出现陈旧/损坏的沙箱配置。如果缺少 Dockerfile.sandbox，脚本会打印警告并继续运行；如果需要，使用 scripts/sandbox-setup.sh 构建 openclaw-sandbox:bookworm-slim。对于非本地的 OPENCLAW_IMAGE 值，镜像必须已包含 Docker CLI 支持才能执行沙箱。

自动化/CI（非交互式，无 TTY 噪音）

对于脚本和 CI，使用 -T 禁用 Compose 伪终端分配：

1. docker compose run -T--rm openclaw-cli gateway probe
2. docker compose run -T--rm openclaw-cli devices list --json

复制代码

如果您的自动化没有导出 Claude 会话变量，现在它们在 docker-compose.yml 中默认保持未设置状态，将解析为空值，以避免重复的“变量未设置”警告。
共享网络安全说明（CLI + 网关）

openclaw-cli 使用 network_mode: "service:openclaw-gateway"，以便 CLI 命令可以可靠地通过 Docker 内的 127.0.0.1 访问网关。
将此视为一个共享的信任边界：回环绑定不是这两个容器之间的隔离。如果您需要更强的分离，请从单独的容器/主机网络路径运行命令，而不是使用捆绑的 openclaw-cli 服务。
为了在 CLI 进程被攻破时减少影响，compose 配置删除了 NET_RAW/NET_ADMIN 并在 openclaw-cli 上启用了 no-new-privileges。
它将配置/工作区写入主机：

~/.openclaw/~/.openclaw/workspace

在 VPS 上运行？请参阅 Hetzner (Docker VPS)。
使用远程镜像（跳过本地构建）

官方预构建镜像发布在：

GitHub 容器注册表包

使用镜像名称 ghcr.io/openclaw/openclaw（不要使用名称相似的 Docker Hub 镜像）。
常见标签：

main — 从 main 分支构建的最新版本`` — 发布标签构建（例如 2026.2.26）latest — 最新的稳定发布标签

基础镜像元数据

主 Docker 镜像当前使用：

node:24-bookworm

docker 镜像现在发布 OCI 基础镜像注解（sha256 是示例，指向该标签的固定多架构清单列表）：

org.opencontainers.image.base.name=docker.io/library/node:24-bookwormorg.opencontainers.image.base.digest=sha256:3a09aa6354567619221ef6c45a5051b671f953f0a1924d1f819ffb236e520e6borg.opencontainers.image.source=https://github.com/openclaw/openclaworg.opencontainers.image.url=https://openclaw.aiorg.opencontainers.image.documentation=https://docs.openclaw.ai/install/dockerorg.opencontainers.image.licenses=MITorg.opencontainers.image.title=OpenClaworg.opencontainers.image.description=OpenClaw 网关和 CLI 运行时容器镜像org.opencontainers.image.revision=org.opencontainers.image.version=org.opencontainers.image.created=

参考：OCI 镜像注解
发布上下文：此仓库的标记历史已在 v2026.2.22 及更早的 2026 标签（例如 v2026.2.21、v2026.2.9）中使用 Bookworm。
默认情况下，设置脚本从源代码构建镜像。要改为拉取预构建镜像，请在运行脚本前设置 OPENCLAW_IMAGE：

1. exportOPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
2. ./docker-setup.sh

复制代码

脚本检测到 OPENCLAW_IMAGE 不是默认的 openclaw:local，并运行 docker pull 而不是 docker build。其他所有操作（入门、网关启动、令牌生成）都以相同方式工作。
docker-setup.sh 仍然从仓库根目录运行，因为它使用本地的 docker-compose.yml 和辅助文件。OPENCLAW_IMAGE 跳过本地镜像构建时间；它不会取代 compose/设置工作流。
Shell 助手（可选）

为了更轻松地进行日常 Docker 管理，请安装 ClawDock：

1. mkdir-p ~/.clawdock &&curl-sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

复制代码

添加到您的 shell 配置 (zsh)：

1. echo'source ~/.clawdock/clawdock-helpers.sh'>> ~/.zshrc &&source ~/.zshrc

复制代码

然后使用 clawdock-start、clawdock-stop、clawdock-dashboard 等。运行 clawdock-help 查看所有命令。
有关详细信息，请参阅 ClawDock 助手自述文件。
手动流程（compose）

1. docker build -t openclaw:local -f Dockerfile .docker compose run --rm openclaw-cli onboard
2. docker compose up -d openclaw-gateway

复制代码

注意：从仓库根目录运行 docker compose ...。如果您启用了 OPENCLAW_EXTRA_MOUNTS 或 OPENCLAW_HOME_VOLUME，设置脚本会写入 docker-compose.extra.yml；在其他地方运行 Compose 时请包含它：

1. docker compose -f docker-compose.yml -f docker-compose.extra.yml

复制代码

控制 UI 令牌 + 配对（Docker）

如果您看到“未授权”或“已断开连接 (1008): 需要配对”，请获取新的仪表板链接并批准浏览器设备：

1. docker compose run --rm openclaw-cli dashboard --no-open
2. docker compose run --rm openclaw-cli devices list
3. docker compose run --rm openclaw-cli devices approve

复制代码

更多详情：仪表板、设备。
额外挂载（可选）

如果您想将额外的主机目录挂载到容器中，请在运行 docker-setup.sh 之前设置 OPENCLAW_EXTRA_MOUNTS。它接受一个逗号分隔的 Docker 绑定挂载列表，并通过生成 docker-compose.extra.yml 将它们同时应用于 openclaw-gateway 和 openclaw-cli。
示例：

1. exportOPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
2. ./docker-setup.sh

复制代码

注意：

路径必须与 macOS/Windows 上的 Docker Desktop 共享。每个条目必须是 source:target[:options]，没有空格、制表符或换行符。如果您编辑了 OPENCLAW_EXTRA_MOUNTS，请重新运行 docker-setup.sh 以重新生成额外的 compose 文件。docker-compose.extra.yml 是生成的。请勿手动编辑。

持久化整个容器的主目录（可选）

如果您希望 /home/node 在容器重新创建后仍然存在，请通过 OPENCLAW_HOME_VOLUME 设置一个命名卷。这将创建一个 Docker 卷并将其挂载到 /home/node，同时保留标准的配置/工作区绑定挂载。此处使用命名卷（而不是绑定路径）；对于绑定挂载，请使用 OPENCLAW_EXTRA_MOUNTS。
示例：

1. exportOPENCLAW_HOME_VOLUME="openclaw_home"
2. ./docker-setup.sh

复制代码

您可以将其与额外挂载结合使用：

1. exportOPENCLAW_HOME_VOLUME="openclaw_home"exportOPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
2. ./docker-setup.sh

复制代码

注意：

命名卷必须匹配 ^[A-Za-z0-9][A-Za-z0-9_.-]*$。如果您更改了 OPENCLAW_HOME_VOLUME，请重新运行 docker-setup.sh 以重新生成额外的 compose 文件。命名卷会一直存在，直到使用 docker volume rm  将其删除。

安装额外的 apt 软件包（可选）

如果您在镜像中需要系统软件包（例如，构建工具或媒体库），请在运行 docker-setup.sh 之前设置 OPENCLAW_DOCKER_APT_PACKAGES。这会在镜像构建期间安装这些软件包，因此即使容器被删除，它们也会保留。
示例：

1. exportOPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
2. ./docker-setup.sh

复制代码

注意：

这接受一个空格分隔的 apt 软件包名称列表。如果您更改了 OPENCLAW_DOCKER_APT_PACKAGES，请重新运行 docker-setup.sh 以重建镜像。

预安装扩展依赖项（可选）

具有自己 package.json 的扩展（例如 diagnostics-otel、matrix、msteams）会在首次加载时安装它们的 npm 依赖项。要将这些依赖项预先构建到镜像中，请在运行 docker-setup.sh 之前设置 OPENCLAW_EXTENSIONS：

1. exportOPENCLAW_EXTENSIONS="diagnostics-otel matrix"
2. ./docker-setup.sh

复制代码

或者直接构建时：

1. docker build --build-arg OPENCLAW_EXTENSIONS="diagnostics-otel matrix".

复制代码

注意：

这接受一个空格分隔的扩展目录名称列表（位于 extensions/ 下）。只有带有 package.json 的扩展会受影响；没有该文件的轻量级插件将被忽略。如果您更改了 OPENCLAW_EXTENSIONS，请重新运行 docker-setup.sh 以重建镜像。

高级用户/功能齐全的容器（选择加入）

默认的 Docker 镜像是安全优先的，以非 root 用户 node 运行。这保持了较小的攻击面，但意味着：

运行时无法安装系统软件包默认没有 Homebrew没有捆绑的 Chromium/Playwright 浏览器

如果您想要一个功能更齐全的容器，请使用这些选择加入的选项：

持久化 /home/node 以便浏览器下载和工具缓存得以保留：

1. exportOPENCLAW_HOME_VOLUME="openclaw_home"
2. ./docker-setup.sh

复制代码

将系统依赖项内置到镜像中（可重复 + 持久化）：

1. exportOPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
2. ./docker-setup.sh

复制代码

无需 npx 安装 Playwright 浏览器（避免 npm 覆盖冲突）：

1. docker compose run --rm openclaw-cli \node /app/node_modules/playwright-core/cli.js install chromium

复制代码

如果您需要 Playwright 安装系统依赖项，请使用 OPENCLAW_DOCKER_APT_PACKAGES 重建镜像，而不是在运行时使用 --with-deps。

持久化 Playwright 浏览器下载：

在 docker-compose.yml 中设置 PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright。通过 OPENCLAW_HOME_VOLUME 确保持久化 /home/node，或通过 OPENCLAW_EXTRA_MOUNTS 挂载 /home/node/.cache/ms-playwright。

权限 + EACCES

镜像以 node 用户（uid 1000）运行。如果您在 /home/node/.openclaw 上看到权限错误，请确保您的主机绑定挂载由 uid 1000 拥有。
示例（Linux 主机）：

1. sudochown-R1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

复制代码

如果您为了方便而选择以 root 身份运行，则需接受相应的安全权衡。
更快的重建（推荐）

为了加快重建速度，请安排您的 Dockerfile 顺序，以便缓存依赖层。这可以避免重新运行 pnpm install，除非锁文件发生更改：

1. FROM node:24-bookworm
3. # 安装 Bun（构建脚本所需）
4. RUN curl -fsSL https://bun.sh/install | bash
5. ENV PATH="/root/.bun/bin:${PATH}"
7. RUN corepack enable
9. WORKDIR /app
11. # 除非包元数据更改，否则缓存依赖项
12. COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
13. COPY ui/package.json ./ui/package.json
14. COPY scripts ./scripts
16. RUN pnpm install --frozen-lockfile
18. COPY . .
19. RUN pnpm build
20. RUN pnpm ui:install
21. RUN pnpm ui:build
23. ENV NODE_ENV=production
25. CMD ["node","dist/index.js"]

复制代码

渠道设置（可选）

使用 CLI 容器配置渠道，然后根据需要重启网关。
WhatsApp (QR)：

1. docker compose run --rm openclaw-cli channels login

复制代码

Telegram (机器人令牌)：

1. docker compose run --rm openclaw-cli channels add--channel telegram --token""

复制代码

Discord (机器人令牌)：

1. docker compose run --rm openclaw-cli channels add--channel discord --token""

复制代码

文档：WhatsApp、Telegram、Discord
OpenAI Codex OAuth（无头 Docker）

如果您在向导中选择 OpenAI Codex OAuth，它会打开一个浏览器 URL 并尝试捕获 http://127.0.0.1:1455/auth/callback 上的回调。在 Docker 或无头设置中，该回调可能会显示浏览器错误。将您进入的完整重定向 URL 复制并粘贴回向导中以完成身份验证。
健康检查

容器探针端点（无需身份验证）：

1. curl-fsS http://127.0.0.1:18789/healthz
2. curl-fsS http://127.0.0.1:18789/readyz

复制代码

别名：/health 和 /ready。
/healthz 是一个浅层的存活探针，用于检测“网关进程是否正在运行”。
/readyz 在启动宽限期内保持就绪状态，然后仅在必需的托管渠道在宽限期后仍未连接或稍后断开连接时才变为 503。
Docker 镜像包含一个内置的 HEALTHCHECK，它在后台 ping /healthz。简单来说：Docker 会持续检查 OpenClaw 是否仍有响应。如果检查持续失败，Docker 会将容器标记为 unhealthy，编排系统（Docker Compose 重启策略、Swarm、Kubernetes 等）可以自动重启或替换它。
经过身份验证的深度健康快照（网关 + 渠道）：

1. docker compose exec openclaw-gateway node dist/index.js health --token"$OPENCLAW_GATEWAY_TOKEN"

复制代码

E2E 冒烟测试（Docker）

1. scripts/e2e/onboard-docker.sh

复制代码

QR 导入冒烟测试（Docker）

1. pnpm test:docker:qr

复制代码

LAN 与回环（Docker Compose）

docker-setup.sh 默认 OPENCLAW_GATEWAY_BIND=lan，以便主机访问 http://127.0.0.1:18789 能够与 Docker 端口发布配合使用。

lan（默认）：主机浏览器 + 主机 CLI 可以访问已发布的网关端口。loopback：只有容器网络命名空间内的进程可以直接访问网关；主机发布的端口访问可能失败。

设置脚本还在入门后固定 gateway.mode=local，以便 Docker CLI 命令默认以本地回环为目标。
遗留配置说明：在 gateway.bind 中使用绑定模式值（lan / loopback / custom / tailnet / auto），而不是主机别名（0.0.0.0、127.0.0.1、localhost、::、::1）。
如果您从 Docker CLI 命令中看到 Gateway target: ws://172.x.x.x:18789 或重复出现的 pairing required 错误，请运行：

1. docker compose run --rm openclaw-cli config set gateway.mode localdocker compose run --rm openclaw-cli config set gateway.bind lan
2. docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

复制代码

注意事项

网关绑定默认为 lan 以用于容器（OPENCLAW_GATEWAY_BIND）。Dockerfile CMD 使用 --allow-unconfigured；如果挂载的配置中 gateway.mode 不是 local，网关仍会启动。覆盖 CMD 以强制执行此检查。网关容器是会话的真实来源（~/.openclaw/agents//sessions/）。

存储模型

持久化主机数据： Docker Compose 将 OPENCLAW_CONFIG_DIR 绑定挂载到 /home/node/.openclaw，将 OPENCLAW_WORKSPACE_DIR 绑定挂载到 /home/node/.openclaw/workspace，因此这些路径在容器替换后仍然存在。临时沙箱 tmpfs： 当启用 agents.defaults.sandbox 时，沙箱容器使用 tmpfs 用于 /tmp、/var/tmp 和 /run。这些挂载与顶层 Compose 堆栈是分开的，并随沙箱容器一起消失。磁盘增长热点： 关注 media/、agents//sessions/sessions.json、转录 JSONL 文件、cron/runs/*.jsonl 以及 /tmp/openclaw/（或您配置的 logging.file）下的滚动文件日志。如果您在 Docker 之外也运行 macOS 应用程序，其服务日志又是独立的：~/.openclaw/logs/gateway.log、~/.openclaw/logs/gateway.err.log 和 /tmp/openclaw/openclaw-gateway.log。

代理沙箱（主机网关 + Docker 工具）

深入了解：沙箱
它的作用

当启用 agents.defaults.sandbox 时，非主会话将在 Docker 容器内运行工具。网关保留在您的主机上，但工具执行是隔离的：

范围：默认为 "agent"（每个代理一个容器 + 工作区）范围："session" 用于按会话隔离按范围的工作区文件夹挂载在 /workspace可选的代理工作区访问权限（agents.defaults.sandbox.workspaceAccess）允许/拒绝工具策略（拒绝优先）入站媒体被复制到活动的沙箱工作区（media/inbound/*），以便工具可以读取它（使用 workspaceAccess: "rw"，这将进入代理工作区）

警告：scope: "shared" 会禁用跨会话隔离。所有会话共享一个容器和一个工作区。
按代理的沙箱配置文件（多代理）

如果您使用多代理路由，每个代理可以覆盖沙箱和工具设置：agents.list[].sandbox 和 agents.list[].tools（加上 agents.list[].tools.sandbox.tools）。这允许您在一个网关中运行混合访问级别：

完全访问（个人代理）只读工具 + 只读工作区（家庭/工作代理）无文件系统/shell 工具（公共代理）

有关示例、优先级和故障排除，请参阅多代理沙箱和工具。
默认行为

镜像：openclaw-sandbox:bookworm-slim每个代理一个容器代理工作区访问：workspaceAccess: "none"（默认）使用 ~/.openclaw/sandboxes

"ro" 将沙箱工作区保留在 /workspace，并将代理工作区以只读方式挂载到 /agent（禁用 write/edit/apply_patch）"rw" 将代理工作区以读写方式挂载到 /workspace

自动清理：空闲 > 24 小时 或 存在时间 > 7 天

• 网络：默认 none（如果需要出站流量，显式选择加入）
  
  host 被阻止。默认情况下 container: 被阻止（命名空间加入风险）。
  
  默认允许：exec、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn、session_status默认拒绝：browser、canvas、nodes、cron、discord、gateway
  

启用沙箱

如果您计划在 setupCommand 中安装软件包，请注意：

默认 docker.network 是 "none"（无出站流量）。docker.network: "host" 被阻止。默认情况下 docker.network: "container:" 被阻止。紧急覆盖：agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true。readOnlyRoot: true 会阻止软件包安装。user 必须是 root 才能使用 apt-get（省略 user 或设置 user: "0:0"）。
当 setupCommand（或 docker 配置）发生更改时，OpenClaw 会自动重新创建容器，除非该容器最近使用过（大约 5 分钟内）。热容器会记录警告，其中包含确切的 openclaw sandbox recreate ... 命令。

1. {
2.   agents: {
3.     defaults: {
4.       sandbox: {
5.         mode: "non-main", // off | non-main | all
6.         scope: "agent", // session | agent | shared (agent 是默认值)
7.         workspaceAccess: "none", // none | ro | rw
8.         workspaceRoot: "~/.openclaw/sandboxes",
9.         docker: {
10.           image: "openclaw-sandbox:bookworm-slim",
11.           workdir: "/workspace",
12.           readOnlyRoot: true,
13.           tmpfs: ["/tmp", "/var/tmp", "/run"],
14.           network: "none",
15.           user: "1000:1000",
16.           capDrop: ["ALL"],
17.           env: { LANG: "C.UTF-8" },
18.           setupCommand: "apt-get update && apt-get install -y git curl jq",
19.           pidsLimit: 256,
20.           memory: "1g",
21.           memorySwap: "2g",
22.           cpus: 1,
23.           ulimits: {
24.             nofile: { soft: 1024, hard: 2048 },
25.             nproc: 256,
26.           },
27.           seccompProfile: "/path/to/seccomp.json",
28.           apparmorProfile: "openclaw-sandbox",
29.           dns: ["1.1.1.1", "8.8.8.8"],
30.           extraHosts: ["internal.service:10.0.0.5"],
31.         },
32.         prune: {
33.           idleHours: 24, // 0 禁用空闲清理
34.           maxAgeDays: 7, // 0 禁用最大存在时间清理
35.         },
36.       },
37.     },
38.   },
39.   tools: {
40.     sandbox: {
41.       tools: {
42.         allow: [
43.           "exec",
44.           "process",
45.           "read",
46.           "write",
47.           "edit",
48.           "sessions_list",
49.           "sessions_history",
50.           "sessions_send",
51.           "sessions_spawn",
52.           "session_status",
53.         ],
54.         deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
55.       },
56.     },
57.   },
58. }

复制代码

加固选项位于 agents.defaults.sandbox.docker 下：
network、user、pidsLimit、memory、memorySwap、cpus、ulimits、
seccompProfile、apparmorProfile、dns、extraHosts、
dangerouslyAllowContainerNamespaceJoin（仅限紧急使用）。
多代理：通过 agents.list[].sandbox.{docker,browser,prune}.* 覆盖每个代理的 agents.defaults.sandbox.{docker,browser,prune}.*
（当 agents.defaults.sandbox.scope / agents.list[].sandbox.scope 为 "shared" 时忽略）。
构建默认沙箱镜像

1. scripts/sandbox-setup.sh

复制代码

这将使用 Dockerfile.sandbox 构建 openclaw-sandbox:bookworm-slim。
沙箱通用镜像（可选）

如果您想要一个包含常见构建工具（Node、Go、Rust 等）的沙箱镜像，请构建通用镜像：

1. scripts/sandbox-common-setup.sh

复制代码

这将构建 openclaw-sandbox-common:bookworm-slim。要使用它：

1. {
2.   agents: {
3.     defaults: {
4.       sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
5.     },
6.   },
7. }

复制代码

沙箱浏览器镜像

要在沙箱内运行浏览器工具，请构建浏览器镜像：

1. scripts/sandbox-browser-setup.sh

复制代码

这将使用 Dockerfile.sandbox-browser 构建 openclaw-sandbox-browser:bookworm-slim。容器运行启用了 CDP 的 Chromium 和一个可选的 noVNC 观察器（通过 Xvfb 实现有头模式）。
注意：

有头模式（Xvfb）比无头模式更能减少机器人拦截。通过设置 agents.defaults.sandbox.browser.headless=true 仍可使用无头模式。不需要完整的桌面环境（GNOME）；Xvfb 提供显示。浏览器容器默认使用专用的 Docker 网络（openclaw-sandbox-browser），而不是全局的 bridge。可选的 agents.defaults.sandbox.browser.cdpSourceRange 通过 CIDR 限制容器边缘 CDP 入站流量（例如 172.21.0.1/32）。noVNC 观察器访问默认受密码保护；OpenClaw 提供一个短期有效的观察器令牌 URL，该 URL 提供一个本地引导页面，并将密码保留在 URL 片段中（而不是 URL 查询中）。

• 浏览器容器启动默认值对于共享/容器工作负载来说是保守的，包括：
  
  --remote-debugging-address=127.0.0.1--remote-debugging-port=--user-data-dir=${HOME}/.chrome--no-first-run--no-default-browser-check--disable-3d-apis--disable-software-rasterizer--disable-gpu--disable-dev-shm-usage--disable-background-networking--disable-features=TranslateUI--disable-breakpad--disable-crash-reporter--metrics-recording-only--renderer-process-limit=2--no-zygote--disable-extensions如果设置了 agents.defaults.sandbox.browser.noSandbox，还会附加 --no-sandbox 和 --disable-setuid-sandbox。上述三个图形加固标志是可选的。如果您的工作负载需要 WebGL/3D，请设置 OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 以在无 --disable-3d-apis、--disable-software-rasterizer 和 --disable-gpu 的情况下运行。扩展行为由 --disable-extensions 控制，可以通过 OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 禁用它（启用扩展），以用于依赖扩展的页面或扩展密集型工作流。--renderer-process-limit=2 也可以通过 OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT 配置；当需要调整浏览器并发性时，设置 0 让 Chromium 选择其默认的进程限制。
  
  
  

默认值在捆绑的镜像中默认应用。如果您需要不同的 Chromium 标志，请使用自定义浏览器镜像并提供您自己的入口点。
使用配置：

1. {
2.   agents: {
3.     defaults: {
4.       sandbox: {
5.         browser: { enabled: true },
6.       },
7.     },
8.   },
9. }

复制代码

自定义浏览器镜像：

1. {
2.   agents: {
3.     defaults: {
4.       sandbox: { browser: { image: "my-openclaw-browser" } },
5.     },
6.   },
7. }

复制代码

启用后，代理将接收：

一个沙箱浏览器控制 URL（用于 browser 工具）一个 noVNC URL（如果启用且 headless=false）

请记住：如果您对工具使用允许列表，请添加 browser（并将其从拒绝列表中移除），否则该工具仍会被阻止。
清理规则（agents.defaults.sandbox.prune）也适用于浏览器容器。
自定义沙箱镜像

构建您自己的镜像并将配置指向它：

1. docker build -t my-openclaw-sbx -f Dockerfile.sandbox .

复制代码

1. {
2.   agents: {
3.     defaults: {
4.       sandbox: { docker: { image: "my-openclaw-sbx" } },
5.     },
6.   },
7. }

复制代码

工具策略（允许/拒绝）

deny 优先于 allow。如果 allow 为空：所有工具（除了被拒绝的）都可用。如果 allow 非空：只有 allow 中的工具可用（减去被拒绝的）。

清理策略

两个控制旋钮：

prune.idleHours：移除在 X 小时内未使用的容器（0 = 禁用）prune.maxAgeDays：移除存在时间超过 X 天的容器（0 = 禁用）

示例：

保持繁忙会话但限制生命周期：idleHours: 24、maxAgeDays: 7从不清理：idleHours: 0、maxAgeDays: 0

安全说明

硬隔离仅适用于工具（exec/read/write/edit/apply_patch）。仅限主机的工具，如 browser/camera/canvas，默认被阻止。在沙箱中允许 browser会破坏隔离（浏览器在主机上运行）。

故障排除

镜像缺失：使用 scripts/sandbox-setup.sh 构建，或设置 agents.defaults.sandbox.docker.image。容器未运行：它会根据需要在每个会话时自动创建。沙箱中的权限错误：设置 docker.user 为与挂载的工作区所有权匹配的 UID:GID（或者更改工作区文件夹的所有权）。找不到自定义工具：OpenClaw 使用 sh -lc（登录 shell）运行命令，这会加载 /etc/profile 并可能重置 PATH。设置 docker.env.PATH 以将您的自定义工具路径添加到前面（例如 /custom/bin:/usr/local/share/npm-global/bin），或者在您的 Dockerfile 中的 /etc/profile.d/ 下添加一个脚本。

原文地址：https://blog.csdn.net/hy592070616/article/details/159514267

---

欢迎光临 AI创想 (https://www.llms-ai.com/)

Powered by Discuz! X3.4