computer-use-gate

Windows 版 Computer Use

无需显卡 · 任何 AI 都能接 · 你不点头它不动手

真正让你感受一下 Windows 版的 Computer Use。

让你的 AI 真正在 Windows 上动手：看屏幕、点按钮、打字、切窗口、操作网页。 每一下都要你授权，每一下都留证据，按一个键全部停下。

5 分钟上手 · 任何 AI 都能接 · 为什么不要显卡 · 视觉是怎么实现的 · 为什么敢让它动手

Computer Use for Windows. No GPU. Works with any agent via MCP, HTTP or CLI. Default-deny, evidence for every action, one-key emergency stop.

TL;DR (English) — Computer Use for Windows, running on your own desktop: your AI agent can see the screen, click, type, switch windows and drive web pages.

• No GPU needed: controls are read via Windows UI Automation, built-in Windows OCR and browser CDP, not a local vision model.

• Layered vision: UIA first, then pixels (OCR), then icon glyph matching — a VLM (cloud GLM-4V or local Ollama) is only ever a default-off last resort. See 视觉是怎么实现的.

• Works with any agent: Claude Code, Codex, Gemini CLI, Cursor, Cherry Studio or your own scripts, via MCP (stdio / HTTP), HTTP API or CLI.

• Default-deny: nothing moves until you click "Allow" on an on-screen prompt. A pass lasts 30 minutes or 60 actions.

• Evidence for every action: before/after screenshots, a hash-chained tamper-evident log, and exportable replay videos.

• One-key stop: Ctrl+Alt+Home halts everything immediately.

Experimental 0.x: no SLA, APIs may change. Needs Windows 10/11 x64 + Python 3.12 + git. Quick start: 5 分钟上手; scope and limits: 先说清楚适用范围.

Keywords: computer-use agent · MCP server · Windows automation · desktop action gate · agent safety · audit trail · UIA grounding · Windows OCR · visual fallback.

Related MCP server: guarded-computer-use-mcp

一句话说明

别的 Computer Use 方案，要么只能跑在 Linux 虚拟机里，要么要一块好显卡跑视觉模型，要么只认某一家的 AI。

computer-use-gate 直接跑在你自己的 Windows 桌面上，普通笔记本就够用，Claude、Codex、Gemini、Cursor、Cherry Studio，或者你自己写的脚本，都能接。

为什么不要显卡

很多 Computer Use 每走一步都要截一张图，丢给视觉模型去猜"按钮在哪"。又慢、又贵，本地跑还得有显卡。

computer-use-gate 换了个思路：先问 Windows，再看截图。

AI 拿到的是"保存按钮在 (812, 430)"这样的准确答案，不用自己从像素里猜。普通笔记本、核显、轻薄本都能跑。

这五条能力怎么搭成一条完整的视觉流水线，每一层的实测数字、踩过的坑、兜底纪律，往下看。

视觉是怎么实现的

computer-use-gate 没有"一个视觉模型"。它的眼睛是一条分层流水线：

              ┌─ ① UI Automation ── 控件名/类型/矩形/状态（结构化，零像素）
              ├─ ② Windows OCR ──── 屏幕上的字 → 词框 + 坐标（系统引擎）
   看 ────────┼─ ③ 浏览器 CDP ───── 网页 DOM 文字与元素（本机回环）
              ├─ ④ 图标字体反查 ─── Segoe 码点模板匹配（纯图标按钮）
              └─ ⑤ 视觉兜底 VLM ─── 云端 GLM-4V / 本地 Ollama（★ 默认关闭）
                          ⇓
   动 ────► 再看一眼屏幕 ──► 三态判词：生效 / 确认没变 / 没测出来

原则只有一条：能问 Windows 要结构化答案的，绝不看像素；能看像素解决的，绝不请模型。 每往下一层，耗时、费用、隐私开销都更高 —— 分层不只是省显卡，更是把"什么时候屏幕会离开你的电脑"变成一个显式决定。

五条通道一览

① UI Automation：元素天生有身份

UIA 是 Windows 给读屏软件用的接口，每个控件天生带名字、类型、矩形、可用状态和交互能力（Invoke / Toggle / Value…）—— 这些是结构化数据，不是图像。所以：

• 元素有短 id（e12、e42）。agent 下一步说"点 e42"，而不是自己算坐标。同一帧里两个长得一模一样的按钮也不会点错 —— 选择的依据是元素身份，不是像素长相。

• 不受主题、颜色、字体、动画影响。深色模式换肤、按钮变灰，名字和位置照读。

• 接口还带视口标注（in_view / scroll_y）：长页面里 y=17838 的节点会明确告诉你"现在不在这一屏"，先滚动再点 —— 屏外节点是"暂时看不见"，不是坏数据。

• 边界如实说：自绘界面（Canvas、游戏、PDF 渲染、未开无障碍的 Electron）UIA 只能拿到外壳甚至全黑。所以这条线是主力而不是全部，②③④⑤ 永远留着。

② OCR：系统引擎 + 实测出来的四条规矩

用 Windows 自带的 Windows.Media.Ocr，不下载任何模型。但"能用"和"能用准"之间隔着四条实测规矩：

1. 必须放大 4 倍再认。原尺寸实测会漏行，4 倍才认全；认完坐标再除回来。

2. 逐字框必须合成词框。Windows OCR 把中文切成单字（「文件」=「文」+「件」两个框），按"同行 + 紧邻 + 同号（字号一致）"三条判据合并，后续对齐和可点化才有"词"这个粒度。

3. 截图只在内存里走一圈。PIL → PNG 字节 → WinRT 内存流，不落任何临时文件；默认 1.5 秒超时，到点就返回，绝不挂着调用方。

4. 坐标口径恒定声明。所有词框坐标都标 client_physical（客户区物理像素），成功失败都带这个字段 —— 调用方永远不用猜"这坐标是哪个坐标系"。

DPI 是最大的坑，也是处理得最严的地方。 150% 缩放的屏幕上，"感知进程"和"非感知进程"读同一个窗口，尺寸能差 1.5 倍；服务进程必须声明 PER_MONITOR_AWARE，拿到的才是物理像素，而且绝不再乘一次缩放系数（双乘就是从这来的）。抓完图还会立刻复查一次窗口几何：抓图期间窗口要是移动过，这一帧就被标记"画面不稳定"，不许拿去和屏幕坐标对齐。

③ CDP：网页有自己的通道

浏览器场景不走截图识别 —— 通过 DevTools 协议（CDP）直接读 DOM：页面文字、元素位置、精确滚动，全是本机回环通信。Chromium 在检测到无障碍客户端接入后会把整棵 DOM 灌进 UIA 树，所以网页在 ① 和 ③ 两条通道里都可见，互为校验。

④ 图标字体反查：纯图标按钮的确定性识别

Windows 界面图标大量来自 Segoe Fluent Icons / Segoe MDL2 Assets，码点是公开的。于是纯图标按钮（设置齿轮、返回箭头、关闭 ×）有了一条零模型的识别路：

屏幕上的图标块 → 归一化 → 与按码点渲染的字体模板做归一化互相关（NCC） → 码点 → 语义名

三条实测纪律：

• 模板按目标窗口的 DPI 渲染：150% 屏上同一个码点是 24px 不是 16px，模板尺寸错了 NCC 必掉分。

• 只对"已知的图标格"工作，不满屏乱扫：实测满屏乱扫的高置信命中密度只有 0.6%，且全是弧线类字形的系统性误判。

• 输出是"多一条证据"，不是结论：给出码点、语义名、分数和 margin（第一名与第二名的分差）。真图标往往是"孤峰"，误命中往往是"一片糊"—— margin 比绝对分更能分清这两者，双闸不过就老实报"认不出"。认错一个图标等于点错一个按钮，这里宁可认输。

截图：窗口被挡住也能截

截图兜底用 PrintWindow(PW_CLIENTONLY | PW_RENDERFULLCONTENT)：目标窗口被别的窗口压着，也能让它把内容画出来。某些硬件加速窗口对这条路返回全黑，就自动退回按屏幕矩形抓。两条路径输出统一成同一口径（客户区物理像素）—— 修之前一个返逻辑尺寸一个返物理尺寸，同一个窗口的坐标能差 1.5 倍。性能上客户区抓帧实测中位 ~24ms（整窗抓帧 ~78ms）。

帧凭据：不许拿旧截图点新画面

"看"的另一半是"什么时候需要重新看"。这块有一套独立的机制：

• 每帧带编号，15 秒过期。动作必须携带新鲜截图的凭据，画面变了凭据作废 —— 拿三秒前的截图点现在的画面，闸门直接拒绝。

• 变化检测是三值的，不是布尔：真变了 / 确认没变 / 没测出来。「我没看见」和「我看见了没变」是两件事，永远不说谎 —— 画面退化（全黑帧）时宁可放弃复用也不硬判。

• 判变化不用整屏 hash。实测屏幕有动画时整屏 hash 变化率 90.6%，等于没有判据；也不用"一像素不同就算变"（记事本光标闪烁 0.01% 的像素也算变过）。实际做法：客户区切 64×64 瓦片、灰度降采样做指纹，差异像素占比超过阈值才算变；再用形状特征滤掉光标（细长条、窄边 ≤8px）这类噪音；连续 2 帧同结论才上报（滞回）。

• 变化即停，不做固定 sleep。动作发出后先给 50ms 重绘宽限（实测界面重绘平均晚 ~40ms），然后 25ms 一次轮询指纹，界面一变立刻停，最多等 300ms —— 常态下只探一轮就出判词。

⑤ 视觉兜底：真需要模型时才请模型（默认关闭）

UIA、OCR、图标反查都看不见的场景（游戏画面、Canvas 自绘、非 Segoe 图标），才轮到视觉模型。这一层是接口位 + 两个可插拔后端：

• 三态纪律：找到了 / 有效观测到"画面里没有" / unobservable（没测出来）。后两者严格分开 —— 模型超时、回执解析不出、候选不合规，一律归"没测出来"，永不当成功、也永不当"没有"。

• 默认关闭：AGENTCTL_VISION_ASSIST=1 才启用。装完就开 = 用户的屏幕被送进一条没人审过的通道，不行。

• 本地后端（Ollama，qwen2.5-vl）：图只发 127.0.0.1，不出门。这里有个实测出来的细节：qwen2.5-vl 的预处理会把任何图当作 1920×1080 处理，返回的框是那个"幻觉坐标系"的值 —— 对策是先把图锚定到 1920×1080 再喂，模型坐标系与真实像素 1:1，返回的框直接反算回原尺寸。冷启动（含模型加载）实测 ~15s，热查询 ~2.8s。

• 云端后端（OpenAI 兼容接口，默认 glm-4v-flash 免费档）：四道闸，缺一不发：

  1. 双钥匙：两个环境变量都由人手设才启用；

  2. 密钥文件制：密钥只在文件里，每次调用现读，不进日志、不进命令行、不进代码（提交前扫描兜底）；

  3. 敏感窗拒发：授权弹窗等敏感窗口在调用侧直接拒绝，图根本不会离开；

  4. 日预算闸（fail-closed）：默认 ¥2/天，价格未知的模型、账本读不了、预算用尽 —— 全部拒发。

• 敏感窗口只走本地，绝不降级到云。

• 面板可见：连的什么模型、调了几次、估了多少费用，悬浮窗可查（从 API 回执实测 token 数记账）；图像本身永不落盘。

动完再核一眼：像素不判成功

视觉流水线的最后一环在动作之后：每个动作做完，再看一眼屏幕，对照动作前后两帧的变化，给出三种判词之一：

这就是"像素不判成功"：动作发出去不算数，屏幕变了才算。点错窗口时这一下根本不会发出去，还会告诉你该关掉哪个窗口。

任何 AI 都能接

同一套工具，提供三种接法。支持 MCP 的 AI 直接接；不支持的，用 HTTP 或命令行也能调。

下面的 <安装目录> 换成你实际的安装位置。令牌默认在 %LOCALAPPDATA%\AgentCtl\state\token，设了 AGENTCTL_HOME 的话就在 %AGENTCTL_HOME%\state\token。

claude mcp add agentctl -- "<安装目录>\agentctl.cmd" mcp

codex mcp add agentctl -- "<安装目录>\agentctl.cmd" mcp

或者接常驻的 HTTP 服务：

$env:AGENTCTL_MCP_TOKEN = (Get-Content "$env:LOCALAPPDATA\AgentCtl\state\token" -Raw).Trim()
codex mcp add agentctl --url http://127.0.0.1:8761/mcp --bearer-token-env-var AGENTCTL_MCP_TOKEN

在客户端的 MCP 配置里加一个 stdio 服务器。大多数客户端都认这个格式（Gemini CLI 是 ~/.gemini/settings.json，Cursor 是 .cursor/mcp.json，Cherry Studio 在设置界面里填同样的命令和参数）：

{
  "mcpServers": {
    "agentctl": {
      "command": "<安装目录>\\agentctl.cmd",
      "args": ["mcp"]
    }
  }
}

先启动 HTTP 服务：

agentctl.cmd serve

然后任何语言都能调，比如 Python：

import os
import requests

token = open(os.path.expandvars(r"%LOCALAPPDATA%\AgentCtl\state\token"), encoding="utf-8").read().strip()
api = "http://127.0.0.1:8760/v1"
headers = {"X-AgentCtl-Token": token}

print(requests.get(f"{api}/status", headers=headers).json())                 # 查状态
print(requests.post(f"{api}/perceive/windows", json={}, headers=headers).json())  # 列窗口

完整接口见 docs/AGENT接口.md。

它能做什么

接上之后，你的 AI 会多出 20 多个桌面工具：

你可以这样跟 AI 说：

"打开记事本，写一段会议纪要，存到桌面。" "把这个网页表格里的数据抄进 Excel。" "帮我在设置里找到显示缩放，截图给我看现在是多少。"

AI 会自己列窗口、找控件、点击、打字，每一步都先过闸门，做完给你看前后截图。

为什么敢让它动手

把键鼠直接交给 AI，等于把电脑借给一个没见过面的人。computer-use-gate 在 AI 和键鼠中间加了五道闸，每个动作都要依次通过：

① 你签发通行证 → ② 租约绑定窗口 → ③ 截图必须是新的 → ④ 敏感窗口一律拦 → ⑤ 急停一票否决
                                                                          ⇓
                                                     每一步都写进证据链（前后截图 + 决策日志）

控制期间屏幕四周会亮一圈细边框，你随时知道 AI 正在动手。

它不会骗你说"成功了"

每个动作做完，它都会再看一眼屏幕，给出三种结果之一（详见 视觉是怎么实现的）：

点错窗口时，这一下根本不会发出去，它还会告诉你该关掉哪个窗口。

事后能查、能证明

• 每个动作都记进时间线，记录带哈希链。改过一个字，ctl_verify 就能指出从第几条开始坏的。

• 任意一段操作都能用 ctl_replay 导出回放视频，不用装 ffmpeg。

• 复盘、交接、需要留记录的场景都用得上。

5 分钟上手

你需要：Windows 10/11 x64、Python 3.12、git。不需要显卡，不需要虚拟机，不需要 Docker。

1. 安装

# 国内用 Gitee 镜像；海外换成 https://github.com/GALAXYLLIYI/computer-use-gate
git clone https://gitee.com/GALAXYLIYI/computer-use-gate
cd computer-use-gate
pwsh -File .\install.ps1

想先看清脚本再运行（推荐）：

irm https://gitee.com/GALAXYLIYI/computer-use-gate/raw/main/install.ps1 -OutFile install.ps1
notepad install.ps1      # 看一眼
.\install.ps1

从 Release 下载 zip 的话，先核对哈希：

Get-FileHash .\agentctl.zip -Algorithm SHA256
# 和 agentctl.zip.sha256 里的值逐字比对，不一样就别装

2. 接到你的 AI

按上面 任何 AI 都能接 选一种方式，一条命令或一段配置就够了。

3. 签发通行证，开始干活

让 AI 调用 ctl_authorize，屏幕上会弹出授权窗口，你本人点"允许"。接下来 30 分钟或 60 个动作内，它可以在你授权的范围里动手。

想亲自验证"默认全拒"是不是真的：

python -X utf8 tests\_默认关闭_判据.py

💡 第一次用，建议拿记事本这类无关紧要的窗口练手，别一上来就在有真实账号的软件上开闸。

先说清楚适用范围

✅ 适合

• 在自己的 Windows 电脑上，让 AI 做有人看着的桌面操作

• 需要事后说清楚"AI 到底干了什么"的场景

• 愿意开工前点一下授权的人。这一步就是它的价值所在

⛔ 不适合

• 无人值守批量点击：每 30 分钟或 60 个动作要重新授权，这是设计，不是缺陷

• 绕过验证码、风控或权限检查：不做，也请不要这样用

• Linux / macOS、云端或远程控制：目前只支持本机 Windows

• 需要 SLA 的生产环境：这是 0.x 实验项目，接口还会变

🚧 已知限制

• Canvas、游戏、PDF 内容、没开无障碍的 Electron 应用读不到控件，只能靠截图兜底

• 多显示器和屏幕缩放（125%、150%）的适配还在开发中，点击位置可能偏

• 界面响应超过约 200ms 时，可能误报"确认没变"

• OCR 第一次识别要暖机，大约 3 秒

隐私：数据不出你的电脑

• 没有遥测，不上传任何数据，服务只监听 127.0.0.1

• 视觉默认不出门：UIA、OCR、CDP、图标反查全在本机；视觉兜底模型默认关闭，开了也分"本地 Ollama（图不出门）/ 云端（四道闸，敏感窗拒发、日预算 fail-closed）"两条路，敏感窗口只走本地

• 证据存在本机 work\ 目录，里面有屏幕截图和窗口标题，属于敏感数据，别提交到仓库，也别随手发给别人

• 授权状态、通行证、急停标志默认存在 %LOCALAPPDATA%\AgentCtl\，可以用 AGENTCTL_HOME 环境变量改到别的盘

• 通行证密钥只存加盐哈希，不存明文

更新与卸载

项目状态

实验性 0.x，由作者与几位协作者共同维护。 当前版本 v0.1.1（2026-10-24）。

• 设计接近成熟：安全模型、授权租约、帧凭据都经过推演

• 实现还有欠账，接口还会调整

• 判据都在维护者自己的电脑上跑过，外部用户还很少

所以最需要的，是你来把它跑坏。遇到问题请提 Issue，写清版本、复现步骤、看到了什么、期望看到什么。

本仓已开放 GitHub / Gitee 协作者权限，欢迎提 PR。贡献者名单见 CONTRIBUTORS.md，贡献流程见 CONTRIBUTING.md。

第一次来？照着 docs/贡献者上手指南.md 走：接受邀请 → 配环境 → 认证 → 切分支 → 提 PR，每一步都有命令和常见坑。

文档

免责声明

本项目让 AI 的动作可以审计，不保证动作一定正确。证据链只能证明"发生了什么"，不能证明"这应该发生"。因误点、误填、误删、账号风控等造成的损失，作者不承担责任。请先在测试环境和测试账号上验证。

许可

Apache License 2.0，允许商用。第三方组件许可见 THIRD_PARTY_NOTICES.md。

Copyright (c) 2026 GALAXYLLIYI

无需显卡，任何 AI 长眼睛接管你自己的 Windows。

觉得有用？点个 ⭐ Star，让更多人用上 Windows 版的 Computer Use。