OpenClaw 多人共用服务器的文件隔离实战指南

发表于最近更新于最近

作者 Administrator

39~51 分钟 阅读

背景：公司内部测试服务器上部署了 OpenClaw，所有同事通过企业微信（WeCom）各自对应一个 agent workspace 使用。某个周末，一位同事误操作把已部署在 3002 端口的前端项目搞成了新网站。为了从根本上杜绝此类问题，我们完整实施了 OpenClaw 官方的 Sandbox 隔离方案，并记录了整个过程。

一、问题分析：为什么要用 Sandbox

在没有隔离的情况下，agent 执行 shell 命令时直接跑在宿主机上，意味着任何一个 agent 都可以：

读写 /www/wwwroot 下的所有前端项目
误操作其他人的 workspace
在服务器上执行任何命令

OpenClaw 官方内置了 Agent Sandbox 功能，专门解决这个问题。核心原理是：Gateway 本身跑在宿主机，所有 agent 的工具执行（exec、文件读写等）放进独立的 Docker 容器里，每个 agent 有自己的 sandbox 容器，互相完全隔离。

官方原话：

This is not a perfect security boundary, but it materially limits filesystem and process access when the model does something dumb.

二、安装方式选择

方式 A：Docker Compose 全新安装

适合还没安装 OpenClaw 的场景。

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 用预构建镜像 + 开启 sandbox，一条命令完成
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh

方式 B：install.sh 安装（本文使用的方式）

curl -fsSL https://openclaw.ai/install.sh | bash

安装完成后，config 文件位于：

~/.openclaw/openclaw.json

可以通过命令确认：

openclaw config file

三、开启 Sandbox 隔离

3.1 确认 Docker 已安装

docker --version
docker compose version  # 必须是 v2

3.2 克隆仓库（只为获取 sandbox 构建脚本）

git clone https://github.com/openclaw/openclaw.git
cd openclaw

3.3 构建 sandbox 镜像

官方提供两个版本：

# 标准镜像（体积小）
./scripts/sandbox-setup.sh

# 带工具链的镜像（包含 curl、jq、nodejs、python3、git）
./scripts/sandbox-common-setup.sh

注意：国内服务器从 deb.debian.org 拉包很慢，建议修改 Dockerfile.sandbox，在 apt-get update 前加一行换源：
sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources && \

实际安装的工具（来自官方 Dockerfile.sandbox）：bash、ca-certificates、curl、git、jq、python3、ripgrep

3.4 配置 Sandbox 策略

官方 Quick enable 示例：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "agent"
      }
    }
  }
}

mode 参数说明（关键）：

值	含义
`"off"`	不隔离，直接跑在宿主机
`"non-main"`	只隔离非 main session（群聊/channel），私聊 main session 不隔离
`"all"`	所有 session 全部走 sandbox

官方注明："non-main" 基于 session.mainKey 判断，不是 agent id。企业微信群聊属于 non-main 会被隔离，但私聊 main session 不会。我们需要所有 session 都隔离，所以用 "all"。

scope 参数说明：

值	含义
`"session"`	每个 session 一个容器（默认）
`"agent"`	每个 agent 一个容器
`"shared"`	所有 agent 共用一个容器

我们用 "agent"，与 add agents 方式一一对应，每人独立容器。

执行配置：

openclaw config set agents.defaults.sandbox.mode "all"
openclaw config set agents.defaults.sandbox.scope "agent"
openclaw config set agents.defaults.sandbox.workspaceAccess "rw"

验证配置是否生效：

openclaw sandbox explain

输出示例：

Effective sandbox:
  agentId: main
  runtime: sandboxed
  mode: all  scope: agent  perSession: false
  workspaceAccess: rw

四、新增 Agent（用户）

4.1 使用 wizard 添加

openclaw agents add zhangsan

wizard 会引导配置 workspace 路径、是否复制 auth profiles 等，全程交互式。

添加完成后，目录结构如下：

workspace：~/.openclaw/workspace-zhangsan（或指定路径）
sessions：~/.openclaw/agents/zhangsan/sessions

4.2 查看所有 agent 配置

openclaw config get agents.list

4.3 修正 workspace 路径

如果已有历史数据在其他目录（如 /workspace/zhangsan），直接修改 config 指向原路径即可，无需复制文件：

# 找到 zhangsan 在 agents.list 里的索引（从 0 开始）
openclaw config set agents.list[2].workspace "/workspace/zhangsan"

4.4 绑定企业微信 Channel

openclaw agents bind --agent zhangsan --bind wechat-work:zhangsan

# 验证
openclaw agents list --bindings

五、特殊权限配置

5.1 某个 agent 跑在宿主机（不隔离）

以管理员账号为例，需要完全访问服务器：

# 找到该 agent 在 agents.list 里的索引
openclaw config set agents.list[2].sandbox.mode "off"
openclaw sandbox recreate --agent zhangsan

效果：该 agent 直接跑在宿主机，可以访问 /www 等所有路径；其他人仍在 sandbox 里。

5.2 给某个 agent 单独挂载额外目录

如果某个 agent 关了 sandbox，不需要额外挂载，直接访问宿主机所有路径。

如果保持 sandbox 模式但需要挂载额外目录，参考下方全局配置。

六、解决容器内工具链缺失问题

6.1 问题根因

sandbox 容器默认：

ReadonlyRootfs: true — 文件系统只读，无法 apt-get 安装
/tmp 是 noexec 的 tmpfs — 无法执行下载的二进制
/www/server 没挂载 — node/java/maven 不可用

6.2 解决方案

关闭只读文件系统：

openclaw config set agents.defaults.sandbox.docker.readOnlyRoot false

挂载宿主机工具链目录（只读）：

openclaw config set agents.defaults.sandbox.docker.binds '["/www/server:/www/server:ro"]' --strict-json

注意：OpenClaw 默认禁止挂载 workspace 根目录以外的路径，需要开启 override：

openclaw config set agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources true

重建所有容器：

openclaw sandbox recreate --all

验证：

docker exec -it openclaw-sbx-agent-wangwu-xxxxxxxx /www/server/nodejs/v24.14.0/bin/node --version

七、解决容器内网络问题（代理配置）

7.1 问题根因

sandbox 容器默认 network: "none"，没有网络出口。即使改成 bridge 有了网络，国内服务器访问谷歌等被墙域名还是需要代理。

7.2 确认网络模式

openclaw config get agents.defaults.sandbox.docker.network

如果是 none，改成 bridge：

openclaw config set agents.defaults.sandbox.docker.network bridge

7.3 注入代理环境变量

服务器用的是 mihomo（监听 7890 端口），容器通过 Docker bridge 网关（172.17.0.1）访问宿主机代理：

openclaw config set agents.defaults.sandbox.docker.env '{"HTTP_PROXY":"http://172.17.0.1:7890","HTTPS_PROXY":"http://172.17.0.1:7890","http_proxy":"http://172.17.0.1:7890","https_proxy":"http://172.17.0.1:7890","NO_PROXY":"localhost,127.0.0.1,*.baidu.com,*.qq.com,*.weixin.qq.com,*.mytibangbang.cn,*.aliyun.com","no_proxy":"localhost,127.0.0.1,*.baidu.com,*.qq.com,*.weixin.qq.com,*.mytibangbang.cn,*.aliyun.com"}' --strict-json

大小写都要写：不同程序读的环境变量名不一样，node 读 https_proxy，有些工具读大写，全写保险。no_proxy 必须加，国内域名不走代理。

重建容器：

openclaw sandbox recreate --all

八、AI 模型限流问题

8.1 问题现象

多人同时使用 claude-opus-4-6 时频繁报错：

The AI service is temporarily overloaded. Please try again in a moment.

8.2 原因

Anthropic API 对 opus 系列限速最严，多人共用同一 API key 打 opus-4-6 容易触发 Rate Limit。

8.3 解决方案：配置 fallback

opus 正常时用 opus，被限流时自动降级到 sonnet，用户无感知：

openclaw config set agents.defaults.model.fallbacks '["anthropic/claude-sonnet-4-6"]' --strict-json

九、完整配置结构参考

最终 ~/.openclaw/openclaw.json 的核心结构：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",
        "scope": "agent",
        "workspaceAccess": "rw",
        "docker": {
          "readOnlyRoot": false,
          "network": "bridge",
          "binds": ["/www/server:/www/server:ro"],
          "dangerouslyAllowExternalBindSources": true,
          "env": {
            "HTTP_PROXY": "http://172.17.0.1:7890",
            "HTTPS_PROXY": "http://172.17.0.1:7890",
            "http_proxy": "http://172.17.0.1:7890",
            "https_proxy": "http://172.17.0.1:7890",
            "NO_PROXY": "localhost,127.0.0.1,*.baidu.com,*.aliyun.com",
            "no_proxy": "localhost,127.0.0.1,*.baidu.com,*.aliyun.com"
          }
        }
      },
      "model": {
        "fallbacks": ["anthropic/claude-sonnet-4-6"]
      }
    },
    "list": [
      { "id": "main" },
      {
        "id": "zhangsan",
        "name": "zhangsan",
        "workspace": "/workspace/zhangsan",
        "agentDir": "/root/.openclaw/agents/zhangsan/agent",
        "model": "anthropic/claude-opus-4-6",
        "sandbox": {
          "mode": "off"
        }
      },
      {
        "id": "lisi",
        "workspace": "/workspace/lisi",
        "model": "anthropic/claude-opus-4-6"
      }
    ]
  }
}

十、常用运维命令

# 查看所有 sandbox 容器状态
openclaw sandbox list

# 查看某个 session 的生效配置
openclaw sandbox explain

# 重建某个 agent 的容器
openclaw sandbox recreate --agent zhangsan

# 重建所有容器
openclaw sandbox recreate --all

# 验证配置格式正确
openclaw config validate

# 查看 gateway 状态
openclaw gateway status

# 查看实时日志
journalctl -u openclaw-gateway.service -f

# 查看错误日志
tail -100 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep -i "error\|fail"

# 进容器调试
docker exec -it openclaw-sbx-agent-zhangsan-xxxxxxxx bash

十一、隔离效果验证

配置完成后，可以进各个容器验证隔离效果：

# 进 wangwu 的容器
docker exec -it openclaw-sbx-agent-wangwu-xxxxxxxx sh -c "
  echo '=== 自己的 workspace ==='
  ls /workspace

  echo '=== 宿主机 /www/wwwroot ==='
  ls /www/wwwroot 2>&1 || echo '✅ 不存在，隔离正常'

  echo '=== node 可用性 ==='
  /www/server/nodejs/v24.14.0/bin/node --version
"

预期输出：

/workspace — 可以看到自己的工作区文件 ✅
/www/wwwroot — 提示不存在，宿主机前端项目完全不可见 ✅
node 版本号正常输出 ✅

总结

配置项	作用
`sandbox.mode: "all"`	所有 session 的 shell/文件操作都进容器
`sandbox.scope: "agent"`	每人一个独立容器，互相看不到
`workspaceAccess: "rw"`	只能读写自己的 workspace 目录
`readOnlyRoot: false`	容器文件系统可写，支持临时安装工具
`binds: ["/www/server:ro"]`	只读挂载工具链，node/java/maven 可用
`dangerouslyAllowExternalBindSources: true`	允许挂载 workspace 根目录以外的路径
`docker.network: "bridge"`	容器有网络出口
`docker.env` 代理配置	容器内可访问被墙域名
管理员 `sandbox.mode: "off"`	管理员跑在宿主机，有完整服务器权限
`model.fallbacks`	限流时自动降级，用户无感知

经过这套配置，任何一个同事的 agent 误操作，最多只能影响自己 workspace 下的文件，无法触碰其他人的目录，也无法碰到宿主机上的前端项目和服务器配置。

许可协议: