Computer Use

munim-computer-use

下载  •  阅读文档  •  报告问题  •  munimtech.com/munim-computer-use

关注 Munim Technologies

   

简介

Computer Use 是一个开源 MCP 服务——一个计算机操作 Agent（CUA）后端——让任何编码 Agent 都能像人一样使用你的电脑。它通过无障碍树读取屏幕，在后台点击和输入文字，让鼠标仍由你掌控；它会显示 Agent 指针以标示当前操作位置，放大细小文字，并操控已登录 Chrome 中的标签页——支持 macOS、Windows 和 Linux。

可与 Claude Code、Codex、Cursor 和 MT Code 配合使用，也可与任何其他 MCP 客户端及任何模型配合使用——交互无需视觉模型。

由 Munim Technologies 构建，作为 MT Code 的 Computer Use 引擎，并在此独立发布。

目录

• 快速开始
• 能力矩阵
• 基准测试
• 表现出色的原因
• 与你并肩工作
• Agent 可能使用的应用和网站
• 工具
• 代码库布局
• 环境标志
• 在应用中嵌入
• 为 Agent 编写提示词
• 参与贡献
• 致谢和许可证

快速开始

1. 从 Releases 下载适用于你平台的最新二进制文件（munim-computer-use-macos-universal.zip、munim-computer-use-windows-x64.zip），或从源代码构建。
2. 将其放在 PATH 中的某个位置（/usr/local/bin/munim-computer-use，或 %LOCALAPPDATA%\Programs\munim-computer-use\munim-computer-use.exe）。
3. 仅限 macOS：运行一次 munim-computer-use request-permissions，以请求辅助功能和屏幕录制权限。
4. 将其注册到你的 Agent：

# Claude Code — fastest: the npm launcher fetches the signed binary on first run.
# Add `--scope user` to register it for every project instead of just this one.
claude mcp add munim-computer-use -- npx -y munim-computer-use
# or point at a downloaded binary
claude mcp add munim-computer-use -- /usr/local/bin/munim-computer-use

# Codex — writes the entry below into ~/.codex/config.toml for you (needs a Codex CLI
# with `codex mcp`; check with `codex mcp --help`)
codex mcp add munim-computer-use -- npx -y munim-computer-use

# Codex — ~/.codex/config.toml, if you would rather edit it yourself
[mcp_servers.munim-computer-use]
command = "npx"
args = ["-y", "munim-computer-use"]

# Cursor — no MCP subcommand in its CLI, so write the config. ~/.cursor/mcp.json applies
# to every project; .cursor/mcp.json in a repo applies to that one.
mkdir -p ~/.cursor && [ -s ~/.cursor/mcp.json ] || echo '{}' > ~/.cursor/mcp.json
jq '.mcpServers["munim-computer-use"] = {"command":"npx","args":["-y","munim-computer-use"]}' \
  ~/.cursor/mcp.json > ~/.cursor/mcp.json.tmp && mv ~/.cursor/mcp.json.tmp ~/.cursor/mcp.json

// Cursor — the entry that produces, in .cursor/mcp.json
{ "mcpServers": { "munim-computer-use": { "command": "npx", "args": ["-y", "munim-computer-use"] } } }

然后询问：“打开 Safari，查找周二飞往丹佛的最便宜航班，并将其记到笔记里。”Agent 使用 get_app_state 读取界面，通过元素 ID 执行操作，并使用 screenshot 进行验证。

能力矩阵

Munim Computer Use 是重点展示的第一列；其他列是人们常用的电脑操作服务。每个单元格的信息均来自该项目自身在 2026 年 9 月和 10 月的 README 或文档（来源见致谢和许可证）。✅ 表示存在 · ❌ 表示不存在或未记录 · ⚠️ 表示部分支持。

能力	Munim Computer Use	Cua Driver	Codex Computer Use	OpenAI Agents API	Anthropic reference demo	Windows-MCP	MacOS-MCP	open-computer-use	computer-use-mcp (zavora)	说明
macOS	✅	✅	✅	n/a	❌	❌	✅	✅	✅	Anthropic 演示会在 Docker 内驱动 Linux 桌面，而不是你的电脑。OpenAI Agents API（2026 年 9 月）运行的是由 OpenAI 托管的浏览器，因此也不会驱动你的电脑。
Windows	✅	✅	✅	n/a	❌	✅	❌	✅	✅	Windows-MCP 仅支持 Windows；MacOS-MCP 仅支持 macOS。
Linux	✅	✅	❌	n/a	✅ (sandbox)	❌	❌	✅	✅	Munim Computer Use 使用 AT-SPI + X11；原生 Wayland 应用支持元素操作，但不支持坐标点击。
带元素 ID 的无障碍树	✅	✅	⚠️	❌	❌	✅	✅	✅	✅	Codex 会先读取 macOS 上的无障碍树，在 Windows 上则通过截图操作；Agents API 和 Anthropic 演示依赖截图。ID 让 Agent 可以按下 按钮，而不是点击像素。
后台输入（鼠标不会移动）	✅	✅	⚠️	n/a	n/a	❌	❌	❌	❌	Munim Computer Use 会将事件发送到目标窗口：在 macOS 上始终如此（SkyLight 和进程级事件）；在 Windows 上适用于 UI Automation 模式和经典 Win32 控件；其他 Windows UI 和所有 Linux 指针输入（XTEST）仍会移动真实指针。Codex 可在 macOS 后台运行并使用自己的光标，在 Windows 上则会接管指针。Cua Driver 默认在后台执行，如果未生效则切换到前台。此表中的其他服务会驱动真实光标。
Agent 指针叠加层	✅	✅	✅	❌	❌	⚠️	❌	❌	❌	Windows-MCP 会在捕获内容周围闪烁边框；Codex 和 Cua Driver 会在屏幕上绘制自己的光标。
以全分辨率放大某个区域	✅	✅	❌	❌	✅	❌	❌	❌	❌	Anthropic 的工具集有 zoom；这里的每个平台都有此工具。
截图包含屏幕坐标映射	✅	⚠️	n/a	n/a	n/a	❌	❌	❌	❌	每次捕获都会包含原点和每点像素数，因此 Retina 或缩小后的图像中的点击都能准确落点。
悬停、等待、标签查询	✅	⚠️	⚠️	❌	⚠️	✅	⚠️	❌	⚠️	Windows-MCP 提供 Wait/WaitFor；MacOS-MCP 提供 Wait；Anthropic 提供 wait/mouse_move。
使用已登录的 Chrome、自己的标签组，或已有标签页	✅	⚠️	⚠️	❌	❌	⚠️	❌	❌	❌	Codex 使用其应用内浏览器；Cua Driver 通过 CDP 连接浏览器；Windows-MCP 读取已打开浏览器的 DOM。Munim Computer Use 会在你的真实 Chrome 中打开自己的带标签标签组，也可以在你提出要求时接管已打开的标签页。
一次调用中执行并观察	✅	✅	n/a	n/a	✅	❌	❌	❌	❌	在任意操作中使用 return_state，都会附加最新的无障碍树或页面快照，因此一次调用即可执行并检查。Cua Driver 的 run_steps 会运行多个操作并报告变化。Anthropic 演示会在每次操作后返回截图；Codex 和 Agents API 则自行运行循环。
一次调用中执行多个操作	✅	✅	n/a	n/a	❌	⚠️	❌	❌	✅	Cua Driver 和 computer-use-mcp (zavora) 使用 run_steps 在一次调用中运行一系列步骤；Windows-MCP 的 MultiSelect 和 MultiEdit 可同时操作多个元素。Munim Computer Use 的 run_steps 也能执行相同操作，会在运行前检查整个步骤列表，并在首次失败时停止。
在已登录的标签页中读取页面文本	✅	⚠️	❌	❌	❌	⚠️	❌	❌	❌	browser_read 会从后台标签页分块返回包含标题的页面文本，并支持使用 query 进行筛选。Windows-MCP 会抓取页面内容。
登录时不让模型看到密码	✅	❌	❌	✅	❌	❌	❌	❌	❌	browser_request_credentials 会打开一个 Chrome 窗口，并显示网站的真实来源；用户输入的内容会直接进入页面，不会进入对话。Agents API 也会以同样方式将登录交给开发者的应用处理。默认情况下，桌面密码字段会拒绝输入。
按应用和网站设置允许／询问／阻止规则	✅	❌	⚠️	⚠️	❌	❌	❌	❌	❌	由用户控制的策略文件；每项任务中，ask 都会显示一次审批提示。Codex 会在每个新应用启动前询问，并保留“始终允许”列表；Agents API 会在每个新网站打开前向开发者的应用询问。
兼容任何 MCP 客户端	✅	✅	❌	❌	❌	✅	✅	✅	✅	Codex Computer Use 仅适用于 Codex；Anthropic 演示仅适用于 Claude。
所有平台上的工具接口完全一致	✅	⚠️	n/a	n/a	n/a	n/a	n/a	⚠️	✅	Swift 和 Rust 服务共有 33 个工具，其架构逐字节相同。Cua Driver 通过 CI 检查确保共享参数保持同步，但有少数工具仅适用于某个平台。
预构建的签名二进制文件 + npm 启动器	✅	✅ (脚本)	✅	n/a	❌	❌	❌	✅ (npm)	✅ (npm)	Releases 中提供 macOS 通用版（Developer ID 签名）和 Windows x64 版本。
开源	✅ Apache-2.0	✅ MIT	❌	❌	✅	✅ MIT	✅ MIT	✅ MIT	✅ MIT
另请参阅：mediar-ai/mcp-server-macos-use（macOS、辅助功能、真实输入）、deploymenttheory/windows-mcp-server（Windows、UIA Invoke 模式、WaitFor）、nuphus-mcp（OCR + 自带视觉模型、CDP Chrome）、computer-control-mcp（PyAutoGUI + OCR）以及 microsoft/playwright-mcp（仅限浏览器）。欢迎指正——请附上链接提交 issue。

图表统计了上方表格（n/a 单元格不计入），因此也存在与表格相同的偏差：行项目是我们自行挑选的。

基准测试

读取窗口是 Agent 最常重复的步骤。这里，所有能够运行的 Windows 服务都会读取同一个文件资源管理器窗口，文件夹中的文件数从 100 增长到 20,000。它们都只读取屏幕上显示的行，因此曲线保持平稳；差异在于耗时和 Token 数。munim-computer-use 在各种规模下都最快，返回的 Token 数也最少，约为次低者的一半。

服务	读取工具	100 个文件	1,000 个文件	5,000 个文件	20,000 个文件	每次读取的 Token 数（约）
munim-computer-use 0.8.0	get_app_state	0.14 s	0.13 s	0.16 s	0.14 s	2.0K
Cua Driver 0.38.0	get_window_state, include_screenshot: false	0.20 s	0.18 s	0.18 s	0.19 s	3.9K
Windows-MCP 0.8.5	Snapshot	0.77 s	0.77 s	0.78 s	0.76 s	3.8K
computer-use-mcp 7.8.0 (zavora)	get_ui_tree (COMPUTER_USE_PROFILE=full)	0.43 s	0.50 s	0.43 s	0.52 s	9.3K
open-computer-use 1.1.2	get_app_state	3.95 s	3.82 s	3.70 s	4.23 s	5.9K，包含屏幕截图
测量方式（2026 年 10 月 27 日）：Windows 11（build 26200），一台 1920×1080 显示器。针对每种文件夹大小，打开一个全新的文件资源管理器窗口并置于前台，然后每个服务启动一次，通过 stdio 调用其自带的读取工具，并使用默认参数（仅在工具有相应开关时使用纯文本；open-computer-use 始终附带截图）。丢弃一次预热调用，然后计时 5 次调用；整轮测试重复两次，因此每个时间都是 10 次的中位数。Token 数为估算值：文本按每 4 个字符算 1 个 token，图像按 Anthropic 的公式计算（API 缩放后的宽度 × 高度 / 750）。Windows-MCP 的 Snapshot 还会列出桌面上的其他窗口；其他工具只读取一个窗口。Terminator 未纳入测试：其 get_window_tree 会选中第一个 explorer 进程，也就是任务栏，而且它不接受 pid。

同一台 PC 上的操作测试：在计算器中点击 1 + 2 = 的 5 次操作（清除、1、+、2、=），每次点击都是一次单独调用，并通过元素 id 定位；此前先读取一次。取 3 轮测试的中位数。

服务	五次点击	每次点击
munim-computer-use 0.8.0	1.70 s	0.34 s
Cua Driver 0.38.0	2.32 s	0.46 s
munim-computer-use 0.7.3	2.98 s	0.60 s

点击操作的大部分时间都花在 Agent 指针飞向目标上，这样你可以看到 Agent 在哪里操作；0.8.0 将这段飞行时间缩短了一半。run_steps 会在一次调用中发送全部五步。

所有 Windows 版本都读取同一个窗口，使用发布版二进制文件；分两轮测试，每轮测试全部 17 个版本，并包含 Windows-MCP。另以同样方式将 0.8.0 与 0.7.3 对比（与上文的测试分开进行，因此时间略有不同）。从 0.7.0 起，get_app_state 只读取屏幕上显示的内容，并在一次请求中获取每个元素的属性；0.8.0 则改为一次请求获取整个窗口，而不是每个元素各请求一次，输出保持不变。

数据

版本	读取时间（中位数）	字符数	Token 数（≈）
0.2.0	0.40 s	9,860	2.5K
0.3.0	0.43 s	9,860	2.5K
0.3.1	0.38 s	9,860	2.5K
0.4.0	0.38 s	9,860	2.5K
0.4.1	0.38 s	9,860	2.5K
0.4.2	0.39 s	9,860	2.5K
0.4.3	0.40 s	9,860	2.5K
0.4.4	0.38 s	9,860	2.5K
0.5.0	0.38 s	9,860	2.5K
0.5.1	0.37 s	9,860	2.5K
0.5.2	0.43 s	9,860	2.5K
0.6.0	0.37 s	9,860	2.5K
0.6.1	0.41 s	9,860	2.5K
0.7.0	0.23 s	7,499	1.9K
0.7.1	0.28 s	7,499	1.9K
0.7.2	0.25 s	7,520	1.9K
0.7.3	0.25 s	7,520	1.9K
0.8.0	0.16 s	7,515	1.9K
Windows-MCP 0.8.5 Snapshot	0.75 s	14,929	3.7K

运行 node scripts/readme-charts.mjs 可重新绘制图表；覆盖率图表的数据由功能矩阵统计得出。

为什么它表现出色

• 无障碍优先，像素其次。 get_app_state 会返回应用的无障碍树，其中包含稳定的元素 ID，因此 Agent 可以按下_按钮_，而不必猜测坐标。它消耗的令牌只有截图的一小部分，而且在 OSWorld 风格的任务中得分最高。截图用于验证，以及查看树无法描述的内容。
• 快速了解屏幕上的内容。 get_app_state 会列出当前视图中的内容：列表或表格会显示可见行，滚动到视图之外的内容则会跳过并计数（也会列出 offscreen: true 的内容）。每个元素的属性通过一次请求读取；在 Windows 上，整个窗口只需一次请求即可返回。读取包含 2,000 个文件的 Finder 窗口只需 165 ms，而非 2.2 s；读取 File Explorer 窗口约需 0.15 s，比我们测量过的其他 Windows 服务都快（参见基准测试）。
• 优先处理对话框。 当工作表、警报或弹出窗口遮挡窗口时，只会列出其中的控件，并附带说明，让 Agent 处理对话框，而不是点击其后方的内容。
• Electron 和 Chromium 应用（macOS）。 Slack、VS Code、Discord 和其他基于 Chromium 的应用只会向主动请求的客户端公开其树；get_app_state 会发起请求，并在后台应用仍在构建树时说明这一点。
• 读取树无法描述的文本。 当应用未公开带标签的控件时，会使用设备端 OCR 读取窗口（macOS 上使用 Apple Vision，Windows 上使用 Windows OCR），并列出文本及对应 ID，供 click、hover、right_click 和 drag 使用。图像不会离开设备。ocr: "always" 或 "never" 可覆盖此设置。
• 失效时报错，而非误操作的 ID。 每次执行操作前都会重新检查 ID。如果元素已消失，或其角色或名称发生变化（例如对话框更换了按钮、列表重新排序），操作会失败并返回清晰的错误，而不会对当前位于该位置的内容执行操作。
• 等待时间随应用而定。 return_state 会等待应用的无障碍通知停止，而不是固定暂停：编辑字段约需 230 ms（之前为 350 ms），等待工作表完全滑入所需的时间也会一并等待。
• 后台控制。 事件会发送到目标窗口（macOS 上使用 SkyLight，Windows 上使用 UI Automation 模式和已发布的窗口消息）。在 macOS 上，Agent 绝不会接管你的鼠标或键盘；各平台的具体保证请参见与你并行工作。
• 指针覆盖层，而非你的指针。 柔和的淡紫色 Agent 指针会显示 Agent 正在操作的位置，不会触碰你的光标。
• 精准定位的坐标。 每张截图和每次缩放都会包含屏幕原点和每点像素数。zoom 会以完整物理分辨率截取任意区域。
• 你的浏览器，你的登录状态。 Chrome 扩展程序会在你已登录的 Chrome 中为 Agent 创建一个专属的带标签页分组；除非你指定某个标签页，否则不会动你的标签页。
• 或者使用已打开的标签页。 browser_list_tabs all=true 会显示浏览器中的所有标签页，browser_use_tab 则会直接接管其中一个标签页；当页面已登录或正在进行流程，重新打开 URL 会丢失当前状态时，这很有用。被接管的标签页不会移入 Agent 的分组、不会激活，也不会重新加载；清理时会释放它，而不是关闭它；你也可以提前调用 browser_release_tab 将其交还。
• 由 Agent 点击打开的标签页也归 Agent 管理。 通过 Agent 的点击或按键打开的 target=_blank 链接或弹出窗口，只要在 10 秒内打开，就会加入该任务的标签页和分组，并在清理时关闭。若从 Agent 标签页打开，但此前没有 Agent 操作，则该标签页仍归你所有。
• 并行任务，共用一个扩展程序。 每个 MCP 进程都有自己的标签页分组；一个进程可以在浏览器调用中传入稳定的 session_id，以运行多个任务。任务无法操作或接管其他任务的标签页，清理时（包括进程退出时）也只会关闭自己的标签页。任意数量的 MCP 进程都可以共用同一个扩展程序：第一个进程负责管理，其余进程通过它操作；如果管理进程退出，其他进程会接手，而不会关闭任何人的标签页。任务共用 Chrome 的 Cookie 和登录状态；桌面应用和剪贴板则不隔离。
• 与模型无关。 交互不需要视觉模型；本地模型也可使用。
• 先查看 → 再操作 → 后验证。 使用 hover 展开鼠标悬停菜单，使用 wait 等待加载，使用 query 按标签查找控件，而无需读取整棵树。
• 一次调用，边操作边查看。 对任意操作（click、type_text、set_value、browser_click、browser_navigate 等）传入 return_state: true，结果就会包含应用最新的无障碍树或页面当前快照。浏览器操作会单独报告就绪状态：标签页已加载，并不代表延迟加载的 SPA 界面已渲染。对于预期显示的元素，请使用 wait_for_selector（见下文）。state_query 会像 query 一样缩小桌面树的范围。
• 多步操作，一次调用。 run_steps 接受一个步骤列表，例如点击字段、输入文本、按下回车，并按顺序执行；每个步骤都会进行与直接调用相同的检查。执行前会检查整个列表，遇到第一个失败的步骤时会停止后续操作，结果会说明哪些步骤已执行、哪些未执行。传入 return_state，即可查看最后一步操作完成后的应用状态。
• 以文本形式读取页面。 browser_read 会返回页面可读文本及其标题，也包括滚动到视图之外的内容，并且支持读取后台标签页。内容会分块返回，可通过 offset 继续读取；query 会按标题保留匹配的行；include_links 会列出链接。
• 密码不会进入对话。 browser_request_credentials 会在一个小型 Chrome 窗口中请求用户登录，并显示网站的真实来源。用户输入的内容会直接进入页面字段，绝不会返回给模型。browser_snapshot 从不显示密码字段的值；在桌面端，默认拒绝向密码字段输入内容。
• 接续你正在查看的内容。 get_app_state 和 screenshot 支持传入 app: "frontmost"，以获取用户当前置前应用的状态或截图，让客户端只需一步就能把“这个窗口”交给 Agent。

与您并肩工作

Agent 有自己的指针；您的指针仍归您使用。

macOS — 有保障。 每项操作都通过辅助功能（按下、设置值、选择文本、显示菜单、滚动条）或发送给目标应用进程和窗口的事件完成。服务绝不会移动您的指针、向系统级输入流发送事件，也不会占用或阻止您的输入，因此 Agent 工作时，您仍可在其他应用中点击和输入——甚至可以在同一应用的另一个窗口中操作。事件来自私有来源，因此您按住的修饰键不会影响 Agent 的点击。目标应用可能会在某一步需要时被调到前台（例如调用 activate_app，或将密码字段交给您），但不会在每项操作时都这样做。

发送给后台应用的命令快捷键会通过其菜单栏执行（macOS 只会将菜单键盘快捷键交给前台应用），因此无需将应用调到前台，cmd+W、cmd+S 等快捷键也能正常工作。最小化的窗口或隐藏的应用，在需要像素或输入时（输入文字、坐标点击、截图、OCR）会临时移至不可见显示器，并在无人看到的情况下工作；20 秒无操作后、其他应用窗口需要该显示器时，或服务退出时，它会再次最小化或隐藏。如果您在此期间自行调出应用，其窗口会回到原来的屏幕位置。对此类窗口执行辅助功能操作（按下、设置值）则无需这些处理。COMPUTER_USE_PARK_WINDOWS=0 可关闭此功能；此时，这些操作会返回错误，提示您恢复窗口。

以下例外操作会直接拒绝，而不会占用您的指针：没有目标应用的点击、悬停或滚动（在任何 get_app_state 之前对桌面坐标进行操作），以及离开源窗口的拖动（在应用之间拖动，或拖到桌面上）。错误信息会说明应改为传入什么。

Windows — 尽力而为，并报告结果。 通过 UI Automation 的 ScrollPattern 执行元素按下（Invoke）、set_value、select_text 和滚动操作时，不会触碰您的指针；传统 Win32 控件也会通过发送窗口消息响应点击、悬停、滚轮和拖动。其他 UI（Chromium、Electron、WPF、UWP）只响应真实鼠标输入，因此这些点击、悬停和拖动会移动您的指针，而 type_text/press_key 会发送到焦点窗口。凡是使用了真实指针，结果都会注明 via cursor。如果某元素被另一个应用的窗口遮挡，针对该元素的坐标操作会被拒绝，而不会误点那个窗口；对最小化窗口执行指针和键盘操作时，会返回错误，提示您恢复窗口（辅助功能操作仍可用于该窗口）。

Linux — 指针操作会使用指针。 XTEST 输入会移动真实指针，并发送给焦点窗口；结果会注明 via cursor。通过 AT-SPI 执行的元素操作（按下、设置值、插入文本、选择）不会移动指针。

Agent 可以使用的应用和网站

由你决定 Agent 可以访问哪些应用和网站。在服务的支持目录（macOS 上为 ~/Library/Application Support/computer-use，Windows 上为 %LOCALAPPDATA%\munim-computer-use，Linux 上为 ~/.local/share/munim-computer-use；运行 munim-computer-use identity 会将其打印为 supportDir）中放置 policy.json，或将 COMPUTER_USE_POLICY 指向任意位置的文件。在自己的配置文件下嵌入服务的应用，会从自己的支持目录读取该文件：

{
  "apps": { "Keychain Access": "block", "com.apple.MobileSMS": "ask" },
  "sites": { "bank.example": "block", "mail.google.com": "ask", "*": "allow" }
}

• allow、ask 或 block，可按应用或网站设置。Agent 首次尝试访问时，ask 会向用户显示提示（应用会显示系统对话框，网站会显示一个小型 Chrome 窗口），且批准仅在该 Agent 任务结束前有效。两分钟后仍未响应的提示视为拒绝。
• 应用按名称或 bundle id 匹配，且不区分大小写。Agent 读取、捕获或激活应用时会应用此规则。之后的操作会针对已获准快照中的元素执行。
• 网站按主机名及其所有子域名匹配，并以最具体的模式为准。每次浏览器操作都会根据标签页当时显示的页面进行检查，因此，点击链接进入被阻止的网站也无法绕过限制。
• * 设置默认规则；默认值原本为 allow，因此 {"apps": {"*": "block", "Notes": "allow"}} 是一个允许列表。
• 更改会立即生效，无需重启。无效文件会阻止所有操作，而非被忽略，因此拼写错误不会悄然将阻止规则变成允许规则。

这是为会遵循指令的 Agent 设置的防护措施，并非沙盒。坐标点击会落在其指向的位置，整屏截图会显示所有窗口。

工具（33）

区域	工具
查看	list_apps、get_app_state（带 query）、screenshot、zoom、list_displays
操作	click、right_click、hover、drag、scroll、type_text、set_value、select_text、press_key、activate_app、wait、run_steps
剪贴板	clipboard_read、clipboard_write（纯文本）
浏览器	browser_open_tab、browser_list_tabs、browser_use_tab、browser_release_tab、browser_select_tab、browser_navigate、browser_snapshot、browser_read、browser_click、browser_type、browser_request_credentials、browser_press_key、browser_close_tab、browser_close_all_tabs

每个操作工具还接受 return_state，可在同一次调用中返回操作后的当前状态。run_steps 会在一次调用中运行一系列操作，并在首个失败步骤处停止。

浏览器就绪状态与安全的重新观察

browser_click、browser_type、browser_press_key 和 browser_navigate 接受 wait_for_selector，并可与 return_state: true 搭配使用。browser_snapshot 也接受相同的等待参数，但不会执行任何操作：

{"tab_id": 42, "index": 0, "return_state": true,
 "wait_for_selector": "[role=dialog] button", "wait_timeout_ms": 3000}

该扩展会轮询顶层文档中任何匹配的可见元素，不受资源加载影响，包括同一文档内的渲染。它与快照使用相同的可见性规则：至少为 2×2 CSS 像素；没有隐藏、aria-hidden、inert 或完全透明的祖先元素。自身透明的原生表单控件仍可用于样式化的上传/复选框点击目标；透明容器则不行。这并不保证元素可点击或未被遮挡。不会搜索框架和影子根。请选择一个专门针对预期的新 UI的选择器；已存在的元素可能立即满足条件。不接受任意页面脚本，且选择器不得检测 value 属性：React 会将受控输入框的值映射到该属性中，密码字段也不例外，否则等待操作可能会逐个确认猜测的密码字符。

• wait_timeout_ms：默认值为 8000，接受 0–10000 的整数；0 表示检查一次。必须设置 wait_for_selector。此预算涵盖轮询，不涵盖浏览器/API 延迟或用户的网站审批提示。每次观察前以及最终快照前，都会重新检查网站规则。
• readiness: met (visible_selector, … ms)：已观察到指定条件，但这不保证所有网络请求、动画或应用工作都已结束。
• readiness: timeout：在预算时间内未观察到该条件。操作是否成功仍单独判断，并且仍会返回当前快照。
• readiness: error：无法评估该条件（例如 CSS 无效）；操作仍可能已成功。请修正等待条件并重新观察。
• 未指定选择器时，return_state 仍会进行短暂暂停和有时限的导航加载等待，但会报告 not_requested (document_load, … ms)，而不是声称 SPA 已就绪。导航加载预算耗尽时会报告 timeout。不带等待条件的普通 browser_snapshot 仍会立即观察。

如果返回的快照看起来没有变化，不要仅仅因为缺少预期 UI 就重复执行不可幂等的点击。请先等待并重新观察：

{"tab_id": 42, "wait_for_selector": "[role=dialog] button", "wait_timeout_ms": 3000}

将此内容发送给 browser_snapshot，检查其就绪状态和最新索引，然后选择下一步操作。超时或工具错误不会回滚点击、提交、输入或导航。请根据当前状态判断重试是否安全。无效的等待类型/范围，或未设置 return_state: true 的操作等待，都会在执行操作前被拒绝。可选参数设为 null 与省略该参数效果相同。这些选项需要更新后的扩展和原生服务；旧版扩展忽略这些选项时，结果会说明这一点并提示重新加载。

回归检查：node --test chrome-extension/background.test.mjs 涵盖等待约定和网站策略保护。真实浏览器 CI 测试脚本 scripts/e2e-browser.mjs 会测试一个延迟 1100 ms 且没有导航的对话框、仅点击一次，以及超时和只读恢复。无依赖 CDP 回归测试涵盖快照范围/分页和 SPA 就绪状态。请使用隔离的 Chrome/Chromium 配置文件运行；无需 Playwright 模块：

node scripts/snapshot-dom.test.mjs --chrome /path/to/chrome
# Extract the pre-fix source; each suite must fail independently:
git show deb4c7a:chrome-extension/background.js > original-background.js
node scripts/snapshot-dom.test.mjs --chrome /path/to/chrome --source original-background.js --suite snapshot
node scripts/snapshot-dom.test.mjs --chrome /path/to/chrome --source original-background.js --suite readiness

browser_snapshot 会在有对话框打开时自动限定到最上层可见对话框，因此被遮挡的背景控件不会占用对话框的预算。对话框通过传送门弹出的内容仍在范围内：控件通过 aria-controls/aria-owns 指向的元素、打开的弹出层，以及绘制在对话框上方的控件，例如渲染在 <body> 末尾的选择框选项。隐藏和 inert 子树会被排除；可访问的屏幕外控件仍可用。原生非模态对话框和显式设置为 aria-modal="false" 的对话框不会限定页面范围。原生模态对话框和显式设置为 aria-modal="true" 的对话框是确定的候选对象。只有当隐式 ARIA 对话框覆盖视口中心且在该处位于最上层时，才会通过启发式方式限定范围，而不只是位于对话框自身的中心。没有命中测试堆栈时，则以中心覆盖作为回退依据。因此，角落的聊天小组件和底部的 Cookie 横幅不会影响页面已索引的控件。 它最多返回 limit 个控件（默认值和最大值均为 250），并报告 scope、offset、limit 和 total；如果结果被截断，也会明确说明，并指出下一步要请求的 offset。继续操作时，请使用相同的 tab_id 和 session_id。索引在所选范围内是全局的；UI 未变化时，翻页后索引仍可操作；UI 发生变化或页面导航后，请从 offset=0 获取新的快照。操作的 return_state 同样从 offset=0 开始，并使用相同的范围限定和截断报告方式。

各平台上的名称、参数形状和描述完全一致，CI 会对此进行检查（node scripts/check-tool-parity.mjs）；在 Mac 上学过这些内容的模型无需在 Windows 上重新学习。要更改工具，请使用 scripts/tool-defs.mjs 同时编辑两处定义，不要手动修改。

仓库布局

目录	内容	构建
macos/	基于 Accessibility API 和 ScreenCaptureKit 的 Swift 服务（macOS 14+）	swift build -c release → .build/release/munim-computer-use
windows-linux/	Rust 服务：Windows 上使用 UI Automation，Linux 上使用 AT-SPI + X11	cargo build --release → target/release/munim-computer-use
chrome-extension/	Chrome 扩展 + 用于 browser_* 工具的原生消息主机	加载未打包的扩展；sh install.sh / install.ps1 用于注册主机；node background.test.mjs
Dockerfile	用于注册表检查（Glama 等）的 Rust 服务无头 Linux 构建；容器内不提供桌面控制	docker build -t munim-computer-use .

从源代码构建

在 Fedora 上构建 Rust 服务之前，请先安装原生开发库（以及 Rust 工具链）：

sudo dnf install gcc pkgconf-pkg-config clang-devel pipewire-devel \
  libdrm-devel mesa-libgbm-devel mesa-libEGL-devel wayland-devel libxcb-devel

即使使用 X11，屏幕捕获依赖项也需要这些库。尤其是，构建过程中如果缺少 libpipewire-0.3.pc，就表示缺少 pipewire-devel。

# macOS
cd macos && swift build -c release
# Windows / Linux
cd windows-linux && cargo build --release

Linux 注意事项：元素操作在所有环境中都可用；坐标点击需要使用 X11 或 XWayland 客户端，因为原生 Wayland 应用不会公开绝对几何位置。

测试

cd windows-linux && cargo test                  # Rust server
node chrome-extension/background.test.mjs       # extension, against a fake Chrome
node scripts/check-tool-parity.mjs              # Swift and Rust tool lists match
# Snapshot and SPA readiness regressions (dependency-free CDP, isolated profile):
node scripts/snapshot-dom.test.mjs --chrome <Chrome for Testing binary>
# The browser tools end to end, in a throwaway Chrome for Testing profile that
# never touches your own Chrome (npx playwright install chromium to get one):
node scripts/e2e-browser.mjs --server <munim-computer-use binary> --chrome <Chrome for Testing binary>

Chrome 扩展（可选）

1. chrome://extensions → 开发者模式 → 加载已解压的扩展程序 → 选择 chrome-extension/。
2. 注册本机消息传递主机：munim-computer-use install-native-host（例如 npx -y munim-computer-use install-native-host），或在检出目录中运行 sh chrome-extension/install.sh（macOS/Linux）/ powershell -File chrome-extension/install.ps1（Windows），这些命令会查找构建文件并运行相同命令。如果二进制文件不在默认构建位置，请将 COMPUTER_USE_PATH 指向该文件。

如果扩展仍提示 Specified native messaging host not found.，或者浏览器工具提示扩展未连接，请在普通终端中运行 munim-computer-use check-native-host。它会像 Chrome 一样查找主机（在 Windows 上检查注册表视图和策略；在所有平台上检查清单的编码、名称、类型和允许的来源），使用 Chrome 的命令行启动主机，并指出可能失败的步骤。有两种 Windows 原因从内部看起来一切正常。由 MSIX 打包应用（某些 Agent 桌面应用采用此打包方式）运行的安装程序会写入私有的虚拟化 HKCU 和 %LOCALAPPDATA% 副本，而 Chrome 不会读取这些副本。由使用独立 Windows 账户的沙盒运行的安装程序，则会写入该账户的 HKCU。检查命令会检测这两种情况；请从你自己的终端再次运行 install-native-host。install-native-host 也会在 problems 下报告相同的问题。

独立服务的主机是 com.munimtech.computer_use.desktop；捆绑此服务的 MT Code 注册的是 com.munim.mtcode.desktop。扩展会同时连接所有已知主机，并通过各自的连接分别响应，因此 MT Code 和独立服务（npx、Claude Code、Cursor、检出目录）可以同时控制 Chrome，各自在自己的标签页组中操作。

沙盒 Agent（Windows）

某些 Agent 会在沙盒中运行命令：使用受限或低完整性令牌、独立 Windows 账户，或另一个桌面。即使在这种环境中启动服务仍能列出窗口及其标题，但其他应用的 UI 自动化会拒绝访问，截取的图像也会变成黑色，且不显示任何错误。出现这种情况时，服务会明确说明：get_app_state 会解释为何树为空，screenshot 和 zoom 会标记画面为单一纯色，activate_app 会检查窗口是否确实切到前台。每项都会指出检测到的原因（例如“以低完整性运行”或“以另一个账户运行”）。在相同环境中重试无济于事；请将 Agent 配置为在你自己的非沙盒环境中启动 MCP 服务。

环境标志

变量	效果
COMPUTER_USE_BROWSER=0	隐藏 browser_* 工具
COMPUTER_USE_AGENT_CURSOR=0	不绘制 Agent 指针
COMPUTER_USE_AGENT_CURSOR_TASK_FADE_SECS	指针在最后一次工具调用后保留的时长（默认值为 8）
COMPUTER_USE_ALLOW_SECURE_FIELD_INPUT=1	允许在密码字段中输入（默认拒绝）
COMPUTER_USE_REMOTE_CONTROL=1	远程桌面模式：输入会接管真实指针
COMPUTER_USE_PARK_WINDOWS=0	macOS：不将最小化或隐藏的窗口移至不可见显示器以便对其进行操作
COMPUTER_USE_POLICY=<file>	应用和网站策略的读取位置（默认为支持目录中的 policy.json）

远程控制

通常，此服务绝不会操作指针：坐标点击会发送到指定窗口，按键会发送到指定进程，而无法指定目标的操作会被拒绝，不会接管整台机器。这样一来，Agent 工作时，用户仍可继续使用自己的电脑。

对单个进程设置 COMPUTER_USE_REMOTE_CONTROL=1 会反转这一约定，适用于有人在另一台设备上观看此机器的屏幕并亲自操控的情况。此时，click、right_click、drag、hover 和 scroll 会移动真实光标，type_text 和 press_key 会发送到当前获得焦点的对象，其行为与 Chrome Remote Desktop 或 Screen Sharing 相同。scroll 还接受 x/y，使滚轮在观看者滚动时所指的位置上生效；Agent 光标叠加层也会保持隐藏——现在只有一个指针。

同时运行 Agent 和观看者的主机上，它们是两个独立进程，因此为观看者启用此功能，不会让它代替 Agent 抢走用户的指针。

在应用中嵌入

应用可以将此二进制文件打包到自己的程序包中，并以自身身份运行，因此它不会与同一台机器上的独立安装共用浏览器桥接程序、Agent 光标应用或原生消息传递主机。MT Code 就是这样做的。使用 --profile <json|file>（任意位置）或 COMPUTER_USE_PROFILE 传入配置文件，可以是 JSON 对象，也可以是 JSON 文件的路径：

{
  "name": "example-desktop",
  "envPrefix": "EXAMPLE_DESKTOP_",
  "agentCursorName": "ExampleAgentCursor",
  "agentCursorBundleId": "com.example.agent-cursor",
  "nativeHostNames": ["com.example.desktop"],
  "extensionIds": ["abcdefghijklmnopabcdefghijklmnop"],
  "nativeHostDescription": "Example desktop control bridge"
}

键	默认值	含义
name	无（独立安装路径）	将支持目录、桥接套接字和 Windows 管道移至此名称下
supportDir	~/Library/Application Support/computer-use、$XDG_DATA_HOME/munim-computer-use、%LOCALAPPDATA%\munim-computer-use	原生主机封装程序、配置文件副本；在 macOS 上还包括桥接套接字和独立构建的叠加层应用
bridgeSocket	<supportDir>/bridge.sock（macOS）、$XDG_RUNTIME_DIR/<name>/bridge.sock（Linux）、<name>-bridge-<user> 管道（Windows）	MCP 服务与 Chrome 中继的连接位置
envPrefix	无	在 COMPUTER_USE_* 之前读取 <prefix>BROWSER、<prefix>AGENT_CURSOR、… 等可调参数
agentCursorName / agentCursorBundleId	MunimAgentCursor / com.munimtech.computer-use.agent-cursor	指针叠加层应用的名称、可执行文件和窗口类名称，以及其 macOS 程序包 ID
historyDir	无	computer-history 的默认 --root
nativeHostNames / extensionIds	com.munimtech.computer_use.desktop、com.munim.mtcode.desktop / kgdolgnijopbghhomnblabjkmjhnoage	install-native-host 注册的名称及其对应的扩展程序。第一个名称属于此身份；后续名称是别名，仅当没有其他已安装应用占用时才会写入

supportDir、bridgeSocket、envPrefix、agentCursorName、agentCursorBundleId 和 historyDir 均可通过 COMPUTER_USE_<SNAKE_CASE> 单独覆盖（例如 COMPUTER_USE_SUPPORT_DIR），且其优先级高于配置文件。munim-computer-use identity 会打印解析后的值。

• 浏览器桥接。 使用相同的配置运行 munim-computer-use install-native-host。它会写入一个包装程序，将 Chrome 中继到此身份的桥接（并重放该配置），还会为每个 Chrome/Chromium 配置目录中的每个名称写入一份主机清单（Windows 上则写入注册表）。如果已有文件是最新的，它不会重写，因此应用可以在每次启动时调用它。
• 扩展程序。 使用原版扩展程序（它连接到 com.munim.mtcode.desktop 和 com.munimtech.computer_use.desktop），或构建具有自定义主机名称、标签组标题和密钥的变体：node scripts/build-extension.mjs --out <dir> --host com.example.desktop --group-title "Example" --key <base64>。该命令会输出此变体的扩展程序 ID，供 extensionIds 使用。
• macOS 权限。 MCP 服务是一个独立可执行文件，因此辅助功能和屏幕录制权限会授予启动它的应用。只有 Agent 光标叠加层拥有独立的应用包；请将 <agentCursorName>.app（二进制文件的副本以及包含 LSUIElement 的 Info.plist）随二进制文件一起分发，否则首次使用时会在 supportDir 下生成该应用包。

提示你的 Agent

查看 → 操作 → 验证。使用 get_app_state 获取 ID，通过 ID 执行操作并设置 return_state: true，即可在同一次调用中查看结果；如果界面树无法显示内容，则使用 screenshot。使用 browser_read 阅读网页，让用户通过 browser_request_credentials 输入密码。小字使用 zoom，鼠标悬停时出现的菜单使用 hover，加载完成后使用 wait，难以操作的控件则使用键盘快捷键。MT Code 提供给其 Agent 的系统提示词位于 CodexDeveloperInstructions.ts，可作为很好的起点。

贡献

本服务在此开发。MT Code 通过固定使用此仓库的某个发行版本来集成它（native/munim-computer-use.json），因此更改会在下一个发行版本中进入 MT Code。欢迎提交问题和拉取请求。

致谢与许可证

由 Munim Technologies（Munim, Inc.）为 MT Code 设计并构建。屏幕内容裁剪、对话框范围限定、基于通知的稳定判定、OCR 回退、菜单快捷键和窗口停靠均遵循 arc-cua（MIT）。版权所有 2026 Munim, Inc. 根据 Apache License 2.0 授权；详情请参阅 LICENSE。

对比参考资料：Codex Computer Use、其文档、其 Windows 说明 和 MacStories 关于其读取应用方式的文章 · Cua Driver 和 其工具参考 · OpenAI Agents API computer use · Anthropic computer-use demo · CursorTouch/Windows-MCP · CursorTouch/MacOS-MCP · QwenLM/open-computer-use · zavora-ai/computer-use-mcp · mediar-ai/mcp-server-macos-use · deploymenttheory/windows-mcp-server · nuphus-mcp · computer-control-mcp · microsoft/playwright-mcp