6.22 沙箱与策略 - OpenClaw中文社区

OpenClaw 提供三层安全控制机制:沙箱(Sandbox)、工具策略(Tool Policy)和提权工具(Elevated),它们协同工作以保护系统安全。

概述

理解这三种机制的区别和作用至关重要:

沙箱 - 控制工具在哪里运行 (Docker 容器 vs 主机)
工具策略 - 控制哪些工具可用 (允许/拒绝列表)
提权工具 - 提供沙箱逃逸选项 (仅限 exec,在主机上运行)

一、沙箱 (Sandbox)

沙箱决定工具在 Docker 容器还是主机上执行。

沙箱模式

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"  // "off" | "non-main" | "all"
      }
    }
  }
}

模式	说明	适用场景
`off`	所有工具在主机上运行	完全信任的环境
`non-main`	主 Agent 在主机,其他在容器	默认推荐配置
`all`	所有 Agent 都在容器中	最高安全级别

注意

工具执行(如 exec, read, write)在沙箱中运行,但 Gateway 本身始终在主机上。

沙箱作用域

{
  "agents": {
    "defaults": {
      "sandbox": {
        "scope": "session"  // "session" | "agent" | "shared"
      }
    }
  }
}

session (默认) - 每个会话独立容器
agent - 每个 Agent 独立容器
shared - 所有 Agent 共享一个容器

工作空间访问

{
  "agents": {
    "defaults": {
      "sandbox": {
        "workspaceAccess": "none"  // "none" | "ro" | "rw"
      }
    }
  }
}

模式	挂载路径	权限	影响
`none`	无	-	仅访问沙箱内部
`ro`	`/agent`	只读	禁用 write 工具
`rw`	`/workspace`	读写	完整文件系统访问

自定义绑定挂载

{
  "agents": {
    "defaults": {
      "sandbox": {
        "bindMounts": [
          "/host/path:/container/path:ro",
          "/data:/data:rw"
        ]
      }
    }
  }
}

重要

绑定挂载会穿透沙箱文件系统,授予对主机路径的直接访问权。在 shared 作用域中被忽略。

二、工具策略 (Tool Policy)

工具策略控制哪些工具对 Agent 可用,独立于沙箱配置。

允许/拒绝列表

{
  "tools": {
    // 允许列表 (白名单)
    "allow": [
      "exec",
      "read",
      "write",
      "http-request"
    ],
    
    // 拒绝列表 (黑名单)
    "deny": [
      "shell",
      "docker"
    ]
  }
}

策略规则

拒绝优先: deny 列表覆盖 allow 列表
严格允许列表: 只有在 allow 中的工具才可用
组通配符: 支持 group:* 语法

工具组

{
  "tools": {
    "allow": [
      "group:filesystem",  // read, write, list, etc.
      "group:network",     // http-request, websocket, etc.
      "exec"               // 单独允许 exec
    ],
    "deny": [
      "write"  // 拒绝 write,即使在 filesystem 组中
    ]
  }
}

Agent 特定策略

{
  "agents": {
    "web-scraper": {
      "tools": {
        "allow": ["http-request", "read"],
        "deny": ["exec", "write"]
      }
    },
    "code-assistant": {
      "tools": {
        "allow": ["exec", "read", "write", "git"],
        "deny": ["http-request"]
      }
    }
  }
}

三、提权工具 (Elevated)

提权工具提供沙箱逃逸机制,仅适用于 exec 工具。

启用提权

{
  "tools": {
    "elevated": {
      "enabled": true
    }
  }
}

关键限制

提权仅适用于 exec 工具
提权不授予工具访问权限
提权不覆盖 allow/deny 策略
它只是"在主机上执行"的逃逸选项

使用提权 exec

// Agent 请求使用提权 exec
{
  "tool": "exec",
  "elevated": true,  // 请求在主机上运行
  "args": {
    "command": "docker ps"
  }
}

三层机制对比

机制	控制内容	作用范围	优先级
工具策略	哪些工具可用	所有工具	最高
沙箱	工具运行位置	允许的工具	中等
提权	逃逸到主机	仅 exec	最低

实践场景

场景 1: 安全的 Web 爬虫

{
  "agents": {
    "scraper": {
      "sandbox": {
        "mode": "all",
        "workspaceAccess": "rw"
      },
      "tools": {
        "allow": ["http-request", "read", "write"],
        "deny": ["exec", "shell"]
      }
    }
  }
}

场景 2: 受限的代码助手

{
  "agents": {
    "coder": {
      "sandbox": {
        "mode": "non-main",
        "workspaceAccess": "rw",
        "bindMounts": [
          "/home/user/projects:/projects:rw"
        ]
      },
      "tools": {
        "allow": ["exec", "read", "write", "git"],
        "deny": ["http-request", "docker"]
      }
    }
  },
  "tools": {
    "elevated": {
      "enabled": false  // 禁止逃逸
    }
  }
}

场景 3: 可信的系统管理

{
  "agents": {
    "admin": {
      "sandbox": {
        "mode": "off"  // 不使用沙箱
      },
      "tools": {
        "allow": ["group:*"]  // 允许所有工具
      }
    }
  },
  "tools": {
    "elevated": {
      "enabled": true  // 允许提权
    }
  }
}

场景 4: 多层防御

{
  "agents": {
    "untrusted": {
      "sandbox": {
        "mode": "all",
        "scope": "session",
        "workspaceAccess": "none"
      },
      "tools": {
        "allow": ["exec", "read"],
        "deny": ["write", "http-request"]
      }
    }
  },
  "tools": {
    "elevated": {
      "enabled": false
    }
  }
}

调试和验证

查看当前策略

# 查看完整配置
openclaw config show

# 查看工具策略
openclaw config show | grep -A 10 tools

# 查看沙箱配置
openclaw config show | grep -A 10 sandbox

测试沙箱行为

# 使用调试命令
openclaw sandbox explain

# 测试工具可用性
openclaw tools list --agent agent-id

# 检查提权状态
openclaw tools check exec --elevated

验证隔离

# 进入沙箱容器
docker exec -it openclaw-sandbox-session-id /bin/sh

# 查看挂载点
mount | grep openclaw

# 检查进程隔离
ps aux

安全最佳实践

默认拒绝: 使用允许列表而非拒绝列表
最小权限: 只授予必需的工具访问
启用沙箱: 默认使用 non-main 或 all 模式
限制工作空间: 优先使用 none 或 ro
谨慎提权: 仅在完全信任时启用 elevated
审计日志: 记录所有工具调用和提权请求
定期审查: 检查策略配置的有效性

常见错误

误解 1: 提权授予工具权限

❌ 错误:

{
  "tools": {
    "elevated": {
      "enabled": true
    }
    // 认为这样就能使用所有工具
  }
}

✅ 正确:

{
  "tools": {
    "allow": ["exec"],  // 必须先允许工具
    "elevated": {
      "enabled": true   // 然后才能提权
    }
  }
}

误解 2: 沙箱控制工具可用性

❌ 错误:认为 sandbox.mode: "off" 会禁用工具

✅ 正确:沙箱只控制运行位置,不控制可用性

误解 3: 绑定挂载是安全的