glovebox

glovebox

为 macOS 上的编码 Agent 提供计算机操作能力：每步只需调用一次 JavaScript， 使用无障碍差异而非屏幕截图，并且不占用你的屏幕。

const calc = await gb.getApp("Calculator");
await calc.pressKey("Escape");
await calc.typeText("6*7=");
await calc.getAXState();

Calculator — window 0 "Calculator" — image 460x816 — changes since last read (~ changed, + added):
~					8 scroll area id=StandardInputView;value:42
~						9 text "Edit field" value="42"

下一次调用时，calc 仍然保持绑定。Agent 每步只需编写几行代码， 而不是每次点击都调用一次工具；它读取的是发生了哪些变化，而非窗口的全新截图。

• 每步运行一段脚本，而非每次点击都调用工具。 绑定和辅助函数会 在多次调用间保留，因此一次调用即可点击、输入、循环和读取。
• 使用差异，而非屏幕截图。 默认读取内容是无障碍树的文本形式， 后续读取只显示变化。如果无障碍树为空（Citrix、画布），则可使用屏幕截图和像素点击。
• 默认在后台操作。 你在其他应用中继续工作时，按键、点击、拖动和滚动仍会作用于目标应用。 光标会保持原位，并会显示一个绘制出来的光标，指示 Agent 正在执行的操作。

在作者进行的测试中，使用 6 种配置完成 12 项任务（每项运行 2 次）， glovebox 的总成本最低，为 $0.57，而其他配置为 $1.41 至 $5.67；它的往返次数最少，通过次数最多。

请先了解： 仅支持 macOS，已在 Apple 芯片的 macOS 27 上测试。你需要 Xcode 命令行工具来 构建一个小型辅助应用，并授予它“辅助功能”和“屏幕录制”权限。后台输入使用两个私有 macOS 调用，并提供前台回退方案。端到端测试仅覆盖了 Claude Code。尽管名称中有 glovebox， 它并非沙箱，也与 glovebox-mcp 无关。

快速开始

需要 Node 20.10+ 和 Xcode 命令行工具（xcode-select --install）。

npm install -g @vashp2029/glovebox
glovebox signing --create   # optional: macOS keeps the grants across helper rebuilds
glovebox setup              # builds the helper, walks through permissions
glovebox doctor             # every line should say ok
glovebox smoke              # a real end-to-end test on Calculator
claude mcp add --scope user glovebox -- glovebox mcp

setup 会将 Glovebox Helper.app 构建到 ~/.glovebox/，并提示你在“系统设置”>“隐私与安全性”> **“辅助功能”和“屏幕与系统音频录制”中启用它。“输入监控”**为可选权限，仅用于启用按 Escape 停止。 辅助应用是独立的应用，因此授予一次权限即可供所有 Agent 和终端使用。signing --create 会在你的登录钥匙串中 创建自签名证书，仅用于签署辅助应用。如果不创建证书，macOS 会将每次重新构建都视为新应用；请参阅升级说明。

适用对象： Claude Code（已完成端到端测试）。Codex、Grok CLI、OpenCode、 Gemini CLI 和 Cursor 都有文档介绍其配置，但尚未实际验证。 任何能够运行 shell 命令的 Agent 都可以使用 glovebox run。 请参阅 docs/agents.md。

为什么不使用 Claude Code 内置的计算机使用功能？

如果它适合你的设置，那它是更简单的选择：无需安装，受 Anthropic 支持，而且不会让你的终端出现在截图中。glovebox 面向不适合使用它的情况。以下内容摘自 Anthropic 的文档，核查日期为 2026-11-03：

	Claude Code 内置功能	glovebox
你的其他应用	Claude 工作时会隐藏	保持可见；输入会在后台发送到目标应用
默认读取方式	缩小后的截图	无障碍文本差异
谁可以使用	通过 claude.ai 使用的 Pro、Max 或 Ultra；不包括 Team、Enterprise、Bedrock、Google Cloud 或 Foundry	任何人；它不会与模型或账户通信
脚本化运行	不支持 -p 模式	基准测试会通过脚本驱动它自动运行；尚未测试 claude -p 本身
会话	一次一个，由锁文件强制执行	没有全局锁；可同时运行多个命名会话
记住授权	仅限当前会话	允许本次会话或始终允许
浏览器	仅查看	批准浏览器后可完全控制，权限更大，风险也更高

Claude Code 内置工具未参与下方基准测试，因此此表比较的是文档所述行为，而非实测结果。

基准测试

2026-11-03，在 macOS 上测试了 12 项任务、6 种配置，每项任务运行两次。所有配置使用相同的模型（Claude Sonnet 5.5，中等强度）、提示词和 Agent 循环；唯一变化的是工具。任务提示词未指定任何工具，并通过一个不使用待测工具的独立检查来判定结果。

配置	通过	往返次数	返回的图像数	按标价计算的费用
glovebox	24/24	128	21	$0.57
由 Claude 驱动的 Codex cua_repl	20/24	166	30	$1.41
由 glovebox 运行的 Anthropic 工具集	22/24	187	179	$1.65
agent-desktop	22/24	204	22	$2.32
open-computer-use	21/24	244	385	$2.76
Peekaboo	20/24	359	183	$5.67

glovebox 未胜出的方面。 在 finder-rename 上，它并非最便宜（费用为 $0.061，而 Codex cua_repl 为 $0.041）。在 12 项任务中，它有 3 项往返次数不是最少，还有 3 项耗时不是最短。在 remote-desktop 上，它耗时 36 秒，而另外两种配置分别耗时 22 秒和 23 秒。

这些结果有多大参考价值：

• 任务由我编写，测试也由我在一台 Mac 上一次完成。几项任务（bulk-entry、remote-desktop、coexistence）是围绕 glovebox 的目标设计的。
• 每项任务只运行两次，因此通过次数意义不大：24/24 与 20/24 的差异不具备统计显著性。费用差距则更可靠，因为逐项任务都能体现这一点：glovebox 在 12 项任务中至少有 11 项的费用低于其他每种配置。
• 测试的 glovebox 是以 0.3.0 版本发布的代码。结果文件中写的是 0.2.0，因为当时尚未更新版本号。
• “Anthropic 工具集”指 Anthropic 的 API 计算机使用工具集，通过 glovebox 的前台路径执行。它因该路径而在 coexistence 上失败，因此这一结果不能代表已发布产品的表现。“Codex cua_repl”测量的是该工具在 Claude 下的表现形式，并非使用自身模型的 Codex。
• Peekaboo 的第一次测试在允许前台输入后重新运行，这对它有所帮助。它在 bulk-entry 上的两次失败，是因为运行触及了我设定的每次 $0.75 预算上限。agent-desktop 通过其 CLI 运行，而非 MCP 模式。

测试方法、各任务的数据和原始结果：bench/ 和 bench/results/v2/summary.md。

对比

于 2026-11-03 对照各项目的 README 和文档进行核查。“—”表示无法从中确认。

	平台	每次调用的操作数	调用间状态	默认读取内容	差异读取	后台输入	需求
glovebox	macOS	多个（一个脚本）	持久 JS 会话	辅助功能文本	是	是	需安装 Xcode CLT 以构建辅助工具
Claude Code 内置功能	macOS（CLI）	—	—	截图	—	否，会隐藏其他应用	Pro、Max 或 Ultra
Codex 电脑操控	macOS、Windows	多个（一个脚本）	持久 JS 会话	辅助功能文本	是	macOS 上支持	ChatGPT 应用和插件
lcu	macOS（Apple silicon）、Linux	与 Codex 相同；它运行 Codex 的运行时	与 Codex 相同	与 Codex 相同	与 Codex 相同	—	已安装 ChatGPT 应用
agent-desktop	macOS、Windows、Linux	每条命令一个，另有 batch	引用与快照绑定	辅助功能树 JSON	—	是	Homebrew 或 npm
Peekaboo	macOS 15+	每条命令一个	来自快照的元素 ID	截图或 JSON UI 映射	—	是	Homebrew 或 npm
open-computer-use	macOS、Linux、Windows	每次 MCP 调用一个；CLI 支持序列	—	应用状态	—	—	npm
computer-use-mcp	macOS 14+	每次调用一个	元素 ID	每次操作提供截图和树	—	是	经公证的二进制文件
cua-driver	macOS、Windows、Linux	—	—	—	—	是	参见其文档

如果你需要 Windows 或 Linux（agent-desktop、cua-driver、lcu），无需构建步骤的经公证二进制文件（computer-use-mcp），或者想使用 OpenAI 的实际运行时且已安装 ChatGPT 应用（lcu），请选用其他方案。

安全性

会话首次操作某个应用时，你会看到一个对话框：允许本次会话、始终允许或拒绝。除非运行 glovebox allow <bundle id>，否则终端、密码管理器、系统设置和其他少数应用会被屏蔽；列表见 SECURITY.md。如果脚本必须将某个应用置于前台，而你切换到其他应用，脚本就会停止。在后台运行的脚本会在你使用其他应用时继续执行；如果你授予“输入监控”权限，按下 Escape 可停止任何脚本。每项操作都会记录到 ~/.glovebox/actions.log。

获准的应用意味着其中的所有内容都已获准：允许浏览器后，Agent 就可以使用你已登录的所有网站。glovebox 不会筛查页面内容以检测提示词注入。请将其视为把该应用的远程控制权交给他人。详情：SECURITY.md。

已知问题： 后台应用的弹出菜单打开时，macOS 会将你的按键发送给该应用，因此你输入的文字可能会落入其中（详情）。

工作原理

agent ──MCP stdio──▶ glovebox mcp ──▶ kernel (persistent JS session)
agent ──shell──▶ glovebox run ──▶ daemon ──▶ kernel        │
                                                            ▼ Unix socket
                                        Glovebox Helper.app (Swift: AX, CGEvent,
                                        ScreenCaptureKit, approval dialogs)

后台输入会使用两个 macOS（SkyLight）私有函数，并在运行时查找；若不可用则回退到前台输入；glovebox doctor 会报告你使用的路径。其他所有功能都使用公开 API。不包含 OpenAI、Anthropic 或其他供应商的二进制文件。

状态

平台	状态
macOS	可用。为 macOS 14+ 构建；仅在 macOS 27（Apple silicon）上测试。
Windows	计划支持（UI Automation）。参见路线图。
Linux	计划支持（AT-SPI；Wayland 支持有限）。参见路线图。

运行真实测试，而非模拟测试：通过 MCP 运行 glovebox smoke 和 smoke --full（批处理步骤、持久绑定、差异、像素点击，以及在另一应用处于前台时执行后台点击、拖动和滚动）；并通过 glovebox mcp 连接 Claude Code。完整列表：docs/testing.md。

一屏了解 API

• gb.getApp(name) 可启动或查找应用，且不会抢占焦点。gb.listApps()。
• app.getAXState() 以文本形式返回无障碍树；后续读取返回差异。{frames: true} 会添加元素框，{disableDiffing: true} 会返回完整树。
• app.getScreenshot() 是获取图像的唯一方式。
• app.click(target)、doubleClick、rightClick、scroll、drag、setValue、focus、selectText、performSecondaryAction。
• app.pressKey("ctrl+a") 使用 xdotool 名称（super 表示 Cmd）。app.typeText("text\n")。
• app.waitForChange() 和 app.settle() 用于等待延迟更新。
• 目标可以是树中的元素索引，也可以是窗口图像中的 [x, y] 像素坐标，即截图的像素空间。

完整参考：docs/api.md，或在会话中调用 help()。

文档

• docs/api.md：面向 Agent 和脚本作者的脚本 API。
• docs/agents.md：连接各个 MCP 客户端或仅使用 shell 的 Agent。
• docs/cli.md：所有子命令、标志、配置项和环境变量。
• docs/recipes.md：可粘贴到一次 js 调用中的简短脚本。
• docs/design.md：面向贡献者和评估者的设计决策及其原因。
• docs/backend-protocol.md：辅助程序协议，用于移植到新平台。
• docs/testing.md：单元测试和冒烟测试，以及在真实硬件上运行过的测试。
• docs/roadmap.md：计划中的工作；其中没有已发布的内容。
• SECURITY.md：哪些内容能保护你、哪些不能，以及如何报告漏洞。
• CONTRIBUTING.md：从克隆开始的设置、测试和拉取请求规则。
• CHANGELOG.md：各版本的变更和升级说明。

许可证

MIT