lzh/picoclaw

Fork 0

mirror of https://github.com/sipeed/picoclaw.git synced 2026-05-25 16:00:35 +00:00

Files

T

hehaijunandhenry 5c0492900e add MQTT channel support

2026-04-29 18:27:33 +08:00

23 KiB

Raw Permalink Blame History

💬 チャットアプリ設定

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	ドキュメント
微信 (Weixin)	⭐ 簡単	ネイティブ QR スキャン（Tencent iLink API）	ドキュメント
Slack	⭐ 簡単	Socket Mode (公開 IP 不要)、エンタープライズ対応	ドキュメント
Matrix	⭐⭐ 中程度	フェデレーションプロトコル、セルフホスト対応	ドキュメント
QQ	⭐⭐ 中程度	公式ボット API、中国コミュニティ向け	ドキュメント
DingTalk	⭐⭐ 中程度	Stream モード（公開 IP 不要）、企業向け	ドキュメント
LINE	⭐⭐⭐ やや難	HTTPS Webhook が必要	ドキュメント
WeCom (企業微信)	⭐⭐⭐ やや難	グループ Bot (Webhook)、カスタムアプリ (API)、AI Bot 対応	ガイド
Feishu (飛書)	⭐⭐⭐ やや難	エンタープライズコラボレーション、機能豊富	ドキュメント
IRC	⭐⭐ 中程度	サーバー + TLS 設定	ドキュメント
OneBot	⭐⭐ 中程度	NapCat/Go-CQHTTP 互換、コミュニティエコシステム充実	ドキュメント
MQTT	⭐ 簡単	ブローカー経由で任意の MQTT クライアントと通信	ドキュメント
MaixCam	⭐ 簡単	Sipeed AI カメラハードウェア統合チャネル	ドキュメント
Pico	⭐ 簡単	PicoClaw ネイティブプロトコルチャネル

Telegram（推奨）

1. Bot を作成

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

2. 設定

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

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

3. 実行

picoclaw gateway

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

PicoClaw は統一されたコマンド定義を使用します。起動時に Telegram がサポートするコマンド（例: /start、/help、/show、/list、/use、/btw）を 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. 設定

{
  "channel_list": {
    "discord": {
      "enabled": true,
      "type": "discord",
      "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 はサーバーチャネル内のすべてのメッセージに応答します。@メンション時のみ応答するには：

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

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

{
  "channel_list": {
    "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 のままにします。

設定（ネイティブ）

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

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

微信 (Weixin)

PicoClaw は Tencent iLink 公式 API を使用して WeChat 個人アカウントへの接続をサポートしています。

1. ログイン

インタラクティブな QR ログインフローを実行します：

picoclaw auth weixin

WeChat モバイルアプリで表示された QR コードをスキャンしてください。ログイン成功後、トークンが設定ファイルに保存されます。

2. 設定

（オプション）ボットと会話できるユーザーを制限するために allow_from に WeChat ユーザー ID を追加します：

{
  "channel_list": {
    "weixin": {
      "enabled": true,
      "type": "weixin",
      "token": "YOUR_TOKEN",
      "allow_from": ["YOUR_USER_ID"]
    }
  }
}

3. 実行

picoclaw gateway

Matrix

1. Bot アカウントを準備

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

2. 設定

{
  "channel_list": {
    "matrix": {
      "enabled": true,
      "type": "matrix",
      "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 開放プラットフォームでは、OpenClaw 互換ボットのワンクリックセットアップページが提供されています：

QQ Bot クイックスタートを開き、QR コードをスキャンしてログイン
ボットが自動的に作成されます — App ID と App Secret をコピー
PicoClaw を設定：

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

picoclaw gateway を実行し、QQ を開いてボットとチャット

App Secret は一度しか表示されません。すぐに保存してください — 再度表示するとリセットされます。

クイックセットアップで作成されたボットは、最初は作成者のみが使用でき、グループチャットには対応していません。グループアクセスを有効にするには、QQ 開放プラットフォームでサンドボックスモードを設定してください。

手動セットアップ

ボットを手動で作成する場合：

QQ 開放プラットフォームにログインして開発者登録
QQ ボットを作成 — アバターと名前をカスタマイズ
ボット設定から App ID と App Secret をコピー
上記の設定を行い、picoclaw gateway を実行

Slack

1. Slack App を作成

Slack API にアクセスして新しいアプリを作成
OAuth & Permissions で Bot スコープを追加：chat:write、app_mentions:read、im:history、im:read、im:write
アプリをワークスペースにインストール
Bot Token（xoxb-...）と App-Level Token（xapp-...、Socket Mode を有効にして取得）をコピー

2. 設定

{
  "channel_list": {
    "slack": {
      "enabled": true,
      "type": "slack",
      "bot_token": "xoxb-YOUR-BOT-TOKEN",
      "app_token": "xapp-YOUR-APP-TOKEN",
      "allow_from": []
    }
  }
}

3. 実行

picoclaw gateway

IRC

1. 設定

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

オプション：NickServ 認証用の nickserv_password、SASL 認証用の sasl_user/sasl_password。

2. 実行

picoclaw gateway

ボットは IRC サーバーに接続し、指定されたチャネルに参加します。

DingTalk

1. Bot を作成

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

2. 設定

{
  "channel_list": {
    "dingtalk": {
      "enabled": true,
      "type": "dingtalk",
      "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. 設定

{
  "channel_list": {
    "line": {
      "enabled": true,
      "type": "line",
      "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 (飛書)

PicoClaw は WebSocket/SDK モードで飛書に接続します — 公開 Webhook URL やコールバックサーバーは不要です。

1. アプリを作成

飛書開放プラットフォームにアクセスしてアプリケーションを作成
アプリ設定で ボット 機能を有効化
バージョンを作成してアプリを公開（アプリは公開しないと有効になりません）
App ID（cli_ で始まる）と App Secret をコピー

2. 設定

{
  "channel_list": {
    "feishu": {
      "enabled": true,
      "type": "feishu",
      "app_id": "cli_xxx",
      "app_secret": "YOUR_APP_SECRET",
      "allow_from": []
    }
  }
}

オプション：encrypt_key と verification_token でイベント暗号化（本番環境推奨）。

3. 実行してチャット

picoclaw gateway

飛書を開き、ボット名を検索してチャットを開始できます。ボットをグループに追加することもできます — group_trigger.mention_only: true を設定すると @メンション時のみ応答します。

詳細なオプションについては飛書チャネル設定ガイドを参照してください。

WeCom (企業微信)

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

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

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

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

1. Bot を作成

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

2. 設定

{
  "channel_list": {
    "wecom": {
      "enabled": true,
      "type": "wecom",
      "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. 設定

{
  "channel_list": {
    "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:18790/webhook/wecom-aibot
Token をコピーし、「ランダム生成」をクリックして EncodingAESKey を取得

2. 設定

{
  "channel_list": {
    "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": "こんにちは！何かお手伝いできますか？",
      "processing_message": "⏳ Processing, please wait. The results will be sent shortly."
    }
  }
}

3. 実行

picoclaw gateway

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

OneBot（OneBot プロトコル経由の QQ）

OneBot は QQ ボット向けのオープンプロトコルです。PicoClaw は OneBot v11 互換の実装（例：Lagrange、NapCat）に WebSocket で接続します。

1. OneBot 実装をセットアップ

OneBot v11 互換の QQ ボットフレームワークをインストールして実行します。WebSocket サーバーを有効にしてください。

2. 設定

{
  "channel_list": {
    "onebot": {
      "enabled": true,
      "type": "onebot",
      "ws_url": "ws://127.0.0.1:8080",
      "access_token": "",
      "allow_from": []
    }
  }
}

フィールド	説明
`ws_url`	OneBot 実装の WebSocket URL
`access_token`	認証用アクセストークン（OneBot 側で設定している場合）
`reconnect_interval`	再接続間隔（秒）（デフォルト：5）

3. 実行

picoclaw gateway

MaixCam

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

{
  "channel_list": {
    "maixcam": {
      "enabled": true,
      "type": "maixcam"
    }
  }
}

picoclaw gateway

MQTT

任意の MQTT クライアントがブローカーを介して PicoClaw と通信できます。デバイスやサービスがブローカーにリクエストをパブリッシュし、PicoClaw がサブスクライブして処理し、レスポンスをパブリッシュして返します。

1. 設定

{
  "channel_list": {
    "mqtt": {
      "enabled": true,
      "type": "mqtt",
      "settings": {
        "broker": "ssl://your-broker:8883",
        "agent_id": "assistant",
        "topic_prefix": "/picoclaw",
        "keep_alive": 60,
        "qos": 0
      }
    }
  }
}

ユーザー名とパスワードは ~/.picoclaw/.security.yml に記載します：

channel_list:
  mqtt:
    settings:
      username: your_username
      password: your_password

トピック形式

{prefix}/{agent_id}/{client_id}/request    # クライアント → PicoClaw
{prefix}/{agent_id}/{client_id}/response   # PicoClaw → クライアント

client_id はクライアントアプリケーションがデバイスやセッションを識別するために設定します。

2. 起動

picoclaw gateway

3. テスト

mosquitto_pub -t "/picoclaw/assistant/device1/request" \
  -m '{"text": "こんにちは"}'

mosquitto_sub -t "/picoclaw/assistant/device1/response"

完全な設定オプションは MQTT チャンネルドキュメントを参照してください。

23 KiB Raw Permalink Blame History Unescape Escape

💬 チャットアプリ設定

💬 チャットアプリ連携

チャネル一覧

23 KiB

Raw Permalink Blame History