usecomputer

usecomputer

面向 AI Agent 的桌面自动化命令行工具。适用于 macOS、Linux（X11）和 Windows。通过 Zig 二进制文件调用原生平台 API 来截屏、点击、输入、 滚动和拖动——运行时无需 Node.js。

始终先运行 --help

使用此工具前，始终先运行 usecomputer --help。 帮助输出是所有命令、 选项和示例的权威依据。切勿猜测命令语法——先查看帮助。

运行帮助命令时，请阅读完整且未截断的输出。切勿将帮助内容通过 head、tail 或 sed 管道处理——否则会漏掉关键选项。

usecomputer --help
usecomputer screenshot --help
usecomputer click --help
usecomputer drag --help

安装

npm install -g usecomputer

要求：

• macOS — 为终端应用启用辅助功能权限
• Linux — 使用设置了 DISPLAY 的 X11 会话（也支持通过 XWayland 使用 Wayland）
• Windows — 在交互式桌面会话中运行

核心循环：截屏 -> 操作 -> 截屏

每次使用计算机的会话都遵循一个反馈循环：

screenshot -> send to model -> model returns action -> execute action -> screenshot again
     ^                                                                        |
     |________________________________________________________________________|

1. 使用 usecomputer screenshot --json 截屏
2. 将截图图像发送给模型
3. 模型返回坐标或操作（点击、输入、按键、滚动）
4. 执行操作，并传入第 1 步中的确切 --coord-map
5. 重新截屏，然后回到第 2 步

完整循环示例

# 1. take screenshot (always use --json to get coordMap)
usecomputer screenshot ./tmp/screen.png --json
# output: {"path":"./tmp/screen.png","coordMap":"0,0,3440,1440,1568,657",...}

# 2. send ./tmp/screen.png to the model
# 3. model says: "click the Save button at x=740 y=320"

# 4. click using the coord-map from the screenshot output
usecomputer click -x 740 -y 320 --coord-map "0,0,3440,1440,1568,657"

# 5. take a fresh screenshot to see what happened
usecomputer screenshot ./tmp/screen.png --json
# ... repeat

切勿跳过 --coord-map。 截图会经过缩放（最长边 <= 1568px）。 coord-map 会将截图空间中的像素映射回真实桌面坐标。 没有它，点击位置就会出错。

每次操作后都要重新截屏。 每次点击、滚动或按键后，界面都会发生变化—— 菜单会打开、页面会滚动、对话框会出现。 切勿重复使用过时的截图。

窗口范围截图

完整桌面截图包含所有内容——Dock、菜单栏和背景窗口。为了提高准确性， 只截取目标应用窗口。这样生成的图像更小、更聚焦，便于模型推理。

第 1 步：查找窗口 ID

usecomputer window list --json

这会返回一个可见窗口数组，其中包含各窗口的 id、ownerName、 title、位置和尺寸。找到你想要操作的窗口。

第 2 步：截取该窗口

usecomputer screenshot ./tmp/app.png --window 12345 --json
# output: {"path":"./tmp/app.png","coordMap":"200,100,1200,800,1568,1045",...}

输出中的 coord-map 仅对应屏幕上该窗口所在区域。

第 3 步：使用 coord-map 操作

# model analyzes ./tmp/app.png and says click at x=400 y=220
usecomputer click -x 400 -y 220 --coord-map "200,100,1200,800,1568,1045"

coord-map 会将窗口截图像素空间中的坐标映射回正确的桌面坐标。即使 截图中只显示一个窗口，点击也会落在正确位置。

区域截图

你也可以截取屏幕上的任意矩形区域：

usecomputer screenshot ./tmp/region.png --region "100,100,800,600" --json

coord-map 的用法相同——将它传给后续的指针命令即可。

coord-map 说明

coord-map 是每次截屏都会输出的 6 个逗号分隔值：

captureX,captureY,captureWidth,captureHeight,imageWidth,imageHeight

• captureX, captureY — 捕获区域左上角的桌面坐标
• captureWidth, captureHeight — 捕获区域的桌面像素尺寸
• imageWidth, imageHeight — 输出 PNG 的尺寸（缩放后）

向 click、hover、drag 或 mouse move 传入 --coord-map 时， 命令会使用这些值，将截图空间中的 x、y 坐标映射回真实的桌面位置。

使用 debug-point 验证坐标

点击前，可以验证点击会落在哪里：

usecomputer debug-point -x 400 -y 220 --coord-map "0,0,1600,900,1568,882"

这会截取一张截图，并在映射后的坐标处绘制红色标记。将输出图像发回给 模型，让它确认目标位置是否正确，并在需要时进行调整。

快速示例

# screenshot the primary display
usecomputer screenshot ./tmp/screen.png --json

# screenshot a specific display (0-indexed)
usecomputer screenshot ./tmp/screen.png --display 1 --json

# click at screenshot coordinates
usecomputer click -x 600 -y 400 --coord-map "0,0,1600,900,1568,882"

# right-click
usecomputer click -x 600 -y 400 --button right --coord-map "..."

# double-click
usecomputer click -x 600 -y 400 --count 2 --coord-map "..."

# click with modifier keys held
usecomputer click -x 600 -y 400 --modifier option --coord-map "..."
usecomputer click -x 600 -y 400 --modifier cmd --modifier shift --coord-map "..."

# type text
usecomputer type "hello from usecomputer"

# type long text from stdin
cat ./notes.txt | usecomputer type --stdin --chunk-size 4000 --chunk-delay 15

# press a key
usecomputer press "enter"

# press a shortcut
usecomputer press "cmd+s"
usecomputer press "cmd+shift+p"

# press with repeat
usecomputer press "down" --count 10 --delay 30

# scroll
usecomputer scroll down 5
usecomputer scroll up 3
usecomputer scroll down 5 --at "400,300"

# drag (straight line)
usecomputer drag 100,200 500,600

# drag (curved path with bezier control point)
usecomputer drag 100,200 500,600 300,50

# drag with coord-map
usecomputer drag 100,200 500,600 --coord-map "..."

# mouse position
usecomputer mouse position --json

# list displays
usecomputer display list --json

# list windows
usecomputer window list --json

# list desktops with windows
usecomputer desktop list --windows --json

提高点击准确性的系统提示词建议

使用 GPT-5.4 或 Claude 操作电脑时，请保持系统提示词简短，并聚焦于任务。冗长的系统提示词会降低点击准确性。

GPT-5.4： 对截图输入使用 detail: "original"。这是提高点击准确性最重要的一项设置。避免使用 detail: "high" 或 detail: "low"。

Claude： 使用 computer_20251124 工具类型，并将 display_width_px 和 display_height_px 设置为与 coord-map 输出中的截图尺寸一致。

一般规则：

• 每次操作后都截取一张新截图
• 始终传入模型所分析截图对应的 coord-map
• 如果点击位置不正确，请使用 debug-point 进行诊断
• 如果模型返回的坐标超出截图尺寸，请重新发送截图并提醒模型图像尺寸

故障排除

1. 点击位置不正确 — 你可能忘记了 --coord-map，或者传入的 coord-map 与模型所分析的截图不匹配。始终使用最新截图对应的 coord-map。

2. Retina 显示器 — usecomputer 会通过 coord-map 在内部处理缩放。不要尝试手动换算显示缩放比例。

3. 过期截图 — 这是最常见的故障来源。每次操作后都要截取一张新截图。界面会不断变化。

4. macOS 上的权限错误 — 在“系统设置”>“隐私与安全性”>“辅助功能”中，为你的终端应用启用辅助功能权限。

5. Linux 上的 X11 错误 — 确保已设置 DISPLAY。对于 XWayland，如果 XShm 失败，截图会自动回退到 XGetImage。