当前位置：首页 > news >正文

OpenClaw技能开发入门：为Phi-3-vision-128k-instruct定制截图分析模块

news 2026/6/4 11:33:42

OpenClaw技能开发入门：为Phi-3-vision-128k-instruct定制截图分析模块

1. 为什么需要定制截图分析技能

上周我在整理产品文档时遇到一个典型场景：需要从上百张软件界面截图中提取关键UI元素的文字描述和功能说明。手动操作不仅耗时，还容易遗漏细节。这让我开始思考——能否让OpenClaw帮我自动完成这个枯燥的任务？

经过验证，现有OpenClaw基础技能库中的"screen-capture"模块只能实现简单的截图保存，缺乏与多模态模型的深度集成。而Phi-3-vision-128k-instruct这个支持128k上下文的多模态模型，恰好能完美解决图文理解的需求。于是决定动手开发一个专属技能插件。

这个定制模块需要实现三个核心能力：

精准捕获屏幕指定区域
调用Phi-3视觉API进行图文分析
将模型输出结构化存储为Markdown报告

2. 开发环境准备

2.1 基础依赖安装

首先确保本地已部署OpenClaw核心框架（我用的v0.8.3版本）。新建技能项目前需要安装必要的Python包：

pip install pillow opencv-python httpx python-dotenv

特别提醒：如果使用MacOS系统，需要额外授权屏幕录制权限。我在第一次运行时忽略了这点，导致截图始终是黑屏。解决方法很简单：

进入"系统设置 > 隐私与安全性"
在"屏幕录制"中勾选终端应用（如iTerm或Terminal）

2.2 Phi-3模型服务配置

假设已在本地通过vllm部署Phi-3-vision-128k-instruct模型服务，默认端口为5000。我们需要在OpenClaw配置文件中添加模型端点：

// ~/.openclaw/openclaw.json { "models": { "providers": { "phi3-vision": { "baseUrl": "http://localhost:5000/v1", "apiKey": "your-api-key", "api": "openai-completions", "models": [ { "id": "phi-3-vision-128k-instruct", "name": "Phi-3 Vision", "contextWindow": 131072 } ] } } } }

配置完成后记得重启网关服务：

openclaw gateway restart

3. 技能核心逻辑实现

3.1 项目结构设计

采用OpenClaw推荐的技能项目结构：

phi3-screenshot-analyzer/ ├── __init__.py ├── manifest.json ├── requirements.txt ├── assets/ │ └── icon.png └── src/ ├── screenshot.py ├── phi3_client.py └── report_generator.py

其中manifest.json是技能的核心声明文件：

{ "name": "phi3-screenshot-analyzer", "version": "0.1.0", "description": "Screenshot analysis with Phi-3-vision model", "author": "Your Name", "skills": [ { "name": "analyze_screenshot", "description": "Capture and analyze screen region with Phi-3-vision", "parameters": { "region": { "type": "string", "description": "Screen region in 'x,y,width,height' format" }, "prompt": { "type": "string", "description": "Analysis instruction for the model" } } } ] }

3.2 截图捕获实现

在screenshot.py中实现区域捕获功能。这里我踩过一个坑：直接使用PIL的ImageGrab在跨平台时表现不一致。最终采用opencv+pyautogui组合方案：

import cv2 import numpy as np import pyautogui def capture_region(region_str): try: x, y, w, h = map(int, region_str.split(',')) screenshot = pyautogui.screenshot(region=(x, y, w, h)) img = cv2.cvtColor(np.array(screenshot), cv2.COLOR_RGB2BGR) # 临时保存截图供调试 temp_path = "/tmp/claw_screenshot.png" cv2.imwrite(temp_path, img) return temp_path except Exception as e: raise ValueError(f"截图失败: {str(e)}")

3.3 模型调用封装

phi3_client.py中实现对Phi-3视觉API的调用。这里需要注意多模态API的特殊传参方式：

import base64 import httpx def analyze_image(image_path, prompt): with open(image_path, "rb") as image_file: encoded_image = base64.b64encode(image_file.read()).decode('utf-8') messages = [ { "role": "user", "content": [ {"type": "text", "text": prompt}, {"type": "image_url", "image_url": f"data:image/png;base64,{encoded_image}"} ] } ] try: response = httpx.post( "http://localhost:5000/v1/chat/completions", json={ "model": "phi-3-vision-128k-instruct", "messages": messages, "max_tokens": 4096 }, timeout=30.0 ) return response.json()["choices"][0]["message"]["content"] except Exception as e: return f"模型调用失败: {str(e)}"

4. 功能集成与测试

4.1 主技能类实现

在__init__.py中集成各个模块：

from .src.screenshot import capture_region from .src.phi3_client import analyze_image from .src.report_generator import generate_markdown from pathlib import Path import datetime class Phi3ScreenshotAnalyzer: def __init__(self, workspace="/tmp/openclaw_workspace"): self.workspace = Path(workspace) self.workspace.mkdir(exist_ok=True) async def analyze_screenshot(self, region, prompt): try: # 1. 捕获截图 image_path = capture_region(region) # 2. 调用模型分析 analysis_result = analyze_image(image_path, prompt) # 3. 生成结构化报告 report_path = self.workspace / f"report_{datetime.datetime.now().strftime('%Y%m%d_%H%M%S')}.md" generate_markdown( image_path=image_path, analysis=analysis_result, output_path=str(report_path) ) return { "status": "success", "report_path": str(report_path), "analysis": analysis_result } except Exception as e: return { "status": "error", "message": str(e) }

4.2 测试验证

通过OpenClaw CLI进行功能测试：

openclaw skills test phi3-screenshot-analyzer analyze_screenshot \ --region "100,100,800,600" \ --prompt "请描述截图中的主要UI元素及其功能"

成功执行后会返回类似结果：

{ "status": "success", "report_path": "/tmp/openclaw_workspace/report_20240615_143022.md", "analysis": "截图显示的是一个代码编辑器界面...（模型分析结果）" }

5. 实际应用案例

最近我用这个技能自动生成了产品文档的UI说明部分。典型工作流如下：

编写批处理脚本遍历所有截图文件

对每张截图执行分析：

results = [] for img in screenshot_files: result = analyzer.analyze_screenshot( region="0,0,1920,1080", prompt="提取图中所有按钮文字和工具提示" ) results.append(result)

将生成的Markdown报告整合到文档系统

相比手动操作，效率提升了约8倍（从6小时压缩到45分钟）。更重要的是，模型能发现一些容易被人类忽略的细节，比如界面中不一致的颜色编码。

6. 开发经验总结

通过这个项目，我总结了几个OpenClaw技能开发的关键要点：

关于性能优化
初期直接传输原始截图导致API响应缓慢。后来改为先压缩到720p分辨率，再转JPEG格式（质量80%），使传输数据量减少90%而不影响识别精度。

关于错误处理
需要特别注意模型超时情况。我的解决方案是加入重试机制，并在连续失败时自动降低图片分辨率。在phi3_client.py中增加了如下逻辑：

MAX_RETRIES = 3 INITIAL_TIMEOUT = 30.0 for attempt in range(MAX_RETRIES): try: response = httpx.post( # ...其他参数不变 timeout=INITIAL_TIMEOUT * (attempt + 1) ) return process_response(response) except httpx.ReadTimeout: if attempt == MAX_RETRIES - 1: raise compress_image(image_path, quality=80 - attempt*20)

关于模型提示词
发现Phi-3-vision对具体明确的指令响应更好。例如：