OpenClaw Sandbox 配置说明
配置路径：~/.openclaw/openclaw.json，位于 agents.defaults.sandbox。
顶层字段
| 字段 | 可选值 | 说明 |
|---|
mode | off / non-main / all | 沙箱启用范围。off 不启用；non-main 仅对非主会话启用（群组/频道会话均属 non-main）；all 对所有会话启用 |
scope | session / agent / shared | 容器粒度。session 每会话一个容器；agent 每 agent 一个容器；shared 所有沙箱会话共用一个容器 |
workspaceAccess | none / ro / rw | 沙箱对 agent workspace 的访问权限，见下方说明 |
workspaceRoot | 路径字符串 | 仅在 workspaceAccess: "none" 时生效，沙箱独立目录的根路径（默认 ~/.openclaw/sandboxes） |
backend | docker / ssh / openshell | 沙箱运行时后端，默认 docker |
workspaceAccess 三种模式对比
| 值 | 容器内工作目录来源 | 说明 |
|---|
none | workspaceRoot/<scope-id>/ | 完全隔离，不接触宿主 agent workspace |
ro | agents.defaults.workspace 只读挂载到 /agent | write/edit/apply_patch 被禁用 |
rw | agents.defaults.workspace 读写挂载到 /workspace | 容器可直接修改宿主 workspace |
注意：workspaceRoot 只在 none 模式下有意义；ro/rw 模式下直接挂载 agent workspace，workspaceRoot 不参与。
docker 子块
基础运行时
| 字段 | 说明 |
|---|
image | Docker 镜像名，默认 openclaw-sandbox:bookworm-slim。可用 scripts/sandbox-common-setup.sh 构建带 curl/jq/git/python3 的增强版镜像 |
workdir | 容器内工作目录 |
readOnlyRoot | 根文件系统只读。为 true 时 setupCommand 中无法写文件，需搭配 tmpfs 使用 |
tmpfs | 挂载为 tmpfs 的路径列表（可写），如 ["/tmp", "/var/tmp", "/run"] |
network | 网络模式，默认 "none"（无网络）。"host" 被明确阻止；"container:<id>" 默认也被阻止 |
user | 容器内运行用户，格式 uid:gid，如 "1000:1000" |
env | 注入容器的环境变量，如 { LANG: "C.UTF-8" } |
初始化命令
| 字段 | 说明 |
|---|
setupCommand | 容器创建后只执行一次的初始化命令（通过 sh -lc 执行，非每次运行都执行）。常见坑：默认 network: "none" 导致 apt 无法联网；readOnlyRoot: true 时无法写文件；需要 apt 安装时用户必须是 root |
资源限制
| 字段 | 说明 |
|---|
pidsLimit | 容器内最大进程数 |
memory | 内存上限，如 "1g" |
memorySwap | 内存 + swap 上限，如 "2g" |
cpus | CPU 核心数限制 |
ulimits.nofile | 文件描述符数限制，{ soft: 1024, hard: 2048 } |
ulimits.nproc | 进程数 ulimit，{ soft: 256, hard: 256 } |
安全加固
| 字段 | 说明 |
|---|
capDrop | 丢弃的 Linux capabilities，["ALL"] 是最严格设置 |
seccompProfile | seccomp 安全配置文件的宿主机路径 |
apparmorProfile | AppArmor profile 名称 |
网络配置
| 字段 | 说明 |
|---|
dns | 容器 DNS 服务器列表，仅在开启网络时有意义 |
extraHosts | 追加到容器 /etc/hosts 的条目，格式 "hostname:ip" |
额外挂载
| 字段 | 说明 |
|---|
binds | 额外 bind mount 列表，格式 "host路径:容器路径:mode"（:ro 或 :rw）。全局与 per-agent binds 会合并。注意：/root、/etc、/proc、docker.sock 等路径被明确阻止 |
prune 子块
| 字段 | 说明 |
|---|
idleHours | 容器空闲超过多少小时后自动清理，0 禁用 |
maxAgeDays | 容器存活超过多少天后自动清理，0 禁用 |
位于 tools.sandbox.tools，控制沙箱内工具的允许/禁止策略。
| 字段 | 说明 |
|---|
allow | 沙箱内允许使用的工具列表 |
deny | 沙箱内明确禁用的工具列表 |
注意：tool allow/deny 策略在沙箱规则之前生效，全局 deny 的工具沙箱不会恢复。
常用工具名：exec、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn、session_status、browser、canvas、nodes、cron、discord、gateway
完整配置示例
{
"agents": {
"defaults": {
"sandbox": {
"mode": "non-main",
"scope": "agent",
"workspaceAccess": "none",
"workspaceRoot": "~/.openclaw/sandboxes",
"docker": {
"image": "openclaw-sandbox:bookworm-slim",
"workdir": "/workspace",
"readOnlyRoot": true,
"tmpfs": ["/tmp", "/var/tmp", "/run"],
"network": "none",
"user": "1000:1000",
"capDrop": ["ALL"],
"env": { "LANG": "C.UTF-8" },
"pidsLimit": 256,
"memory": "1g",
"memorySwap": "2g",
"cpus": 1,
"ulimits": {
"nofile": { "soft": 1024, "hard": 2048 },
"nproc": 256
},
"seccompProfile": "/path/to/seccomp.json",
"apparmorProfile": "openclaw-sandbox",
"dns": ["1.1.1.1", "8.8.8.8"],
"extraHosts": ["internal.service:10.0.0.5"],
"binds": ["/opt/mydata:/data:ro"]
},
"prune": {
"idleHours": 24,
"maxAgeDays": 7
}
}
}
},
"tools": {
"sandbox": {
"tools": {
"allow": ["exec", "process", "read", "write", "edit"],
"deny": ["browser", "canvas", "nodes", "cron"]
}
}
}
}
常用命令
openclaw sandbox list
openclaw sandbox recreate
openclaw sandbox explain
openclaw logs --follow