mirror of
https://github.com/sipeed/picoclaw.git
synced 2026-06-12 18:08:54 +00:00
refactor(docs): reorganize docs by type and locale
This commit is contained in:
wenjie
@@ -0,0 +1,447 @@
|
||||
# 💬 Konfigurasi Aplikasi Sembang
|
||||
|
||||
> Kembali ke [README](../project/README.ms.md)
|
||||
|
||||
## 💬 Aplikasi Sembang
|
||||
|
||||
Berbual dengan picoclaw anda melalui Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, WeCom, Feishu, Slack, IRC, OneBot, MaixCam, atau Pico (protokol asli)
|
||||
|
||||
> **Nota**: Semua saluran berasaskan webhook (LINE, WeCom, dan sebagainya) diservis pada satu pelayan HTTP Gateway yang dikongsi (`gateway.host`:`gateway.port`, lalai `127.0.0.1:18790`). Tiada port khusus per saluran untuk dikonfigurasikan. Nota: Feishu menggunakan mod WebSocket/SDK dan tidak menggunakan pelayan HTTP webhook yang dikongsi.
|
||||
|
||||
| Saluran | Penyediaan |
|
||||
| ---------------- | ------------------------------------------ |
|
||||
| **Telegram** | Mudah (hanya token) |
|
||||
| **Discord** | Mudah (token bot + intents) |
|
||||
| **WhatsApp** | Mudah (asli: imbas QR; atau bridge URL) |
|
||||
| **Matrix** | Sederhana (homeserver + access token bot) |
|
||||
| **QQ** | Mudah (AppID + AppSecret) |
|
||||
| **DingTalk** | Sederhana (kelayakan aplikasi) |
|
||||
| **LINE** | Sederhana (kelayakan + webhook URL) |
|
||||
| **WeCom AI Bot** | Sederhana (Token + kunci AES) |
|
||||
| **Feishu** | Sederhana (App ID + Secret, mod WebSocket) |
|
||||
| **Slack** | Sederhana (Bot token + App token) |
|
||||
| **IRC** | Sederhana (pelayan + konfigurasi TLS) |
|
||||
| **OneBot** | Sederhana (QQ melalui protokol OneBot) |
|
||||
| **MaixCam** | Mudah (integrasi perkakasan Sipeed) |
|
||||
| **Pico** | Protokol PicoClaw asli |
|
||||
|
||||
<details>
|
||||
<summary><b>Telegram</b> (Disyorkan)</summary>
|
||||
|
||||
**1. Cipta bot**
|
||||
|
||||
* Buka Telegram, cari `@BotFather`
|
||||
* Hantar `/newbot`, ikut arahan
|
||||
* Salin token
|
||||
|
||||
**2. Konfigurasi**
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_list": {
|
||||
"telegram": {
|
||||
"enabled": true,
|
||||
"type": "telegram",
|
||||
"token": "YOUR_BOT_TOKEN",
|
||||
"allow_from": ["YOUR_USER_ID"],
|
||||
"use_markdown_v2": false,
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> Dapatkan user ID anda daripada `@userinfobot` di Telegram.
|
||||
|
||||
**3. Jalankan**
|
||||
|
||||
```bash
|
||||
picoclaw gateway
|
||||
```
|
||||
|
||||
**4. Menu arahan Telegram (auto-register semasa startup)**
|
||||
|
||||
PicoClaw kini menyimpan definisi arahan dalam satu registry bersama. Semasa startup, Telegram akan mendaftarkan arahan bot yang disokong secara automatik (contohnya `/start`, `/help`, `/show`, `/list`, `/use`, `/btw`) supaya menu arahan dan tingkah laku runtime sentiasa selari.
|
||||
Pendaftaran menu arahan Telegram kekal sebagai UX penemuan setempat saluran; pelaksanaan arahan generik dikendalikan secara berpusat dalam gelung agen melalui commands executor.
|
||||
|
||||
Jika pendaftaran arahan gagal (ralat sementara rangkaian/API), saluran tetap akan bermula dan PicoClaw akan mencuba semula pendaftaran di latar belakang.
|
||||
|
||||
Anda juga boleh mengurus skill yang dipasang terus dari Telegram:
|
||||
|
||||
- `/list skills`
|
||||
- `/use <skill> <message>`
|
||||
- `/use <skill>` kemudian hantar permintaan sebenar dalam mesej seterusnya
|
||||
- `/use clear`
|
||||
- `/btw <question>` untuk bertanya soalan sampingan segera tanpa mengubah sejarah sesi aktif; `/btw` dikendalikan sebagai pertanyaan langsung tanpa tool dan tidak memasuki aliran pelaksanaan tool biasa
|
||||
|
||||
**4. Pemformatan Lanjutan**
|
||||
Anda boleh menetapkan `use_markdown_v2: true` untuk mengaktifkan pilihan pemformatan yang lebih maju. Ini membolehkan bot menggunakan keseluruhan set ciri Telegram MarkdownV2, termasuk gaya bersarang, spoiler, dan blok lebar tetap tersuai.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Discord</b></summary>
|
||||
|
||||
**1. Cipta bot**
|
||||
|
||||
* Pergi ke <https://discord.com/developers/applications>
|
||||
* Cipta aplikasi → Bot → Add Bot
|
||||
* Salin token bot
|
||||
|
||||
**2. Aktifkan intents**
|
||||
|
||||
* Dalam tetapan Bot, aktifkan **MESSAGE CONTENT INTENT**
|
||||
* (Pilihan) Aktifkan **SERVER MEMBERS INTENT** jika anda bercadang menggunakan allow list berasaskan data ahli
|
||||
|
||||
**3. Dapatkan User ID anda**
|
||||
* Discord Settings → Advanced → aktifkan **Developer Mode**
|
||||
* Klik kanan avatar anda → **Copy User ID**
|
||||
|
||||
**4. Konfigurasi**
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_list": {
|
||||
"discord": {
|
||||
"enabled": true,
|
||||
"type": "discord",
|
||||
"token": "YOUR_BOT_TOKEN",
|
||||
"allow_from": ["YOUR_USER_ID"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**5. Jemput bot**
|
||||
|
||||
* OAuth2 → URL Generator
|
||||
* Scopes: `bot`
|
||||
* Bot Permissions: `Send Messages`, `Read Message History`
|
||||
* Buka URL jemputan yang dijana dan tambahkan bot ke pelayan anda
|
||||
|
||||
**Pilihan: Mod trigger kumpulan**
|
||||
|
||||
Secara lalai bot membalas semua mesej dalam saluran pelayan. Untuk mengehadkan balasan kepada @mention sahaja, tambah:
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_list": {
|
||||
"discord": {
|
||||
"group_trigger": { "mention_only": true }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Anda juga boleh mencetuskan dengan awalan kata kunci (contohnya `!bot`):
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_list": {
|
||||
"discord": {
|
||||
"group_trigger": { "prefixes": ["!bot"] }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**6. Jalankan**
|
||||
|
||||
```bash
|
||||
picoclaw gateway
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>WhatsApp</b> (asli melalui whatsmeow)</summary>
|
||||
|
||||
PicoClaw boleh menyambung ke WhatsApp dalam dua cara:
|
||||
|
||||
- **Asli (disyorkan):** Dalam proses menggunakan [whatsmeow](https://github.com/tulir/whatsmeow). Tiada bridge berasingan. Tetapkan `"use_native": true` dan biarkan `bridge_url` kosong. Pada larian pertama, imbas kod QR dengan WhatsApp (Linked Devices). Sesi disimpan di bawah workspace anda (contohnya `workspace/whatsapp/`). Saluran asli ini adalah **pilihan** untuk memastikan binari lalai kekal kecil; bina dengan `-tags whatsapp_native` (contohnya `make build-whatsapp-native` atau `go build -tags whatsapp_native ./cmd/...`).
|
||||
- **Bridge:** Sambung ke bridge WebSocket luaran. Tetapkan `bridge_url` (contohnya `ws://localhost:3001`) dan biarkan `use_native` sebagai false.
|
||||
|
||||
**Konfigurasi (asli)**
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_list": {
|
||||
"whatsapp": {
|
||||
"enabled": true,
|
||||
"type": "whatsapp",
|
||||
"use_native": true,
|
||||
"session_store_path": "",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Jika `session_store_path` kosong, sesi akan disimpan dalam `<workspace>/whatsapp/`. Jalankan `picoclaw gateway`; pada larian pertama, imbas kod QR yang dipaparkan dalam terminal menggunakan WhatsApp → Linked Devices.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>QQ</b></summary>
|
||||
|
||||
**1. Cipta bot**
|
||||
|
||||
- Pergi ke [QQ Open Platform](https://q.qq.com/#)
|
||||
- Cipta aplikasi → Dapatkan **AppID** dan **AppSecret**
|
||||
|
||||
**2. Konfigurasi**
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_list": {
|
||||
"qq": {
|
||||
"enabled": true,
|
||||
"type": "qq",
|
||||
"app_id": "YOUR_APP_ID",
|
||||
"app_secret": "YOUR_APP_SECRET",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> Tetapkan `allow_from` kepada kosong untuk membenarkan semua pengguna, atau nyatakan nombor QQ untuk mengehadkan akses.
|
||||
|
||||
**3. Jalankan**
|
||||
|
||||
```bash
|
||||
picoclaw gateway
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>DingTalk</b></summary>
|
||||
|
||||
**1. Cipta bot**
|
||||
|
||||
* Pergi ke [Open Platform](https://open.dingtalk.com/)
|
||||
* Cipta aplikasi dalaman
|
||||
* Salin Client ID dan Client Secret
|
||||
|
||||
**2. Konfigurasi**
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_list": {
|
||||
"dingtalk": {
|
||||
"enabled": true,
|
||||
"type": "dingtalk",
|
||||
"client_id": "YOUR_CLIENT_ID",
|
||||
"client_secret": "YOUR_CLIENT_SECRET",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> Tetapkan `allow_from` kepada kosong untuk membenarkan semua pengguna, atau nyatakan user ID DingTalk untuk mengehadkan akses.
|
||||
|
||||
**3. Jalankan**
|
||||
|
||||
```bash
|
||||
picoclaw gateway
|
||||
```
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Matrix</b></summary>
|
||||
|
||||
**1. Sediakan akaun bot**
|
||||
|
||||
* Gunakan homeserver pilihan anda (contohnya `https://matrix.org` atau self-hosted)
|
||||
* Cipta pengguna bot dan dapatkan access tokennya
|
||||
|
||||
**2. Konfigurasi**
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_list": {
|
||||
"matrix": {
|
||||
"enabled": true,
|
||||
"type": "matrix",
|
||||
"homeserver": "https://matrix.org",
|
||||
"user_id": "@your-bot:matrix.org",
|
||||
"access_token": "YOUR_MATRIX_ACCESS_TOKEN",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**3. Jalankan**
|
||||
|
||||
```bash
|
||||
picoclaw gateway
|
||||
```
|
||||
|
||||
Untuk pilihan penuh (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), lihat [Panduan Konfigurasi Saluran Matrix](../channels/matrix/README.md).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>LINE</b></summary>
|
||||
|
||||
**1. Cipta Akaun Rasmi LINE**
|
||||
|
||||
- Pergi ke [LINE Developers Console](https://developers.line.biz/)
|
||||
- Cipta provider → Cipta saluran Messaging API
|
||||
- Salin **Channel Secret** dan **Channel Access Token**
|
||||
|
||||
**2. Konfigurasi**
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_list": {
|
||||
"line": {
|
||||
"enabled": true,
|
||||
"type": "line",
|
||||
"channel_secret": "YOUR_CHANNEL_SECRET",
|
||||
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
|
||||
"webhook_path": "/webhook/line",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> Webhook LINE diservis pada pelayan Gateway yang dikongsi (`gateway.host`:`gateway.port`, lalai `127.0.0.1:18790`).
|
||||
|
||||
**3. Tetapkan Webhook URL**
|
||||
|
||||
LINE memerlukan HTTPS untuk webhook. Gunakan reverse proxy atau tunnel:
|
||||
|
||||
```bash
|
||||
# Contoh dengan ngrok (port lalai gateway ialah 18790)
|
||||
ngrok http 18790
|
||||
```
|
||||
|
||||
Kemudian tetapkan Webhook URL dalam LINE Developers Console kepada `https://your-domain/webhook/line` dan aktifkan **Use webhook**.
|
||||
|
||||
**4. Jalankan**
|
||||
|
||||
```bash
|
||||
picoclaw gateway
|
||||
```
|
||||
|
||||
> Dalam sembang kumpulan, bot hanya membalas apabila @disebut. Balasan akan memetik mesej asal.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>WeCom (企业微信)</b></summary>
|
||||
|
||||
PicoClaw menyokong tiga jenis integrasi WeCom:
|
||||
|
||||
**Pilihan 1: WeCom Bot (Bot)** - Penyediaan lebih mudah, menyokong sembang kumpulan
|
||||
**Pilihan 2: WeCom App (Custom App)** - Lebih banyak ciri, pemesejan proaktif, sembang peribadi sahaja
|
||||
**Pilihan 3: WeCom AI Bot (AI Bot)** - AI Bot rasmi, balasan streaming, menyokong sembang kumpulan & peribadi
|
||||
|
||||
Lihat [Panduan Konfigurasi WeCom](../channels/wecom/README.zh.md) untuk arahan penyediaan terperinci.
|
||||
|
||||
**Quick Setup - WeCom Bot:**
|
||||
|
||||
**1. Cipta bot**
|
||||
|
||||
* Pergi ke WeCom Admin Console → Group Chat → Add Group Bot
|
||||
* Salin webhook URL (format: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
|
||||
|
||||
**2. Konfigurasi**
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_list": {
|
||||
"wecom": {
|
||||
"enabled": true,
|
||||
"type": "wecom",
|
||||
"token": "YOUR_TOKEN",
|
||||
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
|
||||
"webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
|
||||
"webhook_path": "/webhook/wecom",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> Webhook WeCom diservis pada pelayan Gateway yang dikongsi (`gateway.host`:`gateway.port`, lalai `127.0.0.1:18790`).
|
||||
|
||||
**Quick Setup - WeCom App:**
|
||||
|
||||
**1. Cipta aplikasi**
|
||||
|
||||
* Pergi ke WeCom Admin Console → App Management → Create App
|
||||
* Salin **AgentId** dan **Secret**
|
||||
* Pergi ke halaman "My Company", salin **CorpID**
|
||||
|
||||
**2. Konfigurasi penerimaan mesej**
|
||||
|
||||
* Dalam butiran aplikasi, klik "Receive Message" → "Set API"
|
||||
* Tetapkan URL kepada `http://your-server:18790/webhook/wecom-app`
|
||||
* Jana **Token** dan **EncodingAESKey**
|
||||
|
||||
**3. Konfigurasi**
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_list": {
|
||||
"wecom_app": {
|
||||
"enabled": true,
|
||||
"corp_id": "wwxxxxxxxxxxxxxxxx",
|
||||
"corp_secret": "YOUR_CORP_SECRET",
|
||||
"agent_id": 1000002,
|
||||
"token": "YOUR_TOKEN",
|
||||
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
|
||||
"webhook_path": "/webhook/wecom-app",
|
||||
"allow_from": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**4. Jalankan**
|
||||
|
||||
```bash
|
||||
picoclaw gateway
|
||||
```
|
||||
|
||||
> **Nota**: Callback webhook WeCom diservis pada port Gateway (lalai 18790). Gunakan reverse proxy untuk HTTPS.
|
||||
|
||||
**Quick Setup - WeCom AI Bot:**
|
||||
|
||||
**1. Cipta AI Bot**
|
||||
|
||||
* Pergi ke WeCom Admin Console → App Management → AI Bot
|
||||
* Dalam tetapan AI Bot, konfigurasikan callback URL: `http://your-server:18791/webhook/wecom-aibot`
|
||||
* Salin **Token** dan klik "Random Generate" untuk **EncodingAESKey**
|
||||
|
||||
**2. Konfigurasi**
|
||||
|
||||
```json
|
||||
{
|
||||
"channel_list": {
|
||||
"wecom_aibot": {
|
||||
"enabled": true,
|
||||
"token": "YOUR_TOKEN",
|
||||
"encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
|
||||
"webhook_path": "/webhook/wecom-aibot",
|
||||
"allow_from": [],
|
||||
"welcome_message": "Hello! How can I help you?"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**3. Jalankan**
|
||||
|
||||
```bash
|
||||
picoclaw gateway
|
||||
```
|
||||
|
||||
> **Nota**: WeCom AI Bot menggunakan protokol streaming pull — tiada isu timeout balasan. Tugasan panjang (>30 saat) akan bertukar secara automatik kepada penghantaran push `response_url`.
|
||||
|
||||
</details>
|
||||
Reference in New Issue
Block a user