sudo apt install chromium-browser

Captcha Auto Skill - 混合模式 v1.0.7

利用 本地 OCR + 视觉大模型降级 智能识别网页验证码，平衡成本与准确率。

实测成功率：6/6 (100%) - 已在多个真实网站验证（国家统计局、Telerik、Digivarsity 等）

---

⚠️ 重要：安装路径说明

Clawhub 默认安装到当前工作目录的 ./skills 子目录！

✅ 正确的安装方式

bash

方式 1：进入 workspace 目录安装（推荐）

cd ~/.openclaw/workspace
clawhub install captcha-auto

方式 2：使用 --workdir 参数（任何目录都可以）

clawhub install captcha-auto --workdir ~/.openclaw/workspace

方式 3：设置环境变量（永久生效）

export CLAWHUB_WORKDIR=~/.openclaw/workspace clawhub install captcha-auto

❌ 错误的安装方式

bash

不要在 home 目录直接运行！

cd ~
clawhub install captcha-auto # 会安装到 ~/skills/captcha-auto ❌

验证安装位置

bash

正确位置

ls -la ~/.openclaw/workspace/skills/captcha-auto/

如果装错了（在 ~/skills/），删除并重新安装

rm -rf ~/skills/captcha-auto cd ~/.openclaw/workspace clawhub install captcha-auto

---

---

⚠️ 安全与隐私警告

安装前请仔细阅读：

🔒 1. 截图会发送到第三方 API

• - 本技能会截取网页全屏截图并发送到阿里云 DashScope API
• ❌ 不要在包含密码、银行卡、个人信息的页面使用
• ✅ 仅在验证码页面使用
• 📸 截图仅用于 API 识别，不会存储或上传到其他服务

🔑 2. 必需配置 API Key

• - 环境变量：VISIONAPIKEY
• 或配置文件：~/.openclaw/openclaw.json
• 或命令行参数：--api-key
• ✅ 无硬编码凭证 - API Key 完全由用户控制

🌐 3. 需要 Chrome 浏览器

• - 系统必须安装 Google Chrome 或 Chromium
• 支持 macOS、Linux、Windows

---

⚠️ 必需配置

视觉模型 API（降级方案必需）

本 Skill 需要阿里云千问 3 VL Plus API Key，用于当本地 OCR 失败时的降级识别。

推荐配置（阿里云千问 3 VL Plus）：

bash
export VISIONAPIKEY=sk-your-api-key
export VISIONBASEURL=https://dashscope.aliyuncs.com/compatible-mode/v1
export VISION_MODEL=qwen3-vl-plus

说明：

• - qwen3-vl-plus 是阿里云千问 3 视觉模型，国产性价比最高的视觉模型
• Base URL 使用阿里云 DashScope 兼容模式
• API Key 需在阿里云 DashScope 控制台申请

其他配置方式

OpenClaw 配置

编辑 ~/.openclaw/openclaw.json：

json
{
models: {
providers: {
bailian: {
baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1,
apiKey: sk-your-api-key
}
}
}
}

命令行参数

bash
node scripts/run.mjs --url=https://example.com --api-key=sk-xxx --model=qwen3-vl-plus

---

功能特性

• - 🎯 混合识别 - 本地 Tesseract OCR 优先，失败自动降级视觉模型
• 💰 成本优化 - 简单验证码本地解决（零成本），复杂情况用视觉模型
• 🔍 自动定位 - 智能查找验证码输入框和提交按钮（支持 iframe）
• ✍️ 自动填写 - 识别后自动填写并提交
• 📸 全程记录 - 截图保存每一步操作
• 🌐 通用适配 - 支持任何包含验证码的网页
• ✅ 实测验证 - 已在 6 个真实网站测试，成功率 100%

🧪 测试成功案例

网站	验证码类型	结果
captcha.com/demos	标准文本	✅
captcha-generator-basiakedz.netlify.app

随机文本 | ✅ | | tjy.stats.gov.cn (国家统计局) | 数字验证码 | ✅ | | solvecaptcha.com/demo | 字母数字混合 | ✅ | | demos.telerik.com/aspnet-ajax/captcha | ASP.NET 验证码 | ✅ | | aibe.digivarsity.online | 用户认证验证码 | ✅ |

---

快速开始

1. 从 Clawhub 安装

重要：必须在 ~/.openclaw/workspace 目录下运行安装命令！

bash

✅ 正确：在 workspace 目录安装

cd ~/.openclaw/workspace
clawhub install captcha-auto

❌ 错误：在 home 目录安装（会装到 ~/skills/）

cd ~ clawhub install captcha-auto # 不要这样！

验证安装位置：
bash
ls -la ~/.openclaw/workspace/skills/captcha-auto/

2. 安装依赖

bash
cd ~/.openclaw/workspace
npm install

3. 配置视觉模型 API Key

bash
export VISIONAPIKEY=sk-your-api-key
export VISIONBASEURL=https://dashscope.aliyuncs.com/compatible-mode/v1
export VISION_MODEL=qwen3-vl-plus

3. 运行

bash
node skills/captcha-auto/scripts/run.mjs --url=https://example.com/login

4. 查看结果

运行后生成截图文件（保存在 ~/.openclaw/workspace/）：

• - smartcaptchapage.png - 原始页面截图
• smartcaptchafilled.png - 填写验证码后的截图
• smartcaptcharesult.png - 提交后的结果截图

---

使用方法

从 Clawhub 安装（再次强调安装位置）

bash

⚠️ 必须在 ~/.openclaw/workspace 目录下运行！

cd ~/.openclaw/workspace
clawhub install captcha-auto

基本用法

bash

混合模式（本地 OCR 优先，失败降级视觉模型）

node skills/captcha-auto/scripts/run.mjs --url=https://example.com/login

自定义配置

bash

指定输出前缀

node scripts/run.mjs --url=https://example.com --prefix=my_login

直接使用视觉模型（跳过本地 OCR）

node scripts/run.mjs --url=https://example.com --skip-local

命令行覆盖配置

node scripts/run.mjs --url=https://example.com --api-key=sk-xxx --model=gpt-4o

JSON 输出（方便程序解析）

node scripts/run.mjs --url=https://example.com --json

在其他脚本中使用

javascript
import { recognizeCaptcha } from ./skills/captcha-auto/index.mjs;

const result = await recognizeCaptcha({
url: https://example.com/login,
outputPrefix: my_test,
apiKey: sk-xxx,
baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1,
model: qwen3-vl-plus
});

if (result.success) {
console.log(✅ 验证码：${result.text});
console.log(识别方式：${result.method});
} else {
console.error(❌ 失败：${result.error});
}

---

输出格式

人类可读模式（默认）

🤖 Captcha Auto Skill v1.0.2 (混合模式)
============================================================
目标：https://example.com/login
视觉模型：qwen3-vl-plus
============================================================

🔍 尝试本地 Tesseract OCR 识别...
识别进度：45%
识别结果：ABC123 (置信度：52.3%)
⚠️ 本地 OCR 置信度过低，需要降级到视觉模型
⚠️ 本地 OCR 不可靠，降级到视觉模型...
🧠 降级到视觉模型识别...
✅ 视觉模型识别成功：ABC