1. 项目概述：从“看图说话”到智能体自动化

最近在折腾本地AI智能体，发现一个挺有意思的现象：很多朋友把OpenClaw单纯当成了一个“高级聊天机器人”，问它天气、写写文案。这其实有点大材小用了。OpenClaw真正的威力在于它的“技能”（Skill）系统，能让AI智能体像人一样，调用各种工具去完成复杂的、多步骤的任务。比如，你丢给它一张满是文字的截图或产品海报，它不仅能“看懂”图片内容，还能把里面的文字精准地提取出来，甚至根据文字内容进行下一步操作，比如自动整理成表格、翻译或者存入数据库。

这个“识别图片并提取文字”的功能，就是我们今天要拆解的核心。它听起来简单，不就是OCR（光学字符识别）吗？但结合OpenClaw的智能体框架，事情就变得有趣了。想象一下，一个电商客服智能体，能自动读取用户发来的商品问题截图，提取订单号、商品名称，然后去后台系统查询并回复；或者一个内部办公助手，能处理同事发来的会议纪要照片，自动转成可编辑的文本。这背后，是OpenClaw的“大脑”（大语言模型）指挥它的“眼睛”（图片识别技能）和“手”（文本处理技能）协同工作的结果。

我自己在部署和配置OpenClaw用于图片文字识别时，踩过不少坑，从环境依赖冲突到技能配置逻辑，再到如何让识别结果更精准。这篇文章，我就以一个实践者的角度，把OpenClaw实现图片识别与文字提取的完整链路、核心配置、实战技巧以及那些官方文档没写的“坑点”彻底讲清楚。无论你是想给自己的智能体加上“视觉”能力，还是单纯好奇OpenClaw如何整合外部工具，这篇近万字的实操指南都能给你带来直接可用的参考。

2. 核心思路拆解：OpenClaw如何“看见”并“理解”图片

在深入命令行之前，我们必须先理清OpenClaw处理图片的逻辑。这绝不是简单调用一个OCR接口那么简单，而是一个涉及智能体决策、技能调度、服务交互的完整链条。

2.1 OpenClaw的技能驱动架构

OpenClaw的核心是一个“智能体运行时环境”。它本身不直接具备识图能力，它的强项是“调度”和“决策”。你可以把它理解为一个公司的“总经理”（LLM大脑），它自己不生产零件（不直接处理图片），但它知道公司里有哪个部门（Skill技能）擅长做什么，并指挥它们去完成任务。

当用户向OpenClaw发送一条包含图片的消息时（比如在飞书、微信等接入的平台上），流程是这样的：

1. 消息接收与解析：OpenClaw首先接收到一条混合内容（可能包含文本和图片附件）。对于图片，它通常接收到的是一个图片文件的访问链接（URL）或本地路径。
2. 大脑决策：内置的大语言模型（如通过Ollama本地运行的Llama 3、Qwen等）会分析用户的请求。如果判断请求涉及图片内容理解（例如，“帮我看下这张图里写了什么”、“总结一下这张海报的信息”），它就会在已注册的技能库中寻找合适的工具。
3. 技能调用：模型会决定调用具备图片识别能力的Skill。这个Skill本质上是一个独立的服务或函数，OpenClaw会按照预定格式（通常是HTTP请求）向这个服务发送指令，并将图片信息传递过去。
4. 结果整合与回复：Skill服务处理完图片，将提取出的文字结果返回给OpenClaw。OpenClaw的“大脑”再对这些原始文本进行加工，比如润色、总结、或结合上下文生成最终回复，返回给用户。

所以，我们的核心工作就是：为OpenClaw这位“总经理”搭建一个强大的“视觉处理部门”（图片识别Skill），并确保“总经理”知道在什么情况下、如何调用这个部门。

2.2 技术选型：为什么不是内置OCR？

你可能会问，为什么OpenClaw不内置一个OCR引擎？这涉及到设计哲学和实用性。

• 轻量与专注：OpenClaw定位于智能体调度框架，保持核心轻量。将OCR这类重型、专业性强的功能作为外部技能，符合微服务架构思想，也降低了核心复杂度。
• 灵活性与可替换性：不同的OCR服务精度、速度、支持语言、价格各异。作为Skill，你可以自由选择今天用免费的PaddleOCR，明天换更准的百度云OCR，或者商业化的Azure Cognitive Services。只需修改Skill的配置，无需改动OpenClaw核心。
• 功能解耦：图片识别可能只是任务的一环。一个Skill专门负责OCR，另一个Skill负责文本分析，再一个Skill负责调用数据库。这种解耦让智能体的能力组合更加灵活。

基于以上，我们的技术栈就很明确了：

1. OpenClaw本体：负责智能体调度和对话管理。
2. 大模型服务：通常用Ollama在本地运行，作为OpenClaw的“大脑”。
3. 图片识别Skill服务：一个独立的、提供OCR API的服务。这是我们配置的重点。

2.3 实战方案选择

根据你的部署环境和需求，主要有两种主流方案：

方案一：本地化OCR服务（推荐给注重隐私、离线使用的开发者）

• 代表工具：PaddleOCR、Tesseract、EasyOCR。
• 优点：数据完全不出本地，无网络延迟，无调用费用。
• 缺点：部署稍复杂，需要处理Python环境、模型下载；识别精度（尤其是对复杂排版、模糊图片）可能略逊于顶尖云服务；消耗本地计算资源。
• 适合场景：内部工具、处理敏感数据、网络环境受限、希望零成本长期使用。

方案二：云端OCR API服务（推荐给追求高精度、怕麻烦的开发者）

• 代表服务：百度AI开放平台OCR、腾讯云OCR、阿里云OCR（注：根据合规要求，仅列举国内主流合规服务）。
• 优点：识别精度高，尤其是对印刷体、表格、卡证等；部署简单，只需申请API Key；服务稳定，无需维护模型。
• 缺点：数据需传输至服务商服务器（需评估合规性）；有调用次数限制或费用；依赖网络。
• 适合场景：对识别准确率要求高的生产环境、快速原型验证、无本地GPU资源。

我个人的实战建议是：先从本地化的PaddleOCR开始。它开源免费，中文识别效果好，社区活跃，与OpenClaw集成案例多。等跑通流程、验证需求后，如果确实需要更高精度，再考虑迁移到云API。下文也将以PaddleOCR + OpenClaw作为主要实战路线进行详解。

3. 环境部署与核心组件安装

“工欲善其事，必先利其器”。一个稳定的基础环境是后续所有操作的前提。很多人卡在第一步，问题都出在依赖冲突或配置错误。

3.1 OpenClaw本体的部署

OpenClaw的部署方式多样，这里给出最稳健的两种，适用于绝大多数Linux/Windows/macOS环境。

方案A：使用Docker部署（最推荐，最省心）Docker能完美解决环境隔离和依赖问题，是生产环境的首选。

# 1. 拉取官方镜像（以最新稳定版为例） docker pull openclaw/openclaw:latest # 2. 创建用于持久化配置和数据的目录 mkdir -p ~/openclaw/data ~/openclaw/config # 3. 运行容器 docker run -d \ --name openclaw \ -p 3000:3000 \ # 将容器内3000端口映射到宿主机 -v ~/openclaw/data:/app/data \ # 挂载数据卷 -v ~/openclaw/config:/app/config \ # 挂载配置卷 -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \ # 关键！指向宿主机Ollama openclaw/openclaw:latest

注意：OLLAMA_BASE_URL这个环境变量至关重要。如果你的Ollama也运行在宿主机上，Docker容器内部需要通过host.docker.internal这个特殊域名来访问宿主机的服务。如果你是Linux系统且Docker版本较旧，可能需要改用宿主机的实际IP地址（如-e OLLAMA_BASE_URL=http://192.168.1.100:11434）。

方案B：本地Python环境部署（适合深度定制开发者）

# 1. 克隆仓库 git clone https://github.com/openclaw/OpenClaw.git cd OpenClaw # 2. 创建虚拟环境（强烈建议） python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 3. 安装依赖 pip install -r requirements.txt # 4. 配置环境变量 # 创建一个 .env 文件，至少包含以下内容 echo "OLLAMA_BASE_URL=http://localhost:11434" >> .env echo "DEFAULT_MODEL=llama3.1:latest" >> .env # 指定默认模型 # 5. 启动 python app.py

无论哪种方案，启动后访问http://localhost:3000应该能看到OpenClaw的Web界面。

3.2 大模型服务（Ollama）的安装与模型拉取

OpenClaw的“大脑”需要Ollama来提供。

# 安装Ollama，请访问官网 https://ollama.com/ 选择对应系统安装包。 # 安装后，拉取一个适合的中英文模型，例如 Llama 3.1 8B 或 Qwen2.5 7B ollama pull llama3.1:8b # 或 ollama pull qwen2.5:7b-instruct # 启动Ollama服务（通常安装后自动运行） # 检查服务是否运行 curl http://localhost:11434/api/tags

确保你在OpenClaw的配置（环境变量或Web界面设置）中正确指向了Ollama的地址（http://localhost:11434）。

3.3 图片识别技能核心：PaddleOCR服务部署

这是实现功能的关键。我们将PaddleOCR封装成一个独立的HTTP服务，供OpenClaw调用。

步骤1：创建OCR技能目录在你的工作区（不要放在OpenClaw项目内，保持独立），创建一个新目录。

mkdir openclaw_ocr_skill && cd openclaw_ocr_skill

步骤2：编写OCR服务脚本 (ocr_server.py)

#!/usr/bin/env python3 """ OpenClaw OCR Skill 服务端 提供一个简单的HTTP API，接收图片URL或Base64，返回识别文字。 """ from flask import Flask, request, jsonify from paddleocr import PaddleOCR import requests import base64 import io from PIL import Image import logging import os app = Flask(__name__) logging.basicConfig(level=logging.INFO) # 初始化PaddleOCR，这里使用中英文模型，使用CPU运行 # 首次运行会自动下载模型，请保持网络通畅 ocr_engine = PaddleOCR(use_angle_cls=True, lang='ch', use_gpu=False) # lang='ch'代表中英文 logging.info("PaddleOCR引擎初始化完成。") def decode_image(image_input): """解码图片输入，支持URL和Base64格式。""" img = None # 判断是否为URL if image_input.startswith(('http://', 'https://')): try: resp = requests.get(image_input, timeout=10) resp.raise_for_status() img = Image.open(io.BytesIO(resp.content)) logging.info(f"成功从URL加载图片: {image_input}") except Exception as e: logging.error(f"从URL加载图片失败: {e}") raise ValueError(f"无效的图片URL或无法访问: {e}") # 否则尝试解码为Base64 else: try: # 可能包含data:image/png;base64,前缀 if ',' in image_input: image_input = image_input.split(',')[1] image_data = base64.b64decode(image_input) img = Image.open(io.BytesIO(image_data)) logging.info("成功从Base64加载图片。") except Exception as e: logging.error(f"Base64解码失败: {e}") raise ValueError("无效的Base64图片数据") return img @app.route('/ocr', methods=['POST']) def ocr(): """OCR主接口。""" try: data = request.json if not data or 'image' not in data: return jsonify({'error': '请求体中必须包含"image"字段（URL或Base64）'}), 400 image_input = data['image'] # 可选参数：是否需要详细结构（框、坐标、置信度） detail = data.get('detail', False) # 解码图片 pil_image = decode_image(image_input) # 临时保存到内存字节流，PaddleOCR需要文件路径或字节流 img_byte_arr = io.BytesIO() pil_image.save(img_byte_arr, format='PNG') img_byte_arr = img_byte_arr.getvalue() # 执行OCR # 使用ocr_engine.ocr，传入字节流 result = ocr_engine.ocr(img_byte_arr, cls=True) logging.info("OCR识别完成。") # 处理结果 if not result or not result[0]: text = "" boxes = [] else: # result结构: [[[[框坐标], (文本, 置信度)], ...]] boxes = [] texts = [] for line in result[0]: box = line[0] # 四个点的坐标 text_info = line[1] # (文本, 置信度) boxes.append(box) texts.append(text_info[0]) text = '\n'.join(texts) # 将多行文本合并为一个字符串，用换行符分隔 response = {'text': text} if detail: response['detail'] = {'boxes': boxes, 'full_result': result} return jsonify(response), 200 except ValueError as ve: return jsonify({'error': str(ve)}), 400 except Exception as e: logging.exception("OCR处理内部错误") return jsonify({'error': f'内部服务器错误: {e}'}), 500 if __name__ == '__main__': # 获取端口，默认5001，避免与OpenClaw冲突 port = int(os.environ.get('PORT', 5001)) app.run(host='0.0.0.0', port=port, debug=False) # 生产环境请将debug设为False

步骤3：创建依赖文件 (requirements.txt)

Flask>=2.3.0 paddlepaddle>=2.5.0 paddleocr>=2.7.0 requests>=2.31.0 Pillow>=10.0.0

步骤4：安装依赖并启动服务

# 强烈建议在虚拟环境中进行 pip install -r requirements.txt # 启动OCR服务，指定端口（例如5001） PORT=5001 python ocr_server.py

服务启动后，你可以用curl测试一下：

# 测试URL图片识别 (找一个包含文字的图片URL替换掉下面的链接) curl -X POST http://localhost:5001/ocr \ -H "Content-Type: application/json" \ -d '{"image": "https://example.com/sample-text-image.png", "detail": false}' # 测试Base64图片识别 (这里用一个小Base64示例，实际请用真正的图片Base64) curl -X POST http://localhost:5001/ocr \ -H "Content-Type: application/json" \ -d '{"image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==", "detail": false}'

如果返回包含{"text": "识别出的文字..."}的JSON，说明OCR服务部署成功。

4. OpenClaw技能配置与集成实战

现在，我们有了运行中的OpenClaw（总经理）和独立的OCR服务（视觉部门）。接下来，最关键的一步是让总经理知道这个部门的存在，并学会在何时、如何下达指令。

4.1 编写图片识别Skill描述文件

在OpenClaw中，Skill通过一个描述文件来定义。这个文件告诉OpenClaw：这个技能叫什么、能干什么、需要什么参数、以及如何调用。

在你的OpenClaw配置目录下（如果是Docker部署，就是挂载的~/openclaw/config目录；本地部署则在项目根目录），找到或创建skills文件夹。在里面创建一个新文件，例如image_ocr_skill.json。

{ "name": "image_ocr", "description": "识别图片中的文字内容。可以处理用户发送的图片附件或包含图片链接的消息，提取其中的文本信息。适用于读取截图、文档照片、海报文字等场景。", "inputs": [ { "name": "image_input", "description": "图片信息。这可以是一个公开可访问的图片URL（以http://或https://开头），也可以是图片的Base64编码字符串。这是必填参数。", "type": "string", "required": true }, { "name": "need_detail", "description": "是否需要详细的识别结果，包括文字框的位置坐标和置信度。默认为false，只返回纯文本。", "type": "boolean", "required": false, "default": false } ], "outputs": [ { "name": "extracted_text", "description": "从图片中提取出的纯文本内容，多行文字会用换行符分隔。" }, { "name": "detail_info", "description": "当need_detail为true时返回，包含文字框坐标和置信度等结构化信息。" } ], "action": { "type": "http", "config": { "url": "http://localhost:5001/ocr", // 指向我们刚启动的OCR服务地址 "method": "POST", "headers": { "Content-Type": "application/json" }, "body": { "image": "{{image_input}}", "detail": "{{need_detail}}" }, "timeout": 30000 // 超时时间30秒 }, "response": { "type": "json", "schema": { "text": "{{extracted_text}}", "detail": "{{detail_info}}" } } } }

关键点解析：

• name: 技能的唯一标识，后续在对话中，模型会根据这个名称来调用技能。
• description:极其重要！这是给大模型看的“岗位说明书”。描述必须清晰、具体，说明技能的功能、适用场景和输入要求。模型根据这个描述来决定是否以及如何调用该技能。我在这里特意强调了“图片附件”和“图片链接”，覆盖了常见输入方式。
• inputs: 定义了调用技能所需的参数。image_input被设计为兼容URL和Base64，提高了灵活性。need_detail作为可选参数，满足不同颗粒度的需求。
• action: 定义了技能的实际调用方式。这里是HTTP POST请求，体中的{{image_input}}和{{need_detail}}是模板变量，会被实际的参数值替换。url必须确保OpenClaw能够访问到，如果OCR服务运行在宿主机，而OpenClaw在Docker内，则需要使用宿主机的IP地址，而不是localhost。

4.2 加载技能并测试基础功能

1. 放置技能文件：将写好的image_ocr_skill.json文件放入OpenClaw的skills目录。
2. 重启OpenClaw服务：如果是Docker部署，重启容器；如果是本地运行，重启Python应用。OpenClaw会在启动时自动加载skills目录下的所有技能文件。
3. 验证技能加载：访问OpenClaw的Web界面（通常为http://localhost:3000），进入技能管理或设置页面，应该能看到名为image_ocr的技能已被加载。
4. 进行对话测试：
   • 场景一（直接指令）：在聊天框输入“识别一下这张图片：https://example.com/test.png”。观察OpenClaw的思考过程（如果开启了调试信息），它应该会识别出你的意图，调用image_ocr技能，并将图片URL传给我们的服务，最后返回识别出的文字。
   • 场景二（上传图片）：在支持文件上传的OpenClaw前端（如某些WebUI或已接入的飞书/微信机器人），直接上传一张包含文字的图片。OpenClaw接收到的会是一个本地文件路径或内部标识，它需要能将其转换为我们的技能能理解的格式（URL或Base64）。这是最常见的坑点。

4.3 处理图片上传：格式转换的桥梁

OpenClaw接收到的用户上传的图片，通常不是直接的URL。它可能是一个本地临时文件路径，也可能是一个内部存储的标识符。我们的OCR技能期望的是URL或Base64。因此，我们需要一个“适配器”。

方案：在Skill的Action之前，添加一个预处理步骤（通过OpenClaw的“处理器”或“钩子”）。更通用的做法是，修改OCR服务，使其也能接收OpenClaw传递的“文件标识符”，并由服务端自己去OpenClaw的数据存储中读取文件内容。但这涉及更深的定制。

更简单的实战技巧：利用OpenClaw的“文件服务”或“公共访问链接”。许多部署方式（尤其是Docker）中，上传的文件会被保存在一个可被Web服务器访问的目录。你可以配置OpenClaw，使上传的文件能通过一个固定的URL前缀访问。例如，如果你将~/openclaw/data/uploads映射为Web服务的/uploads路径，那么一个上传的文件abc123.jpg的访问URL可能就是http://你的OpenClaw地址/uploads/abc123.jpg。

你需要查阅你的OpenClaw部署文档，确认文件访问方式。然后，在Skill的description或通过系统提示词告诉模型：“当用户上传图片时，请使用图片对应的公开访问URL（格式如http://<openclaw-host>/uploads/<filename>）作为image_input参数来调用技能。”

如果无法获得公共URL，则可能需要编写一个更复杂的Skill，其action的第一步是调用OpenClaw的内部API获取文件二进制数据，再将其转换为Base64，然后转发给OCR服务。这属于高级定制，需要查看OpenClaw的API文档。

一个折中的快速验证方法：在测试阶段，你可以手动将图片上传到某个图床（如阿里云OSS、腾讯云COS，并设置公共读），获得一个公网URL，然后用这个URL去测试技能。这可以验证从“图片URL”到“识别结果”的整个链路是否通畅。

5. 高级配置与优化技巧

基础功能跑通后，我们可以从稳定性、准确性和易用性上进行优化。

5.1 提升OCR识别精度与速度

PaddleOCR默认配置可能不是最优的。我们可以调整初始化参数：

# 在 ocr_server.py 的初始化部分进行调整 ocr_engine = PaddleOCR( use_angle_cls=True, # 启用方向分类，用于校正横竖排 lang='ch', # 语言：中英文混合。可改为 'en' 纯英文，或多语言组合如 'ch', 'en', 'fr' use_gpu=False, # 如果机器有CUDA环境且安装了paddlepaddle-gpu，可设为True大幅加速 page_num=1, # 如果处理PDF或长图，可设置识别页数 det_db_thresh=0.3, # 文本框检测阈值，调低可检测更多模糊文字，但也可能引入噪声 det_db_box_thresh=0.5, # 文本框大小阈值 rec_char_dict_path=None, # 可指定自定义字典路径，用于识别特殊字符（如行业术语） show_log=False # 关闭详细日志，减少输出 )

• GPU加速：如果有NVIDIA显卡，安装paddlepaddle-gpu版本，并将use_gpu=True，速度可提升10倍以上。
• 自定义字典：如果你的图片中常出现特定术语（如产品型号、内部代码），可以创建一个文本文件，每行一个词，通过rec_char_dict_path指定，能显著提升这些词的识别率。

5.2 技能描述的“咒语工程”

Skill的description是与大模型沟通的桥梁。写得不好，模型可能无法正确调用。好的描述应遵循以下原则：

• 明确触发条件：清晰说明在什么情况下使用本技能。例如：“当用户请求读取、识别、提取图片中的文字信息时，或当消息中包含图片附件时使用。”
• 详细说明输入：解释image_input可以是什么。例如：“参数image_input必须是图片的公开HTTP/HTTPS链接，或者是完整的图片Base64编码数据（可包含data:image前缀）。”
• 举例说明：可以在描述中加入一两个例子，帮助模型理解。例如：“例如，用户说‘看看这张图里写了啥’，并附带了一张图片，你应该调用本技能，并将图片的访问链接作为image_input参数。”
• 输出说明：告诉模型你会得到什么，以及它该如何向用户呈现。例如：“技能将返回提取的文本，你可以直接回复给用户，或者根据文本内容进行总结、翻译等后续处理。”

5.3 处理复杂场景与错误

• 多图处理：当前技能一次处理一张图。如果用户上传多图，模型可能会困惑。可以在Skill描述中注明“本技能一次仅处理一张图片”。对于多图需求，可以考虑开发一个支持批量处理的技能，或者让模型循环调用。
• 网络图片与权限：如果图片URL需要鉴权（如私有的OSS链接），我们的简单OCR服务无法处理。需要技能支持传递Headers，或者在OpenClaw端先下载图片再以Base64形式传递。这增加了复杂性。
• 服务降级与超时：在action配置中设置了"timeout": 30000。如果OCR服务挂掉或响应慢，OpenClaw会收到超时错误。你需要在Skill定义或系统层面考虑错误处理，例如让模型回复“图片识别服务暂时不可用，请稍后再试”。
• 结果后处理：OCR返回的原始文本可能包含不必要的空格、换行或识别错误。可以在OCR服务端添加简单的后处理逻辑（如正则表达式清理），也可以在OpenClaw端，让大模型对识别结果进行润色和修正，这恰恰是大模型的强项。

6. 实战案例：构建一个电商客服图片处理智能体

让我们结合一个具体场景，把上面的知识点串起来。假设我们要做一个能处理用户售前咨询图片的电商客服智能体。

目标：用户经常发送包含商品截图、尺寸图、错误提示的图片。智能体需要能提取图片中的关键信息（如商品ID、尺寸、错误代码），并据此回复或进行下一步操作（如查询库存、跳转售后流程）。

实现步骤：

1. 技能增强：我们已有的image_ocr技能是基础。针对电商场景，我们可以创建一个更专业的技能ecommerce_image_parser。这个技能内部依然调用我们的OCR服务，但增加了后处理逻辑：

   • 正则表达式提取：在OCR服务返回文本后，用预设的正则匹配商品ID（如SKU-12345）、尺码（如M,L,XL）、颜色等。
   • 结构化输出：不再返回纯文本，而是返回一个JSON，包含raw_text（原始文本）、extracted_entities（提取出的实体，如{"sku": "SKU-12345", "size": "L"}）。

   // ecommerce_image_parser_skill.json 的 outputs 部分示例 "outputs": [ { "name": "parsed_result", "description": "结构化的解析结果，包含原始文本和提取出的商品实体信息。" } ]

2. 系统提示词优化：在OpenClaw的系统提示词（或Agent的初始化设定）中，明确告诉模型：

   “你是一个电商客服助手。当用户发送图片时，优先调用ecommerce_image_parser技能来提取图片中的关键信息。如果提取到商品SKU，你可以接着调用query_inventory技能（假设我们有这个技能）查询库存。如果提取到错误代码，你可以调用search_knowledge_base技能查找解决方案。”

3. 多技能编排：通过精心设计的技能描述和系统提示，OpenClaw的模型可以自动完成“识图 -> 提取信息 -> 查询 -> 回复”的链条。这就是智能体自动化的魅力。

4. 接入实战：将配置好的OpenClaw通过其提供的插件或API，接入到你的电商平台客服系统（如钉钉、飞书、企业微信的群聊或单聊）。当用户在客服对话中发送图片时，整个流程将自动触发。

7. 常见问题与故障排查实录

在实际部署中，你几乎一定会遇到下面这些问题。这里是我的踩坑记录和解决方案。

问题1：OpenClaw无法调用OCR服务，报错“Connection refused”或“Timeout”。

• 排查思路：
  • 网络连通性：这是Docker部署最常见的问题。在OpenClaw容器内，尝试curl http://host.docker.internal:5001（或宿主机IP）。如果不通，说明容器网络配置有问题。
  • 服务地址：确保Skill配置中的url是OpenClaw容器内能访问到的地址。如果OCR服务运行在宿主机，对于Linux Docker默认的bridge网络，需用http://172.17.0.1:5001（宿主机在docker网桥的IP）或host.docker.internal（Docker Desktop特性，Linux原生Docker可能不支持）。最稳妥的方法是让OCR服务也运行在一个容器，并通过Docker Compose在同一个自定义网络下部署，互相使用服务名访问。
  • 防火墙：检查宿主机防火墙是否屏蔽了5001端口。
• 解决方案：使用Docker Compose将OpenClaw和OCR服务编排在一起。

  # docker-compose.yml version: '3.8' services: ollama: image: ollama/ollama:latest ports: - "11434:11434" volumes: - ollama_data:/root/.ollama openclaw: image: openclaw/openclaw:latest ports: - "3000:3000" volumes: - ./openclaw_data:/app/data - ./openclaw_config:/app/config environment: - OLLAMA_BASE_URL=http://ollama:11434 # 使用服务名访问 depends_on: - ollama ocr_service: build: ./ocr_service # 假设你的OCR服务有Dockerfile # 或者使用 image: your-ocr-image ports: - "5001:5001" # 不需要暴露端口给宿主机，仅需内部网络访问 networks: default: name: openclaw-network

  然后在OpenClaw的Skill配置中，url改为http://ocr_service:5001/ocr。

问题2：OCR识别中文乱码或精度极差。

• 排查思路：
  • 模型未下载完整：PaddleOCR首次运行会下载模型，网络不好会导致模型损坏。查看日志是否有下载错误。
  • 图片格式问题：某些格式（如WebP）可能需要Pillow库额外支持。确保Pillow版本较新。
  • 图片质量太差：分辨率过低、模糊、背景复杂的图片识别率自然低。
• 解决方案：
  • 删除PaddleOCR的模型缓存目录（通常在~/.paddleocr/或~/.paddleocr/whl/），重新运行服务让其重新下载。
  • 在OCR服务端添加图片预处理，如转为灰度图、二值化、调整对比度，可以显著提升某些场景的识别率。可以使用OpenCV或PIL在decode_image函数后添加处理步骤。

问题3：大模型不理解用户意图，不调用图片识别技能。

• 排查思路：
  • 技能描述不清：回顾你的description，是否足够清晰、具体？是否包含了典型用户问法示例？
  • 模型能力不足：如果使用的本地小模型（如7B参数），其工具调用能力可能较弱。尝试换用更大的模型（如Llama 3.1 70B, Qwen 32B），或使用API模型（如GPT-4）。
  • 系统提示词未引导：在OpenClaw的系统提示词中，需要明确强调“当你看到图片时，应优先考虑使用图片识别技能”。
• 解决方案：
  • 优化Skill的description，使用更直接、示例化的语言。
  • 在对话中，用户可以更明确地指令，如“用OCR技能读一下这张图”。
  • 开启OpenClaw的调试日志，查看模型收到消息后的完整思考过程，分析它为什么没有选择调用技能。

问题4：处理速度慢，尤其是多张图片时。

• 排查思路：
  • OCR是瓶颈：PaddleOCR在CPU上运行较慢，特别是首次识别。
  • 网络延迟：如果图片是网络URL，下载耗时。
  • 模型推理慢：大模型生成调用技能的指令也需要时间。
• 解决方案：
  • GPU加速：为PaddleOCR启用GPU。
  • 异步处理：对于非实时场景，可以让Skill调用返回一个任务ID，然后通过Webhook或让用户主动查询的方式获取结果。但这需要更复杂的Skill和前端配合。
  • 缓存：对相同的图片URL，可以在OCR服务端增加简单的缓存机制（如用MD5做键），短期内避免重复识别。

问题5：上传图片后，OpenClaw不知道如何将图片传给Skill。

• 这是集成中最棘手的部分之一。如前所述，关键在于OpenClaw的前端或接收端如何将图片“表示”给模型。
• 解决方案：
  • 研究接入渠道的文档：例如，如果你使用飞书机器人接入，飞书会将图片上传到其服务器，并提供image_key。你需要编写一个特定的“飞书图片处理Skill”，它接收image_key，然后调用飞书API下载图片到临时目录，再转换为Base64或上传到你的图床获得URL，最后调用通用的image_ocr技能。这相当于一个“适配器Skill”。
  • 统一文件存储：配置OpenClaw使用一个公共可访问的文件存储（如S3兼容的对象存储），所有上传的图片都存储在那里并生成公共URL。这样，任何Skill需要图片时，都直接使用这个URL。

部署和调试OpenClaw技能是一个系统工程，需要耐心地一步步排查。从确保单个服务健康，到打通服务间通信，最后优化模型调用的准确性。每当解决一个问题，你对整个智能体架构的理解就会加深一层。