1. 工业质检现场的真实困境：为什么传统方案总是卡在最后一公里

我在产线做视觉项目时，最常听到的一句话是“实验室里跑得好好的，一到车间就废了”。这不是模型不行，而是整条链路没有真正闭环。工业AI质检要解决的不是单点检测精度，而是从图像采集、缺陷定位、分类分级、分拣执行到溯源记录的完整工程问题。

先说人工目检。单件产品耗时普遍超过3秒，7×24小时连续作业下漏检率轻松突破5%，而且招工越来越难、培训周期越来越长。再说传统AOI设备，基于固定特征提取，只能适配单一品类和固定缺陷类型，面对“多品种、小批量”的柔性产线，换型调试动辄数周，根本跟不上生产节奏。最后是传统AI质检开发，需要算法、软件、电气三拨人协同，开发周期1到3个月起步，中小工厂根本养不起这样的团队。

OpenClaw作为开源AI智能体框架，核心价值在于把“感知-推理-决策-执行-迭代”这条链路用低代码方式串起来。它不替代YOLO，也不替代OpenCV，而是作为调度层，把相机采集、模型推理、PLC通信、报告生成这些能力封装成可复用的Skill，让一个电气工程师就能完成整套系统的编排和维护。你可以把它理解成产线质检的“总控大脑”，YOLO负责看，OpenCV负责预处理，OpenClaw负责决定下一步做什么。

这套方案适合三类人：一是想从传统AOI升级到AI质检的工厂技术负责人；二是做工业视觉集成的工程师，需要快速交付可维护的项目；三是算法工程师，希望把模型能力真正落到产线闭环里，而不是只交一个推理脚本。下面我会按实际落地顺序，把每个环节的配置、参数和验证动作写清楚，你跟着做就能跑通一条最小可用的质检链路。

2. TaoToken前置准备：模型调用与API Key配置

在开始写检测脚本之前，需要先解决模型推理的调用通道问题。工业现场通常有两种模式：一种是纯边缘端本地推理，用ONNX Runtime直接跑YOLO模型，不依赖网络；另一种是边缘端做预处理和初筛，复杂分类或大模型辅助判断走云端API。TaoToken在这套方案里承担的是第二种角色——当你需要调用视觉大模型做零样本缺陷识别，或者用大模型生成质检报告摘要时，通过统一的API入口来调用，避免在产线环境里维护多套鉴权逻辑。

先到TaoToken官网注册账号，进入控制台创建API Key。地址是 https://taotoken.net/api ，注意API地址不带UTM参数，直接访问即可。创建Key的时候建议按产线或项目命名，比如“metal-defect-line-a”，方便后续做用量归因和权限隔离。Key生成后只显示一次，复制保存到安全位置。

接下来配置环境变量。在边缘主机的终端里执行：

export TAOTOKEN_API_KEY="sk-your-actual-key-here" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

如果你用的是Docker部署OpenClaw，需要在docker-compose.yml里把这两个变量传进去：

services: openclaw: image: openclaw/openclaw:2026.3 ports: - "18789:18789" environment: - TAOTOKEN_API_KEY=${TAOTOKEN_API_KEY} - TAOTOKEN_BASE_URL=${TAOTOKEN_BASE_URL} volumes: - ./skills:/root/openclaw-skills - ./models:/root/openclaw-models - ./workspace:/workspace

模型ID的选择上，如果你要做缺陷分类的辅助判断，可以用视觉理解类模型；如果只是生成报告文本，用通用对话模型即可。具体可用模型列表在控制台的模型对话页面可以查到，地址是 https://taotoken.net/api-keys 旁边的模型列表入口。配置完成后，先用一个最简单的curl验证连通性：

curl -s https://taotoken.net/api/v1/models \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" | head -c 500

返回JSON里能看到模型列表就说明Key和网络都正常。这一步看起来简单，但实际项目里我遇到过因为Key权限没开、Base URL写错、环境变量没传进容器导致的401，后面排障章节会详细说。

3. 可复制配置：OpenClaw Skill与YOLO推理参数

这一节是整篇文章的核心，所有配置都可以直接复制到你的项目里。先建目录结构：

mkdir -p /root/openclaw-skills/metal-defect-detect/tools mkdir -p /root/openclaw-models mkdir -p /workspace/defect-images mkdir -p /workspace/defect-results

3.1 Skill配置文件 skill.json

{ "name": "metal-defect-detect", "version": "1.0.0", "description": "3C金属外壳缺陷检测技能，支持单图检测、批量统计、PLC联动、报告生成", "permissions": { "file.read": ["/workspace/defect-images/*"], "file.write": ["/workspace/defect-results/*"] }, "tools": [ "detect_single", "detect_batch", "plc_control", "generate_report" ], "dependencies": [ "ultralytics>=8.0.0", "opencv-python>=4.10.0", "onnxruntime>=1.19.0", "pymodbus>=3.6.0", "pandas>=2.0.0" ], "config": { "model_path": "/root/openclaw-models/metal_defect_best.onnx", "defect_classes": ["scratch", "dent", "deform", "color_error", "burr"], "conf_threshold": 0.5, "iou_threshold": 0.45, "input_size": 640, "plc_ip": "192.168.1.10", "plc_port": 502, "plc_register_ok": 100, "plc_register_ng": 101, "plc_register_stop": 102 } }

注意这里的conf_threshold和iou_threshold是检测阶段的参数，分类阈值在后面的分类脚本里单独控制。PLC寄存器地址要根据你实际使用的PLC型号调整，西门子S7-1200的Modbus地址映射和台达、三菱都不一样，这个必须对照手册确认。

3.2 YOLO训练配置 metal_defect.yaml

path: /root/datasets/metal_defect train: images/train val: images/val test: images/test names: 0: scratch 1: dent 2: deform 3: color_error 4: burr

训练命令和参数：

from ultralytics import YOLO model = YOLO("yolo11n.pt") model.train( data="metal_defect.yaml", epochs=100, imgsz=640, batch=16, device=0, mosaic=1.0, mixup=0.1, hsv_h=0.015, hsv_s=0.7, hsv_v=0.4, degrees=5.0, translate=0.1, scale=0.5, fliplr=0.5, patience=20, save_period=10, project="runs/detect", name="metal_defect_v1" )

训练完成后导出ONNX：

yolo export model=runs/detect/metal_defect_v1/weights/best.pt \ format=onnx opset=12 simplify=True dynamic=False

导出后把onnx文件复制到/root/openclaw-models/metal_defect_best.onnx。INT8量化可以用ONNX Runtime的量化工具做，但工业场景建议先验证FP32模型的精度，量化后如果精度掉超过1个点，就回退到FP16。

3.3 分类阈值与分拣联动脚本

检测到缺陷后需要做分类分级，这里用置信度和缺陷面积双条件判断：

def classify_defect(confidence, bbox_area, class_name): """ 缺陷分级规则： - 严重：置信度>0.8 或 面积>100像素 - 中等：置信度>0.6 或 面积>50像素 - 轻微：其余 """ if confidence > 0.8 or bbox_area > 100: return "严重" elif confidence > 0.6 or bbox_area > 50: return "中等" else: return "轻微" def decide_action(defect_level, consecutive_serious): """ 分拣决策： - 无缺陷：放行 - 轻微/中等：放行并记录 - 严重：NG分拣 - 连续3件严重：停机告警 """ if defect_level is None: return {"action": "pass", "plc_register": 100, "value": 1} if defect_level == "严重": if consecutive_serious >= 3: return {"action": "stop", "plc_register": 102, "value": 1} return {"action": "reject", "plc_register": 101, "value": 1} return {"action": "pass", "plc_register": 100, "value": 1}

PLC联动用pymodbus实现：

from pymodbus.client import ModbusTcpClient def plc_write(ip, port, register, value): client = ModbusTcpClient(ip, port=port) if not client.connect(): return {"code": -1, "message": "PLC连接失败"} try: result = client.write_register(register, value) return {"code": 0, "message": "写入成功", "result": str(result)} finally: client.close()

溯源记录用JSON Lines格式追加写入，每件产品一条记录：

import json from datetime import datetime def write_trace(product_id, image_path, detections, action): record = { "product_id": product_id, "timestamp": datetime.now().isoformat(), "image_path": image_path, "defect_count": len(detections), "defects": detections, "action": action } with open("/workspace/defect-results/trace.jsonl", "a", encoding="utf-8") as f: f.write(json.dumps(record, ensure_ascii=False) + "\n")

4. 验证请求：跑通检测→分类→分拣→溯源全链路

配置写完后必须做端到端验证，不能只看单个脚本能不能跑。准备一张样例图放到/workspace/defect-images/sample_001.jpg，然后按顺序执行。

第一步，验证YOLO推理：

cd /root/openclaw-skills/metal-defect-detect/tools python detect_single.py /workspace/defect-images/sample_001.jpg

预期输出是一个JSON，包含total_defects、detections数组，每个detection有class_name、confidence、defect_level、bbox。如果返回{"code": -1, "message": "图像读取失败"}，检查图片路径和权限。

第二步，验证分类分级。在detect_single.py的输出里确认defect_level字段是否正确。你可以手动改一下conf_threshold，比如从0.5改成0.3，看检测数量是否增加，以此确认阈值生效。

第三步，验证PLC联动。如果没有真实PLC，可以用Modbus模拟器：

pip install pymodbus python -m pymodbus.server start --modbus-server tcp --port 502

然后调用plc_control工具，观察模拟器日志里是否有寄存器写入记录。有真实PLC的话，用Modbus Poll或者PLC编程软件监控寄存器值变化。

第四步，验证溯源记录。执行完检测后检查trace.jsonl：

tail -n 5 /workspace/defect-results/trace.jsonl | python -m json.tool

每条记录应该包含product_id、timestamp、defects、action。如果action是reject，说明分拣逻辑生效了。

第五步，在OpenClaw控制台里把整个流程串起来。进入 http://localhost:18789 的Skill管理页面，安装metal-defect-detect技能，然后在智能体对话里输入“检测sample_001.jpg并执行分拣”，观察OpenClaw是否依次调用了detect_single、classify、plc_control、write_trace。这一步能跑通，说明整条链路已经闭环。

验证时重点核对三个东西：检测输出的bbox坐标是否在原图范围内、分类等级是否和置信度匹配、PLC寄存器地址是否和实际接线一致。我见过最多的问题是bbox坐标偏移，通常是预处理里letterbox的padding计算写错了，导致还原时坐标对不上。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

工业现场环境复杂，报错五花八门，这里列几个最高频的。

401 Unauthorized：调用TaoToken API时返回401，九成是Key问题。先确认环境变量是否传进了容器：

docker exec -it openclaw env | grep TAOTOKEN

如果没有输出，说明docker-compose.yml里没写environment或者没重启容器。如果有输出但仍然是401，检查Key是否被禁用、是否复制时带了空格、Base URL是否写成了带UTM的地址。正确地址是https://taotoken.net/api，不要加任何查询参数。

local proxy failed：这个报错通常出现在OpenClaw尝试调用外部服务时。检查边缘主机的DNS和路由，确认能解析taotoken.net。如果是内网环境，需要在网关做域名白名单。另外检查系统时间是否准确，时间偏差超过5分钟会导致TLS握手失败。

reading choices 报错：这个一般出现在解析模型返回结果时。如果你用的是兼容OpenAI格式的接口，返回结构里choices字段可能为空或者格式不对。先打印原始response：

import requests resp = requests.post( f"{BASE_URL}/v1/chat/completions", headers={"Authorization": f"Bearer {API_KEY}"}, json={"model": "your-model", "messages": [{"role": "user", "content": "test"}]} ) print(resp.status_code) print(resp.text[:500])

看返回体里是error还是choices。如果是error，按error.message排查；如果是choices为空，检查model ID是否正确。

OAuth相关报错：如果你在OpenClaw里配置了OAuth类型的模型接入，报错通常和token刷新有关。检查refresh_token是否过期、回调地址是否和注册时一致。工业场景建议直接用API Key模式，少一层OAuth就少一个故障点。

ONNX Runtime报错：常见的是Invalid input name或Got invalid dimensions。前者检查session.get_inputs()[0].name是否和推理时传的key一致；后者检查输入尺寸是否是640×640、通道顺序是否是CHW。用Netron打开onnx文件看一眼输入输出shape，比猜快得多。

PLC连接超时：pymodbus连接失败先ping一下PLC的IP，然后确认502端口是否开放。西门子PLC默认可能不开启Modbus TCP，需要在硬件组态里启用。另外注意单元ID（slave id），有些PLC默认是1，有些是255，写错了就连不上。

6. 语义一致CTA：从跑通到长期运行

这套方案跑通验证之后，下一步就是把它变成产线日常运行的系统。如果你需要长期做编码和Agent编排，建议用Coding Plan，地址是 https://taotoken.net/api 里的coding-plan入口，适合需要持续迭代Skill、维护多条产线配置的场景。如果只是偶尔调用模型做辅助判断，用API Keys按量付费就够了，入口在 https://taotoken.net/api-keys 。

实际产线运行中，我建议把模型热更新做成标准流程：每月收集一次产线新样本，人工标注后增量训练，导出ONNX后替换/root/openclaw-models/下的文件，然后通过OpenClaw的Skill重载机制生效，不需要停线。溯源数据定期归档，trace.jsonl按天切割，避免单文件过大影响查询。

最后说一个容易被忽略的点：产线质检系统的价值不在于单次检测多准，而在于长期运行中的稳定性和可追溯性。把每次检测的原始图、推理结果、分拣动作、时间戳都完整记录下来，出了问题能倒查，模型迭代有数据支撑，这才是工业AI质检和实验室demo的本质区别。