OpenClaw Integration 源码级讲解

源码路径：CubeSandbox/examples/openclaw-integration/

概述

本例展示如何将 CubeSandbox 作为 OpenClaw 的底层执行引擎，让任意 OpenClaw Agent 在隔离的 KVM MicroVM 中安全执行代码。核心是一个名为 cube-sandbox 的 OpenClaw Skill（技能包），封装了 E2B SDK 的全部能力。

整体架构

Skill 定义机制

SKILL.md 是 OpenClaw 的技能描述文件，通过 YAML frontmatter 声明：

---
name: cube-sandbox
description: >
  Cube Sandbox 安全沙箱执行技能。当需要安全执行 Python 代码、Shell 命令，
  或需要隔离环境运行不受信任的代码时使用。
  适用场景：
  (1) 用户要求"在沙箱中执行代码"、"跑一段 Python"、"安全执行"；
  (2) 需要执行可能有副作用的代码，希望通过沙箱隔离风险；
  (3) 需要读写沙箱内文件、挂载宿主机目录；
  (4) 需要控制沙箱网络策略；
  (5) 需要暂停/恢复沙箱。
---

OpenClaw Gateway 根据 description 中的关键词自动匹配：当用户说"在沙箱中执行代码"时，Agent 自动调用此 Skill。

核心能力源码分析

1. 创建沙箱

# 环境变量驱动，无需硬编码
template_id = os.environ["CUBE_TEMPLATE_ID"]  # 模板 ID
api_url = os.environ["E2B_API_URL"]           # CubeAPI 地址

# Sandbox.create → POST /sandboxes (CubeAPI)
with Sandbox.create(template=template_id) as sb:
    info = sb.get_info()  # GET /sandboxes/:id

2. 执行代码（两种模式）

# Python 代码 → Jupyter Kernel
result = sb.run_code("print('hello')")
# result.stdout / result.stderr / result.error / result.results

# Shell 命令 → envd 执行器
r = sb.commands.run("echo hello")
# r.stdout / r.stderr

3. 文件 I/O

# 读取沙箱内文件
content = sb.files.read("/etc/hosts")

# 写入文件
sb.files.write("/tmp/out.txt", "hello")

4. 宿主机挂载

import json
with Sandbox.create(template=template_id, metadata={
    "host-mount": json.dumps([
        {"hostPath": "/tmp/data", "mountPath": "/mnt/data", "readOnly": False}
    ])
}) as sb:
    # /mnt/data 指向宿主机 /tmp/data
    sb.commands.run("ls /mnt/data")

5. 网络策略

# 完全断网
Sandbox.create(template=tpl, allow_internet_access=False)

# 白名单（只允许指定 CIDR）
Sandbox.create(template=tpl, allow_internet_access=False,
               network={"allow_out": ["10.0.0.0/8"]})

# 黑名单（屏蔽指定 CIDR）
Sandbox.create(template=tpl,
               network={"deny_out": ["192.168.1.0/24"]})

6. 暂停与恢复

sb.pause()      # POST /sandboxes/:id/pause → 内存快照
# MicroVM 暂停，计算资源释放

sb.connect()    # POST /sandboxes/:id/connect → 从快照恢复
# MicroVM 恢复，内存状态完整保留

双面访问模型

CubeSandbox 提供两层 API，用途不同：

层	地址	协议	用途
控制面	CubeAPI :3000	HTTP REST	创建/销毁/暂停/恢复沙箱
数据面	CubeProxy :443	HTTPS (E2B SDK)	执行代码、文件读写、命令执行
数据面	CubeProxy :80	HTTP	直接访问（需设置 Host 头）

安装与配置流程

常见问题处理

域名解析失败

SSL 证书配置

场景	配置
使用 cube.app 测试证书	设置 SSL_CERT_FILE 指向 CA 根证书
自定义受信任域名	无需配置
HTTP 访问	无需配置
测试环境	可禁用证书校验（不推荐生产）

推荐阅读

1. skills/cube-sandbox/SKILL.md — Skill 定义与完整用法
2. references/api.md — API 接口参考
3. references/examples.md — 完整示例代码
4. README_zh.md — 中文部署指南

源码参考：SKILL.md