ScreenClaw

📖 什么是 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 运行（生产环境）

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

启动服务

1. 应用启动后，点击"启动服务"按钮
2. 查看连接信息：
   • 本机访问：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

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

录制 API

🔧 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 的机器）

推荐：Windows

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

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

支持：Windows / macOS / Linux

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

部署模式

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

🏗️ 技术架构

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

技术栈

📁 项目结构

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
  }
}

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