ClawHub

OpenClaw Desktop Control

Automation

Remote desktop control and automation. Capture screenshots, control mouse and keyboard, automate UI interactions. Supports VNC, RDP, and local desktop environments.

Install

openclaw skills install oc-desktop-control

Desktop Control - 远程桌面控制

基于 Bytebot Computer Use 模式实现的桌面自动化控制工具。

Version: 1.0.0
Features: 截图、鼠标控制、键盘输入、应用管理、文件操作

Purpose

让 OpenClaw 能够:

  • 查看远程/本地桌面状态 (截图)
  • 控制鼠标和键盘进行 UI 交互
  • 自动化执行桌面任务
  • 与虚拟机、容器、远程服务器交互

Quick Start

1. 连接桌面环境

# 连接到 VNC 桌面
python3 scripts/main.py connect --host localhost --port 5900 --password secret

# 连接到本地桌面 (Linux)
python3 scripts/main.py connect --local

2. 基本操作

# 截图
python3 scripts/main.py screenshot --output /tmp/screen.png

# 移动鼠标
python3 scripts/main.py mouse move --x 500 --y 300

# 点击
python3 scripts/main.py mouse click --x 500 --y 300 --button left

# 输入文本
python3 scripts/main.py type "Hello World"

# 按键
python3 scripts/main.py key press --keys ctrl,c

3. 自动化脚本

# 执行脚本
python3 scripts/main.py script examples/open_browser.txt

Installation

Requirements

# Ubuntu/Debian
sudo apt-get install python3-pil python3-xlib scrot

# macOS
brew install pillow

# Python dependencies
pip3 install -r requirements.txt

Configuration

# 设置环境变量
export DESKTOP_HOST=localhost
export DESKTOP_PORT=5900
export DESKTOP_PASSWORD=secret
export DESKTOP_TYPE=vnc  # vnc, rdp, local

Commands

screenshot - 截图

# 基本截图
python3 scripts/main.py screenshot

# 保存到文件
python3 scripts/main.py screenshot --output /path/to/save.png

# 指定区域
python3 scripts/main.py screenshot --region "100,100,800,600"

# 返回 base64 (用于 AI 分析)
python3 scripts/main.py screenshot --base64

mouse - 鼠标控制

# 移动
python3 scripts/main.py mouse move --x 500 --y 300

# 点击
python3 scripts/main.py mouse click --x 500 --y 300
python3 scripts/main.py mouse click --button right  # 右键
python3 scripts/main.py mouse click --clicks 2      # 双击

# 拖拽
python3 scripts/main.py mouse drag --from "100,100" --to "500,500"

# 滚动
python3 scripts/main.py mouse scroll --direction down --amount 3

# 获取位置
python3 scripts/main.py mouse position

keyboard - 键盘控制

# 输入文本
python3 scripts/main.py keyboard type "Hello World"

# 按键 (支持组合键)
python3 scripts/main.py keyboard press --keys ctrl,alt,t  # 打开终端
python3 scripts/main.py keyboard press --keys ctrl,c      # 复制
python3 scripts/main.py keyboard press --keys ctrl,v      # 粘贴

# 按住/释放
python3 scripts/main.py keyboard hold --key shift
python3 scripts/main.py keyboard release --key shift

app - 应用管理

# 打开应用
python3 scripts/main.py app open --name firefox
python3 scripts/main.py app open --name terminal
python3 scripts/main.py app open --name vscode

# 关闭应用
python3 scripts/main.py app close --name firefox

# 切换到桌面
python3 scripts/main.py app desktop

file - 文件操作

# 读取文件 (从桌面环境)
python3 scripts/main.py file read --path /home/user/document.txt

# 写入文件
python3 scripts/main.py file write --path /home/user/hello.txt --content "Hello"

# 截图并 OCR 识别文字
python3 scripts/main.py file ocr --region "100,100,400,200"

automation - 自动化

# 执行脚本文件
python3 scripts/main.py automation run --script script.txt

# 录制操作
python3 scripts/main.py automation record --output script.txt

# 等待元素出现 (基于图像匹配)
python3 scripts/main.py automation wait --template button.png --timeout 10

Script Format

创建自动化脚本文件 (script.txt):

# 注释以 # 开头
screenshot
wait 1000
mouse move 500 300
mouse click
wait 500
type "Hello World"
key press return
wait 1000
screenshot

API Usage

作为 Python 库使用:

from desktop_controller import DesktopController

# 初始化
controller = DesktopController(host="localhost", port=5900)

# 截图
screenshot = controller.screenshot()

# 鼠标操作
controller.mouse_move(500, 300)
controller.mouse_click(500, 300)

# 键盘操作
controller.type_text("Hello World")
controller.key_press(["ctrl", "c"])

# 关闭
controller.disconnect()

Integration with OpenClaw

在 Skill 中调用:

import subprocess

def analyze_desktop():
    # 截图
    result = subprocess.run(
        ["python3", "skills/desktop-control/scripts/main.py", 
         "screenshot", "--base64"],
        capture_output=True, text=True
    )
    screenshot_base64 = result.stdout.strip()
    
    # 发送给 AI 分析
    return f"![Desktop](data:image/png;base64,{screenshot_base64})"

def click_element(x, y):
    subprocess.run([
        "python3", "skills/desktop-control/scripts/main.py",
        "mouse", "click", "--x", str(x), "--y", str(y)
    ])

Architecture

desktop-control/
├── scripts/
│   └── main.py              # CLI 入口
├── lib/
│   ├── __init__.py
│   ├── desktop_controller.py # 核心控制器
│   ├── vnc_client.py        # VNC 协议实现
│   ├── rdp_client.py        # RDP 协议实现
│   ├── local_display.py     # 本地显示控制
│   └── image_matcher.py     # 图像匹配
├── templates/               # 图像模板示例
├── examples/                # 脚本示例
│   ├── open_browser.txt
│   └── login_form.txt
└── requirements.txt

Use Cases

  1. 远程服务器管理 - 通过 VNC 查看和操作服务器桌面
  2. UI 自动化测试 - 自动化测试桌面应用
  3. IoT 设备控制 - 控制带屏幕的嵌入式设备
  4. 游戏自动化 - 自动化游戏操作 (不推荐用于在线游戏)
  5. 数据录入 - 自动化表单填写

Security Notes

⚠️ 重要安全提示:

  • 不要在生产环境使用弱密码
  • 建议通过 VPN/SSH 隧道连接
  • 避免在公共网络暴露 VNC/RDP 端口
  • 敏感操作建议在本地执行

License

MIT License - 基于 Bytebot 的 Computer Use 模式实现

More in Automation