picoclaw/docs/guides/chat-apps.ms.md

💬 Konfigurasi Aplikasi Sembang

Kembali ke README

💬 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

Telegram (Disyorkan)

1. Cipta bot

• Buka Telegram, cari @BotFather
• Hantar /newbot, ikut arahan
• Salin token

2. Konfigurasi

{
  "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

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.

Discord

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

{
  "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:

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

Anda juga boleh mencetuskan dengan awalan kata kunci (contohnya !bot):

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

6. Jalankan

picoclaw gateway

WhatsApp (asli melalui whatsmeow)

PicoClaw boleh menyambung ke WhatsApp dalam dua cara:

• Asli (disyorkan): Dalam proses menggunakan 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)

{
  "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.

QQ

1. Cipta bot

• Pergi ke QQ Open Platform
• Cipta aplikasi → Dapatkan AppID dan AppSecret

2. Konfigurasi

{
  "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

picoclaw gateway

DingTalk

1. Cipta bot

• Pergi ke Open Platform
• Cipta aplikasi dalaman
• Salin Client ID dan Client Secret

2. Konfigurasi

{
  "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

picoclaw gateway

Matrix

1. Sediakan akaun bot

• Gunakan homeserver pilihan anda (contohnya https://matrix.org atau self-hosted)
• Cipta pengguna bot dan dapatkan access tokennya

2. Konfigurasi

{
  "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

picoclaw gateway

Untuk pilihan penuh (device_id, join_on_invite, group_trigger, placeholder, reasoning_channel_id), lihat Panduan Konfigurasi Saluran Matrix.

LINE

1. Cipta Akaun Rasmi LINE

• Pergi ke LINE Developers Console
• Cipta provider → Cipta saluran Messaging API
• Salin Channel Secret dan Channel Access Token

2. Konfigurasi

{
  "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:

# 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

picoclaw gateway

Dalam sembang kumpulan, bot hanya membalas apabila @disebut. Balasan akan memetik mesej asal.

WeCom (企业微信)

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 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

{
  "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

{
  "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

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

{
  "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

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.