ScreenClaw

📖 什么是 ScreenClaw？

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

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

AI 应用通过 HTTP API 可以：

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

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

✨ 核心特性

🖥️ 后台无感操作

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

📐 百分比坐标网格

• 让任何多模态大模型有了精确定位能力，且识别速度更快
• 基于百分比（0-100）的坐标系统，只要窗口比例不变，适用于任何大小的窗口
• 不同分辨率、不同窗口尺寸都能复用相同的坐标

💻 操作电脑软件

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

📱 操作手机

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

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

💎 沉淀复用

• 支持将成功的任务流程沉淀为场景模板，下次直接复用
• 接入 OpenClaw 等个人 AI 助手后，个性化数据在本地留存
• AI 会越来越懂你，效率越来越高

🔒 安全可控

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

🚀 快速开始

一行部署

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

启动服务

1. 双击启动 ScreenClaw 应用
2. 点击"启动服务"按钮
3. 查看连接信息：
   • 本机访问：http://127.0.0.1:12261
   • 局域网访问：http://192.168.x.x:12261
   • API 文档：http://127.0.0.1:12261/docs

安装 Skill

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

npx skills add https://github.com/GinSing1226/ScreenClaw

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

📚 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,
    "coordinate_type": "grid",
    "grid": {
      "density": 5.0,
      "opacity": 50,
      "color": "#00FF00"
    },
    "coordinate": {
      "number_density": 2,
      "number_decimal": 0,
      "number_size": 8,
      "number_color": "#00FF00",
      "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,
    "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,
    "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,
    "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,
    "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,
    "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,
    "x": 50.0,
    "y": 50.0,
    "text": "Hello World\n",
    "newline_key": "shift enter",
    "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,
    "key": "ctrl c",
    "x": 55.0,
    "y": 65.0,
    "duration_ms": 0,
    "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
  }'

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"}}
    ]
  }'

🎯 适用场景

自动化可视化测试

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

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

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

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

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

复杂任务自动化

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

与其他工具对比

💡 平台说明

执行方（运行 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/        # 平台适配层
│   │   ├── models/          # 数据模型
│   │   ├── services/        # 服务层
│   │   └── 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         # 技能定义（完整使用指南）
│       └── references/      # API 文档和场景模板
│
└── data/                    # 数据目录
    └── config.json          # 配置文件（自动创建）

⚙️ 配置说明

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

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

🔒 安全说明

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

📖 更多文档

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

🗺️ 未来规划

• 🎯 提高识别率 — 通过技能优化和场景模板沉淀，提升多模态大模型的初次识别准确率
• 🔄 更多 RPA 动作 — 扩展支持的自动化操作类型，覆盖更多使用场景
• 📦 场景模板库 — 封装更多常用软件的场景模板，开箱即用

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License