picoclaw/docs/ja/chat-apps.md

💬 チャットアプリ設定

README に戻る

💬 チャットアプリ連携

PicoClaw は複数のチャットプラットフォームをサポートしており、Agent をどこにでも接続できます。

注意: すべての Webhook ベースのチャネル（LINE、WeCom など）は、共有 Gateway HTTP サーバー（gateway.host:gateway.port、デフォルト 127.0.0.1:18790）上で提供されます。チャネルごとにポートを設定する必要はありません。注意：飛書（Feishu）は WebSocket/SDK モードを使用し、共有 HTTP Webhook サーバーは使用しません。

チャネル一覧

チャネル	セットアップ難易度	特徴	ドキュメント
Telegram	⭐ 簡単	推奨、音声テキスト変換対応、ロングポーリング（公開 IP 不要）	ドキュメント
Discord	⭐ 簡単	Socket Mode、グループ/DM 対応、Bot エコシステム充実	ドキュメント
WhatsApp	⭐ 簡単	ネイティブ (QR スキャン) または Bridge URL	ドキュメント
Slack	⭐ 簡単	Socket Mode (公開 IP 不要)、エンタープライズ対応	ドキュメント
Matrix	⭐⭐ 中程度	フェデレーションプロトコル、セルフホスト対応	ドキュメント
QQ	⭐⭐ 中程度	公式ボット API、中国コミュニティ向け	ドキュメント
DingTalk	⭐⭐ 中程度	Stream モード（公開 IP 不要）、企業向け	ドキュメント
LINE	⭐⭐⭐ やや難	HTTPS Webhook が必要	ドキュメント
WeCom (企業微信)	⭐⭐⭐ やや難	グループ Bot (Webhook)、カスタムアプリ (API)、AI Bot 対応	Bot / App / AI Bot
Feishu (飛書)	⭐⭐⭐ やや難	エンタープライズコラボレーション、機能豊富	ドキュメント
IRC	⭐⭐ 中程度	サーバー + TLS 設定	-
OneBot	⭐⭐ 中程度	NapCat/Go-CQHTTP 互換、コミュニティエコシステム充実	ドキュメント
MaixCam	⭐ 簡単	Sipeed AI カメラハードウェア統合チャネル	ドキュメント
Pico	⭐ 簡単	PicoClaw ネイティブプロトコルチャネル

---

Telegram（推奨）

1. Bot を作成

• Telegram を開き、@BotFather を検索
• /newbot を送信し、プロンプトに従う
• Token をコピー

2. 設定

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["YOUR_USER_ID"]
    }
  }
}

Telegram の @userinfobot から User ID を取得できます。

3. 実行

picoclaw gateway

4. Telegram コマンドメニュー（起動時に自動登録）

PicoClaw は統一されたコマンド定義を使用します。起動時に Telegram がサポートするコマンド（例: /start、/help、/show、/list）を Bot コマンドメニューに自動登録し、メニュー表示と実際の動作を一致させます。 Telegram 側はコマンドメニュー登録機能を保持し、汎用コマンドの実行は Agent Loop 内の commands executor で統一的に処理されます。

ネットワークや API の一時的なエラーで登録に失敗しても、チャネルの起動はブロックされません。システムがバックグラウンドで自動リトライします。

Discord

1. Bot を作成

• https://discord.com/developers/applications にアクセス
• アプリケーションを作成 → Bot → Bot を追加
• Bot Token をコピー

2. Intents を有効化

• Bot 設定で MESSAGE CONTENT INTENT を有効化
• （オプション）メンバーデータに基づくホワイトリストが必要な場合は SERVER MEMBERS INTENT を有効化

3. User ID を取得

• Discord 設定 → 詳細設定 → 開発者モード を有効化
• アバターを右クリック → ユーザー ID をコピー

4. 設定

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["YOUR_USER_ID"]
    }
  }
}

5. Bot を招待

• OAuth2 → URL Generator
• Scopes: bot
• Bot Permissions: Send Messages, Read Message History
• 生成された招待リンクを開き、Bot をサーバーに追加

オプション：グループトリガーモード

デフォルトでは Bot はサーバーチャネル内のすべてのメッセージに応答します。@メンション時のみ応答するには：

{
  "channels": {
    "discord": {
      "group_trigger": { "mention_only": true }
    }
  }
}

キーワードプレフィックスでトリガーすることもできます（例: !bot）：

{
  "channels": {
    "discord": {
      "group_trigger": { "prefixes": ["!bot"] }
    }
  }
}

6. 実行

picoclaw gateway

WhatsApp（ネイティブ whatsmeow）

PicoClaw は 2 つの WhatsApp 接続方式をサポートしています：

• ネイティブ（推奨）： プロセス内で whatsmeow を使用。独立した Bridge は不要です。"use_native": true に設定し、bridge_url を空にします。初回実行時に WhatsApp で QR コードをスキャン（リンクデバイス）。セッションはワークスペース配下（例: workspace/whatsapp/）に保存されます。ネイティブチャネルはオプションビルドで、-tags whatsapp_native でコンパイルします（例: make build-whatsapp-native または go build -tags whatsapp_native ./cmd/...）。
• Bridge： 外部 WebSocket Bridge に接続。bridge_url（例: ws://localhost:3001）を設定し、use_native を false のままにします。

設定（ネイティブ）

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "use_native": true,
      "session_store_path": "",
      "allow_from": []
    }
  }
}

session_store_path が空の場合、セッションは <workspace>/whatsapp/ に保存されます。picoclaw gateway を実行し、初回実行時にターミナルに表示される QR コードをスキャンしてください（WhatsApp → リンクデバイス）。

Matrix

1. Bot アカウントを準備

• お好みの homeserver（例: https://matrix.org またはセルフホスト）を使用
• Bot ユーザーを作成し、access token を取得

2. 設定

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "user_id": "@your-bot:matrix.org",
      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
      "allow_from": []
    }
  }
}

3. 実行

picoclaw gateway

すべてのオプション（device_id、join_on_invite、group_trigger、placeholder、reasoning_channel_id）については Matrix チャネル設定ガイド を参照してください。

QQ

1. Bot を作成

• QQ 開放プラットフォーム にアクセス
• アプリケーションを作成 → AppID と AppSecret を取得

2. 設定

{
  "channels": {
    "qq": {
      "enabled": true,
      "app_id": "YOUR_APP_ID",
      "app_secret": "YOUR_APP_SECRET",
      "allow_from": []
    }
  }
}

allow_from を空にするとすべてのユーザーを許可します。QQ 番号を指定してアクセスを制限することもできます。

3. 実行

picoclaw gateway

Slack

1. Slack App を作成

• Slack API でアプリを作成
• Socket Mode を有効化
• Bot Token と App-Level Token を取得

2. 設定

{
  "channels": {
    "slack": {
      "enabled": true,
      "bot_token": "xoxb-YOUR_BOT_TOKEN",
      "app_token": "xapp-YOUR_APP_TOKEN",
      "allow_from": []
    }
  }
}

3. 実行

picoclaw gateway

IRC

1. 設定

{
  "channels": {
    "irc": {
      "enabled": true,
      "server": "irc.libera.chat:6697",
      "nick": "picoclaw-bot",
      "use_tls": true,
      "channels_to_join": ["#your-channel"],
      "allow_from": []
    }
  }
}

2. 実行

picoclaw gateway

DingTalk

1. Bot を作成

• 開放プラットフォーム にアクセス
• 内部アプリを作成
• Client ID と Client Secret をコピー

2. 設定

{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "allow_from": []
    }
  }
}

allow_from を空にするとすべてのユーザーを許可します。DingTalk ユーザー ID を指定してアクセスを制限することもできます。

3. 実行

picoclaw gateway

LINE

1. LINE 公式アカウントを作成

• LINE Developers Console にアクセス
• Provider を作成 → Messaging API チャネルを作成
• Channel Secret と Channel Access Token をコピー

2. 設定

{
  "channels": {
    "line": {
      "enabled": true,
      "channel_secret": "YOUR_CHANNEL_SECRET",
      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
      "webhook_path": "/webhook/line",
      "allow_from": []
    }
  }
}

LINE Webhook は共有 Gateway サーバー（gateway.host:gateway.port、デフォルト 127.0.0.1:18790）上で提供されます。

3. Webhook URL を設定

LINE は HTTPS Webhook が必要です。リバースプロキシまたはトンネルを使用してください：

# 例：ngrok を使用（Gateway デフォルトポートは 18790）
ngrok http 18790

LINE Developers Console で Webhook URL を https://your-domain/webhook/line に設定し、Use webhook を有効にしてください。

4. 実行

picoclaw gateway

グループチャットでは、Bot は @メンション時のみ応答します。返信は元のメッセージを引用します。

Feishu (飛書)

1. アプリを作成

• 飛書開放プラットフォーム にアクセス
• 企業カスタムアプリを作成
• App ID と App Secret を取得

2. 設定

{
  "channels": {
    "feishu": {
      "enabled": true,
      "app_id": "cli_xxx",
      "app_secret": "xxx",
      "encrypt_key": "",
      "verification_token": "",
      "allow_from": []
    }
  }
}

3. 実行

picoclaw gateway

WeCom (企業微信)

PicoClaw は 3 種類の WeCom 統合をサポートしています：

方式 1: グループ Bot (Bot) — セットアップ簡単、グループチャット対応 方式 2: カスタムアプリ (App) — より多機能、プロアクティブメッセージング、プライベートチャットのみ 方式 3: AI Bot — 公式 AI Bot、ストリーミング返信、グループ・プライベートチャット対応

詳細なセットアップ手順は WeCom AI Bot 設定ガイド を参照してください。

クイックセットアップ — グループ Bot：

1. Bot を作成

• WeCom 管理コンソール → グループチャット → グループ Bot を追加
• Webhook URL をコピー（形式：https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx）

2. 設定

{
  "channels": {
    "wecom": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
      "webhook_path": "/webhook/wecom",
      "allow_from": []
    }
  }
}

WeCom Webhook は共有 Gateway サーバー（gateway.host:gateway.port、デフォルト 127.0.0.1:18790）上で提供されます。

クイックセットアップ — カスタムアプリ：

1. アプリを作成

• WeCom 管理コンソール → アプリ管理 → アプリを作成
• AgentId と Secret をコピー
• 「マイ企業」ページで CorpID をコピー

2. メッセージ受信を設定

• アプリ詳細で「メッセージ受信」→「API を設定」をクリック
• URL を http://your-server:18790/webhook/wecom-app に設定
• Token と EncodingAESKey を生成

3. 設定

{
  "channels": {
    "wecom_app": {
      "enabled": true,
      "corp_id": "wwxxxxxxxxxxxxxxxx",
      "corp_secret": "YOUR_CORP_SECRET",
      "agent_id": 1000002,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-app",
      "allow_from": []
    }
  }
}

4. 実行

picoclaw gateway

注意: WeCom Webhook コールバックは Gateway ポート（デフォルト 18790）で提供されます。HTTPS にはリバースプロキシを使用してください。

クイックセットアップ — AI Bot：

1. AI Bot を作成

• WeCom 管理コンソール → アプリ管理 → AI Bot
• AI Bot 設定でコールバック URL を設定：http://your-server:18791/webhook/wecom-aibot
• Token をコピーし、「ランダム生成」をクリックして EncodingAESKey を取得

2. 設定

{
  "channels": {
    "wecom_aibot": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
      "welcome_message": "こんにちは！何かお手伝いできますか？"
    }
  }
}

3. 実行

picoclaw gateway

注意: WeCom AI Bot はストリーミングプルプロトコルを使用しており、返信タイムアウトの心配はありません。長時間タスク（30 秒超）は自動的に response_url プッシュ配信に切り替わります。

OneBot

1. 設定

NapCat / Go-CQHTTP などの OneBot 実装と互換性があります。

{
  "channels": {
    "onebot": {
      "enabled": true,
      "allow_from": []
    }
  }
}

2. 実行

picoclaw gateway

MaixCam

Sipeed AI カメラハードウェア向けの統合チャネルです。

{
  "channels": {
    "maixcam": {
      "enabled": true
    }
  }
}

picoclaw gateway