桌面控制技能

OpenClaw 最先进的桌面自动化技能。提供像素级精度的鼠标控制、闪电般的键盘输入、屏幕捕获、窗口管理和剪贴板操作。

🎯 功能

鼠标控制

• ✅绝对定位- 移动到精确坐标
• ✅相对移动- 从当前位置移动
• ✅平滑移动- 自然、拟人化的鼠标轨迹
• ✅点击类型- 左键、右键、中键、双击、三击
• ✅拖放- 从 A 点拖拽到 B 点
• ✅滚动- 垂直和水平滚动
• ✅位置追踪- 获取当前鼠标坐标

键盘控制

• ✅文本输入- 快速、准确的文本输入
• ✅热键- 执行键盘快捷键（Ctrl+C、Win+R 等）
• ✅特殊键- 回车、Tab、Esc、方向键、功能键
• ✅组合键- 多键同时按下的组合
• ✅按住与释放- 手动控制按键状态
• ✅输入速度- 可配置的每分钟字数（从即时到类人速度）

屏幕操作

• ✅截图- 捕获整个屏幕或指定区域
• ✅图像识别- 在屏幕上查找元素（通过OpenCV）
• ✅颜色检测- 获取坐标处的像素颜色
• ✅多显示器支持- 支持多个显示设备

窗口管理

• ✅窗口列表- 获取所有打开的窗口
• ✅激活窗口- 将窗口置于前台
• ✅窗口信息- 获取位置、尺寸、标题
• ✅最小化/最大化- 控制窗口状态

安全功能

• ✅故障安全机制- 移动鼠标到角落以中止
• ✅暂停控制- 紧急停止机制
• ✅审批模式- 操作需要确认
• ✅边界检查- 防止屏幕外操作
• ✅日志记录- 追踪所有自动化操作

---

🚀 快速开始

安装

首先，安装所需依赖：

pip install pyautogui pillow opencv-python pygetwindow

基础用法

from skills.desktop_control import DesktopController

# Initialize controller
dc = DesktopController(failsafe=True)

# Mouse operations
dc.move_mouse(500, 300)  # Move to coordinates
dc.click()  # Left click at current position
dc.click(100, 200, button="right")  # Right click at position

# Keyboard operations
dc.type_text("Hello from OpenClaw!")
dc.hotkey("ctrl", "c")  # Copy
dc.press("enter")

# Screen operations
screenshot = dc.screenshot()
position = dc.get_mouse_position()

---

📋 完整 API 参考

鼠标功能

move_mouse(x, y, duration=0, smooth=True)

将鼠标移动到绝对屏幕坐标。

参数：

• x（整数）：X坐标（距左侧的像素数）
• y（整数）：Y坐标（距顶部的像素数）
• duration（浮点数）：移动时间，单位为秒（0 = 瞬间移动，0.5 = 平滑移动）
• smooth（布尔值）：是否使用贝塞尔曲线实现自然移动

示例：

# Instant movement
dc.move_mouse(1000, 500)

# Smooth 1-second movement
dc.move_mouse(1000, 500, duration=1.0)

move_relative(x_offset, y_offset, duration=0)

相对于当前位置移动鼠标。

参数：

• x_offset（整数）：水平移动的像素数（正数 = 向右）
• y_offset（整数）：垂直移动的像素数（正数 = 向下）
• duration（浮点数）：移动时间，单位为秒

示例：

# Move 100px right, 50px down
dc.move_relative(100, 50, duration=0.3)

click(x=None, y=None, button='left', clicks=1, interval=0.1)

执行鼠标点击操作。

参数：

• x, y（整数，可选）：点击坐标（None = 当前位置）
• 按钮（字符串）：'left'（左键）、'right'（右键）、'middle'（中键）
• 点击次数（整数）：点击次数（1 = 单击，2 = 双击）
• 间隔（浮点数）：多次点击之间的延迟

示例：

# Simple left click
dc.click()

# Double-click at specific position
dc.click(500, 300, clicks=2)

# Right-click
dc.click(button='right')

drag(start_x, start_y, end_x, end_y, duration=0.5, button='left')

拖放操作。

参数：

• start_x, start_y（整数）：起始坐标
• end_x, end_y（整数）：结束坐标
• 持续时间（浮点数）：拖动持续时间
• 按钮（字符串）：使用的鼠标按钮

示例：

# Drag file from desktop to folder
dc.drag(100, 100, 500, 500, duration=1.0)

scroll(clicks, direction='vertical', x=None, y=None)

滚动鼠标滚轮。

参数：

• 点击次数(整数): 滚动量（正数 = 向上/向左，负数 = 向下/向右）
• 方向(字符串): '垂直' 或 '水平'
• x, y(整数, 可选): 滚动位置

示例:

# Scroll down 5 clicks
dc.scroll(-5)

# Scroll up 10 clicks
dc.scroll(10)

# Horizontal scroll
dc.scroll(5, direction='horizontal')

获取鼠标位置()

获取当前鼠标坐标。

返回值: (x, y)元组

示例:

x, y = dc.get_mouse_position()
print(f"Mouse is at: {x}, {y}")

---

键盘功能

输入文本(文本, 间隔=0, 每分钟字数=无)

以可配置的速度输入文本。

参数:

• 文本(字符串): 要输入的文本
• 间隔(浮点数): 按键之间的延迟（0 = 即时）
• 每分钟字数(整数, 可选): 每分钟单词数（覆盖间隔参数）

示例:

# Instant typing
dc.type_text("Hello World")

# Human-like typing at 60 WPM
dc.type_text("Hello World", wpm=60)

# Slow typing with 0.1s between keys
dc.type_text("Hello World", interval=0.1)

press(key, presses=1, interval=0.1)

按下并释放一个按键。

参数：

• key（字符串）：按键名称（参见按键名称部分）
• presses（整数）：按下的次数
• interval（浮点数）：按键之间的延迟

示例：

# Press Enter
dc.press('enter')

# Press Space 3 times
dc.press('space', presses=3)

# Press Down arrow
dc.press('down')

hotkey(*keys, interval=0.05)

执行键盘快捷键。

参数：

• *keys（字符串）：需要同时按下的按键
• interval（浮点数）：按键之间的延迟

示例：

# Copy (Ctrl+C)
dc.hotkey('ctrl', 'c')

# Paste (Ctrl+V)
dc.hotkey('ctrl', 'v')

# Open Run dialog (Win+R)
dc.hotkey('win', 'r')

# Save (Ctrl+S)
dc.hotkey('ctrl', 's')

# Select All (Ctrl+A)
dc.hotkey('ctrl', 'a')

key_down(key)/key_up(key)

手动控制按键状态。

示例：

# Hold Shift
dc.key_down('shift')
dc.type_text("hello")  # Types "HELLO"
dc.key_up('shift')

# Hold Ctrl and click (for multi-select)
dc.key_down('ctrl')
dc.click(100, 100)
dc.click(200, 100)
dc.key_up('ctrl')

---

屏幕函数

截图(区域=None, 文件名=None)

捕获屏幕或区域。

参数：

• 区域（元组，可选）：用于部分截图的 (左, 上, 宽, 高)
• 文件名（字符串，可选）：保存图像的路径

返回：PIL 图像对象

示例：

# Full screen
img = dc.screenshot()

# Save to file
dc.screenshot(filename="screenshot.png")

# Capture specific region
img = dc.screenshot(region=(100, 100, 500, 300))

获取像素颜色(x, y)

获取坐标处像素的颜色。

返回：RGB 元组(红, 绿, 蓝)

示例：

r, g, b = dc.get_pixel_color(500, 300)
print(f"Color at (500, 300): RGB({r}, {g}, {b})")

在屏幕上查找(图像路径, 置信度=0.8)

在屏幕上查找图像（需要 OpenCV）。

参数：

• 图像路径（字符串）：模板图像的路径
• 置信度（浮点数）：匹配阈值（0-1）

返回值： (x坐标, y坐标, 宽度, 高度)或 None

示例：

# Find button on screen
location = dc.find_on_screen("button.png")
if location:
    x, y, w, h = location
    # Click center of found image
    dc.click(x + w//2, y + h//2)

get_screen_size()

获取屏幕分辨率。

返回值： (宽度, 高度)元组

示例：

width, height = dc.get_screen_size()
print(f"Screen: {width}x{height}")

---

窗口函数

get_all_windows()

列出所有打开的窗口。

返回值：窗口标题列表

示例：

windows = dc.get_all_windows()
for title in windows:
    print(f"Window: {title}")

activate_window(title_substring)

通过标题将窗口置于前台。

参数：

• title_substring（字符串类型）：用于匹配的部分窗口标题

示例：

# Activate Chrome
dc.activate_window("Chrome")

# Activate VS Code
dc.activate_window("Visual Studio Code")

get_active_window()

获取当前获得焦点的窗口。

返回值：窗口标题 (字符串)

示例：

active = dc.get_active_window()
print(f"Active window: {active}")

---

剪贴板功能

copy_to_clipboard(text)

将文本复制到剪贴板。

示例：

dc.copy_to_clipboard("Hello from OpenClaw!")

get_from_clipboard()

从剪贴板获取文本。

返回值：字符串

示例：

text = dc.get_from_clipboard()
print(f"Clipboard: {text}")

---

⌨️ 按键名称参考

字母键

'a'至'z'

数字键

'0'至'9'

功能键

'f1'至'f24'

特殊键

• 'enter'/'返回'
• '退出'/'退出'
• '空格'/'空格键'
• '制表符'
• '退格'
• '删除'/'删除'
• '插入'
• '首页'
• '结尾'
• '上翻页'/'上翻页'
• '下翻页'/'下翻页'

方向键

• '上'/'下'/'左'/'右'

修饰键

• 'ctrl'/'control'
• 'shift'
• 'alt'
• 'win'/'winleft'/'winright'
• 'cmd'/'command'(Mac)

锁定键

• 'capslock'
• 'numlock'
• 'scrolllock'

标点符号

• '.'/','/'?'/'!'/';'/':'
• '['/']'/'{'/'}'
• '('/')'
• '+'/'-'/'*'/'/'/'='

---

🛡️ 安全功能

故障安全模式

将鼠标移至屏幕任意角落以中止所有自动化操作。

# Enable failsafe (enabled by default)
dc = DesktopController(failsafe=True)

暂停控制

# Pause all automation for 2 seconds
dc.pause(2.0)

# Check if automation is safe to proceed
if dc.is_safe():
    dc.click(500, 500)

审批模式

操作前需用户确认：

dc = DesktopController(require_approval=True)

# This will ask for confirmation
dc.click(500, 500)  # Prompt: "Allow click at (500, 500)? [y/n]"

---

🎨 高级示例

示例1：自动表单填写

dc = DesktopController()

# Click name field
dc.click(300, 200)
dc.type_text("John Doe", wpm=80)

# Tab to next field
dc.press('tab')
dc.type_text("john@example.com", wpm=80)

# Tab to password
dc.press('tab')
dc.type_text("SecurePassword123", wpm=60)

# Submit form
dc.press('enter')

示例2：截图区域并保存

# Capture specific area
region = (100, 100, 800, 600)  # left, top, width, height
img = dc.screenshot(region=region)

# Save with timestamp
import datetime
timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
img.save(f"capture_{timestamp}.png")

示例3：多文件选择

# Hold Ctrl and click multiple files
dc.key_down('ctrl')
dc.click(100, 200)  # First file
dc.click(100, 250)  # Second file
dc.click(100, 300)  # Third file
dc.key_up('ctrl')

# Copy selected files
dc.hotkey('ctrl', 'c')

示例4：窗口自动化

# Activate Calculator
dc.activate_window("Calculator")
time.sleep(0.5)

# Type calculation
dc.type_text("5+3=", interval=0.2)
time.sleep(0.5)

# Take screenshot of result
dc.screenshot(filename="calculation_result.png")

示例5：拖放文件

# Drag file from source to destination
dc.drag(
    start_x=200, start_y=300,  # File location
    end_x=800, end_y=500,       # Folder location
    duration=1.0                 # Smooth 1-second drag
)

---

⚡ 性能提示

1. 使用即时移动以提升速度：duration=0
2. 批量操作代替单个调用
3. 缓存屏幕位置避免重复计算
4. 禁用安全防护实现最高性能（谨慎使用）
5. 使用快捷键替代菜单导航

---

⚠️ 重要说明

• 屏幕坐标从左上角的 (0, 0) 开始
• 多显示器设置副显示器可能具有负坐标
• Windows DPI 缩放可能影响坐标精度
• 安全边界角点为: (0,0), (宽度-1, 0), (0, 高度-1), (宽度-1, 高度-1)
• 某些应用程序可能会阻止模拟输入（游戏、安全应用）

---

🔧 故障排除

鼠标未移动到正确位置

• 检查 DPI 缩放设置
• 验证屏幕分辨率是否符合预期
• 使用get_screen_size()来确认尺寸

键盘输入不工作

• 确保目标应用程序获得焦点
• 某些应用需要管理员权限
• 尝试增加interval以提高可靠性

故障保护意外触发

• 增加屏幕边框容差
• 正常使用时将鼠标远离屏幕角落
• 如需可禁用：DesktopController(failsafe=False)

权限错误

• 部分操作需要以管理员权限运行Python
• 某些安全应用会阻止自动化操作

---

📦 依赖项

• PyAutoGUI- 核心自动化引擎
• Pillow- 图像处理
• OpenCV（可选）- 图像识别
• PyGetWindow- 窗口管理

安装全部：

pip install pyautogui pillow opencv-python pygetwindow

---

专为OpenClaw打造- 终极桌面自动化伴侣 🦞

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。