一.3种模式对比

源码位置：/home/mi/aiagent/openclaw/src/agents/sandbox/config.ts

1.隔离级别

OpenClaw 的 sandbox.mode 提供三种不同的隔离级别，用于平衡性能与安全性。

2.默认模式 

默认的 sandbox.mode 是 "off"，也就是说：

• 默认行为：agent 直接在宿主机执行命令

• 文件访问：直接访问宿主机文件系统

• 工具执行：直接在宿主机环境运行

二.详细说明

1.off - 关闭沙箱（默认）

代码逻辑：

if (cfg.mode === "off") {returnfalse;  // 不使用沙箱}

特点：

• ✅ 所有会话直接在宿主机运行

• ✅ 性能最优（无容器开销）

• ⚠️ 安全性最低（无隔离）

• 📍 适用：本地开发、可信环境测试

执行示例：

主会话 → 宿主机执行Telegram → 宿主机执行Discord → 宿主机执行

2.on-main - 仅非主会话

代码逻辑：

return sessionKey.trim() !== mainSessionKey.trim();

特点：

• 主会话在宿主机运行（便于调试）

• 其它会话在沙箱运行（安全隔离）

• 📍 适用：混合场景（本地开发 + 远程会话）

主会话判断规则：

if (params.cfg?.session?.scope === "global") {return"global";}return resolveAgentMainSessionKey({ cfg, agentId });

执行示例：

主会话 (main) → 宿主机执行（开发调试）Telegram → 沙箱执行（外部频道，隔离）Discord → 沙箱执行（外部频道，隔离）

3.all - 全部沙箱

代码逻辑：

if (cfg.mode === "all") {returntrue;  // 全部使用沙箱}

特点：

• ✅ 所有会话完全隔离

• ✅ 安全性最高

• ⚠️ 性能略有降低（容器开销）

• 📍 适用：生产环境、多租户、不可信输入

执行示例：

主会话 → 沙箱执行Telegram → 沙箱执行Discord → 沙箱执行

4.决策流程

收到消息  │  ├─ sandbox.mode = "off"  │    └─ 宿主机执行  │  ├─ sandbox.mode = "all"  │    └─ 沙箱执行  │  └─ sandbox.mode = "non-main"       │       ├─ 是主会话？       │    ├─ YES → 宿主机执行       │    └─ NO  → 沙箱执行

5.安全性对比

6.配置示例

# 关闭沙箱（默认）openclaw config set agents.defaults.sandbox.mode off# 仅非主会话使用沙箱openclaw config set agents.defaults.sandbox.mode non-main# 全部使用沙箱openclaw config set agents.defaults.sandbox.mode all

三.使用建议

1.个人开发

# 使用 off，方便调试agents.defaults.sandbox.mode=off

2.家庭/小团队

# 使用 non-main，保留主会话用于调试agents.defaults.sandbox.mode=non-main

3.生产/云部署

# 使用 all，最大安全性agents.defaults.sandbox.mode=allagents.defaults.sandbox.workspaceAccess=none

4.当前配置状态

根据查询结果，当前配置为：

mode: off                 # 关闭沙箱（默认值）scope: agent              # 按 agent 级别隔离perSession: false         # 非会话级别workspaceAccess: none     # 无法访问工作区文件workspaceRoot: /home/mi/.openclaw/sandboxesruntime: direct           # 直接在宿主机运行

当前状态：沙箱已关闭，所有工具直接在宿主机执行。

四.agent/session启动新的容器

1.scope 参数的三种模式

当配置sandbox.mode = "all"时，沙箱功能已启用，但具体每个会话是否启动独立容器，由scope参数决定：

可以根据需要选择合适的 scope 模式，平衡安全隔离性与资源开销。原始设置scope="agent"。应该：

• 同一 agent 的所有会话共享容器

• 生成的容器：openclaw-sbx-agent-main-xxx

• 对应目录：~/.openclaw/sandboxes/agent-main-xxx

2.测试scope="session"

现在设置scope="session"后，运行 --agent main 命令时，使用默认 sessionKey agent:main:main。创建新的独立 sandbox和容器，而不是复用旧的 scope="agent"时的容器。应该：

• 目录：agent-main-main-{新hash}

• 容器：openclaw-sbx-agent-main-main-{新hash}

(base) mi@llm:~/aiagent/openclaw$ pnpm openclaw agent --agent main --session-id custom-123 --message "当前工作目录"

生成了新的sandbox目录：

生成了新的sandbox容器：

说明：--session-id 是用来恢复已存在会话的唯一标识符，如果找到就恢复，没有找到就创建。

3.如何判断session结束

Session 不会自动"结束"，只会被 Reset 或手动删除。容器会被 Prune 自动清理。

{agents:{defaults:{sandbox:{mode:"all",scope:"session",prune:{idleHours:24,//24小时未使用=清理容器maxAgeDays:3//容器最多保留3天}}}},session:{mode:"idle",//空闲模式idleMinutes:10080//7天未活动=reset历史记录}}

参考文献

[1] OpenClaw的Docker沙箱模式详解：https://my.feishu.cn/wiki/Qgnxwuwi8ipdUAkZXuSc836HnGf

知识星球：Dify源码剖析及答疑，OpenClaw源码剖析及答疑。加微信buxingtianxia21进NLP工程化资料群，Dify源码交流群，OpenClaw源码交流群。