GenericAgent のデプロイと接続：WeChat/QQ/Feishu 全プラットフォーム対応のロボット構築

プロジェクト概要

GenericAgent は、極めてシンプルで、自ら進化していく自律型 Agent のフレームワークです。中核は 約3,000行（~3K 行）のコードのみで、9 個の原子ツール + 約100行の Agent Loop によって、任意の LLM にローカルコンピュータのシステムレベルの制御能力を与えます。

設計思想がとても面白いのがポイントです：スキルを前提として用意せず、進化によって能力を獲得する。新しいタスクを1つ解決するたびに、GenericAgent は実行ルートを Skill として自動的に固定化します。使い続けるほどスキルが蓄積され、3K 行の種コードから育った、完全にあなた専用の専属スキルツリーが形成されていきます。

OpenClaw（~530K 行）と比べると、GenericAgent はミニマル路線です。デプロイはシンプル（pip install + API Key）で、多数のサービスのオーケストレーションは不要。それでも、ブラウザ制御、キーボード/マウス操作、ADB を使った移動デバイスの制御など、コア機能はすべて保持しています。

---

難易度/所要時間/得られるもの

• 難易度：初心者レベルで、深いプログラミング経験は不要
• 所要時間：約30分
• 得られるもの：GenericAgent のデプロイ設定 + WeChat/QQ/Feishu の3つの主要 IM プラットフォームへの接続を習得し、いつでもどこでもスマホで PC の AI を操作できるようになります

---

想定読者像

• 1〜5 年の経験があるバックエンドまたはフルスタック開発者
• 個人用の AI アシスタントや自動化ワークフローを構築したいユーザー
• Agent 技術に興味があり、"AI が本当にあなたの代わりに仕事をしてくれる" 体験を手早く得たい開発者
• 複数プラットフォームの IM 接続が必要なユーザー（例：WeChat/QQ 経由で PC をリモート制御したい）

---

コア依存関係と環境

---

完全なプロジェクト構成

GenericAgent/
├── agentmain.py              # メイン入口。コマンドラインモードに対応
├── launch.pyw                # デスクトップ GUI 起動スクリプト
├── agent_loop.py             # コア Agent Loop（約100行）
├── llmcore.py                # LLM セッション管理
├── ga.py                     # GenericAgentHandler：メモリとツールのディスパッチ
├── frontends/                # IM プラットフォーム向けアダプタ
│   ├── wechatapp.py         # WeChat Bot
│   ├── qqapp.py             # QQ Bot
│   ├── fsapp.py             # Feishu Bot
│   ├── tgapp.py             # Telegram Bot
│   ├── wecomapp.py          # 企業向け WeChat Bot
│   ├── dingtalkapp.py       # DingTalk Bot
│   ├── tuiapp.py            # ターミナル UI
│   └── ...
├── assets/
│   ├── mykey_template.py    # API Key 設定テンプレート
│   ├── tools_schema.json    # 9 個の原子ツール定義
│   ├── sys_prompt*.txt      # システムプロンプト
│   └── tmwd_cdp_bridge/    # ブラウザ注入プラグイン
├── memory/                   # 記憶の保存ディレクトリ
└── temp/                     # 一時ファイルとログ

---

手順を追ってやってみる

Step 1: プロジェクトのインストールと依存関係

まずリポジトリをクローンして、基礎依存関係をインストールします：

# リポジトリをクローン
git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent

# 基礎依存関係
pip install requests

# GUI 依存関係（デスクトップモード）
pip install streamlit pywebview

# もしくはターミナル UI 依存関係
pip install requests textual

Step 2: API Key を設定

設定テンプレートをコピーします：

cp assets/mykey_template.py mykey.py

mykey.py を編集し、あなたの LLM 設定を入力します。以下は Defapi を使う例です（Claude の場合）：

# Defapi を経由して Claude を利用（公式半額）
native_claude_config = {
    'name': 'claude-defapi',                    # 表示名
    'apikey': 'sk-ant-your-defapi-key',         # Defapi が提供する key
    'apibase': 'https://api.defapi.org',        # Defapi のエンドポイント
    'model': 'claude-sonnet-4-6',               # または claude-opus-4-7
    'fake_cc_system_prompt': True,              # 中継サービス側で有効化が必要
    'thinking_type': 'adaptive',
    'max_tokens': 16384,
}

GenericAgent は変数名に基づいてプロトコル形式を自動判定します：

• native + claude を含む → NativeClaudeSession（ネイティブの tool フィールド）
• native + oai を含む → NativeOAISession（OpenAI ネイティブの tool フィールド）
• claude（native を含まない）→ ClaudeSession（テキストプロトコルのツール）

Step 3: GenericAgent を起動

まず、コマンドラインモードが正常かテストします：

python agentmain.py

インタラクティブプロンプト > が表示され、1 行入力してテストできます：

> デスクトップに hello.txt を作成し、内容は Hello World

すべてうまくいっていれば、Agent がタスクを実行し結果を返します。

デスクトップ GUI モードに切り替えます：

python launch.pyw

---

Step 4: WeChat Bot を接続

WeChat Bot は個人向けの WeChat スキャンログインに対応しており、最も簡単です。

追加の依存関係のインストール：

pip install pycryptodome qrcode requests

設定（任意：設定しなくても動きますが、ホワイトリスト設定を推奨）：

mykey.py に次を追加します：

# WeChat のホワイトリスト。WeChat ID を入力。未入力なら全ユーザー許可
wechat_allowed_users = []

WeChat Bot の起動：

python frontends/wechatapp.py

初回起動時に QR コードのウィンドウが表示されます。WeChat でスキャンして確認してください。ログインが成功すると、あなたの WeChat が GenericAgent と会話する画面になります。

Step 5: QQ Bot を接続

QQ Bot は QQ ロボットの公式 API を使用し、パブリックな webhook は不要です。WebSocket の長い接続でメッセージを受信します。

依存関係：

pip install qq-botpy

設定：

1. QQ オープンプラットフォーム でロボットを作成し、AppID と AppSecret を取得
2. mykey.py に次を追加：

qq_app_id = "あなたのAPP_ID"
qq_app_secret = "あなたのAPP_SECRET"
qq_allowed_users = ["ユーザー openid"]  # もしくは ['*'] ですべて許可

QQ Bot の起動：

python frontends/qqapp.py

初回にロボットへメッセージを送ると、ユーザーの openid が temp/qqapp.log に記録されます。

Step 6: Feishu Bot を接続

Feishu Bot はテキスト、リッチテキスト、画像、ファイル、音声、インタラクティブカードなど、多様なメッセージ形式に対応しています。

依存関係：

pip install lark-oapi

設定：

1. Feishu のオープンプラットフォームで企業向けの自作アプリを作成し、AppID と AppSecret を取得
2. mykey.py に次を追加：

fs_app_id = "cli_xxxxxxxxxxxxxxxx"
fs_app_secret = "xxxxxxxxxxxxxxxx"
fs_allowed_users = ["ou_xxxxxxxxxxxxxxxx"]  # もしくは ['*'] ですべて許可

Feishu Bot の起動：

python frontends/fsapp.py

Step 7: 検証とチューニング

すべての Bot は次の汎用コマンドに対応しています：

• /new - 新しい対話を開始し、現在の文脈をクリア
• /continue - 復元可能なセッションのスナップショットを一覧表示
• /continue N - 過去のセッションのうち N 番目を復元

複数プラットフォームを同時に接続する検証：

複数の Bot を同時に動かしたい場合は、複数のターミナルウィンドウを開くだけです：

# ターミナル1：WeChat
python frontends/wechatapp.py

# ターミナル2：QQ
python frontends/qqapp.py

# ターミナル3：Feishu
python frontends/fsapp.py

---

よくある不具合の調査

1. API Key の設定後に認証エラーが出る

原因：変数名の誤り、または fake_cc_system_prompt の設定ミス

解決：

• 変数名に正しいキーワードが含まれていることを確認（native_claude、oai_config など）
• 中継サービスでは fake_cc_system_prompt: True が必須
• apibase が正しいか確認（例：Defapi なら https://api.defapi.org）

2. WeChat で QR スキャン後にログイン失敗と表示される

原因：WeChat のリスク制御による、新しい端末でのログイン制限

解決：

• スマホ側でログインを確認（場合によってはスマホ側での二次認証が必要）
• WeChat アカウントに異常な行動がないことを確認
• Bot の利用頻度を下げて、リスク制御に引っかかるのを避ける

3. QQ Bot がメッセージを受け取れない

原因：ロボットが有効化されていない、または権限設定が誤っている

解決：

• QQ オープンプラットフォームでロボットが有効になっていることを確認
• イベント購読を正しく追加したか確認（プライベートチャットメッセージ イベントの購読が必要）
• temp/qqapp.log を確認して、ユーザー openid が正しく記録されているか確認

4. Feishu Bot の応答が遅い

原因：LLM 推論自体が遅い、またはネットワーク遅延

解決：

• より高速なモデルを使う（例：GPT-4o-mini、MiniMax-M2）
• LLM API までのネットワーク遅延を確認
• max_tokens を適切に下げて、先頭トークンの応答を早める

5. Bot が会話の文脈を記憶できない

原因：/new コマンドを実行した、またはセッションがタイムアウトした

解決：

• /continue コマンドで履歴セッションを復元する
• memory/ ディレクトリへの書き込み権限を確認
• temp/model_responses/ ディレクトリに会話ログが記録されているか確認

6. 実行時に ModuleNotFoundError が出る

原因：依存パッケージが不足している

解決：

# Agent に自動インストールさせる
> 必要なすべての Python 依存関係をインストールしてください

# もしくはよくある依存関係を手動でインストール
pip install requests pycryptodome qrcode streamlit pywebview

---

追加の読み物 / 進め方（上級）

ブラウザ自動化の能力

Web ツールを解放すると、GenericAgent はログイン状態を保持した本物のブラウザで操作できます：

> web setup sop を実行して、web ツールを解放する

その後は例えば次のように使えます：

> 楽天市場を開き、iPhone 16 を検索して価格順に並べ替えて
> YouTube で、最近見た履歴動画を確認して

ブラウザプラグインは assets/tmwd_cdp_bridge/ にあります。Chrome/Edge などの主要ブラウザに対応しています。

自己進化メカニズムの詳細

GenericAgent の核心的な違いは、タスクを1つ完了するたびに、実行ルートを自動で Skill として固定化することです。次に似たタスクに出会ったときは、直接呼び出せるため、毎回最初から試行錯誤する必要がありません。

つまり：

• 使い続けるほど、Agent はあなたのワークフローをより理解する
• スキルツリーは完全にあなたのもの。ほかの人の"事前に用意されたスキル"とは一致しない
• 3K 行の種コードから、無限の可能性が育っていく

Skill ライブラリエコシステム

コミュニティにはすでに 100万件級の Skill ライブラリ が蓄積されています（公众号の記事）。あなたは次のようにできます：

• Agent に検索させる：XXX を作るための skill を探して
• 直接インポート：XXX にアクセスして、この skill のとおりに作って

上級モード

GenericAgent の高度な機能はすべて自己ドキュメント化されています。つまり、Agent に直接聞けばOKです：

プログラミング能力と Claude Code の比較

多くの開発者が気にしているのは次の点です：GenericAgent は Claude Code や Codex の代わりになりますか？

答えは、プログラミングはできますが、完全には代替できません。

GenericAgent のプログラミング能力

GenericAgent は code_run ツールで任意のコードを実行し、file_read/file_write/file_patch などのファイル操作と組み合わせることで、プログラミング能力は完全です。プログラミングが得意なモデル（Claude、GPT-4o など）を用意すれば、GenericAgent は次のことができます：

• ファイルの読み書き
• コマンドラインの実行
• コードのデバッグ
• コードの論理を説明

# バックエンドとして Claude を設定
native_claude_config = {
    'apikey': 'your-key',
    'apibase': 'https://api.defapi.org',
    'model': 'claude-sonnet-4-6',
    'fake_cc_system_prompt': True,
}

そして、自然言語で直接プログラミングできます：

> クイックソート関数を書いて、それからテストを実行して
> Python で HTTP サーバーを実装して
> この React コンポーネントがどう動くか説明して

Claude Code / Codex との違い

重要な違いは：Claude Code は独自のプロトコルとツールチェーンで動作（MCP に似た形）しており、GenericAgent はそれを直接呼び出すことはできません。ただし、次のような間接的な方法があります：

方法 1：Codeg で並行利用

Codeg のプロジェクトでは、同時に GenericAgent + Claude Code + Codex を起動でき、同一の UI 内で協調させられます：

# GenericAgent と Codeg を同じ階層ディレクトリに置く
/workspace/
  ├── GenericAgent/
  └── codeg/

# Codeg は GenericAgent を自動検出し、そのまま並行利用

方法 2：API 経由の中継

GenericAgent の NativeClaudeSession は Claude Code 互換プロトコルです。中継サービス（例：Defapi）が Claude Code の透過（パススルー）に対応しているなら、GenericAgent から Claude のプログラミング能力を利用できます：

# GenericAgent が Claude の能力でプログラミング
native_claude_config = {
    'name': 'claude-defapi',
    'apikey': 'your-defapi-key',
    'apibase': 'https://api.defapi.org',
    'model': 'claude-sonnet-4-6',
    'fake_cc_system_prompt': True,  # Claude Code プロトコルの透過
}

結論

---

Reference

• GitHub: lsdefine/GenericAgent
• 技術レポート: arXiv:2604.17091
• 入門チュートリアル: Datawhale Hello GenericAgent
• Feishu 設定ガイド: assets/SETUP_FEISHU.md