沙箱与故障排查

启用 Docker 智能体沙箱，并修复了沙箱镜像、权限和 Control UI 配对问题。属于 Docker 指南的一部分。

智能体沙箱¶

当使用 Docker 后端启用 agents.defaults.sandbox 时，网关会在隔离的 Docker 容器内运行智能体工具执行（shell、文件读写等），而网关本身仍留在宿主机上——无需容器化整个网关，就能在不受信任或多租户的智能体会话周围建立一道硬隔离墙。

沙箱作用域可以是按智能体（默认）、按会话或共享的；每个作用域都有自己的工作区，挂载在 /workspace。你还可以配置允许/拒绝工具策略、网络隔离、资源限制和浏览器容器。

有关完整配置、镜像、安全说明和多智能体配置：

沙箱 —— 完整的沙箱参考
OpenShell —— OpenShell 管理的本地或远程沙箱后端
多智能体沙箱与工具 —— 按智能体覆盖

快速启用¶

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
      },
    },
  },
}

从源码检出构建默认沙箱镜像：

scripts/sandbox-setup.sh

对于没有源码检出的 npm 安装，请参阅沙箱 § 镜像与设置中的内联 docker build 命令。

故障排除¶

镜像缺失或沙箱容器无法启动

使用 scripts/sandbox-setup.sh（源码检出）或沙箱 § 镜像与设置（npm 安装）中的内联 docker build 命令来构建沙箱镜像，或者将 agents.defaults.sandbox.docker.image 设置为你自定义的镜像。容器会按会话按需自动创建。

沙箱中的权限错误

将 docker.user 设置为与所挂载工作区属主匹配的 UID:GID，或者对工作区文件夹执行 chown。

沙箱中找不到自定义工具

OpenClaw 使用 sh -lc（登录 shell）运行命令，该方式会加载 /etc/profile，从而可能重置 PATH。请设置 docker.env.PATH 以在路径前添加你的自定义工具路径，或在 Dockerfile 中的 /etc/profile.d/ 下添加脚本。

镜像构建期间被 OOM 杀死（退出码 137）

本地源码镜像构建至少需要 6 GB 内存。请使用更大的机器类型或预构建镜像，然后重试。

Control UI 中未授权或需要配对

获取一个新的仪表盘链接并批准浏览器设备：

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

更多详情：仪表盘、设备。

网关目标显示 ws://172.x.x.x 或来自 Docker CLI 的配对错误

重置网关模式和绑定：

docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw