opencode/picoclaw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add channel docs in 6 languages, QQ quick setup, picoclaw.io install

Browse source 
Install section:
- README (all 6 languages): add picoclaw.io as recommended download, GitHub Releases as secondary

QQ channel:
- Add quick setup via q.qq.com/qqbot/openclaw (one-click bot creation)
- Add manual setup as fallback
- Sync to all 6 languages

chat-apps.md:
- Add Feishu, Slack, IRC, OneBot detail sections (all 6 languages)
- Add MaixCam section to ja/fr/pt-br/vi
- Fix all channel doc links to point to correct language version

Channel docs (6 languages each):
- telegram, discord, qq, feishu, maixcam
- dingtalk, line, slack, onebot
- wecom/wecom_aibot, wecom/wecom_app, wecom/wecom_bot
This commit is contained in:
BeaconCat 2026-03-20 21:03:02 +08:00
parent 48d330cf9e
commit 20fe265ad3
84 changed files with 3733 additions and 223 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
README.fr.md
View file

@ -162,11 +162,15 @@ PicoClaw peut être déployé sur pratiquement n'importe quel appareil Linux !
## 📦 Installation
### Installer avec un binaire précompilé
### Télécharger depuis picoclaw.io (Recommandé)
Téléchargez le binaire pour votre plateforme depuis la page des [Releases](https://github.com/sipeed/picoclaw/releases).
Visitez **[picoclaw.io](https://picoclaw.io)** — le site officiel détecte automatiquement votre plateforme et propose un téléchargement en un clic. Pas besoin de choisir manuellement une architecture.
### Installer depuis les sources (dernières fonctionnalités, recommandé pour le développement)
### Télécharger le binaire précompilé
Vous pouvez aussi télécharger le binaire pour votre plateforme depuis la page [GitHub Releases](https://github.com/sipeed/picoclaw/releases).
### Compiler depuis les sources (pour le développement)
```bash
git clone https://github.com/sipeed/picoclaw.git

10
README.ja.md
View file

@ -162,11 +162,15 @@ PicoClaw はほぼすべての Linux デバイスにデプロイできます！
## 📦 インストール
### コンパイル済みバイナリでインストール
### picoclaw.io からダウンロード（推奨）
[リリースページ](https://github.com/sipeed/picoclaw/releases) からお使いのプラットフォーム用のバイナリをダウンロードしてください。
**[picoclaw.io](https://picoclaw.io)** にアクセス — 公式サイトがプラットフォームを自動検出し、ワンクリックでダウンロードできます。アーキテクチャを手動で選ぶ必要はありません。
### ソースからインストール（最新機能、開発向け推奨）
### プリコンパイル済みバイナリをダウンロード
または、[GitHub Releases](https://github.com/sipeed/picoclaw/releases) ページからプラットフォームに合ったバイナリをダウンロードしてください。
### ソースからビルド（開発用）
```bash
git clone https://github.com/sipeed/picoclaw.git

10
README.md
View file

@ -162,11 +162,15 @@ PicoClaw can be deployed on almost any Linux device!
## 📦 Install
### Install with precompiled binary
### Download from picoclaw.io (Recommended)
Download the binary for your platform from the [Releases](https://github.com/sipeed/picoclaw/releases) page.
Visit **[picoclaw.io](https://picoclaw.io)** — the official website auto-detects your platform and provides one-click download. No need to manually pick an architecture.
### Install from source (latest features, recommended for development)
### Download precompiled binary
Alternatively, download the binary for your platform from the [GitHub Releases](https://github.com/sipeed/picoclaw/releases) page.
### Build from source (for development)
```bash
git clone https://github.com/sipeed/picoclaw.git

10
README.pt-br.md
View file

@ -162,11 +162,15 @@ O PicoClaw pode ser implantado em praticamente qualquer dispositivo Linux!
## 📦 Instalação
### Instalar com binário pré-compilado
### Baixar de picoclaw.io (Recomendado)
Baixe o binário para sua plataforma na página de [Releases](https://github.com/sipeed/picoclaw/releases).
Visite **[picoclaw.io](https://picoclaw.io)** — o site oficial detecta automaticamente sua plataforma e oferece download com um clique. Sem necessidade de escolher manualmente a arquitetura.
### Instalar a partir do código-fonte (funcionalidades mais recentes, recomendado para desenvolvimento)
### Baixar binário pré-compilado
Alternativamente, baixe o binário para sua plataforma na página de [GitHub Releases](https://github.com/sipeed/picoclaw/releases).
### Compilar a partir do código-fonte (para desenvolvimento)
```bash
git clone https://github.com/sipeed/picoclaw.git

10
README.vi.md
View file

@ -162,11 +162,15 @@ PicoClaw có thể triển khai trên hầu hết mọi thiết bị Linux!
## 📦 Cài đặt
### Cài đặt bằng binary biên dịch sẵn
### Tải từ picoclaw.io (Khuyến nghị)
Tải file binary cho nền tảng của bạn từ [trang Releases](https://github.com/sipeed/picoclaw/releases).
Truy cập **[picoclaw.io](https://picoclaw.io)** — trang web chính thức tự động phát hiện nền tảng của bạn và cung cấp tải xuống một cú nhấp. Không cần chọn kiến trúc thủ công.
### Cài đặt từ mã nguồn (có tính năng mới nhất, khuyên dùng cho phát triển)
### Tải binary đã biên dịch sẵn
Hoặc tải binary cho nền tảng của bạn từ trang [GitHub Releases](https://github.com/sipeed/picoclaw/releases).
### Biên dịch từ mã nguồn (cho phát triển)
```bash
git clone https://github.com/sipeed/picoclaw.git

10
README.zh.md
View file

@ -161,11 +161,15 @@ PicoClaw 几乎可以部署在任何 Linux 设备上！
## 📦 安装
### 使用预编译二进制文件安装
### 从 picoclaw.io 下载（推荐）
从 [Release 页面](https://github.com/sipeed/picoclaw/releases) 下载适用于您平台的二进制文件。
访问 **[picoclaw.io](https://picoclaw.io)** — 官网自动检测你的平台，提供一键下载，无需手动选择架构。
### 从源码安装（获取最新特性，开发推荐）
### 下载预编译二进制文件
也可以从 [GitHub Releases](https://github.com/sipeed/picoclaw/releases) 页面手动下载对应平台的二进制文件。
### 从源码构建（开发用）
```bash
git clone https://github.com/sipeed/picoclaw.git

35
docs/channels/dingtalk/README.fr.md Normal file
View file

@ -0,0 +1,35 @@
> Retour au [README](../../../README.fr.md)
# DingTalk
DingTalk est la plateforme de communication d'entreprise d'Alibaba, très populaire dans les milieux professionnels chinois. Elle utilise un SDK de streaming pour maintenir des connexions persistantes.
## Configuration
```json
{
"channels": {
"dingtalk": {
"enabled": true,
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"allow_from": []
}
}
}
```
| Champ | Type | Requis | Description |
| ------------- | ------ | ------ | ---------------------------------------------------------------- |
| enabled | bool | Oui | Activer ou non le canal DingTalk |
| client_id | string | Oui | Client ID de l'application DingTalk |
| client_secret | string | Oui | Client Secret de l'application DingTalk |
| allow_from | array | Non | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs |
## Procédure de configuration
1. Rendez-vous sur la [plateforme ouverte DingTalk](https://open.dingtalk.com/)
2. Créez une application interne d'entreprise
3. Obtenez le Client ID et le Client Secret depuis les paramètres de l'application
4. Configurez OAuth et les abonnements aux événements (si nécessaire)
5. Renseignez le Client ID et le Client Secret dans le fichier de configuration

35
docs/channels/dingtalk/README.ja.md Normal file
View file

@ -0,0 +1,35 @@
> [README](../../../README.ja.md) に戻る
# DingTalk
DingTalkはアリババの企業向けコミュニケーションプラットフォームで、中国のビジネス環境で広く利用されています。ストリーミング SDK を使用して持続的な接続を維持します。
## 設定
```json
{
"channels": {
"dingtalk": {
"enabled": true,
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"allow_from": []
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ------------- | ------ | ---- | -------------------------------------------- |
| enabled | bool | はい | DingTalk チャンネルを有効にするかどうか |
| client_id | string | はい | DingTalk アプリケーションの Client ID |
| client_secret | string | はい | DingTalk アプリケーションの Client Secret |
| allow_from | array | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可 |
## セットアップ手順
1. [DingTalk オープンプラットフォーム](https://open.dingtalk.com/) にアクセスする
2. 企業内部アプリケーションを作成する
3. アプリケーション設定から Client ID と Client Secret を取得する
4. OAuth とイベントサブスクリプションを設定する（必要な場合）
5. Client ID と Client Secret を設定ファイルに入力する

35
docs/channels/dingtalk/README.md Normal file
View file

@ -0,0 +1,35 @@
> Back to [README](../../../README.md)
# DingTalk
DingTalk is Alibaba's enterprise communication platform, widely used in Chinese workplaces. It uses a streaming SDK to maintain persistent connections.
## Configuration
```json
{
"channels": {
"dingtalk": {
"enabled": true,
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"allow_from": []
}
}
}
```
| Field | Type | Required | Description |
| ------------- | ------ | -------- | -------------------------------------------------------- |
| enabled | bool | Yes | Whether to enable the DingTalk channel |
| client_id | string | Yes | Client ID of the DingTalk application |
| client_secret | string | Yes | Client Secret of the DingTalk application |
| allow_from | array | No | User ID whitelist; empty means all users are allowed |
## Setup
1. Go to the [DingTalk Open Platform](https://open.dingtalk.com/)
2. Create an internal enterprise application
3. Obtain the Client ID and Client Secret from the application settings
4. Configure OAuth and event subscriptions (if needed)
5. Fill in the Client ID and Client Secret in the configuration file

35
docs/channels/dingtalk/README.pt-br.md Normal file
View file

@ -0,0 +1,35 @@
> Voltar ao [README](../../../README.pt-br.md)
# DingTalk
DingTalk é a plataforma de comunicação empresarial da Alibaba, amplamente utilizada no ambiente corporativo chinês. Ela usa um SDK de streaming para manter conexões persistentes.
## Configuração
```json
{
"channels": {
"dingtalk": {
"enabled": true,
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"allow_from": []
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ------------- | ------ | ----------- | ---------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal DingTalk deve ser habilitado |
| client_id | string | Sim | Client ID do aplicativo DingTalk |
| client_secret | string | Sim | Client Secret do aplicativo DingTalk |
| allow_from | array | Não | Lista de permissão de IDs de usuário; vazio permite todos |
## Configuração passo a passo
1. Acesse a [Plataforma Aberta DingTalk](https://open.dingtalk.com/)
2. Crie um aplicativo interno corporativo
3. Obtenha o Client ID e o Client Secret nas configurações do aplicativo
4. Configure OAuth e assinaturas de eventos (se necessário)
5. Preencha o Client ID e o Client Secret no arquivo de configuração

35
docs/channels/dingtalk/README.vi.md Normal file
View file

@ -0,0 +1,35 @@
> Quay lại [README](../../../README.vi.md)
# DingTalk
DingTalk là nền tảng giao tiếp doanh nghiệp của Alibaba, được sử dụng rộng rãi trong môi trường làm việc tại Trung Quốc. Nền tảng này sử dụng SDK streaming để duy trì kết nối liên tục.
## Cấu hình
```json
{
"channels": {
"dingtalk": {
"enabled": true,
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"allow_from": []
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ------------- | ------ | -------- | ---------------------------------------------------------------- |
| enabled | bool | Có | Có bật kênh DingTalk hay không |
| client_id | string | Có | Client ID của ứng dụng DingTalk |
| client_secret | string | Có | Client Secret của ứng dụng DingTalk |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống cho phép tất cả |
## Quy trình thiết lập
1. Truy cập [Nền tảng mở DingTalk](https://open.dingtalk.com/)
2. Tạo một ứng dụng nội bộ doanh nghiệp
3. Lấy Client ID và Client Secret từ cài đặt ứng dụng
4. Cấu hình OAuth và đăng ký sự kiện (nếu cần)
5. Điền Client ID và Client Secret vào file cấu hình

2
docs/channels/dingtalk/README.zh.md
View file

@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# 钉钉
钉钉是阿里巴巴的企业通讯平台，在中国职场中广受欢迎。它采用流式 SDK 来维持持久连接。

39
docs/channels/discord/README.fr.md Normal file
View file

@ -0,0 +1,39 @@
> Retour au [README](../../../README.fr.md)
# Discord
Discord est une application gratuite de chat vocal, vidéo et textuel conçue pour les communautés. PicoClaw se connecte aux serveurs Discord via l'API Bot Discord, avec prise en charge de la réception et de l'envoi de messages.
## Configuration
```json
{
"channels": {
"discord": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"allow_from": ["YOUR_USER_ID"],
"group_trigger": {
"mention_only": false
}
}
}
}
```
| Champ | Type | Requis | Description |
| ------------- | ------ | ------ | --------------------------------------------------------------------------- |
| enabled | bool | Oui | Activer ou non le canal Discord |
| token | string | Oui | Token du bot Discord |
| allow_from | array | Non | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
| group_trigger | object | Non | Paramètres de déclenchement de groupe (exemple : { "mention_only": false }) |
## Configuration initiale
1. Accéder au [Portail des développeurs Discord](https://discord.com/developers/applications) et créer une nouvelle application
2. Activer les Intents :
- Message Content Intent
- Server Members Intent
3. Obtenir le Token du bot
4. Renseigner le Token du bot dans le fichier de configuration
5. Inviter le bot sur le serveur et lui accorder les permissions nécessaires (ex. envoyer des messages, lire l'historique des messages)

39
docs/channels/discord/README.ja.md Normal file
View file

@ -0,0 +1,39 @@
> [README](../../../README.ja.md) に戻る
# Discord
Discord はコミュニティ向けに設計された無料の音声・ビデオ・テキストチャットアプリケーションです。PicoClaw は Discord Bot API を通じて Discord サーバーに接続し、メッセージの受信と送信をサポートします。
## 設定
```json
{
"channels": {
"discord": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"allow_from": ["YOUR_USER_ID"],
"group_trigger": {
"mention_only": false
}
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ------------- | ------ | ------ | ----------------------------------------------------------------- |
| enabled | bool | はい | Discord チャンネルを有効にするかどうか |
| token | string | はい | Discord ボットトークン |
| allow_from | array | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可 |
| group_trigger | object | いいえ | グループトリガー設定（例: { "mention_only": false }） |
## セットアップ手順
1. [Discord 開発者ポータル](https://discord.com/developers/applications) にアクセスして新しいアプリケーションを作成する
2. Intents を有効にする:
- Message Content Intent
- Server Members Intent
3. Bot トークンを取得する
4. 設定ファイルに Bot トークンを入力する
5. ボットをサーバーに招待し、必要な権限を付与する（例: メッセージの送信、メッセージ履歴の読み取りなど）

39
docs/channels/discord/README.md Normal file
View file

@ -0,0 +1,39 @@
> Back to [README](../../../README.md)
# Discord
Discord is a free voice, video, and text chat application designed for communities. PicoClaw connects to Discord servers via the Discord Bot API, supporting both receiving and sending messages.
## Configuration
```json
{
"channels": {
"discord": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"allow_from": ["YOUR_USER_ID"],
"group_trigger": {
"mention_only": false
}
}
}
}
```
| Field | Type | Required | Description |
| ------------- | ------ | -------- | --------------------------------------------------------------------------- |
| enabled | bool | Yes | Whether to enable the Discord channel |
| token | string | Yes | Discord Bot Token |
| allow_from | array | No | Allowlist of user IDs; empty means all users are allowed |
| group_trigger | object | No | Group trigger settings (example: { "mention_only": false }) |
## Setup
1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and create a new application
2. Enable Intents:
- Message Content Intent
- Server Members Intent
3. Obtain the Bot Token
4. Fill in the Bot Token in the configuration file
5. Invite the bot to your server and grant the necessary permissions (e.g. Send Messages, Read Message History)

39
docs/channels/discord/README.pt-br.md Normal file
View file

@ -0,0 +1,39 @@
> Voltar ao [README](../../../README.pt-br.md)
# Discord
Discord é um aplicativo gratuito de chat de voz, vídeo e texto projetado para comunidades. O PicoClaw se conecta a servidores Discord via Discord Bot API, com suporte para receber e enviar mensagens.
## Configuração
```json
{
"channels": {
"discord": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"allow_from": ["YOUR_USER_ID"],
"group_trigger": {
"mention_only": false
}
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ------------- | ------ | ----------- | --------------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal Discord deve ser habilitado |
| token | string | Sim | Token do Bot Discord |
| allow_from | array | Não | Lista de IDs de usuários permitidos; vazio significa todos os usuários |
| group_trigger | object | Não | Configurações de gatilho de grupo (exemplo: { "mention_only": false }) |
## Configuração inicial
1. Acesse o [Portal de Desenvolvedores do Discord](https://discord.com/developers/applications) e crie uma nova aplicação
2. Habilite os Intents:
- Message Content Intent
- Server Members Intent
3. Obtenha o Token do Bot
4. Preencha o Token do Bot no arquivo de configuração
5. Convide o bot para o servidor e conceda as permissões necessárias (ex. enviar mensagens, ler histórico de mensagens)

39
docs/channels/discord/README.vi.md Normal file
View file

@ -0,0 +1,39 @@
> Quay lại [README](../../../README.vi.md)
# Discord
Discord là ứng dụng chat thoại, video và văn bản miễn phí được thiết kế cho cộng đồng. PicoClaw kết nối với máy chủ Discord qua Discord Bot API, hỗ trợ nhận và gửi tin nhắn.
## Cấu hình
```json
{
"channels": {
"discord": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"allow_from": ["YOUR_USER_ID"],
"group_trigger": {
"mention_only": false
}
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ------------- | ------ | -------- | --------------------------------------------------------------------------- |
| enabled | bool | Có | Có bật kênh Discord hay không |
| token | string | Có | Token Bot Discord |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả |
| group_trigger | object | Không | Cài đặt kích hoạt nhóm (ví dụ: { "mention_only": false }) |
## Hướng dẫn thiết lập
1. Truy cập [Discord Developer Portal](https://discord.com/developers/applications) và tạo ứng dụng mới
2. Bật các Intents:
- Message Content Intent
- Server Members Intent
3. Lấy Bot Token
4. Điền Bot Token vào file cấu hình
5. Mời bot vào máy chủ và cấp các quyền cần thiết (ví dụ: gửi tin nhắn, đọc lịch sử tin nhắn)

2
docs/channels/discord/README.zh.md
View file

@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# Discord
Discord 是一个专为社区设计的免费语音、视频和文本聊天应用。PicoClaw 通过 Discord Bot API 连接到 Discord 服务器，支持接收和发送消息。

48
docs/channels/feishu/README.fr.md Normal file
View file

@ -0,0 +1,48 @@
> Retour au [README](../../../README.fr.md)
# Feishu
Feishu (nom international : Lark) est une plateforme de collaboration d'entreprise de ByteDance. Elle prend en charge les marchés chinois et mondiaux via des connexions WebSocket pilotées par événements.
## Configuration
```json
{
"channels": {
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"allow_from": []
}
}
}
```
| Champ | Type | Requis | Description |
| --------------------- | ------ | ------ | --------------------------------------------------------------------------- |
| enabled | bool | Oui | Activer ou non le canal Feishu |
| app_id | string | Oui | App ID de l'application Feishu (commence par `cli_`) |
| app_secret | string | Oui | App Secret de l'application Feishu |
| encrypt_key | string | Non | Clé de chiffrement pour les callbacks d'événements |
| verification_token | string | Non | Token utilisé pour la vérification des événements Webhook |
| allow_from | array | Non | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
| random_reaction_emoji | array | Non | Liste d'emojis de réaction aléatoires ; vide utilise le "Pin" par défaut |
## Configuration initiale
1. Accéder à la [plateforme ouverte Feishu](https://open.feishu.cn/) et créer une application
2. Activer la capacité **Bot** dans les paramètres de l'application
3. Créer une version et publier l'application (la configuration prend effet après la publication)
4. Obtenir l'**App ID** (commence par `cli_`) et l'**App Secret**
5. Renseigner l'App ID et l'App Secret dans le fichier de configuration PicoClaw
6. Exécuter `picoclaw gateway` pour démarrer le service
7. Rechercher le nom du bot dans Feishu et commencer une conversation
> PicoClaw se connecte à Feishu en mode WebSocket/SDK — aucune adresse de callback publique ni URL Webhook n'est requise.
>
> `encrypt_key` et `verification_token` sont optionnels ; l'activation du chiffrement des événements est recommandée pour les environnements de production.
>
> Pour les références d'emojis personnalisés, voir : [Liste des emojis Feishu](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)

48
docs/channels/feishu/README.ja.md Normal file
View file

@ -0,0 +1,48 @@
> [README](../../../README.ja.md) に戻る
# 飛書（Feishu）
飛書（国際名：Lark）は ByteDance が提供するエンタープライズコラボレーションプラットフォームです。イベント駆動型の WebSocket 接続を通じて、中国および世界市場の両方をサポートします。
## 設定
```json
{
"channels": {
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"allow_from": []
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| --------------------- | ------ | ------ | ----------------------------------------------------------------- |
| enabled | bool | はい | 飛書チャンネルを有効にするかどうか |
| app_id | string | はい | 飛書アプリケーションの App ID（`cli_` で始まる） |
| app_secret | string | はい | 飛書アプリケーションの App Secret |
| encrypt_key | string | いいえ | イベントコールバックの暗号化キー |
| verification_token | string | いいえ | Webhook イベント検証に使用するトークン |
| allow_from | array | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可 |
| random_reaction_emoji | array | いいえ | ランダムに追加する絵文字のリスト。空の場合はデフォルトの "Pin" を使用 |
## セットアップ手順
1. [飛書オープンプラットフォーム](https://open.feishu.cn/) にアクセスしてアプリケーションを作成する
2. アプリケーション設定で**ボット**機能を有効にする
3. バージョンを作成してアプリケーションを公開する（公開後に設定が有効になる）
4. **App ID**（`cli_` で始まる）と **App Secret** を取得する
5. PicoClaw 設定ファイルに App ID と App Secret を入力する
6. `picoclaw gateway` を実行してサービスを起動する
7. 飛書でボット名を検索して会話を始める
> PicoClaw は WebSocket/SDK モードで飛書に接続するため、公開コールバックアドレスや Webhook URL の設定は不要です。
>
> `encrypt_key` と `verification_token` はオプションですが、本番環境ではイベント暗号化を有効にすることを推奨します。
>
> カスタム絵文字の参考：[飛書絵文字リスト](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)

48
docs/channels/feishu/README.md Normal file
View file

@ -0,0 +1,48 @@
> Back to [README](../../../README.md)
# Feishu
Feishu (international name: Lark) is an enterprise collaboration platform by ByteDance. It supports both Chinese and global markets through event-driven WebSocket connections.
## Configuration
```json
{
"channels": {
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"allow_from": []
}
}
}
```
| Field | Type | Required | Description |
| --------------------- | ------ | -------- | ------------------------------------------------------------------ |
| enabled | bool | Yes | Whether to enable the Feishu channel |
| app_id | string | Yes | App ID of the Feishu application (starts with `cli_`) |
| app_secret | string | Yes | App Secret of the Feishu application |
| encrypt_key | string | No | Encryption key for event callbacks |
| verification_token | string | No | Token used for Webhook event verification |
| allow_from | array | No | Allowlist of user IDs; empty means all users are allowed |
| random_reaction_emoji | array | No | List of random reaction emojis; empty uses the default "Pin" |
## Setup
1. Go to the [Feishu Open Platform](https://open.feishu.cn/) and create an application
2. Enable the **Bot** capability in the application settings
3. Create a version and publish the application (configuration takes effect only after publishing)
4. Obtain the **App ID** (starts with `cli_`) and **App Secret**
5. Fill in the App ID and App Secret in the PicoClaw configuration file
6. Run `picoclaw gateway` to start the service
7. Search for the bot name in Feishu and start a conversation
> PicoClaw connects to Feishu using WebSocket/SDK mode — no public callback address or Webhook URL is required.
>
> `encrypt_key` and `verification_token` are optional; enabling event encryption is recommended for production environments.
>
> For custom emoji references, see: [Feishu Emoji List](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)

48
docs/channels/feishu/README.pt-br.md Normal file
View file

@ -0,0 +1,48 @@
> Voltar ao [README](../../../README.pt-br.md)
# Feishu
Feishu (nome internacional: Lark) é uma plataforma de colaboração empresarial da ByteDance. Suporta os mercados chinês e global por meio de conexões WebSocket orientadas a eventos.
## Configuração
```json
{
"channels": {
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"allow_from": []
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| --------------------- | ------ | ----------- | -------------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal Feishu deve ser habilitado |
| app_id | string | Sim | App ID da aplicação Feishu (começa com `cli_`) |
| app_secret | string | Sim | App Secret da aplicação Feishu |
| encrypt_key | string | Não | Chave de criptografia para callbacks de eventos |
| verification_token | string | Não | Token usado para verificação de eventos Webhook |
| allow_from | array | Não | Lista de IDs de usuários permitidos; vazio significa todos os usuários |
| random_reaction_emoji | array | Não | Lista de emojis de reação aleatórios; vazio usa o "Pin" padrão |
## Configuração inicial
1. Acesse a [Plataforma Aberta Feishu](https://open.feishu.cn/) e crie uma aplicação
2. Habilite a capacidade de **Bot** nas configurações da aplicação
3. Crie uma versão e publique a aplicação (a configuração entra em vigor após a publicação)
4. Obtenha o **App ID** (começa com `cli_`) e o **App Secret**
5. Preencha o App ID e o App Secret no arquivo de configuração do PicoClaw
6. Execute `picoclaw gateway` para iniciar o serviço
7. Pesquise o nome do bot no Feishu e inicie uma conversa
> O PicoClaw se conecta ao Feishu usando o modo WebSocket/SDK — nenhum endereço de callback público ou URL de Webhook é necessário.
>
> `encrypt_key` e `verification_token` são opcionais; recomenda-se habilitar a criptografia de eventos em ambientes de produção.
>
> Para referências de emojis personalizados, consulte: [Lista de Emojis do Feishu](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)

48
docs/channels/feishu/README.vi.md Normal file
View file

@ -0,0 +1,48 @@
> Quay lại [README](../../../README.vi.md)
# Feishu
Feishu (tên quốc tế: Lark) là nền tảng cộng tác doanh nghiệp của ByteDance. Hỗ trợ cả thị trường Trung Quốc và toàn cầu thông qua kết nối WebSocket theo hướng sự kiện.
## Cấu hình
```json
{
"channels": {
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"allow_from": []
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| --------------------- | ------ | -------- | ------------------------------------------------------------------------ |
| enabled | bool | Có | Có bật kênh Feishu hay không |
| app_id | string | Có | App ID của ứng dụng Feishu (bắt đầu bằng `cli_`) |
| app_secret | string | Có | App Secret của ứng dụng Feishu |
| encrypt_key | string | Không | Khóa mã hóa cho callback sự kiện |
| verification_token | string | Không | Token dùng để xác minh sự kiện Webhook |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả |
| random_reaction_emoji | array | Không | Danh sách emoji phản ứng ngẫu nhiên; để trống dùng "Pin" mặc định |
## Hướng dẫn thiết lập
1. Truy cập [Nền tảng Mở Feishu](https://open.feishu.cn/) và tạo ứng dụng
2. Bật khả năng **Bot** trong cài đặt ứng dụng
3. Tạo phiên bản và xuất bản ứng dụng (cấu hình có hiệu lực sau khi xuất bản)
4. Lấy **App ID** (bắt đầu bằng `cli_`) và **App Secret**
5. Điền App ID và App Secret vào file cấu hình PicoClaw
6. Chạy `picoclaw gateway` để khởi động dịch vụ
7. Tìm kiếm tên bot trong Feishu và bắt đầu trò chuyện
> PicoClaw kết nối với Feishu bằng chế độ WebSocket/SDK — không cần cấu hình địa chỉ callback công khai hay Webhook URL.
>
> `encrypt_key` và `verification_token` là tùy chọn; nên bật mã hóa sự kiện trong môi trường sản xuất.
>
> Tham khảo emoji tùy chỉnh: [Danh sách Emoji Feishu](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)

21
docs/channels/feishu/README.zh.md
View file

@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# 飞书
飞书（国际版名称：Lark）是字节跳动旗下的企业协作平台。它通过事件驱动的 Webhook 同时支持中国和全球市场。
@ -33,9 +35,16 @@
## 设置流程
1. 前往 [飞书开放平台](https://open.feishu.cn/)（国际版用户请前往 [Lark 开放平台](https://open.larksuite.com/)）创建应用程序
2. 获取 App ID 和 App Secret
3. 配置事件订阅和Webhook URL
4. 设置加密(可选,生产环境建议启用)
5. 将 App ID、App Secret、Encrypt Key 和 Verification Token(如果启用加密) 填入配置文件中
6. 自定义你希望 PicoClaw react 你消息时的表情（可选, Reference URL: [Feishu Emoji List](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce))
1. 前往 [飞书开放平台](https://open.feishu.cn/)（国际版用户请前往 [Lark 开放平台](https://open.larksuite.com/)）创建应用
2. 在应用设置中启用**机器人**能力
3. 创建版本并发布应用（应用发布后配置才会生效）
4. 获取 **App ID**（以 `cli_` 开头）和 **App Secret**
5. 将 App ID 和 App Secret 填入 PicoClaw 配置文件
6. 运行 `picoclaw gateway` 启动服务
7. 在飞书中搜索机器人名称，开始对话
> PicoClaw 使用 WebSocket/SDK 模式连接飞书，无需配置公网回调地址或 Webhook URL。
>
> `encrypt_key` 和 `verification_token` 为可选项，生产环境建议启用事件加密。
>
> 自定义表情参考：[飞书表情列表](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)

40
docs/channels/line/README.fr.md Normal file
View file

@ -0,0 +1,40 @@
> Retour au [README](../../../README.fr.md)
# Line
PicoClaw prend en charge LINE via l'API LINE Messaging avec des callbacks webhook.
## Configuration
```json
{
"channels": {
"line": {
"enabled": true,
"channel_secret": "YOUR_CHANNEL_SECRET",
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
"webhook_path": "/webhook/line",
"allow_from": []
}
}
}
```
| Champ | Type | Requis | Description |
| -------------------- | ------ | ------ | ------------------------------------------------------------------------ |
| enabled | bool | Oui | Activer ou non le canal LINE |
| channel_secret | string | Oui | Channel Secret de l'API LINE Messaging |
| channel_access_token | string | Oui | Channel Access Token de l'API LINE Messaging |
| webhook_path | string | Non | Chemin du webhook (par défaut : /webhook/line) |
| allow_from | array | Non | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs |
## Procédure de configuration
1. Rendez-vous sur la [LINE Developers Console](https://developers.line.biz/console/) et créez un fournisseur de services ainsi qu'un canal Messaging API
2. Obtenez le Channel Secret et le Channel Access Token
3. Configurez le webhook :
- LINE exige que les webhooks utilisent HTTPS. Vous devez donc déployer un serveur compatible HTTPS ou utiliser un outil de proxy inverse comme ngrok pour exposer votre serveur local sur Internet
- PicoClaw utilise un serveur HTTP Gateway partagé pour recevoir les callbacks webhook de tous les canaux, écoutant par défaut sur 127.0.0.1:18790
- Définissez l'URL du webhook sur `https://your-domain.com/webhook/line`, puis configurez un proxy inverse de votre domaine externe vers le Gateway local (port par défaut 18790)
- Activez le webhook et vérifiez l'URL
4. Renseignez le Channel Secret et le Channel Access Token dans le fichier de configuration

40
docs/channels/line/README.ja.md Normal file
View file

@ -0,0 +1,40 @@
> [README](../../../README.ja.md) に戻る
# Line
PicoClaw は LINE Messaging API と Webhook コールバックを通じて LINE をサポートします。
## 設定
```json
{
"channels": {
"line": {
"enabled": true,
"channel_secret": "YOUR_CHANNEL_SECRET",
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
"webhook_path": "/webhook/line",
"allow_from": []
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| -------------------- | ------ | ------ | ------------------------------------------------------------------ |
| enabled | bool | はい | LINE チャンネルを有効にするかどうか |
| channel_secret | string | はい | LINE Messaging API の Channel Secret |
| channel_access_token | string | はい | LINE Messaging API の Channel Access Token |
| webhook_path | string | いいえ | Webhook のパス（デフォルト: /webhook/line） |
| allow_from | array | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可 |
## セットアップ手順
1. [LINE Developers Console](https://developers.line.biz/console/) にアクセスし、サービスプロバイダーと Messaging API チャンネルを作成する
2. Channel Secret と Channel Access Token を取得する
3. Webhook を設定する:
- LINE は Webhook に HTTPS が必要なため、HTTPS 対応サーバーをデプロイするか、ngrok などのリバースプロキシツールを使用してローカルサーバーをインターネットに公開する必要があります
- PicoClaw は共有の Gateway HTTP サーバーを使用してすべてのチャンネルの Webhook コールバックを受信します。デフォルトのリッスンアドレスは 127.0.0.1:18790 です
- Webhook URL を `https://your-domain.com/webhook/line` に設定し、外部ドメインをローカルの Gateway（デフォルトポート 18790）にリバースプロキシする
- Webhook を有効にして URL を検証する
4. Channel Secret と Channel Access Token を設定ファイルに入力する

40
docs/channels/line/README.md Normal file
View file

@ -0,0 +1,40 @@
> Back to [README](../../../README.md)
# Line
PicoClaw supports LINE through the LINE Messaging API with webhook callbacks.
## Configuration
```json
{
"channels": {
"line": {
"enabled": true,
"channel_secret": "YOUR_CHANNEL_SECRET",
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
"webhook_path": "/webhook/line",
"allow_from": []
}
}
}
```
| Field | Type | Required | Description |
| -------------------- | ------ | -------- | ------------------------------------------------------------------ |
| enabled | bool | Yes | Whether to enable the LINE channel |
| channel_secret | string | Yes | Channel Secret for the LINE Messaging API |
| channel_access_token | string | Yes | Channel Access Token for the LINE Messaging API |
| webhook_path | string | No | Webhook path (default: /webhook/line) |
| allow_from | array | No | User ID whitelist; empty means all users are allowed |
## Setup
1. Go to the [LINE Developers Console](https://developers.line.biz/console/) and create a provider and a Messaging API channel
2. Obtain the Channel Secret and Channel Access Token
3. Configure the webhook:
- LINE requires webhooks to use HTTPS, so you need to deploy a server with HTTPS support, or use a reverse proxy tool like ngrok to expose your local server to the internet
- PicoClaw uses a shared Gateway HTTP server to receive webhook callbacks for all channels, listening on 127.0.0.1:18790 by default
- Set the Webhook URL to `https://your-domain.com/webhook/line`, then reverse-proxy your external domain to the local Gateway (default port 18790)
- Enable the webhook and verify the URL
4. Fill in the Channel Secret and Channel Access Token in the configuration file

40
docs/channels/line/README.pt-br.md Normal file
View file

@ -0,0 +1,40 @@
> Voltar ao [README](../../../README.pt-br.md)
# Line
O PicoClaw suporta o LINE por meio da LINE Messaging API com callbacks de webhook.
## Configuração
```json
{
"channels": {
"line": {
"enabled": true,
"channel_secret": "YOUR_CHANNEL_SECRET",
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
"webhook_path": "/webhook/line",
"allow_from": []
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| -------------------- | ------ | ----------- | ---------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal LINE deve ser habilitado |
| channel_secret | string | Sim | Channel Secret da LINE Messaging API |
| channel_access_token | string | Sim | Channel Access Token da LINE Messaging API |
| webhook_path | string | Não | Caminho do webhook (padrão: /webhook/line) |
| allow_from | array | Não | Lista de permissão de IDs de usuário; vazio permite todos |
## Configuração passo a passo
1. Acesse o [LINE Developers Console](https://developers.line.biz/console/) e crie um provedor de serviços e um canal Messaging API
2. Obtenha o Channel Secret e o Channel Access Token
3. Configure o webhook:
- O LINE exige que os webhooks usem HTTPS, portanto é necessário implantar um servidor com suporte a HTTPS ou usar uma ferramenta de proxy reverso como o ngrok para expor seu servidor local à internet
- O PicoClaw usa um servidor HTTP Gateway compartilhado para receber callbacks de webhook de todos os canais, escutando em 127.0.0.1:18790 por padrão
- Defina a URL do webhook como `https://your-domain.com/webhook/line` e configure um proxy reverso do seu domínio externo para o Gateway local (porta padrão 18790)
- Ative o webhook e verifique a URL
4. Preencha o Channel Secret e o Channel Access Token no arquivo de configuração

40
docs/channels/line/README.vi.md Normal file
View file

@ -0,0 +1,40 @@
> Quay lại [README](../../../README.vi.md)
# Line
PicoClaw hỗ trợ LINE thông qua LINE Messaging API kết hợp với webhook callback.
## Cấu hình
```json
{
"channels": {
"line": {
"enabled": true,
"channel_secret": "YOUR_CHANNEL_SECRET",
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
"webhook_path": "/webhook/line",
"allow_from": []
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| -------------------- | ------ | -------- | ---------------------------------------------------------------------- |
| enabled | bool | Có | Có bật kênh LINE hay không |
| channel_secret | string | Có | Channel Secret của LINE Messaging API |
| channel_access_token | string | Có | Channel Access Token của LINE Messaging API |
| webhook_path | string | Không | Đường dẫn webhook (mặc định: /webhook/line) |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống cho phép tất cả |
## Quy trình thiết lập
1. Truy cập [LINE Developers Console](https://developers.line.biz/console/) và tạo một nhà cung cấp dịch vụ cùng một kênh Messaging API
2. Lấy Channel Secret và Channel Access Token
3. Cấu hình webhook:
- LINE yêu cầu webhook phải sử dụng HTTPS, vì vậy bạn cần triển khai máy chủ hỗ trợ HTTPS hoặc dùng công cụ reverse proxy như ngrok để expose máy chủ cục bộ ra internet
- PicoClaw sử dụng máy chủ HTTP Gateway dùng chung để nhận webhook callback cho tất cả các kênh, mặc định lắng nghe tại 127.0.0.1:18790
- Đặt Webhook URL thành `https://your-domain.com/webhook/line`, sau đó reverse proxy tên miền bên ngoài về Gateway cục bộ (cổng mặc định 18790)
- Bật webhook và xác minh URL
4. Điền Channel Secret và Channel Access Token vào file cấu hình

2
docs/channels/line/README.zh.md
View file

@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# Line
PicoClaw 通过 LINE Messaging API 配合 Webhook 回调功能实现对 LINE 的支持。

35
docs/channels/maixcam/README.fr.md Normal file
View file

@ -0,0 +1,35 @@
> Retour au [README](../../../README.fr.md)
# MaixCam
MaixCam est un canal dédié à la connexion aux caméras AI Sipeed MaixCAM et MaixCAM2. Il utilise des sockets TCP pour une communication bidirectionnelle et prend en charge les scénarios de déploiement d'IA en périphérie.
## Configuration
```json
{
"channels": {
"maixcam": {
"enabled": true,
"host": "0.0.0.0",
"port": 18790,
"allow_from": []
}
}
}
```
| Champ | Type | Requis | Description |
| ---------- | ------ | ------ | --------------------------------------------------------------------------- |
| enabled | bool | Oui | Activer ou non le canal MaixCam |
| host | string | Oui | Adresse d'écoute du serveur TCP |
| port | int | Oui | Port d'écoute du serveur TCP |
| allow_from | array | Non | Liste blanche d'identifiants d'appareils ; vide signifie tous les appareils |
## Cas d'utilisation
Le canal MaixCam permet à PicoClaw de fonctionner comme backend IA pour les appareils en périphérie :
- **Surveillance intelligente** : MaixCAM envoie des images ; PicoClaw les analyse via des modèles de vision
- **Contrôle IoT** : Les appareils envoient des données de capteurs ; PicoClaw coordonne les réponses
- **IA hors ligne** : Déployer PicoClaw sur un réseau local pour une inférence à faible latence

35
docs/channels/maixcam/README.ja.md Normal file
View file

@ -0,0 +1,35 @@
> [README](../../../README.ja.md) に戻る
# MaixCam
MaixCam は、Sipeed MaixCAM および MaixCAM2 AI カメラデバイスへの接続専用チャンネルです。TCP ソケットを使用した双方向通信を実装し、エッジ AI デプロイメントシナリオをサポートします。
## 設定
```json
{
"channels": {
"maixcam": {
"enabled": true,
"host": "0.0.0.0",
"port": 18790,
"allow_from": []
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------- | ------ | ------ | ------------------------------------------------------------- |
| enabled | bool | はい | MaixCam チャンネルを有効にするかどうか |
| host | string | はい | TCP サーバーのリッスンアドレス |
| port | int | はい | TCP サーバーのリッスンポート |
| allow_from | array | いいえ | 許可するデバイスIDのリスト。空の場合はすべてのデバイスを許可 |
## ユースケース
MaixCam チャンネルにより、PicoClaw はエッジデバイスの AI バックエンドとして機能できます：
- **スマート監視**：MaixCAM が画像フレームを送信し、PicoClaw がビジョンモデルで分析する
- **IoT 制御**：デバイスがセンサーデータを送信し、PicoClaw がレスポンスを調整する
- **オフライン AI**：ローカルネットワークに PicoClaw をデプロイして低遅延推論を実現する

35
docs/channels/maixcam/README.md Normal file
View file

@ -0,0 +1,35 @@
> Back to [README](../../../README.md)
# MaixCam
MaixCam is a dedicated channel for connecting to Sipeed MaixCAM and MaixCAM2 AI camera devices. It uses TCP sockets for bidirectional communication and supports edge AI deployment scenarios.
## Configuration
```json
{
"channels": {
"maixcam": {
"enabled": true,
"host": "0.0.0.0",
"port": 18790,
"allow_from": []
}
}
}
```
| Field | Type | Required | Description |
| ---------- | ------ | -------- | ---------------------------------------------------------------- |
| enabled | bool | Yes | Whether to enable the MaixCam channel |
| host | string | Yes | TCP server listening address |
| port | int | Yes | TCP server listening port |
| allow_from | array | No | Allowlist of device IDs; empty means all devices are allowed |
## Use Cases
The MaixCam channel enables PicoClaw to act as an AI backend for edge devices:
- **Smart Surveillance**: MaixCAM sends image frames; PicoClaw analyzes them using vision models
- **IoT Control**: Devices send sensor data; PicoClaw coordinates responses
- **Offline AI**: Deploy PicoClaw on a local network for low-latency inference

35
docs/channels/maixcam/README.pt-br.md Normal file
View file

@ -0,0 +1,35 @@
> Voltar ao [README](../../../README.pt-br.md)
# MaixCam
MaixCam é um canal dedicado para conectar dispositivos de câmera AI Sipeed MaixCAM e MaixCAM2. Utiliza sockets TCP para comunicação bidirecional e suporta cenários de implantação de IA na borda.
## Configuração
```json
{
"channels": {
"maixcam": {
"enabled": true,
"host": "0.0.0.0",
"port": 18790,
"allow_from": []
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ---------- | ------ | ----------- | -------------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal MaixCam deve ser habilitado |
| host | string | Sim | Endereço de escuta do servidor TCP |
| port | int | Sim | Porta de escuta do servidor TCP |
| allow_from | array | Não | Lista de IDs de dispositivos permitidos; vazio significa todos os dispositivos |
## Casos de uso
O canal MaixCam permite que o PicoClaw atue como backend de IA para dispositivos de borda:
- **Vigilância inteligente**: MaixCAM envia quadros de imagem; PicoClaw os analisa usando modelos de visão
- **Controle IoT**: Dispositivos enviam dados de sensores; PicoClaw coordena as respostas
- **IA offline**: Implante o PicoClaw em uma rede local para inferência de baixa latência

35
docs/channels/maixcam/README.vi.md Normal file
View file

@ -0,0 +1,35 @@
> Quay lại [README](../../../README.vi.md)
# MaixCam
MaixCam là kênh chuyên dụng để kết nối với các thiết bị camera AI Sipeed MaixCAM và MaixCAM2. Sử dụng TCP socket để giao tiếp hai chiều và hỗ trợ các kịch bản triển khai AI tại biên.
## Cấu hình
```json
{
"channels": {
"maixcam": {
"enabled": true,
"host": "0.0.0.0",
"port": 18790,
"allow_from": []
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
| enabled | bool | Có | Có bật kênh MaixCam hay không |
| host | string | Có | Địa chỉ lắng nghe của máy chủ TCP |
| port | int | Có | Cổng lắng nghe của máy chủ TCP |
| allow_from | array | Không | Danh sách trắng ID thiết bị; để trống nghĩa là cho phép tất cả thiết bị |
## Trường hợp sử dụng
Kênh MaixCam cho phép PicoClaw hoạt động như backend AI cho các thiết bị biên:
- **Giám sát thông minh**: MaixCAM gửi khung hình ảnh; PicoClaw phân tích bằng mô hình thị giác
- **Điều khiển IoT**: Thiết bị gửi dữ liệu cảm biến; PicoClaw điều phối phản hồi
- **AI ngoại tuyến**: Triển khai PicoClaw trên mạng nội bộ để suy luận độ trễ thấp

2
docs/channels/maixcam/README.zh.md
View file

@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# MaixCam
MaixCam 是专用于连接矽速科技 MaixCAM 与 MaixCAM2 AI 摄像设备的通道。它采用 TCP 套接字实现双向通信，支持边缘 AI 部署场景。

33
docs/channels/onebot/README.fr.md Normal file
View file

@ -0,0 +1,33 @@
> Retour au [README](../../../README.fr.md)
# OneBot
OneBot est un standard de protocole ouvert pour les bots QQ, fournissant une interface unifiée pour diverses implémentations de bots QQ (par exemple go-cqhttp, Mirai). Il utilise WebSocket pour la communication.
## Configuration
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://localhost:8080",
"access_token": "",
"allow_from": []
}
}
}
```
| Champ | Type | Requis | Description |
| ------------ | ------ | ------ | -------------------------------------------------------------------- |
| enabled | bool | Oui | Activer ou non le canal OneBot |
| ws_url | string | Oui | URL WebSocket du serveur OneBot |
| access_token | string | Non | Jeton d'accès pour la connexion au serveur OneBot |
| allow_from | array | Non | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs |
## Procédure de configuration
1. Déployez une implémentation compatible OneBot (par exemple napcat)
2. Configurez l'implémentation OneBot pour activer le service WebSocket et définir un jeton d'accès (si nécessaire)
3. Renseignez l'URL WebSocket et le jeton d'accès dans le fichier de configuration

33
docs/channels/onebot/README.ja.md Normal file
View file

@ -0,0 +1,33 @@
> [README](../../../README.ja.md) に戻る
# OneBot
OneBot は QQ ボット向けのオープンプロトコル標準で、複数の QQ ボット実装（例: go-cqhttp、Mirai）に統一されたインターフェースを提供します。通信には WebSocket を使用します。
## 設定
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://localhost:8080",
"access_token": "",
"allow_from": []
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ------------ | ------ | ------ | ---------------------------------------------------------------- |
| enabled | bool | はい | OneBot チャンネルを有効にするかどうか |
| ws_url | string | はい | OneBot サーバーの WebSocket URL |
| access_token | string | いいえ | OneBot サーバーへの接続に使用するアクセストークン |
| allow_from | array | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可 |
## セットアップ手順
1. OneBot 互換の実装（例: napcat）をデプロイする
2. OneBot 実装で WebSocket サービスを有効にし、アクセストークンを設定する（必要な場合）
3. WebSocket URL とアクセストークンを設定ファイルに入力する

33
docs/channels/onebot/README.md Normal file
View file

@ -0,0 +1,33 @@
> Back to [README](../../../README.md)
# OneBot
OneBot is an open protocol standard for QQ bots, providing a unified interface for various QQ bot implementations (e.g. go-cqhttp, Mirai). It uses WebSocket for communication.
## Configuration
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://localhost:8080",
"access_token": "",
"allow_from": []
}
}
}
```
| Field | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------------------------------- |
| enabled | bool | Yes | Whether to enable the OneBot channel |
| ws_url | string | Yes | WebSocket URL of the OneBot server |
| access_token | string | No | Access token for connecting to the OneBot server |
| allow_from | array | No | User ID whitelist; empty means all users are allowed |
## Setup
1. Deploy a OneBot-compatible implementation (e.g. napcat)
2. Configure the OneBot implementation to enable the WebSocket service and set an access token (if needed)
3. Fill in the WebSocket URL and access token in the configuration file

33
docs/channels/onebot/README.pt-br.md Normal file
View file

@ -0,0 +1,33 @@
> Voltar ao [README](../../../README.pt-br.md)
# OneBot
OneBot é um padrão de protocolo aberto para bots QQ, fornecendo uma interface unificada para diversas implementações de bots QQ (ex.: go-cqhttp, Mirai). Utiliza WebSocket para comunicação.
## Configuração
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://localhost:8080",
"access_token": "",
"allow_from": []
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ------------ | ------ | ----------- | -------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal OneBot deve ser habilitado |
| ws_url | string | Sim | URL WebSocket do servidor OneBot |
| access_token | string | Não | Token de acesso para conexão ao servidor OneBot |
| allow_from | array | Não | Lista de permissão de IDs de usuário; vazio permite todos |
## Configuração passo a passo
1. Implante uma implementação compatível com OneBot (ex.: napcat)
2. Configure a implementação OneBot para habilitar o serviço WebSocket e definir um token de acesso (se necessário)
3. Preencha a URL WebSocket e o token de acesso no arquivo de configuração

33
docs/channels/onebot/README.vi.md Normal file
View file

@ -0,0 +1,33 @@
> Quay lại [README](../../../README.vi.md)
# OneBot
OneBot là tiêu chuẩn giao thức mở dành cho bot QQ, cung cấp giao diện thống nhất cho nhiều triển khai bot QQ khác nhau (ví dụ: go-cqhttp, Mirai). Nó sử dụng WebSocket để giao tiếp.
## Cấu hình
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://localhost:8080",
"access_token": "",
"allow_from": []
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ------------ | ------ | -------- | -------------------------------------------------------------------- |
| enabled | bool | Có | Có bật kênh OneBot hay không |
| ws_url | string | Có | URL WebSocket của máy chủ OneBot |
| access_token | string | Không | Token truy cập để kết nối với máy chủ OneBot |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống cho phép tất cả |
## Quy trình thiết lập
1. Triển khai một bản triển khai tương thích OneBot (ví dụ: napcat)
2. Cấu hình bản triển khai OneBot để bật dịch vụ WebSocket và đặt token truy cập (nếu cần)
3. Điền URL WebSocket và token truy cập vào file cấu hình

2
docs/channels/onebot/README.zh.md
View file

@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# OneBot
OneBot 是一个面向 QQ 机器人的开放协议标准，为多种 QQ 机器人实现（例如 go-cqhttp、Mirai）提供了统一的接口。它使用 WebSocket 进行通信。

54
docs/channels/qq/README.fr.md Normal file
View file

@ -0,0 +1,54 @@
> Retour au [README](../../../README.fr.md)
# QQ
PicoClaw prend en charge QQ via l'API Bot officielle de la plateforme ouverte QQ.
## Configuration
```json
{
"channels": {
"qq": {
"enabled": true,
"app_id": "YOUR_APP_ID",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
| Champ | Type | Requis | Description |
| ---------- | ------ | ------ | --------------------------------------------------------------------------- |
| enabled | bool | Oui | Activer ou non le canal QQ |
| app_id | string | Oui | App ID de l'application bot QQ |
| app_secret | string | Oui | App Secret de l'application bot QQ |
| allow_from | array | Non | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
## Configuration initiale
### Configuration rapide (recommandée)
La plateforme ouverte QQ propose une entrée de création en un clic :
1. Ouvrir [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) et se connecter en scannant le QR code
2. Le système crée automatiquement un bot — copier l'**App ID** et l'**App Secret**
3. Renseigner les identifiants dans le fichier de configuration PicoClaw
4. Exécuter `picoclaw gateway` pour démarrer le service
5. Ouvrir QQ et commencer à discuter avec le bot
> L'App Secret n'est affiché qu'une seule fois — sauvegardez-le immédiatement. Le consulter à nouveau forcera une réinitialisation.
>
> Les bots créés via l'entrée rapide sont réservés à l'usage personnel du créateur et ne prennent pas en charge les discussions de groupe. Pour la prise en charge des groupes, configurez le mode sandbox sur la [plateforme ouverte QQ](https://q.qq.com/).
### Configuration manuelle
1. Se connecter à la [plateforme ouverte QQ](https://q.qq.com/) avec son compte QQ et s'inscrire en tant que développeur
2. Créer un bot QQ et personnaliser son avatar et son nom
3. Obtenir l'**App ID** et l'**App Secret** dans les paramètres du bot
4. Renseigner les identifiants dans le fichier de configuration PicoClaw
5. Exécuter `picoclaw gateway` pour démarrer le service
6. Rechercher votre bot dans QQ et commencer à discuter
> Pendant le développement, il est recommandé d'activer le mode sandbox et d'y ajouter les utilisateurs et groupes de test pour le débogage.

54
docs/channels/qq/README.ja.md Normal file
View file

@ -0,0 +1,54 @@
> [README](../../../README.ja.md) に戻る
# QQ
PicoClaw は QQ オープンプラットフォームの公式 Bot API を通じて QQ をサポートします。
## 設定
```json
{
"channels": {
"qq": {
"enabled": true,
"app_id": "YOUR_APP_ID",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------- | ------ | ------ | ------------------------------------------------------------- |
| enabled | bool | はい | QQ チャンネルを有効にするかどうか |
| app_id | string | はい | QQ ボットアプリケーションの App ID |
| app_secret | string | はい | QQ ボットアプリケーションの App Secret |
| allow_from | array | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可 |
## セットアップ手順
### クイックセットアップ（推奨）
QQ オープンプラットフォームにはワンクリック作成エントリーが用意されています：
1. [QQ ボットクイック作成](https://q.qq.com/qqbot/openclaw/index.html) を開き、QR コードをスキャンしてログインする
2. システムが自動的にボットを作成するので、**App ID** と **App Secret** をコピーする
3. PicoClaw 設定ファイルに認証情報を入力する
4. `picoclaw gateway` を実行してサービスを起動する
5. QQ を開いてボットとの会話を始める
> App Secret は一度しか表示されません。すぐに保存してください。再度表示しようとすると強制的にリセットされます。
>
> クイックエントリーで作成したボットは作成者本人のみが使用でき、グループチャットには対応していません。グループチャット機能が必要な場合は、[QQ オープンプラットフォーム](https://q.qq.com/) でサンドボックスモードを設定してください。
### 手動セットアップ
1. QQ アカウントで [QQ オープンプラットフォーム](https://q.qq.com/) にログインし、開発者アカウントを登録する
2. QQ ボットを作成し、アバターと名前をカスタマイズする
3. ボット設定から **App ID** と **App Secret** を取得する
4. PicoClaw 設定ファイルに認証情報を入力する
5. `picoclaw gateway` を実行してサービスを起動する
6. QQ でボットを検索して会話を始める
> 開発段階ではサンドボックスモードを有効にし、テストユーザーとグループをサンドボックスに追加してデバッグすることを推奨します。

54
docs/channels/qq/README.md Normal file
View file

@ -0,0 +1,54 @@
> Back to [README](../../../README.md)
# QQ
PicoClaw provides QQ support via the official Bot API from the QQ Open Platform.
## Configuration
```json
{
"channels": {
"qq": {
"enabled": true,
"app_id": "YOUR_APP_ID",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
| Field | Type | Required | Description |
| ---------- | ------ | -------- | -------------------------------------------------------- |
| enabled | bool | Yes | Whether to enable the QQ channel |
| app_id | string | Yes | App ID of the QQ bot application |
| app_secret | string | Yes | App Secret of the QQ bot application |
| allow_from | array | No | Allowlist of user IDs; empty means all users are allowed |
## Setup
### Quick Setup (Recommended)
The QQ Open Platform provides a one-click creation entry:
1. Open [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) and log in by scanning the QR code
2. The system automatically creates a bot — copy the **App ID** and **App Secret**
3. Fill in the credentials in the PicoClaw configuration file
4. Run `picoclaw gateway` to start the service
5. Open QQ and start chatting with the bot
> The App Secret is only shown once — save it immediately. Viewing it again will force a reset.
>
> Bots created via the quick entry are for the creator's personal use only and do not support group chats. For group chat support, configure sandbox mode on the [QQ Open Platform](https://q.qq.com/).
### Manual Setup
1. Log in to the [QQ Open Platform](https://q.qq.com/) with your QQ account and register as a developer
2. Create a QQ bot and customize its avatar and name
3. Obtain the **App ID** and **App Secret** from the bot settings
4. Fill in the credentials in the PicoClaw configuration file
5. Run `picoclaw gateway` to start the service
6. Search for your bot in QQ and start chatting
> During development, it is recommended to enable sandbox mode and add test users and groups to the sandbox for debugging.

54
docs/channels/qq/README.pt-br.md Normal file
View file

@ -0,0 +1,54 @@
> Voltar ao [README](../../../README.pt-br.md)
# QQ
O PicoClaw oferece suporte ao QQ via API Bot oficial da Plataforma Aberta QQ.
## Configuração
```json
{
"channels": {
"qq": {
"enabled": true,
"app_id": "YOUR_APP_ID",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ---------- | ------ | ----------- | -------------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal QQ deve ser habilitado |
| app_id | string | Sim | App ID da aplicação bot QQ |
| app_secret | string | Sim | App Secret da aplicação bot QQ |
| allow_from | array | Não | Lista de IDs de usuários permitidos; vazio significa todos os usuários |
## Configuração inicial
### Configuração rápida (recomendada)
A Plataforma Aberta QQ oferece uma entrada de criação com um clique:
1. Abra o [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) e faça login escaneando o QR code
2. O sistema cria o bot automaticamente — copie o **App ID** e o **App Secret**
3. Preencha as credenciais no arquivo de configuração do PicoClaw
4. Execute `picoclaw gateway` para iniciar o serviço
5. Abra o QQ e comece a conversar com o bot
> O App Secret é exibido apenas uma vez — salve-o imediatamente. Visualizá-lo novamente forçará uma redefinição.
>
> Bots criados pela entrada rápida são apenas para uso pessoal do criador e não suportam chats em grupo. Para suporte a grupos, configure o modo sandbox na [Plataforma Aberta QQ](https://q.qq.com/).
### Configuração manual
1. Faça login na [Plataforma Aberta QQ](https://q.qq.com/) com sua conta QQ e registre-se como desenvolvedor
2. Crie um bot QQ e personalize seu avatar e nome
3. Obtenha o **App ID** e o **App Secret** nas configurações do bot
4. Preencha as credenciais no arquivo de configuração do PicoClaw
5. Execute `picoclaw gateway` para iniciar o serviço
6. Pesquise seu bot no QQ e comece a conversar
> Durante o desenvolvimento, recomenda-se habilitar o modo sandbox e adicionar usuários e grupos de teste ao sandbox para depuração.

54
docs/channels/qq/README.vi.md Normal file
View file

@ -0,0 +1,54 @@
> Quay lại [README](../../../README.vi.md)
# QQ
PicoClaw hỗ trợ QQ thông qua API Bot chính thức của Nền tảng Mở QQ.
## Cấu hình
```json
{
"channels": {
"qq": {
"enabled": true,
"app_id": "YOUR_APP_ID",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
| enabled | bool | Có | Có bật kênh QQ hay không |
| app_id | string | Có | App ID của ứng dụng bot QQ |
| app_secret | string | Có | App Secret của ứng dụng bot QQ |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả |
## Hướng dẫn thiết lập
### Thiết lập nhanh (Khuyến nghị)
Nền tảng Mở QQ cung cấp lối vào tạo bot một chạm:
1. Mở [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) và đăng nhập bằng cách quét mã QR
2. Hệ thống tự động tạo bot — sao chép **App ID** và **App Secret**
3. Điền thông tin xác thực vào file cấu hình PicoClaw
4. Chạy `picoclaw gateway` để khởi động dịch vụ
5. Mở QQ và bắt đầu trò chuyện với bot
> App Secret chỉ hiển thị một lần — hãy lưu lại ngay. Xem lại sẽ buộc phải đặt lại.
>
> Bot được tạo qua lối vào nhanh chỉ dành cho người tạo sử dụng cá nhân và chưa hỗ trợ chat nhóm. Để hỗ trợ chat nhóm, hãy cấu hình chế độ sandbox trên [Nền tảng Mở QQ](https://q.qq.com/).
### Tạo thủ công
1. Đăng nhập vào [Nền tảng Mở QQ](https://q.qq.com/) bằng tài khoản QQ và đăng ký tài khoản nhà phát triển
2. Tạo bot QQ, tùy chỉnh ảnh đại diện và tên
3. Lấy **App ID** và **App Secret** trong cài đặt bot
4. Điền thông tin xác thực vào file cấu hình PicoClaw
5. Chạy `picoclaw gateway` để khởi động dịch vụ
6. Tìm kiếm bot của bạn trong QQ và bắt đầu trò chuyện
> Trong giai đoạn phát triển, nên bật chế độ sandbox và thêm người dùng, nhóm thử nghiệm vào sandbox để gỡ lỗi.

30
docs/channels/qq/README.zh.md
View file

@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# QQ
PicoClaw 通过 QQ 开放平台的官方机器人 API 提供对 QQ 的支持。
@ -28,7 +30,27 @@ PicoClaw 通过 QQ 开放平台的官方机器人 API 提供对 QQ 的支持。
## 设置流程
1. 前往 [QQ 开放平台](https://q.qq.com/) 创建一个机器人
2. 通过仪表盘获取 App ID 和 App Secret
3. 开启机器人沙箱模式, 将用户和群添加到沙箱中
4. 将 App ID 和 App Secret 填入配置文件中
### 快捷方式（推荐）
QQ 开放平台提供了一键创建入口：
1. 打开 [QQ 机器人快速创建](https://q.qq.com/qqbot/openclaw/index.html)，扫码登录
2. 系统自动创建机器人，复制 **App ID** 和 **App Secret**
3. 将凭证填入 PicoClaw 配置文件
4. 运行 `picoclaw gateway` 启动服务
5. 打开 QQ，与机器人开始对话
> App Secret 仅显示一次，请立即保存。再次查看将强制重置。
>
> 通过快捷入口创建的机器人仅供创建人使用，暂不支持群聊。如需群聊功能，请在 [QQ 开放平台](https://q.qq.com/) 配置沙箱模式。
### 手动创建
1. 使用 QQ 账号登录 [QQ 开放平台](https://q.qq.com/)，注册开发者账号
2. 创建 QQ 机器人，自定义头像和名称
3. 在机器人设置中获取 **App ID** 和 **App Secret**
4. 将凭证填入 PicoClaw 配置文件
5. 运行 `picoclaw gateway` 启动服务
6. 在 QQ 中搜索你的机器人，开始对话
> 开发阶段建议开启沙箱模式，将测试用户和群添加到沙箱中进行调试。

35
docs/channels/slack/README.fr.md Normal file
View file

@ -0,0 +1,35 @@
> Retour au [README](../../../README.fr.md)
# Slack
Slack est l'une des principales plateformes de messagerie instantanée pour les entreprises. PicoClaw utilise le Socket Mode de Slack pour une communication bidirectionnelle en temps réel, sans nécessiter la configuration d'un endpoint webhook public.
## Configuration
```json
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-...",
"app_token": "xapp-...",
"allow_from": []
}
}
}
```
| Champ | Type | Requis | Description |
| ---------- | ------ | ------ | ---------------------------------------------------------------------------- |
| enabled | bool | Oui | Activer ou non le canal Slack |
| bot_token | string | Oui | Bot User OAuth Token du bot Slack (commence par xoxb-) |
| app_token | string | Oui | App Level Token Socket Mode de l'application Slack (commence par xapp-) |
| allow_from | array | Non | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs |
## Procédure de configuration
1. Rendez-vous sur [Slack API](https://api.slack.com/) et créez une nouvelle application Slack
2. Activez le Socket Mode et obtenez l'App Level Token
3. Ajoutez des Bot Token Scopes (par exemple `chat:write`, `im:history`, etc.)
4. Installez l'application dans votre espace de travail et obtenez le Bot User OAuth Token
5. Renseignez le Bot Token et l'App Token dans le fichier de configuration

35
docs/channels/slack/README.ja.md Normal file
View file

@ -0,0 +1,35 @@
> [README](../../../README.ja.md) に戻る
# Slack
Slack は世界をリードする企業向けインスタントメッセージングプラットフォームです。PicoClaw は Slack の Socket Mode を使用してリアルタイムの双方向通信を実現しており、公開 Webhook エンドポイントの設定は不要です。
## 設定
```json
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-...",
"app_token": "xapp-...",
"allow_from": []
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------- | ------ | ------ | ------------------------------------------------------------------------ |
| enabled | bool | はい | Slack チャンネルを有効にするかどうか |
| bot_token | string | はい | Slack ボットの Bot User OAuth Token（xoxb- で始まる） |
| app_token | string | はい | Slack アプリの Socket Mode App Level Token（xapp- で始まる） |
| allow_from | array | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可 |
## セットアップ手順
1. [Slack API](https://api.slack.com/) にアクセスして新しい Slack アプリを作成する
2. Socket Mode を有効にして App Level Token を取得する
3. Bot Token Scopes を追加する（例: `chat:write`、`im:history` など）
4. アプリをワークスペースにインストールして Bot User OAuth Token を取得する
5. Bot Token と App Token を設定ファイルに入力する

35
docs/channels/slack/README.md Normal file
View file

@ -0,0 +1,35 @@
> Back to [README](../../../README.md)
# Slack
Slack is a leading enterprise instant messaging platform. PicoClaw uses Slack's Socket Mode for real-time bidirectional communication, with no need to configure a public webhook endpoint.
## Configuration
```json
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-...",
"app_token": "xapp-...",
"allow_from": []
}
}
}
```
| Field | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
| enabled | bool | Yes | Whether to enable the Slack channel |
| bot_token | string | Yes | Bot User OAuth Token for the Slack bot (starts with xoxb-) |
| app_token | string | Yes | Socket Mode App Level Token for the Slack app (starts with xapp-) |
| allow_from | array | No | User ID whitelist; empty means all users are allowed |
## Setup
1. Go to [Slack API](https://api.slack.com/) and create a new Slack app
2. Enable Socket Mode and obtain the App Level Token
3. Add Bot Token Scopes (e.g. `chat:write`, `im:history`, etc.)
4. Install the app to your workspace and obtain the Bot User OAuth Token
5. Fill in the Bot Token and App Token in the configuration file

35
docs/channels/slack/README.pt-br.md Normal file
View file

@ -0,0 +1,35 @@
> Voltar ao [README](../../../README.pt-br.md)
# Slack
O Slack é uma das principais plataformas de mensagens instantâneas para empresas. O PicoClaw usa o Socket Mode do Slack para comunicação bidirecional em tempo real, sem necessidade de configurar um endpoint de webhook público.
## Configuração
```json
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-...",
"app_token": "xapp-...",
"allow_from": []
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ---------- | ------ | ----------- | ---------------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal Slack deve ser habilitado |
| bot_token | string | Sim | Bot User OAuth Token do bot Slack (começa com xoxb-) |
| app_token | string | Sim | App Level Token do Socket Mode do aplicativo Slack (começa com xapp-) |
| allow_from | array | Não | Lista de permissão de IDs de usuário; vazio permite todos |
## Configuração passo a passo
1. Acesse o [Slack API](https://api.slack.com/) e crie um novo aplicativo Slack
2. Ative o Socket Mode e obtenha o App Level Token
3. Adicione Bot Token Scopes (ex.: `chat:write`, `im:history`, etc.)
4. Instale o aplicativo no seu workspace e obtenha o Bot User OAuth Token
5. Preencha o Bot Token e o App Token no arquivo de configuração

35
docs/channels/slack/README.vi.md Normal file
View file

@ -0,0 +1,35 @@
> Quay lại [README](../../../README.vi.md)
# Slack
Slack là nền tảng nhắn tin tức thì hàng đầu dành cho doanh nghiệp. PicoClaw sử dụng Socket Mode của Slack để giao tiếp hai chiều theo thời gian thực, không cần cấu hình endpoint webhook công khai.
## Cấu hình
```json
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-...",
"app_token": "xapp-...",
"allow_from": []
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ---------- | ------ | -------- | ---------------------------------------------------------------------------- |
| enabled | bool | Có | Có bật kênh Slack hay không |
| bot_token | string | Có | Bot User OAuth Token của Slack bot (bắt đầu bằng xoxb-) |
| app_token | string | Có | App Level Token Socket Mode của ứng dụng Slack (bắt đầu bằng xapp-) |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống cho phép tất cả |
## Quy trình thiết lập
1. Truy cập [Slack API](https://api.slack.com/) và tạo một ứng dụng Slack mới
2. Bật Socket Mode và lấy App Level Token
3. Thêm Bot Token Scopes (ví dụ: `chat:write`, `im:history`, v.v.)
4. Cài đặt ứng dụng vào workspace và lấy Bot User OAuth Token
5. Điền Bot Token và App Token vào file cấu hình

2
docs/channels/slack/README.zh.md
View file

@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# Slack
Slack 是全球领先的企业级即时通讯平台。PicoClaw 采用 Slack 的 Socket Mode 实现实时双向通信，无需配置公开的 Webhook 端点。

35
docs/channels/telegram/README.fr.md Normal file
View file

@ -0,0 +1,35 @@
> Retour au [README](../../../README.fr.md)
# Telegram
Le canal Telegram utilise le long polling via l'API Bot Telegram pour une communication basée sur les bots. Il prend en charge les messages texte, les pièces jointes multimédias (photos, messages vocaux, audio, documents), la transcription vocale via Groq Whisper et la gestion des commandes intégrée.
## Configuration
```json
{
"channels": {
"telegram": {
"enabled": true,
"token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
"allow_from": ["123456789"],
"proxy": ""
}
}
}
```
| Champ | Type | Requis | Description |
| ---------- | ------ | ------ | ------------------------------------------------------------------------ |
| enabled | bool | Oui | Activer ou non le canal Telegram |
| token | string | Oui | Token de l'API Bot Telegram |
| allow_from | array | Non | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
| proxy | string | Non | URL du proxy pour se connecter à l'API Telegram (ex. http://127.0.0.1:7890) |
## Configuration initiale
1. Rechercher `@BotFather` dans Telegram
2. Envoyer la commande `/newbot` et suivre les instructions pour créer un nouveau bot
3. Obtenir le Token de l'API HTTP
4. Renseigner le Token dans le fichier de configuration
5. (Optionnel) Configurer `allow_from` pour restreindre les identifiants utilisateur autorisés à interagir (les IDs peuvent être obtenus via `@userinfobot`)

35
docs/channels/telegram/README.ja.md Normal file
View file

@ -0,0 +1,35 @@
> [README](../../../README.ja.md) に戻る
# Telegram
Telegram チャンネルは、Telegram Bot API を使用したロングポーリングによるボットベースの通信を実装しています。テキストメッセージ、メディア添付ファイル（写真、音声、オーディオ、ドキュメント）、Groq Whisper による音声文字起こし、および組み込みコマンドハンドラーをサポートしています。
## 設定
```json
{
"channels": {
"telegram": {
"enabled": true,
"token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
"allow_from": ["123456789"],
"proxy": ""
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------- | ------ | ---- | ----------------------------------------------------------------- |
| enabled | bool | はい | Telegram チャンネルを有効にするかどうか |
| token | string | はい | Telegram Bot API トークン |
| allow_from | array | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可 |
| proxy | string | いいえ | Telegram API への接続に使用するプロキシ URL (例: http://127.0.0.1:7890) |
## セットアップ手順
1. Telegram で `@BotFather` を検索する
2. `/newbot` コマンドを送信し、指示に従って新しいボットを作成する
3. HTTP API トークンを取得する
4. 設定ファイルにトークンを入力する
5. (任意) `allow_from` を設定して、対話を許可するユーザー ID を制限する（ID は `@userinfobot` で取得可能）

35
docs/channels/telegram/README.md Normal file
View file

@ -0,0 +1,35 @@
> Back to [README](../../../README.md)
# Telegram
The Telegram channel uses long polling via the Telegram Bot API for bot-based communication. It supports text messages, media attachments (photos, voice, audio, documents), voice transcription via Groq Whisper, and built-in command handling.
## Configuration
```json
{
"channels": {
"telegram": {
"enabled": true,
"token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
"allow_from": ["123456789"],
"proxy": ""
}
}
}
```
| Field | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------------------------------------ |
| enabled | bool | Yes | Whether to enable the Telegram channel |
| token | string | Yes | Telegram Bot API Token |
| allow_from | array | No | Allowlist of user IDs; empty means all users are allowed |
| proxy | string | No | Proxy URL for connecting to the Telegram API (e.g. http://127.0.0.1:7890) |
## Setup
1. Search for `@BotFather` in Telegram
2. Send the `/newbot` command and follow the prompts to create a new bot
3. Obtain the HTTP API Token
4. Fill in the Token in the configuration file
5. (Optional) Configure `allow_from` to restrict which user IDs can interact (you can get IDs via `@userinfobot`)

35
docs/channels/telegram/README.pt-br.md Normal file
View file

@ -0,0 +1,35 @@
> Voltar ao [README](../../../README.pt-br.md)
# Telegram
O canal Telegram utiliza long polling via a API de Bot do Telegram para comunicação baseada em bots. Suporta mensagens de texto, anexos de mídia (fotos, voz, áudio, documentos), transcrição de voz via Groq Whisper e tratamento de comandos integrado.
## Configuração
```json
{
"channels": {
"telegram": {
"enabled": true,
"token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
"allow_from": ["123456789"],
"proxy": ""
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ---------- | ------ | ----------- | -------------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal Telegram deve ser habilitado |
| token | string | Sim | Token da API de Bot do Telegram |
| allow_from | array | Não | Lista de IDs de usuários permitidos; vazio significa todos os usuários |
| proxy | string | Não | URL do proxy para conexão com a API do Telegram (ex. http://127.0.0.1:7890) |
## Configuração inicial
1. Pesquise por `@BotFather` no Telegram
2. Envie o comando `/newbot` e siga as instruções para criar um novo bot
3. Obtenha o Token da API HTTP
4. Preencha o Token no arquivo de configuração
5. (Opcional) Configure `allow_from` para restringir quais IDs de usuário podem interagir (os IDs podem ser obtidos via `@userinfobot`)

35
docs/channels/telegram/README.vi.md Normal file
View file

@ -0,0 +1,35 @@
> Quay lại [README](../../../README.vi.md)
# Telegram
Kênh Telegram sử dụng long polling qua Telegram Bot API để giao tiếp dựa trên bot. Hỗ trợ tin nhắn văn bản, tệp đính kèm đa phương tiện (ảnh, giọng nói, âm thanh, tài liệu), chuyển giọng nói thành văn bản qua Groq Whisper và xử lý lệnh tích hợp sẵn.
## Cấu hình
```json
{
"channels": {
"telegram": {
"enabled": true,
"token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
"allow_from": ["123456789"],
"proxy": ""
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
| enabled | bool | Có | Có bật kênh Telegram hay không |
| token | string | Có | Token API Bot Telegram |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả |
| proxy | string | Không | URL proxy để kết nối với Telegram API (ví dụ: http://127.0.0.1:7890) |
## Hướng dẫn thiết lập
1. Tìm kiếm `@BotFather` trong Telegram
2. Gửi lệnh `/newbot` và làm theo hướng dẫn để tạo bot mới
3. Lấy Token API HTTP
4. Điền Token vào file cấu hình
5. (Tùy chọn) Cấu hình `allow_from` để giới hạn ID người dùng được phép tương tác (có thể lấy ID qua `@userinfobot`)

2
docs/channels/telegram/README.zh.md
View file

@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# Telegram
Telegram Channel 通过 Telegram 机器人 API 使用长轮询实现基于机器人的通信。它支持文本消息、媒体附件（照片、语音、音频、文档）、通过 Groq Whisper 进行语音转录以及内置命令处理器。

118
docs/channels/wecom/wecom_aibot/README.fr.md Normal file
View file

@ -0,0 +1,118 @@
> Retour au [README](../../../../README.fr.md)
# WeCom AI Bot
Le WeCom AI Bot est une méthode d'intégration de conversation IA officiellement fournie par WeCom. Il prend en charge les conversations privées et de groupe, intègre un protocole de réponse en streaming et supporte l'envoi proactif de la réponse finale via `response_url` en cas de dépassement de délai.
## Comparaison avec les autres canaux WeCom
| Fonctionnalité | WeCom Bot | WeCom App | **WeCom AI Bot** |
|----------------|-----------|-----------|-----------------|
| Chat privé | ✅ | ✅ | ✅ |
| Chat de groupe | ✅ | ❌ | ✅ |
| Sortie en streaming | ❌ | ❌ | ✅ |
| Push proactif en cas de timeout | ❌ | ✅ | ✅ |
| Complexité de configuration | Faible | Élevée | Moyenne |
## Configuration
```json
{
"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": "你好！有什么可以帮助你的吗？",
"max_steps": 10
}
}
}
```
| Champ | Type | Requis | Description |
| ---------------- | ------ | ------ | -------------------------------------------------- |
| token | string | Oui | Jeton de vérification du callback, configuré sur la page de gestion de l'AI Bot |
| encoding_aes_key | string | Oui | Clé AES de 43 caractères, générée aléatoirement sur la page de gestion de l'AI Bot |
| webhook_path | string | Non | Chemin du webhook (par défaut : /webhook/wecom-aibot) |
| allow_from | array | Non | Liste blanche d'ID utilisateurs ; un tableau vide autorise tous les utilisateurs |
| welcome_message | string | Non | Message de bienvenue envoyé à l'ouverture du chat ; laisser vide pour désactiver |
| reply_timeout | int | Non | Délai de réponse en secondes (par défaut : 5) |
| max_steps | int | Non | Nombre maximum d'étapes d'exécution de l'agent (par défaut : 10) |
## Procédure de configuration
1. Connectez-vous à la [console d'administration WeCom](https://work.weixin.qq.com/wework_admin)
2. Accédez à « Gestion des applications » → « AI Bot », puis créez ou sélectionnez un AI Bot
3. Sur la page de configuration de l'AI Bot, renseignez les informations de « Réception des messages » :
- **URL** : `http://<your-server-ip>:18790/webhook/wecom-aibot`
- **Token** : Généré aléatoirement ou personnalisé
- **EncodingAESKey** : Cliquez sur « Générer aléatoirement » pour obtenir une clé de 43 caractères
4. Saisissez le Token et l'EncodingAESKey dans le fichier de configuration PicoClaw, démarrez le service, puis revenez à la console d'administration pour enregistrer (WeCom enverra une requête de vérification)
> [!TIP]
> Le serveur doit être accessible par les serveurs WeCom. Si vous êtes sur un intranet ou en développement local, utilisez [ngrok](https://ngrok.com) ou frp pour le tunneling.
## Protocole de réponse en streaming
Le WeCom AI Bot utilise un protocole de « pull en streaming », différent de la réponse unique d'un webhook standard :
```
L'utilisateur envoie un message
│
▼
PicoClaw retourne immédiatement {finish: false} (l'agent commence le traitement)
│
▼
WeCom effectue un pull environ toutes les 1 seconde avec {msgtype: "stream", stream: {id: "..."}}
│
├─ Agent non terminé → retourne {finish: false} (continuer à attendre)
│
└─ Agent terminé → retourne {finish: true, content: "contenu de la réponse"}
```
**Gestion du timeout** (tâche dépassant 30 secondes) :
Si le traitement de l'agent dépasse environ 30 secondes (la fenêtre de polling maximale de WeCom est de 6 minutes), PicoClaw va :
1. Fermer immédiatement le stream et afficher à l'utilisateur : « ⏳ 正在处理中，请稍候，结果将稍后发送。 »
2. L'agent continue de s'exécuter en arrière-plan
3. Une fois l'agent terminé, la réponse finale est envoyée proactivement à l'utilisateur via le `response_url` inclus dans le message
> `response_url` est émis par WeCom, valable 1 heure, utilisable une seule fois, sans chiffrement requis — il suffit de POSTer directement le corps du message markdown.
## Message de bienvenue
Lorsque `welcome_message` est configuré, PicoClaw répond automatiquement avec ce message lorsqu'un utilisateur ouvre la fenêtre de chat avec l'AI Bot (événement `enter_chat`). Laisser vide pour ignorer silencieusement.
```json
"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
```
## FAQ
### Échec de la vérification de l'URL de callback
- Vérifiez que le pare-feu du serveur autorise le port concerné (par défaut 18790)
- Vérifiez que `token` et `encoding_aes_key` sont correctement renseignés
- Consultez les logs PicoClaw pour voir si une requête GET de WeCom a été reçue
### Les messages ne reçoivent pas de réponse
- Vérifiez que `allow_from` ne restreint pas accidentellement l'expéditeur
- Recherchez `context canceled` ou des erreurs d'agent dans les logs
- Vérifiez que la configuration de l'agent (ex. `model_name`) est correcte
### Pas de push final reçu pour les tâches longues
- Vérifiez que le callback du message inclut `response_url` (uniquement supporté par la nouvelle version du WeCom AI Bot)
- Vérifiez que le serveur peut effectuer des requêtes sortantes (nécessite un POST vers `response_url`)
- Consultez les logs pour les mots-clés `response_url mode` et `Sending reply via response_url`
## Références
- [Documentation d'intégration WeCom AI Bot](https://developer.work.weixin.qq.com/document/path/100719)
- [Description du protocole de réponse en streaming](https://developer.work.weixin.qq.com/document/path/100719)
- [Réponse proactive via response_url](https://developer.work.weixin.qq.com/document/path/101138)

118
docs/channels/wecom/wecom_aibot/README.ja.md Normal file
View file

@ -0,0 +1,118 @@
> [README](../../../../README.ja.md) に戻る
# 企業WeChat AIボット
企業WeChat AIボット（AI Bot）は、企業WeChatが公式に提供するAI会話連携方式です。プライベートチャットとグループチャットの両方をサポートし、ストリーミングレスポンスプロトコルを内蔵しており、タイムアウト後に `response_url` を通じて最終返信をプッシュする機能もサポートしています。
## 他のWeCom チャンネルとの比較
| 機能 | WeCom Bot | WeCom App | **WeCom AI Bot** |
|------|-----------|-----------|-----------------|
| プライベートチャット | ✅ | ✅ | ✅ |
| グループチャット | ✅ | ❌ | ✅ |
| ストリーミング出力 | ❌ | ❌ | ✅ |
| タイムアウト時のプッシュ | ❌ | ✅ | ✅ |
| 設定の複雑さ | 低 | 高 | 中 |
## 設定
```json
{
"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": "你好！有什么可以帮助你的吗？",
"max_steps": 10
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------------- | ------ | ---- | -------------------------------------------------- |
| token | string | はい | コールバック検証トークン。AIボット管理ページで設定 |
| encoding_aes_key | string | はい | 43文字のAESキー。AIボット管理ページでランダム生成 |
| webhook_path | string | いいえ | Webhookパス（デフォルト：/webhook/wecom-aibot） |
| allow_from | array | いいえ | ユーザーIDの許可リスト。空配列は全ユーザーを許可 |
| welcome_message | string | いいえ | ユーザーがチャットを開いたときに送信するウェルカムメッセージ。空白の場合は送信しない |
| reply_timeout | int | いいえ | 返信タイムアウト（秒、デフォルト：5） |
| max_steps | int | いいえ | エージェントの最大実行ステップ数（デフォルト：10） |
## セットアップ手順
1. [企業WeChat管理コンソール](https://work.weixin.qq.com/wework_admin) にログイン
2. 「アプリ管理」→「AIボット」に進み、AIボットを作成または選択
3. AIボット設定ページで「メッセージ受信」情報を入力：
- **URL**：`http://<your-server-ip>:18790/webhook/wecom-aibot`
- **Token**：ランダム生成またはカスタム
- **EncodingAESKey**：「ランダム生成」をクリックして43文字のキーを取得
4. TokenとEncodingAESKeyをPicoClawの設定ファイルに入力し、サービスを起動してから管理コンソールに戻って保存（企業WeChatが検証リクエストを送信します）
> [!TIP]
> サーバーは企業WeChatのサーバーからアクセス可能である必要があります。イントラネットやローカル開発環境の場合は、[ngrok](https://ngrok.com) またはfrpを使用してトンネリングしてください。
## ストリーミングレスポンスプロトコル
WeCom AIボットは「ストリーミングプル」プロトコルを使用しており、通常のWebhookの一回限りの返信とは異なります：
```
ユーザーがメッセージを送信
│
▼
PicoClawが即座に {finish: false} を返す（エージェントが処理開始）
│
▼
企業WeChatが約1秒ごとに {msgtype: "stream", stream: {id: "..."}} でプル
│
├─ エージェント未完了 → {finish: false} を返す（待機継続）
│
└─ エージェント完了 → {finish: true, content: "返信内容"} を返す
```
**タイムアウト処理**（タスクが30秒を超える場合）：
エージェントの処理時間が約30秒を超えた場合（企業WeChatの最大ポーリングウィンドウは6分）、PicoClawは：
1. 即座にストリームを閉じ、ユーザーに「⏳ 正在处理中，请稍候，结果将稍后发送。」と表示
2. エージェントはバックグラウンドで処理を継続
3. エージェント完了後、メッセージに含まれる `response_url` を通じて最終返信をユーザーにプッシュ
> `response_url` は企業WeChatが発行し、有効期限は1時間、使用は1回限りで、暗号化不要。マークダウンメッセージ本文をそのままPOSTするだけです。
## ウェルカムメッセージ
`welcome_message` を設定すると、ユーザーがAIボットとのチャットウィンドウを開いたとき（`enter_chat` イベント）に、PicoClawが自動的にそのメッセージを返信します。空白の場合は無視されます。
```json
"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
```
## よくある質問
### コールバックURL検証の失敗
- サーバーのファイアウォールで該当ポートが開放されているか確認（デフォルト18790）
- `token` と `encoding_aes_key` が正しく入力されているか確認
- PicoClawのログに企業WeChatからのGETリクエストが届いているか確認
### メッセージに返信がない
- `allow_from` が誤って送信者を制限していないか確認
- ログに `context canceled` またはエージェントエラーが出ていないか確認
- エージェント設定（`model_name` など）が正しいか確認
### 長時間タスクで最終プッシュが届かない
- メッセージコールバックに `response_url` が含まれているか確認（新バージョンの企業WeChat AIボットのみ対応）
- サーバーが外部ネットワークへのアウトバウンドリクエストを送信できるか確認（`response_url` へのPOSTが必要）
- ログのキーワード `response_url mode` と `Sending reply via response_url` を確認
## 参考ドキュメント
- [企業WeChat AIボット連携ドキュメント](https://developer.work.weixin.qq.com/document/path/100719)
- [ストリーミングレスポンスプロトコルの説明](https://developer.work.weixin.qq.com/document/path/100719)
- [response_url によるプロアクティブ返信](https://developer.work.weixin.qq.com/document/path/101138)

118
docs/channels/wecom/wecom_aibot/README.md Normal file
View file

@ -0,0 +1,118 @@
> Back to [README](../../../../README.md)
# WeCom AI Bot
The WeCom AI Bot is an official AI conversation integration provided by WeCom. It supports both private and group chats, has a built-in streaming response protocol, and supports proactively pushing the final reply via `response_url` after a timeout.
## Comparison with Other WeCom Channels
| Feature | WeCom Bot | WeCom App | **WeCom AI Bot** |
|---------|-----------|-----------|-----------------|
| Private Chat | ✅ | ✅ | ✅ |
| Group Chat | ✅ | ❌ | ✅ |
| Streaming Output | ❌ | ❌ | ✅ |
| Proactive Push on Timeout | ❌ | ✅ | ✅ |
| Configuration Complexity | Low | High | Medium |
## Configuration
```json
{
"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": "你好！有什么可以帮助你的吗？",
"max_steps": 10
}
}
}
```
| Field | Type | Required | Description |
| ---------------- | ------ | -------- | -------------------------------------------------- |
| token | string | Yes | Callback verification token, configured on the AI Bot management page |
| encoding_aes_key | string | Yes | 43-character AES key, randomly generated on the AI Bot management page |
| webhook_path | string | No | Webhook path (default: /webhook/wecom-aibot) |
| allow_from | array | No | User ID allowlist; empty array allows all users |
| welcome_message | string | No | Welcome message sent when a user opens the chat; leave empty to disable |
| reply_timeout | int | No | Reply timeout in seconds (default: 5) |
| max_steps | int | No | Maximum agent execution steps (default: 10) |
## Setup
1. Log in to the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin)
2. Go to "App Management" → "AI Bot", then create or select an AI Bot
3. On the AI Bot configuration page, fill in the "Message Reception" details:
- **URL**: `http://<your-server-ip>:18790/webhook/wecom-aibot`
- **Token**: Randomly generated or custom
- **EncodingAESKey**: Click "Random Generate" to get a 43-character key
4. Enter the Token and EncodingAESKey into the PicoClaw config file, start the service, then return to the admin console to save (WeCom will send a verification request)
> [!TIP]
> The server must be accessible by WeCom's servers. If you are on an intranet or developing locally, use [ngrok](https://ngrok.com) or frp for tunneling.
## Streaming Response Protocol
WeCom AI Bot uses a "streaming pull" protocol, which differs from the one-shot reply of a standard webhook:
```
User sends a message
│
▼
PicoClaw immediately returns {finish: false} (Agent starts processing)
│
▼
WeCom pulls approximately every 1 second with {msgtype: "stream", stream: {id: "..."}}
│
├─ Agent not done → returns {finish: false} (keep waiting)
│
└─ Agent done → returns {finish: true, content: "reply content"}
```
**Timeout Handling** (task exceeds 30 seconds):
If the Agent takes longer than approximately 30 seconds (WeCom's maximum polling window is 6 minutes), PicoClaw will:
1. Immediately close the stream and show the user: "⏳ 正在处理中，请稍候，结果将稍后发送。"
2. The Agent continues running in the background
3. Once the Agent finishes, the final reply is proactively pushed to the user via the `response_url` included in the message
> `response_url` is issued by WeCom, valid for 1 hour, can only be used once, requires no encryption — just POST the markdown message body directly.
## Welcome Message
When `welcome_message` is configured, PicoClaw will automatically reply with it when a user opens the chat window with the AI Bot (`enter_chat` event). Leave it empty to silently ignore the event.
```json
"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
```
## FAQ
### Callback URL Verification Failed
- Confirm the server firewall has the relevant port open (default 18790)
- Confirm `token` and `encoding_aes_key` are entered correctly
- Check PicoClaw logs to see if a GET request from WeCom was received
### Messages Not Getting a Reply
- Check whether `allow_from` is accidentally restricting the sender
- Look for `context canceled` or Agent errors in the logs
- Confirm the Agent configuration (e.g., `model_name`) is correct
### No Final Push Received for Long-Running Tasks
- Confirm the message callback includes `response_url` (only supported by the newer WeCom AI Bot)
- Confirm the server can make outbound requests (needs to POST to `response_url`)
- Check logs for keywords `response_url mode` and `Sending reply via response_url`
## Reference
- [WeCom AI Bot Integration Docs](https://developer.work.weixin.qq.com/document/path/100719)
- [Streaming Response Protocol](https://developer.work.weixin.qq.com/document/path/100719)
- [Proactive Reply via response_url](https://developer.work.weixin.qq.com/document/path/101138)

118
docs/channels/wecom/wecom_aibot/README.pt-br.md Normal file
View file

@ -0,0 +1,118 @@
> Voltar ao [README](../../../../README.pt-br.md)
# WeCom AI Bot
O WeCom AI Bot é uma forma oficial de integração de conversas com IA fornecida pelo WeCom. Suporta conversas privadas e em grupo, possui um protocolo de resposta em streaming integrado e suporta o envio proativo da resposta final via `response_url` após um timeout.
## Comparação com outros canais WeCom
| Recurso | WeCom Bot | WeCom App | **WeCom AI Bot** |
|---------|-----------|-----------|-----------------|
| Chat privado | ✅ | ✅ | ✅ |
| Chat em grupo | ✅ | ❌ | ✅ |
| Saída em streaming | ❌ | ❌ | ✅ |
| Push proativo em timeout | ❌ | ✅ | ✅ |
| Complexidade de configuração | Baixa | Alta | Média |
## Configuração
```json
{
"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": "你好！有什么可以帮助你的吗？",
"max_steps": 10
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ---------------- | ------ | ----------- | -------------------------------------------------- |
| token | string | Sim | Token de verificação de callback, configurado na página de gerenciamento do AI Bot |
| encoding_aes_key | string | Sim | Chave AES de 43 caracteres, gerada aleatoriamente na página de gerenciamento do AI Bot |
| webhook_path | string | Não | Caminho do webhook (padrão: /webhook/wecom-aibot) |
| allow_from | array | Não | Lista de permissão de IDs de usuários; array vazio permite todos os usuários |
| welcome_message | string | Não | Mensagem de boas-vindas enviada quando o usuário abre o chat; deixe vazio para desativar |
| reply_timeout | int | Não | Timeout de resposta em segundos (padrão: 5) |
| max_steps | int | Não | Número máximo de etapas de execução do agente (padrão: 10) |
## Configuração passo a passo
1. Faça login no [Console de Administração do WeCom](https://work.weixin.qq.com/wework_admin)
2. Acesse "Gerenciamento de Apps" → "AI Bot", depois crie ou selecione um AI Bot
3. Na página de configuração do AI Bot, preencha as informações de "Recebimento de Mensagens":
- **URL**: `http://<your-server-ip>:18790/webhook/wecom-aibot`
- **Token**: Gerado aleatoriamente ou personalizado
- **EncodingAESKey**: Clique em "Gerar Aleatoriamente" para obter uma chave de 43 caracteres
4. Insira o Token e o EncodingAESKey no arquivo de configuração do PicoClaw, inicie o serviço e volte ao console de administração para salvar (o WeCom enviará uma requisição de verificação)
> [!TIP]
> O servidor precisa ser acessível pelos servidores do WeCom. Se estiver em uma intranet ou desenvolvendo localmente, use [ngrok](https://ngrok.com) ou frp para tunelamento.
## Protocolo de resposta em streaming
O WeCom AI Bot usa um protocolo de "pull em streaming", diferente da resposta única de um webhook padrão:
```
Usuário envia uma mensagem
│
▼
PicoClaw retorna imediatamente {finish: false} (Agente começa a processar)
│
▼
WeCom faz pull aproximadamente a cada 1 segundo com {msgtype: "stream", stream: {id: "..."}}
│
├─ Agente não concluído → retorna {finish: false} (continuar aguardando)
│
└─ Agente concluído → retorna {finish: true, content: "conteúdo da resposta"}
```
**Tratamento de timeout** (tarefa excede 30 segundos):
Se o processamento do agente demorar mais de aproximadamente 30 segundos (a janela máxima de polling do WeCom é de 6 minutos), o PicoClaw irá:
1. Fechar imediatamente o stream e exibir ao usuário: "⏳ 正在处理中，请稍候，结果将稍后发送。"
2. O agente continua executando em segundo plano
3. Após a conclusão do agente, a resposta final é enviada proativamente ao usuário via `response_url` incluído na mensagem
> `response_url` é emitido pelo WeCom, válido por 1 hora, pode ser usado apenas uma vez, sem necessidade de criptografia — basta fazer um POST com o corpo da mensagem em markdown diretamente.
## Mensagem de boas-vindas
Quando `welcome_message` está configurado, o PicoClaw responde automaticamente com essa mensagem quando um usuário abre a janela de chat com o AI Bot (evento `enter_chat`). Deixe vazio para ignorar silenciosamente.
```json
"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
```
## Perguntas frequentes
### Falha na verificação da URL de callback
- Confirme que o firewall do servidor tem a porta correspondente aberta (padrão 18790)
- Confirme que `token` e `encoding_aes_key` estão preenchidos corretamente
- Verifique os logs do PicoClaw para ver se uma requisição GET do WeCom foi recebida
### Mensagens sem resposta
- Verifique se `allow_from` está restringindo acidentalmente o remetente
- Procure por `context canceled` ou erros do agente nos logs
- Confirme que a configuração do agente (ex.: `model_name`) está correta
### Nenhum push final recebido para tarefas longas
- Confirme que o callback da mensagem inclui `response_url` (suportado apenas pelo novo WeCom AI Bot)
- Confirme que o servidor consegue fazer requisições de saída (precisa fazer POST para `response_url`)
- Verifique nos logs as palavras-chave `response_url mode` e `Sending reply via response_url`
## Referências
- [Documentação de integração do WeCom AI Bot](https://developer.work.weixin.qq.com/document/path/100719)
- [Descrição do protocolo de resposta em streaming](https://developer.work.weixin.qq.com/document/path/100719)
- [Resposta proativa via response_url](https://developer.work.weixin.qq.com/document/path/101138)

118
docs/channels/wecom/wecom_aibot/README.vi.md Normal file
View file

@ -0,0 +1,118 @@
> Quay lại [README](../../../../README.vi.md)
# WeCom AI Bot
WeCom AI Bot là phương thức tích hợp hội thoại AI chính thức do WeCom cung cấp. Hỗ trợ cả chat riêng tư và chat nhóm, tích hợp giao thức phản hồi streaming, và hỗ trợ chủ động đẩy phản hồi cuối cùng qua `response_url` sau khi hết thời gian chờ.
## So sánh với các kênh WeCom khác
| Tính năng | WeCom Bot | WeCom App | **WeCom AI Bot** |
|-----------|-----------|-----------|-----------------|
| Chat riêng tư | ✅ | ✅ | ✅ |
| Chat nhóm | ✅ | ❌ | ✅ |
| Đầu ra streaming | ❌ | ❌ | ✅ |
| Đẩy chủ động khi timeout | ❌ | ✅ | ✅ |
| Độ phức tạp cấu hình | Thấp | Cao | Trung bình |
## Cấu hình
```json
{
"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": "你好！有什么可以帮助你的吗？",
"max_steps": 10
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ---------------- | ------ | --------- | -------------------------------------------------- |
| token | string | Có | Token xác minh callback, cấu hình trên trang quản lý AI Bot |
| encoding_aes_key | string | Có | Khóa AES 43 ký tự, được tạo ngẫu nhiên trên trang quản lý AI Bot |
| webhook_path | string | Không | Đường dẫn webhook (mặc định: /webhook/wecom-aibot) |
| allow_from | array | Không | Danh sách cho phép ID người dùng; mảng rỗng cho phép tất cả người dùng |
| welcome_message | string | Không | Tin nhắn chào mừng gửi khi người dùng mở chat; để trống để tắt |
| reply_timeout | int | Không | Thời gian chờ phản hồi tính bằng giây (mặc định: 5) |
| max_steps | int | Không | Số bước thực thi tối đa của agent (mặc định: 10) |
## Hướng dẫn thiết lập
1. Đăng nhập vào [Bảng điều khiển quản trị WeCom](https://work.weixin.qq.com/wework_admin)
2. Vào "Quản lý ứng dụng" → "AI Bot", sau đó tạo hoặc chọn một AI Bot
3. Trên trang cấu hình AI Bot, điền thông tin "Nhận tin nhắn":
- **URL**: `http://<your-server-ip>:18790/webhook/wecom-aibot`
- **Token**: Tạo ngẫu nhiên hoặc tùy chỉnh
- **EncodingAESKey**: Nhấp "Tạo ngẫu nhiên" để lấy khóa 43 ký tự
4. Nhập Token và EncodingAESKey vào file cấu hình PicoClaw, khởi động dịch vụ rồi quay lại bảng điều khiển quản trị để lưu (WeCom sẽ gửi yêu cầu xác minh)
> [!TIP]
> Máy chủ cần có thể truy cập được từ các máy chủ WeCom. Nếu bạn đang ở mạng nội bộ hoặc phát triển cục bộ, hãy sử dụng [ngrok](https://ngrok.com) hoặc frp để tạo tunnel.
## Giao thức phản hồi streaming
WeCom AI Bot sử dụng giao thức "pull streaming", khác với phản hồi một lần của webhook thông thường:
```
Người dùng gửi tin nhắn
│
▼
PicoClaw trả về ngay {finish: false} (Agent bắt đầu xử lý)
│
▼
WeCom pull khoảng mỗi 1 giây với {msgtype: "stream", stream: {id: "..."}}
│
├─ Agent chưa xong → trả về {finish: false} (tiếp tục chờ)
│
└─ Agent xong → trả về {finish: true, content: "nội dung phản hồi"}
```
**Xử lý timeout** (tác vụ vượt quá 30 giây):
Nếu thời gian xử lý của agent vượt quá khoảng 30 giây (cửa sổ polling tối đa của WeCom là 6 phút), PicoClaw sẽ:
1. Đóng stream ngay lập tức và hiển thị cho người dùng: "⏳ 正在处理中，请稍候，结果将稍后发送。"
2. Agent tiếp tục chạy ở nền
3. Sau khi agent hoàn thành, phản hồi cuối cùng được chủ động đẩy đến người dùng qua `response_url` có trong tin nhắn
> `response_url` do WeCom cấp, có hiệu lực 1 giờ, chỉ dùng được một lần, không cần mã hóa — chỉ cần POST trực tiếp nội dung tin nhắn markdown.
## Tin nhắn chào mừng
Khi `welcome_message` được cấu hình, PicoClaw sẽ tự động phản hồi bằng tin nhắn đó khi người dùng mở cửa sổ chat với AI Bot (sự kiện `enter_chat`). Để trống để bỏ qua im lặng.
```json
"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
```
## Câu hỏi thường gặp
### Xác minh URL callback thất bại
- Xác nhận tường lửa máy chủ đã mở cổng tương ứng (mặc định 18790)
- Xác nhận `token` và `encoding_aes_key` được điền đúng
- Kiểm tra log PicoClaw xem có nhận được yêu cầu GET từ WeCom không
### Tin nhắn không nhận được phản hồi
- Kiểm tra xem `allow_from` có vô tình hạn chế người gửi không
- Tìm `context canceled` hoặc lỗi agent trong log
- Xác nhận cấu hình agent (ví dụ: `model_name`) là đúng
### Không nhận được push cuối cùng cho tác vụ dài
- Xác nhận callback tin nhắn có chứa `response_url` (chỉ hỗ trợ bởi WeCom AI Bot phiên bản mới)
- Xác nhận máy chủ có thể thực hiện yêu cầu ra ngoài (cần POST đến `response_url`)
- Kiểm tra log với từ khóa `response_url mode` và `Sending reply via response_url`
## Tài liệu tham khảo
- [Tài liệu tích hợp WeCom AI Bot](https://developer.work.weixin.qq.com/document/path/100719)
- [Mô tả giao thức phản hồi streaming](https://developer.work.weixin.qq.com/document/path/100719)
- [Phản hồi chủ động qua response_url](https://developer.work.weixin.qq.com/document/path/101138)

2
docs/channels/wecom/wecom_aibot/README.zh.md
View file

@ -1,3 +1,5 @@
> 返回 [README](../../../../README.zh.md)
# 企业微信智能机器人 (AI Bot)
企业微信智能机器人（AI Bot）是企业微信官方提供的 AI 对话接入方式，支持私聊与群聊，内置流式响应协议。PicoClaw 当前同时支持两种接入模式：

47
docs/channels/wecom/wecom_app/README.fr.md Normal file
View file

@ -0,0 +1,47 @@
> Retour au [README](../../../../README.fr.md)
# Application interne WeCom
Une application interne WeCom est une application créée par une entreprise au sein de WeCom, principalement destinée à un usage interne. Grâce aux applications internes WeCom, les entreprises peuvent assurer une communication et une collaboration efficaces avec leurs employés, améliorant ainsi la productivité.
## Configuration
```json
{
"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": [],
"reply_timeout": 5
}
}
}
```
| Champ | Type | Requis | Description |
| ---------------- | ------ | ------ | ---------------------------------------- |
| corp_id | string | Oui | ID de l'entreprise |
| corp_secret | string | Oui | Secret de l'application |
| agent_id | int | Oui | ID de l'agent de l'application |
| token | string | Oui | Jeton de vérification du callback |
| encoding_aes_key | string | Oui | Clé AES de 43 caractères |
| webhook_path | string | Non | Chemin du webhook (par défaut : /webhook/wecom-app) |
| allow_from | array | Non | Liste blanche d'ID utilisateurs |
| reply_timeout | int | Non | Délai de réponse en secondes |
## Procédure de configuration
1. Connectez-vous à la [console d'administration WeCom](https://work.weixin.qq.com/)
2. Accédez à « Gestion des applications » -> « Créer une application »
3. Obtenez l'ID d'entreprise (CorpID) et le Secret de l'application
4. Configurez « Réception des messages » dans les paramètres de l'application pour obtenir le Token et l'EncodingAESKey
5. Définissez l'URL de callback sur `http://<your-server-ip>:<port>/webhook/wecom-app`
6. Saisissez le CorpID, le Secret, l'AgentID et les autres informations dans le fichier de configuration
Remarque : PicoClaw utilise désormais un serveur HTTP Gateway partagé pour recevoir les callbacks webhook de tous les canaux. L'adresse d'écoute par défaut est 127.0.0.1:18790. Pour recevoir des callbacks depuis l'internet public, configurez un reverse proxy de votre domaine externe vers le Gateway (port par défaut 18790).

47
docs/channels/wecom/wecom_app/README.ja.md Normal file
View file

@ -0,0 +1,47 @@
> [README](../../../../README.ja.md) に戻る
# 企業WeChat 自社開発アプリ
企業WeChat 自社開発アプリとは、企業が企業WeChat内で作成するアプリケーションで、主に社内利用を目的としています。企業WeChat 自社開発アプリを通じて、企業は従業員との効率的なコミュニケーションと協業を実現し、業務効率を向上させることができます。
## 設定
```json
{
"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": [],
"reply_timeout": 5
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------------- | ------ | ---- | ---------------------------------------- |
| corp_id | string | はい | 企業ID |
| corp_secret | string | はい | アプリケーションシークレット |
| agent_id | int | はい | アプリケーションエージェントID |
| token | string | はい | コールバック検証トークン |
| encoding_aes_key | string | はい | 43文字のAESキー |
| webhook_path | string | いいえ | Webhookパス（デフォルト：/webhook/wecom-app） |
| allow_from | array | いいえ | ユーザーIDの許可リスト |
| reply_timeout | int | いいえ | 返信タイムアウト（秒） |
## セットアップ手順
1. [企業WeChat管理コンソール](https://work.weixin.qq.com/) にログイン
2. 「アプリ管理」→「アプリを作成」に進む
3. 企業ID（CorpID）とアプリのSecretを取得
4. アプリ設定で「メッセージ受信」を設定し、TokenとEncodingAESKeyを取得
5. コールバックURLを `http://<your-server-ip>:<port>/webhook/wecom-app` に設定
6. CorpID、Secret、AgentIDなどの情報を設定ファイルに入力
注意：PicoClawは現在、すべてのチャンネルのwebhookコールバックを受信するために共有のGateway HTTPサーバーを使用しています。デフォルトのリスニングアドレスは127.0.0.1:18790です。公共インターネットからコールバックを受信するには、外部ドメインをGateway（デフォルトポート18790）にリバースプロキシしてください。

47
docs/channels/wecom/wecom_app/README.md Normal file
View file

@ -0,0 +1,47 @@
> Back to [README](../../../../README.md)
# WeCom Internal App
A WeCom Internal App is an application created by an enterprise within WeCom, primarily intended for internal use. Through WeCom Internal Apps, enterprises can achieve efficient communication and collaboration with employees, improving productivity.
## Configuration
```json
{
"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": [],
"reply_timeout": 5
}
}
}
```
| Field | Type | Required | Description |
| ---------------- | ------ | -------- | ---------------------------------------- |
| corp_id | string | Yes | Enterprise ID |
| corp_secret | string | Yes | Application secret |
| agent_id | int | Yes | Application agent ID |
| token | string | Yes | Callback verification token |
| encoding_aes_key | string | Yes | 43-character AES key |
| webhook_path | string | No | Webhook path (default: /webhook/wecom-app) |
| allow_from | array | No | User ID allowlist |
| reply_timeout | int | No | Reply timeout in seconds |
## Setup
1. Log in to the [WeCom Admin Console](https://work.weixin.qq.com/)
2. Go to "App Management" -> "Create App"
3. Obtain the Enterprise ID (CorpID) and App Secret
4. Configure "Receive Messages" in the app settings to get the Token and EncodingAESKey
5. Set the callback URL to `http://<your-server-ip>:<port>/webhook/wecom-app`
6. Enter the CorpID, Secret, AgentID, and other details into the config file
Note: PicoClaw now uses a shared Gateway HTTP server to receive webhook callbacks for all channels. The default listening address is 127.0.0.1:18790. To receive callbacks from the public internet, reverse-proxy your external domain to the Gateway (default port 18790).

47
docs/channels/wecom/wecom_app/README.pt-br.md Normal file
View file

@ -0,0 +1,47 @@
> Voltar ao [README](../../../../README.pt-br.md)
# App Interno WeCom
Um App Interno WeCom é um aplicativo criado por uma empresa dentro do WeCom, destinado principalmente ao uso interno. Por meio dos Apps Internos WeCom, as empresas podem alcançar comunicação e colaboração eficientes com os funcionários, melhorando a produtividade.
## Configuração
```json
{
"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": [],
"reply_timeout": 5
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ---------------- | ------ | ----------- | ---------------------------------------- |
| corp_id | string | Sim | ID da empresa |
| corp_secret | string | Sim | Segredo da aplicação |
| agent_id | int | Sim | ID do agente da aplicação |
| token | string | Sim | Token de verificação de callback |
| encoding_aes_key | string | Sim | Chave AES de 43 caracteres |
| webhook_path | string | Não | Caminho do webhook (padrão: /webhook/wecom-app) |
| allow_from | array | Não | Lista de permissão de IDs de usuários |
| reply_timeout | int | Não | Timeout de resposta em segundos |
## Configuração passo a passo
1. Faça login no [Console de Administração do WeCom](https://work.weixin.qq.com/)
2. Acesse "Gerenciamento de Apps" -> "Criar App"
3. Obtenha o ID da Empresa (CorpID) e o Secret do App
4. Configure "Receber Mensagens" nas configurações do app para obter o Token e o EncodingAESKey
5. Defina a URL de callback como `http://<your-server-ip>:<port>/webhook/wecom-app`
6. Insira o CorpID, Secret, AgentID e outras informações no arquivo de configuração
Nota: O PicoClaw agora usa um servidor HTTP Gateway compartilhado para receber callbacks de webhook de todos os canais. O endereço de escuta padrão é 127.0.0.1:18790. Para receber callbacks da internet pública, configure um reverse proxy do seu domínio externo para o Gateway (porta padrão 18790).

47
docs/channels/wecom/wecom_app/README.vi.md Normal file
View file

@ -0,0 +1,47 @@
> Quay lại [README](../../../../README.vi.md)
# Ứng dụng nội bộ WeCom
Ứng dụng nội bộ WeCom là ứng dụng được doanh nghiệp tạo ra trong WeCom, chủ yếu dùng cho mục đích nội bộ. Thông qua ứng dụng nội bộ WeCom, doanh nghiệp có thể thực hiện giao tiếp và cộng tác hiệu quả với nhân viên, nâng cao hiệu suất làm việc.
## Cấu hình
```json
{
"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": [],
"reply_timeout": 5
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ---------------- | ------ | --------- | ---------------------------------------- |
| corp_id | string | Có | ID doanh nghiệp |
| corp_secret | string | Có | Secret của ứng dụng |
| agent_id | int | Có | ID agent của ứng dụng |
| token | string | Có | Token xác minh callback |
| encoding_aes_key | string | Có | Khóa AES 43 ký tự |
| webhook_path | string | Không | Đường dẫn webhook (mặc định: /webhook/wecom-app) |
| allow_from | array | Không | Danh sách cho phép ID người dùng |
| reply_timeout | int | Không | Thời gian chờ phản hồi tính bằng giây |
## Hướng dẫn thiết lập
1. Đăng nhập vào [Bảng điều khiển quản trị WeCom](https://work.weixin.qq.com/)
2. Vào "Quản lý ứng dụng" -> "Tạo ứng dụng"
3. Lấy ID doanh nghiệp (CorpID) và Secret của ứng dụng
4. Cấu hình "Nhận tin nhắn" trong cài đặt ứng dụng để lấy Token và EncodingAESKey
5. Đặt URL callback thành `http://<your-server-ip>:<port>/webhook/wecom-app`
6. Nhập CorpID, Secret, AgentID và các thông tin khác vào file cấu hình
Lưu ý: PicoClaw hiện sử dụng máy chủ HTTP Gateway dùng chung để nhận callback webhook cho tất cả các kênh. Địa chỉ lắng nghe mặc định là 127.0.0.1:18790. Để nhận callback từ internet công cộng, hãy cấu hình reverse proxy từ tên miền bên ngoài của bạn đến Gateway (cổng mặc định 18790).

2
docs/channels/wecom/wecom_app/README.zh.md
View file

@ -1,3 +1,5 @@
> 返回 [README](../../../../README.zh.md)
# 企业微信自建应用
企业微信自建应用是指企业在企业微信中创建的应用，主要用于企业内部使用。通过企业微信自建应用，企业可以实现与员工的高效沟通和协作，提高工作效率。

41
docs/channels/wecom/wecom_bot/README.fr.md Normal file
View file

@ -0,0 +1,41 @@
> Retour au [README](../../../../README.fr.md)
# WeCom Bot
Le WeCom Bot est une méthode d'intégration rapide fournie par WeCom, permettant de recevoir des messages via une URL Webhook.
## Configuration
```json
{
"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": [],
"reply_timeout": 5
}
}
}
```
| Champ | Type | Requis | Description |
| ---------------- | ------ | ------ | -------------------------------------------- |
| token | string | Oui | Jeton de vérification de signature |
| encoding_aes_key | string | Oui | Clé AES de 43 caractères utilisée pour le déchiffrement |
| webhook_url | string | Oui | URL Webhook du bot de groupe WeCom utilisée pour envoyer les réponses |
| webhook_path | string | Non | Chemin de l'endpoint webhook (par défaut : /webhook/wecom) |
| allow_from | array | Non | Liste blanche d'ID utilisateurs (vide = autoriser tous les utilisateurs) |
| reply_timeout | int | Non | Délai de réponse en secondes (par défaut : 5) |
## Procédure de configuration
1. Ajouter un bot à un groupe WeCom
2. Obtenir l'URL Webhook
3. (Pour recevoir des messages) Configurer l'adresse API de réception des messages (URL de callback), le Token et l'EncodingAESKey sur la page de configuration du bot
4. Saisir les informations pertinentes dans le fichier de configuration
Remarque : PicoClaw utilise désormais un serveur HTTP Gateway partagé pour recevoir les callbacks webhook de tous les canaux. L'adresse d'écoute par défaut est 127.0.0.1:18790. Pour recevoir des callbacks depuis l'internet public, configurez un reverse proxy de votre domaine externe vers le Gateway (port par défaut 18790).

41
docs/channels/wecom/wecom_bot/README.ja.md Normal file
View file

@ -0,0 +1,41 @@
> [README](../../../../README.ja.md) に戻る
# 企業WeChat ボット
企業WeChat ボットは、企業WeChatが提供するWebhook URLを通じてメッセージを受信できる迅速な連携方式です。
## 設定
```json
{
"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": [],
"reply_timeout": 5
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------------- | ------ | ---- | -------------------------------------------- |
| token | string | はい | 署名検証トークン |
| encoding_aes_key | string | はい | 復号化に使用する43文字のAESキー |
| webhook_url | string | はい | 返信送信に使用する企業WeChatグループボットのWebhook URL |
| webhook_path | string | いいえ | Webhookエンドポイントパス（デフォルト：/webhook/wecom） |
| allow_from | array | いいえ | ユーザーIDの許可リスト（空 = 全ユーザーを許可） |
| reply_timeout | int | いいえ | 返信タイムアウト（秒、デフォルト：5） |
## セットアップ手順
1. 企業WeChatグループにボットを追加
2. Webhook URLを取得
3. （メッセージを受信する場合）ボット設定ページでメッセージ受信APIアドレス（コールバックURL）、Token、EncodingAESKeyを設定
4. 関連情報を設定ファイルに入力
注意：PicoClawは現在、すべてのチャンネルのwebhookコールバックを受信するために共有のGateway HTTPサーバーを使用しています。デフォルトのリスニングアドレスは127.0.0.1:18790です。公共インターネットからコールバックを受信するには、外部ドメインをGateway（デフォルトポート18790）にリバースプロキシしてください。

41
docs/channels/wecom/wecom_bot/README.md Normal file
View file

@ -0,0 +1,41 @@
> Back to [README](../../../../README.md)
# WeCom Bot
WeCom Bot is a quick integration method provided by WeCom that can receive messages via a Webhook URL.
## Configuration
```json
{
"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": [],
"reply_timeout": 5
}
}
}
```
| Field | Type | Required | Description |
| ---------------- | ------ | -------- | -------------------------------------------- |
| token | string | Yes | Signature verification token |
| encoding_aes_key | string | Yes | 43-character AES key used for decryption |
| webhook_url | string | Yes | WeCom group bot webhook URL used to send replies |
| webhook_path | string | No | Webhook endpoint path (default: /webhook/wecom) |
| allow_from | array | No | User ID allowlist (empty = allow all users) |
| reply_timeout | int | No | Reply timeout in seconds (default: 5) |
## Setup
1. Add a bot to a WeCom group
2. Obtain the Webhook URL
3. (To receive messages) Configure the message receiving API address (callback URL), Token, and EncodingAESKey on the bot configuration page
4. Enter the relevant information into the config file
Note: PicoClaw now uses a shared Gateway HTTP server to receive webhook callbacks for all channels. The default listening address is 127.0.0.1:18790. To receive callbacks from the public internet, reverse-proxy your external domain to the Gateway (default port 18790).

41
docs/channels/wecom/wecom_bot/README.pt-br.md Normal file
View file

@ -0,0 +1,41 @@
> Voltar ao [README](../../../../README.pt-br.md)
# WeCom Bot
O WeCom Bot é um método de integração rápida fornecido pelo WeCom que pode receber mensagens via URL de Webhook.
## Configuração
```json
{
"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": [],
"reply_timeout": 5
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ---------------- | ------ | ----------- | -------------------------------------------- |
| token | string | Sim | Token de verificação de assinatura |
| encoding_aes_key | string | Sim | Chave AES de 43 caracteres usada para descriptografia |
| webhook_url | string | Sim | URL do webhook do bot de grupo WeCom usada para enviar respostas |
| webhook_path | string | Não | Caminho do endpoint webhook (padrão: /webhook/wecom) |
| allow_from | array | Não | Lista de permissão de IDs de usuários (vazio = permitir todos) |
| reply_timeout | int | Não | Timeout de resposta em segundos (padrão: 5) |
## Configuração passo a passo
1. Adicione um bot a um grupo WeCom
2. Obtenha a URL do Webhook
3. (Para receber mensagens) Configure o endereço da API de recebimento de mensagens (URL de callback), Token e EncodingAESKey na página de configuração do bot
4. Insira as informações relevantes no arquivo de configuração
Nota: O PicoClaw agora usa um servidor HTTP Gateway compartilhado para receber callbacks de webhook de todos os canais. O endereço de escuta padrão é 127.0.0.1:18790. Para receber callbacks da internet pública, configure um reverse proxy do seu domínio externo para o Gateway (porta padrão 18790).

41
docs/channels/wecom/wecom_bot/README.vi.md Normal file
View file

@ -0,0 +1,41 @@
> Quay lại [README](../../../../README.vi.md)
# WeCom Bot
WeCom Bot là phương thức tích hợp nhanh do WeCom cung cấp, có thể nhận tin nhắn qua URL Webhook.
## Cấu hình
```json
{
"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": [],
"reply_timeout": 5
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ---------------- | ------ | --------- | -------------------------------------------- |
| token | string | Có | Token xác minh chữ ký |
| encoding_aes_key | string | Có | Khóa AES 43 ký tự dùng để giải mã |
| webhook_url | string | Có | URL webhook của bot nhóm WeCom dùng để gửi phản hồi |
| webhook_path | string | Không | Đường dẫn endpoint webhook (mặc định: /webhook/wecom) |
| allow_from | array | Không | Danh sách cho phép ID người dùng (rỗng = cho phép tất cả) |
| reply_timeout | int | Không | Thời gian chờ phản hồi tính bằng giây (mặc định: 5) |
## Hướng dẫn thiết lập
1. Thêm bot vào một nhóm WeCom
2. Lấy URL Webhook
3. (Để nhận tin nhắn) Cấu hình địa chỉ API nhận tin nhắn (URL callback), Token và EncodingAESKey trên trang cấu hình bot
4. Nhập thông tin liên quan vào file cấu hình
Lưu ý: PicoClaw hiện sử dụng máy chủ HTTP Gateway dùng chung để nhận callback webhook cho tất cả các kênh. Địa chỉ lắng nghe mặc định là 127.0.0.1:18790. Để nhận callback từ internet công cộng, hãy cấu hình reverse proxy từ tên miền bên ngoài của bạn đến Gateway (cổng mặc định 18790).

2
docs/channels/wecom/wecom_bot/README.zh.md
View file

@ -1,3 +1,5 @@
> 返回 [README](../../../../README.zh.md)
# 企业微信机器人
企业微信机器人是企业微信提供的一种快速接入方式，可以通过 Webhook URL 接收消息。

205
docs/chat-apps.md
View file

@ -8,22 +8,22 @@ Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk,
> **Note**: All webhook-based channels (LINE, WeCom, etc.) are served on a single shared Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). There are no per-channel ports to configure. Note: Feishu uses WebSocket/SDK mode and does not use the shared HTTP webhook server.
| Channel | Setup |
| ------------ | ---------------------------------- |
| **Telegram** | Easy (just a token) |
| **Discord** | Easy (bot token + intents) |
| **WhatsApp** | Easy (native: QR scan; or bridge URL) |
| **Matrix** | Medium (homeserver + bot access token) |
| **QQ** | Easy (AppID + AppSecret) |
| **DingTalk** | Medium (app credentials) |
| **LINE** | Medium (credentials + webhook URL) |
| **WeCom AI Bot** | Medium (Token + AES key) |
| **Feishu** | Medium (App ID + Secret, WebSocket mode) |
| **Slack** | Medium (Bot token + App token) |
| **IRC** | Medium (server + TLS config) |
| **OneBot** | Medium (QQ via OneBot protocol) |
| **MaixCam** | Easy (Sipeed hardware integration) |
| **Pico** | Native PicoClaw protocol |
| Channel | Difficulty | Description | Documentation |
| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Telegram** | ⭐ Easy | Recommended, voice-to-text, long polling (no public IP needed) | [Docs](../channels/telegram/README.md) |
| **Discord** | ⭐ Easy | Socket Mode, group/DM support, rich bot ecosystem | [Docs](../channels/discord/README.md) |
| **WhatsApp** | ⭐ Easy | Native (QR scan) or Bridge URL | [Docs](#whatsapp) |
| **Slack** | ⭐ Easy | **Socket Mode** (no public IP needed), enterprise | [Docs](../channels/slack/README.md) |
| **Matrix** | ⭐⭐ Medium | Federated protocol, self-hosting supported | [Docs](../channels/matrix/README.md) |
| **QQ** | ⭐⭐ Medium | Official bot API, Chinese community | [Docs](../channels/qq/README.md) |
| **DingTalk** | ⭐⭐ Medium | Stream mode (no public IP needed), enterprise | [Docs](../channels/dingtalk/README.md) |
| **LINE** | ⭐⭐⭐ Advanced | HTTPS Webhook required | [Docs](../channels/line/README.md) |
| **WeCom (企业微信)** | ⭐⭐⭐ Advanced | Group Bot (Webhook), custom App (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.md) / [App](../channels/wecom/wecom_app/README.md) / [AI Bot](../channels/wecom/wecom_aibot/README.md) |
| **Feishu (飞书)** | ⭐⭐⭐ Advanced | Enterprise collaboration, feature-rich | [Docs](../channels/feishu/README.md) |
| **IRC** | ⭐⭐ Medium | Server + TLS configuration | - |
| **OneBot** | ⭐⭐ Medium | NapCat/Go-CQHTTP compatible, community ecosystem | [Docs](../channels/onebot/README.md) |
| **MaixCam** | ⭐ Easy | Hardware integration channel for Sipeed AI cameras | [Docs](../channels/maixcam/README.md) |
| **Pico** | ⭐ Easy | Native PicoClaw protocol channel | |
<details>
<summary><b>Telegram</b> (Recommended)</summary>
@ -172,12 +172,13 @@ If `session_store_path` is empty, the session is stored in `<workspace>/whatsapp
<details>
<summary><b>QQ</b></summary>
**1. Create a bot**
**Quick setup (recommended)**
- Go to [QQ Open Platform](https://q.qq.com/#)
- Create an application → Get **AppID** and **AppSecret**
QQ Open Platform provides a one-click setup page for OpenClaw-compatible bots:
**2. Configure**
1. Open [QQ Bot Quick Start](https://q.qq.com/qqbot/openclaw/index.html) and scan the QR code to log in
2. A bot is created automatically — copy the **App ID** and **App Secret**
3. Configure PicoClaw:
```json
{
@ -192,13 +193,20 @@ If `session_store_path` is empty, the session is stored in `<workspace>/whatsapp
}
```
> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access.
4. Run `picoclaw gateway` and open QQ to chat with your bot
**3. Run**
> The App Secret is only shown once. Save it immediately — viewing it again will force a reset.
>
> Bots created via the quick setup page are initially for the creator only and do not support group chats. To enable group access, configure sandbox mode on the [QQ Open Platform](https://q.qq.com/).
```bash
picoclaw gateway
```
**Manual setup**
If you prefer to create the bot manually:
* Log in at [QQ Open Platform](https://q.qq.com/) to register as a developer
* Create a QQ bot — customize its avatar and name
* Copy the **App ID** and **App Secret** from the bot settings
* Configure as shown above and run `picoclaw gateway`
</details>
@ -326,7 +334,7 @@ PicoClaw supports three types of WeCom integration:
**Option 2: WeCom App (Custom App)** - More features, proactive messaging, private chat only
**Option 3: WeCom AI Bot (AI Bot)** - Official AI Bot, streaming replies, supports group & private chat
See [WeCom AI Bot Configuration Guide](channels/wecom/wecom_aibot/README.zh.md) for detailed setup instructions.
See [WeCom AI Bot Configuration Guide](channels/wecom/wecom_aibot/README.md) for detailed setup instructions.
**Quick Setup - WeCom Bot:**
@ -430,3 +438,148 @@ picoclaw gateway
> **Note**: WeCom AI Bot uses streaming pull protocol — no reply timeout concerns. Long tasks (>30 seconds) automatically switch to `response_url` push delivery.
</details>
<details>
<summary><b>Feishu (Lark)</b></summary>
PicoClaw connects to Feishu via WebSocket/SDK mode — no public webhook URL or callback server needed.
**1. Create an app**
* Go to [Feishu Open Platform](https://open.feishu.cn/) and create an application
* In the app settings, enable the **Bot** capability
* Create a version and publish the app (the app must be published to take effect)
* Copy the **App ID** (starts with `cli_`) and **App Secret**
**2. Configure**
```json
{
"channels": {
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
Optional fields: `encrypt_key` and `verification_token` for event encryption (recommended for production).
**3. Run and chat**
```bash
picoclaw gateway
```
Open Feishu, search for your bot name, and start chatting. You can also add the bot to a group — use `group_trigger.mention_only: true` to only respond when @mentioned.
For full options, see [Feishu Channel Configuration Guide](channels/feishu/README.md).
</details>
<details>
<summary><b>Slack</b></summary>
**1. Create a Slack app**
* Go to [Slack API](https://api.slack.com/apps) and create a new app
* Under **OAuth & Permissions**, add bot scopes: `chat:write`, `app_mentions:read`, `im:history`, `im:read`, `im:write`
* Install the app to your workspace
* Copy the **Bot Token** (`xoxb-...`) and **App-Level Token** (`xapp-...`, enable Socket Mode to get this)
**2. Configure**
```json
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-YOUR-BOT-TOKEN",
"app_token": "xapp-YOUR-APP-TOKEN",
"allow_from": []
}
}
}
```
**3. Run**
```bash
picoclaw gateway
```
</details>
<details>
<summary><b>IRC</b></summary>
**1. Configure**
```json
{
"channels": {
"irc": {
"enabled": true,
"server": "irc.libera.chat:6697",
"tls": true,
"nick": "picoclaw-bot",
"channels": ["#your-channel"],
"password": "",
"allow_from": []
}
}
}
```
Optional: `nickserv_password` for NickServ authentication, `sasl_user`/`sasl_password` for SASL auth.
**2. Run**
```bash
picoclaw gateway
```
The bot will connect to the IRC server and join the specified channels.
</details>
<details>
<summary><b>OneBot (QQ via OneBot protocol)</b></summary>
OneBot is an open protocol for QQ bots. PicoClaw connects to any OneBot v11 compatible implementation (e.g., [Lagrange](https://github.com/LagrangeDev/Lagrange.Core), [NapCat](https://github.com/NapNeko/NapCatQQ)) via WebSocket.
**1. Set up a OneBot implementation**
Install and run a OneBot v11 compatible QQ bot framework. Enable its WebSocket server.
**2. Configure**
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://127.0.0.1:8080",
"access_token": "",
"allow_from": []
}
}
}
```
| Field | Description |
|-------|-------------|
| `ws_url` | WebSocket URL of the OneBot implementation |
| `access_token` | Access token for authentication (if configured in OneBot) |
| `reconnect_interval` | Reconnect interval in seconds (default: 5) |
**3. Run**
```bash
picoclaw gateway
```
</details>

128
docs/fr/chat-apps.md
View file

@ -8,22 +8,22 @@ Communiquez avec votre PicoClaw via Telegram, Discord, WhatsApp, Matrix, QQ, Din
> **Note** : Tous les canaux basés sur les webhooks (LINE, WeCom, etc.) sont servis sur un seul serveur HTTP Gateway partagé (`gateway.host`:`gateway.port`, par défaut `127.0.0.1:18790`). Il n'y a pas de ports par canal à configurer. Note : Feishu utilise le mode WebSocket/SDK et n'utilise pas le serveur HTTP webhook partagé.
| Canal | Configuration |
| ------------ | -------------------------------------- |
| **Telegram** | Facile (juste un token) |
| **Discord** | Facile (bot token + intents) |
| **WhatsApp** | Facile (natif : scan QR ; ou bridge URL) |
| **Matrix** | Moyen (homeserver + bot access token) |
| **QQ** | Facile (AppID + AppSecret) |
| **DingTalk** | Moyen (identifiants de l'application) |
| **LINE** | Moyen (identifiants + webhook URL) |
| **WeCom AI Bot** | Moyen (Token + clé AES) |
| **Feishu** | Moyen (App ID + Secret, mode WebSocket) |
| **Slack** | Moyen (Bot token + App token) |
| **IRC** | Moyen (serveur + configuration TLS) |
| **OneBot** | Moyen (QQ via protocole OneBot) |
| **MaixCam** | Facile (intégration matérielle Sipeed) |
| **Pico** | Native PicoClaw protocol |
| Canal | Difficulté | Description | Documentation |
| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Telegram** | ⭐ Facile | Recommandé, transcription vocale, long polling (pas d'IP publique requise) | [Documentation](../channels/telegram/README.fr.md) |
| **Discord** | ⭐ Facile | Socket Mode, groupes/DM, écosystème bot riche | [Documentation](../channels/discord/README.fr.md) |
| **WhatsApp** | ⭐ Facile | Natif (scan QR) ou Bridge URL | [Documentation](#whatsapp) |
| **Slack** | ⭐ Facile | **Socket Mode** (pas d'IP publique requise), entreprise | [Documentation](../channels/slack/README.fr.md) |
| **Matrix** | ⭐⭐ Moyen | Protocole fédéré, auto-hébergement possible | [Documentation](../channels/matrix/README.fr.md) |
| **QQ** | ⭐⭐ Moyen | API bot officielle, communauté chinoise | [Documentation](../channels/qq/README.fr.md) |
| **DingTalk** | ⭐⭐ Moyen | Mode Stream (pas d'IP publique requise), entreprise | [Documentation](../channels/dingtalk/README.fr.md) |
| **LINE** | ⭐⭐⭐ Avancé | HTTPS Webhook requis | [Documentation](../channels/line/README.fr.md) |
| **WeCom (企业微信)** | ⭐⭐⭐ Avancé | Bot groupe (Webhook), app personnalisée (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.fr.md) / [App](../channels/wecom/wecom_app/README.fr.md) / [AI Bot](../channels/wecom/wecom_aibot/README.fr.md) |
| **Feishu (飞书)** | ⭐⭐⭐ Avancé | Collaboration entreprise, fonctionnalités riches | [Documentation](../channels/feishu/README.fr.md) |
| **IRC** | ⭐⭐ Moyen | Serveur + configuration TLS | - |
| **OneBot** | ⭐⭐ Moyen | Compatible NapCat/Go-CQHTTP, écosystème communautaire | [Documentation](../channels/onebot/README.fr.md) |
| **MaixCam** | ⭐ Facile | Canal d'intégration matérielle pour caméras AI Sipeed | [Documentation](../channels/maixcam/README.fr.md) |
| **Pico** | ⭐ Facile | Canal protocole natif PicoClaw | |
<details>
<summary><b>Telegram</b> (Recommandé)</summary>
@ -168,12 +168,13 @@ Si `session_store_path` est vide, la session est stockée dans `<workspace>/what
<details>
<summary><b>QQ</b></summary>
**1. Créer un bot**
**Configuration rapide (recommandée)**
- Allez sur [QQ Open Platform](https://q.qq.com/#)
- Créez une application → Obtenez **AppID** et **AppSecret**
QQ Open Platform propose une page de configuration en un clic pour les bots compatibles OpenClaw :
**2. Configurer**
1. Ouvrez [QQ Bot Quick Start](https://q.qq.com/qqbot/openclaw/index.html) et scannez le QR code pour vous connecter
2. Un bot est créé automatiquement — copiez l'**App ID** et l'**App Secret**
3. Configurez PicoClaw :
```json
{
@ -188,13 +189,20 @@ Si `session_store_path` est vide, la session est stockée dans `<workspace>/what
}
```
> Définissez `allow_from` vide pour autoriser tous les utilisateurs, ou spécifiez des numéros QQ pour restreindre l'accès.
4. Lancez `picoclaw gateway` et ouvrez QQ pour discuter avec votre bot
**3. Lancer**
> L'App Secret n'est affiché qu'une seule fois. Enregistrez-le immédiatement — le consulter à nouveau forcera une réinitialisation.
>
> Les bots créés via la page de configuration rapide sont initialement réservés au créateur et ne prennent pas en charge les discussions de groupe. Pour activer l'accès en groupe, configurez le mode sandbox sur la [QQ Open Platform](https://q.qq.com/).
```bash
picoclaw gateway
```
**Configuration manuelle**
Si vous préférez créer le bot manuellement :
* Connectez-vous sur [QQ Open Platform](https://q.qq.com/) pour vous inscrire en tant que développeur
* Créez un bot QQ — personnalisez son avatar et son nom
* Copiez l'**App ID** et l'**App Secret** depuis les paramètres du bot
* Configurez comme indiqué ci-dessus et lancez `picoclaw gateway`
</details>
@ -322,7 +330,7 @@ PicoClaw prend en charge trois types d'intégration WeCom :
**Option 2 : WeCom App (Application personnalisée)** - Plus de fonctionnalités, messagerie proactive, chat privé uniquement
**Option 3 : WeCom AI Bot (Bot IA)** - Bot IA officiel, réponses en streaming, prend en charge les discussions de groupe et privées
Voir le [Guide de Configuration WeCom AI Bot](../channels/wecom/wecom_aibot/README.zh.md) pour les instructions détaillées.
Voir le [Guide de Configuration WeCom AI Bot](../channels/wecom/wecom_aibot/README.fr.md) pour les instructions détaillées.
**Configuration rapide - WeCom Bot :**
@ -430,10 +438,14 @@ picoclaw gateway
<details>
<summary><b>Feishu (飞书)</b></summary>
PicoClaw se connecte à Feishu via le mode WebSocket/SDK — aucune URL webhook publique ni serveur de callback nécessaire.
**1. Créer une application**
* Allez sur [Feishu Open Platform](https://open.feishu.cn/)
* Créez une application → Obtenez **App ID** et **App Secret**
* Allez sur [Feishu Open Platform](https://open.feishu.cn/) et créez une application
* Dans les paramètres de l'application, activez la capacité **Bot**
* Créez une version et publiez l'application (l'application doit être publiée pour prendre effet)
* Copiez l'**App ID** (commence par `cli_`) et l'**App Secret**
**2. Configurer**
@ -443,23 +455,25 @@ picoclaw gateway
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
> Feishu utilise le mode WebSocket/SDK et ne nécessite pas de serveur webhook.
Optionnel : `encrypt_key` et `verification_token` pour le chiffrement des événements (recommandé en production).
**3. Lancer**
**3. Lancer et discuter**
```bash
picoclaw gateway
```
Ouvrez Feishu, recherchez le nom de votre bot et commencez à discuter. Vous pouvez aussi ajouter le bot à un groupe — utilisez `group_trigger.mention_only: true` pour ne répondre que lorsqu'il est @mentionné.
Pour toutes les options, voir le [Guide de Configuration du Canal Feishu](../channels/feishu/README.fr.md).
</details>
<details>
@ -467,9 +481,10 @@ picoclaw gateway
**1. Créer une application Slack**
* Allez sur [Slack API](https://api.slack.com/apps)
* Créez une nouvelle application
* Obtenez le **Bot Token** et l'**App Token**
* Allez sur [Slack API](https://api.slack.com/apps) et créez une nouvelle application
* Sous **OAuth & Permissions**, ajoutez les scopes bot : `chat:write`, `app_mentions:read`, `im:history`, `im:read`, `im:write`
* Installez l'application dans votre workspace
* Copiez le **Bot Token** (`xoxb-...`) et l'**App-Level Token** (`xapp-...`, activez Socket Mode pour l'obtenir)
**2. Configurer**
@ -478,8 +493,8 @@ picoclaw gateway
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-your-bot-token",
"app_token": "xapp-your-app-token",
"bot_token": "xoxb-YOUR-BOT-TOKEN",
"app_token": "xapp-YOUR-APP-TOKEN",
"allow_from": []
}
}
@ -497,42 +512,44 @@ picoclaw gateway
<details>
<summary><b>IRC</b></summary>
**1. Configurer le serveur IRC**
* Préparez les informations de votre serveur IRC (adresse, port, canal)
**2. Configurer**
**1. Configurer**
```json
{
"channels": {
"irc": {
"enabled": true,
"server": "irc.example.com:6697",
"nick": "picoclaw-bot",
"channel": "#your-channel",
"server": "irc.libera.chat:6697",
"tls": true,
"nick": "picoclaw-bot",
"channels": ["#your-channel"],
"password": "",
"allow_from": []
}
}
}
```
**3. Lancer**
Optionnel : `nickserv_password` pour l'authentification NickServ, `sasl_user`/`sasl_password` pour l'authentification SASL.
**2. Lancer**
```bash
picoclaw gateway
```
Le bot se connectera au serveur IRC et rejoindra les canaux spécifiés.
</details>
<details>
<summary><b>OneBot</b></summary>
<summary><b>OneBot (QQ via protocole OneBot)</b></summary>
**1. Configurer OneBot**
OneBot est un protocole ouvert pour les bots QQ. PicoClaw se connecte à toute implémentation compatible OneBot v11 (par ex. [Lagrange](https://github.com/LagrangeDev/Lagrange.Core), [NapCat](https://github.com/NapNeko/NapCatQQ)) via WebSocket.
* Installez une implémentation OneBot compatible (par ex. go-cqhttp, Lagrange)
* Configurez la connexion WebSocket
**1. Configurer une implémentation OneBot**
Installez et exécutez un framework de bot QQ compatible OneBot v11. Activez son serveur WebSocket.
**2. Configurer**
@ -541,14 +558,19 @@ picoclaw gateway
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://localhost:8080",
"ws_url": "ws://127.0.0.1:8080",
"access_token": "",
"allow_from": []
}
}
}
```
> OneBot permet d'utiliser QQ via le protocole OneBot standard.
| Champ | Description |
|-------|-------------|
| `ws_url` | URL WebSocket de l'implémentation OneBot |
| `access_token` | Token d'accès pour l'authentification (si configuré dans OneBot) |
| `reconnect_interval` | Intervalle de reconnexion en secondes (par défaut : 5) |
**3. Lancer**

109
docs/ja/chat-apps.md
View file

@ -12,19 +12,19 @@ PicoClaw は複数のチャットプラットフォームをサポートして
| チャネル | セットアップ難易度 | 特徴 | ドキュメント |
| -------------------- | ------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Telegram** | ⭐ 簡単 | 推奨、音声テキスト変換対応、ロングポーリング（公開 IP 不要） | [ドキュメント](../channels/telegram/README.zh.md) |
| **Discord** | ⭐ 簡単 | Socket Mode、グループ/DM 対応、Bot エコシステム充実 | [ドキュメント](../channels/discord/README.zh.md) |
| **Telegram** | ⭐ 簡単 | 推奨、音声テキスト変換対応、ロングポーリング（公開 IP 不要） | [ドキュメント](../channels/telegram/README.ja.md) |
| **Discord** | ⭐ 簡単 | Socket Mode、グループ/DM 対応、Bot エコシステム充実 | [ドキュメント](../channels/discord/README.ja.md) |
| **WhatsApp** | ⭐ 簡単 | ネイティブ (QR スキャン) または Bridge URL | [ドキュメント](#whatsapp) |
| **Slack** | ⭐ 簡単 | **Socket Mode** (公開 IP 不要)、エンタープライズ対応 | [ドキュメント](../channels/slack/README.zh.md) |
| **Matrix** | ⭐⭐ 中程度 | フェデレーションプロトコル、セルフホスト対応 | [ドキュメント](../channels/matrix/README.zh.md) |
| **QQ** | ⭐⭐ 中程度 | 公式ボット API、中国コミュニティ向け | [ドキュメント](../channels/qq/README.zh.md) |
| **DingTalk** | ⭐⭐ 中程度 | Stream モード（公開 IP 不要）、企業向け | [ドキュメント](../channels/dingtalk/README.zh.md) |
| **LINE** | ⭐⭐⭐ やや難 | HTTPS Webhook が必要 | [ドキュメント](../channels/line/README.zh.md) |
| **WeCom (企業微信)** | ⭐⭐⭐ やや難 | グループ Bot (Webhook)、カスタムアプリ (API)、AI Bot 対応 | [Bot](../channels/wecom/wecom_bot/README.zh.md) / [App](../channels/wecom/wecom_app/README.zh.md) / [AI Bot](../channels/wecom/wecom_aibot/README.zh.md) |
| **Feishu (飛書)** | ⭐⭐⭐ やや難 | エンタープライズコラボレーション、機能豊富 | [ドキュメント](../channels/feishu/README.zh.md) |
| **Slack** | ⭐ 簡単 | **Socket Mode** (公開 IP 不要)、エンタープライズ対応 | [ドキュメント](../channels/slack/README.ja.md) |
| **Matrix** | ⭐⭐ 中程度 | フェデレーションプロトコル、セルフホスト対応 | [ドキュメント](../channels/matrix/README.ja.md) |
| **QQ** | ⭐⭐ 中程度 | 公式ボット API、中国コミュニティ向け | [ドキュメント](../channels/qq/README.ja.md) |
| **DingTalk** | ⭐⭐ 中程度 | Stream モード（公開 IP 不要）、企業向け | [ドキュメント](../channels/dingtalk/README.ja.md) |
| **LINE** | ⭐⭐⭐ やや難 | HTTPS Webhook が必要 | [ドキュメント](../channels/line/README.ja.md) |
| **WeCom (企業微信)** | ⭐⭐⭐ やや難 | グループ Bot (Webhook)、カスタムアプリ (API)、AI Bot 対応 | [Bot](../channels/wecom/wecom_bot/README.ja.md) / [App](../channels/wecom/wecom_app/README.ja.md) / [AI Bot](../channels/wecom/wecom_aibot/README.ja.md) |
| **Feishu (飛書)** | ⭐⭐⭐ やや難 | エンタープライズコラボレーション、機能豊富 | [ドキュメント](../channels/feishu/README.ja.md) |
| **IRC** | ⭐⭐ 中程度 | サーバー + TLS 設定 | - |
| **OneBot** | ⭐⭐ 中程度 | NapCat/Go-CQHTTP 互換、コミュニティエコシステム充実 | [ドキュメント](../channels/onebot/README.zh.md) |
| **MaixCam** | ⭐ 簡単 | Sipeed AI カメラハードウェア統合チャネル | [ドキュメント](../channels/maixcam/README.zh.md) |
| **OneBot** | ⭐⭐ 中程度 | NapCat/Go-CQHTTP 互換、コミュニティエコシステム充実 | [ドキュメント](../channels/onebot/README.ja.md) |
| **MaixCam** | ⭐ 簡単 | Sipeed AI カメラハードウェア統合チャネル | [ドキュメント](../channels/maixcam/README.ja.md) |
| **Pico** | ⭐ 簡単 | PicoClaw ネイティブプロトコルチャネル | |
---
@ -207,12 +207,13 @@ picoclaw gateway
<details>
<summary><b>QQ</b></summary>
**1. Bot を作成**
**クイックセットアップ（推奨）**
- [QQ 開放プラットフォーム](https://q.qq.com/#) にアクセス
- アプリケーションを作成 → **AppID** と **AppSecret** を取得
QQ 開放プラットフォームでは、OpenClaw 互換ボットのワンクリックセットアップページが提供されています：
**2. 設定**
1. [QQ Bot クイックスタート](https://q.qq.com/qqbot/openclaw/index.html) を開き、QR コードをスキャンしてログイン
2. ボットが自動的に作成されます — **App ID** と **App Secret** をコピー
3. PicoClaw を設定：
```json
{
@ -227,13 +228,20 @@ picoclaw gateway
}
```
> `allow_from` を空にするとすべてのユーザーを許可します。QQ 番号を指定してアクセスを制限することもできます。
4. `picoclaw gateway` を実行し、QQ を開いてボットとチャット
**3. 実行**
> App Secret は一度しか表示されません。すぐに保存してください — 再度表示するとリセットされます。
>
> クイックセットアップで作成されたボットは、最初は作成者のみが使用でき、グループチャットには対応していません。グループアクセスを有効にするには、[QQ 開放プラットフォーム](https://q.qq.com/) でサンドボックスモードを設定してください。
```bash
picoclaw gateway
```
**手動セットアップ**
ボットを手動で作成する場合：
* [QQ 開放プラットフォーム](https://q.qq.com/) にログインして開発者登録
* QQ ボットを作成 — アバターと名前をカスタマイズ
* ボット設定から **App ID** と **App Secret** をコピー
* 上記の設定を行い、`picoclaw gateway` を実行
</details>
@ -242,9 +250,10 @@ picoclaw gateway
**1. Slack App を作成**
* [Slack API](https://api.slack.com/apps) でアプリを作成
* **Socket Mode** を有効化
* **Bot Token** と **App-Level Token** を取得
* [Slack API](https://api.slack.com/apps) にアクセスして新しいアプリを作成
* **OAuth & Permissions** で Bot スコープを追加：`chat:write`、`app_mentions:read`、`im:history`、`im:read`、`im:write`
* アプリをワークスペースにインストール
* **Bot Token**（`xoxb-...`）と **App-Level Token**（`xapp-...`、Socket Mode を有効にして取得）をコピー
**2. 設定**
@ -253,8 +262,8 @@ picoclaw gateway
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-YOUR_BOT_TOKEN",
"app_token": "xapp-YOUR_APP_TOKEN",
"bot_token": "xoxb-YOUR-BOT-TOKEN",
"app_token": "xapp-YOUR-APP-TOKEN",
"allow_from": []
}
}
@ -280,21 +289,26 @@ picoclaw gateway
"irc": {
"enabled": true,
"server": "irc.libera.chat:6697",
"nick": "picoclaw-bot",
"tls": true,
"nick": "picoclaw-bot",
"channels": ["#your-channel"],
"password": "",
"allow_from": []
}
}
}
```
オプション：NickServ 認証用の `nickserv_password`、SASL 認証用の `sasl_user`/`sasl_password`。
**2. 実行**
```bash
picoclaw gateway
```
ボットは IRC サーバーに接続し、指定されたチャネルに参加します。
</details>
<details>
@ -382,11 +396,14 @@ picoclaw gateway
<details>
<summary><b>Feishu (飛書)</b></summary>
PicoClaw は WebSocket/SDK モードで飛書に接続します — 公開 Webhook URL やコールバックサーバーは不要です。
**1. アプリを作成**
* [飛書開放プラットフォーム](https://open.feishu.cn/) にアクセス
* 企業カスタムアプリを作成
* **App ID** と **App Secret** を取得
* [飛書開放プラットフォーム](https://open.feishu.cn/) にアクセスしてアプリケーションを作成
* アプリ設定で **ボット** 機能を有効化
* バージョンを作成してアプリを公開（アプリは公開しないと有効になりません）
* **App ID**（`cli_` で始まる）と **App Secret** をコピー
**2. 設定**
@ -396,21 +413,25 @@ picoclaw gateway
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
**3. 実行**
オプション：`encrypt_key` と `verification_token` でイベント暗号化（本番環境推奨）。
**3. 実行してチャット**
```bash
picoclaw gateway
```
飛書を開き、ボット名を検索してチャットを開始できます。ボットをグループに追加することもできます — `group_trigger.mention_only: true` を設定すると @メンション時のみ応答します。
詳細なオプションについては [飛書チャネル設定ガイド](../channels/feishu/README.ja.md) を参照してください。
</details>
<details>
@ -422,7 +443,7 @@ PicoClaw は 3 種類の WeCom 統合をサポートしています：
**方式 2: カスタムアプリ (App)** — より多機能、プロアクティブメッセージング、プライベートチャットのみ
**方式 3: AI Bot** — 公式 AI Bot、ストリーミング返信、グループ・プライベートチャット対応
詳細なセットアップ手順は [WeCom AI Bot 設定ガイド](../channels/wecom/wecom_aibot/README.zh.md) を参照してください。
詳細なセットアップ手順は [WeCom AI Bot 設定ガイド](../channels/wecom/wecom_aibot/README.ja.md) を参照してください。
**クイックセットアップ — グループ Bot：**
@ -528,24 +549,36 @@ picoclaw gateway
</details>
<details>
<summary><b>OneBot</b></summary>
<summary><b>OneBot（OneBot プロトコル経由の QQ）</b></summary>
**1. 設定**
OneBot は QQ ボット向けのオープンプロトコルです。PicoClaw は OneBot v11 互換の実装（例：[Lagrange](https://github.com/LagrangeDev/Lagrange.Core)、[NapCat](https://github.com/NapNeko/NapCatQQ)）に WebSocket で接続します。
NapCat / Go-CQHTTP などの OneBot 実装と互換性があります。
**1. OneBot 実装をセットアップ**
OneBot v11 互換の QQ ボットフレームワークをインストールして実行します。WebSocket サーバーを有効にしてください。
**2. 設定**
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://127.0.0.1:8080",
"access_token": "",
"allow_from": []
}
}
}
```
**2. 実行**
| フィールド | 説明 |
|-------|-------------|
| `ws_url` | OneBot 実装の WebSocket URL |
| `access_token` | 認証用アクセストークン（OneBot 側で設定している場合） |
| `reconnect_interval` | 再接続間隔（秒）（デフォルト：5） |
**3. 実行**
```bash
picoclaw gateway

249
docs/pt-br/chat-apps.md
View file

@ -8,22 +8,22 @@ Converse com seu picoclaw através do Telegram, Discord, WhatsApp, Matrix, QQ, D
> **Nota**: Todos os canais baseados em webhook (LINE, WeCom, etc.) são servidos em um único servidor HTTP Gateway compartilhado (`gateway.host`:`gateway.port`, padrão `127.0.0.1:18790`). Não há portas por canal para configurar. Nota: Feishu usa o modo WebSocket/SDK e não utiliza o servidor HTTP webhook compartilhado.
| Channel | Setup |
| ------------ | ---------------------------------- |
| **Telegram** | Easy (just a token) |
| **Discord** | Easy (bot token + intents) |
| **WhatsApp** | Easy (native: QR scan; or bridge URL) |
| **Matrix** | Medium (homeserver + bot access token) |
| **QQ** | Easy (AppID + AppSecret) |
| **DingTalk** | Medium (app credentials) |
| **LINE** | Medium (credentials + webhook URL) |
| **WeCom AI Bot** | Medium (Token + AES key) |
| **Feishu** | Medium (App ID + Secret, WebSocket mode) |
| **Slack** | Medium (Bot token + App token) |
| **IRC** | Medium (server + TLS config) |
| **OneBot** | Medium (QQ via OneBot protocol) |
| **MaixCam** | Easy (Sipeed hardware integration) |
| **Pico** | Native PicoClaw protocol |
| Canal | Dificuldade | Descrição | Documentação |
| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Telegram** | ⭐ Fácil | Recomendado, voz para texto, long polling (sem IP público) | [Documentação](../channels/telegram/README.pt-br.md) |
| **Discord** | ⭐ Fácil | Socket Mode, suporte a grupos/DM, ecossistema bot rico | [Documentação](../channels/discord/README.pt-br.md) |
| **WhatsApp** | ⭐ Fácil | Nativo (scan QR) ou Bridge URL | [Documentação](#whatsapp) |
| **Slack** | ⭐ Fácil | **Socket Mode** (sem IP público), empresarial | [Documentação](../channels/slack/README.pt-br.md) |
| **Matrix** | ⭐⭐ Médio | Protocolo federado, suporte a auto-hospedagem | [Documentação](../channels/matrix/README.pt-br.md) |
| **QQ** | ⭐⭐ Médio | API bot oficial, comunidade chinesa | [Documentação](../channels/qq/README.pt-br.md) |
| **DingTalk** | ⭐⭐ Médio | Modo Stream (sem IP público), empresarial | [Documentação](../channels/dingtalk/README.pt-br.md) |
| **LINE** | ⭐⭐⭐ Avançado | HTTPS Webhook obrigatório | [Documentação](../channels/line/README.pt-br.md) |
| **WeCom (企业微信)** | ⭐⭐⭐ Avançado | Bot de grupo (Webhook), app personalizado (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.pt-br.md) / [App](../channels/wecom/wecom_app/README.pt-br.md) / [AI Bot](../channels/wecom/wecom_aibot/README.pt-br.md) |
| **Feishu (飞书)** | ⭐⭐⭐ Avançado | Colaboração empresarial, rico em recursos | [Documentação](../channels/feishu/README.pt-br.md) |
| **IRC** | ⭐⭐ Médio | Servidor + configuração TLS | - |
| **OneBot** | ⭐⭐ Médio | Compatível com NapCat/Go-CQHTTP, ecossistema comunitário | [Documentação](../channels/onebot/README.pt-br.md) |
| **MaixCam** | ⭐ Fácil | Canal de integração de hardware para câmeras AI Sipeed | [Documentação](../channels/maixcam/README.pt-br.md) |
| **Pico** | ⭐ Fácil | Canal de protocolo nativo PicoClaw | |
<details>
<summary><b>Telegram</b> (Recomendado)</summary>
@ -168,12 +168,13 @@ Se `session_store_path` estiver vazio, a sessão é armazenada em `<workspace>/w
<details>
<summary><b>QQ</b></summary>
**1. Criar um bot**
**Configuração rápida (recomendada)**
- Acesse a [QQ Open Platform](https://q.qq.com/#)
- Crie um aplicativo → Obtenha **AppID** e **AppSecret**
A QQ Open Platform oferece uma página de configuração com um clique para bots compatíveis com OpenClaw:
**2. Configurar**
1. Abra o [QQ Bot Quick Start](https://q.qq.com/qqbot/openclaw/index.html) e escaneie o QR code para fazer login
2. Um bot é criado automaticamente — copie o **App ID** e o **App Secret**
3. Configure o PicoClaw:
```json
{
@ -188,13 +189,20 @@ Se `session_store_path` estiver vazio, a sessão é armazenada em `<workspace>/w
}
```
> Defina `allow_from` como vazio para permitir todos os usuários, ou especifique números QQ para restringir o acesso.
4. Execute `picoclaw gateway` e abra o QQ para conversar com seu bot
**3. Executar**
> O App Secret é exibido apenas uma vez. Salve-o imediatamente — visualizá-lo novamente forçará uma redefinição.
>
> Bots criados pela página de configuração rápida são inicialmente apenas para o criador e não suportam chats de grupo. Para habilitar o acesso em grupo, configure o modo sandbox na [QQ Open Platform](https://q.qq.com/).
```bash
picoclaw gateway
```
**Configuração manual**
Se preferir criar o bot manualmente:
* Faça login na [QQ Open Platform](https://q.qq.com/) para se registrar como desenvolvedor
* Crie um bot QQ — personalize seu avatar e nome
* Copie o **App ID** e o **App Secret** nas configurações do bot
* Configure conforme mostrado acima e execute `picoclaw gateway`
</details>
@ -229,8 +237,31 @@ picoclaw gateway
```bash
picoclaw gateway
```
</details>
<details>
<summary><b>MaixCam</b></summary>
Canal de integração projetado especificamente para hardware de câmera AI Sipeed.
```json
{
"channels": {
"maixcam": {
"enabled": true
}
}
}
```
```bash
picoclaw gateway
```
</details>
<details>
<summary><b>Matrix</b></summary>
@ -322,7 +353,7 @@ O PicoClaw suporta três tipos de integração WeCom:
**Opção 2: WeCom App (App Personalizado)** - Mais recursos, mensagens proativas, apenas chat privado
**Opção 3: WeCom AI Bot (AI Bot)** - AI Bot oficial, respostas em streaming, suporta chat de grupo e privado
Veja o [Guia de Configuração do WeCom AI Bot](../channels/wecom/wecom_aibot/README.zh.md) para instruções detalhadas de configuração.
Veja o [Guia de Configuração do WeCom AI Bot](../channels/wecom/wecom_aibot/README.pt-br.md) para instruções detalhadas de configuração.
**Configuração Rápida - WeCom Bot:**
@ -425,3 +456,169 @@ picoclaw gateway
> **Nota**: O WeCom AI Bot usa protocolo de streaming pull — sem preocupações com timeout de resposta. Tarefas longas (>30 segundos) mudam automaticamente para entrega via `response_url` push.
</details>
<details>
<summary><b>Feishu (Lark)</b></summary>
O PicoClaw se conecta ao Feishu via modo WebSocket/SDK — não é necessário URL de webhook público nem servidor de callback.
**1. Criar um aplicativo**
* Acesse a [Feishu Open Platform](https://open.feishu.cn/) e crie um aplicativo
* Nas configurações do aplicativo, habilite a capacidade **Bot**
* Crie uma versão e publique o aplicativo (o aplicativo deve ser publicado para funcionar)
* Copie o **App ID** (começa com `cli_`) e o **App Secret**
**2. Configurar**
```json
{
"channels": {
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
Opcional: `encrypt_key` e `verification_token` para criptografia de eventos (recomendado para produção).
**3. Executar e conversar**
```bash
picoclaw gateway
```
Abra o Feishu, pesquise o nome do seu bot e comece a conversar. Você também pode adicionar o bot a um grupo — use `group_trigger.mention_only: true` para responder apenas quando @mencionado.
Para opções completas, veja o [Guia de Configuração do Canal Feishu](../channels/feishu/README.pt-br.md).
</details>
<details>
<summary><b>Slack</b></summary>
**1. Criar um aplicativo Slack**
* Acesse a [Slack API](https://api.slack.com/apps) e crie um novo aplicativo
* Em **OAuth & Permissions**, adicione os escopos do bot: `chat:write`, `app_mentions:read`, `im:history`, `im:read`, `im:write`
* Instale o aplicativo no seu workspace
* Copie o **Bot Token** (`xoxb-...`) e o **App-Level Token** (`xapp-...`, habilite Socket Mode para obtê-lo)
**2. Configurar**
```json
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-YOUR-BOT-TOKEN",
"app_token": "xapp-YOUR-APP-TOKEN",
"allow_from": []
}
}
}
```
**3. Executar**
```bash
picoclaw gateway
```
</details>
<details>
<summary><b>IRC</b></summary>
**1. Configurar**
```json
{
"channels": {
"irc": {
"enabled": true,
"server": "irc.libera.chat:6697",
"tls": true,
"nick": "picoclaw-bot",
"channels": ["#your-channel"],
"password": "",
"allow_from": []
}
}
}
```
Opcional: `nickserv_password` para autenticação NickServ, `sasl_user`/`sasl_password` para autenticação SASL.
**2. Executar**
```bash
picoclaw gateway
```
O bot se conectará ao servidor IRC e entrará nos canais especificados.
</details>
<details>
<summary><b>OneBot (QQ via protocolo OneBot)</b></summary>
OneBot é um protocolo aberto para bots QQ. O PicoClaw se conecta a qualquer implementação compatível com OneBot v11 (ex.: [Lagrange](https://github.com/LagrangeDev/Lagrange.Core), [NapCat](https://github.com/NapNeko/NapCatQQ)) via WebSocket.
**1. Configurar uma implementação OneBot**
Instale e execute um framework de bot QQ compatível com OneBot v11. Habilite seu servidor WebSocket.
**2. Configurar**
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://127.0.0.1:8080",
"access_token": "",
"allow_from": []
}
}
}
```
| Campo | Descrição |
|-------|-----------|
| `ws_url` | URL WebSocket da implementação OneBot |
| `access_token` | Token de acesso para autenticação (se configurado no OneBot) |
| `reconnect_interval` | Intervalo de reconexão em segundos (padrão: 5) |
**3. Executar**
```bash
picoclaw gateway
```
</details>
<details>
<summary><b>MaixCam</b></summary>
Canal de integração projetado especificamente para hardware de câmera AI Sipeed.
```json
{
"channels": {
"maixcam": {
"enabled": true
}
}
}
```
```bash
picoclaw gateway
```
</details>

249
docs/vi/chat-apps.md
View file

@ -8,22 +8,22 @@ Trò chuyện với picoclaw của bạn qua Telegram, Discord, WhatsApp, Matrix
> **Lưu ý**: Tất cả các kênh dựa trên webhook (LINE, WeCom, v.v.) được phục vụ trên một máy chủ HTTP Gateway chung (`gateway.host`:`gateway.port`, mặc định `127.0.0.1:18790`). Không có port riêng cho từng kênh. Lưu ý: Feishu sử dụng chế độ WebSocket/SDK và không sử dụng máy chủ HTTP webhook chung.
| Channel | Setup |
| ------------ | ---------------------------------- |
| **Telegram** | Easy (just a token) |
| **Discord** | Easy (bot token + intents) |
| **WhatsApp** | Easy (native: QR scan; or bridge URL) |
| **Matrix** | Medium (homeserver + bot access token) |
| **QQ** | Easy (AppID + AppSecret) |
| **DingTalk** | Medium (app credentials) |
| **LINE** | Medium (credentials + webhook URL) |
| **WeCom AI Bot** | Medium (Token + AES key) |
| **Feishu** | Medium (App ID + Secret, WebSocket mode) |
| **Slack** | Medium (Bot token + App token) |
| **IRC** | Medium (server + TLS config) |
| **OneBot** | Medium (QQ via OneBot protocol) |
| **MaixCam** | Easy (Sipeed hardware integration) |
| **Pico** | Native PicoClaw protocol |
| Kênh | Độ khó | Mô tả | Tài liệu |
| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Telegram** | ⭐ Dễ | Khuyến nghị, chuyển giọng nói thành văn bản, long polling (không cần IP công khai) | [Tài liệu](../channels/telegram/README.vi.md) |
| **Discord** | ⭐ Dễ | Socket Mode, hỗ trợ nhóm/DM, hệ sinh thái bot phong phú | [Tài liệu](../channels/discord/README.vi.md) |
| **WhatsApp** | ⭐ Dễ | Bản địa (quét QR) hoặc Bridge URL | [Tài liệu](#whatsapp) |
| **Slack** | ⭐ Dễ | **Socket Mode** (không cần IP công khai), doanh nghiệp | [Tài liệu](../channels/slack/README.vi.md) |
| **Matrix** | ⭐⭐ Trung bình | Giao thức liên kết, hỗ trợ tự lưu trữ | [Tài liệu](../channels/matrix/README.vi.md) |
| **QQ** | ⭐⭐ Trung bình | API bot chính thức, cộng đồng Trung Quốc | [Tài liệu](../channels/qq/README.vi.md) |
| **DingTalk** | ⭐⭐ Trung bình | Chế độ Stream (không cần IP công khai), doanh nghiệp | [Tài liệu](../channels/dingtalk/README.vi.md) |
| **LINE** | ⭐⭐⭐ Nâng cao | Yêu cầu HTTPS Webhook | [Tài liệu](../channels/line/README.vi.md) |
| **WeCom (企业微信)** | ⭐⭐⭐ Nâng cao | Bot nhóm (Webhook), ứng dụng tùy chỉnh (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.vi.md) / [App](../channels/wecom/wecom_app/README.vi.md) / [AI Bot](../channels/wecom/wecom_aibot/README.vi.md) |
| **Feishu (飞书)** | ⭐⭐⭐ Nâng cao | Cộng tác doanh nghiệp, nhiều tính năng | [Tài liệu](../channels/feishu/README.vi.md) |
| **IRC** | ⭐⭐ Trung bình | Máy chủ + cấu hình TLS | - |
| **OneBot** | ⭐⭐ Trung bình | Tương thích NapCat/Go-CQHTTP, hệ sinh thái cộng đồng | [Tài liệu](../channels/onebot/README.vi.md) |
| **MaixCam** | ⭐ Dễ | Kênh tích hợp phần cứng cho camera AI Sipeed | [Tài liệu](../channels/maixcam/README.vi.md) |
| **Pico** | ⭐ Dễ | Kênh giao thức bản địa PicoClaw | |
<details>
<summary><b>Telegram</b> (Khuyến nghị)</summary>
@ -168,12 +168,13 @@ Nếu `session_store_path` trống, phiên được lưu tại `<workspace>/what
<details>
<summary><b>QQ</b></summary>
**1. Tạo bot**
**Thiết lập nhanh (khuyến nghị)**
- Truy cập [QQ Open Platform](https://q.qq.com/#)
- Tạo ứng dụng → Lấy **AppID** và **AppSecret**
QQ Open Platform cung cấp trang thiết lập một chạm cho bot tương thích OpenClaw:
**2. Cấu hình**
1. Mở [QQ Bot Quick Start](https://q.qq.com/qqbot/openclaw/index.html) và quét mã QR để đăng nhập
2. Bot được tạo tự động — sao chép **App ID** và **App Secret**
3. Cấu hình PicoClaw:
```json
{
@ -188,13 +189,20 @@ Nếu `session_store_path` trống, phiên được lưu tại `<workspace>/what
}
```
> Đặt `allow_from` trống để cho phép tất cả người dùng, hoặc chỉ định số QQ để giới hạn truy cập.
4. Chạy `picoclaw gateway` và mở QQ để trò chuyện với bot của bạn
**3. Chạy**
> App Secret chỉ hiển thị một lần. Lưu ngay lập tức — xem lại sẽ buộc phải đặt lại.
>
> Bot được tạo qua trang thiết lập nhanh ban đầu chỉ dành cho người tạo và không hỗ trợ chat nhóm. Để bật quyền truy cập nhóm, cấu hình chế độ sandbox trên [QQ Open Platform](https://q.qq.com/).
```bash
picoclaw gateway
```
**Thiết lập thủ công**
Nếu bạn muốn tạo bot thủ công:
* Đăng nhập tại [QQ Open Platform](https://q.qq.com/) để đăng ký làm nhà phát triển
* Tạo bot QQ — tùy chỉnh avatar và tên
* Sao chép **App ID** và **App Secret** từ cài đặt bot
* Cấu hình như trên và chạy `picoclaw gateway`
</details>
@ -229,8 +237,31 @@ picoclaw gateway
```bash
picoclaw gateway
```
</details>
<details>
<summary><b>MaixCam</b></summary>
Kênh tích hợp được thiết kế đặc biệt cho phần cứng camera AI Sipeed.
```json
{
"channels": {
"maixcam": {
"enabled": true
}
}
}
```
```bash
picoclaw gateway
```
</details>
<details>
<summary><b>Matrix</b></summary>
@ -322,7 +353,7 @@ PicoClaw hỗ trợ ba loại tích hợp WeCom:
**Tùy chọn 2: WeCom App (App Tùy chỉnh)** - Nhiều tính năng hơn, nhắn tin chủ động, chỉ chat riêng
**Tùy chọn 3: WeCom AI Bot (AI Bot)** - AI Bot chính thức, phản hồi streaming, hỗ trợ chat nhóm & riêng
Xem [Hướng Dẫn Cấu Hình WeCom AI Bot](../channels/wecom/wecom_aibot/README.zh.md) để biết hướng dẫn thiết lập chi tiết.
Xem [Hướng Dẫn Cấu Hình WeCom AI Bot](../channels/wecom/wecom_aibot/README.vi.md) để biết hướng dẫn thiết lập chi tiết.
**Thiết Lập Nhanh - WeCom Bot:**
@ -426,3 +457,169 @@ picoclaw gateway
> **Lưu ý**: WeCom AI Bot sử dụng giao thức streaming pull — không lo timeout phản hồi. Tác vụ dài (>30 giây) tự động chuyển sang gửi qua `response_url` push.
</details>
<details>
<summary><b>Feishu (Lark)</b></summary>
PicoClaw kết nối với Feishu qua chế độ WebSocket/SDK — không cần URL webhook công khai hay máy chủ callback.
**1. Tạo ứng dụng**
* Truy cập [Feishu Open Platform](https://open.feishu.cn/) và tạo ứng dụng
* Trong cài đặt ứng dụng, bật khả năng **Bot**
* Tạo phiên bản và xuất bản ứng dụng (ứng dụng phải được xuất bản mới có hiệu lực)
* Sao chép **App ID** (bắt đầu bằng `cli_`) và **App Secret**
**2. Cấu hình**
```json
{
"channels": {
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
Tùy chọn: `encrypt_key` và `verification_token` để mã hóa sự kiện (khuyến nghị cho môi trường production).
**3. Chạy và trò chuyện**
```bash
picoclaw gateway
```
Mở Feishu, tìm tên bot của bạn và bắt đầu trò chuyện. Bạn cũng có thể thêm bot vào nhóm — sử dụng `group_trigger.mention_only: true` để chỉ phản hồi khi được @mention.
Để xem đầy đủ các tùy chọn, xem [Hướng Dẫn Cấu Hình Kênh Feishu](../channels/feishu/README.vi.md).
</details>
<details>
<summary><b>Slack</b></summary>
**1. Tạo ứng dụng Slack**
* Truy cập [Slack API](https://api.slack.com/apps) và tạo ứng dụng mới
* Trong **OAuth & Permissions**, thêm các scope bot: `chat:write`, `app_mentions:read`, `im:history`, `im:read`, `im:write`
* Cài đặt ứng dụng vào workspace của bạn
* Sao chép **Bot Token** (`xoxb-...`) và **App-Level Token** (`xapp-...`, bật Socket Mode để lấy token này)
**2. Cấu hình**
```json
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-YOUR-BOT-TOKEN",
"app_token": "xapp-YOUR-APP-TOKEN",
"allow_from": []
}
}
}
```
**3. Chạy**
```bash
picoclaw gateway
```
</details>
<details>
<summary><b>IRC</b></summary>
**1. Cấu hình**
```json
{
"channels": {
"irc": {
"enabled": true,
"server": "irc.libera.chat:6697",
"tls": true,
"nick": "picoclaw-bot",
"channels": ["#your-channel"],
"password": "",
"allow_from": []
}
}
}
```
Tùy chọn: `nickserv_password` để xác thực NickServ, `sasl_user`/`sasl_password` để xác thực SASL.
**2. Chạy**
```bash
picoclaw gateway
```
Bot sẽ kết nối đến máy chủ IRC và tham gia các kênh đã chỉ định.
</details>
<details>
<summary><b>OneBot (QQ qua giao thức OneBot)</b></summary>
OneBot là giao thức mở cho bot QQ. PicoClaw kết nối với bất kỳ triển khai tương thích OneBot v11 nào (ví dụ: [Lagrange](https://github.com/LagrangeDev/Lagrange.Core), [NapCat](https://github.com/NapNeko/NapCatQQ)) qua WebSocket.
**1. Thiết lập triển khai OneBot**
Cài đặt và chạy framework bot QQ tương thích OneBot v11. Bật máy chủ WebSocket của nó.
**2. Cấu hình**
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://127.0.0.1:8080",
"access_token": "",
"allow_from": []
}
}
}
```
| Trường | Mô tả |
|--------|-------|
| `ws_url` | URL WebSocket của triển khai OneBot |
| `access_token` | Token truy cập để xác thực (nếu đã cấu hình trong OneBot) |
| `reconnect_interval` | Khoảng thời gian kết nối lại tính bằng giây (mặc định: 5) |
**3. Chạy**
```bash
picoclaw gateway
```
</details>
<details>
<summary><b>MaixCam</b></summary>
Kênh tích hợp được thiết kế đặc biệt cho phần cứng camera AI Sipeed.
```json
{
"channels": {
"maixcam": {
"enabled": true
}
}
}
```
```bash
picoclaw gateway
```
</details>

85
docs/zh/chat-apps.md
View file

@ -207,12 +207,13 @@ picoclaw gateway
<details>
<summary><b>QQ</b></summary>
**1. 创建 Bot**
**快速设置（推荐）**
- 前往 [QQ 开放平台](https://q.qq.com/#)
- 创建应用 → 获取 **AppID** 和 **AppSecret**
QQ 开放平台提供了一键创建 OpenClaw 兼容机器人的页面：
**2. 配置**
1. 打开 [QQ 机器人快速创建](https://q.qq.com/qqbot/openclaw/index.html)，扫码登录
2. 机器人自动创建 — 复制 **App ID** 和 **App Secret**
3. 配置 PicoClaw：
```json
{
@ -227,13 +228,20 @@ picoclaw gateway
}
```
> `allow_from` 留空表示允许所有用户，或指定 QQ 号限制访问。
4. 运行 `picoclaw gateway`，打开 QQ 与机器人聊天
**3. 运行**
> App Secret 仅显示一次，请立即保存 — 再次查看将强制重置。
>
> 通过快速创建页面创建的机器人初始仅限创建者使用，不支持群聊。如需启用群聊访问，请在 [QQ 开放平台](https://q.qq.com/) 配置沙箱模式。
```bash
picoclaw gateway
```
**手动设置**
如果你更喜欢手动创建机器人：
* 登录 [QQ 开放平台](https://q.qq.com/) 注册成为开发者
* 创建 QQ 机器人 — 自定义头像和名称
* 从机器人设置中复制 **App ID** 和 **App Secret**
* 按上述方式配置并运行 `picoclaw gateway`
</details>
@ -242,9 +250,10 @@ picoclaw gateway
**1. 创建 Slack App**
* 前往 [Slack API](https://api.slack.com/apps) 创建应用
* 启用 **Socket Mode**
* 获取 **Bot Token** 和 **App-Level Token**
* 前往 [Slack API](https://api.slack.com/apps) 创建新应用
* 在 **OAuth & Permissions** 中添加 Bot 权限范围：`chat:write`、`app_mentions:read`、`im:history`、`im:read`、`im:write`
* 将应用安装到你的工作区
* 复制 **Bot Token**（`xoxb-...`）和 **App-Level Token**（`xapp-...`，启用 Socket Mode 后获取）
**2. 配置**
@ -253,8 +262,8 @@ picoclaw gateway
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-YOUR_BOT_TOKEN",
"app_token": "xapp-YOUR_APP_TOKEN",
"bot_token": "xoxb-YOUR-BOT-TOKEN",
"app_token": "xapp-YOUR-APP-TOKEN",
"allow_from": []
}
}
@ -280,21 +289,26 @@ picoclaw gateway
"irc": {
"enabled": true,
"server": "irc.libera.chat:6697",
"nick": "picoclaw-bot",
"tls": true,
"nick": "picoclaw-bot",
"channels": ["#your-channel"],
"password": "",
"allow_from": []
}
}
}
```
可选：`nickserv_password` 用于 NickServ 认证，`sasl_user`/`sasl_password` 用于 SASL 认证。
**2. 运行**
```bash
picoclaw gateway
```
Bot 将连接到 IRC 服务器并加入指定的频道。
</details>
<details>
@ -382,11 +396,14 @@ picoclaw gateway
<details>
<summary><b>飞书 (Feishu)</b></summary>
PicoClaw 通过 WebSocket/SDK 模式连接飞书 — 无需公网 Webhook URL 或回调服务器。
**1. 创建应用**
* 前往 [飞书开放平台](https://open.feishu.cn/)
* 创建企业自建应用
* 获取 **App ID** 和 **App Secret**
* 前往 [飞书开放平台](https://open.feishu.cn/) 创建应用
* 在应用设置中启用 **机器人** 能力
* 创建版本并发布应用（应用必须发布后才能生效）
* 复制 **App ID**（以 `cli_` 开头）和 **App Secret**
**2. 配置**
@ -396,21 +413,25 @@ picoclaw gateway
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
**3. 运行**
可选：`encrypt_key` 和 `verification_token` 用于事件加密（生产环境推荐）。
**3. 运行并聊天**
```bash
picoclaw gateway
```
打开飞书，搜索你的机器人名称即可开始聊天。也可以将机器人添加到群组 — 使用 `group_trigger.mention_only: true` 设置为仅在 @提及时回复。
完整选项请参考 [飞书渠道配置指南](../channels/feishu/README.zh.md)。
</details>
<details>
@ -528,24 +549,36 @@ picoclaw gateway
</details>
<details>
<summary><b>OneBot</b></summary>
<summary><b>OneBot（通过 OneBot 协议连接 QQ）</b></summary>
**1. 配置**
OneBot 是 QQ 机器人的开放协议。PicoClaw 通过 WebSocket 连接任何 OneBot v11 兼容实现（如 [Lagrange](https://github.com/LagrangeDev/Lagrange.Core)、[NapCat](https://github.com/NapNeko/NapCatQQ)）。
兼容 NapCat / Go-CQHTTP 等 OneBot 实现。
**1. 设置 OneBot 实现**
安装并运行 OneBot v11 兼容的 QQ 机器人框架，启用其 WebSocket 服务器。
**2. 配置**
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://127.0.0.1:8080",
"access_token": "",
"allow_from": []
}
}
}
```
**2. 运行**
| 字段 | 说明 |
|------|------|
| `ws_url` | OneBot 实现的 WebSocket URL |
| `access_token` | 认证用的访问令牌（如果在 OneBot 中配置了的话） |
| `reconnect_interval` | 重连间隔（秒）（默认：5） |
**3. 运行**
```bash
picoclaw gateway