#Computer Use

computer-use 是一个为驱动真实桌面而设计的 worker 进程：

• 鼠标和键盘
• 截图
• 剪贴板
• 窗口列表
• 无障碍树（accessibility tree）

它是独立于 aiod 的进程，可以运行在任何有桌面的主机上。例如：

• 一台 Ubuntu 桌面
• 一台跑 Xvfb 或 Xvnc 的虚拟机
• 一台带交互登录会话的 Windows 主机

aiod 只代理它的 API，不直接接触桌面。这层进程边界让桌面能力成为可选项：没有桌面时 aiod 照常运行，有桌面时则通过 computer-use 触达它。

桌面能力只在 v2 提供，路径在 /v2/computer/* 下。

v1 为 1.x 客户端保留两个别名：

• POST /v1/browser/actions
• POST /v1/display/record

路由对照见 从 1.x 迁移。

这一页前半部分介绍 agent 工具使用的动作，后半部分介绍用于观察或接管同一个桌面的查看器。

基于 CDP 的页面自动化见 浏览器 API；完整的桌面任务演示见 Computer Use 示例。

#面向 agent 的工具

#连接 daemon 与 worker

worker 监听 AIO_COMPUTER_USE_LISTEN（默认 0.0.0.0:18100）。aiod 通过 AIO_COMPUTER_USE_URL（默认 http://127.0.0.1:18100）连接 worker，并代理桌面路由。

worker 停止时，这些路由返回 503：

{
  "success": false,
  "message": "computer-use worker is not available",
  "data": null,
  "hint": "start computer-use or set AIO_COMPUTER_USE_URL"
}

两个 v1 别名走的是同一个 worker，返回同样的结果。

#运行 worker 的条件

Linux：需要一个可达的 X11 display。设置 DISPLAY；如果该 display 需要 cookie 鉴权，再设置 XAUTHORITY。 GET /v2/computer/info 会返回探测到的 display 和 xauthority。

Windows：一个交互登录会话。aiod 自己可以作为 Session 0 的 SCM 服务运行。

computer-use 必须运行在交互登录会话中，才能看到桌面并注入输入。

#查看当前可用能力

curl "$BASE_URL/v2/computer/info"

curl "$BASE_URL/v1/capabilities"

{
  "status": "absent",
  "provider": null,
  "display": null,
  "screenshot": false,
  "actions": false,
  "clipboard": false,
  "recording": false,
  "accessibility": false,
  "accessibility_backend": null,
  "resolution": {
    "width": null,
    "height": null
  },
  "missing": [
    "computer-use"
  ],
  "warnings": [
    "computer-use worker probe failed: error sending request for url (http://127.0.0.1:18100/capabilities)"
  ]
}

#截图

curl "$BASE_URL/v2/computer/screenshot" -o desktop.png

curl -X POST "$BASE_URL/v1/browser/actions?include_screenshot=true" \
  -H "Content-Type: application/json" \
  -d '{"action_type": "WAIT", "duration": 0.5}'

#执行动作

一次请求一个动作，坐标是屏幕坐标。加 ?include_screenshot=true 把观察步并入动作步：

curl -X POST "$BASE_URL/v2/computer/actions" \
  -H "Content-Type: application/json" \
  -d '{"action_type": "CLICK", "x": 640, "y": 400}'

curl -X POST "$BASE_URL/v2/computer/actions?include_screenshot=true" \
  -H "Content-Type: application/json" \
  -d '{"action_type": "SCROLL", "dx": 0, "dy": -3}'

curl -X POST "$BASE_URL/v1/browser/actions" \
  -H "Content-Type: application/json" \
  -d '{"action_type": "CLICK", "x": 640, "y": 400}'

curl -X POST "$BASE_URL/v1/browser/actions?include_screenshot=true" \
  -H "Content-Type: application/json" \
  -d '{"action_type": "SCROLL", "dx": 0, "dy": -3}'

from agent_sandbox import Sandbox
from agent_sandbox.browser.types.action import Action_Click

client = Sandbox(base_url="http://127.0.0.1:18091")
client.browser.execute_action(request=Action_Click(x=640, y=400))

import { SandboxClient } from "@agent-infra/sandbox";

const client = new SandboxClient({ environment: "http://127.0.0.1:18091" });
await client.browser.executeAction({ action_type: "CLICK", x: 640, y: 400 });

v1 和 v2 的动作请求体相同，例如点击屏幕坐标 (640, 400)：

{
  "action_type": "CLICK",
  "x": 640,
  "y": 400
}

请求体直接描述动作，action_type 决定具体执行哪一种：

• duration 的单位是秒；keys 是一个列表，复制是 ["ctrl", "c"]。
• window_id 来自窗口列表，node_id 来自无障碍树，两者都在下文。
• 有两条限制对每个动作都成立，单发和批量都一样：单个 WAIT 最多 10 秒，单个 SCROLL 每个方向最多 100 格。
• TYPING 对 ASCII 文本直接按键输入；含其他字符的文本走剪贴板（use_clipboard，默认 true），会覆盖剪贴板原有内容；use_clipboard: false 时这类文本返回 400，因为按键输入会丢字。剪贴板里的文本用 Shift+Insert 粘贴，终端和 GTK、Chromium 窗口都接受这个组合键。
• PRESS、HOTKEY、TYPING 成功只表示输入已送到焦点窗口，不表示应用已经响应。用截图确认结果。
• 每种类型的完整 schema 见 API 参考。

响应包含 status 和 action_performed。请求动作后的截图时，响应还会包含 base64 PNG。

如果截图失败，响应会在动作结果旁返回 screenshot_error，但不会让整个请求失败；动作本身已经执行。

#批量动作

curl -X POST "$BASE_URL/v2/computer/actions/batch" \
  -H "Content-Type: application/json" \
  -d '{"include_screenshot": true,
       "actions": [
         {"action_type": "HOTKEY", "keys": ["ctrl", "l"]},
         {"action_type": "TYPING", "text": "example.com"},
         {"action_type": "PRESS", "key": "enter"}
       ]}'

#自己写自动化脚本

桌面就是一个普通的 X display，每条命令都带着 DISPLAY，所以直接操作屏幕的脚本可以通过 POST /v2/commands（v1 为 /v1/bash/exec）跑在上面这些动作所用的同一个桌面上。Computer 镜像自带 xdotool；pyautogui 用 pip install pyautogui 装一次即可：

sb = Aio(BASE_URL)  # 示例首页定义的 helper
sb.post("/v2/commands", command="pip install --quiet pyautogui", timeout=280)
sb.post("/v2/commands", command='''python3 - <<'EOF'
import pyautogui
pyautogui.moveTo(320, 240)
pyautogui.click()
pyautogui.write("hello")
pyautogui.screenshot("/tmp/desk.png")
EOF''')
print(sb.get("/v2/computer/cursor"))   # {'x': 320, 'y': 240}

#读取指针、剪贴板、窗口列表

#通过无障碍树操作

后端按平台提供：Linux 使用 AT-SPI2（Assistive Technology Service Provider Interface，辅助技术服务提供接口），Windows 使用 UI Automation（UIA）。

501 表示平台没有可用的后端，例如平台尚未实现，或 Linux 镜像缺少 AT-SPI 运行时。重试不会改变结果。

503 表示后端存在，但当前无法读取，例如没有交互桌面或没有获得焦点的窗口。Chromium/Electron 应用必须使用 --force-renderer-accessibility 启动，才会暴露无障碍树。

#录屏

client.display.record(action="start", save_path="/workspace/recordings/session.mp4")
client.display.record(action="stop")

await client.display.record({
  action: "start",
  save_path: "/workspace/recordings/session.mp4",
});
await client.display.record({ action: "stop" });

录制基于 ffmpeg，同一时间只能有一个在跑。start 接受这些采集参数：

save_path 可以省略。省略时，文件写入临时目录，文件名为 recording_<timestamp>.mp4。

父目录不存在时会自动创建；worker 无法写入目标目录时返回 400。

data 带上：

• status —— recording、stopped 或 idle
• duration —— 已录制的秒数
• save_path —— 文件写到哪里
• file_size_bytes —— 停止之后的文件大小

把录像存到 文件 API 能取到的路径下。销毁宿主前先停止录制。这样文件才完整可播放。

#Windows：安全桌面

安全桌面会拒绝输入，例如 UAC 提示或锁屏界面。单个动作返回 403，data 为 {"status": "denied", "reason": "secure-desktop-or-uipi"}。

这是 Windows 的会话边界，不是需要绕过的 bug。批量执行时，之前的动作已经完成，因此同样的拒绝会通过 200 响应中的 status 和 reason 返回。

#直接访问 worker API

computer-use 也能不经 aiod 直接被访问：

单独部署或给 worker 做健康检查时有用。

#Human in the loop

人可以进入 agent 正在驱动的终端、浏览器或桌面，查看运行过程，也可以接手登录或验证码，再把控制权交回去。

daemon 不需要为此改变配置。预构建镜像通过网关提供这些查看器，每个查看器都连接到 agent 已经在使用的对象：

Xvnc 同时是 X server 和 VNC server。人的点击直接作用于 display，worker 会在下一次截图中看到结果。

daemon 只提供 API；单独运行的 aiod 对这些查看器路径都返回 404。

预构建镜像已经配置好这些组件。

AIO 镜像在 DISPLAY=:99.0 上运行 Xvnc、openbox 和 Chromium，并提供 noVNC、DevTools 和 WebShell。

Computer 镜像在此基础上设置 AIO_DESKTOP=xfce。

XFCE 会话接管 display，computer-use worker 和 aiod 一起启动。会话 D-Bus 为 AT-SPI 提供支持，Chromium 使用 --force-renderer-accessibility，因此标签页内容会出现在无障碍树中。

#相关页面

• Computer Use 示例 —— 一次完整的验证过程：导航、通过无障碍树点链接、观察结果
• 浏览器 API —— 基于 CDP 的页面自动化
• 文件操作 —— 取回录像与下载