Reflex Computer Use

reflex-computer-use

reflex-computer-use is an open-source computer use MCP server for Claude Code, Codex and other AI agents. It controls macOS and Windows desktops, including a remote Windows machine over SSH, by reading the accessibility / UI Automation tree instead of taking a screenshot at every step, and uses Jev (TypeSafe's System One decision model; a TypeSafe, OpenRouter or Command Code key works) as a fast judge. On macOS it works in the background since 0.5: clicks, typing and scrolling go to the window the agent is working on, even behind your other windows, without moving your cursor or taking your keyboard. Since 0.4, Jev can also look at the screen itself (look: Jev 1.14 image input and boxes) to find icons and things in game scenes. → English README

给编码代理（Claude Code、Codex 等）用的桌面操作（computer use）MCP 服务（原名 reflex-cu）：让 AI 自己操作 Mac 和 Windows 的桌面，也能通过 SSH 操作另一台 Windows。在 Mac 上，AI 可以在后台操作窗口，你照常用自己的电脑，互不干扰。

名字里的 reflex 是"反射"：除了常规的截图、点击、打字，它把"点哪个""成功了没""加载完没"这类不需要思考的高频小判断，交给一个反射式的快速判断模型去做，代理不用每一步都看截图。目前接的判断模型是 Jev（TypeSafe 的 System One 模型，一次约 0.3 秒）。

0.5 新功能：后台运行，不抢你的鼠标键盘（Mac）。 AI 操作的窗口可以压在你的窗口下面：点击、输入、快捷键、粘贴、拖动、滚轮都只发给那个应用，你的光标不动、前台不切、键盘焦点不丢，你可以一边干自己的活一边让它干活。截图和读字也能看到被挡住的窗口。非要动真实鼠标键盘时（比如游戏），它会先等你停手。少数应用会自己把窗口抬上来（比如 Chrome 新建标签页），这时键盘焦点约 0.1 秒内还给你。详见下文后台运行，不抢你的鼠标键盘。

0.4 新功能：Jev 能看画面了。 给 find、check、wait 加上 look: true，Jev 直接看截图：能找到纯图标、游戏画面里的人物和物件，也能回答"画面里有没有某样东西"。截图只发给 Jev，不进代理的上下文。目前是实验性功能，只支持 TypeSafe 官方密钥，详见下文看画面。

English

三种用法

用法	被操作的机器	怎么连
本机 Mac	运行代理的这台 Mac	MCP 服务进程内直接调用系统接口
本机 Windows	运行代理的这台 Windows	同上
远程	另一台 Windows	那台机器的桌面会话里跑一个只监听本机的服务，MCP 服务通过 SSH 隧道访问

三种用法的工具、参数、坐标约定完全相同。

工具

工具	作用
status	分辨率、前台窗口、用户多久没动鼠标键盘
screenshot	截图，可截窗口或局部
windows / focus	列出窗口、切到前台
observe	不截图，直接读出窗口里的界面元素和它们的坐标；打开着的菜单也会列出
click / move / drag / scroll	鼠标，可以用坐标，也可以用 observe 返回的元素编号
key / type	按键和组合键；输入文字（含中文），可走剪贴板
find	Jev：一句话描述要操作的元素，返回最匹配的那个和置信度，可以直接点；加 look 时看截图找（图标、游戏画面）
check	Jev：对当前屏幕问一个是非题；加 look 时连截图一起看
wait	Jev：轮询直到是非题成立或超时
steps	一次执行一串操作，Jev 没把握或某步失败就停下

带 Jev 标记的三个工具需要你自备 Jev 密钥（见下文）；没有密钥时它们不可用，其余工具照常工作。

界面是怎么读出来的

• Windows 用 UI Automation，Mac 用辅助功能树：能拿到控件的名称、类型、位置和是否禁用，通常 0.1–0.5 秒。
• 控件的状态会一起读出来：开关是开还是关，下拉框当前选的是什么、有没有展开，哪一项被选中，输入框里填了什么（密码框除外）。几个控件重名时标出各自属于哪个分组。
• Windows 上，滚动区域里还没滚到的项也会列出；用元素编号点击或用 find 点击时会先自动滚动到它。
• 读不到东西的窗口（游戏、自绘界面）自动改用文字识别：Windows 用 RapidOCR，Mac 用系统自带的 Vision。
• 默认只把文字交给 Jev。纯图标、游戏画面这类没有文字的内容，给 find、check、wait 加上 look: true，Jev 会直接看截图（见下一节）。

看画面（look，实验性）

Jev 1.13 起能看图，1.14 又加了"框出某个东西"的问题类型。加上 look: true 后：

• find 先在整个窗口上粗框一次，再把那一块放大重新框一次，返回中心坐标；confidence 是放大之后 Jev 认为它确实在那里的概率，够高才会点。
• check、wait 把窗口截图和读出的文字一起交给 Jev 判断。
• 截图只发给 Jev，不进代理的上下文，代理那边不花看图的钱。

实测（本机，不点击，只比对位置）：一张游戏截图上的 8 个目标（人物、灯笼、箭靶、旗帜等）两轮框选 8/8 命中；浏览器工具栏上 8 个小按钮命中 6 个，其中一个低置信度没点，一个框在了同一个标签页的标题上而不是它的关闭按钮。一次 find 约 1~3 秒，check 约 0.6 秒。

在一台 4K 显示器的全屏游戏（黑神话：悟空）上问"画面里有人物吗？"：只读文字时 Jev 只拿到 1 个识别出的元素，答 0.06（错）；加 look 后答 0.98。

限制：

• 这是 TypeSafe 标为实验性（"Dreamer-ready"）的功能，格式和准确度都可能变。紧挨着的小图标仍可能框错，重要的点击先用 check 确认，或者自己看截图。
• 目前只有 TypeSafe 官方密钥能用。OpenRouter 已经上了 Jev 1.14，但会把图片丢掉、让模型闭着眼回答，所以通过 OpenRouter 或 Command Code 时 look 会直接报错，而不是瞎答。status 的 jev_images 表示当前来源能不能看图。
• 框选需要 Jev 1.14，默认用 jev-preview；TypeSafe 把 jev-latest 切到 1.14 之后可以用 CU_JEV_VISION_MODEL 改回。

后台运行，不抢你的鼠标键盘（Mac）

一般的 computer use 要独占电脑：它动鼠标、切窗口的时候你只能看着，你一碰鼠标它就点错。reflex-computer-use 在 Mac 上把操作直接发给目标应用，AI 在后台干活，你在前台干自己的事。代理只要先 observe 指定窗口，之后的操作就都发给那个窗口：

observe(window: "Chrome")              # 读后台的 Chrome，不切到前台
click(id: 33)                          # 点地址栏
type(text: "youtube.com", enter: true) # 输入并回车

整个过程中你的光标不动，前台还是你正在用的应用，Chrome 也一直压在你的窗口下面。

各种操作的走法：

操作	走法	对你的影响
对后台窗口点击（坐标或元素 id）、拖动、滚轮	事件只发给该应用（route: "bg"）	不动光标、不切窗口、不抬窗口，窗口被挡住也行
对前台窗口用元素 id 点击	辅助功能接口（route: "ax"）	不动光标
type、key 发给后台窗口，含 cmd 组合键和粘贴	事件只发给该应用（route: "pid"）	前台不受影响，粘贴后恢复剪贴板
按窗口截图、读文字、look	截窗口自身的内容	被挡住也能看到
操作前台窗口、全局快捷键、real: true	真实鼠标键盘（route: "real"）	先等你停手 1.5 秒，最多等 8 秒，还在用就报错不动手；force: true 可跳过

不写 window 时，操作发给上次读过或切过的窗口；坐标落在该窗口外时走真实鼠标。目标窗口已关闭时报错，不会打到别的窗口。全局快捷键加 global: true。

实现上，后台操作靠的是告诉目标应用“你被激活了”，真实前台并没有变，用到了系统未公开的事件字段和 CGEventSetWindowLocation，系统升级后可能失效。游戏这类直接读硬件输入的程序收不到后台事件，要用 real: true。

坐标

所有坐标都以不带 zoom 的截图为准：主显示器等比缩放到最宽 1600（环境变量 CU_VIEW_W 可改）。截图上看到的位置就是要点的位置。

安装

想让 AI 替你装：把 INSTALL_FOR_AI.md 的链接发给你的编码代理，让它照着做。下面是手动安装的步骤。

需要 Python 3.10 以上。

快速安装（操作本机 Mac 或 Windows）：装了 uv 后，可以直接从 GitHub 源码包注册：

claude mcp add reflexcu -s user -- uvx --from https://github.com/8itlab/reflex-computer-use/archive/refs/heads/main.tar.gz reflex-computer-use
codex mcp add reflexcu -- uvx --from https://github.com/8itlab/reflex-computer-use/archive/refs/heads/main.tar.gz reflex-computer-use

或者 pip install https://github.com/8itlab/reflex-computer-use/archive/refs/heads/main.tar.gz 后用命令 reflex-computer-use 启动。远程操作另一台 Windows 仍按下文"远程 Windows"安装。

Jev 密钥（需自备）

本项目不附带、也不代理任何 Jev 额度。find、check、wait 三个工具要用你自己的密钥，费用由你自己的账户承担。不配置密钥也能用，只是这三个工具会报错，其余工具不受影响。

密钥有三种来源，任选其一：

来源	环境变量	或者写进文件	看画面（look）
TypeSafe 官方	TYPESAFE_API_KEY	~/.reflexcu/typesafe_key	支持
OpenRouter（不需要 TypeSafe 账号）	OPENROUTER_API_KEY	~/.reflexcu/openrouter_key	暂不支持（图片会被丢掉）
Command Code 的 Provider API	COMMANDCODE_API_KEY	~/.reflexcu/commandcode_key	未验证，默认不发图

密钥放在被操作的那台机器上，文件里只写密钥本身（Windows 上 ~ 是 %USERPROFILE%）。配了不止一种时按表里的顺序取第一个；要指定就把 CU_JEV_PROVIDER（或文件 ~/.reflexcu/jev_provider）设成 typesafe、openrouter 或 commandcode。status 的 jev_provider 会显示当前用的是哪一个。

别的兼容同一协议（System One）的网关也能接：用 CU_JEV_URL 和 CU_JEV_MODEL（或文件 ~/.reflexcu/jev_url、~/.reflexcu/jev_model）覆盖地址和模型名，密钥仍按上面的方式放。

如果所在网络访问不了 TypeSafe 的接口（返回 HTTP 451），可以换一种来源（比如 OpenRouter），或者配一个代理：环境变量 CU_PROXY，或文件 ~/.reflexcu/proxy，内容形如 http://127.0.0.1:7890。Windows 上由计划任务启动的远程服务读不到登录之后才设置的环境变量，这种情况用文件。

本机 Mac

git clone https://github.com/8itlab/reflex-computer-use && cd reflex-computer-use
python3 -m venv ~/.reflexcu/venv
~/.reflexcu/venv/bin/pip install -r requirements-macos.txt
claude mcp add reflexcu -s user -- ~/.reflexcu/venv/bin/python "$PWD/reflexcu/server.py"

启动代理的那个应用（终端、IDE）需要"辅助功能"和"屏幕录制"两项权限，status 会报告它们是否到位。

本机 Windows

git clone https://github.com/8itlab/reflex-computer-use
cd reflex-computer-use
python -m venv venv
venv\Scripts\pip install -r requirements-windows.txt
claude mcp add reflexcu -s user -- "%CD%\venv\Scripts\python.exe" "%CD%\reflexcu\server.py"

要操作以管理员身份运行的程序，代理本身也得以管理员身份运行，否则输入会被系统拦掉。

远程 Windows

在被操作的机器上（需要已经能从你的机器 SSH 过去）：

git clone https://github.com/8itlab/reflex-computer-use C:\reflexcu
powershell -ExecutionPolicy Bypass -File C:\reflexcu\scripts\install-windows-daemon.ps1

脚本会建虚拟环境、装依赖，并注册一个登录时启动的计划任务。服务必须跑在桌面会话里：从 SSH 直接启动的进程看不到屏幕。

在运行代理的机器上（这一侧只用标准库）：

claude mcp add winbox -s user -e CU_SSH=<ssh 别名> -e 'CU_DIR=C:\reflexcu' -- python3 /path/to/reflexcu/reflexcu/server.py

要连多台机器，就各注册一个，并用 CU_LPORT 给每台分一个不同的本地端口。

在 Codex（ChatGPT 桌面应用）里用

它是标准的 stdio MCP 服务，Codex 同样能用。把上面 claude mcp add 换成 codex mcp add，环境变量用 --env：

codex mcp add reflexcu -- ~/.reflexcu/venv/bin/python /path/to/reflex-computer-use/reflexcu/server.py
codex mcp add winbox --env CU_SSH=<ssh 别名> --env 'CU_DIR=C:\reflexcu' -- python3 /path/to/reflex-computer-use/reflexcu/server.py

只读工具（status、screenshot、windows、observe、check、wait）带有只读标注，codex exec 这类非交互运行可以直接调用；会动鼠标键盘的工具需要你在交互界面里批准。在 Mac 上，系统权限是按启动服务的应用给的：从 ChatGPT 应用里用，就要给 ChatGPT 开"辅助功能"和"屏幕录制"。

配置

环境变量	用在哪	含义
CU_SSH	MCP 服务	不设或 local 是本机；否则是远程机器的 SSH 别名
CU_DIR	MCP 服务	远程机器上的安装目录，用来读 token.txt（默认 C:\reflexcu）
CU_TOKEN	MCP 服务	直接给出令牌，不通过 SSH 读取
CU_LPORT / CU_RPORT	MCP 服务	隧道的本地端口（默认 18765）和远程服务端口（默认 8765）
CU_PORT	远程服务	监听端口（默认 8765）
CU_VIEW_W	后端	坐标系宽度（默认 1600）
TYPESAFE_API_KEY	后端	你自己的 TypeSafe 密钥；也可以写在 ~/.reflexcu/typesafe_key
OPENROUTER_API_KEY	后端	通过 OpenRouter 用 Jev 时的密钥；也可以写在 ~/.reflexcu/openrouter_key
COMMANDCODE_API_KEY	后端	通过 Command Code 用 Jev 时的密钥；也可以写在 ~/.reflexcu/commandcode_key
CU_JEV_PROVIDER	后端	typesafe、openrouter 或 commandcode；不设时按这个顺序用第一个配了密钥的。也可以写在 ~/.reflexcu/jev_provider
CU_JEV_URL / CU_JEV_MODEL	后端	覆盖接口地址和模型名，用来接别的兼容网关；也可以写在 ~/.reflexcu/jev_url、~/.reflexcu/jev_model
CU_JEV_VISION_MODEL	后端	look 用的模型（默认 jev-preview）；也可以写在 ~/.reflexcu/jev_vision_model
CU_JEV_IMAGES	后端	设成 1 时，即使当前来源没被确认支持图片也照样发图（给已经支持图片的兼容网关用）
CU_PROXY	后端	访问 Jev 用的代理，例如 http://127.0.0.1:7890；也可以写在 ~/.reflexcu/proxy。系统代理不会被自动使用

命令行调试

server.py 带参数时直接执行一个工具并打印结果：

python reflexcu/server.py status
python reflexcu/server.py find '{"goal":"保存按钮"}'
python reflexcu/server.py find '{"goal":"右上角的齿轮图标","look":true}'
python reflexcu/server.py check '{"question":"画面里有没有弹出的对话框？","look":true}'
CU_SHOT=shot.jpg python reflexcu/server.py screenshot

tests/local_smoke.py 通过真实的 MCP 协议做一遍只读检查；tests/selftest_mac.py 在一个临时的"文本编辑"文档里测鼠标键盘。

安全

这个工具能看到屏幕、能控制鼠标键盘，请按这个分量对待它。

• 远程服务只监听 127.0.0.1，每个请求都要带 token.txt 里的令牌，对外只走 SSH 隧道。不要把端口暴露到网络上。
• 远程服务以最高权限运行，这样才能操作管理员窗口。能访问那个端口和令牌的人就能控制那台机器。
• find、check、wait 会把屏幕上的文字发给 TypeSafe 的 Jev 接口（用 OpenRouter 或 Command Code 的密钥时经由它们转发）。加了 look 时还会发送那个窗口的截图。
• 用 OpenRouter 的密钥时，请求会带上本项目的名称和仓库地址（OpenRouter 的应用归属标头，用于它公开的应用榜单），不含你的任何信息；设 CU_NO_ATTRIBUTION=1 可以关掉。屏幕上有敏感内容时不要用这三个工具，或者不配置密钥。
• 输入是发给前台窗口的。先切对窗口再打字，否则按键会进别的程序；有人正在用那台机器时，status 的 idle_seconds 会很小。
• 带内核反作弊的在线游戏可能把模拟输入当作外挂，请自行判断，不要在这类游戏里使用。

已知限制

• Mac 后台操作：应用自己要抬窗口的动作照样会抬（比如 Chrome 新建标签页会把窗口提到最前并拿走键盘焦点），后台时要新开页面就在地址栏输入网址后按 cmd+enter，它在后台标签页打开、不抬窗口；万一焦点被抢，maccu 会在约 0.1 秒内还回去，结果里带 focus_restored_to，但窗口会留在上层；最小化或在其他桌面空间的窗口不在窗口列表里；游戏这类读硬件输入的程序收不到后台事件。Windows 版还没有后台操作。
• 只操作主显示器。
• look 是实验性功能：紧挨着的小图标可能框错，Jev 偶尔对框错的位置也给出高置信度；重要的点击先确认。分辨率很高的窗口更慢：4K 全屏游戏上一次看图判断约 8 秒，其中文字识别约 4 秒；游戏里只想看画面时加 source: "tree" 跳过文字识别，约 4 秒。
• key 发的字符键会经过输入法；输入文字用 type。key 的长按只是保持按下，不会连发字符。
• Mac 上打开的菜单靠文字识别读取，没有禁用状态；Windows 上经典菜单和归属于该窗口的弹出层走 UI Automation。
• 远程模式目前只有 Windows 的安装脚本。Mac 后端也能跑 daemon.py，但没有测过。
• 游戏里的相对移动（转镜头）没有系统测试过。

实测数据

都是同一个代理（Claude Opus 5.5）、同一句任务描述，只换工具：一组用 reflex-computer-use 的全部工具，另一组把同一个服务限制成只有截图、点击、按键（CU_TOOLS=screenshot）。对照组是本项目自己的截图模式，不是别家产品。每格只跑了 2 次，数字只能看量级。

任务	reflex-computer-use 全部工具	只用截图和点击
Mac，只说一句话："打开 ChatGPT 应用"	8 / 9 秒，4 次调用	18 / 30 秒，7 / 12 次调用
Mac，只说一句话："打开计算器，算出 1234 乘以 56"	23 / 22 秒，5–6 次调用	35 / 38 秒，21 次调用
Mac，只说一句话："打开系统设置，查 macOS 版本号"	25 / 24 秒，4 次调用	31 / 26 秒，11–13 次调用
远程 Windows，在"设置"里连改五项	61 / 88 秒，11–15 次调用，约 $0.27	54 / 72 秒，28–38 次调用，$0.40–0.56

短任务上更快，调用次数少一半以上；步骤很多的长任务上速度没有优势，但花费更低。

常见问题

reflex-computer-use 是什么？ 一个标准的 stdio MCP 服务，给 AI 代理提供"看屏幕、动鼠标键盘"的工具，也就是通常说的 computer use。它装在你自己的机器上，由你已经在用的代理（Claude Code、Codex、ChatGPT 桌面应用里的 Codex）来调用。

和模型自带的 computer use 有什么不同？ 常见做法是每一步截一张图交给大模型看。reflex-computer-use 优先直接读出界面上的控件（名称、状态、坐标），只有图标、游戏画面这类没有文字的内容才看图，而且看图找东西也可以交给 Jev（look），截图不必进大模型的上下文；"点哪个""成功了没"这类小判断交给 Jev。它还能通过 SSH 操作另一台 Windows 的真实桌面。

AI 操作的时候我还能用电脑吗？ 在 Mac 上能。AI 操作的窗口可以在你的窗口后面，它的点击和输入只发给那个应用，不动你的光标、不抢你的键盘，见上文"后台运行，不抢你的鼠标键盘"。游戏这类必须用真实鼠标键盘的，它会等你停手再动。Windows 上目前还会占用鼠标键盘。

没有 Jev 密钥能用吗？ 能。截图、读界面、鼠标、键盘都不需要密钥，只有 find、check、wait 三个工具需要。

Jev 能看图吗？ 能，Jev 1.13 起支持图片，目前还是实验性功能。reflex-computer-use 0.4 起用它来找图标和游戏画面里的东西（look），只支持 TypeSafe 官方密钥，见上文"看画面"。

Jev 的密钥从哪来？ TypeSafe 官方、OpenRouter、Command Code 三选一，见上文"Jev 密钥"。在访问不了 TypeSafe 的网络里，可以用 OpenRouter 的密钥。

支持哪些系统和客户端？ 被操作的机器：macOS、Windows；远程模式目前只支持操作 Windows。客户端：在 Claude Code 和 Codex（含 ChatGPT 桌面应用）里实测过，其他支持 stdio MCP 的客户端按同样方式注册。

代码结构

reflexcu/core.py     与平台无关：合并界面树和文字识别、Jev 判断、各个工具的实现
reflexcu/win.py      Windows 后端
reflexcu/mac.py      Mac 后端
reflexcu/server.py   MCP 服务（stdio）：本机直连，或经 SSH 隧道转发
reflexcu/daemon.py   远程模式下跑在被操作机器上的 HTTP 服务

许可证

MIT