桌面控制技能

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

🎯 功能特性

鼠标控制

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

键盘控制

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

屏幕操作

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

窗口管理

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

安全功能

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

---

🚀 快速开始

安装

首先，安装所需依赖：

上网淘巴领天猫淘宝优惠券，一年省好几千。

pip install pyautogui pillow opencv-python pygetwindow

基础用法

from skills.desktop_control import DesktopController

# 初始化控制器
dc = DesktopController(failsafe=True)

# 鼠标操作
dc.move_mouse(500, 300)  # 移动到坐标位置
dc.click()  # 当前位置左键点击
dc.click(100, 200, button="right")  # 指定位置右键点击

# 键盘操作
dc.type_text("来自OpenClaw的问候！")
dc.hotkey("ctrl", "c")  # 复制
dc.press("enter")

# 屏幕操作
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(布尔值): 使用贝塞尔曲线实现自然移动

示例：

# 瞬时移动
dc.move_mouse(1000, 500)

# 平滑的1秒移动
dc.move_mouse(1000, 500, duration=1.0)

move_relative(x_offset, y_offset, duration=0)

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

参数：

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

示例：

# 向右移动100像素，向下移动50像素
dc.move_relative(100, 50, duration=0.3)

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

执行鼠标点击。

参数：

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

示例：

# 简单的左键单击
dc.click()

# 在特定位置双击
dc.click(500, 300, clicks=2)

# 右键单击
dc.click(button='right')

拖动（起始X坐标，起始Y坐标，结束X坐标，结束Y坐标，持续时间=0.5，按钮='左键'）

拖放操作。

参数：

• 起始X坐标，起始Y坐标（整数）：起始坐标
• 结束X坐标，结束Y坐标（整数）：结束坐标
• 持续时间（浮点数）：拖动持续时间
• 按钮（字符串）：使用的鼠标按键

示例：

# 将文件从桌面拖动到文件夹
dc.drag(100, 100, 500, 500, duration=1.0)

滚动（点击次数，方向='垂直'，X坐标=无，Y坐标=无）

滚动鼠标滚轮。

参数：

• 点击次数（整数）：滚动量（正数 = 向上/向左，负数 = 向下/向右）
• 方向（字符串）：'垂直' 或 '水平'
• X坐标，Y坐标（整数，可选）：滚动操作发生的位置

示例：

# 向下滚动5次
dc.scroll(-5)

# 向上滚动10次
dc.scroll(10)

# 水平滚动
dc.scroll(5, direction='horizontal')

获取鼠标位置()

获取当前鼠标坐标。

返回值： (x, y)元组

示例：

x, y = dc.get_mouse_position()
print(f"鼠标位置：{x}, {y}")

---

键盘功能

type_text(text, interval=0, wpm=None)

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

参数：

• text（字符串）：要输入的文本
• interval（浮点数）：按键之间的延迟（0 = 即时）
• wpm（整数，可选）：每分钟单词数（覆盖 interval 参数）

示例：

# 即时输入
dc.type_text("Hello World")

# 以 60 WPM 的速度模拟人类输入
dc.type_text("Hello World", wpm=60)

# 缓慢输入，按键间隔 0.1 秒
dc.type_text("Hello World", interval=0.1)

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

按下并释放一个按键。

参数：

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

示例：

# 按下 Enter 键
dc.press('enter')

# 按下 Space 键 3 次
dc.press('space', presses=3)

# 按下 Down 方向键
dc.press('down')

热键(*键位, 间隔=0.05)

执行键盘快捷键。

参数:

• *键位(str): 需要同时按下的键
• 间隔(float): 按键之间的延迟

示例:

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

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

# 打开运行对话框 (Win+R)
dc.hotkey('win', 'r')

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

# 全选 (Ctrl+A)
dc.hotkey('ctrl', 'a')

键位按下(键位)/键位抬起(键位)

手动控制按键状态。

示例:

# 按住 Shift 键
dc.key_down('shift')
dc.type_text("hello")  # 输入 "HELLO"
dc.key_up('shift')

# 按住 Ctrl 键并点击 (用于多选)
dc.key_down('ctrl')
dc.click(100, 100)
dc.click(200, 100)
dc.key_up('ctrl')

---

屏幕功能

屏幕截图(区域=无, 文件名=无)

捕获屏幕或区域。

参数:

• 区域(元组, 可选): (左, 上, 宽, 高) 用于部分捕获
• 文件名(str, 可选): 保存图像的路径

返回:PIL 图像对象

示例:

# 全屏
img = dc.screenshot()

# 保存到文件
dc.screenshot(filename="screenshot.png")

# 捕获特定区域
img = dc.screenshot(region=(100, 100, 500, 300))

get_pixel_color(x, y)

获取指定坐标处像素的颜色。

返回值：RGB 元组(r, g, b)

示例：

r, g, b = dc.get_pixel_color(500, 300)
print(f"坐标 (500, 300) 处的颜色：RGB({r}, {g}, {b})")

find_on_screen(image_path, confidence=0.8)

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

参数：

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

返回值： (x, y, width, height)或 None

示例：

# 在屏幕上查找按钮
location = dc.find_on_screen("button.png")
if location:
    x, y, w, h = location
    # 点击找到的图像的中心
    dc.click(x + w//2, y + h//2)

get_screen_size()

获取屏幕分辨率。

返回值： (width, height)元组

示例：

width, height = dc.get_screen_size()
print(f"屏幕分辨率：{width}x{height}")

---

窗口函数

get_all_windows()

列出所有打开的窗口。

返回：窗口标题列表

示例：

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

activate_window(title_substring)

根据标题将窗口置于前台。

参数：

• title_substring(str): 用于匹配窗口标题的部分字符串

示例：

# 激活 Chrome
dc.activate_window("Chrome")

# 激活 VS Code
dc.activate_window("Visual Studio Code")

get_active_window()

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

返回：窗口标题 (str)

示例：

active = dc.get_active_window()
print(f"活动窗口：{active}")

---

剪贴板功能

copy_to_clipboard(text)

复制文本到剪贴板。

示例：

dc.copy_to_clipboard("来自 OpenClaw 的问候！")

get_from_clipboard()

从剪贴板获取文本。

返回：str

示例：

text = dc.get_from_clipboard()
print(f"剪贴板内容: {text}")

---

⌨️ 键名参考

字母键

'a'至'z'

数字键

'0'至'9'

功能键

'f1'至'f24'

特殊键

• 'enter'/'return'
• 'esc'/'escape'
• 'space'/'spacebar'
• 'tab'
• 'backspace'
• 'delete'/'删除'
• '插入'
• '起始'
• '结束'
• '向上翻页'/'向上翻页'
• '向下翻页'/'向下翻页'

方向键

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

修饰键

• 'ctrl'/'控制'
• '上档'
• '换档'
• '窗口'/'左窗口'/'右窗口'
• 'cmd'/'命令'（Mac）

锁定键

• '大写锁定键'
• '数字锁定键'
• '滚动锁定键'

标点符号

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

---

🛡️ 安全特性

故障安全模式

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

# 启用故障安全模式（默认启用）
dc = DesktopController(failsafe=True)

暂停控制

# 暂停所有自动化操作2秒钟
dc.pause(2.0)

# 检查自动化操作是否可以安全继续
if dc.is_safe():
    dc.click(500, 500)

审批模式

在执行操作前需要用户确认：

dc = DesktopController(require_approval=True)

# 这将请求确认
dc.click(500, 500)  # 提示："允许在 (500, 500) 位置点击吗？ [y/n]"

---

🎨 高级示例

示例 1：自动填写表单

dc = DesktopController()

# 点击姓名字段
dc.click(300, 200)
dc.type_text("John Doe", wpm=80)

# 按Tab键切换到下一个字段
dc.press('tab')
dc.type_text("john@example.com", wpm=80)

# 按Tab键切换到密码字段
dc.press('tab')
dc.type_text("SecurePassword123", wpm=60)

# 提交表单
dc.press('enter')

示例 2：截取屏幕区域并保存

# 捕获特定区域
region = (100, 100, 800, 600)  # 左、上、宽、高
img = dc.screenshot(region=region)

# 使用时间戳保存
import datetime
timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
img.save(f"capture_{timestamp}.png")

示例 3：多文件选择

# 按住Ctrl并点击多个文件
dc.key_down('ctrl')
dc.click(100, 200)  # 第一个文件
dc.click(100, 250)  # 第二个文件
dc.click(100, 300)  # 第三个文件
dc.key_up('ctrl')

# 复制选中的文件
dc.hotkey('ctrl', 'c')

示例4：窗口自动化

# 激活计算器
dc.activate_window("Calculator")
time.sleep(0.5)

# 输入计算式
dc.type_text("5+3=", interval=0.2)
time.sleep(0.5)

# 对结果进行截图
dc.screenshot(filename="calculation_result.png")

示例5：拖放文件

# 将文件从源位置拖放到目标位置
dc.drag(
    start_x=200, start_y=300,  # 文件位置
    end_x=800, end_y=500,       # 文件夹位置
    duration=1.0                 # 平滑的1秒拖动
)

---

⚡ 性能提示

1. 为了速度，使用即时移动：duration=0使用批量操作
2. 而非单个调用缓存屏幕位置
3. 而非重新计算禁用安全措施
4. 以获得最大性能（谨慎使用）使用快捷键
5. 而非菜单导航⚠️ 重要注意事项

---

屏幕坐标

• 从左上角的 (0, 0) 开始多显示器设置中
• 副显示器可能具有负坐标Windows DPI缩放
• 可能影响坐标精度安全角位于：
• (0,0), (width-1, 0), (0, height-1), (width-1, height-1)某些应用程序
• 可能阻止模拟输入（如游戏、安全应用）may block simulated input (games, secure apps)

---

🔧 故障排除

鼠标未移动到正确位置

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

键盘输入无效

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

安全防护意外触发

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

权限错误

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

---

📦 依赖项

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

全部安装：

pip install pyautogui pillow opencv-python pygetwindow

---

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

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