ScreenClaw

睇虾 — AI 应用的可视化操作必备伴侣

让任何多模态大模型识别网格坐标，自动化操作任何软件

English | Agent Guide | Demo Video

📖 什么是 ScreenClaw？

ScreenClaw（睇虾）是一款本地运行的"中间件"程序，它充当 AI 应用与桌面软件之间的桥梁。

核心创新：通过在截图中叠加百分比坐标网格，让任何多模态大模型都能精确识别界面元素位置，无需专门训练 UI 模型。

AI 应用通过 HTTP API 可以：

📸 截图并绘制坐标网格 — 精确定位界面元素位置
🖱️ 注入鼠标键盘操作 — 后台无感控制，不影响用户使用
🔄 自动化任何软件 — 即使软件没有 API 或命令行接口

关键特性：全程不抢夺用户的物理鼠标和键盘，你可以在看电影、写文档的同时，让 AI 在后台完成自动化任务。

✨ 核心特性

🖥️ 后台无感操作

采用 background 模式，通过 PostMessage/SendMessage 注入事件，不会激活窗口或抢占焦点，用户毫无感知。

📐 百分比坐标网格

让任何多模态大模型有了精确定位能力，且识别速度更快
基于百分比（0-100）的坐标系统，只要窗口比例不变，适用于任何大小的窗口
不同分辨率、不同窗口尺寸都能复用相同的坐标
自适应网格密度和数字大小：基于压缩后的图片尺寸，自动生成最合适的密度和数字大小，避免 AI 乱传参数影响读坐标

💻 操作电脑软件

支持自动化操作大部分电脑软件，特别是不提供 API、CLI 等自动化工具的传统桌面软件。

📱 操作手机

支持自动化操作手机模拟器、官方手机助手（各家手机厂商的多屏协同/手机投屏）：

无需 ADB
无需 root
无需虚拟机
无需专门 UI 大模型就能操作手机 APP

🖥️ 桌面级截图+操作

直接对桌面截图和操作，不绑定进程，可操作桌面图标、任务栏、开始菜单等任何可见内容
支持多显示器，每个显示器独立坐标空间，支持跨屏拖拽
操作方式与窗口级一致，共用网格绘制和百分比坐标体系

🎬 录制+沉淀场景

人工带跑：通过快捷键或托盘菜单启动录制，人工操作，后台自自动捕获每步截图、坐标和操作类型。
AI沉淀：调用screenclaw技能，给出录制产物文件夹（程序根目录record下），让AI将产物沉淀为场景模板

💎 沉淀复用

AI操作+AI沉淀：AI自动操作完后，支持将成功的任务流程沉淀为场景模板，下次直接复用。也可以优化历史模板。
坐标适配检测：使用模板时，若应用尺寸与模板不符，支持按比例调整坐标，尝试复用

🔒 安全可控

Token 认证机制
禁止访问进程黑名单，避免 AI 访问敏感应用
Hijack 操作需用户确认

🎮 托管模式

用户主动要求时进入，AI 完全控制电脑，物理输入，无需逐次确认。适合需要持续操作的场景（如中文输入）。通过快捷键 Ctrl+Alt+Z 可随时退出。

🔍 辅助读坐标

坐标网格支持展示标记点（marker），方便 AI 预览坐标是否正确后再执行操作
裁剪放大接口，对已有截图局部放大，更容易读准坐标

🎛️ 控制工程（Harness Engineering）

轮数自检：每隔若干轮截图操作，通过 API 报错强制 AI 停下来阅读自检文档，重新装载关键上下文，防止长会话中指令遗忘
自检入参校验：AI 需要输入满足最低字符数、包含用户配置关键词的内容才能通过自检，服务端对自检内容做重复校验，防止 AI 偷懒跳过
自定义自检文档：自检文档内容可自定义，不局限于 ScreenClaw，可用于强制 AI 重载任何关键信息

🚀 快速开始

从源码运行（开发环境）

一行部署和启动：

git clone https://github.com/GinSing1226/ScreenClaw.git && cd ScreenClaw && pip install -r python/requirements.txt && npm install && npm run tauri dev

已有项目：

# 安装依赖（首次或依赖更新时）
pip install -r python/requirements.txt && npm install

# 运行开发环境1 建议以管理员身份启动终端
npm run tauri dev

# 或运行开发环境2
npx tauri dev

下载 Release 运行（生产环境）

前往 Releases 页面
下载最新版本的 Windows 压缩包
解压后双击 ScreenClaw.exe 启动

启动服务

应用启动后，点击"启动服务"按钮
查看连接信息：
- 本机访问：http://127.0.0.1:12261
- 局域网访问：http://192.168.x.x:12261

安装 Skill

在 Claude Code、OpenClaw、OpenCode、Codex 等 AI Agent 工具中执行：

npx skills add GinSing1226/ScreenClaw

安装后，AI 即可自动调用 ScreenClaw API 进行桌面软件自动化操作。

📚 API 清单

窗口级 API

API	用途	说明
`health`	验证服务是否可连接	操作前的第一步检查
`get_window_list`	查找目标窗口	获取 window_id（后续操作必需）
`screenshot`	查看界面状态、定位坐标	每次操作后验证结果
`click`	触发功能、进入页面	普通点击操作
`long_press`	触发长按功能	拖拽起点、显示菜单等
`swipe`	触摸式滑动	翻页、切换标签、拖拽
`scroll`	鼠标滚轮滚动	浏览长内容、列表
`right_click`	打开上下文菜单	调用快捷方式
`hover`	触发悬停效果	显示 tooltip、隐藏 UI 元素
`input_text`	输入文本内容	填表、搜索等
`press_key`	触发快捷键	Ctrl+C 复制、Enter 确认等
`wait`	等待 UI 稳定	等待动画、加载完成
`batch`	执行多步骤流程	减少网络请求、固定序列
`drag`	拖拽操作	文件拖放、元素拖动，支持速度控制
`mouse_move`	鼠标相对移动	游戏视角控制，仅 hijack/delegated
`scroll_screenshot`	滚动长截图	自动滚动拼接，生成长图
`crop_zoom_screenshot`	裁剪放大	对已有截图局部放大，看清细节
`delegated`	进入/退出托管模式	用户主动要求完全控制时

桌面级 API

桌面级操作以显示器为单位，不绑定窗口进程，可操作桌面图标、任务栏、开始菜单等。固定使用 hijack 模式。

API	用途	说明
`desktop_get_monitors_list`	枚举显示器	获取索引、名称、分辨率、是否主屏
`desktop_screenshot`	桌面截图	指定显示器截图，叠加网格和标记
`desktop_click`	桌面单击	点击桌面元素
`desktop_double_click`	桌面双击	双击桌面元素
`desktop_right_click`	桌面右键	右键点击桌面元素
`desktop_drag`	桌面拖拽	支持同屏和跨屏拖拽
`desktop_scroll`	桌面滚动	滚轮操作
`desktop_input_text`	桌面文本输入	剪贴板粘贴输入
`desktop_press_key`	桌面按键	键盘快捷键
`desktop_hover`	桌面悬浮	触发悬浮提示

录制 API

API	用途	说明
`recording/start`	开始录制	通过快捷键或 API 触发
`recording/stop`	停止录制	停止并保存产物到 record/ 目录
`recording/status`	查询录制状态	当前是否录制中、步骤数等

🔧 API 使用示例

通用请求头

所有 API 请求都需要携带：

Authorization: Bearer {token}
Content-Type: application/json

1. 健康检查

curl -X GET http://127.0.0.1:12261/api/health

2. 获取窗口列表

curl -X POST http://127.0.0.1:12261/api/get_window_list \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "keyword": "notepad",
    "include_children": true,
    "children_filter": "titled"
  }'

3. 截图（带坐标网格）

curl -X POST http://127.0.0.1:12261/api/screenshot \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "window_id": 1001,
    "main_window_id": 1001,
    "coordinate_type": "grid",
    "color_mode": "grayscale",
    "grid": {
      "density_x": 5.0,
      "density_y": 5.0,
      "opacity": 50,
      "color": "#ff0000"
    },
    "coordinate": {
      "number_density": 2,
      "number_decimal": 1,
      "number_size": 14,
      "number_color": "#ff0000",
      "number_opacity": 100
    }
  }'

4. 点击

curl -X POST http://127.0.0.1:12261/api/click \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "window_id": 1001,
    "main_window_id": 1001,
    "x": 50.0,
    "y": 30.0,
    "action_method": "background"
  }'

5. 长按

curl -X POST http://127.0.0.1:12261/api/long_press \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "window_id": 1001,
    "main_window_id": 1001,
    "x": 50.0,
    "y": 50.0,
    "duration_ms": 500,
    "action_method": "background"
  }'

6. 滑动

curl -X POST http://127.0.0.1:12261/api/swipe \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "window_id": 1001,
    "main_window_id": 1001,
    "start_x": 50.0,
    "start_y": 80.0,
    "end_x": 50.0,
    "end_y": 20.0,
    "action_method": "background"
  }'

7. 滚动

curl -X POST http://127.0.0.1:12261/api/scroll \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "window_id": 1001,
    "main_window_id": 1001,
    "x": 50.0,
    "y": 50.0,
    "delta": -120,
    "action_method": "background"
  }'

8. 右键点击

curl -X POST http://127.0.0.1:12261/api/right_click \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "window_id": 1001,
    "main_window_id": 1001,
    "x": 50.0,
    "y": 50.0,
    "action_method": "background"
  }'

9. 鼠标悬浮

curl -X POST http://127.0.0.1:12261/api/hover \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "window_id": 1001,
    "main_window_id": 1001,
    "x": 50.0,
    "y": 50.0,
    "duration_ms": 500,
    "action_method": "hijack"
  }'

10. 输入文本

curl -X POST http://127.0.0.1:12261/api/input_text \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "window_id": 1001,
    "main_window_id": 1001,
    "x": 50.0,
    "y": 50.0,
    "text": "Hello World\n",
    "action_method": "hijack"
  }'

11. 按键

curl -X POST http://127.0.0.1:12261/api/press_key \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "window_id": 1001,
    "main_window_id": 1001,
    "key": "ctrl c",
    "action_method": "background"
  }'

12. 等待

curl -X POST http://127.0.0.1:12261/api/wait \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "window_id": 1001,
    "duration_ms": 1000,
    "random_range": 300
  }'

13. 批量执行

curl -X POST http://127.0.0.1:12261/api/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "window_id": 1001,
    "main_window_id": 1001,
    "instructions": [
      {"action": "click", "params": {"x": 50, "y": 35, "action_method": "background"}},
      {"action": "wait", "params": {"duration_ms": 200}},
      {"action": "input_text", "params": {"x": 50, "y": 35, "text": "hello", "action_method": "hijack"}},
      {"action": "wait", "params": {"duration_ms": 300}},
      {"action": "screenshot", "params": {"coordinate_type": "no"}}
    ]
  }'

14. 托管模式

curl -X POST http://127.0.0.1:12261/api/delegated \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "action": "enter"
  }'

退出托管模式：将 "action": "enter" 改为 "action": "exit"，或按快捷键 Ctrl+Alt+Z。

15. 拖拽

curl -X POST http://127.0.0.1:12261/api/drag \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "window_id": 1001,
    "main_window_id": 1001,
    "start_x": 30.0,
    "start_y": 50.0,
    "end_x": 70.0,
    "end_y": 50.0,
    "duration_ms": 500,
    "action_method": "background"
  }'

跨窗口拖拽（可选 target_window_id、target_main_window_id，end_x/end_y 相对于目标窗口）。

16. 鼠标移动

curl -X POST http://127.0.0.1:12261/api/mouse_move \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "window_id": 1001,
    "main_window_id": 1001,
    "delta_x": 200,
    "delta_y": 0,
    "duration_ms": 300,
    "action_method": "hijack"
  }'

17. 裁剪放大

curl -X POST http://127.0.0.1:12261/api/crop_zoom_screenshot \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "source_image_path": "D:/screenClaw/data/claude_code__session-123/screenshot_143215.png",
    "center_x": 55.0,
    "center_y": 65.0,
    "crop_width": 20,
    "crop_height": 20,
    "zoom_scale": 2.0
  }'

18. 滚动长截图

curl -X POST http://127.0.0.1:12261/api/scroll_screenshot \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_app_type": "claude_code",
    "session_id": "session-123",
    "window_id": 1001,
    "main_window_id": 1001,
    "max_scrolls": 20,
    "scroll_percent": 0.85,
    "scroll_wait": 1.0,
    "action_method": "hijack"
  }'

🎯 适用场景

自动化可视化测试

模拟人工操作可视化界面，沉淀测试用例，自动打开 F12 管理报错。

自动操作无网页版、无 API、无 CLI 的电脑软件

传统 ERP、OA 系统、专业工具软件等，只要能显示在屏幕上就能操作。

手机模拟器、手机投屏助手

对于大部分普通人，现阶段的 ADB、虚拟机、docker 等方案的自动化手机太麻烦，门槛太高。专门的 AI 手机又已停产。ScreenClaw 让你直接操作投屏/模拟器界面。

复杂任务自动化

专用的 UI 大模型通常参数量较低，难以理解复杂任务，难以尝试长时程执行任务。而 ScreenClaw 能让 SOTA 级别的多模态大模型（如 GPT-4V、Claude 3.5 Sonnet）自动化操作软件。

录制操作 → 沉淀模板 → 自动复用

用户手动操作一遍，录制每步截图和操作，AI 分析后沉淀为场景模板。下次 AI 自动执行相同任务，并支持坐标适配检测和模板优化。

与其他工具对比

场景	推荐工具	ScreenClaw 作用
浏览器自动化	Playwright、CDP、agent-browser	补充：模拟人工走查操作、获取控制台报错
传统 RPA	UiPath、Power Automate	更智能：AI 自动识别坐标，无需人工配置

💡 平台说明

执行方（运行 ScreenClaw 的机器）

推荐：Windows

✅ 支持无感截图（后台截图，不抢占前台）
✅ 支持无感鼠标和键盘操作（不影响用户使用）
✅ 拥有丰富的手机模拟器（如 MuMu、蓝叠、夜神等）
✅ 各大手机厂商的投屏软件（华为多屏协同、小米跨屏协作等）
✅ 能自动化大部分手机 APP

调用方（运行 AI 应用的机器）

支持：Windows / macOS / Linux

通过 HTTP API 调用，跨平台无限制。

部署模式

本地模式：执行方和调用方是同一台机器
局域网模式：不同机器，需在同一局域网内

🏗️ 技术架构

┌─────────────────────────────────────────────┐
│         外部 AI 应用                         │
│  (Claude Code / openclaw / 其他 Agent)         │
└──────────────────┬──────────────────────────┘
                   │ HTTP API
                   ▼
┌─────────────────────────────────────────────┐
│         Python 后端服务                      │
│       FastAPI :12261                         │
│  ┌───────┬────────┬────────┬────────┐      │
│  │ API层 │ Core层 │Platform│Service │      │
│  └───────┴────────┴────────┴────────┘      │
└──────────────────┬──────────────────────────┘
                   │ 子进程
┌──────────────────▼──────────────────────────┐
│         Tauri 桌面应用                       │
│  监控面板 │ 系统设置 │ 托盘图标               │
└─────────────────────────────────────────────┘

技术栈

层级	技术
前端	Tauri 2.0 + Vue 3 + TypeScript
后端	Python 3.11 + FastAPI + Uvicorn
窗口截图	pywin32 (PrintWindow)
桌面截图	mss
操作注入	pywin32 (PostMessage) / pyautogui (SendInput)
操作录制	Windows Hook (WH_MOUSE_LL / WH_KEYBOARD_LL)
网格绘制	Pillow (PIL)

📁 项目结构

screenClaw/
├── python/                   # Python 后端
│   ├── app/
│   │   ├── api/             # API 路由（窗口级、桌面级、录制）
│   │   ├── core/            # 核心业务逻辑（录制器等）
│   │   ├── platform/        # 平台适配层（截图、Hook、操作注入）
│   │   ├── models/          # 数据模型
│   │   ├── services/        # 服务层
│   │   ├── scripts/         # API 调用脚本
│   │   └── utils/           # 工具函数
│   └── main.py              # 入口文件
│
├── src-tauri/               # Tauri 后端（Rust）
│   └── src/
│       ├── commands.rs      # Tauri 命令
│       └── main.rs          # 入口
│
├── src/                     # Vue 前端
│   ├── components/          # 组件
│   ├── composables/         # 组合式函数
│   └── main.ts              # 入口
│
├── skills/                  # AI Skill
│   └── screenclaw/
│       ├── SKILL.md         # 技能定义（完整使用指南）
│       ├── scripts/         # 辅助脚本（coord_adapt、recording_windows 等）
│       └── references/      # API 文档和场景模板
│
├── record/                  # 录制产物（自动创建，已 gitignore）
│   └── record_YYYYMMDD_HHmmss/
│       ├── step.json        # 录制元数据 + 步骤
│       └── step_XXXX.png    # 步骤截图
│
└── data/                    # 数据目录
    └── config.json          # 配置文件（自动创建）

⚙️ 配置说明

ScreenClaw 服务配置

位于 data/config.json（应用初始化时自动创建）：

{
  "server": {
    "host": "0.0.0.0",
    "port": 12261,
    "token": "your-token-here",
    "local_ip": "192.168.x.x"
  },
  "recording": {
    "hotkey": "ctrl+alt+\\",
    "scroll_merge_interval_ms": 1000
  }
}

配置项	说明
`host`	绑定地址，0.0.0.0 允许局域网访问
`port`	HTTP 服务端口
`token`	API 认证令牌
`local_ip`	自动检测的局域网 IP
`recording.hotkey`	录制快捷键，默认 `Ctrl+Alt+\`
`recording.scroll_merge_interval_ms`	连续滚动合并间隔（毫秒）

AI Skill 连接配置

位于技能目录 {skill-dir}/references/config.md，用于 AI 应用连接 ScreenClaw 服务。

{
  "server": {
    "host": "0.0.0.0",
    "port": 12261,
    "token": "your-token-here",
    "local_ip": "192.168.x.x"
  }
}

🔒 安全说明

所有 API 请求需要 Token 认证
Hijack 模式操作会弹出确认窗口
可配置禁止访问的进程黑名单
仅允许局域网和本机访问

📖 更多文档

Skill 使用指南 — 完整的 API 文档和使用方法论

🗺️ 未来规划

🎯 提高识别率 — 通过技能优化和场景模板沉淀，提升多模态大模型的初次识别准确率
🔄 更多 RPA 动作 — 扩展支持的自动化操作类型，覆盖更多使用场景
🧠 坐标准确性提升 — 利用轻度 OCR 或无障碍树技术，进一步提高坐标准确性
📦 场景模板库 — 封装更多常用软件的场景模板，开箱即用

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

🤝 社区

QQ群：676692393

📄 许可证

MIT License

如果这个项目对你有帮助，请给一个 ⭐ Star 支持一下！

睇虾 — 让任何多模态大模型操作任何屏幕

Made with ❤️ by GinSing

ScreenClaw

About ScreenClaw

Platforms

Languages

Links

Need Help Installing ScreenClaw?

ScreenClaw

ScreenClaw

📖 什么是 ScreenClaw？

✨ 核心特性

🖥️ 后台无感操作

📐 百分比坐标网格

💻 操作电脑软件

📱 操作手机

🖥️ 桌面级截图+操作

🎬 录制+沉淀场景

💎 沉淀复用

🔒 安全可控

🎮 托管模式

🔍 辅助读坐标

🎛️ 控制工程（Harness Engineering）

🚀 快速开始

从源码运行（开发环境）

下载 Release 运行（生产环境）

启动服务

安装 Skill

📚 API 清单

窗口级 API

桌面级 API

录制 API

🔧 API 使用示例

通用请求头

1. 健康检查

2. 获取窗口列表

3. 截图（带坐标网格）

4. 点击

5. 长按

6. 滑动

7. 滚动

8. 右键点击

9. 鼠标悬浮

10. 输入文本

11. 按键

12. 等待

13. 批量执行

14. 托管模式

15. 拖拽

16. 鼠标移动

17. 裁剪放大

18. 滚动长截图

🎯 适用场景

自动化可视化测试

自动操作无网页版、无 API、无 CLI 的电脑软件

手机模拟器、手机投屏助手

复杂任务自动化

录制操作 → 沉淀模板 → 自动复用

与其他工具对比

💡 平台说明

执行方（运行 ScreenClaw 的机器）

调用方（运行 AI 应用的机器）

部署模式

🏗️ 技术架构

技术栈

📁 项目结构

⚙️ 配置说明

ScreenClaw 服务配置

AI Skill 连接配置

🔒 安全说明

📖 更多文档

🗺️ 未来规划

🤝 贡献指南

🤝 社区

📄 许可证