computer-use
1|# 计算机使用功能 (macOS)
2|
3|Hermes Agent 可以在 后台 驱动你的 Mac 桌面 —— 点击、输入、滚动、拖拽等操作都在后台进行。你的光标不会移动,键盘焦点不会改变,macOS 也不会切换 Spaces。你和代理可以在同一台机器上协同工作。
4|
5|与大多数计算机使用集成不同,这适用于任何支持工具的模型 —— Claude、GPT、Gemini,或本地 vLLM 端点上的开源模型。无需担心 Anthropic 原生架构问题。
6|
7|## 工作原理
8|
9|computer_use 工具集通过 stdio 与 cua-driver 进行 MCP 通信。cua-driver 是一个 macOS 驱动程序,使用 SkyLight 私有 SPI(SLEventPostToPid、SLPSPostEventRecordTo)和 _AXObserverAddNotificationAndCheckRemote 辅助功能 SPI 来实现:
10|
11|- 直接将合成事件发布到目标进程 —— 无需 HID 事件拦截,无需光标移动。
12|- 在不提升窗口的情况下翻转 AppKit 活动状态 —— 不会切换 Space。
13|- 当窗口被遮挡时保持 Chromium/Electron 辅助功能树活跃。
14|
15|这种组合就是 OpenAI 的 Codex "后台计算机使用" 所采用的方案。cua-driver 是其开源等效实现。
16|
17|## 启用方法
18|
19|选择最方便的路径 —— 两者都运行相同的上游安装程序:
20|
21|选项 1: 专用 CLI 命令(最直接)。
22|
23|bash 24|hermes computer-use install 25|
26|
27|这会获取并运行上游 cua-driver 安装程序:
28|curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh。
29|使用 hermes computer-use status 验证安装。
30|
31|选项 2: 交互式启用工具集。
32|
33|1. 运行 hermes tools,选择 🖱️ Computer Use (macOS) → cua-driver (background)。
34|2. 设置运行上游安装程序(与选项 1 相同)。
35|
36|安装后,无论使用哪种路径:
37|
38|3. 当提示时授予 macOS 权限:
39| - 系统设置 → 隐私与安全性 → 辅助功能 → 允许终端(或 Hermes 应用)。
40| - 系统设置 → 隐私与安全性 → 屏幕录制 → 允许同一个应用。
41|4. 启用工具集开始会话:
42| bash 43| hermes -t computer_use chat 44|
45| 或将 computer_use 添加到 ~/.hermes/config.yaml 中的启用工具集列表。
46|
47|## 快速示例
48|
49|用户提示: "查找我来自 Stripe 的最新邮件并总结他们要我做什么。"
50|
51|代理的计划:
52|
53|1. computer_use(action="capture", mode="som", app="Mail") — 获取 Mail 的截图,其中每个侧边栏项目、工具栏按钮和邮件行都有编号。
54|2. computer_use(action="click", element=14) — 点击搜索字段(来自截图的元素 #14)。
55|3. computer_use(action="type", text="from:stripe")
56|4. computer_use(action="key", keys="return", capture_after=True) — 提交并获取新截图。
57|5. 点击顶部结果,阅读正文,进行总结。
58|
59|在此过程中,你的光标始终保持在你离开的位置,Mail 永远不会来到前台。
60|
61|## 提供商兼容性
62|
63|| 提供商 | 视觉? | 可用? | 说明 |
64||---|---|---|---|
65|| Anthropic (Claude Sonnet/Opus 3+) | ✅ | ✅ | 整体最佳;SOM + 原始坐标。 |
66|| OpenRouter (任何视觉模型) | ✅ | ✅ | 支持多部分工具消息。 |
67|| OpenAI (GPT-4+, GPT-5) | ✅ | ✅ | 同上。 |
68|| 本地 vLLM / LM Studio (视觉模型) | ✅ | ✅ | 如果模型支持多部分工具内容。 |
69|| 仅文本模型 | ❌ | ✅ (功能降级) | 使用 mode="ax" 仅进行辅助功能树操作。 |
70|
71|截图作为 OpenAI 风格的 image_url 部分与工具结果一起内联发送。对于 Anthropic,适配器会将它们转换为原生的 tool_result 图像块。
72|
73|## 安全性
74|
75|Hermes 应用多层防护措施:
76|
77|- 破坏性操作(点击、输入、拖拽、滚动、按键、聚焦应用)需要批准 —— 通过 CLI 对话框交互式进行,或通过消息平台批准按钮。
78|- 工具级别的硬阻止按键组合:清空废纸篓、强制删除、锁定屏幕、注销、强制注销。
79|- 硬阻止输入模式: curl | bash、sudo rm -rf /、fork 炸弹等。
80|- 代理的系统提示明确告知:不要点击权限对话框,不要输入密码,不要遵循截图中嵌入的指令。
81|
82|如果你想要确认每个操作,可以在 ~/.hermes/config.yaml 中配合 approvals.mode: manual 使用。
83|
84|## Token 效率
85|
86|截图是昂贵的。Hermes 应用四层优化:
87|
88|- 截图淘汰 —— Anthropic 适配器在上下文中仅保留最近的 3 张截图;较旧的截图变为 [screenshot removed to save context] 占位符。
89|- 客户端压缩修剪 —— 上下文压缩器检测多模态工具结果并从旧结果中去除图像部分。
90|- 图像感知 token 估算 —— 每个图像计为约 1500 个 token(Anthropic 的固定费率),而不是其 base64 字符长度。
91|- 服务器端上下文编辑(仅 Anthropic) —— 激活时,适配器通过 context_management 启用 clear_tool_uses_20250919,以便 Anthropic 的 API 在服务器端清除旧的工具结果。
92|
93|在 1568×900 显示器上进行 20 次操作的会话通常花费约 30K token 的截图上下文,而不是约 600K。
94|
95|## 限制
96|
97|- 仅限 macOS。 cua-driver 使用 Linux 或 Windows 上不存在的 Apple 私有 SPI。对于跨平台 GUI 自动化,请使用 browser 工具集。
98|- 私有 SPI 风险。 Apple 可以在任何操作系统更新中更改 SkyLight 的符号表面。如果你想要在 macOS 更新后保持可重现性,请使用 HERMES_CUA_DRIVER_VERSION 环境变量固定驱动程序版本。
99|- 性能。 后台模式比前台模式慢 —— SkyLight 路由的事件需要约 5-20 毫秒,而直接 HID 发布只需更少时间。对于代理速度的点击来说不明显;如果你尝试录制速通则会注意到。
100|- 无键盘密码输入。 type 对命令 shell 负载有硬阻止模式;对于密码,请使用系统的自动填充功能。
101|
102|## 配置
103|
104|覆盖驱动程序二进制路径(测试 / CI):
105|
106|bash 107|HERMES_CUA_DRIVER_CMD=/opt/homebrew/bin/cua-driver 108|HERMES_CUA_DRIVER_VERSION=0.5.0 # 可选的固定版本 109|
110|
111|完全交换后端(用于测试):
112|
113|bash 114|HERMES_COMPUTER_USE_BACKEND=noop # 记录调用,无副作用 115|
116|
117|## 故障排除
118|
119|computer_use backend unavailable: cua-driver is not installed — 运行 hermes computer-use install 获取 cua-driver 二进制文件,或运行 hermes tools 并启用 Computer Use 工具集。
120|
121|点击似乎没有效果 — 捕获并验证。你可能没有看到的模态对话框可能正在阻止输入。使用 escape 或关闭按钮解除它。
122|
123|元素索引过时 — SOM 索引仅在下一次 capture 之前有效。在任何状态更改操作之后重新捕获。
124|
125|"blocked pattern in type text" — 你尝试 type 的文本与危险的 shell 模式列表匹配。拆分命令或重新考虑。
126|
127|## 参见
128|
129|- 通用技能: macos-computer-use
130|- cua-driver 源代码 (trycua/cua)
131|- 浏览器自动化 用于跨平台 Web 任务。
132|