C

Captcha Auto

captcha-auto

🌐 English

智能验证码自动识别 Skill - 混合模式（本地 Tesseract OCR + 阿里云千问 3 VL Plus）。支持两阶段输入框查找、安全隐私警告。用于网页自动化中的验证码识别、填写和提交。

数据来源：ClawHub。在 ClawSkills 查看

1.1k下载量

0收藏数

5浏览量

安装

选择你使用的 Agent

方法一：命令行安装（推荐）

关于 Captcha Auto

--- name: captcha-auto description: 智能验证码自动识别 Skill - 混合模式（本地 Tesseract OCR + 阿里云千问 3 VL Plus）。支持两阶段输入框查找、安全隐私警告。用于网页自动化中的验证码识别、填写和提交。 ---

Captcha Auto Skill - 混合模式 v1.0.7

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

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

---

⚠️ 重要：安装路径说明

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

✅ 正确的安装方式

# 方式 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

❌ 错误的安装方式

# 不要在 home 目录直接运行！
cd ~
clawhub install captcha-auto  # 会安装到 ~/skills/captcha-auto ❌

验证安装位置

# 正确位置
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

环境变量：VISION_API_KEY
或配置文件：~/.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）：

export VISION_API_KEY="sk-your-api-key"
export VISION_BASE_URL="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：

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

命令行参数

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 目录下运行安装命令！

# ✅ 正确：在 workspace 目录安装
cd ~/.openclaw/workspace
clawhub install captcha-auto

# ❌ 错误：在 home 目录安装（会装到 ~/skills/）
cd ~
clawhub install captcha-auto  # 不要这样！

验证安装位置：

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

2. 安装依赖

cd ~/.openclaw/workspace
npm install

3. 配置视觉模型 API Key

export VISION_API_KEY="sk-your-api-key"
export VISION_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export VISION_MODEL="qwen3-vl-plus"

3. 运行

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

4. 查看结果

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

smart_captcha_page.png - 原始页面截图
smart_captcha_filled.png - 填写验证码后的截图
smart_captcha_result.png - 提交后的结果截图

---

使用方法

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

# ⚠️ 必须在 ~/.openclaw/workspace 目录下运行！
cd ~/.openclaw/workspace
clawhub install captcha-auto

基本用法

# 混合模式（本地 OCR 优先，失败降级视觉模型）
node skills/captcha-auto/scripts/run.mjs --url="https://example.com/login"

自定义配置

# 指定输出前缀
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

在其他脚本中使用

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 不可靠，降级到视觉模型...
🧠 降级到视觉模型识别...
✅ 视觉模型识别成功：ABC123

✅ 完成！验证码：ABC123
识别方式：视觉模型

JSON 模式（`--json`）

{
  "success": true,
  "text": "ABC123",
  "method": "vision",
  "analysis": {
    "captchaText": "ABC123",
    "captchaLocation": "登录框右侧",
    "inputLocation": "验证码图片左侧",
    "buttonLocation": "输入框下方",
    "buttonText": "登录"
  },
  "screenshots": {
    "page": "/Users/xxx/.openclaw/workspace/smart_captcha_page.png",
    "filled": "/Users/xxx/.openclaw/workspace/smart_captcha_filled.png",
    "result": "/Users/xxx/.openclaw/workspace/smart_captcha_result.png"
  },
  "metadata": {
    "url": "https://example.com/login",
    "model": "qwen3-vl-plus",
    "timestamp": "2026-02-24T12:00:00Z"
  }
}

---

工作原理

1. 打开目标网页并截图
2. 第一层：本地 Tesseract OCR 识别
   - 置信度 >= 60% → 使用结果
   - 置信度 < 60% → 降级
3. 第二层：视觉模型分析截图
   - 调用阿里云千问 3 VL Plus
   - 返回验证码文字和位置信息
4. 自动查找输入框并填写
5. 自动点击提交按钮
6. 截图记录结果

---

优势与局限

优势

✅ 成本优化 - 简单验证码本地解决（零 token 消耗）
✅ 高成功率 - 视觉模型兜底，复杂验证码也能处理
✅ 通用性强 - 无需分析网页结构，自动适配
✅ 高性价比 - 使用阿里云千问 3 VL Plus（国产性价比最高）

局限

⚠️ 需要 API Key - 视觉模型降级需要配置第三方 API
⚠️ 本地 OCR 限制 - 严重扭曲/干扰线的验证码本地识别率低
⚠️ Canvas 验证码 - 某些动态绘制的验证码可能不支持
⚠️ Token 成本 - 视觉模型调用消耗 token（约 0.01-0.05 元/次）

---

故障排除

本地 OCR 总是失败

原因：验证码过于复杂（扭曲、干扰线、背景噪声）

解决：使用 --skip-local 直接用视觉模型

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

API 401 错误

检查：VISION_API_KEY 是否正确

echo $VISION_API_KEY

API 404 错误

检查：VISION_BASE_URL 是否正确

echo $VISION_BASE_URL
# 应为：https://dashscope.aliyuncs.com/compatible-mode/v1

找不到 Chrome 浏览器

macOS：安装 Google Chrome

# 下载地址：https://www.google.com/chrome/

Linux：安装 Chromium

sudo apt install chromium-browser

---

版本历史

v1.0.7 - 统一版本号、完善安全警告（强调无硬编码凭证）、添加跨平台支持说明
v1.0.6 - 更新文档：添加测试成功案例表、增强安全警告说明、修复路径引用
v1.0.5 - 优化输入框查找逻辑、改进按钮点击策略
v1.0.4 - 添加 iframe 支持、优化 accessibility 分析
v1.0.3 - 修复元数据匹配（env: VISION_API_KEY, bins: node + google-chrome）；添加安全与隐私警告（截图会发送到第三方 API）；运行时显示安全提示
v1.0.2 - 混合模式（本地 Tesseract OCR + 阿里云千问 3 VL Plus 视觉模型降级）；两阶段输入框查找策略；支持无 placeholder 的验证码输入框

---

依赖

必需

Node.js >= 18 - 运行环境
playwright-core - 浏览器自动化
tesseract.js - 本地 OCR 引擎
Chrome/Chromium - 系统需安装浏览器
视觉模型 API Key - Qwen/GPT-4V/Claude 等（降级必需）

环境检查

# 检查 Node.js
node --version  # 需 >= 18

# 检查 Chrome（macOS）
ls /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome

# 检查 API Key
echo $VISION_API_KEY

---

授权

MIT

Prompt 示例

安装 Captcha Auto 后，可以对 AI 说这些话来触发它

U

Help me get started with Captcha Auto

A

Explains what Captcha Auto does, walks through the setup, and runs a quick demo based on your current project

U

Use Captcha Auto to intelligent verification code automatic recognition Skill - hybrid ...

A

Invokes Captcha Auto with the right parameters and returns the result directly in the conversation

U

What can I do with Captcha Auto in my documents & notes workflow?

A

Lists the top use cases for Captcha Auto, with example commands for each scenario

常见问题

如何安装 Captcha Auto？▾

将技能文件夹放到 ~/.claude/skills/captcha-auto/ 目录（个人级，所有项目可用），或 .claude/skills/captcha-auto/（项目级）。重启 AI 客户端后，用 /captcha-auto 主动调用，或让 AI 根据上下文自动发现并使用。

Captcha Auto 支持哪些 AI 平台？▾

Captcha Auto 支持 Claude、Cursor、OpenClaw，可与这些 AI 平台无缝集成，扩展其能力。

Captcha Auto 是免费的吗？▾

Captcha Auto 可免费安装使用。请查阅仓库了解许可证信息。

Captcha Auto 有什么功能？▾