基于Scrcpy与OpenClaw的安卓自动化：原理、实践与进阶应用

1. 项目概述：当开源Scrcpy遇上“机械爪”

如果你和我一样，经常需要在电脑上操作安卓手机，无论是为了录屏演示、自动化测试，还是单纯觉得大屏操作更舒服，那你肯定听说过Scrcpy。这个由Genymobile开源的神器，通过ADB（Android Debug Bridge）将手机屏幕镜像到电脑，并允许用键鼠直接控制，延迟低、画质好，几乎是开发者与极客的标配。

但Scrcpy本身是个“显示与控制”工具，它不负责“执行”。想象一个场景：你需要定时在手机上完成一系列固定操作，比如每天凌晨自动签到、批量处理图片、或者进行长时间的稳定性测试。手动操作显然不现实，而市面上的一些自动化工具要么封闭收费，要么功能笨重。这时，ammarlakis/openclaw-scrcpy这个项目就进入了我的视野。

简单来说，它是在Scrcpy这座坚固的桥梁上，搭建了一个自动化的“机械爪”。项目名中的“OpenClaw”（开源之爪）非常形象——它利用Scrcpy建立的低延迟、高保真连接，注入了一套自动化指令执行引擎。你可以把它理解为一个为Scrcpy量身定做的、开源免费的“按键精灵”，但它运行在电脑端，通过ADB向手机发送精确的触控、滑动、按键事件，从而完成复杂的自动化流程。

我最初接触它，是为了解决一个烦人的问题：公司有一批测试机，需要每晚执行相同的App遍历测试用例。手动操作几十台手机根本不现实，而一些云测平台成本又太高。OpenClaw-Scrcpy的方案让我眼前一亮：它直接复用现有、高效的Scrcpy连接，无需在手机端安装任何额外的辅助服务（无障碍服务除外），所有逻辑在电脑上编写和调度，既轻量又灵活。

2. 核心架构与工作原理拆解

要玩转这个“机械爪”，得先明白它的内部构造。它不是一个从头造轮子的项目，而是一个巧妙的“集成增强”方案。

2.1 技术栈与依赖关系

项目的核心建立在三大支柱之上：

1. Scrcpy (v2.0+): 这是基石。OpenClaw-Scrcpy并不包含Scrcpy本体，而是作为它的一个“控制器”或“插件”运行。它要求你的系统已经能够正常运行Scrcpy。Scrcpy负责了最复杂的部分：高效的视频编码（H.264/H.265）、解码渲染、以及双向输入事件传输的底层通道。
2. ADB (Android Debug Bridge): 这是连接的生命线。无论是Scrcpy的初始连接，还是OpenClaw发送的自动化命令，最终都通过ADB与手机通信。这意味着你的手机必须开启“开发者选项”和“USB调试”（或已配对成功的无线调试）。
3. OpenClaw 引擎 (Python): 这是项目本体，用Python编写。它的核心职责是：
   • 流程编排：解析用户编写的自动化脚本（通常是YAML或Python）。
   • 状态感知：虽然不像UI自动化测试框架那样可以做复杂的图像识别，但它可以通过ADB获取当前活动（Activity）、包名（Package Name）、以及通过Scrcpy间接获取屏幕图像（用于简单的像素颜色检测或OCR集成）。
   • 指令翻译与发送：将脚本中的“点击(100,200)”、“滑动从A到B”、“输入文本‘Hello’”等高级指令，翻译成具体的ADBinput命令或Scrcpy控制协议命令，并注入到连接中。

这种架构带来了一个关键优势：稳定性与性能依赖Scrcpy，逻辑与控制则由轻量的Python脚本处理。你获得了Scrcpy久经考验的流畅镜像体验，同时拥有了可编程的自动化能力。

2.2 与纯ADB自动化及UI测试框架的对比

很多朋友可能会问，直接用ADB shell命令input tapinput swipe不也能自动化吗？或者用Appium、UIAutomator2这样的专业框架不行吗？这里就是OpenClaw-Scrcpy的精准定位所在。

• vs 纯ADB命令：

  • 优势：纯ADB命令是“盲操作”。你发送一个input tap 500 500，ADB并不知道这个点是否可点击，屏幕是否已经加载完成。OpenClaw-Scrcpy通过与Scrcpy的结合，可以有条件地执行。例如，它可以先获取一张屏幕截图（通过Scrcpy），检查某个特定位置的像素颜色是否变为预期状态（如“提交按钮”由灰变蓝），然后再执行点击。这引入了简单的“等待”和“条件判断”逻辑，避免了脚本因网络延迟或手机卡顿而乱序执行。
  • 劣势：它的条件判断能力远不如专业的UI测试框架强大和便捷。

• vs Appium/UIAutomator2：

  • 优势：
    1. 轻量级：无需在手机端安装额外的测试服务（如Appium Settings， UIAutomator2 Server），仅依赖标准的开发者选项。部署更简单，对手机系统影响小。
    2. 连接稳定：直接复用Scrcpy的ADB连接，Scrcpy在维持连接稳定性上做得非常好，避免了无线调试时端口断开等常见问题。
    3. 操作直观：对于简单的、基于坐标或固定流程的自动化，编写脚本更直接。你可以一边看着Scrcpy的实时镜像，一边调试脚本，所见即所得。
  • 劣势：
    1. 可维护性差：严重依赖屏幕坐标。一旦应用UI改版，按钮位置变化，脚本就需要重新调整坐标，维护成本高。
    2. 缺乏高级定位：无法通过ID、文本内容、XPath等属性来定位元素，不适合复杂或动态UI的自动化。
    3. 跨设备适配难：在不同分辨率、不同尺寸的手机上，需要计算坐标比例，不如基于控件树的框架自适应能力强。

结论：OpenClaw-Scrcpy最适合的场景是流程固定、UI稳定、且对部署轻量性要求高的自动化任务。比如，在固定型号的测试机上执行冒烟测试、对某个特定应用进行每日重复性操作（签到、收菜）、或者作为硬件项目（如树莓派）中控制安卓设备的中枢。

3. 环境搭建与快速上手

理论说了不少，我们来点实际的。下面是我在Ubuntu 22.04和Windows 11上均验证过的搭建流程。

3.1 基础环境准备

首先，确保你的电脑已经具备了运行Scrcpy的所有条件。

1. 安装ADB：

   # Ubuntu/Debian sudo apt update sudo apt install android-tools-adb # Windows # 推荐下载官方SDK Platform-Tools，解压后将adb.exe所在目录加入系统PATH。 # 或使用Chocolatey: choco install adb

2. 安装Scrcpy：

   # Ubuntu (使用snap，最简单) sudo snap install scrcpy # 或者从源码编译/使用预编译包，详见Scrcpy官方GitHub。 # Windows: 直接下载release中的scrcpy-win64-v2.x.zip，解压即可。

3. 手机端准备：

   • 进入“设置”->“关于手机”，连续点击“版本号”7次，开启“开发者选项”。
   • 在“开发者选项”中，开启“USB调试”。
   • 如果是无线连接，还需在“开发者选项”中开启“无线调试”，并在电脑上使用adb connect IP:端口连接。

4. 验证连接：

   adb devices

   你应该能看到你的设备号，后面跟着device字样。然后运行scrcpy，应该能正常弹出手机镜像窗口。

3.2 安装OpenClaw-Scrcpy

项目是Python写的，所以我们需要Python环境（建议3.8+）。

# 1. 克隆项目 git clone https://github.com/ammarlakis/openclaw-scrcpy.git cd openclaw-scrcpy # 2. 创建虚拟环境（推荐，避免包冲突） python -m venv venv # Windows: venv\Scripts\activate # Linux/Mac: source venv/bin/activate # 3. 安装依赖 pip install -r requirements.txt # 核心依赖通常包括：pyyaml（解析脚本）， pillow（图像处理）， opencv-python（可选，用于高级图像识别）等。

注意：项目的requirements.txt可能不会列出所有隐式依赖。如果运行时提示缺少模块，请根据错误信息使用pip install手动安装。例如，可能需要pyscrcpy（一个Python的Scrcpy客户端库）或其类似物。

3.3 你的第一个自动化脚本：自动解锁并打开微信

OpenClaw-Scrcpy通常使用YAML或Python文件来定义任务。我们从一个最简单的YAML示例开始，假设手机锁屏密码是“123456”。

创建一个名为unlock_and_open_wechat.yaml的文件：

name: "解锁并打开微信" description: "模拟滑动解锁，输入密码，然后点击微信图标" steps: - name: "唤醒屏幕" action: "keyevent" args: key: "POWER" # 发送电源键事件，唤醒屏幕 - name: "滑动解锁" action: "swipe" args: start: [300, 1000] # 起始坐标，从屏幕底部向上滑 end: [300, 400] duration: 300 # 滑动持续时间，单位毫秒 - name: "输入密码" action: "input_text" args: text: "123456" # 这里通常需要等待一下键盘动画，但简单密码屏保可能不需要 - name: "点击进入桌面" action: "tap" args: point: [540, 1800] # 假设“确认”或“进入”按钮在屏幕底部中央，坐标需根据实际屏幕调整 - name: "等待桌面加载" action: "sleep" args: ms: 2000 - name: "点击微信图标" action: "tap" args: point: [150, 350] # 微信图标在桌面第一屏的坐标，这需要你手动获取

如何获取坐标？这是基于坐标自动化的关键一步。你可以通过以下方式获取：

1. 在Scrcpy镜像窗口上，开启“显示触摸”选项（通常默认开启），你的每次点击都会在屏幕上留下白点。
2. 手动操作一次，记住关键点的位置。
3. 更专业的方法是使用ADB命令adb shell getevent -l或adb shell input tap x y来测试，但通过Scrcpy直观查看是最快的。

运行这个脚本：

# 假设你的主脚本是 run.py，它负责解析YAML并执行 python run.py -f unlock_and_open_wechat.yaml # 或者根据项目README的指示，使用其提供的命令行工具

实操心得：基于坐标的脚本非常脆弱。上述示例中，微信图标坐标一旦变化就失效了。因此，在实际项目中，我们很少直接使用绝对坐标，而是会结合一些简单的图像识别来“寻找”目标。

4. 核心功能进阶：引入图像识别与条件逻辑

纯粹的坐标点击像是“蒙眼操作”，而图像识别则给了“机械爪”一双眼睛。OpenClaw-Scrcpy通常可以集成opencv-python和pillow库来实现简单的模板匹配。

4.1 实现“寻找并点击”功能

我们改进上面的最后一步：不是直接点击固定坐标，而是在屏幕上寻找微信图标，找到后再点击。

首先，你需要截取微信图标的模板图片（一个小图，比如 72x72 像素），保存为wechat_icon.png。

然后，修改YAML脚本或使用Python编写更灵活的脚本：

# find_and_tap.py import cv2 import numpy as np from PIL import ImageGrab # 用于截取屏幕，需要根据OpenClaw提供的接口调整 import subprocess import time def get_screenshot(): """通过Scrcpy或ADB获取当前屏幕截图。 这里是一个概念性示例，实际需调用项目提供的截图方法或ADB命令。 """ # 方法1: 使用ADB命令截图并拉取到电脑 subprocess.run(['adb', 'shell', 'screencap', '-p', '/sdcard/screen.png']) subprocess.run(['adb', 'pull', '/sdcard/screen.png', '.']) return cv2.imread('screen.png') # 方法2: 如果OpenClaw项目封装了Scrcpy的截图API，直接调用即可。 def find_template(screenshot, template_path, threshold=0.8): """在截图screenshot中寻找模板template_path，返回匹配位置的列表。""" img_rgb = screenshot template = cv2.imread(template_path) h, w = template.shape[:-1] res = cv2.matchTemplate(img_rgb, template, cv2.TM_CCOEFF_NORMED) loc = np.where(res >= threshold) points = [] for pt in zip(*loc[::-1]): # Switch columns and rows points.append((pt[0] + w//2, pt[1] + h//2)) # 返回图标中心点 return points def tap(point): """执行点击操作""" x, y = point subprocess.run(['adb', 'shell', 'input', 'tap', str(x), str(y)]) # 主逻辑 screen = get_screenshot() wechat_icon_positions = find_template(screen, 'wechat_icon.png', threshold=0.9) if wechat_icon_positions: print(f"找到微信图标在 {wechat_icon_positions[0]}") tap(wechat_icon_positions[0]) else: print("未找到微信图标，可能不在当前屏幕，尝试滑动") # 这里可以加入滑动查找的逻辑

将这样的Python函数封装成OpenClaw可以调用的“动作”（Action），你就能在YAML脚本中写出如下步骤：

- name: "寻找并点击微信" action: "find_and_tap" # 这是一个自定义动作 args: template: "assets/wechat_icon.png" threshold: 0.85 retry: times: 3 interval: 1000

4.2 添加等待与条件判断

自动化脚本的灵魂在于“在正确的时间做正确的事”。OpenClaw-Scrcpy应该支持基本的等待和条件循环。

- name: "等待登录按钮出现" action: "wait_for" args: condition: "image_exists" # 等待某个图片出现 target: "assets/login_button.png" timeout: 10000 # 最多等10秒 on_timeout: "fail" # 超时后任务失败 - name: "点击登录" action: "tap_on_image" args: image: "assets/login_button.png" - name: "等待登录成功" action: "wait_for" args: condition: "activity_is" # 等待特定Activity出现（通过ADB获取） activity: "com.tencent.mm.ui.LauncherUI" timeout: 15000

这些高级动作（wait_for,find_and_tap）需要你在OpenClaw-Scrcpy的项目框架内进行扩展开发。通常，项目会提供一个基础的动作类，你可以继承并实现自己的逻辑。

5. 实战案例：构建一个自动化签到脚本

假设我们需要为某个游戏App（包名：com.example.game）每日自动签到。流程是：打开App -> 可能弹公告（点关闭）-> 进入主界面 -> 点击“签到”按钮 -> 领取奖励 -> 关闭App。

5.1 准备工作：获取关键资源

1. 模板图片：用Scrcpy截图，裁剪出“关闭公告按钮”、“签到按钮”、“领取奖励按钮”等关键UI元素的小图，保存到assets/目录。
2. 坐标备用：同时记录下这些按钮的大致坐标，作为图像识别失败的备选方案。
3. 了解Activity：通过adb shell dumpsys window | findstr mCurrentFocus(Windows) 或grep(Linux) 命令，查看各个界面对应的Activity名称。

5.2 编写脚本

我们使用一个混合策略的Python脚本：

# auto_sign.py import sys import os sys.path.append(os.path.dirname(__file__)) from openclaw_core import Runner, ActionBase # 假设项目有这样的核心类 import cv2 import adbutils class TapOnImageAction(ActionBase): def execute(self, context): template_path = self.params['template'] threshold = self.params.get('threshold', 0.8) # ... 实现图像查找和点击逻辑，同第4.1节 # 如果找到，点击并返回True；如果没找到，返回False pass class WaitForActivityAction(ActionBase): def execute(self, context): target_activity = self.params['activity'] timeout = self.params.get('timeout', 5000) device = context['device'] # 从上下文中获取adb设备对象 start_time = time.time() while time.time() - start_time < timeout / 1000: current_activity = device.current_activity() if target_activity in current_activity: return True time.sleep(0.5) return False # 超时 def main(): # 初始化运行器 runner = Runner() # 注册自定义动作 runner.register_action('tap_on_image', TapOnImageAction) runner.register_action('wait_for_activity', WaitForActivityAction) # 定义任务步骤 task_steps = [ {'action': 'start_app', 'args': {'package': 'com.example.game'}}, {'action': 'sleep', 'args': {'ms': 3000}}, # 等待App启动 {'action': 'tap_on_image', 'args': {'template': 'assets/close_ad.png'}, 'retry': 3}, # 尝试关闭公告 {'action': 'wait_for_activity', 'args': {'activity': '.MainActivity'}, 'timeout': 10000}, {'action': 'tap_on_image', 'args': {'template': 'assets/sign_button.png'}, 'retry': 5, 'interval': 1000}, # 重试5次，每次间隔1秒找签到按钮 {'action': 'sleep', 'args': {'ms': 1000}}, {'action': 'tap', 'args': {'point': [540, 1200]}}, # 假设领取奖励在固定位置 {'action': 'sleep', 'args': {'ms': 2000}}, {'action': 'keyevent', 'args': {'key': 'BACK'}}, # 返回 {'action': 'keyevent', 'args': {'key': 'HOME'}}, # 回到桌面 ] # 执行任务 success = runner.run(task_steps) if success: print("✅ 自动签到任务完成！") else: print("❌ 任务执行失败。") # 可以在这里添加错误处理，比如发送通知 if __name__ == '__main__': main()

5.3 部署与定时执行

在Linux服务器或树莓派上，我们可以使用cron定时任务。

1. 确保设备通过USB连接或稳定的无线ADB连接。
2. 编写一个启动脚本run_sign.sh：

   #!/bin/bash cd /path/to/openclaw-scrcpy source venv/bin/activate python auto_sign.py >> /tmp/auto_sign.log 2>&1

3. 给脚本执行权限：chmod +x run_sign.sh
4. 编辑cron任务：crontab -e

   # 每天凌晨3点30分执行 30 3 * * * /path/to/run_sign.sh

在Windows上，可以使用“任务计划程序”实现同样的效果。

6. 常见问题、排查技巧与优化建议

在实际使用中，你肯定会遇到各种问题。下面是我踩过的一些坑和总结的经验。

6.1 连接与稳定性问题

重要提示：对于生产环境，强烈建议使用USB连接。无线连接仅适合临时调试。USB连接不仅稳定，还能同时为手机充电。

6.2 脚本执行准确性问题

6.3 性能与优化建议

1. 截图优化：频繁截图并进行图像识别是性能瓶颈。如果操作流程固定，能使用坐标就尽量使用坐标。必须用图像识别时，可以：

   • 缩小搜索区域：不要在全屏搜索，根据UI布局，只在可能出现的区域进行匹配。
   • 降低截图分辨率：在满足识别精度的前提下，让Scrcpy以较低的分辨率运行（scrcpy -m 800）。
   • 使用灰度图像：模板匹配时，将图片转为灰度图进行处理，可以减少计算量。

2. 脚本健壮性：

   • 重试机制：为核心步骤（如点击按钮）添加重试逻辑。不是简单的sleep后重试，而是“失败 -> 重新识别 -> 再点击”的循环。
   • 状态检查：在关键步骤后，加入简单的状态验证。例如，点击登录后，检查是否跳转到了主界面Activity，而不是停留在登录页。
   • 日志记录：详细记录每个步骤的执行结果、截图（在失败时），便于后期排查。

3. 代码结构：

   • 抽象公共操作：将“寻找并点击”、“等待出现”等操作封装成函数或类，使主脚本清晰易读。
   • 配置与代码分离：将设备的坐标、模板图片路径、等待超时时间等可变参数提取到配置文件（如JSON或YAML）中，方便适配不同设备或App版本。

7. 扩展思路：不止于点击

OpenClaw-Scrcpy的潜力不止于模拟触控。结合ADB命令，你可以实现更丰富的自动化：

• 文件管理：自动将电脑上的配置文件、图片推送到手机指定位置，或从手机拉取生成的文件。

  # 在脚本中调用 subprocess.run(['adb', 'push', 'local/file.txt', '/sdcard/Download/'])

• 信息读取：定期抓取手机上的特定信息，如短信验证码、通知栏内容、当前运行的应用等，并回传到电脑进行处理。

  # 获取最近一条短信 subprocess.run(['adb', 'shell', 'content', 'query', '--uri', 'content://sms/inbox', '--projection', 'body', '--sort', 'date DESC', '--limit', '1'])

• 系统控制：调节音量、亮度、切换网络状态、安装/卸载APK等。
• 与其它系统集成：将OpenClaw-Scrcpy作为一个服务，通过REST API接收指令，从而与Home Assistant等智能家居系统，或Jenkins等CI/CD流水线集成，实现更复杂的联动自动化。

这个项目的魅力在于，它用一个相对简单直接的方式，撬动了Scrcpy这个强大工具的另一面。它可能不像商业自动化软件那样功能齐全、界面友好，但它给了你完全的控制权和无限的定制空间。对于有编程基础、喜欢折腾、并且有明确自动化需求的开发者来说，花点时间搭建和调试OpenClaw-Scrcpy，换来的是一个高度定制、稳定可靠且零成本的自动化助手。