沙箱机制

沙箱（Sandbox）是 Gateway 的核心安全组件，负责隔离 Agent 的工具执行环境，防止恶意或意外操作影响宿主系统。

什么是沙箱

沙箱为每次工具执行创建一个受限环境（Restricted Environment），限制其对文件系统、网络和系统资源的访问。

┌─────────────────────────────────────┐
│          Gateway Process            │
│                                     │
│  ┌───────────────────────────────┐  │
│  │         Sandbox                │  │
│  │  ┌───────────┐ ┌───────────┐  │  │
│  │  │ 工具执行   │ │ 工具执行   │  │  │
│  │  │ (隔离)    │ │ (隔离)    │  │  │
│  │  └───────────┘ └───────────┘  │  │
│  │                               │  │
│  │  ■ 文件系统限制               │  │
│  │  ■ 网络访问限制               │  │
│  │  ■ 资源配额限制               │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

沙箱模式

Gateway 提供三种沙箱模式：

模式	安全等级	说明
off	⚠️ 无保护	禁用沙箱，工具直接在宿主环境执行
standard	✅ 标准	限制文件和网络访问，默认模式
strict	🔒 严格	最小权限，适合生产环境

配置沙箱模式

# 设置沙箱模式
openclaw config set security.sandbox.mode standard

{
  "security": {
    "sandbox": {
      "enabled": true,
      "mode": "standard"
    }
  }
}

禁用沙箱风险

将沙箱模式设为 off 意味着 Agent 的工具执行不受任何限制，可能对系统造成不可逆的损害。仅在完全信任 Agent 行为时使用。

文件系统隔离

标准模式

操作	允许范围
读取	工作目录及其子目录
写入	工作目录及其子目录
创建	工作目录及其子目录
删除	工作目录及其子目录（需确认）
系统文件	❌ 禁止访问
其他用户目录	❌ 禁止访问

严格模式

操作	允许范围
读取	仅白名单目录
写入	仅白名单目录
创建	仅白名单目录
删除	❌ 禁止
系统文件	❌ 禁止访问
其他用户目录	❌ 禁止访问

自定义文件访问规则

{
  "security": {
    "sandbox": {
      "mode": "standard",
      "filesystem": {
        "allowedPaths": [
          "/home/user/project",
          "/tmp/openclaw"
        ],
        "deniedPaths": [
          "/home/user/.ssh",
          "/home/user/.env"
        ],
        "readOnlyPaths": [
          "/etc/hosts",
          "/usr/share"
        ]
      }
    }
  }
}

网络限制

沙箱控制工具执行时的网络访问：

标准模式

• ✅ 允许 HTTP/HTTPS 出站请求
• ❌ 禁止监听端口
• ❌ 禁止原始套接字（Raw Socket）

严格模式

• ❌ 禁止所有网络访问
• 需要通过白名单显式允许

{
  "security": {
    "sandbox": {
      "network": {
        "outbound": "restricted",
        "allowedHosts": [
          "api.github.com",
          "registry.npmjs.org"
        ],
        "deniedHosts": [
          "*.internal.corp"
        ]
      }
    }
  }
}

工具限制

沙箱根据模式限制可执行的工具：

{
  "security": {
    "sandbox": {
      "tools": {
        // 自动批准的工具（无需用户确认）
        "autoApprove": [
          "read_file",
          "list_files",
          "search_files"
        ],
        // 需要用户确认的工具
        "requireApproval": [
          "write_file",
          "execute_command"
        ],
        // 完全禁用的工具
        "denied": [
          "delete_directory"
        ]
      }
    }
  }
}

最小权限原则

遵循最小权限原则（Principle of Least Privilege）：只授予 Agent 完成任务所需的最少权限。

资源配额

限制工具执行的资源消耗：

{
  "security": {
    "sandbox": {
      "resources": {
        "maxExecutionTime": 30000,    // 最大执行时间（毫秒）
        "maxMemory": "512MB",         // 最大内存使用
        "maxFileSize": "10MB",        // 最大单文件写入大小
        "maxOutputSize": "1MB"        // 最大输出大小
      }
    }
  }
}

沙箱违规处理

当工具执行违反沙箱规则时：

{
  "type": "tool-result",
  "payload": {
    "toolCallId": "tc_001",
    "success": false,
    "error": {
      "code": "sandbox_violation",
      "message": "Access denied: /etc/passwd is outside the allowed sandbox path"
    }
  }
}

运行时检查

# 查看当前沙箱配置
openclaw config get security.sandbox

# 诊断沙箱状态
openclaw doctor --check sandbox

相关文档

• 沙箱 vs 工具策略 vs 提权 — 安全机制对比
• 安全概览 — 完整安全架构
• 配置参考 — 完整配置项