Tự động hóa PicoClaw: Hướng dẫn tích hợp CapSolver API

Khi trợ lý AI của bạn tự động hóa các nhiệm vụ trên web, CAPTCHAs là rào cản số một. Các trang được bảo vệ từ chối gửi, quy trình đăng nhập bị treo, và toàn bộ quy trình tự động hóa dừng lại chờ người dùng click vào hộp kiểm hoặc xác định đèn giao thông.

PicoClaw là một trợ lý AI cá nhân siêu nhẹ viết bằng Go, chạy trên phần cứng $10 với dưới 10MB RAM. Nó kết nối với các nền tảng tin nhắn bạn đang sử dụng, bao gồm công cụ exec tích hợp cho phép đại diện viết và chạy script tự động.

CapSolver cung cấp API giải CAPTCHA dựa trên AI. Kết hợp khả năng thực thi script của PicoClaw với API REST của CapSolver, đại diện của bạn có thể phát hiện CAPTCHAs, giải chúng, chèn token và gửi biểu mẫu — tất cả mà không cần can thiệp của con người.

Điều tuyệt vời nhất là bạn chỉ cần nói với đại diện điều bạn muốn làm bằng ngôn ngữ thông thường. Nó sẽ viết một script Playwright, trích xuất sitekey, gọi CapSolver, chèn token và gửi biểu mẫu — tất cả tự động. Và vì PicoClaw là Go đã biên dịch, toàn bộ lớp điều phối vừa vặn trong 10MB RAM trên bo mạch RISC-V $10.

PicoClaw là gì?

PicoClaw là một trợ lý AI cá nhân siêu nhẹ được xây dựng bằng Go 1.25.7 thông qua một quy trình tự khởi động đáng kinh ngạc: chính đại diện AI đã điều phối toàn bộ quá trình chuyển đổi kiến trúc từ Python, tạo ra 95% mã nguồn cốt lõi một cách tự động với sự điều chỉnh từ con người.

Số liệu

Thông điệp của PicoClaw nói lên tất cả: $10 phần cứng. 10MB RAM. 1 giây khởi động.

Tính năng chính

• Siêu nhẹ: Dung lượng bộ nhớ dưới 10MB — nhỏ hơn 99% so với các đại diện TypeScript tương đương
• Tính di động thực sự: Tập tin nhị phân đơn lẻ cho các kiến trúc RISC-V, ARM64 và x86_64
• Công cụ tích hợp: Đại diện có thể đọc/ghi tệp, thực thi lệnh shell, tìm kiếm web, tải trang, gửi tin nhắn đa kênh, lập lịch công việc định kỳ, và thậm chí tương tác với phần cứng I2C/SPI
• Không phụ thuộc nhà cung cấp: Hoạt động với OpenAI, Anthropic, DeepSeek, Gemini, Qwen, Moonshot, Groq, vLLM, Ollama, Cerebras, Mistral, NVIDIA và các nhà cung cấp cổng như OpenRouter
• Hệ thống kỹ năng: Mở rộng khả năng với các tệp SKILL.md sử dụng frontmatter JSON hoặc YAML
• Hệ thống bộ nhớ: Ghi chú hàng ngày và bộ nhớ dài hạn bền vững qua các cuộc trò chuyện
• Công cụ phần cứng: Công cụ I2C và SPI để tương tác trực tiếp với thiết bị nhúng — độc quyền của PicoClaw

Công cụ ExecTool

ExecTool của PicoClaw (được định nghĩa trong pkg/tools/shell.go) là yếu tố làm cho tự động hóa trình duyệt có thể thực hiện được. Đây là môi trường thực thi shell được cách ly cẩn thận với 27+ mẫu từ chối bảo mật được biên dịch thành regexp Go, thời gian chờ mặc định 60 giây, giới hạn đường dẫn thư mục làm việc và phát hiện các cuộc tấn công xâm nhập đường dẫn.

Khi bạn yêu cầu đại diện tương tác với một trang web, nó sẽ:

1. Viết một script Playwright bằng công cụ write_file
2. Chạy nó bằng công cụ exec (gọi sh -c trên Linux)
3. Đọc đầu ra (stdout + stderr, giới hạn 10KB)
4. Báo cáo kết quả lại cho bạn qua kênh trò chuyện

Phương thức guardCommand() của công cụ kiểm tra mỗi lệnh với các mẫu từ chối đã biên dịch trước khi thực thi, đảm bảo giới hạn đường dẫn thư mục làm việc và phát hiện các nỗ lực xâm nhập đường dẫn. Hãy nghĩ đến nó như là quyền truy cập dòng lệnh được cách ly — đại diện có thể chạy script Node.js và cài đặt gói cục bộ, nhưng không thể rm -rf, sudo hoặc docker run.

Vòng lặp Đại diện

Logic cốt lõi nằm trong pkg/tools/toolloop.go — một chu kỳ chặt chẽ: Gọi LLM -> Trích xuất các lệnh công cụ -> Thực thi công cụ -> Gắn kết kết quả -> lặp lại cho đến khi có phản hồi văn bản cuối cùng (hoặc MaxIterations, mặc định là 20). Vòng lặp này được chia sẻ giữa đại diện chính (pkg/agent/loop.go) và các subagent nền tảng qua spawn.

CapSolver là gì?

CapSolver là dịch vụ giải CAPTCHA hàng đầu cung cấp giải pháp dựa trên AI để vượt qua các thách thức CAPTCHA khác nhau. Với hỗ trợ nhiều loại CAPTCHA và thời gian phản hồi nhanh, CapSolver tích hợp mượt mà vào quy trình tự động hóa.

Các loại CAPTCHA được hỗ trợ

• reCAPTCHA v2 (dựa trên hình ảnh và không nhìn thấy)
• reCAPTCHA v3 & v3 Enterprise
• Cloudflare Turnstile
• Cloudflare 5-second Challenge
• AWS WAF CAPTCHA

Tại sao cách tiếp cận của PicoClaw lại khác biệt

Hầu hết các tích hợp giải CAPTCHA đều rơi vào hai nhóm: tích hợp API cấp mã, nơi bạn viết một lớp dịch vụ chuyên dụng, hoặc mở rộng trình duyệt nơi một phần mở rộng Chrome xử lý mọi thứ một cách vô hình. PicoClaw chọn cách tiếp cận thứ ba: tích hợp API được điều phối bởi đại diện trên phần cứng cạnh biên.

Chính đại diện AI sẽ tự động điều phối toàn bộ quy trình giải CAPTCHA — viết script Playwright, trích xuất sitekey, gọi API CapSolver và chèn token giải pháp — tất cả thông qua các script mà nó viết và thực thi theo thời gian thực. Quan trọng nhất, bộ điều phối dựa trên Go thực hiện mọi việc này chỉ tiêu tốn dưới 10MB RAM.

Ưu thế của thiết bị cạnh biên

Bạn có thể chạy tự động hóa phá CAPTCHA trên phần cứng có giá dưới một ly cà phê. Một bo mạch LicheeRV-Nano giá $9.90 chạy PicoClaw có thể nhận tin nhắn Telegram, điều phối với API đám mây của CapSolver, chèn token và gửi biểu mẫu — tất cả trong khi sử dụng một phần nhỏ RAM 64MB của bo mạch. Việc xử lý nặng (nhận diện CAPTCHA) được thực hiện trên máy chủ của CapSolver; PicoClaw chỉ điều phối. Luôn hoạt động 24/7 trên thiết bị kích thước bằng tem thư.

Điểm mấu chốt: Tập tin nhị phân Go của PicoClaw quá nhẹ để chạy trên phần cứng mà hầu hết các khung không thể khởi động — nhưng nó vẫn có thể điều phối toàn bộ quy trình giải CAPTCHA thông qua script Playwright và API REST của CapSolver.

Yêu cầu

Lưu ý: Các ví dụ dưới đây đã được kiểm tra trên Ubuntu 22.04 / 24.04. Các lệnh sử dụng apt và bash — điều chỉnh cho phân phối của bạn nếu cần. Đối với thiết bị cạnh biên (RISC-V, ARM), biên dịch chéo PicoClaw trên máy xây dựng của bạn hoặc tải xuống tập tin nhị phân đã xây dựng từ trang phát hành.

Trước khi thiết lập tích hợp, hãy đảm bảo bạn có:

1. Ubuntu 22.04+ (hoặc bất kỳ phân phối Linux nào — tập tin nhị phân đơn lẻ của PicoClaw chạy ở bất kỳ đâu)
2. Go 1.25.7+ đã cài đặt (chỉ cần thiết lập khi xây dựng từ nguồn)
3. PicoClaw đã cài đặt và chạy (tập tin nhị phân đã xây dựng hoặc make build)
4. Tài khoản CapSolver với khóa API (đăng ký tại đây)
5. Node.js 18+ đã cài đặt (để chạy script Playwright qua công cụ exec)
6. Playwright đã cài đặt trong thư mục làm việc của bạn

Hướng dẫn cài đặt từng bước

Bước 1: Cài đặt PicoClaw

Tùy chọn A: Tập tin nhị phân đã xây dựng (Nhanh nhất)

# Tải xuống phiên bản mới nhất cho nền tảng của bạn
# Thay thế v0.1.1 bằng phiên bản mới nhất từ trang Releases
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-amd64
chmod +x picoclaw-linux-amd64
sudo mv picoclaw-linux-amd64 /usr/local/bin/picoclaw

# Chạy trình hướng dẫn cài đặt tương tác
picoclaw onboard

Tùy chọn B: Xây dựng từ nguồn

git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
make build
make install

# Khởi tạo cấu hình và thư mục làm việc
picoclaw onboard

Điều này tạo ra ~/.picoclaw/config.json, ~/.picoclaw/workspace/ (script, kỹ năng và bộ nhớ).

Bước 2: Thiết lập khóa API CapSolver của bạn

Thêm khóa API CapSolver của bạn dưới dạng biến môi trường:

export CAPSOLVER_API_KEY="CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Bạn có thể nhận khóa API từ bảng điều khiển CapSolver.

Đối với cấu hình bền vững, thêm nó vào ~/.bashrc hoặc ~/.zshrc.

Bước 3: Cài đặt công cụ tự động hóa trình duyệt

Cài đặt Playwright và các phụ thuộc hệ thống trên Ubuntu:

# Cài đặt phụ thuộc trình duyệt Playwright (Ubuntu)
sudo apt install -y libnss3 libatk-bridge2.0-0 libdrm2 libxcomposite1 \
  libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libasound2t64

# Cài đặt Playwright trong thư mục làm việc của PicoClaw
cd ~/.picoclaw/workspace
npm init -y
npm install playwright
npx playwright install chromium

Lưu ý thiết bị cạnh biên: Trên các bo mạch hạn chế tài nguyên, bạn có thể muốn cài đặt Chromium trên máy mạnh hơn và chỉ định PicoClaw kết nối đến trình duyệt từ xa thông qua browserType.connect() của Playwright. Bản thân đại diện PicoClaw chỉ cần ~10MB RAM; trình duyệt là phần nặng.

Bước 4: Cấu hình ExecTool cho tự động hóa trình duyệt

ExecTool của PicoClaw có các mẫu từ chối tích hợp để đảm bảo an toàn. Mặc định hoạt động tốt cho tự động hóa CAPTCHA: node, npx và npm install cục bộ đều được phép. Chỉ có các lệnh nguy hiểm như npm install -g, sudo, docker run bị chặn. Không cần thay đổi cấu hình cho quy trình thông thường.

Bước 5: Khởi động cổng kết nối

# Khởi động dịch vụ kênh (Telegram, Discord, v.v.)
picoclaw gateway

# Hoặc để kiểm tra tương tác
picoclaw agent

Bước 6: Xác minh cài đặt

Gửi một tin nhắn kiểm tra đến đại diện của bạn qua bất kỳ kênh nào đã kết nối:

Bạn có những công cụ nào sẵn có?

Đại diện nên liệt kê exec trong số các công cụ — đây là cách nó chạy script tự động hóa trình duyệt. Bạn cũng có thể xác minh quyền truy cập Node.js:

Chạy: node --version

Đại diện nên thực thi lệnh này qua công cụ exec và trả về phiên bản Node.js.

Kỹ năng tích hợp CapSolver

PicoClaw sử dụng một hệ thống kỹ năng dựa trên tệp SKILL.md với dữ liệu frontmatter. Các kỹ năng được tải từ ba vị trí theo thứ tự ưu tiên (được xác định trong pkg/skills/loader.go):

1. Kỹ năng trong thư mục làm việc: ~/.picoclaw/workspace/skills/{name}/SKILL.md (cấp dự án, ưu tiên cao nhất)
2. Kỹ năng toàn cục: ~/.picoclaw/skills/{name}/SKILL.md (cấp người dùng)
3. Kỹ năng tích hợp: skills/{name}/SKILL.md (được tích hợp cùng tập tin nhị phân)

Kỹ năng trong thư mục làm việc ghi đè lên kỹ năng toàn cục, và kỹ năng toàn cục ghi đè lên kỹ năng tích hợp. Bộ tải đọc frontmatter dưới dạng JSON hoặc YAML và xây dựng bản tóm tắt XML cho prompt hệ thống.

Tệp kỹ năng (~/.picoclaw/workspace/skills/capsolver/SKILL.md)

---
name: capsolver
description: "Giải CAPTCHAs bằng API REST của CapSolver với Playwright. Hỗ trợ reCAPTCHA v2, reCAPTCHA v3 và Cloudflare Turnstile. Sử dụng khi tự động hóa việc gửi biểu mẫu hoặc tương tác trang web gặp thách thức CAPTCHA."
metadata: {"picoclaw":{"emoji":"🔓","always":true,"requires":{"bins":["node"],"env":["CAPSOLVER_API_KEY"]}}}
---

# CapSolver

## LƯU Ý: Yêu cầu thực thi

Khi người dùng yêu cầu bạn giải CAPTCHA, bạn **phải gọi công cụ ngay lập tức**. Không được trả lời bằng văn bản như "Đang chạy..." hoặc "Tôi sẽ bắt đầu..." hoặc "Tôi đã bắt đầu tự động hóa...".

Hành động đầu tiên của bạn phải là một trong số:
1. Gọi `write_file` để lưu script Node.js, sau đó gọi `exec` để chạy nó
2. Gọi `spawn` với mô tả nhiệm vụ chi tiết để thực thi nền

Nếu bạn chỉ trả lời bằng văn bản mà không gọi công cụ, người dùng sẽ không thấy bất kỳ hành động nào xảy ra. Luôn thực thi.

## Các điểm cuối API

- **Tạo nhiệm vụ**: `POST https://api.capsolver.com/createTask`
- **Lấy kết quả**: `POST https://api.capsolver.com/getTaskResult`

## Loại nhiệm vụ

| CAPTCHA | Loại nhiệm vụ | Vị trí sitekey |
|---|---|---|
| reCAPTCHA v2 | `ReCaptchaV2TaskProxyLess` | Thuộc tính `data-sitekey` |
| reCAPTCHA v3 | `ReCaptchaV3TaskProxyLess` | Gọi `grecaptcha.execute` hoặc nguồn trang |
| Cloudflare Turnstile | `AntiTurnstileTaskProxyLess` | `data-sitekey` trên div Turnstile |

Phiên bản doanh nghiệp: `ReCaptchaV2EnterpriseTaskProxyLess`, `ReCaptchaV3EnterpriseTaskProxyLess`.

## Quy trình làm việc

1. Điều hướng đến trang bằng Playwright (Chromium headless)
2. Trích xuất sitekey từ DOM (`[data-sitekey]`)
3. Gọi `createTask` với sitekey và URL trang
4. Kiểm tra `getTaskResult` mỗi 2 giây cho đến khi `status: "ready"`
5. Chèn token vào trang (trường biểu mẫu ẩn)
6. Gửi biểu mẫu

## Mẫu mã cốt lõi

```javascript
const CAPSOLVER_API_KEY = process.env.CAPSOLVER_API_KEY;

// Bước 1: Tạo nhiệm vụ
const createRes = await fetch('https://api.capsolver.com/createTask', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    clientKey: CAPSOLVER_API_KEY,
    task: {
      type: 'ReCaptchaV2TaskProxyLess',  // hoặc ReCaptchaV3TaskProxyLess, AntiTurnstileTaskProxyLess
      websiteURL: pageUrl,
      websiteKey: siteKey
    }
  })
});
const { taskId } = await createRes.json();

// Bước 2: Kiểm tra kết quả
let token;
while (true) {
  await new Promise(r => setTimeout(r, 2000));
  const res = await fetch('https://api.capsolver.com/getTaskResult', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ clientKey: CAPSOLVER_API_KEY, taskId })
  });
  const result = await res.json();
  if (result.status === 'ready') { token = result.solution.gRecaptchaResponse || result.solution.token; break; }
  if (result.status === 'failed') throw new Error('Giải CAPTCHA thất bại');
}

// Bước 3: Chèn token (reCAPTCHA)
await page.evaluate((t) => {
  document.querySelectorAll('textarea[name="g-recaptcha-response"]')
    .forEach(el => { el.value = t; el.innerHTML = t; });
}, token);
```

Đối với Turnstile, trường token thường là `input[name="cf-turnstile-response"]` và giải pháp nằm trong `result.solution.token`.

## Tài liệu API

Tất cả các loại nhiệm vụ đều yêu cầu `type`, `websiteURL`, `websiteKey`. Các trường tùy chọn thay đổi tùy theo loại:
- **reCAPTCHA v2**: `isInvisible`, `pageAction`, `enterprisePayload`, `apiDomain`
- **reCAPTCHA v3**: `pageAction` (từ `grecaptcha.execute(key, {action: "..."})`)
- **Cloudflare Turnstile**: `metadata.action`, `metadata.cdata`

Điểm chính:

• Frontmatter sử dụng JSON hoặc YAML (pkg/skills/loader.go thử JSON trước, sau đó dùng YAML)
• metadata chứa cấu hình đặc thù của PicoClaw: emoji để hiển thị, always để tự động tải, requires để kiểm tra phụ thuộc
• SkillsLoader.BuildSkillsSummary() tạo bản tóm tắt XML được chèn vào prompt hệ thống
• Phần "Execution Required" buộc gọi công cụ thay vì phản hồi chỉ bằng văn bản

Sau khi tạo kỹ năng, xác minh bằng picoclaw skills — bạn nên thấy capsolver được liệt kê.

Cách hoạt động

Khi bạn yêu cầu PicoClaw tương tác với trang web có bảo vệ CAPTCHA, đây là quy trình đầy đủ từ tin nhắn đến kết quả:

  Tin nhắn của bạn                     Agent PicoClaw (Go, ~10MB RAM)
  ─────────────────────────────────────────────────────────────
  "Hãy truy cập trang đó,           ──► Agent nhận được qua MessageBus
   điền biểu mẫu,                  │ (pkg/bus/bus.go)
   giải CAPTCHA,                  ▼
   và gửi nó"             ContextBuilder chèn kỹ năng
                                   │ (pkg/agent/context.go)
                                   ▼
                              RunToolLoop bắt đầu
                                   │ (pkg/tools/toolloop.go)
                                   ▼
                              Agent ghi script Node.js
                                   │ qua công cụ write_file
                                   ▼
                              ExecTool chạy script
                              ┌────────────────────────────┐
                              │ pkg/tools/shell.go          │
                              │ guardCommand() → 27+ kiểm tra │
                              │ sh -c "node script.js"      │
                              │                             │
                              │  Chromium không giao diện      │
                              │  1. Điều hướng đến trang      │
                              │  2. Trích xuất sitekey       │
                              │  3. POST /createTask ────────── API CapSolver
                              │  4. Poll /getTaskResult ─────── (đám mây)
                              │  5. Chèn token              │
                              │  6. Gửi biểu mẫu             │
                              │  7. Chụp màn hình            │
                              └────────────────────────────┘
                                   │
                                   ▼ stdout trả về (tối đa 10KB)
                              Agent đọc đầu ra
                                   │
                                   ▼
                              "Biểu mẫu đã được gửi thành công!
                               Xác minh thành công!"

Quy trình API CapSolver

Hạt nhân của tích hợp là hai lời gọi API:

1. Tạo nhiệm vụ — Gửi sitekey và URL trang CAPTCHA đến CapSolver:

const response = await fetch('https://api.capsolver.com/createTask', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    clientKey: CAPSOLVER_API_KEY,
    task: {
      type: 'ReCaptchaV2TaskProxyLess',
      websiteURL: pageUrl,
      websiteKey: siteKey
    }
  })
});

2. Kiểm tra kết quả — Kiểm tra mỗi 2 giây cho đến khi CapSolver trả về token đã giải:

const result = await fetch('https://api.capsolver.com/getTaskResult', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    clientKey: CAPSOLVER_API_KEY,
    taskId: taskId
  })
});
// result.solution.gRecaptchaResponse chứa token

3. Chèn token — Thiết lập nó trong trường biểu mẫu ẩn mà reCAPTCHA kỳ vọng:

await page.evaluate((token) => {
  const textarea = document.querySelector('textarea[name="g-recaptcha-response"]');
  if (textarea) {
    textarea.value = token;
    textarea.innerHTML = token;
  }
}, captchaToken);

Ví dụ hoàn chỉnh

Đây là script Node.js thực tế mà agent PicoClaw tạo ra và chạy để giải reCAPTCHA trên trang demo Google. Agent ghi tệp này qua write_file, sau đó chạy nó với exec — tất cả tự động từ một tin nhắn Telegram duy nhất:

const { chromium } = require('playwright');
const https = require('https');

const CAPSOLVER_API_KEY = process.env.CAPSOLVER_API_KEY;
const PAGE_URL = '';

function httpsPost(url, data) {
  return new Promise((resolve, reject) => {
    const req = https.request(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' }
    }, (res) => {
      let body = '';
      res.on('data', chunk => body += chunk);
      res.on('end', () => resolve(JSON.parse(body)));
    });
    req.on('error', reject);
    req.write(JSON.stringify(data));
    req.end();
  });
}

async function solveRecaptcha(siteKey, pageUrl) {
  console.log('Tạo nhiệm vụ CapSolver...');

  const createRes = await httpsPost('https://api.capsolver.com/createTask', {
    clientKey: CAPSOLVER_API_KEY,
    task: {
      type: 'ReCaptchaV2TaskProxyLess',
      websiteURL: pageUrl,
      websiteKey: siteKey
    }
  });

  if (createRes.errorId) {
    throw new Error(`Lỗi CapSolver: ${createRes.errorDescription}`);
  }

  const { taskId } = createRes;
  console.log(`Mã nhiệm vụ: ${taskId}`);

  let token;
  while (true) {
    await new Promise(r => setTimeout(r, 2000));

    const res = await httpsPost('https://api.capsolver.com/getTaskResult', {
      clientKey: CAPSOLVER_API_KEY,
      taskId
    });

    if (res.status === 'ready') {
      token = res.solution.gRecaptchaResponse;
      console.log(`Token nhận được! Độ dài: ${token.length}`);
      break;
    }
    if (res.status === 'failed') {
      throw new Error(`Nhiệm vụ CapSolver thất bại: ${res.errorDescription}`);
    }

    console.log('Đang kiểm tra... trạng thái:', res.status);
  }

  if (!token) throw new Error('Không nhận được token');
  return token;
}

async function main() {
  const browser = await chromium.launch({
    headless: true,
    args: ['--no-sandbox', '--disable-setuid-sandbox']
  });
  const page = await browser.newPage();

  try {
    await page.goto(PAGE_URL, { waitUntil: 'domcontentloaded', timeout: 30000 });
    const siteKey = await page.locator('[data-sitekey]').getAttribute('data-sitekey');
    console.log(`Sitekey: ${siteKey}`);

    const token = await solveRecaptcha(siteKey, PAGE_URL);

    await page.evaluate((t) => {
      document.querySelectorAll('textarea[name="g-recaptcha-response"]')
        .forEach(el => { el.value = t; el.innerHTML = t; });
    }, token);

    await page.locator('input[type="submit"]').click();
    await page.waitForTimeout(3000);

    const body = await page.textContent('body');
    console.log(body.includes('Success') ? 'THÀNH CÔNG!' : 'Kết quả:', body.slice(0, 200));
    await page.screenshot({ path: 'recaptcha_result.png' });
  } finally {
    await browser.close();
  }
}

main().catch(err => {
  console.error('Lỗi:', err.message);
  process.exit(1);
});

Chạy trực tiếp:

CAPSOLVER_API_KEY=CAP-XXX node solve_recaptcha.js

Hoặc để agent PicoClaw xử lý mọi thứ — chỉ cần gửi một tin nhắn trên Telegram:

Giải CAPTCHA tại https://example.com và gửi biểu mẫu.

Agent đọc kỹ năng capsolver, ghi script, chạy nó qua exec, đọc đầu ra và báo cáo lại.

Cách sử dụng

Sau khi cài đặt xong, sử dụng CapSolver với PicoClaw đơn giản chỉ cần gửi một tin nhắn trên bất kỳ kênh nào được kết nối.

Ví dụ 1: Giải CAPTCHA demo

Gửi tin nhắn này đến agent của bạn qua Telegram, Discord, WhatsApp, hoặc bất kỳ kênh nào được kết nối:

Truy cập https://example.com và giải CAPTCHA bằng API CapSolver, sau đó gửi biểu mẫu và cho tôi biết nó có thành công không.

Cái gì xảy ra: Agent đọc kỹ năng capsolver, ghi script Playwright, chạy nó qua exec (điều này vượt qua các kiểm tra guardCommand() và chạy trong vòng 60 giây), script điều hướng trang, trích xuất sitekey, gọi CapSolver, chèn token và gửi. Kết quả được trả về cho bạn qua MessageBus.

Ví dụ 2: Đăng nhập vào trang được bảo vệ

Truy cập https://example.com/login, điền email bằng
"me@example.com" và mật khẩu bằng "mypassword", phát hiện và
giải bất kỳ CAPTCHA nào trên trang, sau đó nhấn Đăng nhập và cho tôi biết
điều gì xảy ra.

Ví dụ 3: Gửi biểu mẫu liên hệ

Mở https://example.com/contact, điền các trường tên, email và
nội dung, giải CAPTCHA, gửi biểu mẫu và cho tôi biết thông báo xác nhận.

Ví dụ 4: Tự động hóa nền bằng Spawn

Đối với các tác vụ kéo dài, sử dụng công cụ spawn (pkg/tools/spawn.go) để phân quyền cho một subagent nền:

Ở nền, truy cập https://example.com/register, tạo tài khoản với thông tin của tôi, giải bất kỳ CAPTCHA nào bạn gặp phải,
và cho tôi biết khi nào nó xong.

Ví dụ 5: Giám sát thiết bị cạnh (Telegram trên bo $10)

Nếu PicoClaw đang chạy trên bo LicheeRV-Nano hoặc tương tự, kết hợp với công cụ cron:

Mỗi giờ, kiểm tra https://example.com/status — nếu có cổng CAPTCHA, giải nó và báo cáo nội dung trang trạng thái.

Tại sao điều này hoạt động

Agent PicoClaw có tất cả các công cụ cần thiết để giải CAPTCHA tự động:

• exec (pkg/tools/shell.go) — thực thi shell được sandbox hóa với 27+ mẫu từ chối an ninh
• write_file / read_file (pkg/tools/filesystem.go) — quản lý script trong không gian làm việc
• spawn (pkg/tools/spawn.go) — phân quyền cho subagent nền cho các tác vụ kéo dài
• web_fetch (pkg/tools/web.go) — tải nội dung trang để phân tích DOM
• Hệ thống kỹ năng (pkg/skills/loader.go) — kỹ năng capsolver cung cấp tài liệu API trong ngữ cảnh
• Bộ nhớ (pkg/agent/memory.go) — lưu trữ các phương pháp thành công qua các phiên

Kết quả hiệu năng

Chúng tôi đã kiểm tra tích hợp trên trang demo reCAPTCHA v2 của Google qua bot Discord trực tiếp trên Ubuntu 24.04. Agent PicoClaw (sử dụng glm-4.7 qua z.ai) nhận tin nhắn Discord, tự động ghi script Playwright, giải CAPTCHA và báo cáo lại — không cần can thiệp của con người:

Ghi chú thiết bị cạnh: Trên các bo có RAM hạn chế (ví dụ: LicheeRV-Nano $9.90 với 64MB), PicoClaw itself dễ dàng vừa (~8MB) nhưng Chromium cần 100-300MB. Sử dụng connect() của Playwright để chuyển trình duyệt sang máy có sức mạnh cao hơn trong khi giữ agent nhẹ nhàng trên thiết bị cạnh.

Xử lý sự cố

"Không tìm thấy mô-đun 'playwright'"

Playwright không được cài đặt trong không gian làm việc. Chạy:

cd ~/.picoclaw/workspace && npm install playwright && npx playwright install chromium

Thiếu thư viện trình duyệt trên Ubuntu

Nếu Chromium không thể khởi động với lỗi về thư viện chia sẻ, cài đặt các phụ thuộc hệ thống:

sudo apt install -y libnss3 libatk-bridge2.0-0 libdrm2 libxcomposite1 \
  libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libasound2t64

Mẫu từ chối của ExecTool chặn npm install

Các mẫu từ chối của PicoClaw chặn npm install -g (cài đặt toàn cục), sudo, và apt install, nhưng cho phép npm install cục bộ, node script.js, và npx playwright install. Nếu bạn thấy "Lệnh bị chặn bởi bảo vệ an toàn", bạn có thể tắt mẫu từ chối hoặc cung cấp danh sách cho phép tùy chỉnh trong ~/.picoclaw/config.json:

{ "tools": { "exec": { "enable_deny_patterns": false } } }

Hoặc sử dụng danh sách cho phép tùy chỉnh loại bỏ chỉ các mẫu bạn muốn chặn.

Thời gian chờ giải CAPTCHA

• Kiểm tra khóa API CapSolver của bạn có hợp lệ không
• Kiểm tra số dư tài khoản CapSolver tại capsolver.com/dashboard
• Script kiểm tra mỗi 2 giây cho đến khi CapSolver trả về ready hoặc failed
• Nếu thời gian chờ 60 giây của công cụ exec không đủ, script sẽ bị dừng. Bạn có thể tăng nó bằng cách lập trình hoặc sử dụng công cụ spawn cho các tác vụ kéo dài (subagent có thời gian chờ riêng)

Thời gian chờ 60 giây của ExecTool quá ngắn

Mặc định, thời gian chờ trong pkg/tools/shell.go là 60 giây. Đối với giải CAPTCHA, điều này có thể quá ngắn. Sử dụng công cụ spawn cho các tác vụ kéo dài (subagent chạy độc lập), hoặc thay đổi thời gian chờ trong NewExecToolWithConfig() trong mã nguồn (timeout: 120 * time.Second).

Không tìm thấy sitekey

Script trích xuất sitekey từ thuộc tính data-sitekey. Nếu không tìm thấy phần tử nào, agent có thể điều chỉnh và trích xuất từ URL iframe hoặc nguồn trang.

Trình duyệt bị treo trong Docker/containers

Thêm --no-sandbox, --disable-setuid-sandbox, và --disable-dev-shm-usage vào các tham số khởi động Playwright.

Agent không sử dụng CapSolver

Kiểm tra: (1) biến môi trường CAPSOLVER_API_KEY được thiết lập trước khi khởi động PicoClaw, (2) tệp kỹ năng tồn tại tại ~/.picoclaw/workspace/skills/capsolver/SKILL.md, (3) picoclaw skills hiển thị nó.

Nguyên tắc tốt nhất

1. Thiết lập khóa API dưới dạng biến môi trường

Không ghi khóa vào script. Sử dụng process.env.CAPSOLVER_API_KEY để agent tự động nhận. PicoClaw truyền biến môi trường của tiến trình cha đến tất cả các cuộc gọi exec.

2. Sử dụng chế độ không giao diện trên máy chủ

Cách tiếp cận dựa trên API của PicoClaw hoạt động trong môi trường hoàn toàn không giao diện — không cần Xvfb hoặc màn hình ảo. Đây là lợi thế lớn so với các phương pháp dựa trên tiện ích mở rộng, đặc biệt là trên thiết bị cạnh nơi phần cứng màn hình không tồn tại.

3. Giám sát số dư CapSolver

Mỗi lần giải CAPTCHA tốn điểm. Kiểm tra số dư của bạn tại capsolver.com/dashboard thường xuyên.

4. Cập nhật Playwright

Các nhà cung cấp CAPTCHA liên tục thay đổi. Đảm bảo Playwright và Chromium được cập nhật:

cd ~/.picoclaw/workspace && npm update playwright && npx playwright install chromium

5. Sử dụng công cụ Spawn cho các tác vụ kéo dài

Tự động hóa trình duyệt có thể mất 30-60 giây. Sử dụng spawn thay vì dựa vào vòng lặp chính của agent để tránh thời gian chờ và giữ agent chính phản hồi nhanh cho các tin nhắn khác.

6. Tận dụng hệ thống bộ nhớ của PicoClaw

Sau khi giải CAPTCHA thành công, agent lưu cách tiếp cận vào ~/.picoclaw/workspace/memory/MEMORY.md. Lần sau, nó nhớ chính xác mẫu đã hoạt động.

7. Triển khai trên thiết bị cạnh: Chuyển tải trình duyệt

Trên các bảng có giá 10 đô la với RAM hạn chế, kết nối đến một phiên bản Chromium từ xa bằng chromium.connect('ws://server:9222'). Điều này giữ cho PicoClaw có kích thước ~8MB trên thiết bị biên trong khi trình duyệt chạy ở nơi khác.

8. Cấu hình giới hạn không gian làm việc một cách cẩn thận

Cài đặt restrict_to_workspace của PicoClaw giới hạn các thao tác tệp và thực thi chỉ trong thư mục không gian làm việc. Đảm bảo rằng các tập lệnh và cài đặt Playwright của bạn nằm trong ~/.picoclaw/workspace/.

Kết luận

Sự tích hợp PicoClaw + CapSolver đại diện cho một cách tiếp cận hoàn toàn khác để giải CAPTCHA. Thay vì các phần mở rộng trình duyệt nặng trên máy tính để bàn, một tác nhân được biên dịch bằng Go chạy trên phần cứng 10 đô la điều phối toàn bộ quy trình giải quyết:

1. Truy cập trang đích bằng Playwright
2. Trích xuất sitekey từ thuộc tính data-sitekey
3. Giải quyết bằng cách gọi API REST của CapSolver trực tiếp
4. Chèn mã giải vào trường ẩn
5. Gửi biểu mẫu và xác minh thành công

Điều này mang lại cho bạn:

• Không cần phụ thuộc vào phần mở rộng Chrome — hoạt động với bất kỳ trình duyệt không giao diện nào
• Hỗ trợ máy chủ không giao diện — không cần màn hình hoặc Xvfb
• Kiểm soát bằng ngôn ngữ tự nhiên — chỉ cần nói với tác nhân điều gì bạn muốn thực hiện qua Telegram, Discord hoặc bất kỳ kênh nào trong số 12+ kênh
• Triển khai trên thiết bị biên — chạy 24/7 trên bảng RISC-V 10 đô la với dưới 10MB RAM
• Bảo mật mặc định — 27+ mẫu từ chối trong ExecTool ngăn các lệnh nguy hiểm

Gợi ý: Tập lệnh khởi động nhanh

Lưu ví dụ làm việc hoàn chỉnh ở trên vào ~/.picoclaw/workspace/solve_captcha.js và chạy:

CAPSOLVER_API_KEY=CAP-XXX node ~/.picoclaw/workspace/solve_captcha.js

Hoặc đơn giản gửi một tin nhắn Telegram đến tác nhân PicoClaw của bạn và để nó xử lý mọi thứ tự động.

Sẵn sàng bắt đầu chưa? Đăng ký tại CapSolver và sử dụng mã khuyến mãi PICOCLAW để nhận thêm 6% khuyến mãi cho lần nạp đầu tiên!

Câu hỏi thường gặp

PicoClaw giải CAPTCHA khác biệt như thế nào so với phần mở rộng trình duyệt?

PicoClaw sử dụng trực tiếp API REST của CapSolver. Tác nhân viết và thực thi các tập lệnh Node.js/Playwright gọi createTask và getTaskResult để nhận các mã giải, sau đó chèn chúng vào DOM trang. Không cần phần mở rộng trình duyệt. Toàn bộ quy trình được thực hiện thông qua ExecTool của PicoClaw (pkg/tools/shell.go), chạy sh -c "node script.js" với 27+ mẫu từ chối bảo mật, giới hạn đường dẫn không gian làm việc và thời gian chờ có thể cấu hình.

Bạn có cần phiên bản Chrome đặc biệt không?

Không. Khác với các phương pháp dựa trên phần mở rộng yêu cầu Chrome for Testing (vì Chrome có thương hiệu 137+ đã vô hiệu hóa việc tải phần mở rộng), PicoClaw hoạt động với bất kỳ bản Chromium nào — bao gồm Chromium được đóng gói bởi Playwright, các gói Chromium tiêu chuẩn hoặc Chrome không giao diện. Điều này đặc biệt quan trọng trên các thiết bị biên nơi bạn chỉ có thể truy cập Chromium được đóng gói bởi phân phối.

PicoClaw có thực sự chạy trên bảng 10 đô la không?

Có. PicoClaw sử dụng dưới 10MB RAM và khởi động trong dưới 1 giây trên lõi 0,6GHz. Nó hỗ trợ RISC-V, ARM64 và x86_64. API đám mây của CapSolver xử lý công việc nặng; PicoClaw chỉ điều phối. Lưu ý: Chromium cần 100-300MB RAM, vì vậy các bảng dưới 256MB nên kết nối đến trình duyệt từ xa.

CapSolver hỗ trợ loại CAPTCHA nào?

CapSolver hỗ trợ reCAPTCHA v2 (hộp kiểm và ẩn), reCAPTCHA v3, reCAPTCHA Enterprise, Cloudflare Turnstile, AWS WAF CAPTCHA và nhiều hơn nữa. Sự tích hợp PicoClaw sử dụng ReCaptchaV2TaskProxyLess trong ví dụ, nhưng tệp kỹ năng ghi chú tất cả các loại nhiệm vụ. Tác nhân có thể thích ứng với bất kỳ loại CAPTCHA nào được hỗ trợ bằng cách thay đổi tham số loại nhiệm vụ.

Bạn có thể sử dụng nó trên máy chủ không giao diện không?

Có — và đây là nơi cách tiếp cận của PicoClaw tỏa sáng. Vì không có phần mở rộng trình duyệt, bạn không cần Xvfb hoặc màn hình ảo. Playwright chạy ở chế độ không giao diện hoàn toàn. Kết hợp với kích thước nhỏ của PicoClaw, điều này làm cho nó lý tưởng cho các triển khai máy chủ luôn hoạt động.

Chi phí của CapSolver là bao nhiêu?

CapSolver cung cấp giá cả cạnh tranh dựa trên loại CAPTCHA và khối lượng. Truy cập capsolver.com để xem giá hiện tại. Sử dụng mã khuyến mãi PICOCLAW để nhận thêm 6% cho lần nạp đầu tiên.

PicoClaw có miễn phí không?

PicoClaw là mã nguồn mở (giấy phép MIT) và miễn phí để chạy trên phần cứng của bạn. Bạn sẽ cần khóa API cho nhà cung cấp mô hình AI bạn chọn và, để giải CAPTCHA, tài khoản CapSolver với tín dụng. Bản nhị phân PicoClaw không có chi phí hoạt động.

Thời gian giải CAPTCHA là bao lâu?

Trong thử nghiệm tích hợp bot Discord với reCAPTCHA v2, tập lệnh Playwright của tác nhân (bao gồm việc gọi API CapSolver) đã thực thi trong 24,2 giây. Thời gian toàn bộ từ tin nhắn Discord đến phản hồi là khoảng 30 giây, bao gồm 5 lần lặp LLM để tạo, thực thi và xác minh tập lệnh.

Các mẫu từ chối của PicoClaw có chặn các tập lệnh tự động hóa của bạn không?

Không. Các mẫu từ chối trong pkg/tools/shell.go chặn các lệnh hệ thống nguy hiểm (rm -rf, sudo, docker run), không phải việc thực thi Node.js thông thường. Chạy node script.js và npm install cục bộ được phép hoàn toàn. Chỉ các cài đặt toàn cục (npm install -g) và các lệnh quản lý gói bị chặn.

Bạn có thể chạy nhiều lần giải CAPTCHA song song không?

Có. Sử dụng công cụ spawn của PicoClaw để tạo nhiều tác nhân con, mỗi tác nhân xử lý một nhiệm vụ CAPTCHA khác nhau. SubagentManager (pkg/tools/subagent.go) chạy mỗi tác nhân độc lập và báo cáo kết quả trở lại qua MessageBus.

PicoClaw so sánh với Nanobot như thế nào trong việc giải CAPTCHA?

PicoClaw được lấy cảm hứng từ Nanobot (Python), được viết lại bằng Go để đạt hiệu suất cực kỳ cao. Cả hai đều sử dụng giải pháp CAPTCHA dựa trên tác nhân — điểm khác biệt chính là tài nguyên. Nanobot cần 100MB+ RAM và Python; PicoClaw cần dưới 10MB và được phân phối dưới dạng một tệp nhị phân. Đối với thiết bị biên, PicoClaw là lựa chọn rõ ràng.