AI 助理
文档备案控制台
官方文档
首页

沙箱Computer-Use场景使用

更新时间：
复制 MD 格式
产品详情
我的收藏

本文介绍如何在RDS Supabase沙箱中使用Computer-Use（桌面操控）能力，通过E2B Desktop SDK结合AI视觉模型构建"看屏幕、理解、操控"的自动化智能体，涵盖5个典型使用示例。

前提条件

  • 已创建RDS Supabase实例，且实例处于运行中状态。

  • 实例所在地域为华北2（北京）、华东2（上海）、华东1（杭州）、华南1（深圳）或西南1（成都）。

  • 已完成关联角色AliyunServiceRoleForRDSAISupabase授权。

  • 已在RDS控制台的沙箱和边缘函数页面启用沙箱功能。具体操作，请参见使用沙箱和边缘函数。

使用限制

  • 桌面沙箱基于Ubuntu Linux环境，不支持Windows或macOS桌面。

  • 单个沙箱默认超时时长为300秒，可通过timeout参数调整，超时后需重新创建。

配置Computer-Use

依次完成以下6个配置项，准备Computer-Use运行环境。

步骤一：创建desktop沙箱模板

在RDS Supabase实例详情页创建desktop公共模板，并记录模板ID供后续代码使用。

  1. 在实例详情页左侧导航栏，选择组件 > 沙箱和边缘函数。

  2. 确认启用沙箱和边缘函数开关已开启。

  3. 在沙箱模板区域，单击模板市场。

  4. 在右侧弹出的模板市场面板中，找到模板名称列为desktop、描述列为Image used in computer-use scenarios的行，单击该行操作列的创建。

  5. 创建完成后返回沙箱模板列表，找到配置项为desktop的行，复制模板ID列的完整值，格式为desktop-<随机后缀>。此模板ID将作为后续代码中Sandbox.create(template="<模板id>")参数的取值，请妥善保存。

步骤二：绑定域名

为Supabase实例的IP地址绑定域名。

  1. 在实例详情页中获取实例的外网连接地址对应的IP地址。

  2. 在本地/etc/hosts文件中添加域名映射记录。本文以<实例ID>.sb.rds.com为示例域名：

    <实例IP地址> <实例ID>.sb.rds.com
说明

开发测试场景建议直接写入/etc/hosts;生产环境请使用DNS解析。

步骤三：下载e2b SDK的patch代码

从GitHub仓库下载e2b SDK的patch代码,该patch用于适配RDS Supabase的路由方式。

步骤四：（可选）配置SSL实现HTTPS访问

如需通过HTTPS访问沙箱，请先为Supabase实例配置SSL证书。配置SSL后，设置以下环境变量：

# rootCA.pem为生成Supabase实例SSL证书对应的CA证书
export SSL_CERT_FILE="/xxx/rootCA.pem"
export REQUESTS_CA_BUNDLE="/xxx/rootCA.pem"
说明

如未配置SSL,访问方式退化为HTTP。

步骤五：配置环境变量

设置以下环境变量，用于e2b SDK连接Supabase实例：

# E2B_DOMAIN:「绑定域名」配置项中绑定的域名
export E2B_DOMAIN=<实例ID>.sb.rds.com

# E2B_API_KEY:Supabase实例的Service Key
export E2B_API_KEY=<your_service_key>

Service Key获取路径:在实例详情页右上角，单击获取API Key,在弹出的对话框中复制ServiceKey的值。

说明

后续Python代码中调用patch_e2b()方法即表示对e2b SDK进行patch，其入参True或False表示是否使用HTTPS访问沙箱。传入True时使用HTTPS,此时需先为RDS Supabase实例开通HTTPS,并参见使用沙箱和边缘函数文档设置HTTPS相关的环境变量;传入False时使用HTTP访问。

步骤六：安装Desktop SDK

执行以下命令安装Desktop SDK:

pip install e2b-desktop

Computer-Use使用示例

Computer-Use的核心工作流程依次为：接收用户指令、创建Ubuntu桌面沙箱、截取屏幕、将截图发送给AI视觉模型分析、执行模型返回的操作（点击/输入/滚动等），并循环直至任务完成。以下5个使用示例各自提供一份完整可运行的Python脚本，复制后按运行示例代码的说明保存为.py文件即可执行。

示例一：桌面串流（远程桌面查看）

启动一个交互式远程桌面，获取浏览器查看链接，在本地浏览器中实时观看沙箱桌面画面。

from e2b_desktop import Sandbox
from patch_e2b import patch_e2b

patch_e2b(True)

desktop = Sandbox.create(template="<模板id>")
print(f"sandboxId: {desktop.sandbox_id}")

# 启动桌面串流,开启认证
desktop.stream.start(require_auth=True)
auth_key = desktop.stream.get_auth_key()
print('Stream URL:', desktop.stream.get_url(auth_key=auth_key))

input("press ENTER to exit")
desktop.kill()

在浏览器中打开输出的Stream URL,即可实时查看沙箱桌面画面。

示例二：界面控制（键盘与鼠标操作）

自动打开浏览器并模拟键盘输入，实现基本的UI操控。

from e2b_desktop import Sandbox
from patch_e2b import patch_e2b

patch_e2b(True)

with Sandbox.create(template="<模板id>") as desktop:
    # 打开浏览器
    desktop.launch('google-chrome')
    # 输入网址
    desktop.write('https://www.aliyun.com')
    # 按回车访问
    desktop.press('enter')
    input("press ENTER to exit")

示例三：自定义桌面分辨率与截图

创建指定分辨率和DPI的桌面沙箱，并截取屏幕图像。

from e2b_desktop import Sandbox
from patch_e2b import patch_e2b

patch_e2b(True)

# 创建指定分辨率的桌面沙箱
sandbox = Sandbox.create(
    template="<模板id>",
    resolution=(1024, 720),
    dpi=96,
    timeout=300,
)

# 启动串流并在浏览器中查看
sandbox.stream.start()
print("View desktop at:", sandbox.stream.get_url())

# 截取屏幕
img_bytes = sandbox.screenshot()
with open("screenshot.png", "wb") as f:
    f.write(img_bytes)
print("Screenshot saved.")

sandbox.kill()

示例四：完整桌面操控API

E2B Desktop SDK提供的桌面操控方法分类如下：

类别

方法

鼠标操作

left_click(x, y)、right_click(x, y)、double_click(x, y)、middle_click(x, y)、move_mouse(x, y)、drag([x1, y1], [x2, y2])

键盘操作

write(text)、press(key)

滚动操作

scroll(direction, count),其中direction为"up"或"down"

屏幕截图

screenshot()返回图片字节流

执行命令

commands.run(shell_command)

完整调用示例：

from e2b_desktop import Sandbox
from patch_e2b import patch_e2b

patch_e2b(True)

sandbox = Sandbox.create(template="<模板id>")

# —— 鼠标操作 ——
sandbox.left_click(500, 300)          # 左键单击
sandbox.right_click(500, 300)         # 右键单击
sandbox.double_click(500, 300)        # 双击
sandbox.middle_click(500, 300)        # 中键点击
sandbox.move_mouse(500, 300)          # 移动鼠标
sandbox.drag([100, 200], [400, 500])  # 拖拽

# —— 键盘操作 ——
sandbox.write("Hello, world!")        # 输入文本
sandbox.press("Enter")                # 按下按键

# —— 滚动操作 ——
sandbox.scroll("down", 3)             # 向下滚动3格
sandbox.scroll("up", 3)               # 向上滚动3格

# —— 屏幕截图 ——
img_bytes = sandbox.screenshot()

# —— 执行命令 ——
sandbox.commands.run("ls -la /home")

sandbox.kill()

示例五：AI视觉驱动的自动化循环

结合AI视觉模型（如OpenAI GPT-4o、Anthropic Claude等）,实现截图、AI分析、执行操作的自动化循环，让AI像人一样观察屏幕并操控桌面完成任务。

LLM返回的操作对象格式规范如下：

操作类型

示例

单击

{"type": "click", "x": 500, "y": 300}

输入文本

{"type": "type", "text": "Hello"}

按键

{"type": "keypress", "keys": "Enter"}

滚动

{"type": "scroll", "scroll_y": 3},正数向下，负数向上

拖拽

{"type": "drag", "start_x": 100, "start_y": 200, "end_x": 400, "end_y": 500}

任务完成

返回None

自动化循环代码示例：

from e2b_desktop import Sandbox
from patch_e2b import patch_e2b

patch_e2b(True)

sandbox = Sandbox.create(
    template="<模板id>",
    resolution=(1024, 720),
    dpi=96,
    timeout=300,
)

def get_next_action_from_llm(screenshot):
    """
    将截图发送给AI视觉模型,获取下一步操作指令。
    此处为占位函数,实际使用时替换为您的LLM调用逻辑。
    模型应返回本示例开头表格中定义的操作对象格式,
    或返回None表示任务完成。
    """
    pass

# 自动化循环:截图、AI分析、执行操作
while True:
    screenshot = sandbox.screenshot()
    action = get_next_action_from_llm(screenshot)

    if not action:
        break

    if action.type == "click":
        sandbox.left_click(action.x, action.y)
    elif action.type == "type":
        sandbox.write(action.text)
    elif action.type == "keypress":
        sandbox.press(action.keys)
    elif action.type == "scroll":
        direction = "up" if action.scroll_y < 0 else "down"
        sandbox.scroll(direction, abs(action.scroll_y))
    elif action.type == "drag":
        sandbox.drag(
            [action.start_x, action.start_y],
            [action.end_x, action.end_y]
        )

sandbox.kill()
说明

占位函数get_next_action_from_llm需要您自行接入LLM服务（如OpenAI Vision、Anthropic Claude Vision等）,本文不展开LLM集成细节，可参见对应模型的官方文档。

运行示例代码

完成前面6个配置步骤后，按以下流程运行本文中的Python示例。

步骤一：创建脚本文件

将示例代码保存为.py文件，必须与配置Computer-Use步骤三下载的patch_e2b源码放在同一目录，否则会报ModuleNotFoundError: No module named 'patch_e2b'。目录结构示例：

e2b-sdk-patch/
├── patch_e2b/          # 「配置Computer-Use」步骤三下载的patch源码
└── demo.py             # 您的示例脚本

如需将脚本放在其他目录，请将patch_e2b源码路径加入PYTHONPATH：

export PYTHONPATH="/path/to/e2b-sdk-patch:$PYTHONPATH"
说明

其中/path/to/e2b-sdk-patch为占位符，需替换为本地patch_e2b源码所在的实际绝对路径（例如/Users/yourname/code/e2b-sdk-patch）；:$PYTHONPATH用于保留原有路径，避免覆盖。设置完成后，在同一终端窗口中运行脚本即可生效。

步骤二：替换代码中的占位符

示例代码中的<模板id>需替换为「配置Computer-Use」步骤一记录的模板ID（格式为desktop-<后缀>）。

步骤三：确认环境变量已生效

在运行脚本的终端中执行以下命令，确认配置Computer-Use步骤五配置的环境变量已加载：

echo $E2B_DOMAIN     # 应输出 <实例ID>.sb.rds.com
echo $E2B_API_KEY    # 应输出 Supabase ServiceKey

步骤四：运行脚本

python3 demo.py

常见启动问题

Q1：报错ModuleNotFoundError: No module named 'patch_e2b'怎么办？

A：脚本不在patch_e2b源码目录，请将脚本移动到patch源码目录，或配置PYTHONPATH环境变量指向patch源码路径。

Q2：报错ModuleNotFoundError: No module named 'e2b_desktop'怎么办？

A：未安装Desktop SDK，请执行pip install e2b-desktop。

Q3：连接超时或DNS解析失败怎么办？

A：可能原因是/etc/hosts未配置域名映射，或E2B_DOMAIN环境变量未设置。请检查「配置Computer-Use」步骤二和步骤五的配置。

Q4：报错401认证失败怎么办？

A：E2B_API_KEY错误，请在实例详情页右上角单击获取API Key重新获取ServiceKey并更新环境变量。

相关文档

上一篇：使用沙箱和边缘函数下一篇：沙箱Browser-Use场景使用