WeClaw徹底解説｜WeChatからClaude・Codex・Geminiを操るAIエージェントブリッジ

この記事ではAIエージェントに特化して解説します。AIエージェント全般は AIエージェントフレームワーク比較2026年版 をご覧ください。

WeClawとは：WeChatをAIエージェントのフロントエンドにする

WeChatは中国圏を中心に月間13億人以上が日常的に使うメッセージングプラットフォームだ。だがClaude・Codex・Geminiといった最新AIエージェントをWeChatから直接操作する公式手段は存在しない。WeClawはそのギャップを1つのブリッジで埋めるオープンソースツールだ。

GitHubリポジトリ fastclaw-ai/weclaw はGo言語で実装されており、ワンラインのインストールスクリプトで立ち上がる。README冒頭のメッセージはシンプルだ。

「WeChat AI Agent Bridge — connect WeChat to AI agents (Claude, Codex, Gemini, Kimi, etc.)」

プロジェクトは @tencent-weixin/openclaw-weixin にインスパイアされており、個人学習目的のツールとして公開されている（商用利用は想定されていない点はREADMEで明記されている）。

特徴的なのは、1つのブリッジから複数のAIエージェントを切り替えて使える点だ。メッセージの先頭に /cc や /cx とエイリアスを付ければ、Claudeに投げるかCodexに投げるかをその場で選べる。Slack BotやDiscord Botのように「1ボット=1エージェント」という制約がない。

OpenHandsのようなAIコーディングエージェントが普及する中で、AIをどの入口から操作するかが重要になっている。WeClawは「自分が毎日開いているチャット」をそのままAI開発の入口に変える設計思想を持つ。

なぜWeChatを選ぶのか

WeClawが敢えてWeChatを選んだ背景は明快だ。中国圏ではWeChatがOSレベルのインフラとして機能しており、仕事の連絡・決済・ミニプログラム・ニュース購読までがひとつのアプリで完結する。ブラウザでClaudeを開くより、WeChatのチャットに打ち込むほうが心理的摩擦が低いユーザーは多い。一方で海外勢のAIエージェントはWeChatを標準サポートしていないため、ブリッジツールが必要になる。WeClawはこの「プラットフォーム特有のギャップ」を埋めるニッチに正面から取り組んだOSSだ。

加えて、WeChatアカウントは多くの開発者にとって既に個人の連絡網・プロフェッショナルネットワークが蓄積された「ホーム基地」でもある。そこへAIエージェントを呼び込めると、クライアントとの会話の合間にClaudeへ整理を依頼したり、友人からのメッセージをCodexにそのままコードへ変換させたりといった操作が現実的になる。AIをわざわざ呼び出しに行くのではなく、すでに開いているウィンドウに滑り込ませる発想だ。

プロジェクトの基本情報

WeClawのリポジトリはMITライセンスで公開されており、GitHub Actionsによる多OS・多アーキテクチャの自動リリース、make dev でのホットリロード開発、Docker公式イメージ（ghcr.io/fastclaw-ai/weclaw）の配布まで一通り揃っている。個人学習用のツールとしては珍しく、本番運用に近い完成度を持つ。README末尾にはStar History Chartが埋め込まれており、プロジェクトの成長を定点観測できる。リポジトリ直下には previews/ ディレクトリがあり、実際のチャット画面のキャプチャが3枚並んでいるので、導入前に雰囲気を掴みやすい。

インストールと初期セットアップ：3通りの導入経路

WeClawの導入経路は3つ用意されている。もっとも手軽なのは公式インストールスクリプトだ。

# ワンライナーインストール
curl -sSL https://raw.githubusercontent.com/fastclaw-ai/weclaw/main/install.sh | sh

# 起動（初回はQRコードログインが必要）
weclaw start

weclaw start を初めて実行すると、ターミナルにQRコードが表示される。WeChatアプリでそのQRコードをスキャンしてログインすれば、あとは自動的に以下の処理が走る。

1. インストール済みのAIエージェント（Claude・Codex・Gemini等）を自動検出
2. 設定を ~/.weclaw/config.json に保存
3. WeChatメッセージの受信・返信ループを開始

2番目の導入経路はGoのgo installだ。リポジトリをクローンせずに最新版を取得できる。

# Go経由でインストール
go install github.com/fastclaw-ai/weclaw@latest

3番目はDockerだ。macOSでもLinuxでも、OS環境を汚さずにブリッジを立ち上げられる。

# Docker経由でインストール・起動
docker run -it -v ~/.weclaw:/root/.weclaw ghcr.io/fastclaw-ai/weclaw start

追加のWeChatアカウントを接続したい場合は、本体を動かしたまま別セッションで weclaw login を実行する。複数アカウントを1つのブリッジで束ねられる設計だ。個人用アカウントと仕事用アカウントを分けている開発者は、両方から同じClaudeへメッセージを飛ばせる構成にできる。

自動検出される対応エージェント

初回起動時にWeClawが走査するのは、よく使われるAIエージェントのバイナリ群だ。Claude（claude-agent-acp および claude CLI）、Codex（codex-acp および codex exec）、Gemini、Kimi、Cursor、OpenCode、OpenClawなどが自動検出の対象になる。検出結果は ~/.weclaw/config.json にそのまま書き込まれるので、複数エージェントを併用する環境ではインストール直後から全部を使える状態になる。後から手動で編集して微調整する前提の設計だ。

3つのエージェント接続モード：ACP / CLI / HTTP

WeClawのコア設計はエージェント接続モードの3層構成にある。1つのブリッジが異なる起動方式のAIをすべて吸収できるよう、プロトコルごとの抽象が用意されている。

ACPとCLIの両方が利用可能な場合、WeClawはACPを優先的に選択する。これはプロセスとセッションを再利用できるACPのほうが応答が圧倒的に速いためだ。CLIは1メッセージごとにプロセスを起動するオーバーヘッドがある一方、--resume オプションでセッション復元できる利点がある。HTTPモードはサーバ側にAPIを置いておけばクライアント側を軽くできる。

「Auto-detection picks ACP over CLI when both are available」— WeClaw README

この設計はMCPサーバーの構築ガイドでも触れた「プロトコル選択が体感性能を決める」という原則と共通している。長時間稼働のJSON-RPCはツール連携で一般に好まれるパターンだ。

ACP・CLI・HTTPをどう選ぶか

実運用では、原則ACPを使い、ACPがないエージェントだけCLIやHTTPで補う構成が合理的だ。ACPはプロセス起動コストをゼロに近づけ、セッションコンテキストも保持し続けるので、マルチターン対話の体感が段違いに良い。1メッセージあたりの応答がコンマ数秒変わるだけでも、チャットUIでの「待ち」の感覚は大きく変わる。

CLIモードは、エージェント側がACPサーバーを提供していない過渡期のツールや、インストール制約のある環境で有効だ。--resume フラグを使えば同じセッションIDで続きから会話でき、プロセス再起動の重さをある程度軽減できる。デバッグ時に「1リクエスト=1プロセス」の独立性が欲しい場面でも役立つ。

HTTPモードは、AIエージェントをサーバ側に集約し、WeClawクライアントは軽量に保ちたい構成で便利だ。OpenAI互換APIを話す任意のサービスを繋げられるため、自社で立てた推論APIに統一して個人のマシンリソースを消費しないワークフローも組める。

チャットコマンドとエイリアス：複数AIを瞬時に切り替える

WeClawの最大の魅力はWeChatメッセージにコマンドを書くだけでAIを操作できる点だ。メッセージ先頭の識別子でエージェントやセッションを制御する。

標準エイリアスは以下の通り短くて覚えやすい。

デフォルトエージェントの切替は ~/.weclaw/config.json に永続化されるため、サーバを再起動しても直前の選択が復元される。

カスタムエイリアスも定義できる。自分が打ちやすい略称をプロジェクトごとに割り当てられるのは日常運用で効いてくる。

{
  "agents": {
    "claude": {
      "type": "acp",
      "aliases": ["ai", "c"]
    }
  }
}

この設定があると /ai hello や /c hello でClaudeにルーティングされる。/cwd でワークスペースディレクトリを切り替えれば、同じブリッジから別プロジェクトのコードベースをAIに見せられる。

Browser Useのようなブラウザ自動化ツールと組み合わせて、WeChatから「この商品ページを要約して」といった指示をAIに投げるワークフローも実装できる。

セッション管理の考え方

WeClawはセッションの概念を持つ。同じ会話を続ける限り、AIエージェント側のコンテキスト（会話履歴・スタックしたツール使用・作業中のファイル状態など）はACPなら常駐プロセスがそのまま保持し、CLIなら --resume によって呼び戻される。話題が切り替わったら /new で明示的にセッションをクリアするのがコツだ。クリアしないまま別の質問を投げると、前の話題の残響がAIの応答に混ざってしまう。

また /cwd /path/to/other-project で作業ディレクトリを切り替えると、以降のAI操作の基準ディレクトリが変わる。複数プロジェクトを並行して触る開発者は、カスタムエイリアスを使ってプロジェクト名から作業ディレクトリへの切替を一発コマンド化しておくとさらに楽になる。

運用で実際に便利な管理コマンド

/info は現在アクティブなエージェント名・モード・作業ディレクトリを一覧表示してくれる。会話を長く続けていると「いま自分はClaudeと話しているのかCodexなのか」が分からなくなることがあるが、このコマンドひとつで即確認できる。/help はチートシートとして重宝する。これらの管理系コマンドはどれも軽く、AIへの問いかけを中断させない設計だ。

設定ファイル完全解説：config.jsonで全てを制御する

WeClawの振る舞いはすべて ~/.weclaw/config.json に集約される。以下はClaude（ACP）、Codex（ACP）、OpenClaw（HTTP）の3種を同居させた設定例だ。

{
  "default_agent": "claude",
  "agents": {
    "claude": {
      "type": "acp",
      "command": "/usr/local/bin/claude-agent-acp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-xxx"
      },
      "model": "sonnet"
    },
    "codex": {
      "type": "acp",
      "command": "/usr/local/bin/codex-acp",
      "env": {
        "OPENAI_API_KEY": "sk-xxx"
      }
    },
    "openclaw": {
      "type": "http",
      "endpoint": "https://api.example.com/v1/chat/completions",
      "api_key": "sk-xxx",
      "model": "openclaw:main"
    }
  }
}

1つのJSONに複数エージェントを並べ、default_agent でデフォルト選択を決める構造だ。認証キーはエージェントごとに env ブロックで分離できるため、個人APIキーと業務用APIキーを同じブリッジで混在させられる。

環境変数による上書き

CIや一時的な差し替えでは、環境変数で上書きするのがベストプラクティスだ。

パーミッションバイパス：WeChat経由で操作不可な承認を回避

一部のAIエージェントは、破壊的操作を実行するときにインタラクティブな承認プロンプトを表示する。WeChat越しではこのプロンプトに答えられないため、CLIモードでは args フラグを明示的に渡して回避する。

{
  "claude": {
    "type": "cli",
    "command": "/usr/local/bin/claude",
    "cwd": "/home/user/my-project",
    "args": ["--dangerously-skip-permissions"]
  },
  "codex": {
    "type": "cli",
    "command": "/usr/local/bin/codex",
    "cwd": "/home/user/my-project",
    "args": ["--skip-git-repo-check"]
  }
}

cwd で作業ディレクトリを明示する。省略時は ~/.weclaw/workspace がデフォルトになる。これらのフラグはセーフティチェックを無効化する破壊的オプションなので、信頼できる環境以外では使わないこと。ACPモードのエージェントは内部的に権限を処理するため、こうしたフラグは不要だ。

ForgeCodeのようなAIコーディングツールと同じように、権限モデルの扱い方がエージェント設計の分水嶺になる。チャット経由でのAI操作は「確認プロンプトに答えられない」という制約を前提に設計しないと、意図せずAIが止まって返答が返ってこなくなる事故が起きる。

カスタム環境変数の渡し方

各エージェント設定の env ブロックには自由なキーを追加できる。社内APIのトークン、プロキシ設定、デバッグフラグなど、エージェントプロセスに渡したい値はここに書けばよい。

{
  "default_agent": "claude",
  "agents": {
    "claude": {
      "type": "acp",
      "command": "/usr/local/bin/claude-agent-acp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-xxx",
        "HTTPS_PROXY": "http://corp-proxy:8080",
        "CUSTOM_DEBUG_FLAG": "1"
      }
    }
  }
}

この env は親プロセス（WeClaw本体）の環境と独立しており、エージェントごとに異なるAPIキーやプロキシ設定を混在できる。複数アカウント・複数組織のAIを同じマシンで同時運用するなら非常に便利だ。

メディア対応とプロアクティブ送信：双方向の自動化を設計する

WeClawは単なるテキストブリッジではなく、画像・動画・ファイル・音声メッセージの双方向転送に対応している。日常利用ではこの機能が効いてくる。

音声メッセージ：WeChatの音声認識をそのまま利用

WeChatで音声メッセージを送ると、WeClawはWeChatの音声認識APIで自動的にテキスト化し、AIエージェントに転送する。重複する音声メッセージイベントは自動デデュプリケーションされるため、ネットワークの都合で同じ音声が2回届いても返信が二重化することはない。

AIからの画像返信：Markdown画像をCDNに転送

AIエージェントの応答にMarkdown画像記法（![](url) 形式）が含まれる場合、WeClawはURLを抽出してダウンロードし、WeChat CDNにAES-128-ECB暗号化でアップロードしてから画像メッセージとして送信する。テキストと画像が混在した応答をWeChat側で自然に表示できる。

加えて、AIの応答は自動的にMarkdownからプレーンテキストに整形される。コードフェンスは除去、リンクは表示テキストのみ、太字・斜体のマーカーは消える。WeChatはMarkdownを解釈しないため、この前処理がないと記号が目立って読みづらくなる。

プロアクティブメッセージング：AI側から能動的に送る

WeClawはユーザーからの問いかけを待たずに、こちらから能動的にメッセージを送る仕組みを提供する。CLIとHTTP APIの両方で使える。

# CLIでテキスト送信
weclaw send --to "[email protected]" --text "Hello from weclaw"

# CLIで画像送信
weclaw send --to "[email protected]" --media "https://example.com/photo.png"

# CLIでテキスト+画像を同時送信
weclaw send --to "[email protected]" --text "Check this out" --media "https://example.com/photo.png"

# CLIでファイル送信（PDF/DOC/ZIP等）
weclaw send --to "[email protected]" --media "https://example.com/report.pdf"

HTTP APIは weclaw start 実行中に 127.0.0.1:18011 で待ち受ける。cronやGitHub Actionsから叩ける。

# テキスト送信
curl -X POST http://127.0.0.1:18011/api/send \
  -H "Content-Type: application/json" \
  -d '{"to": "[email protected]", "text": "Hello from weclaw"}'

# 画像送信
curl -X POST http://127.0.0.1:18011/api/send \
  -H "Content-Type: application/json" \
  -d '{"to": "[email protected]", "media_url": "https://example.com/photo.png"}'

# テキスト+メディア同時
curl -X POST http://127.0.0.1:18011/api/send \
  -H "Content-Type: application/json" \
  -d '{"to": "[email protected]", "text": "See this", "media_url": "https://example.com/photo.png"}'

対応メディアは画像（PNG、JPG、GIF、WebP）、動画（MP4、MOV）、ファイル（PDF、DOC、ZIP等）の幅広い形式をカバーする。WECLAW_API_ADDR 環境変数でリッスンアドレスを 0.0.0.0:18011 などに変更すれば、別ホストからのAPI呼び出しも受けられる。

この仕組みがあるから、AIエージェントのバッチ処理結果や監視アラートをWeChatに流し込む双方向ワークフローが組める。

プロアクティブ送信の実用例

例えば、GitHub Actionsのデプロイ成功通知をWeChatに飛ばしたいとき、ワークフロー末尾に curl を1つ足すだけで済む。Slackに送るのと同じ感覚でWeChatに送れる。AIエージェントがバックグラウンドで長時間タスクを実行し、完了時にユーザーへ結果を届ける「非同期エージェント」のパターンも組みやすい。ユーザーはスマホでWeChat通知を受け取り、結果を確認したらそのまま続きの指示を返信できる。

もうひとつ実用的な例が、cronによる定期レポートだ。毎朝8時に前日分のサーバログ要約をClaudeに生成させ、結果をWeChat経由で自分に送る、といった運用は数十行のシェルスクリプトで実装できる。これまでメールやSlackでやっていた通知フローを、WeChatを主戦場にしている開発者はそのまま置き換えられる。

バックグラウンド運用とサービス登録：常駐させるための作法

WeClawはデフォルトでバックグラウンドプロセスとして動く。サーバ常駐の管理コマンドが揃っている。

# 起動（バックグラウンド）
weclaw start

# 実行状態の確認
weclaw status

# 停止
weclaw stop

# フォアグラウンド起動（デバッグ時のログを直接見たい）
weclaw start -f

# アップデート（実行中なら自動再起動）
weclaw update

# 現バージョンの確認
weclaw version

ログは ~/.weclaw/weclaw.log に書き出される。問題が起きたらまずこのファイルを確認する運用になる。

OS起動時の自動起動：launchdとsystemd

OS起動と同時にWeClawを立ち上げるサービス定義がリポジトリに同梱されている。macOSはlaunchd、Linuxはsystemdだ。

# macOS: launchdでサービス登録
cp service/com.fastclaw.weclaw.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.fastclaw.weclaw.plist

# Linux: systemdでサービス登録
sudo cp service/weclaw.service /etc/systemd/system/
sudo systemctl enable --now weclaw

Docker常駐構成：HTTPモードとの相性が良い

Dockerで常駐させる場合は、認証済みの ~/.weclaw をボリュームマウントすることで起動ごとのログイン再実施を避けられる。

# イメージ自作
docker build -t weclaw .

# 初回ログイン（インタラクティブ・QRコード読み取り）
docker run -it -v ~/.weclaw:/root/.weclaw weclaw login

# HTTPエージェントでバックグラウンド起動
docker run -d --name weclaw \
  -v ~/.weclaw:/root/.weclaw \
  -e OPENCLAW_GATEWAY_URL=https://api.example.com \
  -e OPENCLAW_GATEWAY_TOKEN=sk-xxx \
  weclaw

# ログ確認
docker logs -f weclaw

Docker環境ではACP/CLIモードのエージェントバイナリが標準イメージに含まれない点に注意。HTTPモードなら環境変数だけで完結するため、コンテナ運用との相性は最良だ。

リリースとアップデート

リポジトリ側のワークフローはGoのマトリクスビルドで darwin/linux/windows × amd64/arm64 の全組み合わせをリリースする。ユーザー側のアップデートは weclaw update で完結し、実行中なら自動的に再起動される。

類似ツールとの比較：WeClawの立ち位置

AIエージェントをチャット経由で操作するブリッジは、プラットフォーム別に複数存在する。WeClawがどこに位置するかを整理する。

WeClawの最大の差別化は「1ブリッジ・多エージェント」の構造にある。Slack/DiscordのBot統合は基本的に1ボットで1エージェントを提供するため、Claude用とCodex用で別のボットをセットアップすることになる。WeClawは1つの config.json に全エージェントをリストし、WeChat側は1つのアカウントで全部を叩ける。

「Switching default agent is persisted to config — survives restarts」— WeClaw README

もちろんWeClawにも制約はある。WeChatアカウントのログインはQRコードを介した個人認証で、業務用のBot API経由ではない。このため商用サービスというより、個人・研究用途のAIフロントエンドとして設計されていることをREADMEは明確に述べている。

開発者向け：ホットリロードとコントリビュート

WeClawはGoで書かれているため、開発者がフォークして機能追加するのも難しくない。READMEの Development セクションには最小限のコマンドが載っている。

# ホットリロードで開発
make dev

# バイナリビルド
go build -o weclaw .

# 起動
./weclaw start

リリースはGitタグをプッシュすることでGitHub Actionsが darwin/linux/windows × amd64/arm64 の全組み合わせをビルドし、チェックサム付きでGitHub Releasesにアップロードする。

# 新バージョンのタグを打ってリリースを走らせる
git tag v0.1.0
git push origin v0.1.0

make dev はファイル変更検知付きのホットリロードを提供するため、メッセージ解釈ロジックやエージェントアダプタを手探りで弄りながら動作確認できる。ACP/CLI/HTTPの抽象がそれぞれ分離されているので、新しいAIエージェントのアダプタを追加するだけの小さなPRも出しやすい構造だ。

継続的な機能追加

README末尾のContributors画像は自動生成で、GitHub上のコントリビューター一覧を動的に表示する。Star HistoryチャートもREADMEに埋め込まれており、プロジェクトの成長を外から確認できる。

導入前 vs 導入後：運用がどう変わるか

WeClawを入れる前後で日常運用がどう変わるかを整理する。

特にモバイル運用でのメリットが大きい。出先でノートPCを開けないとき、WeChatアプリ1つで複数AIをコマンド切替できるのは、移動の多い開発者・研究者にとって日常的な効率化になる。

向いているユースケースと向いていないユースケース

READMEの免責事項が明記しているように、WeClawは個人学習用のツールだ。WeChat側の利用規約・認証フローとの兼ね合いで、商用展開には別の枠組み（公式のWeChatオープンプラットフォーム等）を検討すべきケースが多い。

セキュリティとプライバシーの視点

WeClawを常駐させる以上、自分のWeChat会話がブリッジプロセスを経由することになる。設定ファイルには各種APIキーが平文で入るため、リポジトリに誤って含めないよう .gitignore で確実に除外する運用が必須だ。macOSならKeychain、LinuxならGNOME Keyringなどと連携して環境変数として注入し、config.json にはダミー値だけ残しておくのが安全寄りのやり方になる。

またログファイル ~/.weclaw/weclaw.log にはメッセージ内容の一部が書き出される可能性がある。機密情報を扱う場合はログローテーションとアクセス制御を忘れずに設定する。複数の開発者が同じサーバに相乗りしてWeClawを動かすのは、個人のWeChatアカウントが絡む以上避けたほうが無難だ。

📌 まとめ：WeClawが示す「AIフロントエンドのコモディティ化」

WeClawの技術ポイントを最後に整理する。

1. 構造: Go製ブリッジ、~/.weclaw/config.json が単一の設定ソース
2. 接続モード: ACP（最速・常駐）/ CLI（毎回起動・--resume）/ HTTP（OpenAI互換）の3層
3. エージェント切替: /cc /cx /gm 等のエイリアスで瞬時切替、カスタム定義も可
4. メディア: 画像・動画・ファイル・音声に双方向対応、AI画像返信はWeChat CDNへ暗号化転送
5. プロアクティブ: weclaw send CLI と HTTP API（127.0.0.1:18011）で能動送信
6. 運用: launchd / systemd / Dockerで常駐、weclaw update でホットアップデート
7. 制約: 個人学習用、商用展開は公式WeChatオープンプラットフォームが推奨

WeClawが示すのは、AIエージェントの「入口」はブラウザやIDEの専用UIだけでなく、ユーザーが毎日使っているチャットアプリに置けるという可能性だ。Slack BotやDiscord Botでは「1ボット=1AI」が普通だったが、WeClawは1つのブリッジで複数エージェントを瞬時に切り替える。この発想が普及すれば、TelegramでもLINEでも同じ構造のブリッジが生まれるだろう。

「connect WeChat to AI agents」— このシンプルな一行が、13億人が使うチャット基盤を開発者の道具箱に変える。

Claude CodeのMCPサーバー構築ガイドとあわせて読むと、「外部データとの接続」「AI操作の入口」の両面をカバーできる。WeClawは後者の具体的な実装例だ。

まずは curl -sSL .../install.sh | sh から始めてみよう。QRコードをスキャンすれば、数分後には手元のWeChatから複数のAIエージェントが呼び出せる。

参照ソース

• fastclaw-ai/weclaw — 公式GitHubリポジトリ — README、インストールスクリプト、設定例、サービス定義
• fastclaw-ai/weclaw README_CN — 中国語版README（英語版と併読で補完情報）
• @tencent-weixin/openclaw-weixin — WeClawのインスピレーション元プロジェクト
• Agent Client Protocol (ACP) 概要 — ACPモードが採用するJSON-RPC over stdio仕様