PicoClaw Automation: CapSolver APIの統合ガイド

AIアシスタントがウェブタスクを自動化する際、CAPTCHAが最も大きな障壁となります。保護されたページは送信を拒否し、ログインフローが停止し、全体の自動化パイプラインが人間がチェックボックスをクリックしたり、交通信号を識別するのを待って停止します。

PicoClaw は、10ドルのハードウェアで動作し、10MB未満のRAMを消費する非常に軽量な個人用AIアシスタントです。このツールは、既存のメッセージングプラットフォームに接続し、エージェントがスクリプトを自動的に書き込み実行できる組み込みの exec ツールを備えています。

CapSolver はAIを活用したCAPTCHA解決APIを提供します。PicoClawのスクリプト実行機能とCapSolverのREST APIを組み合わせることで、エージェントはCAPTCHAを検出・解決し、トークンを挿入し、フォームを送信することができます。すべてを人間の介入なしに実行できます。

最も良い点は、エージェントに plain language で何をしたいかを伝えるだけで、Playwrightスクリプトを自動的に生成し、サイトキーを抽出し、CapSolverを呼び出し、トークンを挿入し、フォームを送信するという一連の処理をすべて自動的に行うということです。さらに、PicoClawはコンパイルされたGoで構成されているため、10ドルのRISC-Vボードで10MBのRAMに収まります。

PicoClawとは何か？

PicoClaw は、Go 1.25.7で作成された非常に軽量な個人用AIアシスタントで、独自の自己ブートストラッププロセスを通じて構築されています。AIエージェント自体がPythonから全体のアーキテクチャを移行し、95%のコアコードを自動的に生成しました。

数字で見るPicoClaw

PicoClawのスローガンはこれです：10ドルのハードウェア。10MBのRAM。1秒のブート。

主な特徴

• 非常に軽量: 10MB未満のメモリ使用量 – 比較可能なTypeScriptエージェントの99%小さい
• 真のポータビリティ: RISC-V、ARM64、x86_64アーキテクチャで1つの自己完結型バイナリ
• 組み込みツール: ファイルの読み書き、シェルコマンドの実行、ウェブ検索、ページの取得、クロスチャネルメッセージの送信、スケジュールの作成、I2C/SPIハードウェア周辺機器との対話が可能
• プロバイダーアグノスティック: OpenAI、Anthropic、DeepSeek、Gemini、Qwen、Moonshot、Groq、vLLM、Ollama、Cerebras、Mistral、NVIDIA、OpenRouterなどのゲートウェイプロバイダと動作
• スキルシステム: JSONまたはYAMLのフロントマターを使用してSKILL.mdファイルで機能を拡張
• メモリシステム: コンバージェーション全体を通じて日々のノートと永続的な長期記憶を保持
• ハードウェアツール: I2CとSPIツールを備え、直接的な埋め込みデバイスとの対話が可能 – PicoClawにのみ搭載

ExecTool

PicoClawの ExecTool ( pkg/tools/shell.go に定義) がブラウザ自動化を可能にします。これは、27以上のセキュリティ拒否パターンがコンパイルされたGo正規表現で、60秒のデフォルトタイムアウト、ワークスペースパス制限、パストラバーサル検出を備えた、慎重にサンドボックス化されたシェル実行環境です。

エージェントがウェブページと対話する際には、以下の手順を実行します：

1. write_fileツールを使用してPlaywrightスクリプトを書き込む
2. execツールを使用して実行する（Linuxでは sh -c を呼び出す）
3. 出力（stdout + stderr）を読み込む（10KBに制限）
4. チャットチャネルで結果を報告する

guardCommand()メソッドは、実行前にすべてのコマンドをコンパイルされた正規表現拒否パターンでチェックし、ワークスペースパス制限を強制し、パストラバーサルの試みを検出します。これはサンドボックス化されたコマンドラインアクセスと見なせます。エージェントはNode.jsスクリプトやローカルパッケージのインストールを実行できますが、rm -rf、sudo、docker runはできません。

エージェントループ

コアロジックは pkg/tools/toolloop.go にあり、LLM呼び出し → ツール呼び出しの抽出 → ツールの実行 → 結果の追加 → 繰り返しというタイトなサイクルです。このループは、メインエージェント (pkg/agent/loop.go) とバックグラウンドサブエージェントの間で spawn を通じて共有されます。

CapSolverとは何か？

CapSolver は、さまざまなCAPTCHAチャレンジを回避するためのAI駆動の解決サービスです。複数のCAPTCHAタイプをサポートし、高速な応答時間を提供し、自動化ワークフローにスムーズに統合されます。

サポートされているCAPTCHAタイプ

• reCAPTCHA v2 (画像ベース & 非表示)
• reCAPTCHA v3 & v3 Enterprise
• Cloudflare Turnstile
• Cloudflare 5秒チャレンジ
• AWS WAF CAPTCHA

PicoClawのアプローチが異なる理由

ほとんどのCAPTCHA解決統合は、2つのグループに分けられます。1つはコードレベルのAPI統合で、専用サービスクラスを書く必要があるもの、もう1つはブラウザ拡張機能で、Chrome拡張機能がすべてを自動的に処理するものです。PicoClawは3番目のアプローチを取っています：エッジハードウェア上のエージェント駆動のAPI統合。

AIエージェント自体がすべての解決フローを自動的に調整します。Playwrightスクリプトを書き、サイトキーを抽出し、CapSolver APIを呼び出し、解決トークンを挿入し、フォームを送信する—all through scripts it writes and executes on the fly. そして、最も重要なのは、すべての調整を実行するGoベースのオーケストレーターが10MB未満のRAMを消費していることです。

エッジデバイスの利点

1杯のコーヒー以下のコストで、CAPTCHA回避の自動化を実行できます。 9.9ドルのLicheeRV-NanoでPicoClawを動作させると、Telegramメッセージを受け取り、CapSolverのクラウドAPIと連携し、トークンを挿入し、フォームを送信できます。ボードの64MB RAMの一部しか使用しません。重い処理（CAPTCHA認識）はCapSolverのサーバーで行われ、PicoClawはオーケストレーションのみを行います。常に動作し、24時間365日、切手サイズのデバイスで動作します。

重要なポイント: PicoClawのGoバイナリは非常に軽量で、他のフレームワークが起動できないハードウェアでも動作しますが、PlaywrightスクリプトとCapSolverのREST APIを通じて完全なCAPTCHA解決パイプラインをオーケストレートできます。

必要条件

注意: 以下の例は Ubuntu 22.04 / 24.04 でテストされています。コマンドは apt と bash を使用しています。必要に応じてディストロに合わせて調整してください。エッジデバイス（RISC-V、ARM）では、ビルドマシンでPicoClawをクロスコンパイルするか、リリースページからプリビルドバイナリをダウンロードしてください。

統合をセットアップする前に、以下の項目を確認してください：

1. Ubuntu 22.04+ (または任意のLinuxディストロ – PicoClawのシングルバイナリはどこでも動作)
2. Go 1.25.7+ がインストールされている（ソースからビルドする場合のみ必要）
3. PicoClaw がインストールされ、実行中（プリビルドバイナリまたは make build）
4. CapSolverアカウント とAPIキー（ここから登録）
5. Node.js 18+ がインストールされている（execツールでPlaywrightスクリプトを実行するため）
6. Playwright がワークスペースにインストールされている

ステップバイステップのセットアップ

ステップ1: PicoClawをインストール

オプションA: プリビルドバイナリ（最も速い）

# プラットフォームに応じた最新リリースをダウンロード
# v0.1.1をリリースページの最新バージョンに置き換えてください
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

# インタラクティブなオンボーディングウィザードを実行
picoclaw onboard

オプションB: ソースからビルド

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

# 設定とワークスペースの初期化
picoclaw onboard

これにより ~/.picoclaw/config.json と ~/.picoclaw/workspace/（スクリプト、スキル、メモリ）が作成されます。

ステップ2: CapSolver APIキーを設定

環境変数としてCapSolver APIキーを追加します：

export CAPSOLVER_API_KEY="CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

APIキーはCapSolverダッシュボードから取得できます。

永続的な設定が必要な場合は、~/.bashrc または ~/.zshrc に追加してください。

ステップ3: ブラウザ自動化ツールをインストール

UbuntuでPlaywrightとそのシステム依存関係をインストールします：

# Playwrightブラウザの依存関係をインストール（Ubuntu）
sudo apt install -y libnss3 libatk-bridge2.0-0 libdrm2 libxcomposite1 \
  libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libasound2t64

# Playwrightをワークスペースにインストール
cd ~/.picoclaw/workspace
npm init -y
npm install playwright
npx playwright install chromium

エッジデバイスの注意: リソース制約のあるボードでは、よりパワフルなマシンでChromiumをインストールし、PicoClawがPlaywrightの browserType.connect() を通じてリモートブラウザに接続するようにする必要があります。PicoClawエージェント自体は約10MBのRAMしか必要としません。ブラウザは重い処理を担当します。

ステップ4: ExecToolをブラウザ自動化に設定

PicoClawのExecToolにはセキュリティのための組み込み拒否パターンがあります。デフォルトの設定はCAPTCHA自動化に適しています。node、npx、ローカルのnpm installはすべて許可されています。npm install -g、sudo、docker runなどの危険なコマンドのみがブロックされます。標準的なワークフローでは設定変更は必要ありません。

ステップ5: ゲートウェイを起動

# チャネルサービス（Telegram、Discordなど）を起動
picoclaw gateway

# またはインタラクティブなテスト用
picoclaw agent

ステップ6: 設定を確認

接続されたチャネルを通じてエージェントにテストメッセージを送信します：

利用可能なツールはありますか？

エージェントは exec をリストに表示するはずです。これはブラウザ自動化スクリプトを実行するために使用されます。Node.jsのアクセスも確認できます：

実行: node --version

エージェントは exec ツールを通じてこれを実行し、Node.jsバージョンを返します。

オンボーディングされたCapSolverスキル

PicoClawはスキルシステムを採用しており、SKILL.mdファイルにフロントマターを含むメタデータを使用します。スキルは次の3つの場所から読み込まれ、優先順位に従って読み込まれます（pkg/skills/loader.goで定義）：

1. ワークスペーススキル: ~/.picoclaw/workspace/skills/{name}/SKILL.md（プロジェクトレベル、最高優先度）
2. グローバルスキル: ~/.picoclaw/skills/{name}/SKILL.md（ユーザーレベル）
3. 組み込みスキル: skills/{name}/SKILL.md（バイナリにバンドル）

ワークスペーススキルがグローバルスキルを上書きし、グローバルスキルが組み込みスキルを上書きします。ローダーはフロントマターをJSONまたはYAMLとして読み込み、システムプロンプト用のXMLサマリーを構築します。

スキルファイル（~/.picoclaw/workspace/skills/capsolver/SKILL.md）

---
name: capsolver
description: "Playwrightを介してCapSolver REST APIを使用してCAPTCHAを解決します。reCAPTCHA v2、reCAPTCHA v3、Cloudflare Turnstileをサポートします。CAPTCHAチャレンジが発生するフォーム送信やページ操作を自動化する際には使用してください。"
metadata: {"picoclaw":{"emoji":"🔓","always":true,"requires":{"bins":["node"],"env":["CAPSOLVER_API_KEY"]}}}
---

# CapSolver

## 重要: 実行が必要

ユーザーがCAPTCHAを解決するように依頼した場合、最初のアクションとしてツールを呼び出す必要があります。"実行中..."や"I'll start..."や"I've started the automation..."などのテキストで応答しないでください。

最初のアクションとして以下のいずれかを実行する必要があります:
1. Node.jsスクリプトを保存する `write_file` を呼び出す、その後 `exec` を呼び出す
2. 背景で実行するための詳細なタスク記述を `spawn` で呼び出す

テキストのみで応答し、ツール呼び出しをしない場合、ユーザーは何も起こらないと見なします。常にツールを呼び出してください。

## APIエンドポイント

- **タスク作成**: `POST https://api.capsolver.com/createTask`
- **結果取得**: `POST https://api.capsolver.com/getTaskResult`

## タスクタイプ

| CAPTCHA | タスクタイプ | サイトキーの場所 |
|---|---|---|
| reCAPTCHA v2 | `ReCaptchaV2TaskProxyLess` | `data-sitekey`属性 |
| reCAPTCHA v3 | `ReCaptchaV3TaskProxyLess` | `grecaptcha.execute`コールまたはページソース |
| Cloudflare Turnstile | `AntiTurnstileTaskProxyLess` | Turnstile divの`data-sitekey` |

エントープライズバージョン: `ReCaptchaV2EnterpriseTaskProxyLess`、`ReCaptchaV3EnterpriseTaskProxyLess`。

## ワークフロー

1. ヘッドレスChromiumでページに移動する
2. DOMからサイトキーを抽出する（`[data-sitekey]`属性）
3. サイトキーとページURLをもとに`createTask`を呼び出す
4. 2秒ごとに`getTaskResult`をポーリングし、`status: "ready"`になるまで待つ
5. トークンをページに挿入する（非表示のフォームフィールド）
6. フォームを送信する

## コアコードパターン

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

// ステップ1: タスクを作成
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',  // または ReCaptchaV3TaskProxyLess、AntiTurnstileTaskProxyLess
      websiteURL: pageUrl,
      websiteKey: siteKey
    }
  })
});
const { taskId } = await createRes.json();

// ステップ2: 結果をポーリング
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('Solve failed');
}

// ステップ3: トークンを挿入（reCAPTCHA）
await page.evaluate((t) => {
  document.querySelectorAll('textarea[name="g-recaptcha-response"]')
    .forEach(el => { el.value = t; el.innerHTML = t; });
}, token);
```

Turnstileの場合、トークンフィールドは通常 `input[name="cf-turnstile-response"]` で、解決は `result.solution.token` にあります。

## APIリファレンス

すべてのタスクタイプで `type`、`websiteURL`、`websiteKey` が必要です。オプションフィールドはタイプによって異なります:
- **reCAPTCHA v2**: `isInvisible`、`pageAction`、`enterprisePayload`、`apiDomain`
- **reCAPTCHA v3**: `pageAction`（`grecaptcha.execute(key, {action: "..."})`から）
- **Cloudflare Turnstile**: `metadata.action`, `metadata.cdata`

ポイント:

• フロントマターはJSONまたはYAMLを使用します（pkg/skills/loader.goはJSONを優先し、失敗時はYAMLにフォールバックします）
• metadataにはPicoClaw固有の設定が含まれます: emojiは表示用、alwaysは自動読み込み、requiresは依存関係のチェック用
• SkillsLoader.BuildSkillsSummary()はシステムプロンプトにインジェクトされるXMLの要約を生成します
• 「実行が必要」セクションはテキストのみのレスポンスではなくツールコールを強制します

スキルを作成した後、picoclaw skillsで確認してください — capsolverがリストされているはずです。

動作方法

PicoClawにCAPTCHA保護ページと対話するように指示すると、メッセージから結果までのフローは以下の通りです:

  あなたのメッセージ                     PicoClawエージェント（Go、約10MB RAM）
  ─────────────────────────────────────────────────────────────
  "そのページに移動して、           ──► メッセージバス経由で受信
   フォームを入力し、                │ （`pkg/bus/bus.go`）
   CAPTCHAを解決し、                 ▼
   送信してください"             コンテキストビルダーがスキルをインジェクト
                                   │ （`pkg/agent/context.go`）
                                   ▼
                              RunToolLoopが開始されます
                                   │ （`pkg/tools/toolloop.go`）
                                   ▼
                              エージェントがNode.jsスクリプトを書き込みます
                                   │ `write_file`ツール経由
                                   ▼
                              ExecToolがスクリプトを実行します
                              ┌────────────────────────────┐
                              │ `pkg/tools/shell.go`       │
                              │ guardCommand() → 27以上のチェック │
                              │ `sh -c "node script.js"`     │
                              │                            │
                              │ Headless Chromium           │
                              │ 1. ページに移動           │
                              │ 2. sitekeyを抽出           │
                              │ 3. POST /createTask ────────── CapSolver API
                              │ 4. /getTaskResultをポーリング ─── (クラウド)
                              │ 5. トークンをインジェクト       │
                              │ 6. フォームを送信           │
                              │ 7. スクリーンショット         │
                              └────────────────────────────┘
                                   │
                                   ▼ stdoutが返却（最大10KB）
                              エージェントが出力を読み込みます
                                   │
                                   ▼
                              "フォームが正常に送信されました！
                               検証成功！"

CapSolver APIフロー

統合のコアとなる2つのAPIコール:

1. タスクの作成 — CAPTCHAのsitekeyとページURLを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. 結果のポーリング — 2秒ごとにCapSolverが解決されたトークンを返却するまでチェックします:

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にトークンが含まれます

3. トークンのインジェクト — reCAPTCHAが期待する非表示フォームフィールドに設定します:

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

完全な動作例

PicoClawエージェントが生成して実行する実際に動作するNode.jsスクリプトです。エージェントはwrite_file経由でこれを書き込み、execで実行します — これは1つのTelegramメッセージから完全に自律的に行われます:

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('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(`CapSolverエラー: ${createRes.errorDescription}`);
  }

  const { taskId } = createRes;
  console.log(`タスクID: ${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.length}`);
      break;
    }
    if (res.status === 'failed') {
      throw new Error(`CapSolverタスク失敗: ${res.errorDescription}`);
    }

    console.log('ポーリング中... 状態:', res.status);
  }

  if (!token) throw new Error('トークンの取得に失敗しました');
  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') ? 'SUCCESS!' : '結果:', body.slice(0, 200));
    await page.screenshot({ path: 'recaptcha_result.png' });
  } finally {
    await browser.close();
  }
}

main().catch(err => {
  console.error('エラー:', err.message);
  process.exit(1);
});

直接実行するには:

CAPSOLVER_API_KEY=CAP-XXX node solve_recaptcha.js

またはPicoClawエージェントにすべてを任せます — Telegramにメッセージを送信するだけです:

https://example.comでreCAPTCHAを解決し、フォームを送信してください。

エージェントはcapsolverスキルを読み込み、Playwrightスクリプトを書き込み、exec経由で実行し、出力を読み込み、結果を報告します。

使用方法

セットアップが完了したら、PicoClawでCapSolverを使用するのは、任意の接続されたチャネルでメッセージを送信するだけです。

例1: reCAPTCHAデモを解決する

Telegram、Discord、WhatsApp、または任意の接続チャネルからこのメッセージをエージェントに送信してください:

https://example.comに移動し、CapSolver APIを使用してreCAPTCHAを解決してください。その後フォームを送信し、成功したかどうかを教えてください。

処理内容: エージェントはcapsolverスキルを読み込み、Playwrightスクリプトを書き込み、exec経由で実行します（guardCommand()のチェックを通過し、60秒のタイムアウトで実行されます）。スクリプトはページに移動し、sitekeyを抽出し、CapSolverを呼び出し、トークンをインジェクトし、送信します。結果はMessageBus経由で戻ってきます。

例2: 保護されたサイトにログインする

https://example.com/loginに移動し、メールアドレスに"[email protected]"、パスワードに"mypassword"を入力し、ページ上のCAPTCHAを検出および解決し、サインインをクリックして、その後の状況を教えてください。

例3: お問い合わせフォームを送信する

https://example.com/contactを開き、名前、メールアドレス、メッセージのフィールドを入力し、CAPTCHAを解決し、フォームを送信し、確認メッセージを教えてください。

例4: 背景自動化用のspawn

長時間実行が必要なタスクの場合、spawnツール（pkg/tools/spawn.go）を使用して背景のサブエージェントに委譲します:

背景で、https://example.com/registerに移動し、私の詳細でアカウントを作成し、遭遇するすべてのCAPTCHAを解決し、完了したら教えてください。

例5: エッジデバイス監視（$10ボード上のTelegram）

PicoClawがLicheeRV-Nanoや同様のエッジデバイスで動作している場合、cronツールと組み合わせて使用してください:

毎時間、https://example.com/statusをチェックしてください — CAPTCHAゲートがある場合、解決してステータスページの内容を報告してください。

なぜこれで動作するのか

PicoClawエージェントには自律的なCAPTCHA解決に必要なすべてのツールが含まれています:

• exec（pkg/tools/shell.go） — 27以上のセキュリティ拒否パターンを持つサンドボックス化されたシェル実行
• write_file / read_file（pkg/tools/filesystem.go） — ワークスペースでのスクリプト管理
• spawn（pkg/tools/spawn.go） — 長時間タスク用の背景サブエージェントの委譲
• web_fetch（pkg/tools/web.go） — DOM分析のためのページコンテンツ取得
• スキルシステム（pkg/skills/loader.go） — capsolverスキルがコンテキスト内のAPIドキュメントを提供します
• メモリ（pkg/agent/memory.go） — セッション間で成功したアプローチを永続化します

パフォーマンス結果

Ubuntu 24.04でのライブDiscordボットを介してGoogleのreCAPTCHA v2デモページでテストを行いました。PicoClawエージェント（glm-4.7をz.ai経由で使用）はDiscordメッセージを受け取り、自律的にPlaywrightスクリプトを書き込み、CAPTCHAを解決し、結果を報告しました — 人間の介入なしで:

エッジデバイスのノート: RAMが限られているボード（例: 64MBのLicheeRV-Nano）では、PicoClaw自体は簡単に収まります（~8MB）が、Chromiumには100〜300MBが必要です。ブラウザをより高性能なマシンにオフロードするにはPlaywrightのconnect()を使用してください。

問題解決

"Cannot find module 'playwright'"

ワークスペースにPlaywrightがインストールされていません。実行してください:

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

Ubuntuでブラウザのライブラリが見つからない

Chromiumが起動できず、共有ライブラリに関するエラーが発生した場合、システムの依存関係をインストールしてください:

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

ExecToolの拒否パターンがnpm installをブロックしている

PicoClawの拒否パターンはnpm install -g（グローバルインストール）、sudo、apt installをブロックしますが、ローカルのnpm install、node script.js、npx playwright installは許可されます。"Command blocked by safety guard"というエラーが表示された場合、拒否パターンを無効化するか、~/.picoclaw/config.jsonでカスタムの許可リストを提供してください:

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

または、ブロックしたいパターンのみを除外するカスタム許可リストを使用してください。

CAPTCHA解決のタイムアウト

• 有効なCapSolver APIキーであることを確認してください
• CapSolverアカウントの残高をcapsolver.com/dashboardで確認してください
• スクリプトは2秒ごとにCapSolverがreadyまたはfailedを返却するまでポーリングします
• execツールの60秒のタイムアウトが不足している場合、スクリプトは終了します。プログラムでタイムアウトを増やすか、spawnツールを使用して長時間タスクを実行してください（サブエージェントは独自のタイムアウトを持っています）

ExecToolの60秒タイムアウトが短すぎる

pkg/tools/shell.goのデフォルトタイムアウトは60秒です。CAPTCHA自動化ではこの時間は限界かもしれません。長時間タスクにはspawnツールを使用してください（サブエージェントは独立して実行されます）。または、ソースコード内のNewExecToolWithConfig()でタイムアウトを変更してください（timeout: 120 * time.Second）。

sitekeyが見つからない

スクリプトはdata-sitekey属性からsitekeyを抽出します。要素が見つからない場合、エージェントはiframeのURLやページソースから抽出するように調整されます。

Docker/コンテナでブラウザがクラッシュする

Playwrightの起動引数に--no-sandbox、--disable-setuid-sandbox、--disable-dev-shm-usageを追加してください。

エージェントがCapSolverを使用しない

確認してください: (1) PicoClawを起動する前にCAPSOLVER_API_KEYの環境変数が設定されているか、(2) スキルファイルが~/.picoclaw/workspace/skills/capsolver/SKILL.mdに存在するか、(3) picoclaw skillsでリストされているか。

最適な実践方法

1. APIキーを環境変数として設定する

スクリプトに直接記述しないでください。process.env.CAPSOLVER_API_KEYを使用して、エージェントが自動的に取得できるようにしてください。PicoClawは親プロセスの環境変数をすべてのexecツール呼び出しに渡します。

2. サーバーでヘッドレスモードを使用する

PicoClawのAPIベースのアプローチは完全なヘッドレス環境で動作します — Xvfbや仮想ディスプレイは必要ありません。これはエッジデバイスでディスプレイハードウェアが存在しない場合の拡張機能ベースのアプローチよりも大きな利点です。

3. CapSolver残高を監視する

各CAPTCHA解決にはクレジットが使われます。定期的にcapsolver.com/dashboardで残高を確認してください。

4. Playwrightを最新版に保つ

CAPTCHAプロバイダーは進化します。PlaywrightとChromiumを最新版に保つ:

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

5. 長時間タスクにはspawnツールを使用する

ブラウザの自動化には30〜60秒かかることがあります。タイムアウトを避けるためにエージェントのメインループに依存せず、spawnツールを使用してください。

6. PicoClawのメモリシステムを活用する

成功したCAPTCHA解決のアプローチは、~/.picoclaw/workspace/memory/MEMORY.mdに保存されます。次回は、正確に動作したパターンを思い出します。

7. エッジデバイスの展開: ブラウザをオフロードする

10ドルのボードでRAMが限られている場合、chromium.connect('ws://server:9222')を介してリモートのChromiumインスタンスに接続してください。これにより、PicoClawの約8MBのフットプリントをエッジで維持しながら、ブラウザは他の場所で実行されます。

8. ワークスペース制限の設定に注意してください

PicoClawのrestrict_to_workspace設定は、ファイルおよび実行操作をワークスペースディレクトリに制限します。スクリプトとPlaywrightのインストールが~/.picoclaw/workspace/内にあることを確認してください。

結論

PicoClaw + CapSolverの統合は、デスクトップマシンに重いブラウザ拡張機能をインストールする代わりに、10ドルのハードウェア上で実行されるGoコンパイル済みエージェントが全体の解決フローを調整する fundamentally differentなアプローチを提供します。

1. Playwrightで対象ページに移動
2. data-sitekey属性からサイトキーを抽出
3. CapSolverのREST APIを直接呼び出して解決
4. 解決トークンを非表示フォームフィールドにインジェクト
5. フォームを送信し、成功を確認

これにより、以下の利点が得られます:

• Chrome拡張機能の依存関係なし — 任意のヘッドレスブラウザで動作
• ヘッドレスサーバーのサポート — 表示やXvfbは必要ありません
• 自然言語によるコントロール — 12以上のチャネル（Telegram、Discordなど）を通じてエージェントに何をすべきかを伝えるだけでOK
• エッジデバイスへのデプロイ — 10MB未満のRAMで動作する10ドルのRISC-Vボードで24/7稼働可能
• デフォルトでセキュリティ — ExecToolに27以上の拒否パターンが含まれており、危険なコマンドを防止

ボーナス: クイックスタートスクリプト

上記の完全な動作例を~/.picoclaw/workspace/solve_captcha.jsに保存し、次のように実行してください:

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

または、単にPicoClawエージェントにTelegramメッセージを送信するだけで、すべてを自律的に処理させることができます。

始める準備はできましたか？ CapSolverに登録し、初回チャージで6%のボーナスを追加するためのボーナスコードPICOCLAWを使用してください！

FAQ

PicoClawはブラウザ拡張機能とはどのようにCAPTCHAを解決しますか？

PicoClawは直接CapSolverのREST APIを使用します。エージェントはNode.js/Playwrightスクリプトを書き込み実行し、createTaskとgetTaskResultを呼び出して解決トークンを取得し、それらをページのDOMにインジェクトします。ブラウザ拡張機能は必要ありません。全体の調整はPicoClawのExecTool（pkg/tools/shell.go）を通じて行われ、27以上のセキュリティ拒否パターン、ワークスペースパスの制限、および設定可能なタイムアウトでsh -c "node script.js"を実行します。

特別なChromeバージョンが必要ですか？

いいえ。拡張機能ベースのアプローチではChrome for Testingが必要ですが、ブランド Chrome 137以降では拡張機能の読み込みが無効化されているため、PicoClawはあらゆるChromiumビルド（PlaywrightのバンドルChromium、標準Chromiumパッケージ、ヘッドレスChromeを含む）で動作します。これはエッジデバイスでディストローパッケージのChromiumのみにアクセスできる場合に特に重要です。

PicoClawは本当に10ドルのボードで動作しますか？

はい。PicoClawは0.6GHzのコアで1秒未満で起動し、10MB未満のRAMを使用します。RISC-V、ARM64、x86_64をサポートしています。CapSolverのクラウドAPIが重い作業を処理し、PicoClawは調整のみを行います。注意: Chromiumは100〜300MBのRAMが必要なので、256MB未満のボードはリモートブラウザに接続する必要があります。

CapSolverはどのCAPTCHAタイプをサポートしていますか？

CapSolverはreCAPTCHA v2（チェックボックスおよび非表示）、reCAPTCHA v3、reCAPTCHA Enterprise、Cloudflare Turnstile、AWS WAF CAPTCHAなどに対応しています。PicoClawの統合ではReCaptchaV2TaskProxyLessが例として使用されますが、スキルファイルにはすべてのタスクタイプが記載されています。エージェントはタスクタイプパラメータを変更することで、あらゆるサポートされているCAPTCHAタイプに対応できます。

ヘッドレスサーバーで使用できますか？

はい。これはPicoClawのアプローチが最も活かされる場面です。ブラウザ拡張機能が関与していないため、Xvfbや仮想ディスプレイは必要ありません。Playwrightは標準で完全なヘッドレスモードで動作します。PicoClawの小さなフットプリントと組み合わせることで、常に動作するサーバーのデプロイに最適です。

CapSolverの料金はどのくらいですか？

CapSolverはCAPTCHAの種類とボリュームに基づいて競争力のある料金を提供しています。最新の料金はcapsolver.comをご覧ください。初回チャージで6%のボーナスを追加するためのボーナスコードPICOCLAWを使用してください。

PicoClawは無料ですか？

PicoClawはオープンソース（MITライセンス）で、自前のハードウェアで無料で動作します。AIモデルプロバイダーのAPIキーと、CAPTCHA解決の場合、CapSolverアカウントとクレジットが必要です。PicoClawのバイナリ自体には実行時のコストはありません。

CAPTCHA解決にはどのくらい時間がかかりますか？

Discordボット統合テストでreCAPTCHA v2を使用した場合、エージェントのPlaywrightスクリプト（CapSolver APIポーリングを含む）は24.2秒で実行されました。Discordメッセージから応答までの全体的なエンドツーエンド時間は約30秒で、スクリプト生成、実行、視覚的検証の5回のLLMイテレーションを含んでいます。

PicoClawの拒否パターンは私の自動化スクリプトをブロックしますか？

いいえ。pkg/tools/shell.go内の拒否パターンは危険なシステムコマンド（rm -rf、sudo、docker run）をブロックしますが、通常のNode.js実行はブロックしません。node script.jsとローカルなnpm installは完全に許可されています。グローバルインストール（npm install -g）とパッケージ管理コマンドのみがブロックされます。

複数のCAPTCHA解決を並列で実行できますか？

はい。PicoClawのspawnツールを使用して複数のバックグラウンドサブエージェントを作成し、それぞれが異なるCAPTCHAタスクを処理できます。SubagentManager（pkg/tools/subagent.go）は各サブエージェントを独立して実行し、MessageBusを通じて結果を報告します。

PicoClawはNanobotとどのように比較されますか？

PicoClawはNanobot（Python）にインスパイアされ、極端な効率性のためにGoで再実装されました。両方ともエージェント駆動のCAPTCHA解決を使用しますが、主な違いはリソースです。Nanobotは100MB以上のRAMとPythonが必要ですが、PicoClawは10MB未満で単一のバイナリで提供されます。エッジデバイスでは、PicoClawが明確な選択肢です。