pyautogui

核心功能

OpenClaw PyAutoGUI 是一套基于 Python 的跨平台自动化工具集，整合了 PyAutoGUI、OpenCV 与 RapidOCR，提供从鼠标键盘控制到图像识别定位的完整自动化能力。

主要能力模块

1. 键鼠自动化控制

• 鼠标：移动、点击、拖拽、滚动，支持精确坐标定位与多显示器环境
• 键盘：单键按压、组合热键、文本输入，模拟真实打字间隔
• 剪贴板操作：copy/paste/copy_paste 三种模式，长文本输入效率显著优于逐字模拟

2. 屏幕与截图操作

• 全屏/区域截图，支持 PNG/JPG/BMP 等格式
• 实时获取鼠标坐标与屏幕尺寸
• 屏幕叠加标记（临时高亮）与图像绘制标记（持久化标注）

3. 图像处理与定位

• 图像元数据查询、裁剪、格式转换
• 模板匹配：基于 OpenCV 的像素级图像查找，精度高、速度快
• OCR 文字定位：基于 RapidOCR 的屏幕文字识别，支持置信度过滤
• 自动点击与结果标记，形成"查找-确认-执行"闭环

4. 文件清理

• 按时间/大小筛选清理截图与临时文件
• 自动清理策略防止磁盘空间膨胀

显著优势

• 本地化执行：纯本地计算，无 API 调用成本，响应毫秒级
• 双模式定位：模板匹配（固定UI元素）+ OCR（动态文字），覆盖绝大多数场景
• 调试友好：屏幕/图像双重标记系统，坐标校准可视化
• 跨平台：Windows/Linux/macOS 全支持（Linux需X11，macOS需授权）

局限性与风险

| 方面 | 说明 |

|------|------|

| **系统依赖** | Linux Wayland 不支持；macOS 需手动授予辅助功能权限 |

| **OCR 精度** | 受字体、背景复杂度、分辨率影响，低置信度场景需人工复核 |

| **安全性** | 具备实际控制鼠标键盘的能力，需警惕恶意脚本；PyAutoGUI 自带 failsafe（鼠标移至左上角触发中断） |

| **多显示器** | 截图默认仅主屏幕，多屏场景需额外处理 |

| **坐标硬编码** | 分辨率变更会导致坐标失效，建议配合图像定位动态获取 |

适用人群

• 自动化测试工程师（UI 回归测试、流程自动化）
• 数据录入/重复性办公场景用户
• RPA（机器人流程自动化）开发者
• 需要批量截图标注与图像分析的技术人员

典型工作流

# 1. 截图并查找目标
python3 scripts/keyboard_mouse.py screenshot screen.png
python3 scripts/image_finder.py image send_button.png --mark

# 2. 可视化确认坐标
python3 scripts/draw_overlay.py marker target 3788 2080 --duration 3

# 3. 执行点击
python3 scripts/keyboard_mouse.py mouse_click_at 3788 2080 left

# 4. 清理临时文件
python3 scripts/cleanup.py clean . --days 1 --execute

安全建议

• 生产环境使用建议添加操作延迟与确认机制
• 敏感场景避免 hardcode 坐标，优先使用图像/OCR 定位
• 定期清理 screenshot 目录防止敏感信息泄露

核心用法

openclaw-pyautogui 是一款基于 PyAutoGUI 的跨平台 UI 自动化技能，覆盖 Windows、Linux 和 macOS 三大操作系统。其核心功能分为六大模块：

1. 键鼠自动化：支持鼠标移动、点击、拖拽、滚动，以及键盘按键、组合键、文本输入。提供 copy_paste 模式绕过逐字输入，提升长文本输入效率。

2. 屏幕操作：支持全屏截图、区域截图，获取屏幕尺寸和鼠标实时坐标。

3. 图像处理：基于 Pillow 实现图片元信息提取（尺寸、格式、文件大小）和精准裁剪。

4. 视觉辅助：提供屏幕临时标记（overlay）和图片持久标注（draw_on_image），支持十字准星、圆形、箭头等多种标记样式，便于坐标校准和调试。

5. 智能定位：集成 OpenCV 模板匹配和 RapidOCR 文字识别，实现"以图找图"和"以文找图"的像素级定位，无需硬编码坐标。

6. 文件清理：内置 cleanup 工具，支持按时间、大小自动清理生成的截图和临时文件。

显著优点

• 跨平台兼容：一套代码覆盖主流桌面系统，降低多环境部署成本。
• 零 API 成本：纯本地计算，无外部服务依赖（除 OCR 模型首次下载）。
• 像素级精度：模板匹配可达 98%+ 相似度，OCR 识别支持中文字符。
• 调试友好：overlay 标记和分步保存机制让自动化流程可视可回溯。
• 安全设计：PyAutoGUI failsafe（鼠标移至左上角停止）、cleanup 默认预览模式，降低误操作风险。

潜在缺点与局限性

• Linux 限制：需 X11 环境，Wayland 不支持；macOS 需手动授权辅助功能权限。
• OCR 依赖体积：RapidOCR 模型约 15MB，首次使用需下载。
• 分辨率敏感：模板匹配依赖固定分辨率，DPI 缩放或窗口大小变化可能导致失效。
• 非后台执行：操作依赖当前焦点窗口，被遮挡或切换会导致失败。
• 无原生等待机制：需手动添加延迟处理异步加载场景。

适合的目标群体

• 自动化测试工程师：快速搭建端到端 UI 测试流程。
• RPA 开发者：替代人工重复性桌面操作。
• 数据标注人员：批量截图、裁剪、标注工具链。
• 效率极客：个人工作流自动化（表单填写、文件整理）。

使用风险

1. 系统级操作风险：键鼠控制、剪贴板访问、屏幕截图属敏感权限，需确保运行环境可信。
2. 供应链依赖：PyAutoGUI、OpenCV 等为核心依赖，建议锁定版本并定期审计 CVE。
3. 误操作可能：--execute 参数启用真实删除，生产环境建议先验证预览输出。
4. 隐私合规：截图可能含敏感信息，需规范存储路径和定期清理。