6.23 沙箱机制

OpenClaw 沙箱机制通过 Docker 容器隔离工具执行,限制潜在风险的影响范围,是可选但强烈推荐的安全措施。

概述

沙箱在 Docker 容器中运行工具执行操作(如 exec、read、write),而 Gateway 本身继续在主机上运行。这种设计限制了代码执行的"爆炸半径",即使 AI 生成恶意命令,影响范围也被限制在容器内。

沙箱配置

基本配置

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",     // 沙箱模式
        "scope": "session",     // 隔离范围
        "workspaceAccess": "none"  // 工作空间访问
      }
    }
  }
}

沙箱模式

模式选项

模式	行为	安全级别	使用场景
off	所有工具在主机运行	低	完全可信环境
non-main	主 Agent 在主机,其他在容器	中	默认推荐
all	所有 Agent 在容器	高	零信任环境

配置示例

// 最小配置 (使用默认值)
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

// 禁用沙箱
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "off"
      }
    }
  }
}

// 最高安全
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all"
      }
    }
  }
}

隔离范围 (Scope)

控制容器的共享级别:

范围	隔离级别	说明
session	会话级	每个会话独立容器(默认)
agent	Agent 级	每个 Agent 独立容器
shared	共享	所有 Agent 共享一个容器

配置示例

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session"  // 默认:会话级隔离
      }
    }
  }
}

工作空间访问

控制容器对主机文件系统的访问:

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

配置示例

// 无主机访问 (默认)
{
  "sandbox": {
    "workspaceAccess": "none"
  }
}

// 只读访问
{
  "sandbox": {
    "workspaceAccess": "ro"
  }
}

// 读写访问
{
  "sandbox": {
    "workspaceAccess": "rw"
  }
}

自定义绑定挂载

可以挂载特定主机路径到容器:

语法

{
  "sandbox": {
    "bindMounts": [
      "host-path:container-path:mode"
    ]
  }
}

// mode: ro (只读) 或 rw (读写)

配置示例

{
  "agents": {
    "defaults": {
      "sandbox": {
        "bindMounts": [
          "/home/user/data:/data:ro",
          "/tmp/cache:/cache:rw"
        ]
      }
    }
  }
}

全局与 Agent 级挂载合并

{
  "agents": {
    "defaults": {
      "sandbox": {
        "bindMounts": [
          "/shared/lib:/lib:ro"  // 全局挂载
        ]
      }
    },
    "data-processor": {
      "sandbox": {
        "bindMounts": [
          "/data:/data:rw"  // Agent 特定挂载
        ]
      }
    }
  }
}

// 结果: data-processor 同时拥有两个挂载

容器镜像和网络

默认镜像

// OpenClaw 使用的默认沙箱镜像
openclaw-sandbox:bookworm-slim

// 基于 Debian Bookworm
// 最小化安装,默认无网络访问

网络配置

默认情况下,沙箱容器无网络访问。需要网络时可以启用:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "network": "bridge"  // 启用网络
      }
    }
  }
}

Setup Command

在容器创建后运行一次性设置命令:

配置

{
  "agents": {
    "defaults": {
      "sandbox": {
        "setupCommand": "apt-get update && apt-get install -y git python3"
      }
    }
  }
}

常见 Setup 示例

// Python 数据科学环境
{
  "sandbox": {
    "network": "bridge",
    "setupCommand": "pip install pandas numpy scikit-learn"
  }
}

// Node.js 环境
{
  "sandbox": {
    "network": "bridge",
    "setupCommand": "apt-get update && apt-get install -y nodejs npm"
  }
}

// 开发工具
{
  "sandbox": {
    "network": "bridge",
    "setupCommand": "apt-get update && apt-get install -y git curl wget vim"
  }
}

工具策略与沙箱

工具策略在沙箱之前应用:

{
  "tools": {
    "allow": ["exec", "read", "write"],
    "deny": ["shell"]
  },
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

// 执行顺序:
// 1. 检查工具策略 (allow/deny)
// 2. 如果允许,在沙箱中执行
// 3. 除非使用 elevated 逃逸

Elevated 工具

tools.elevated 提供沙箱逃逸机制:

配置

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

使用

// Agent 请求在主机上执行
{
  "tool": "exec",
  "elevated": true,
  "args": {
    "command": "docker ps"
  }
}

// 此命令将在主机而非沙箱中执行

调试沙箱

查看沙箱配置

# 解释当前沙箱配置
openclaw sandbox explain

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

# 列出运行的容器
docker ps | grep openclaw-sandbox

进入沙箱容器

# 查找容器 ID
docker ps | grep openclaw-sandbox

# 进入容器
docker exec -it  /bin/sh

# 查看挂载点
mount | grep openclaw

# 查看文件系统
ls -la /

查看容器日志

# 查看容器日志
docker logs 

# 实时跟踪
docker logs -f 

# 查看最近 100 行
docker logs --tail 100 

性能优化

容器重用

使用 agent 或 shared 范围重用容器:

{
  "sandbox": {
    "scope": "agent"  // 重用 Agent 容器,避免频繁创建
  }
}

镜像预热

# 提前拉取镜像
docker pull openclaw-sandbox:bookworm-slim

# 使用自定义预构建镜像
{
  "sandbox": {
    "image": "mycustom/openclaw-sandbox:v1"
  }
}

实践配置示例

Web 爬虫 Agent

{
  "agents": {
    "scraper": {
      "sandbox": {
        "mode": "all",
        "scope": "session",
        "workspaceAccess": "rw",
        "network": "bridge",
        "setupCommand": "pip install requests beautifulsoup4"
      },
      "tools": {
        "allow": ["http-request", "read", "write"]
      }
    }
  }
}

代码分析 Agent

{
  "agents": {
    "analyzer": {
      "sandbox": {
        "mode": "all",
        "scope": "agent",
        "workspaceAccess": "ro",  // 只读,安全分析
        "bindMounts": [
          "/projects:/projects:ro"
        ]
      },
      "tools": {
        "allow": ["read", "exec"],
        "deny": ["write", "http-request"]
      }
    }
  }
}

可信系统 Agent

{
  "agents": {
    "admin": {
      "sandbox": {
        "mode": "off"  // 无沙箱,完全信任
      },
      "tools": {
        "allow": ["group:*"]
      }
    }
  },
  "tools": {
    "elevated": {
      "enabled": true
    }
  }
}

安全建议

• 默认启用: 使用 non-main 或 all 模式
• 最小化挂载: 仅挂载必需路径,优先只读
• 禁用网络: 除非必需,保持网络禁用
• 限制 Setup: 避免在 setupCommand 中安装敏感工具
• 谨慎 Elevated: 仅在完全信任时启用
• 定期清理: 清理未使用的容器和镜像
• 监控容器: 监控异常容器行为

相关资源

• 沙箱与策略对比
• 安全机制
• Gateway 配置
• 工具策略