为什么需要沙箱

OpenClaw 的 Agent 可以执行命令、读写文件、浏览器控制——这些都是高危操作。如果不对 Agent 的权限进行隔离，它一旦被恶意指令诱导，就可能对你的系统造成实际破坏。

沙箱机制就是把 Agent 放进一个"笼子"里，让它只能操作指定范围内的文件和资源，即使指令出错或被恶意利用，也不会影响真实系统。

这篇文章详细介绍 OpenClaw 沙箱的工作原理、三种后端、以及如何正确配置。

三种沙箱模式

OpenClaw 的沙箱由 agents.defaults.sandbox.mode 控制，有三种级别：

off —— 完全不隔离

Agent 拥有宿主机完整权限，可以读写任何文件、执行任意命令。这是最危险也是最灵活的模式。

适用场景：本地开发测试、对 Agent 完全信任、不需要生产级安全隔离。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "off"
      }
    }
  }
}

non-main —— 主 Agent 受保护，SubAgent 隔离

主 Agent 不启用沙箱（可以操作真实文件系统），但 SubAgent（小鱼）会被放进隔离环境。这是当前网站的配置模式——主 Agent（虾哥）有完整权限，小鱼被关在笼子里。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main"
      }
    }
  }
}

all —— 所有 Agent 都隔离

主 Agent 和所有 SubAgent 都在沙箱中运行。这是生产环境推荐的安全模式。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all"
      }
    }
  }
}

三种沙箱后端

沙箱的具体实现由 agents.defaults.sandbox.backend 指定，支持三种后端：

Docker 后端（推荐生产使用）

Docker 是目前最成熟的隔离方案。每个沙箱 Agent 在独立的 Docker 容器中运行，与宿主机完全隔离。

{
  agents: {
    defaults: {
      sandbox: {
        backend: "docker",
        docker: {
          image: "openclaw-sandbox:bookworm-slim"
        }
      }
    }
  }
}

更新 Docker 镜像后的重建流程：

# 拉取新镜像
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim

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

SSH 后端（远程隔离）

如果你的计算资源在远程服务器上，可以用 SSH 后端建立隔离环境。Agent 在远程机器上运行，结果通过 SSH 会话传回本地。

{
  agents: {
    defaults: {
      sandbox: {
        backend: "ssh",
        ssh: {
          target: "root@your-server.com:22",
          workspaceRoot: "/opt/openclaw/workspace",
          identityFile: "~/.ssh/id_ed25519"
        }
      }
    }
  }
}

SSH 后端的特点是：远程 workspace 是"规范版本"，本地修改不会直接影响远程。每次 recreate 会删除远程 workspace，下次运行时从本地重新同步。

OpenShell 后端（轻量隔离）

OpenShell 是 OpenClaw 自研的轻量级沙箱方案，适合不需要完整 Docker 隔离但仍需权限控制的场景。

{
  agents: {
    defaults: {
      sandbox: {
        backend: "openshell"
      }
    }
  }
}

沙箱权限控制

除了隔离模式，沙箱还支持细粒度的权限控制。通过 sandbox.tools 可以指定 Agent 允许调用哪些工具：

{
  agents: {
    defaults: {
      sandbox: {
        tools: {
          allow: ["exec", "read", "write", "browser"]
          deny: ["process"]
        }
      }
    }
  }
}

常用的沙箱工具策略：

策略 允许 禁止 适用场景
最小权限 read, web_fetch exec, write 内容浏览
开发模式 exec, read, write rm, format 本地开发
浏览器自动化 browser, read, write exec 网页操作

沙箱管理命令

安装配置好后，用 openclaw sandbox 系列命令管理沙箱：

查看当前沙箱状态：

openclaw sandbox list
openclaw sandbox list --browser   # 只看浏览器容器
openclaw sandbox list --json      # JSON 输出

理解当前配置：

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work

重建沙箱（配置更新后必须）：

openclaw sandbox recreate --all           # 重建所有
openclaw sandbox recreate --session main  # 重建特定会话
openclaw sandbox recreate --browser        # 只重建浏览器容器
openclaw sandbox recreate --all --force   # 跳过确认

实际配置示例：安全 vs 便利的权衡

推荐：平衡模式（非生产环境）

{
  agents: {
    defaults: {
      model: "anthropic/claude-sonnet-4-6",
      sandbox: {
        mode: "non-main",
        backend: "docker",
        docker: {
          image: "openclaw-sandbox:bookworm-slim"
        }
      }
    }
  }
}

主 Agent 有完整权限（方便调试），小鱼的浏览器自动化跑在 Docker 里隔离。

推荐：生产安全模式

{
  agents: {
    defaults: {
      model: "anthropic/claude-sonnet-4-6",
      sandbox: {
        mode: "all",
        backend: "docker",
        docker: {
          image: "openclaw-sandbox:bookworm-slim"
        },
        tools: {
          allow: ["exec", "read", "write", "browser"]
        }
      }
    }
  }
}

所有 Agent 都在 Docker 中运行，禁止高危操作。

常见问题

Q: 沙箱模式下文件写不进去？ A: 检查 workspace 目录是否在沙箱的映射范围内。Docker 后端需要在镜像构建时配置 volume 映射。

Q: openclaw sandbox recreate 会丢失数据吗？ A: Docker 后端不会丢失（容器重启即可）。SSH 后端会删除远程 workspace，需要重新同步。

Q: 沙箱影响 Agent 响应速度吗？ A: Docker 冷启动约 2-3 秒，之后与本地运行速度相当。OpenShell 最轻量，几乎无感知。

总结

沙箱是 OpenClaw 安全架构的核心：

  • mode: off → 本地开发测试用，不推荐生产
  • mode: non-main → 主 Agent 灵活，小鱼隔离（当前选用）
  • mode: all → 生产环境推荐，所有 Agent 都隔离
  • 后端选择：Docker 成熟稳定，OpenShell 轻量，SSH 适合远程

正确配置沙箱，可以在充分利用 Agent 能力的同时，把风险控制在可接受范围内。