1. 项目概述：当大语言模型“学会”点鼠标

最近在折腾一个挺有意思的项目，核心是让大语言模型（LLM）来干自动化测试的活儿，具体来说，是驱动一个叫 OpenClaw 的工具去操作图形界面（UI）。这听起来有点像让一个“大脑”去控制一个“机械臂”来点击、输入、验证。我用的“大脑”是经过蒸馏和推理优化的 Qwen3.5-4B-Claude-4.6-Opus-Reasoning-Distilled 模型，并且为了方便部署，转换成了 GGUF 格式。这个项目的目标很直接：提升在复杂、动态的 UI 操作场景下的指令执行准确率。如果你也正在探索 AI 驱动的自动化测试，或者对如何让本地部署的中小型模型在具体任务上发挥出超常水平感兴趣，那这篇从踩坑到填坑的实战记录，或许能给你一些直接的参考。

为什么是 OpenClaw？它本质上是一个基于计算机视觉（CV）和自然语言处理（NLP）的 UI 自动化框架。你不需要像传统自动化测试（如 Selenium、Appium）那样去定位元素的 XPath 或 CSS 选择器，你只需要用自然语言告诉它“点击登录按钮”或者“在搜索框里输入‘OpenClaw’并回车”，它就能尝试去理解和执行。这大大降低了对被测应用内部结构的依赖，尤其适合那些元素难以定位、或者频繁变动的客户端应用、桌面软件甚至一些游戏界面。

而“大脑”的选择是关键。纯视觉模型（如一些 OCR+CV 的方案）对界面理解有限，容易在相似元素或动态布局上出错。引入大语言模型，就是希望它能像人一样，结合屏幕截图和你的指令，进行“思考”和“推理”，从而做出更准确的决策。我选择的这个 Qwen3.5-4B 的混合蒸馏版本，目标就是在有限的参数量（4B）下，融合多个先进模型（如 Claude 3 Opus 的推理能力）的长处，专门针对“指令理解”和“多步推理”进行优化，再通过 GGUF 量化实现高效的本地运行。整个项目的挑战，就在于如何将这套“大脑”与 OpenClaw 这个“躯体”完美结合，并调教出高准确率。

2. 核心思路与方案选型背后的考量

这个项目的核心思路可以概括为： “视觉感知 + 语言推理 + 精准执行”的闭环 。OpenClaw 负责捕捉屏幕状态（截图），并将其与用户指令一起，提交给本地部署的 LLM。LLM 需要分析图像内容，理解指令意图，并输出一个结构化的、可执行的行动计划，比如 [动作类型， 目标描述， 附加参数] 。然后，OpenClaw 再根据这个计划去操作鼠标和键盘。

2.1 为什么选择 OpenClaw 而非传统框架？

传统自动化测试框架如 Selenium/Appium 的核心是“元素定位”。它们需要与被测应用的内部结构（DOM树、视图层级）紧密耦合。这带来了几个问题：

  1. 维护成本高 ：UI 每次改版，定位器就可能失效，需要重新编写和维护测试脚本。
  2. 跨平台/技术栈适配复杂 ：针对 Web、桌面、移动端需要不同的驱动和工具链。
  3. 对某些应用无能为力 ：对于游戏、基于 Canvas 的复杂应用、或某些客户端软件，可能根本没有标准的可访问性树供其定位。

OpenClaw 走的是另一条路： 以视觉和自然语言为中心 。它不关心内部是什么，只关心屏幕上“看起来”是什么。这带来了巨大的灵活性：

  • 技术栈无关 ：只要能截图，就能尝试自动化。
  • 更贴近真实用户 ：用户也是通过“看”和“理解”来操作软件的。
  • 快速原型 ：对新功能或新应用，可以立刻用自然语言描述进行测试，无需等待开发提供定位器。

当然，代价是对“视觉识别”和“指令理解”的精度要求极高，这也是本项目聚焦“准确率提升”的根本原因。

2.2 模型选型：Qwen3.5-4B-Claude-4.6-Opus-Reasoning-Distilled-GGUF 的深度解析

模型名字很长，拆开看每一步都有讲究：

  • Qwen3.5-4B ：基座模型。通义千问的 4B 参数版本，在中文理解和代码能力上表现均衡，参数量适中，适合本地部署和微调。
  • Claude-4.6-Opus-Reasoning-Distilled ：这是关键的后处理步骤。它不是简单的模型融合，而是通过一种称为“蒸馏”的技术，将更大、更强模型（这里暗示了 Claude 3 Opus 级别的复杂推理能力）的“思维过程”和“输出风格”迁移到小模型上。具体来说，“Reasoning Distilled”意味着在训练时，不仅让 Qwen3.5-4B 学习大模型的最终答案，还让它学习大模型得出答案的中间推理步骤。这对于需要多步决策的 UI 自动化任务至关重要。例如，指令是“登录后查看第一条消息”，模型需要推理出：先找到用户名输入框->输入->找密码框->输入->找登录按钮->点击->等待页面加载->识别消息列表->定位第一条消息。
  • GGUF ：模型格式。它是由 llama.cpp 社区推动的格式，相比之前的 GGML，提供了更灵活的量化配置和更好的硬件支持。选择 GGUF 意味着我们可以轻松地在 CPU 或混合（CPU+GPU）环境下运行模型，并通过量化（如 Q4_K_M, Q5_K_M）在精度和速度/显存占用之间取得平衡。对于自动化测试这种对延迟有一定容忍度但希望节省资源的场景，Q4 或 Q5 量化是非常实用的选择。

注意 ：市面上有很多类似的“蒸馏”或“合并”模型，质量参差不齐。选择这个特定版本，是因为其发布者通常提供了详细的训练数据和方法说明，并且在多项推理基准测试中表现突出。建议从 Hugging Face 或 ModelScope 等可信平台上有良好口碑的发布者处下载。

2.3 整体架构设计

最终的方案架构如下：

  1. 环境层 ：OpenClaw 作为执行器，负责屏幕捕获、鼠标键盘控制。
  2. 推理层 ：本地 llama.cpp 或 ollama 服务，加载上述 GGUF 模型，提供 API 接口（通常兼容 OpenAI API 格式）。
  3. 协调层 ：一个 Python 控制脚本。它的工作是：
    • 接收测试用例（自然语言指令）。
    • 调用 OpenClaw 截取当前屏幕。
    • 将截图（编码为 base64）和指令组合成符合模型预期的 Prompt，发送给推理层 API。
    • 解析模型返回的 JSON 格式的“动作计划”。
    • 将动作计划翻译成 OpenClaw 的底层命令并执行。
    • 根据执行结果（成功/失败）和可能的下一步屏幕状态，决定继续或重试。

这个架构的核心是 Prompt 工程 和 动作计划的解析与容错 ，这也是提升准确率的主战场。

3. 提升准确率的核心技巧与实战配置

准确率提升不是单一魔法，而是一系列工程化技巧的组合。下面我结合实战，拆解几个最关键的部分。

3.1 精心设计的 Prompt 模板

Prompt 是与模型对话的“说明书”，直接决定模型输出的质量。经过大量测试，一个有效的多模态 Prompt 模板应包含以下部分：

你是一个专业的UI自动化助手。你需要根据提供的屏幕截图和用户指令，输出一个可执行的JSON动作序列。

## 屏幕上下文
[这里系统会自动插入当前的屏幕截图描述或base64占位符，具体取决于后端实现]

## 用户指令
{user_instruction}

## 输出格式要求
你必须严格输出一个JSON数组，每个元素代表一个动作。动作结构如下：
[
  {
    "action": "click | type | scroll | wait | key_press",
    "target_description": "清晰描述要操作的元素，例如‘蓝色的登录按钮’、‘顶部的搜索输入框’",
    "params": {"text": "要输入的文本", "key": "按键名如ENTER", "direction": "up/down", "duration": 秒数} // 根据action类型可选
  },
  ...
]

## 推理过程（仅供你思考，不要输出）
1. 分析屏幕主要内容：有哪些可交互元素（按钮、输入框、链接、列表）？
2. 理解用户指令的真实意图：需要达成什么最终状态？可能需要几步？
3. 规划动作序列：按顺序执行哪些动作可以安全、高效地达成目标？注意避免重复操作或无效操作。
4. 精确定位目标：使用独特且稳定的特征描述目标元素，如颜色、文字、相对位置（“在‘用户名’标签右侧的输入框”）。

## 重要规则
- 如果屏幕内容与指令完全不相关或无法执行，输出 []。
- 优先使用 `click` 和 `type` 动作。
- `wait` 动作用于等待页面加载或元素出现，默认2秒。
- 描述 `target_description` 时，务必结合截图中的视觉特征。

现在，开始执行任务。

这个模板的设计逻辑：

  1. 角色设定 ：明确模型的任务身份，引导其进入状态。
  2. 结构化输入 ：分离“屏幕上下文”和“用户指令”，符合多模态模型的处理习惯。
  3. 严格输出格式 ：强制模型输出 JSON，便于程序化解析。定义了有限的几种 action 类型，覆盖绝大多数 UI 操作。
  4. 内置“思维链” ：虽然要求模型不输出“推理过程”，但在 Prompt 里给出思考框架，能显著提升其规划能力。这是“Reasoning Distilled”模型能发挥优势的关键。
  5. 明确规则与边界 ：告诉模型何时该放弃（输出空数组），以及如何描述目标，减少歧义。

3.2 模型加载与推理参数调优

使用 llama.cpp 加载 GGUF 模型时，参数设置对推理质量和速度影响很大。

# 一个推荐的启动命令示例
./server -m ./models/qwen3.5-4b-claude-4.6-opus-reasoning-distilled-Q5_K_M.gguf \
  --host 0.0.0.0 --port 8080 \
  --ctx-size 4096 \          # 上下文长度，处理截图描述需要较大空间
  --threads 8 \              # CPU线程数，根据核心数调整
  --mlock \                  # 锁定模型在内存，避免交换
  --n-gpu-layers 40 \        # 如果使用GPU，指定卸载到GPU的层数，加速推理
  --parallel 1 \
  --cont-batching \          # 持续批处理，提升吞吐
  --log-disable

对于推理时的生成参数，通过 API 调用时传递：

generation_params = {
    "max_tokens": 512,        # 足够输出JSON动作序列
    "temperature": 0.1,       # 低温度，保证输出的确定性和一致性，对自动化任务至关重要
    "top_p": 0.95,
    "frequency_penalty": 0.1,
    "presence_penalty": 0.1,
    "stop": ["\n```"],         # 防止模型输出多余内容
    "seed": 42,               # 固定种子，确保相同输入得到相同输出，便于复现和调试
}

关键点：

  • 低 Temperature (0.1-0.3) ：这是最重要的参数。自动化测试需要确定性，而不是创造性。低温度让模型选择概率最高的 token，减少随机性导致的动作飘忽。
  • 固定 Seed ：确保在调试阶段，相同的屏幕和指令总能产生相同的动作计划，否则问题排查会变成噩梦。
  • 足够的上下文 (ctx-size) ：如果直接将截图以 base64 编码的长字符串形式送入 Prompt，会消耗大量 token。更常见的做法是先用一个轻量级视觉模型（如 BLIP、ViT）或 OCR 工具（如 PaddleOCR）对截图生成一个文本描述，再将描述放入 Prompt。这样能节省大量 token，让 LLM 专注于推理。我们的 ctx-size 需要能容纳这个描述和完整的 Prompt。

3.3 动作执行与状态验证的闭环

模型输出动作计划只是第一步，执行环节的鲁棒性同样重要。

  1. 动作翻译 ：将通用的 {"action": "click", "target_description": "登录按钮"} 转化为 OpenClaw 可执行的命令。这通常需要 OpenClaw 自身的视觉匹配功能。我们需要将 target_description 进一步细化，或者结合截图，调用 OpenClaw 的 find_element_by_text 或 find_element_by_image 方法。
  2. 执行与等待 ：执行一个点击后，必须加入显式等待（例如 2-3 秒），让应用程序有足够时间响应（加载新页面、弹出对话框等）。这个等待时间可以放在动作计划的 wait 中，也可以由协调脚本在每次操作后固定等待。
  3. 状态验证 ：执行完一系列动作后，如何判断成功了？不能只依赖动作执行无异常。我们需要一个“验证步骤”。可以在原用户指令中隐含，也可以单独设计验证指令。例如，指令是“登录系统”，在模型执行完点击登录按钮的动作后，协调脚本可以再次截图，并问模型：“当前屏幕是否显示已登录的主页？”根据模型的回答（是/否）来判断测试用例的成功与否。这就形成了一个“感知-推理-执行-验证”的闭环。

4. 实操流程：从零搭建到运行第一个测试

假设你已经准备好了 Python 环境和基本的开发工具，下面是一步步的实操指南。

4.1 环境准备与依赖安装

首先，需要安装 OpenClaw。由于其安装方式可能更新，建议查阅其官方 GitHub 仓库。通常可以通过 pip 安装：

pip install openclaw

接着，需要部署 LLM 推理服务。这里以 ollama 为例，因为它管理模型非常方便。如果你追求极致性能或自定义，也可以用 llama.cpp 直接编译 server 。

  1. 安装 Ollama ：前往官网下载对应操作系统的安装包。
  2. 拉取自定义模型 ：我们需要将下载好的 GGUF 模型文件导入 Ollama。创建一个 Modelfile ：
FROM ./qwen3.5-4b-claude-4.6-opus-reasoning-distilled-Q5_K_M.gguf
PARAMETER temperature 0.1
PARAMETER seed 42
# 可以设置其他默认参数

然后创建模型：

ollama create my-ui-helper -f ./Modelfile
ollama run my-ui-helper

Ollama 会以 API 服务形式运行，默认端口 11434。

4.2 核心协调脚本编写

编写一个 Python 脚本 ui_automator.py 作为大脑和躯干的连接器。

import requests
import json
import base64
from openclaw import Claw
import time
from PIL import ImageGrab
import io

class UIAutoHelper:
    def __init__(self, ollama_base_url="http://localhost:11434"):
        self.claw = Claw()
        self.ollama_url = f"{ollama_base_url}/api/generate"
        self.model_name = "my-ui-helper"
        # 初始化OCR工具，用于将截图转为文本描述，节省token
        # 这里以PaddleOCR为例，需先安装：pip install paddleocr paddlepaddle
        # from paddleocr import PaddleOCR
        # self.ocr = PaddleOCR(use_angle_cls=True, lang='ch')
        # 为简化，我们先使用一个假设的函数
        self.screen_describer = self._simple_describe_screen

    def _simple_describe_screen(self, image):
        """简化版的屏幕描述生成器。实际应用中应替换为更强大的CV模型或OCR组合。"""
        # 这里可以集成BLIP2等图像描述模型，或复杂的OCR分析
        # 暂时返回一个占位符，实际开发中需要实现
        return "屏幕截图已捕获，包含各种UI元素。"

    def capture_and_describe(self):
        """捕获屏幕并生成文本描述"""
        screenshot = ImageGrab.grab()
        img_byte_arr = io.BytesIO()
        screenshot.save(img_byte_arr, format='PNG')
        img_byte_arr = img_byte_arr.getvalue()
        # 将图片转为base64，可用于后续直接发送（如果模型支持视觉token）
        # base64_image = base64.b64encode(img_byte_arr).decode('utf-8')
        description = self.screen_describer(screenshot)
        return description, img_byte_arr

    def get_action_plan(self, instruction, screen_description):
        """调用Ollama API，获取动作计划"""
        prompt = f"""你是一个专业的UI自动化助手。根据以下屏幕描述和用户指令，输出JSON动作序列。

屏幕描述：{screen_description}

用户指令：{instruction}

输出格式必须为：[{{"action": "click|type|scroll|wait|key_press", "target_description": "...", "params": {{...}}}}]
确保target_description足够具体。如果无法执行，输出空数组[]。"""
        
        payload = {
            "model": self.model_name,
            "prompt": prompt,
            "stream": False,
            "options": {
                "temperature": 0.1,
                "seed": 42,
                "num_predict": 512
            }
        }
        try:
            response = requests.post(self.ollama_url, json=payload, timeout=30)
            response.raise_for_status()
            result = response.json()
            # Ollama的响应在'response'字段中
            response_text = result.get('response', '').strip()
            # 清理响应，提取JSON部分
            json_start = response_text.find('[')
            json_end = response_text.rfind(']') + 1
            if json_start != -1 and json_end > json_start:
                json_str = response_text[json_start:json_end]
                action_plan = json.loads(json_str)
                return action_plan
            else:
                print(f"未能从模型响应中解析出JSON: {response_text}")
                return []
        except Exception as e:
            print(f"调用模型API失败: {e}")
            return []

    def execute_action(self, action):
        """将通用动作翻译为OpenClaw命令并执行"""
        action_type = action.get('action')
        target = action.get('target_description', '')
        params = action.get('params', {})

        if action_type == 'click':
            # 这里需要将文本描述转化为OpenClaw可定位的元素
            # 例如，使用OpenClaw的文本查找或图像匹配
            # 简化演示：假设target就是按钮文字
            self.claw.click_text(target)
        elif action_type == 'type':
            text = params.get('text', '')
            self.claw.click_text(target)  # 先点击目标输入框
            time.sleep(0.2)
            self.claw.type_text(text)
        elif action_type == 'wait':
            duration = params.get('duration', 2)
            time.sleep(duration)
        elif action_type == 'key_press':
            key = params.get('key', 'ENTER')
            self.claw.press_key(key)
        # ... 其他动作类型
        time.sleep(0.5)  # 每个动作后的基础间隔

    def run_instruction(self, instruction):
        """主流程：执行一条自然语言指令"""
        print(f"执行指令: {instruction}")
        screen_desc, _ = self.capture_and_describe()
        print(f"屏幕状态: {screen_desc[:100]}...") # 打印前100字符

        action_plan = self.get_action_plan(instruction, screen_desc)
        print(f"生成动作计划: {json.dumps(action_plan, indent=2, ensure_ascii=False)}")

        if not action_plan:
            print("模型认为当前无法执行该指令。")
            return False

        for i, action in enumerate(action_plan):
            print(f"执行动作 {i+1}: {action}")
            try:
                self.execute_action(action)
            except Exception as e:
                print(f"执行动作失败: {e}")
                # 可以加入重试逻辑
                return False
        print("指令执行完毕。")
        return True

if __name__ == "__main__":
    helper = UIAutoHelper()
    # 测试：打开一个记事本，然后尝试让助手输入文字
    # 首先需要手动将记事本窗口置于前台
    input("请将记事本窗口置于前台，然后按回车继续...")
    helper.run_instruction("在文本编辑区域输入‘Hello, OpenClaw!’")

4.3 测试与迭代优化

运行上述脚本只是一个开始。你需要准备一个测试集，包含各种复杂度的指令和对应的屏幕状态。

  1. 构建测试集 ：录制或截取不同应用（浏览器、IDE、文件管理器）的屏幕状态，并为每个状态编写 5-10 条自然语言指令，从简单（“点击关闭按钮”）到复杂（“将第三个标签页的内容保存到‘文档’文件夹，命名为‘备份.txt’”）。
  2. 批量运行与评估 ：自动化运行测试集，记录每条指令的最终验证状态（成功/失败）。
  3. 分析错误 ：失败通常源于：
    • 描述歧义 ：模型对 target_description 的描述，OpenClaw 无法精准定位。需要优化 Prompt 中对描述的要求，或增强 OpenClaw 的查找策略（结合多模态查找）。
    • 推理链断裂 ：模型规划的步骤缺失或顺序错误。需要丰富 Prompt 中的“推理过程”示例，或考虑使用更复杂的思维链（Chain-of-Thought）提示，甚至让模型输出每一步的思考。
    • 状态判断错误 ：验证环节模型误判。可以引入更严格的验证，比如询问多个问题，或结合简单的图像相似度比较。
  4. 迭代优化 ：根据错误分析，反复调整 Prompt 模板、模型参数（如 temperature ）、以及协调脚本中的执行策略（如等待时间、重试机制）。

5. 常见问题、避坑指南与进阶技巧

在实际操作中，你会遇到各种各样的问题。下面是我踩过的一些坑和总结的技巧。

5.1 模型响应不稳定或格式错误

  • 问题 ：模型有时不输出 JSON，或输出格式混乱。
  • 解决 ：
    1. 强化格式指令 ：在 Prompt 中使用非常严格的格式描述，甚至给出一个完美的示例（Few-Shot Learning）。例如，在 Prompt 开头直接写一个完整的示例。
    2. 后处理清洗 ：在解析模型响应时，加入更鲁棒的 JSON 提取逻辑，比如使用正则表达式匹配 [...] 之间的内容，或者使用 json5 库来解析容错性更好的 JSON。
    3. 降低 Temperature ：确保 temperature 设置在 0.1 或 0.2，这是保证格式稳定的首要条件。

5.2 OpenClaw 定位元素失败

  • 问题 ：模型给出了看似正确的描述（如“红色的删除图标”），但 OpenClaw 在屏幕上找不到。
  • 解决 ：
    1. 多模态查找 ：不要只依赖文本。OpenClaw 支持基于图像模板的查找。可以在 Prompt 中要求模型输出更具体的描述，同时，协调脚本可以保存当前截图的小区域（ROI），将“红色的删除图标”这样的描述，转化为一个图像模板，供 OpenClaw 进行图像匹配。
    2. 分层定位 ：对于复杂界面，指导模型使用“在...旁边”、“...下方第二个”、“位于窗口右上角”等相对位置描述。这需要你的屏幕描述生成器（ screen_describer ）能提供基本的空间布局信息。
    3. 组合定位器 ：结合文本、图像、颜色和相对位置，提高定位成功率。

5.3 处理动态内容和加载等待

  • 问题 ：网络应用页面加载慢，元素延迟出现，导致操作失败。
  • 解决 ：
    1. 显式 Wait 动作 ：在 Prompt 中强调，在可能引起页面刷新的操作（如点击提交、导航）后，主动插入 {"action": "wait", "params": {"duration": 3}} 。
    2. 智能等待 ：在协调脚本中实现“条件等待”。执行一个动作后，不是死等固定时间，而是周期性地截图，并问模型“等待的目标元素（如‘加载完成’的标识）出现了吗？”，直到模型回答“是”或超时。
    3. 超时与重试 ：为每个动作设置超时和重试次数。失败后，可以重新捕获屏幕，让模型基于新状态重新规划。

5.4 性能瓶颈与优化

  • 问题 ：每次推理都要截图、描述、调用模型，速度较慢。
  • 优化 ：
    1. 缓存屏幕描述 ：如果两次操作间屏幕没有变化（可以通过图像哈希简单判断），则复用上一次的描述和动作计划，避免重复调用模型。
    2. 使用更轻量的视觉模型 ：用于生成屏幕描述的模型不必太复杂。可以考虑专门的、轻量化的场景图生成或 UI 元素检测模型（如微软的 ScreenAI 或 PADDLE 的 UI 结构识别），它们比通用多模态大模型更快。
    3. 动作批处理 ：对于一连串确定性的操作（如输入表单），可以让模型一次性输出所有步骤，而不是每一步都交互一次。但这需要模型有很强的规划能力。

5.5 进阶技巧：让模型学会“使用工具”

这是提升复杂任务准确率的终极技巧。我们可以将 OpenClaw 的一些高级功能（如 get_text_from_region , compare_images ）也暴露给模型，作为它可以调用的“工具”。

在 Prompt 中定义工具：

可用的工具：
1.  find_element(description): 根据描述查找元素，返回坐标或是否找到。
2.  get_text(region_description): 获取屏幕上某个区域的文字。
3.  is_screen_changed(before_image_hash): 判断屏幕自上次操作后是否发生变化。

然后，修改输出格式，让模型不仅可以输出 action ，还可以输出 tool_call 。协调脚本负责执行这些工具调用，并将结果反馈给模型，进行下一步决策。这就实现了更复杂的、带状态感知的自动化流程，准确率会大幅提升，但系统复杂度和延迟也会增加。

最后，我想分享一个最深的体会： Prompt 工程是连接意图与执行的桥梁，其质量直接决定了上限；而鲁棒的执行和状态验证逻辑，则是保证下限的基石 。不要指望一个模型解决所有问题，它是一个强大的“决策核心”，但需要被妥善地嵌入到一个精心设计的、容错的自动化流程中。从简单的点击开始，逐步增加复杂度，持续用测试集喂养和评估，你会发现这个“AI 测试员”会变得越来越聪明可靠。

Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

【花雕动手做】行空板 K10 系列实验之人工智能调用语音合成（TTS）模块

avatar AI Agent技术社区
cover

苏州企业AI Agent智能体从概念到落地：2026年开发者必须关注的技术范式与工程实践

avatar AI Agent技术社区
cover

GitHub 狂揽 4万+ Star！这个项目直接让你省下 60–95% 的 Token

avatar AI Agent技术社区