omni-computer-use

omni-computer-use

我受够了 Claude Code 和 Codex 在电脑操作方面的权限限制，所以自己做了一个。尤其是对我们 Windows 用户来说：这里的 Claude Code CLI 根本没有电脑操作功能。我对此真的很不满。为什么在氛围编程中，Windows 用户总是二等公民？

自 2026 年 6 月以来，我一直在使用 omni。每当我发现有什么地方让人恼火，就会更新它。

我同时使用 Claude Code 和 Codex，而 omni 在 Claude Desktop Code、Claude Code CLI 和 Codex 上运行得都很完美。下面的 GIF 展示了这一点：Claude 和 GPT 都会打开 VS Code 并在其中输入内容。我也在 Warp 中测试过，同样能用。我还推荐给一位使用 Cursor 的朋友，他测试后发现也能正常使用。

它之所以能在任何地方运行，是因为它不与这些工具中的任何一个集成。它只是一个普通的 MCP 服务。启动时，它会沿着自身的进程祖先向上查找，第一个拥有窗口的祖先就是它要服务的窗口。因此，无论你从终端、Claude Desktop 还是 Codex 启动它，它都会自行判断，无需进行任何配置。

如果你正在构建自己的桌面应用，不妨试试 omni。Agent 可以查看你的 UI 并自行调试，非常方便。这和构建 Web 应用时使用 Playwright 是同一个思路。

一行命令即可安装：

claude mcp add omni-computer-use -s user -- uvx omni-computer-use-mcp

下面是两段 GIF：

Claude Code CLI，一镜到底。

Codex，一镜到底。这段视频由 Codex 自己录制并剪辑。

以下内容都是写给 AI 的。想跳过的话请自便。祝你好运 👍

安装

需要 Windows 和 Python 3.11+（uv / uvx 会为你获取 Python）。PyPI 包名带有 -mcp 后缀；其他所有名称——命令、服务键和此仓库——都直接使用 omni-computer-use。

推荐 — 安装到 Claude Code。 Claude Desktop 除了读取自己的 MCP 服务外，也会读取 Claude Code 的 MCP 服务，因此只需运行这一条命令，即可在 Claude Code CLI 和 Claude Desktop 应用中使用此服务：

claude mcp add omni-computer-use -s user -- uvx omni-computer-use-mcp
claude mcp list   # expect: omni-computer-use … ✓ Connected

其他安装方式适用范围较窄。在 Claude Desktop 的 claude_desktop_config.json 中配置——仅对 Claude Desktop 可见，CLI 无法读取：

{
  "mcpServers": {
    "omni-computer-use": { "command": "uvx", "args": ["omni-computer-use-mcp"] }
  }
}

每个 GitHub 版本发布页都附有桌面扩展包（.mcpb，一键安装）——适用范围同样有限：仅限 Claude Desktop。

独立运行（适用于任何 MCP 客户端，也可以单纯用来试用）：

uvx omni-computer-use-mcp

Windows 启动提示：uv/uvx 是原生可执行文件，无需包装器。如果你的 MCP 客户端通过 .cmd 垫片启动服务（例如 npx），则只有它需要添加 cmd /c 前缀——此服务不需要。

示例

在多显示器设备上，每张截图都会自我说明——它会标明截图对应的显示器以及连接的其他设备，因此 Agent 始终清楚自己正在查看哪个屏幕：

This screenshot was taken on monitor "\\.\DISPLAY2" (2560x1600, primary).
Other attached monitors: "\\.\DISPLAY1" (2560x1440). Use switch_display to
capture a different monitor.

open_application 会报告实际发生的情况，而不是发出请求后就不再理会：

Opened "Calculator".                                  # a real window appeared
launched "…" but its process exited within ~2s        # crashed on startup — reported, not faked
  without showing a window …

状态

• 29 个工具——27 个与 Claude Desktop 的电脑操作工具相对应，另有 deactivate 和 display_overview；当 COMPUTER_USE_DEV=on 时，开发用的 reload 工具会使总数达到 30 个。
• tests/ 下有一个包含 16 个场景的端到端测试套件（scen_*.json），每个场景都通过一个全新的 MCP 进程运行。
• 在 Windows 11（2560×1600 @ 150% DPI）上构建并验证，以 Claude Desktop 的电脑操作功能为基准；截图缩小后的分辨率经四舍五入后与 CDC 的约 1.2 MP 相符。

工具

与 Anthropic 的 computer-use 匹配（27 个）： request_access、list_granted_applications、request_teach_access、screenshot、zoom、switch_display、cursor_position、mouse_move、left_click、right_click、middle_click、double_click、triple_click、left_click_drag、left_mouse_down、left_mouse_up、scroll、key、hold_key、type、wait、open_application、read_clipboard、write_clipboard、computer_batch、teach_step、teach_batch。

omni 专用（2 个）：

• deactivate — 结束会话但不终止进程（关闭光效、恢复控制窗口、撤销授权）；与 request_access 相对应。
• display_overview — 将所有显示器按虚拟桌面布局组合成一张带标签的图片（用于辅助判断“那个窗口在哪个屏幕上？”；不能用于点击）。

所有点击／移动／滚动／拖动／缩放坐标都采用最近一次截图的图像像素空间；服务会将它们映射回物理像素。

工作原理（值得了解的部分）

忠实还原桌面视觉。 会话处于活动状态时，服务会复现 Claude Desktop 屏幕上的交互元素，并根据参考截图进行像素级校准：静态橙色边缘光效、会飞到角落的居中“Agent is using your computer”提示条，以及缩小后紧贴右上角的控制窗口（运行 CLI 的 Windows Terminal，或 Claude Desktop 窗口本身）。每次截图时，控制窗口都会移出屏幕，确保截图呈现真实桌面，不带黑框。点击穿透会根据窗口类型处理：非分层终端会在每次模拟点击时移至 z 顺序底部；分层的 Claude Desktop 窗口会设置 WS_EX_TRANSPARENT（桌面工具自身采用的做法），使点击穿透到下方的窗口。窗口本身不会移动，因此不会影响用户的真实鼠标。

键盘自我误操作防护。 模拟按键会发送到当前持有操作系统焦点的窗口。如果控制窗口（Claude 窗口或承载它的终端）位于最前方，type／key 操作会被拦截，否则文本可能会输入 Agent 自己的对话框，或作为带有结尾 Return 的 Shell 命令运行。该防护始终启用，并通过窗口标识和所属进程识别控制界面，同时允许将另一个无关的终端窗口作为合法目标。鼠标操作不受此限制（点击会携带自身坐标）。

多显示器。 截图会附带一条由事件驱动的说明，标明所截取的显示器，并在显示器发生变化时发出提示；如果窗口打开的显示器与当前截图目标显示器不同，open_application 会发出警告——在获取到窗口句柄时会精确标明显示器名称；display_overview 会返回所有屏幕的布局图。光效和缩小后的窗口会显示在控制窗口所在的显示器上，不会影响其他显示器。

如实报告启动结果并自我修复。 open_application 会轮询检查实际窗口，并区分 opened／running-no-window-yet／crashed-on-startup／nothing-launched，而不是始终报告成功。被强制终止的会话，其缩小后的终端会在下次启动时通过一个小型状态文件恢复（并防止窗口句柄被重复使用）。

热重载（开发）。 设置 COMPUTER_USE_DEV=on 可添加 reload 工具，在进程内对逻辑模块执行 importlib.reload，让编辑后的代码立即生效，无需重启会话——适用于针对该服务开发自动化。此功能默认关闭（保持精简的 29 个工具界面）。

权威的逐工具约定和模块架构，请参阅 SPEC.md。

与桌面工具的差异（有意设计）

内置的 computer use 仅允许列表中的已安装应用，并采用分层模型：浏览器可见但只读，终端和 IDE 只能点击——由于架构限制，无法输入按键。这些设置是通用桌面使用的合理默认值，但会限制本服务旨在支持的工作流：让 Agent 启动你当前正在开发的应用——一个安装列表中找不到的独立 .exe 文件——在其中点击、输入、验证行为，然后返回 IDE 编辑代码。

omni 会以 tier:"full" 授予所有获准应用完整权限——包括 IDE、终端和开发版本（open_application 接受完整的 .exe 路径）。功能强大，责任自负。

CLI 没有权限 GUI，因此 request_access 会自动授予可解析的应用 tier:"full" 权限，并返回相同的 JSON 结构；默认情况下，前台应用限制较宽松（仅在允许列表为空时出错）。默认关闭对非允许列表窗口的遮罩（基于矩形的遮罩范围过大）。教学模式目前是占位实现——它会执行步骤中的操作并返回屏幕截图，但不会显示全屏工具提示覆盖层（这是桌面应用的功能）。这些设置均可通过以下环境变量控制。

配置

变量	默认值	含义
COMPUTER_USE_MAX_PIXELS	1200000	缩小后的屏幕截图最大像素数（≈ 1.2 MP）。
COMPUTER_USE_MASKING	off	在屏幕截图中遮罩非允许列表应用窗口。
COMPUTER_USE_ENFORCE_FOREGROUND	off	当前台应用不在允许列表中时阻止输入。
COMPUTER_USE_AUTOGRANT	on	在 request_access 时自动授予可解析的应用权限。
COMPUTER_USE_DEV	off	注册开发者热重载工具 reload（开启后 → 30 个工具）。
COMPUTER_USE_LOG_DIR	%LOCALAPPDATA%\omni-computer-use\logs	轮换日志 mcp.log 的目录（记录工具调用和回溯信息）。
COMPUTER_USE_GLOW	on	会话处于活动状态时显示静态橙色边缘光效。
COMPUTER_USE_SHRINK_TERMINAL	on	将控制窗口缩小并移至右上角。
COMPUTER_USE_HIDE_CONTROLLING	on	截图期间将控制窗口移至屏幕外。
COMPUTER_USE_PILL	on	居中显示“Agent is using your computer”提示条。
COMPUTER_USE_GLOW_COLOR	217,119,87	光效／提示条颜色（#D97757）。
COMPUTER_USE_GLOW_ALPHA	0.4	最边缘处光效的最大不透明度。
COMPUTER_USE_GLOW_BAND	0.05	光效带宽占屏幕较短边尺寸的比例。
COMPUTER_USE_GLOW_EXCLUDE	on	截图时排除光效／提示条。

易踩坑点（Windows 实际行为）

• IME 会影响 key / hold_key，但不会影响 type。 type 直接注入 Unicode，绕过输入法（任意输入布局都支持中日韩文字和表情符号）。key / hold_key 发送的虚拟键码会经过当前启用的 IME — 因此，启用中文 IME 时，发送字母 a 会打开拼音候选列表，而不是输入 a。输入文本请使用 type；使用字母快捷键前，请将 IME 切换到英文。
• 无法操作提权应用（任务管理器、UAC 提示、管理员安装程序）— Windows UIPI 会阻止来自非提权进程的输入。与桌面工具存在相同限制。
• 时序关键型 UI 需要使用 computer_batch。 同一批次中的操作间隔只有几毫秒；不同工具调用之间则相隔一次模型往返（数秒）。任何只在操作过程中短暂出现的内容 — Stop/Cancel 按钮、失焦后会关闭的菜单 — 都无法通过逐次调用触达。请将整个操作序列放入一个批次，并通过调整 wait 来控制时机。
• 键盘操作前必须先聚焦目标。 当控制窗口处于焦点状态时，自我伤害防护会阻止 type / key 操作。请以点击目标窗口作为批次中的第一步：点击会切换焦点，同一批次中后续的键盘操作便会发送到预期位置。
• 点击到位，不代表点击生效。 合成点击会由操作系统发送，但应用仍可能忽略点击 — 尤其是当 Electron 窗口的标题栏由渲染器绘制且渲染器处于错误状态时：原生工具提示仍会出现，窗口也仍会激活，但关闭按钮不起作用，而原生 WM_CLOSE 却能正常关闭窗口。请通过屏幕截图验证，不要只相信返回的 Clicked.；如果悬停有效但操作无效，应怀疑应用本身，而不是坐标。

测试

tests/ 包含一个 16 场景端到端测试套件（scen_*.json），以及一个用于启动全新服务并运行场景 JSON 工具调用列表、穿插返回图像的驱动程序：

uv run python tests/drive.py tests/scen_calc.json     # compute 7×8 by clicks, screenshot, verify

tests/dev/ 包含开发期间编写的一次性 Win32 探测程序（辉光／胶囊采样、z 顺序和捕获亲和性实验）。

技术栈

Python ≥ 3.11，使用 uv 打包，采用 src 布局和 hatchling。通过标准输入／输出运行的 mcp Python SDK（FastMCP）；用于屏幕捕获的 mss；用于图像处理的 pillow；以及用于 DPI 感知、窗口／剪贴板／前台访问和原始 Win32 SendInput 鼠标／键盘注入的 pywin32 + ctypes。

隐私政策

omni-computer-use 完全在你的计算机上运行，不涉及服务器端。

• 不收集数据。 源代码未导入任何网络库，也不包含遥测、分析或崩溃报告功能。任何内容都不会上传到任何地方。
• 使用和存储。 屏幕截图、剪贴板内容和输入事件都在你的计算机内存中处理，并仅通过本地标准输入／输出返回给你连接此服务的 MCP 客户端。唯一写入磁盘的内容是 %LOCALAPPDATA%\omni-computer-use\logs 下的本地轮替日志（mcp.log，记录工具调用和回溯信息）— 可通过 COMPUTER_USE_LOG_DIR 配置，也可随时删除。
• 不与第三方共享。 无账户、无外部服务、无第三方。
• 数据保留。 唯一的数据保留形式是在你自己的磁盘上轮替日志；由你自行控制。
• 联系方式。 如有隐私相关问题：提交 GitHub issue。

请注意，你连接的任何 MCP 客户端（例如 Claude Desktop、Claude Code CLI）都会接收此服务捕获的屏幕截图和文本，并受其自身隐私政策约束。

许可证

MIT © Jason26214