mirror of
https://github.com/sipeed/picoclaw.git
synced 2026-06-12 18:08:54 +00:00
Merge branch 'main' into version
This commit is contained in:
Cytown
@@ -0,0 +1,64 @@
|
||||
> Retour au [README](../../../README.fr.md)
|
||||
|
||||
# Guide de configuration du canal Matrix
|
||||
|
||||
## 1. Exemple de configuration
|
||||
|
||||
Ajoutez ceci à `config.json` :
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"matrix": {
|
||||
"enabled": true,
|
||||
"homeserver": "https://matrix.org",
|
||||
"user_id": "@your-bot:matrix.org",
|
||||
"access_token": "YOUR_MATRIX_ACCESS_TOKEN",
|
||||
"device_id": "",
|
||||
"join_on_invite": true,
|
||||
"allow_from": [],
|
||||
"group_trigger": {
|
||||
"mention_only": true
|
||||
},
|
||||
"placeholder": {
|
||||
"enabled": true,
|
||||
"text": "Thinking..."
|
||||
},
|
||||
"reasoning_channel_id": "",
|
||||
"message_format": "richtext"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Référence des champs
|
||||
|
||||
| Champ | Type | Requis | Description |
|
||||
|----------------------|----------|--------|-------------|
|
||||
| enabled | bool | Oui | Activer ou désactiver le canal Matrix |
|
||||
| homeserver | string | Oui | URL du homeserver Matrix (par exemple `https://matrix.org`) |
|
||||
| user_id | string | Oui | ID utilisateur Matrix du bot (par exemple `@bot:matrix.org`) |
|
||||
| access_token | string | Oui | Jeton d'accès du bot |
|
||||
| device_id | string | Non | ID d'appareil Matrix optionnel |
|
||||
| join_on_invite | bool | Non | Rejoindre automatiquement les salons invités |
|
||||
| allow_from | []string | Non | Liste blanche d'utilisateurs (IDs Matrix) |
|
||||
| group_trigger | object | Non | Stratégie de déclenchement de groupe (`mention_only` / `prefixes`) |
|
||||
| placeholder | object | Non | Configuration du message de remplacement |
|
||||
| reasoning_channel_id | string | Non | Canal cible pour la sortie de raisonnement |
|
||||
| message_format | string | Non | Format de sortie : `"richtext"` (défaut) rend le markdown en HTML ; `"plain"` envoie du texte brut uniquement |
|
||||
|
||||
## 3. Fonctionnalités actuellement supportées
|
||||
|
||||
- Envoi/réception de messages texte avec rendu markdown (gras, italique, titres, blocs de code, etc.)
|
||||
- Format de message configurable (`richtext` / `plain`)
|
||||
- Téléchargement d'images/audio/vidéo/fichiers entrants (MediaStore en priorité, chemin local en secours)
|
||||
- Normalisation de l'audio entrant dans le flux de transcription existant (`[audio: ...]`)
|
||||
- Upload et envoi d'images/audio/vidéo/fichiers sortants
|
||||
- Règles de déclenchement de groupe (y compris le mode mention uniquement)
|
||||
- État de frappe (`m.typing`)
|
||||
- Message de remplacement + remplacement de la réponse finale
|
||||
- Rejoindre automatiquement les salons invités (peut être désactivé)
|
||||
|
||||
## 4. TODO
|
||||
|
||||
- Améliorations des métadonnées des médias riches (par exemple taille et miniatures des images/vidéos)
|
||||
@@ -0,0 +1,64 @@
|
||||
> [README](../../../README.ja.md) に戻る
|
||||
|
||||
# Matrix チャンネル設定ガイド
|
||||
|
||||
## 1. 設定例
|
||||
|
||||
`config.json` に以下を追加してください：
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"matrix": {
|
||||
"enabled": true,
|
||||
"homeserver": "https://matrix.org",
|
||||
"user_id": "@your-bot:matrix.org",
|
||||
"access_token": "YOUR_MATRIX_ACCESS_TOKEN",
|
||||
"device_id": "",
|
||||
"join_on_invite": true,
|
||||
"allow_from": [],
|
||||
"group_trigger": {
|
||||
"mention_only": true
|
||||
},
|
||||
"placeholder": {
|
||||
"enabled": true,
|
||||
"text": "Thinking..."
|
||||
},
|
||||
"reasoning_channel_id": "",
|
||||
"message_format": "richtext"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. フィールドリファレンス
|
||||
|
||||
| フィールド | 型 | 必須 | 説明 |
|
||||
|----------------------|----------|------|------|
|
||||
| enabled | bool | はい | Matrix チャンネルの有効/無効 |
|
||||
| homeserver | string | はい | Matrix ホームサーバー URL（例：`https://matrix.org`） |
|
||||
| user_id | string | はい | ボットの Matrix ユーザー ID（例：`@bot:matrix.org`） |
|
||||
| access_token | string | はい | ボットのアクセストークン |
|
||||
| device_id | string | いいえ | オプションの Matrix デバイス ID |
|
||||
| join_on_invite | bool | いいえ | 招待されたルームに自動参加 |
|
||||
| allow_from | []string | いいえ | ユーザーホワイトリスト（Matrix ユーザー ID） |
|
||||
| group_trigger | object | いいえ | グループトリガー戦略（`mention_only` / `prefixes`） |
|
||||
| placeholder | object | いいえ | プレースホルダーメッセージ設定 |
|
||||
| reasoning_channel_id | string | いいえ | 推論出力のターゲットチャンネル |
|
||||
| message_format | string | いいえ | 出力形式：`"richtext"`（デフォルト）は markdown を HTML としてレンダリング；`"plain"` はプレーンテキストのみ送信 |
|
||||
|
||||
## 3. 現在サポートされている機能
|
||||
|
||||
- markdown レンダリング付きテキストメッセージ送受信（太字、斜体、見出し、コードブロックなど）
|
||||
- 設定可能なメッセージ形式（`richtext` / `plain`）
|
||||
- 受信画像/音声/動画/ファイルのダウンロード（MediaStore 優先、ローカルパスフォールバック）
|
||||
- 受信音声の既存文字起こしフローへの正規化（`[audio: ...]`）
|
||||
- 送信画像/音声/動画/ファイルのアップロードと送信
|
||||
- グループトリガールール（メンションのみモードを含む）
|
||||
- タイピング状態（`m.typing`）
|
||||
- プレースホルダーメッセージ + 最終返信の置き換え
|
||||
- 招待されたルームへの自動参加（無効化可能）
|
||||
|
||||
## 4. TODO
|
||||
|
||||
- リッチメディアメタデータの改善（例：画像/動画のサイズとサムネイル）
|
||||
@@ -1,3 +1,5 @@
|
||||
> Back to [README](../../../README.md)
|
||||
|
||||
# Matrix Channel Configuration Guide
|
||||
|
||||
## 1. Example Configuration
|
||||
|
||||
@@ -0,0 +1,64 @@
|
||||
> Voltar ao [README](../../../README.pt-br.md)
|
||||
|
||||
# Guia de Configuração do Canal Matrix
|
||||
|
||||
## 1. Exemplo de Configuração
|
||||
|
||||
Adicione isto ao `config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"matrix": {
|
||||
"enabled": true,
|
||||
"homeserver": "https://matrix.org",
|
||||
"user_id": "@your-bot:matrix.org",
|
||||
"access_token": "YOUR_MATRIX_ACCESS_TOKEN",
|
||||
"device_id": "",
|
||||
"join_on_invite": true,
|
||||
"allow_from": [],
|
||||
"group_trigger": {
|
||||
"mention_only": true
|
||||
},
|
||||
"placeholder": {
|
||||
"enabled": true,
|
||||
"text": "Thinking..."
|
||||
},
|
||||
"reasoning_channel_id": "",
|
||||
"message_format": "richtext"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Referência de Campos
|
||||
|
||||
| Campo | Tipo | Obrigatório | Descrição |
|
||||
|----------------------|----------|-------------|-----------|
|
||||
| enabled | bool | Sim | Habilitar ou desabilitar o canal Matrix |
|
||||
| homeserver | string | Sim | URL do homeserver Matrix (por exemplo `https://matrix.org`) |
|
||||
| user_id | string | Sim | ID de usuário Matrix do bot (por exemplo `@bot:matrix.org`) |
|
||||
| access_token | string | Sim | Token de acesso do bot |
|
||||
| device_id | string | Não | ID de dispositivo Matrix opcional |
|
||||
| join_on_invite | bool | Não | Entrar automaticamente em salas convidadas |
|
||||
| allow_from | []string | Não | Lista branca de usuários (IDs Matrix) |
|
||||
| group_trigger | object | Não | Estratégia de gatilho de grupo (`mention_only` / `prefixes`) |
|
||||
| placeholder | object | Não | Configuração de mensagem de espaço reservado |
|
||||
| reasoning_channel_id | string | Não | Canal alvo para saída de raciocínio |
|
||||
| message_format | string | Não | Formato de saída: `"richtext"` (padrão) renderiza markdown como HTML; `"plain"` envia apenas texto simples |
|
||||
|
||||
## 3. Suporte Atual
|
||||
|
||||
- Envio/recebimento de mensagens de texto com renderização markdown (negrito, itálico, cabeçalhos, blocos de código, etc.)
|
||||
- Formato de mensagem configurável (`richtext` / `plain`)
|
||||
- Download de imagens/áudio/vídeo/arquivos recebidos (MediaStore primeiro, fallback para caminho local)
|
||||
- Normalização de áudio recebido no fluxo de transcrição existente (`[audio: ...]`)
|
||||
- Upload e envio de imagens/áudio/vídeo/arquivos de saída
|
||||
- Regras de gatilho de grupo (incluindo modo somente menção)
|
||||
- Estado de digitação (`m.typing`)
|
||||
- Mensagem de espaço reservado + substituição de resposta final
|
||||
- Entrada automática em salas convidadas (pode ser desabilitado)
|
||||
|
||||
## 4. TODO
|
||||
|
||||
- Melhorias nos metadados de mídia rica (por exemplo tamanho e miniaturas de imagens/vídeos)
|
||||
@@ -0,0 +1,64 @@
|
||||
> Quay lại [README](../../../README.vi.md)
|
||||
|
||||
# Hướng dẫn Cấu hình Kênh Matrix
|
||||
|
||||
## 1. Cấu hình Mẫu
|
||||
|
||||
Thêm vào `config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"matrix": {
|
||||
"enabled": true,
|
||||
"homeserver": "https://matrix.org",
|
||||
"user_id": "@your-bot:matrix.org",
|
||||
"access_token": "YOUR_MATRIX_ACCESS_TOKEN",
|
||||
"device_id": "",
|
||||
"join_on_invite": true,
|
||||
"allow_from": [],
|
||||
"group_trigger": {
|
||||
"mention_only": true
|
||||
},
|
||||
"placeholder": {
|
||||
"enabled": true,
|
||||
"text": "Thinking..."
|
||||
},
|
||||
"reasoning_channel_id": "",
|
||||
"message_format": "richtext"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Tham chiếu Trường
|
||||
|
||||
| Trường | Kiểu | Bắt buộc | Mô tả |
|
||||
|----------------------|----------|----------|-------|
|
||||
| enabled | bool | Có | Bật hoặc tắt kênh Matrix |
|
||||
| homeserver | string | Có | URL homeserver Matrix (ví dụ `https://matrix.org`) |
|
||||
| user_id | string | Có | ID người dùng Matrix của bot (ví dụ `@bot:matrix.org`) |
|
||||
| access_token | string | Có | Token truy cập của bot |
|
||||
| device_id | string | Không | ID thiết bị Matrix tùy chọn |
|
||||
| join_on_invite | bool | Không | Tự động tham gia phòng được mời |
|
||||
| allow_from | []string | Không | Danh sách trắng người dùng (ID Matrix) |
|
||||
| group_trigger | object | Không | Chiến lược kích hoạt nhóm (`mention_only` / `prefixes`) |
|
||||
| placeholder | object | Không | Cấu hình tin nhắn giữ chỗ |
|
||||
| reasoning_channel_id | string | Không | Kênh đích cho đầu ra suy luận |
|
||||
| message_format | string | Không | Định dạng đầu ra: `"richtext"` (mặc định) render markdown thành HTML; `"plain"` chỉ gửi văn bản thuần |
|
||||
|
||||
## 3. Tính năng Hiện tại
|
||||
|
||||
- Gửi/nhận tin nhắn văn bản với render markdown (đậm, nghiêng, tiêu đề, khối code, v.v.)
|
||||
- Định dạng tin nhắn có thể cấu hình (`richtext` / `plain`)
|
||||
- Tải xuống hình ảnh/âm thanh/video/tệp đến (MediaStore trước, fallback đường dẫn cục bộ)
|
||||
- Chuẩn hóa âm thanh đến vào luồng phiên âm hiện có (`[audio: ...]`)
|
||||
- Tải lên và gửi hình ảnh/âm thanh/video/tệp đi
|
||||
- Quy tắc kích hoạt nhóm (bao gồm chế độ chỉ đề cập)
|
||||
- Trạng thái đang gõ (`m.typing`)
|
||||
- Tin nhắn giữ chỗ + thay thế phản hồi cuối cùng
|
||||
- Tự động tham gia phòng được mời (có thể tắt)
|
||||
|
||||
## 4. TODO
|
||||
|
||||
- Cải thiện metadata phương tiện phong phú (ví dụ kích thước và hình thu nhỏ hình ảnh/video)
|
||||
@@ -1,3 +1,5 @@
|
||||
> 返回 [README](../../../README.zh.md)
|
||||
|
||||
# Matrix 通道配置指南
|
||||
|
||||
## 1. 配置示例
|
||||
|
||||
+29
-14
@@ -10,22 +10,23 @@ Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk,
|
||||
|
||||
| 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) |
|
||||
| **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) |
|
||||
| **Weixin** | ⭐ Easy | Native QR scan (Tencent iLink API) | [Docs](../channels/weixin/README.md) |
|
||||
| **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) |
|
||||
| **Weixin** | ⭐ Easy | Native QR scan (Tencent iLink API) | [Docs](#weixin) |
|
||||
| **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 | [Docs](#irc) |
|
||||
| **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 | |
|
||||
|
||||
<a id="telegram"></a>
|
||||
<details>
|
||||
<summary><b>Telegram</b> (Recommended)</summary>
|
||||
|
||||
@@ -44,7 +45,7 @@ Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk,
|
||||
"enabled": true,
|
||||
"token": "YOUR_BOT_TOKEN",
|
||||
"allow_from": ["YOUR_USER_ID"],
|
||||
"use_markdown_v2": false,
|
||||
"use_markdown_v2": false
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -70,6 +71,7 @@ You can set use_markdown_v2: true to enable enhanced formatting options. This al
|
||||
|
||||
</details>
|
||||
|
||||
<a id="discord"></a>
|
||||
<details>
|
||||
<summary><b>Discord</b></summary>
|
||||
|
||||
@@ -143,6 +145,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="whatsapp"></a>
|
||||
<details>
|
||||
<summary><b>WhatsApp</b> (native via whatsmeow)</summary>
|
||||
|
||||
@@ -170,12 +173,14 @@ If `session_store_path` is empty, the session is stored in `<workspace>/whatsapp
|
||||
|
||||
</details>
|
||||
|
||||
<a id="weixin"></a>
|
||||
<details>
|
||||
<summary><b>Weixin</b> (WeChat Personal)</summary>
|
||||
|
||||
PicoClaw supports connecting to your personal WeChat account using the official Tencent iLink API.
|
||||
|
||||
**1. Login**
|
||||
|
||||
Run the interactive QR login flow:
|
||||
```bash
|
||||
picoclaw onboard weixin
|
||||
@@ -183,6 +188,7 @@ picoclaw onboard weixin
|
||||
Scan the printed QR code with your WeChat mobile app. On success, the token is saved to your config.
|
||||
|
||||
**2. Configure**
|
||||
|
||||
(Optional) Update `allow_from` with your WeChat User ID to restrict who can message the bot:
|
||||
```json
|
||||
{
|
||||
@@ -203,6 +209,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="qq"></a>
|
||||
<details>
|
||||
<summary><b>QQ</b></summary>
|
||||
|
||||
@@ -244,6 +251,7 @@ If you prefer to create the bot manually:
|
||||
|
||||
</details>
|
||||
|
||||
<a id="dingtalk"></a>
|
||||
<details>
|
||||
<summary><b>DingTalk</b></summary>
|
||||
|
||||
@@ -277,6 +285,7 @@ picoclaw gateway
|
||||
```
|
||||
</details>
|
||||
|
||||
<a id="matrix"></a>
|
||||
<details>
|
||||
<summary><b>Matrix</b></summary>
|
||||
|
||||
@@ -311,6 +320,7 @@ For full options (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`,
|
||||
|
||||
</details>
|
||||
|
||||
<a id="line"></a>
|
||||
<details>
|
||||
<summary><b>LINE</b></summary>
|
||||
|
||||
@@ -359,6 +369,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="wecom"></a>
|
||||
<details>
|
||||
<summary><b>WeCom (企业微信)</b></summary>
|
||||
|
||||
@@ -473,6 +484,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="feishu"></a>
|
||||
<details>
|
||||
<summary><b>Feishu (Lark)</b></summary>
|
||||
|
||||
@@ -514,6 +526,7 @@ For full options, see [Feishu Channel Configuration Guide](channels/feishu/READM
|
||||
|
||||
</details>
|
||||
|
||||
<a id="slack"></a>
|
||||
<details>
|
||||
<summary><b>Slack</b></summary>
|
||||
|
||||
@@ -547,6 +560,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="irc"></a>
|
||||
<details>
|
||||
<summary><b>IRC</b></summary>
|
||||
|
||||
@@ -580,6 +594,7 @@ The bot will connect to the IRC server and join the specified channels.
|
||||
|
||||
</details>
|
||||
|
||||
<a id="onebot"></a>
|
||||
<details>
|
||||
<summary><b>OneBot (QQ via OneBot protocol)</b></summary>
|
||||
|
||||
|
||||
@@ -347,3 +347,396 @@ For long-running tasks (web search, API calls), use the `spawn` tool to create a
|
||||
|
||||
```markdown
|
||||
# Periodic Tasks
|
||||
|
||||
## Quick Tasks (respond directly)
|
||||
|
||||
- Report current time
|
||||
|
||||
## Long Tasks (use spawn for async)
|
||||
|
||||
- Search the web for AI news and summarize
|
||||
- Check email and report important messages
|
||||
```
|
||||
|
||||
**Key behaviors:**
|
||||
|
||||
| Feature | Description |
|
||||
| ----------------------- | --------------------------------------------------------- |
|
||||
| **spawn** | Creates async subagent, doesn't block heartbeat |
|
||||
| **Independent context** | Subagent has its own context, no session history |
|
||||
| **message tool** | Subagent communicates with user directly via message tool |
|
||||
| **Non-blocking** | After spawning, heartbeat continues to next task |
|
||||
|
||||
#### How Subagent Communication Works
|
||||
|
||||
```
|
||||
Heartbeat triggers
|
||||
↓
|
||||
Agent reads HEARTBEAT.md
|
||||
↓
|
||||
For long task: spawn subagent
|
||||
↓ ↓
|
||||
Continue to next task Subagent works independently
|
||||
↓ ↓
|
||||
All tasks done Subagent uses "message" tool
|
||||
↓ ↓
|
||||
Respond HEARTBEAT_OK User receives result directly
|
||||
```
|
||||
|
||||
The subagent has access to tools (message, web_search, etc.) and can communicate with the user independently without going through the main agent.
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```json
|
||||
{
|
||||
"heartbeat": {
|
||||
"enabled": true,
|
||||
"interval": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Option | Default | Description |
|
||||
| ---------- | ------- | ---------------------------------- |
|
||||
| `enabled` | `true` | Enable/disable heartbeat |
|
||||
| `interval` | `30` | Check interval in minutes (min: 5) |
|
||||
|
||||
**Environment variables:**
|
||||
|
||||
* `PICOCLAW_HEARTBEAT_ENABLED=false` to disable
|
||||
* `PICOCLAW_HEARTBEAT_INTERVAL=60` to change interval
|
||||
|
||||
### Providers
|
||||
|
||||
> [!NOTE]
|
||||
> Groq provides free voice transcription via Whisper. If configured, audio messages from any channel will be automatically transcribed at the agent level.
|
||||
|
||||
| Provider | Purpose | Get API Key |
|
||||
| ------------ | --------------------------------------- | ------------------------------------------------------------ |
|
||||
| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) |
|
||||
| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](https://bigmodel.cn) |
|
||||
| `volcengine` | LLM (Volcengine direct) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
|
||||
| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) |
|
||||
| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) |
|
||||
| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) |
|
||||
| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) |
|
||||
| `qwen` | LLM (Qwen direct) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
|
||||
| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) |
|
||||
| `cerebras` | LLM (Cerebras direct) | [cerebras.ai](https://cerebras.ai) |
|
||||
| `vivgrid` | LLM (Vivgrid direct) | [vivgrid.com](https://vivgrid.com) |
|
||||
|
||||
### Model Configuration (model_list)
|
||||
|
||||
> **What's New?** PicoClaw now uses a **model-centric** configuration approach. Simply specify `vendor/model` format (e.g., `zhipu/glm-4.7`) to add new providers — **zero code changes required!**
|
||||
|
||||
This design also enables **multi-agent support** with flexible provider selection:
|
||||
|
||||
- **Different agents, different providers**: Each agent can use its own LLM provider
|
||||
- **Model fallbacks**: Configure primary and fallback models for resilience
|
||||
- **Load balancing**: Distribute requests across multiple endpoints
|
||||
- **Centralized configuration**: Manage all providers in one place
|
||||
|
||||
#### All Supported Vendors
|
||||
|
||||
| Vendor | `model` Prefix | Default API Base | Protocol | API Key |
|
||||
| ----------------------- | ----------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
|
||||
| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Get Key](https://platform.openai.com) |
|
||||
| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Get Key](https://console.anthropic.com) |
|
||||
| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
|
||||
| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Get Key](https://platform.deepseek.com) |
|
||||
| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Get Key](https://aistudio.google.com/api-keys) |
|
||||
| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Get Key](https://console.groq.com) |
|
||||
| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Get Key](https://platform.moonshot.cn) |
|
||||
| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Get Key](https://dashscope.console.aliyun.com) |
|
||||
| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Get Key](https://build.nvidia.com) |
|
||||
| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (no key needed) |
|
||||
| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Get Key](https://openrouter.ai/keys) |
|
||||
| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | Your LiteLLM proxy key |
|
||||
| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local |
|
||||
| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Get Key](https://cerebras.ai) |
|
||||
| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
|
||||
| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | — |
|
||||
| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [Get Key](https://www.byteplus.com) |
|
||||
| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [Get Key](https://vivgrid.com) |
|
||||
| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [Get Key](https://longcat.chat/platform) |
|
||||
| **ModelScope (魔搭)** | `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [Get Token](https://modelscope.cn/my/tokens) |
|
||||
| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth only |
|
||||
| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | — |
|
||||
|
||||
#### Basic Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"model_list": [
|
||||
{
|
||||
"model_name": "ark-code-latest",
|
||||
"model": "volcengine/ark-code-latest",
|
||||
"api_key": "sk-your-api-key"
|
||||
},
|
||||
{
|
||||
"model_name": "gpt-5.4",
|
||||
"model": "openai/gpt-5.4",
|
||||
"api_key": "sk-your-openai-key"
|
||||
},
|
||||
{
|
||||
"model_name": "claude-sonnet-4.6",
|
||||
"model": "anthropic/claude-sonnet-4.6",
|
||||
"api_key": "sk-ant-your-key"
|
||||
},
|
||||
{
|
||||
"model_name": "glm-4.7",
|
||||
"model": "zhipu/glm-4.7",
|
||||
"api_key": "your-zhipu-key"
|
||||
}
|
||||
],
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": "gpt-5.4"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Vendor-Specific Examples
|
||||
|
||||
<details>
|
||||
<summary><b>OpenAI</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "gpt-5.4",
|
||||
"model": "openai/gpt-5.4",
|
||||
"api_key": "sk-..."
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>VolcEngine (Doubao)</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "ark-code-latest",
|
||||
"model": "volcengine/ark-code-latest",
|
||||
"api_key": "sk-..."
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>智谱 AI (GLM)</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "glm-4.7",
|
||||
"model": "zhipu/glm-4.7",
|
||||
"api_key": "your-key"
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>DeepSeek</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "deepseek-chat",
|
||||
"model": "deepseek/deepseek-chat",
|
||||
"api_key": "sk-..."
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Anthropic</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "claude-sonnet-4.6",
|
||||
"model": "anthropic/claude-sonnet-4.6",
|
||||
"api_key": "sk-ant-your-key"
|
||||
}
|
||||
```
|
||||
|
||||
> Run `picoclaw auth login --provider anthropic` to paste your API token.
|
||||
|
||||
For direct Anthropic API access or custom endpoints that only support Anthropic's native message format:
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "claude-opus-4-6",
|
||||
"model": "anthropic-messages/claude-opus-4-6",
|
||||
"api_key": "sk-ant-your-key",
|
||||
"api_base": "https://api.anthropic.com"
|
||||
}
|
||||
```
|
||||
|
||||
> Use `anthropic-messages` when the endpoint requires Anthropic's native `/v1/messages` format instead of OpenAI-compatible `/v1/chat/completions`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Ollama (local)</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "llama3",
|
||||
"model": "ollama/llama3"
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Custom Proxy / LiteLLM</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "my-custom-model",
|
||||
"model": "openai/custom-model",
|
||||
"api_base": "https://my-proxy.com/v1",
|
||||
"api_key": "sk-..."
|
||||
}
|
||||
```
|
||||
|
||||
PicoClaw strips only the outer `litellm/` prefix before sending the request, so `litellm/lite-gpt4` sends `lite-gpt4`, while `litellm/openai/gpt-4o` sends `openai/gpt-4o`.
|
||||
|
||||
</details>
|
||||
|
||||
#### Load Balancing
|
||||
|
||||
Configure multiple endpoints for the same model name — PicoClaw will automatically round-robin between them:
|
||||
|
||||
```json
|
||||
{
|
||||
"model_list": [
|
||||
{
|
||||
"model_name": "gpt-5.4",
|
||||
"model": "openai/gpt-5.4",
|
||||
"api_base": "https://api1.example.com/v1",
|
||||
"api_key": "sk-key1"
|
||||
},
|
||||
{
|
||||
"model_name": "gpt-5.4",
|
||||
"model": "openai/gpt-5.4",
|
||||
"api_base": "https://api2.example.com/v1",
|
||||
"api_key": "sk-key2"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Migration from Legacy `providers` Config
|
||||
|
||||
The old `providers` configuration is **deprecated** but still supported for backward compatibility. See [docs/migration/model-list-migration.md](../migration/model-list-migration.md) for the full guide.
|
||||
|
||||
### Provider Architecture
|
||||
|
||||
PicoClaw routes providers by protocol family:
|
||||
|
||||
- **OpenAI-compatible**: OpenRouter, Groq, Zhipu, vLLM-style endpoints, and most others.
|
||||
- **Anthropic**: Claude-native API behavior.
|
||||
- **Codex/OAuth**: OpenAI OAuth/token authentication route.
|
||||
|
||||
This keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (`api_base` + `api_key`).
|
||||
|
||||
<details>
|
||||
<summary><b>Zhipu (legacy providers format)</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"workspace": "~/.picoclaw/workspace",
|
||||
"model": "glm-4.7",
|
||||
"max_tokens": 8192,
|
||||
"temperature": 0.7,
|
||||
"max_tool_iterations": 20
|
||||
}
|
||||
},
|
||||
"providers": {
|
||||
"zhipu": {
|
||||
"api_key": "Your API Key",
|
||||
"api_base": "https://open.bigmodel.cn/api/paas/v4"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Full config example</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": "anthropic/claude-opus-4-5"
|
||||
}
|
||||
},
|
||||
"session": {
|
||||
"dm_scope": "per-channel-peer",
|
||||
"backlog_limit": 20
|
||||
},
|
||||
"providers": {
|
||||
"openrouter": {
|
||||
"api_key": "sk-or-v1-xxx"
|
||||
},
|
||||
"groq": {
|
||||
"api_key": "gsk_xxx"
|
||||
}
|
||||
},
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"enabled": true,
|
||||
"token": "123456:ABC...",
|
||||
"allow_from": ["123456789"]
|
||||
}
|
||||
},
|
||||
"tools": {
|
||||
"web": {
|
||||
"duckduckgo": {
|
||||
"enabled": true,
|
||||
"max_results": 5
|
||||
}
|
||||
}
|
||||
},
|
||||
"heartbeat": {
|
||||
"enabled": true,
|
||||
"interval": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Scheduled Tasks / Reminders
|
||||
|
||||
PicoClaw supports cron-style scheduled tasks via the `cron` tool. The agent can set, list, and cancel reminders or recurring jobs that trigger at specified times.
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"cron": {
|
||||
"enabled": true,
|
||||
"exec_timeout_minutes": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Scheduled tasks persist across restarts and are stored in `~/.picoclaw/workspace/cron/`.
|
||||
|
||||
### Advanced Topics
|
||||
|
||||
| Topic | Description |
|
||||
| ----- | ----------- |
|
||||
| [Hook System](hooks/README.md) | Event-driven hooks: observers, interceptors, approval hooks |
|
||||
| [Steering](steering.md) | Inject messages into a running agent loop between tool calls |
|
||||
| [SubTurn](subturn.md) | Subagent coordination, concurrency control, lifecycle |
|
||||
| [Context Management](agent-refactor/context.md) | Context boundary detection, proactive budget check, compression |
|
||||
|
||||
+51
-1
@@ -13,6 +13,7 @@ Communiquez avec votre PicoClaw via Telegram, Discord, WhatsApp, Matrix, QQ, Din
|
||||
| **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) |
|
||||
| **Weixin** | ⭐ Facile | Scan QR natif (API Tencent iLink) | [Documentation](#weixin) |
|
||||
| **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) |
|
||||
@@ -20,11 +21,12 @@ Communiquez avec votre PicoClaw via Telegram, Discord, WhatsApp, Matrix, QQ, Din
|
||||
| **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 | - |
|
||||
| **IRC** | ⭐⭐ Moyen | Serveur + configuration TLS | [Documentation](#irc) |
|
||||
| **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 | |
|
||||
|
||||
<a id="telegram"></a>
|
||||
<details>
|
||||
<summary><b>Telegram</b> (Recommandé)</summary>
|
||||
|
||||
@@ -65,6 +67,7 @@ Si l'enregistrement des commandes échoue (erreurs transitoires réseau/API), le
|
||||
|
||||
</details>
|
||||
|
||||
<a id="discord"></a>
|
||||
<details>
|
||||
<summary><b>Discord</b></summary>
|
||||
|
||||
@@ -138,6 +141,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="whatsapp"></a>
|
||||
<details>
|
||||
<summary><b>WhatsApp</b> (natif via whatsmeow)</summary>
|
||||
|
||||
@@ -165,6 +169,43 @@ Si `session_store_path` est vide, la session est stockée dans `<workspace>/what
|
||||
|
||||
</details>
|
||||
|
||||
<a id="weixin"></a>
|
||||
<details>
|
||||
<summary><b>Weixin</b> (WeChat Personnel)</summary>
|
||||
|
||||
PicoClaw prend en charge la connexion à votre compte WeChat personnel via l'API officielle Tencent iLink.
|
||||
|
||||
**1. Connexion**
|
||||
|
||||
Lancez le flux de connexion interactif par QR code :
|
||||
```bash
|
||||
picoclaw onboard weixin
|
||||
```
|
||||
Scannez le QR code affiché avec votre application WeChat mobile. Une fois connecté, le token est sauvegardé dans votre configuration.
|
||||
|
||||
**2. Configurer**
|
||||
|
||||
(Optionnel) Ajoutez votre identifiant utilisateur WeChat dans `allow_from` pour restreindre qui peut envoyer des messages au bot :
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"weixin": {
|
||||
"enabled": true,
|
||||
"token": "YOUR_TOKEN",
|
||||
"allow_from": ["YOUR_USER_ID"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**3. Lancer**
|
||||
```bash
|
||||
picoclaw gateway
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<a id="qq"></a>
|
||||
<details>
|
||||
<summary><b>QQ</b></summary>
|
||||
|
||||
@@ -206,6 +247,7 @@ Si vous préférez créer le bot manuellement :
|
||||
|
||||
</details>
|
||||
|
||||
<a id="dingtalk"></a>
|
||||
<details>
|
||||
<summary><b>DingTalk</b></summary>
|
||||
|
||||
@@ -239,6 +281,7 @@ picoclaw gateway
|
||||
```
|
||||
</details>
|
||||
|
||||
<a id="matrix"></a>
|
||||
<details>
|
||||
<summary><b>Matrix</b></summary>
|
||||
|
||||
@@ -273,6 +316,7 @@ Pour toutes les options (`device_id`, `join_on_invite`, `group_trigger`, `placeh
|
||||
|
||||
</details>
|
||||
|
||||
<a id="line"></a>
|
||||
<details>
|
||||
<summary><b>LINE</b></summary>
|
||||
|
||||
@@ -321,6 +365,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="wecom"></a>
|
||||
<details>
|
||||
<summary><b>WeCom (企业微信)</b></summary>
|
||||
|
||||
@@ -435,6 +480,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="feishu"></a>
|
||||
<details>
|
||||
<summary><b>Feishu (飞书)</b></summary>
|
||||
|
||||
@@ -476,6 +522,7 @@ Pour toutes les options, voir le [Guide de Configuration du Canal Feishu](../cha
|
||||
|
||||
</details>
|
||||
|
||||
<a id="slack"></a>
|
||||
<details>
|
||||
<summary><b>Slack</b></summary>
|
||||
|
||||
@@ -509,6 +556,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="irc"></a>
|
||||
<details>
|
||||
<summary><b>IRC</b></summary>
|
||||
|
||||
@@ -542,6 +590,7 @@ Le bot se connectera au serveur IRC et rejoindra les canaux spécifiés.
|
||||
|
||||
</details>
|
||||
|
||||
<a id="onebot"></a>
|
||||
<details>
|
||||
<summary><b>OneBot (QQ via protocole OneBot)</b></summary>
|
||||
|
||||
@@ -580,6 +629,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="maixcam"></a>
|
||||
<details>
|
||||
<summary><b>MaixCam</b></summary>
|
||||
|
||||
|
||||
+146
-1
@@ -214,5 +214,150 @@ L'agent lira ce fichier toutes les 30 minutes (configurable) et exécutera toute
|
||||
Pour les tâches longues (recherche web, appels API), utilisez l'outil `spawn` pour créer un **subagent** :
|
||||
|
||||
```markdown
|
||||
# Periodic Tasks
|
||||
# Tâches Périodiques
|
||||
|
||||
## Tâches Rapides (répondre directement)
|
||||
|
||||
- Indiquer l'heure actuelle
|
||||
|
||||
## Tâches Longues (utiliser spawn pour l'asynchrone)
|
||||
|
||||
- Rechercher les actualités IA sur le web et résumer
|
||||
- Vérifier les e-mails et signaler les messages importants
|
||||
```
|
||||
|
||||
**Comportements clés :**
|
||||
|
||||
| Fonctionnalité | Description |
|
||||
| ---------------- | ------------------------------------------------------------------ |
|
||||
| **spawn** | Crée un subagent asynchrone, ne bloque pas le heartbeat |
|
||||
| **Contexte indépendant** | Le subagent a son propre contexte, sans historique de session |
|
||||
| **message tool** | Le subagent communique directement avec l'utilisateur |
|
||||
| **Non-bloquant** | Après le spawn, le heartbeat continue vers la tâche suivante |
|
||||
|
||||
#### Flux de Communication du Subagent
|
||||
|
||||
```
|
||||
Heartbeat déclenché
|
||||
↓
|
||||
Agent lit HEARTBEAT.md
|
||||
↓
|
||||
Tâche longue : spawn subagent
|
||||
↓ ↓
|
||||
Continue tâche suivante Subagent travaille indépendamment
|
||||
↓ ↓
|
||||
Toutes tâches terminées Subagent utilise "message" tool
|
||||
↓ ↓
|
||||
Répond HEARTBEAT_OK Utilisateur reçoit le résultat
|
||||
```
|
||||
|
||||
**Configuration :**
|
||||
|
||||
```json
|
||||
{
|
||||
"heartbeat": {
|
||||
"enabled": true,
|
||||
"interval": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Option | Défaut | Description |
|
||||
| ---------- | ------ | ---------------------------------------- |
|
||||
| `enabled` | `true` | Activer/désactiver le heartbeat |
|
||||
| `interval` | `30` | Intervalle en minutes (minimum : 5) |
|
||||
|
||||
**Variables d'environnement :**
|
||||
|
||||
* `PICOCLAW_HEARTBEAT_ENABLED=false` pour désactiver
|
||||
* `PICOCLAW_HEARTBEAT_INTERVAL=60` pour changer l'intervalle
|
||||
|
||||
### Providers
|
||||
|
||||
> [!NOTE]
|
||||
> Groq fournit une transcription vocale gratuite via Whisper. Si configuré, les messages audio de n'importe quel canal seront automatiquement transcrits au niveau de l'agent.
|
||||
|
||||
| Provider | Usage | Obtenir une clé API |
|
||||
| ------------ | --------------------------------------- | ------------------------------------------------------------ |
|
||||
| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) |
|
||||
| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](https://bigmodel.cn) |
|
||||
| `volcengine` | LLM (Volcengine direct) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
|
||||
| `openrouter` | LLM (recommandé, accès à tous modèles) | [openrouter.ai](https://openrouter.ai) |
|
||||
| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) |
|
||||
| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) |
|
||||
| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) |
|
||||
| `qwen` | LLM (Qwen direct) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
|
||||
| `groq` | LLM + **Transcription vocale** (Whisper)| [console.groq.com](https://console.groq.com) |
|
||||
| `cerebras` | LLM (Cerebras direct) | [cerebras.ai](https://cerebras.ai) |
|
||||
| `vivgrid` | LLM (Vivgrid direct) | [vivgrid.com](https://vivgrid.com) |
|
||||
|
||||
### Configuration des Modèles (model_list)
|
||||
|
||||
> **Nouveauté :** PicoClaw utilise désormais une approche **centrée sur le modèle**. Spécifiez simplement le format `vendor/model` (ex. `zhipu/glm-4.7`) pour ajouter de nouveaux providers — **aucune modification de code requise !**
|
||||
|
||||
#### Tous les Vendors Supportés
|
||||
|
||||
| Vendor | Préfixe `model` | API Base par défaut | Protocole | API Key |
|
||||
| ----------------------- | --------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
|
||||
| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Obtenir](https://platform.openai.com) |
|
||||
| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Obtenir](https://console.anthropic.com) |
|
||||
| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Obtenir](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
|
||||
| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Obtenir](https://platform.deepseek.com) |
|
||||
| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Obtenir](https://aistudio.google.com/api-keys) |
|
||||
| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Obtenir](https://console.groq.com) |
|
||||
| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Obtenir](https://dashscope.console.aliyun.com) |
|
||||
| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (pas de clé) |
|
||||
| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Obtenir](https://openrouter.ai/keys) |
|
||||
| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Obtenir](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
|
||||
| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth uniquement |
|
||||
|
||||
#### Équilibrage de Charge
|
||||
|
||||
Configurez plusieurs endpoints pour le même nom de modèle — PicoClaw effectuera automatiquement un round-robin :
|
||||
|
||||
```json
|
||||
{
|
||||
"model_list": [
|
||||
{ "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" },
|
||||
{ "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Migration depuis l'ancienne config `providers`
|
||||
|
||||
L'ancienne configuration `providers` est **dépréciée** mais toujours supportée. Voir [docs/migration/model-list-migration.md](../migration/model-list-migration.md).
|
||||
|
||||
### Architecture des Providers
|
||||
|
||||
PicoClaw route les providers par famille de protocole :
|
||||
|
||||
- **Compatible OpenAI** : OpenRouter, Groq, Zhipu, endpoints vLLM et la plupart des autres.
|
||||
- **Anthropic** : Comportement natif de l'API Claude.
|
||||
- **Codex/OAuth** : Route d'authentification OAuth/token OpenAI.
|
||||
|
||||
### Tâches Planifiées / Rappels
|
||||
|
||||
PicoClaw supporte les tâches planifiées via l'outil `cron`. L'agent peut définir, lister et annuler des rappels ou tâches récurrentes.
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"cron": {
|
||||
"enabled": true,
|
||||
"exec_timeout_minutes": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Les tâches planifiées persistent après redémarrage dans `~/.picoclaw/workspace/cron/`.
|
||||
|
||||
### Sujets Avancés
|
||||
|
||||
| Sujet | Description |
|
||||
| ----- | ----------- |
|
||||
| [Système de Hooks](../hooks/README.md) | Hooks événementiels : observateurs, intercepteurs, hooks d'approbation |
|
||||
| [Steering](../steering.md) | Injecter des messages dans une boucle agent en cours d'exécution |
|
||||
| [SubTurn](../subturn.md) | Coordination de subagents, contrôle de concurrence, cycle de vie |
|
||||
| [Gestion du Contexte](../agent-refactor/context.md) | Détection des limites de contexte, compression |
|
||||
|
||||
@@ -41,14 +41,6 @@ Paramètres généraux pour la récupération et le traitement du contenu des pa
|
||||
| `fetch_limit_bytes` | int | 10485760 | Taille maximale du contenu de la page web à récupérer, en octets (par défaut 10 Mo). |
|
||||
| `format` | string | "plaintext" | Format de sortie du contenu récupéré. Options : `plaintext` ou `markdown` (recommandé). |
|
||||
|
||||
### Brave
|
||||
|
||||
| Config | Type | Par défaut | Description |
|
||||
|---------------|--------|------------|---------------------------|
|
||||
| `enabled` | bool | false | Activer la recherche Brave |
|
||||
| `api_key` | string | - | Clé API Brave Search |
|
||||
| `max_results` | int | 5 | Nombre maximum de résultats |
|
||||
|
||||
### DuckDuckGo
|
||||
|
||||
| Config | Type | Par défaut | Description |
|
||||
@@ -56,13 +48,73 @@ Paramètres généraux pour la récupération et le traitement du contenu des pa
|
||||
| `enabled` | bool | true | Activer la recherche DuckDuckGo |
|
||||
| `max_results` | int | 5 | Nombre maximum de résultats |
|
||||
|
||||
### Baidu Search
|
||||
|
||||
| Config | Type | Par défaut | Description |
|
||||
|---------------|--------|-----------------------------------------------------------------|------------------------------------|
|
||||
| `enabled` | bool | false | Activer la recherche Baidu |
|
||||
| `api_key` | string | - | Clé API Qianfan |
|
||||
| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | URL de l'API Baidu Search |
|
||||
| `max_results` | int | 10 | Nombre maximum de résultats |
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"web": {
|
||||
"baidu_search": {
|
||||
"enabled": true,
|
||||
"api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
|
||||
"max_results": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Perplexity
|
||||
|
||||
| Config | Type | Par défaut | Description |
|
||||
|---------------|--------|------------|--------------------------------|
|
||||
| `enabled` | bool | false | Activer la recherche Perplexity |
|
||||
| `api_key` | string | - | Clé API Perplexity |
|
||||
| `max_results` | int | 5 | Nombre maximum de résultats |
|
||||
| `enabled` | bool | false | Activer la recherche Perplexity |
|
||||
| `api_key` | string | - | Clé API Perplexity |
|
||||
| `api_keys` | string[] | - | Plusieurs clés API Perplexity pour la rotation (`api_key` prioritaire) |
|
||||
| `max_results` | int | 5 | Nombre maximum de résultats |
|
||||
|
||||
### Brave
|
||||
|
||||
| Config | Type | Par défaut | Description |
|
||||
|---------------|--------|------------|---------------------------|
|
||||
| `enabled` | bool | false | Activer la recherche Brave |
|
||||
| `api_key` | string | - | Clé API Brave Search |
|
||||
| `api_keys` | string[] | - | Plusieurs clés API Brave Search pour la rotation (`api_key` prioritaire) |
|
||||
| `max_results` | int | 5 | Nombre maximum de résultats |
|
||||
|
||||
### Tavily
|
||||
|
||||
| Config | Type | Par défaut | Description |
|
||||
|---------------|--------|------------|------------------------------------|
|
||||
| `enabled` | bool | false | Activer la recherche Tavily |
|
||||
| `api_key` | string | - | Clé API Tavily |
|
||||
| `base_url` | string | - | URL de base Tavily personnalisée |
|
||||
| `max_results` | int | 0 | Nombre maximum de résultats (0 = défaut) |
|
||||
|
||||
### SearXNG
|
||||
|
||||
| Config | Type | Par défaut | Description |
|
||||
|---------------|--------|--------------------------|--------------------------------|
|
||||
| `enabled` | bool | false | Activer la recherche SearXNG |
|
||||
| `base_url` | string | `http://localhost:8888` | URL de l'instance SearXNG |
|
||||
| `max_results` | int | 5 | Nombre maximum de résultats |
|
||||
|
||||
### GLM Search
|
||||
|
||||
| Config | Type | Par défaut | Description |
|
||||
|-----------------|--------|------------------------------------------------------|---------------------------|
|
||||
| `enabled` | bool | false | Activer GLM Search |
|
||||
| `api_key` | string | - | Clé API GLM |
|
||||
| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | URL de l'API GLM Search |
|
||||
| `search_engine` | string | `search_std` | Type de moteur de recherche |
|
||||
| `max_results` | int | 5 | Nombre maximum de résultats |
|
||||
|
||||
## Outil Exec
|
||||
|
||||
|
||||
+51
-1
@@ -15,6 +15,7 @@ PicoClaw は複数のチャットプラットフォームをサポートして
|
||||
| **Telegram** | ⭐ 簡単 | 推奨、音声テキスト変換対応、ロングポーリング（公開 IP 不要） | [ドキュメント](../channels/telegram/README.ja.md) |
|
||||
| **Discord** | ⭐ 簡単 | Socket Mode、グループ/DM 対応、Bot エコシステム充実 | [ドキュメント](../channels/discord/README.ja.md) |
|
||||
| **WhatsApp** | ⭐ 簡単 | ネイティブ (QR スキャン) または Bridge URL | [ドキュメント](#whatsapp) |
|
||||
| **微信 (Weixin)** | ⭐ 簡単 | ネイティブ QR スキャン（Tencent iLink API）| [ドキュメント](#weixin) |
|
||||
| **Slack** | ⭐ 簡単 | **Socket Mode** (公開 IP 不要)、エンタープライズ対応 | [ドキュメント](../channels/slack/README.ja.md) |
|
||||
| **Matrix** | ⭐⭐ 中程度 | フェデレーションプロトコル、セルフホスト対応 | [ドキュメント](../channels/matrix/README.ja.md) |
|
||||
| **QQ** | ⭐⭐ 中程度 | 公式ボット API、中国コミュニティ向け | [ドキュメント](../channels/qq/README.ja.md) |
|
||||
@@ -22,13 +23,14 @@ PicoClaw は複数のチャットプラットフォームをサポートして
|
||||
| **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 設定 | - |
|
||||
| **IRC** | ⭐⭐ 中程度 | サーバー + TLS 設定 | [ドキュメント](#irc) |
|
||||
| **OneBot** | ⭐⭐ 中程度 | NapCat/Go-CQHTTP 互換、コミュニティエコシステム充実 | [ドキュメント](../channels/onebot/README.ja.md) |
|
||||
| **MaixCam** | ⭐ 簡単 | Sipeed AI カメラハードウェア統合チャネル | [ドキュメント](../channels/maixcam/README.ja.md) |
|
||||
| **Pico** | ⭐ 簡単 | PicoClaw ネイティブプロトコルチャネル | |
|
||||
|
||||
---
|
||||
|
||||
<a id="telegram"></a>
|
||||
<details>
|
||||
<summary><b>Telegram</b>（推奨）</summary>
|
||||
|
||||
@@ -69,6 +71,7 @@ Telegram 側はコマンドメニュー登録機能を保持し、汎用コマ
|
||||
|
||||
</details>
|
||||
|
||||
<a id="discord"></a>
|
||||
<details>
|
||||
<summary><b>Discord</b></summary>
|
||||
|
||||
@@ -143,6 +146,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="whatsapp"></a>
|
||||
<details>
|
||||
<summary><b>WhatsApp</b>（ネイティブ whatsmeow）</summary>
|
||||
|
||||
@@ -170,6 +174,43 @@ PicoClaw は 2 つの WhatsApp 接続方式をサポートしています：
|
||||
|
||||
</details>
|
||||
|
||||
<a id="weixin"></a>
|
||||
<details>
|
||||
<summary><b>微信 (Weixin)</b></summary>
|
||||
|
||||
PicoClaw は Tencent iLink 公式 API を使用して WeChat 個人アカウントへの接続をサポートしています。
|
||||
|
||||
**1. ログイン**
|
||||
|
||||
インタラクティブな QR ログインフローを実行します：
|
||||
```bash
|
||||
picoclaw onboard weixin
|
||||
```
|
||||
WeChat モバイルアプリで表示された QR コードをスキャンしてください。ログイン成功後、トークンが設定ファイルに保存されます。
|
||||
|
||||
**2. 設定**
|
||||
|
||||
（オプション）ボットと会話できるユーザーを制限するために `allow_from` に WeChat ユーザー ID を追加します：
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"weixin": {
|
||||
"enabled": true,
|
||||
"token": "YOUR_TOKEN",
|
||||
"allow_from": ["YOUR_USER_ID"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**3. 実行**
|
||||
```bash
|
||||
picoclaw gateway
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<a id="matrix"></a>
|
||||
<details>
|
||||
<summary><b>Matrix</b></summary>
|
||||
|
||||
@@ -204,6 +245,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="qq"></a>
|
||||
<details>
|
||||
<summary><b>QQ</b></summary>
|
||||
|
||||
@@ -245,6 +287,7 @@ QQ 開放プラットフォームでは、OpenClaw 互換ボットのワンク
|
||||
|
||||
</details>
|
||||
|
||||
<a id="slack"></a>
|
||||
<details>
|
||||
<summary><b>Slack</b></summary>
|
||||
|
||||
@@ -278,6 +321,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="irc"></a>
|
||||
<details>
|
||||
<summary><b>IRC</b></summary>
|
||||
|
||||
@@ -311,6 +355,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="dingtalk"></a>
|
||||
<details>
|
||||
<summary><b>DingTalk</b></summary>
|
||||
|
||||
@@ -345,6 +390,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="line"></a>
|
||||
<details>
|
||||
<summary><b>LINE</b></summary>
|
||||
|
||||
@@ -393,6 +439,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="feishu"></a>
|
||||
<details>
|
||||
<summary><b>Feishu (飛書)</b></summary>
|
||||
|
||||
@@ -434,6 +481,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="wecom"></a>
|
||||
<details>
|
||||
<summary><b>WeCom (企業微信)</b></summary>
|
||||
|
||||
@@ -548,6 +596,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="onebot"></a>
|
||||
<details>
|
||||
<summary><b>OneBot（OneBot プロトコル経由の QQ）</b></summary>
|
||||
|
||||
@@ -586,6 +635,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="maixcam"></a>
|
||||
<details>
|
||||
<summary><b>MaixCam</b></summary>
|
||||
|
||||
|
||||
@@ -256,3 +256,109 @@ Agent は 30 分ごと（設定可能）にこのファイルを読み取り、
|
||||
|
||||
- `PICOCLAW_HEARTBEAT_ENABLED=false` で無効化
|
||||
- `PICOCLAW_HEARTBEAT_INTERVAL=60` で間隔を変更
|
||||
|
||||
#### サブ Agent の通信フロー
|
||||
|
||||
```
|
||||
ハートビート起動
|
||||
↓
|
||||
Agent が HEARTBEAT.md を読む
|
||||
↓
|
||||
長時間タスク：spawn サブ Agent
|
||||
↓ ↓
|
||||
次のタスクへ継続 サブ Agent が独立して動作
|
||||
↓ ↓
|
||||
全タスク完了 サブ Agent が "message" ツールを使用
|
||||
↓ ↓
|
||||
HEARTBEAT_OK を返信 ユーザーが直接結果を受信
|
||||
```
|
||||
|
||||
### Providers
|
||||
|
||||
> [!NOTE]
|
||||
> Groq は Whisper による無料音声文字起こしを提供します。設定すると、任意のチャンネルの音声メッセージが Agent レベルで自動的に文字起こしされます。
|
||||
|
||||
| Provider | 用途 | API キー取得 |
|
||||
| ------------ | --------------------------------------- | ------------------------------------------------------------ |
|
||||
| `gemini` | LLM（Gemini 直接） | [aistudio.google.com](https://aistudio.google.com) |
|
||||
| `zhipu` | LLM（Zhipu 直接） | [bigmodel.cn](https://bigmodel.cn) |
|
||||
| `volcengine` | LLM（Volcengine 直接） | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
|
||||
| `openrouter` | LLM（推奨、全モデルにアクセス可能） | [openrouter.ai](https://openrouter.ai) |
|
||||
| `anthropic` | LLM（Claude 直接） | [console.anthropic.com](https://console.anthropic.com) |
|
||||
| `openai` | LLM（GPT 直接） | [platform.openai.com](https://platform.openai.com) |
|
||||
| `deepseek` | LLM（DeepSeek 直接） | [platform.deepseek.com](https://platform.deepseek.com) |
|
||||
| `qwen` | LLM（Qwen 直接） | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
|
||||
| `groq` | LLM + **音声文字起こし**（Whisper） | [console.groq.com](https://console.groq.com) |
|
||||
| `cerebras` | LLM（Cerebras 直接） | [cerebras.ai](https://cerebras.ai) |
|
||||
| `vivgrid` | LLM（Vivgrid 直接） | [vivgrid.com](https://vivgrid.com) |
|
||||
|
||||
### モデル設定 (model_list)
|
||||
|
||||
> **新機能：** PicoClaw は**モデル中心**の設定アプローチを採用しました。`vendor/model` 形式（例：`zhipu/glm-4.7`）を指定するだけで新しい Provider を追加できます — **コード変更不要！**
|
||||
|
||||
#### サポートされている全 Vendor
|
||||
|
||||
| Vendor | `model` プレフィックス | デフォルト API Base | プロトコル | API Key |
|
||||
| ----------------------- | ---------------------- | --------------------------------------------------- | ---------- | ---------------------------------------------------------------- |
|
||||
| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [取得](https://platform.openai.com) |
|
||||
| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [取得](https://console.anthropic.com) |
|
||||
| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [取得](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
|
||||
| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [取得](https://platform.deepseek.com) |
|
||||
| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [取得](https://aistudio.google.com/api-keys) |
|
||||
| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [取得](https://console.groq.com) |
|
||||
| **通義千問 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [取得](https://dashscope.console.aliyun.com) |
|
||||
| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | ローカル（キー不要） |
|
||||
| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [取得](https://openrouter.ai/keys) |
|
||||
| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [取得](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
|
||||
| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth のみ |
|
||||
|
||||
#### ロードバランシング
|
||||
|
||||
同じモデル名に複数のエンドポイントを設定すると、PicoClaw が自動的にラウンドロビンします：
|
||||
|
||||
```json
|
||||
{
|
||||
"model_list": [
|
||||
{ "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" },
|
||||
{ "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 旧 `providers` 設定からの移行
|
||||
|
||||
旧 `providers` 設定は**非推奨**ですが後方互換性のためサポートされています。[docs/migration/model-list-migration.md](../migration/model-list-migration.md) を参照してください。
|
||||
|
||||
### Provider アーキテクチャ
|
||||
|
||||
PicoClaw はプロトコルファミリーで Provider をルーティングします：
|
||||
|
||||
- **OpenAI 互換**：OpenRouter、Groq、Zhipu、vLLM スタイルのエンドポイントなど。
|
||||
- **Anthropic**：Claude ネイティブ API の動作。
|
||||
- **Codex/OAuth**：OpenAI OAuth/トークン認証ルート。
|
||||
|
||||
### スケジュールタスク / リマインダー
|
||||
|
||||
PicoClaw は `cron` ツールを通じて cron スタイルのスケジュールタスクをサポートします。
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"cron": {
|
||||
"enabled": true,
|
||||
"exec_timeout_minutes": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
スケジュールタスクは再起動後も `~/.picoclaw/workspace/cron/` に保存されます。
|
||||
|
||||
### 高度なトピック
|
||||
|
||||
| トピック | 説明 |
|
||||
| -------- | ---- |
|
||||
| [Hook システム](../hooks/README.md) | イベント駆動 Hook：オブザーバー、インターセプター、承認 Hook |
|
||||
| [Steering](../steering.md) | 実行中の Agent ループにメッセージを注入 |
|
||||
| [SubTurn](../subturn.md) | サブ Agent の調整、並行制御、ライフサイクル |
|
||||
| [コンテキスト管理](../agent-refactor/context.md) | コンテキスト境界検出、圧縮戦略 |
|
||||
|
||||
@@ -41,14 +41,6 @@ Web ツールはウェブ検索とフェッチに使用されます。
|
||||
| `fetch_limit_bytes` | int | 10485760 | 取得するウェブページペイロードの最大サイズ（バイト単位、デフォルトは10MB）。 |
|
||||
| `format` | string | "plaintext" | 取得コンテンツの出力形式。オプション：`plaintext` または `markdown`（推奨）。 |
|
||||
|
||||
### Brave
|
||||
|
||||
| 設定項目 | 型 | デフォルト | 説明 |
|
||||
|---------------|--------|------------|-----------------------|
|
||||
| `enabled` | bool | false | Brave 検索を有効にする |
|
||||
| `api_key` | string | - | Brave Search API キー |
|
||||
| `max_results` | int | 5 | 最大結果数 |
|
||||
|
||||
### DuckDuckGo
|
||||
|
||||
| 設定項目 | 型 | デフォルト | 説明 |
|
||||
@@ -56,13 +48,73 @@ Web ツールはウェブ検索とフェッチに使用されます。
|
||||
| `enabled` | bool | true | DuckDuckGo 検索を有効にする |
|
||||
| `max_results` | int | 5 | 最大結果数 |
|
||||
|
||||
### Baidu Search
|
||||
|
||||
| 設定項目 | 型 | デフォルト | 説明 |
|
||||
|---------------|--------|-----------------------------------------------------------------|-------------------------------|
|
||||
| `enabled` | bool | false | Baidu 検索を有効にする |
|
||||
| `api_key` | string | - | Qianfan API キー |
|
||||
| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | Baidu Search API URL |
|
||||
| `max_results` | int | 10 | 最大結果数 |
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"web": {
|
||||
"baidu_search": {
|
||||
"enabled": true,
|
||||
"api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
|
||||
"max_results": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Perplexity
|
||||
|
||||
| 設定項目 | 型 | デフォルト | 説明 |
|
||||
|---------------|--------|------------|---------------------------|
|
||||
| `enabled` | bool | false | Perplexity 検索を有効にする |
|
||||
| `api_key` | string | - | Perplexity API キー |
|
||||
| `max_results` | int | 5 | 最大結果数 |
|
||||
| `enabled` | bool | false | Perplexity 検索を有効にする |
|
||||
| `api_key` | string | - | Perplexity API キー |
|
||||
| `api_keys` | string[] | - | 複数の Perplexity API キー（ローテーション用、`api_key` より優先） |
|
||||
| `max_results` | int | 5 | 最大結果数 |
|
||||
|
||||
### Brave
|
||||
|
||||
| 設定項目 | 型 | デフォルト | 説明 |
|
||||
|---------------|--------|------------|-----------------------|
|
||||
| `enabled` | bool | false | Brave 検索を有効にする |
|
||||
| `api_key` | string | - | Brave Search API キー |
|
||||
| `api_keys` | string[] | - | 複数の Brave Search API キー（ローテーション用、`api_key` より優先） |
|
||||
| `max_results` | int | 5 | 最大結果数 |
|
||||
|
||||
### Tavily
|
||||
|
||||
| 設定項目 | 型 | デフォルト | 説明 |
|
||||
|---------------|--------|------------|-----------------------------------|
|
||||
| `enabled` | bool | false | Tavily 検索を有効にする |
|
||||
| `api_key` | string | - | Tavily API キー |
|
||||
| `base_url` | string | - | カスタム Tavily API ベース URL |
|
||||
| `max_results` | int | 0 | 最大結果数（0 = デフォルト） |
|
||||
|
||||
### SearXNG
|
||||
|
||||
| 設定項目 | 型 | デフォルト | 説明 |
|
||||
|---------------|--------|--------------------------|---------------------------|
|
||||
| `enabled` | bool | false | SearXNG 検索を有効にする |
|
||||
| `base_url` | string | `http://localhost:8888` | SearXNG インスタンス URL |
|
||||
| `max_results` | int | 5 | 最大結果数 |
|
||||
|
||||
### GLM Search
|
||||
|
||||
| 設定項目 | 型 | デフォルト | 説明 |
|
||||
|-----------------|--------|------------------------------------------------------|---------------------------|
|
||||
| `enabled` | bool | false | GLM Search を有効にする |
|
||||
| `api_key` | string | - | GLM API キー |
|
||||
| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | GLM Search API URL |
|
||||
| `search_engine` | string | `search_std` | 検索エンジンタイプ |
|
||||
| `max_results` | int | 5 | 最大結果数 |
|
||||
|
||||
## Exec ツール
|
||||
|
||||
|
||||
+51
-1
@@ -13,6 +13,7 @@ Converse com seu picoclaw através do Telegram, Discord, WhatsApp, Matrix, QQ, D
|
||||
| **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) |
|
||||
| **Weixin** | ⭐ Fácil | Scan QR nativo (API Tencent iLink) | [Documentação](#weixin) |
|
||||
| **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) |
|
||||
@@ -20,11 +21,12 @@ Converse com seu picoclaw através do Telegram, Discord, WhatsApp, Matrix, QQ, D
|
||||
| **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 | - |
|
||||
| **IRC** | ⭐⭐ Médio | Servidor + configuração TLS | [Documentação](#irc) |
|
||||
| **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 | |
|
||||
|
||||
<a id="telegram"></a>
|
||||
<details>
|
||||
<summary><b>Telegram</b> (Recomendado)</summary>
|
||||
|
||||
@@ -65,6 +67,7 @@ Se o registro de comandos falhar (erros transitórios de rede/API), o canal aind
|
||||
|
||||
</details>
|
||||
|
||||
<a id="discord"></a>
|
||||
<details>
|
||||
<summary><b>Discord</b></summary>
|
||||
|
||||
@@ -138,6 +141,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="whatsapp"></a>
|
||||
<details>
|
||||
<summary><b>WhatsApp</b> (nativo via whatsmeow)</summary>
|
||||
|
||||
@@ -165,6 +169,43 @@ Se `session_store_path` estiver vazio, a sessão é armazenada em `<workspace>/w
|
||||
|
||||
</details>
|
||||
|
||||
<a id="weixin"></a>
|
||||
<details>
|
||||
<summary><b>Weixin</b> (WeChat Pessoal)</summary>
|
||||
|
||||
O PicoClaw suporta conexão com sua conta pessoal do WeChat usando a API oficial Tencent iLink.
|
||||
|
||||
**1. Login**
|
||||
|
||||
Execute o fluxo de login interativo por QR code:
|
||||
```bash
|
||||
picoclaw onboard weixin
|
||||
```
|
||||
Escaneie o QR code exibido com seu aplicativo WeChat mobile. Após o login bem-sucedido, o token é salvo na sua configuração.
|
||||
|
||||
**2. Configurar**
|
||||
|
||||
(Opcional) Adicione seu ID de usuário WeChat em `allow_from` para restringir quem pode enviar mensagens ao bot:
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"weixin": {
|
||||
"enabled": true,
|
||||
"token": "YOUR_TOKEN",
|
||||
"allow_from": ["YOUR_USER_ID"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**3. Executar**
|
||||
```bash
|
||||
picoclaw gateway
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<a id="qq"></a>
|
||||
<details>
|
||||
<summary><b>QQ</b></summary>
|
||||
|
||||
@@ -206,6 +247,7 @@ Se preferir criar o bot manualmente:
|
||||
|
||||
</details>
|
||||
|
||||
<a id="dingtalk"></a>
|
||||
<details>
|
||||
<summary><b>DingTalk</b></summary>
|
||||
|
||||
@@ -240,6 +282,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="maixcam"></a>
|
||||
<details>
|
||||
<summary><b>MaixCam</b></summary>
|
||||
|
||||
@@ -262,6 +305,7 @@ picoclaw gateway
|
||||
</details>
|
||||
|
||||
|
||||
<a id="matrix"></a>
|
||||
<details>
|
||||
<summary><b>Matrix</b></summary>
|
||||
|
||||
@@ -296,6 +340,7 @@ Para opções completas (`device_id`, `join_on_invite`, `group_trigger`, `placeh
|
||||
|
||||
</details>
|
||||
|
||||
<a id="line"></a>
|
||||
<details>
|
||||
<summary><b>LINE</b></summary>
|
||||
|
||||
@@ -344,6 +389,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="wecom"></a>
|
||||
<details>
|
||||
<summary><b>WeCom (企业微信)</b></summary>
|
||||
|
||||
@@ -457,6 +503,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="feishu"></a>
|
||||
<details>
|
||||
<summary><b>Feishu (Lark)</b></summary>
|
||||
|
||||
@@ -498,6 +545,7 @@ Para opções completas, veja o [Guia de Configuração do Canal Feishu](../chan
|
||||
|
||||
</details>
|
||||
|
||||
<a id="slack"></a>
|
||||
<details>
|
||||
<summary><b>Slack</b></summary>
|
||||
|
||||
@@ -531,6 +579,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="irc"></a>
|
||||
<details>
|
||||
<summary><b>IRC</b></summary>
|
||||
|
||||
@@ -564,6 +613,7 @@ O bot se conectará ao servidor IRC e entrará nos canais especificados.
|
||||
|
||||
</details>
|
||||
|
||||
<a id="onebot"></a>
|
||||
<details>
|
||||
<summary><b>OneBot (QQ via protocolo OneBot)</b></summary>
|
||||
|
||||
|
||||
@@ -216,4 +216,149 @@ Para tarefas de longa duração (busca na web, chamadas de API), use a ferrament
|
||||
|
||||
```markdown
|
||||
# Tarefas Periódicas
|
||||
|
||||
## Tarefas Rápidas (responder diretamente)
|
||||
|
||||
- Informar a hora atual
|
||||
|
||||
## Tarefas Longas (usar spawn para assíncrono)
|
||||
|
||||
- Pesquisar notícias de IA na web e resumir
|
||||
- Verificar e-mails e reportar mensagens importantes
|
||||
```
|
||||
|
||||
**Comportamentos principais:**
|
||||
|
||||
| Funcionalidade | Descrição |
|
||||
| ---------------- | ------------------------------------------------------------------ |
|
||||
| **spawn** | Cria subagente assíncrono, não bloqueia o heartbeat |
|
||||
| **Contexto independente** | Subagente tem seu próprio contexto, sem histórico de sessão |
|
||||
| **message tool** | Subagente comunica diretamente com o usuário via message tool |
|
||||
| **Não-bloqueante** | Após o spawn, o heartbeat continua para a próxima tarefa |
|
||||
|
||||
#### Fluxo de Comunicação do Subagente
|
||||
|
||||
```
|
||||
Heartbeat disparado
|
||||
↓
|
||||
Agent lê HEARTBEAT.md
|
||||
↓
|
||||
Tarefa longa: spawn subagente
|
||||
↓ ↓
|
||||
Continua próxima tarefa Subagente trabalha independentemente
|
||||
↓ ↓
|
||||
Todas tarefas concluídas Subagente usa ferramenta "message"
|
||||
↓ ↓
|
||||
Responde HEARTBEAT_OK Usuário recebe resultado diretamente
|
||||
```
|
||||
|
||||
**Configuração:**
|
||||
|
||||
```json
|
||||
{
|
||||
"heartbeat": {
|
||||
"enabled": true,
|
||||
"interval": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Opção | Padrão | Descrição |
|
||||
| ---------- | ------ | -------------------------------------- |
|
||||
| `enabled` | `true` | Ativar/desativar heartbeat |
|
||||
| `interval` | `30` | Intervalo em minutos (mínimo: 5) |
|
||||
|
||||
**Variáveis de ambiente:**
|
||||
|
||||
* `PICOCLAW_HEARTBEAT_ENABLED=false` para desativar
|
||||
* `PICOCLAW_HEARTBEAT_INTERVAL=60` para alterar o intervalo
|
||||
|
||||
### Providers
|
||||
|
||||
> [!NOTE]
|
||||
> O Groq fornece transcrição de voz gratuita via Whisper. Se configurado, mensagens de áudio de qualquer canal serão automaticamente transcritas no nível do agente.
|
||||
|
||||
| Provider | Finalidade | Obter API Key |
|
||||
| ------------ | --------------------------------------- | ------------------------------------------------------------ |
|
||||
| `gemini` | LLM (Gemini direto) | [aistudio.google.com](https://aistudio.google.com) |
|
||||
| `zhipu` | LLM (Zhipu direto) | [bigmodel.cn](https://bigmodel.cn) |
|
||||
| `volcengine` | LLM (Volcengine direto) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
|
||||
| `openrouter` | LLM (recomendado, acesso a todos modelos) | [openrouter.ai](https://openrouter.ai) |
|
||||
| `anthropic` | LLM (Claude direto) | [console.anthropic.com](https://console.anthropic.com) |
|
||||
| `openai` | LLM (GPT direto) | [platform.openai.com](https://platform.openai.com) |
|
||||
| `deepseek` | LLM (DeepSeek direto) | [platform.deepseek.com](https://platform.deepseek.com) |
|
||||
| `qwen` | LLM (Qwen direto) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
|
||||
| `groq` | LLM + **Transcrição de voz** (Whisper) | [console.groq.com](https://console.groq.com) |
|
||||
| `cerebras` | LLM (Cerebras direto) | [cerebras.ai](https://cerebras.ai) |
|
||||
| `vivgrid` | LLM (Vivgrid direto) | [vivgrid.com](https://vivgrid.com) |
|
||||
|
||||
### Configuração de Modelos (model_list)
|
||||
|
||||
> **Novidade:** PicoClaw agora usa uma abordagem **centrada no modelo**. Basta especificar o formato `vendor/model` (ex.: `zhipu/glm-4.7`) para adicionar novos providers — **sem alterações de código!**
|
||||
|
||||
#### Todos os Vendors Suportados
|
||||
|
||||
| Vendor | Prefixo `model` | API Base padrão | Protocolo | API Key |
|
||||
| ----------------------- | --------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
|
||||
| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Obter](https://platform.openai.com) |
|
||||
| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Obter](https://console.anthropic.com) |
|
||||
| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Obter](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
|
||||
| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Obter](https://platform.deepseek.com) |
|
||||
| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Obter](https://aistudio.google.com/api-keys) |
|
||||
| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Obter](https://console.groq.com) |
|
||||
| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Obter](https://dashscope.console.aliyun.com) |
|
||||
| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (sem chave) |
|
||||
| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Obter](https://openrouter.ai/keys) |
|
||||
| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Obter](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
|
||||
| **Antigravity** | `antigravity/` | Google Cloud | Custom | Somente OAuth |
|
||||
|
||||
#### Balanceamento de Carga
|
||||
|
||||
Configure múltiplos endpoints para o mesmo nome de modelo — PicoClaw fará round-robin automaticamente:
|
||||
|
||||
```json
|
||||
{
|
||||
"model_list": [
|
||||
{ "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" },
|
||||
{ "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Migração da Configuração Legada `providers`
|
||||
|
||||
A configuração antiga `providers` está **depreciada** mas ainda é suportada. Veja [docs/migration/model-list-migration.md](../migration/model-list-migration.md).
|
||||
|
||||
### Arquitetura de Providers
|
||||
|
||||
PicoClaw roteia providers por família de protocolo:
|
||||
|
||||
- **Compatível com OpenAI**: OpenRouter, Groq, Zhipu, endpoints vLLM e a maioria dos outros.
|
||||
- **Anthropic**: Comportamento nativo da API Claude.
|
||||
- **Codex/OAuth**: Rota de autenticação OAuth/token OpenAI.
|
||||
|
||||
### Tarefas Agendadas / Lembretes
|
||||
|
||||
PicoClaw suporta tarefas agendadas via ferramenta `cron`.
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"cron": {
|
||||
"enabled": true,
|
||||
"exec_timeout_minutes": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
As tarefas agendadas persistem após reinicializações em `~/.picoclaw/workspace/cron/`.
|
||||
|
||||
### Tópicos Avançados
|
||||
|
||||
| Tópico | Descrição |
|
||||
| ------ | --------- |
|
||||
| [Sistema de Hooks](../hooks/README.md) | Hooks orientados a eventos: observadores, interceptores, hooks de aprovação |
|
||||
| [Steering](../steering.md) | Injetar mensagens em um loop de agente em execução |
|
||||
| [SubTurn](../subturn.md) | Coordenação de subagentes, controle de concorrência, ciclo de vida |
|
||||
| [Gerenciamento de Contexto](../agent-refactor/context.md) | Detecção de limites de contexto, compressão |
|
||||
|
||||
@@ -41,14 +41,6 @@ Configurações gerais para busca e processamento de conteúdo de páginas web.
|
||||
| `fetch_limit_bytes` | int | 10485760 | Tamanho máximo do payload da página web a ser buscado, em bytes (padrão é 10MB). |
|
||||
| `format` | string | "plaintext" | Formato de saída do conteúdo buscado. Opções: `plaintext` ou `markdown` (recomendado). |
|
||||
|
||||
### Brave
|
||||
|
||||
| Config | Tipo | Padrão | Descrição |
|
||||
|---------------|--------|--------|----------------------------|
|
||||
| `enabled` | bool | false | Habilitar pesquisa Brave |
|
||||
| `api_key` | string | - | Chave API do Brave Search |
|
||||
| `max_results` | int | 5 | Número máximo de resultados |
|
||||
|
||||
### DuckDuckGo
|
||||
|
||||
| Config | Tipo | Padrão | Descrição |
|
||||
@@ -56,13 +48,73 @@ Configurações gerais para busca e processamento de conteúdo de páginas web.
|
||||
| `enabled` | bool | true | Habilitar pesquisa DuckDuckGo |
|
||||
| `max_results` | int | 5 | Número máximo de resultados |
|
||||
|
||||
### Baidu Search
|
||||
|
||||
| Config | Tipo | Padrão | Descrição |
|
||||
|---------------|--------|-----------------------------------------------------------------|------------------------------------|
|
||||
| `enabled` | bool | false | Habilitar pesquisa Baidu |
|
||||
| `api_key` | string | - | Chave API Qianfan |
|
||||
| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | URL da API Baidu Search |
|
||||
| `max_results` | int | 10 | Número máximo de resultados |
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"web": {
|
||||
"baidu_search": {
|
||||
"enabled": true,
|
||||
"api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
|
||||
"max_results": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Perplexity
|
||||
|
||||
| Config | Tipo | Padrão | Descrição |
|
||||
|---------------|--------|--------|--------------------------------|
|
||||
| `enabled` | bool | false | Habilitar pesquisa Perplexity |
|
||||
| `api_key` | string | - | Chave API do Perplexity |
|
||||
| `max_results` | int | 5 | Número máximo de resultados |
|
||||
| `enabled` | bool | false | Habilitar pesquisa Perplexity |
|
||||
| `api_key` | string | - | Chave API do Perplexity |
|
||||
| `api_keys` | string[] | - | Várias chaves API do Perplexity para rotação (prioridade sobre `api_key`) |
|
||||
| `max_results` | int | 5 | Número máximo de resultados |
|
||||
|
||||
### Brave
|
||||
|
||||
| Config | Tipo | Padrão | Descrição |
|
||||
|---------------|--------|--------|----------------------------|
|
||||
| `enabled` | bool | false | Habilitar pesquisa Brave |
|
||||
| `api_key` | string | - | Chave API única do Brave Search |
|
||||
| `api_keys` | string[] | - | Várias chaves API do Brave para rotação (prioridade sobre `api_key`) |
|
||||
| `max_results` | int | 5 | Número máximo de resultados |
|
||||
|
||||
### Tavily
|
||||
|
||||
| Config | Tipo | Padrão | Descrição |
|
||||
|---------------|--------|--------|------------------------------------|
|
||||
| `enabled` | bool | false | Habilitar pesquisa Tavily |
|
||||
| `api_key` | string | - | Chave API do Tavily |
|
||||
| `base_url` | string | - | URL base personalizada do Tavily |
|
||||
| `max_results` | int | 0 | Número máximo de resultados (0 = padrão) |
|
||||
|
||||
### SearXNG
|
||||
|
||||
| Config | Tipo | Padrão | Descrição |
|
||||
|---------------|--------|--------------------------|--------------------------------|
|
||||
| `enabled` | bool | false | Habilitar pesquisa SearXNG |
|
||||
| `base_url` | string | `http://localhost:8888` | URL da instância SearXNG |
|
||||
| `max_results` | int | 5 | Número máximo de resultados |
|
||||
|
||||
### GLM Search
|
||||
|
||||
| Config | Tipo | Padrão | Descrição |
|
||||
|-----------------|--------|------------------------------------------------------|----------------------------|
|
||||
| `enabled` | bool | false | Habilitar GLM Search |
|
||||
| `api_key` | string | - | Chave API GLM |
|
||||
| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | URL da API GLM Search |
|
||||
| `search_engine` | string | `search_std` | Tipo de motor de busca |
|
||||
| `max_results` | int | 5 | Número máximo de resultados |
|
||||
|
||||
## Ferramenta Exec
|
||||
|
||||
|
||||
@@ -55,6 +55,31 @@ General settings for fetching and processing webpage content.
|
||||
| `enabled` | bool | true | Enable DuckDuckGo search |
|
||||
| `max_results` | int | 5 | Maximum number of results |
|
||||
|
||||
### Baidu Search
|
||||
|
||||
Baidu Search uses the [Qianfan AI Search API](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5), which is AI-powered and optimized for Chinese-language queries.
|
||||
|
||||
| Config | Type | Default | Description |
|
||||
|---------------|--------|------------------------------------------------------------------|---------------------------|
|
||||
| `enabled` | bool | false | Enable Baidu Search |
|
||||
| `api_key` | string | - | Qianfan API key |
|
||||
| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | Baidu Search API URL |
|
||||
| `max_results` | int | 10 | Maximum number of results |
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"web": {
|
||||
"baidu_search": {
|
||||
"enabled": true,
|
||||
"api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
|
||||
"max_results": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Perplexity
|
||||
|
||||
| Config | Type | Default | Description |
|
||||
|
||||
+51
-1
@@ -13,6 +13,7 @@ Trò chuyện với picoclaw của bạn qua Telegram, Discord, WhatsApp, Matrix
|
||||
| **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) |
|
||||
| **Weixin** | ⭐ Dễ | Quét QR gốc (API Tencent iLink) | [Tài liệu](#weixin) |
|
||||
| **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) |
|
||||
@@ -20,11 +21,12 @@ Trò chuyện với picoclaw của bạn qua Telegram, Discord, WhatsApp, Matrix
|
||||
| **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 | - |
|
||||
| **IRC** | ⭐⭐ Trung bình | Máy chủ + cấu hình TLS | [Tài liệu](#irc) |
|
||||
| **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 | |
|
||||
|
||||
<a id="telegram"></a>
|
||||
<details>
|
||||
<summary><b>Telegram</b> (Khuyến nghị)</summary>
|
||||
|
||||
@@ -65,6 +67,7 @@ Nếu đăng ký lệnh thất bại (lỗi tạm thời mạng/API), kênh vẫ
|
||||
|
||||
</details>
|
||||
|
||||
<a id="discord"></a>
|
||||
<details>
|
||||
<summary><b>Discord</b></summary>
|
||||
|
||||
@@ -138,6 +141,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="whatsapp"></a>
|
||||
<details>
|
||||
<summary><b>WhatsApp</b> (native qua whatsmeow)</summary>
|
||||
|
||||
@@ -165,6 +169,43 @@ Nếu `session_store_path` trống, phiên được lưu tại `<workspace>/what
|
||||
|
||||
</details>
|
||||
|
||||
<a id="weixin"></a>
|
||||
<details>
|
||||
<summary><b>Weixin</b> (WeChat Cá nhân)</summary>
|
||||
|
||||
PicoClaw hỗ trợ kết nối với tài khoản WeChat cá nhân của bạn thông qua API chính thức Tencent iLink.
|
||||
|
||||
**1. Đăng nhập**
|
||||
|
||||
Chạy luồng đăng nhập QR tương tác:
|
||||
```bash
|
||||
picoclaw onboard weixin
|
||||
```
|
||||
Quét mã QR được in ra bằng ứng dụng WeChat trên điện thoại. Sau khi đăng nhập thành công, token sẽ được lưu vào cấu hình.
|
||||
|
||||
**2. Cấu hình**
|
||||
|
||||
(Tùy chọn) Thêm ID người dùng WeChat vào `allow_from` để giới hạn ai có thể nhắn tin với bot:
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"weixin": {
|
||||
"enabled": true,
|
||||
"token": "YOUR_TOKEN",
|
||||
"allow_from": ["YOUR_USER_ID"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**3. Chạy**
|
||||
```bash
|
||||
picoclaw gateway
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<a id="qq"></a>
|
||||
<details>
|
||||
<summary><b>QQ</b></summary>
|
||||
|
||||
@@ -206,6 +247,7 @@ Nếu bạn muốn tạo bot thủ công:
|
||||
|
||||
</details>
|
||||
|
||||
<a id="dingtalk"></a>
|
||||
<details>
|
||||
<summary><b>DingTalk</b></summary>
|
||||
|
||||
@@ -240,6 +282,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="maixcam"></a>
|
||||
<details>
|
||||
<summary><b>MaixCam</b></summary>
|
||||
|
||||
@@ -262,6 +305,7 @@ picoclaw gateway
|
||||
</details>
|
||||
|
||||
|
||||
<a id="matrix"></a>
|
||||
<details>
|
||||
<summary><b>Matrix</b></summary>
|
||||
|
||||
@@ -296,6 +340,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="line"></a>
|
||||
<details>
|
||||
<summary><b>LINE</b></summary>
|
||||
|
||||
@@ -344,6 +389,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="wecom"></a>
|
||||
<details>
|
||||
<summary><b>WeCom (企业微信)</b></summary>
|
||||
|
||||
@@ -458,6 +504,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="feishu"></a>
|
||||
<details>
|
||||
<summary><b>Feishu (Lark)</b></summary>
|
||||
|
||||
@@ -499,6 +546,7 @@ Mở Feishu, tìm tên bot của bạn và bắt đầu trò chuyện. Bạn cũ
|
||||
|
||||
</details>
|
||||
|
||||
<a id="slack"></a>
|
||||
<details>
|
||||
<summary><b>Slack</b></summary>
|
||||
|
||||
@@ -532,6 +580,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="irc"></a>
|
||||
<details>
|
||||
<summary><b>IRC</b></summary>
|
||||
|
||||
@@ -565,6 +614,7 @@ Bot sẽ kết nối đến máy chủ IRC và tham gia các kênh đã chỉ đ
|
||||
|
||||
</details>
|
||||
|
||||
<a id="onebot"></a>
|
||||
<details>
|
||||
<summary><b>OneBot (QQ qua giao thức OneBot)</b></summary>
|
||||
|
||||
|
||||
@@ -216,4 +216,149 @@ Cho tác vụ chạy lâu (tìm kiếm web, gọi API), sử dụng công cụ `
|
||||
|
||||
```markdown
|
||||
# Tác Vụ Định Kỳ
|
||||
|
||||
## Tác Vụ Nhanh (trả lời trực tiếp)
|
||||
|
||||
- Báo giờ hiện tại
|
||||
|
||||
## Tác Vụ Dài (dùng spawn cho bất đồng bộ)
|
||||
|
||||
- Tìm kiếm tin tức AI trên web và tóm tắt
|
||||
- Kiểm tra email và báo cáo tin nhắn quan trọng
|
||||
```
|
||||
|
||||
**Hành vi chính:**
|
||||
|
||||
| Tính năng | Mô tả |
|
||||
| ---------------- | ------------------------------------------------------------------ |
|
||||
| **spawn** | Tạo subagent bất đồng bộ, không chặn heartbeat |
|
||||
| **Ngữ cảnh độc lập** | Subagent có ngữ cảnh riêng, không có lịch sử phiên |
|
||||
| **message tool** | Subagent giao tiếp trực tiếp với người dùng qua message tool |
|
||||
| **Không chặn** | Sau khi spawn, heartbeat tiếp tục tác vụ tiếp theo |
|
||||
|
||||
#### Luồng Giao Tiếp Của Subagent
|
||||
|
||||
```
|
||||
Heartbeat kích hoạt
|
||||
↓
|
||||
Agent đọc HEARTBEAT.md
|
||||
↓
|
||||
Tác vụ dài: spawn subagent
|
||||
↓ ↓
|
||||
Tiếp tục tác vụ tiếp theo Subagent hoạt động độc lập
|
||||
↓ ↓
|
||||
Hoàn thành tất cả tác vụ Subagent dùng công cụ "message"
|
||||
↓ ↓
|
||||
Trả lời HEARTBEAT_OK Người dùng nhận kết quả trực tiếp
|
||||
```
|
||||
|
||||
**Cấu hình:**
|
||||
|
||||
```json
|
||||
{
|
||||
"heartbeat": {
|
||||
"enabled": true,
|
||||
"interval": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Tùy chọn | Mặc định | Mô tả |
|
||||
| ---------- | -------- | -------------------------------------- |
|
||||
| `enabled` | `true` | Bật/tắt heartbeat |
|
||||
| `interval` | `30` | Khoảng thời gian kiểm tra tính bằng phút (tối thiểu: 5) |
|
||||
|
||||
**Biến môi trường:**
|
||||
|
||||
* `PICOCLAW_HEARTBEAT_ENABLED=false` để tắt
|
||||
* `PICOCLAW_HEARTBEAT_INTERVAL=60` để thay đổi khoảng thời gian
|
||||
|
||||
### Providers
|
||||
|
||||
> [!NOTE]
|
||||
> Groq cung cấp chuyển đổi giọng nói thành văn bản miễn phí qua Whisper. Nếu được cấu hình, tin nhắn âm thanh từ bất kỳ kênh nào sẽ được tự động chuyển đổi ở cấp độ agent.
|
||||
|
||||
| Provider | Mục đích | Lấy API Key |
|
||||
| ------------ | --------------------------------------- | ------------------------------------------------------------ |
|
||||
| `gemini` | LLM (Gemini trực tiếp) | [aistudio.google.com](https://aistudio.google.com) |
|
||||
| `zhipu` | LLM (Zhipu trực tiếp) | [bigmodel.cn](https://bigmodel.cn) |
|
||||
| `volcengine` | LLM (Volcengine trực tiếp) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
|
||||
| `openrouter` | LLM (khuyến nghị, truy cập tất cả mô hình) | [openrouter.ai](https://openrouter.ai) |
|
||||
| `anthropic` | LLM (Claude trực tiếp) | [console.anthropic.com](https://console.anthropic.com) |
|
||||
| `openai` | LLM (GPT trực tiếp) | [platform.openai.com](https://platform.openai.com) |
|
||||
| `deepseek` | LLM (DeepSeek trực tiếp) | [platform.deepseek.com](https://platform.deepseek.com) |
|
||||
| `qwen` | LLM (Qwen trực tiếp) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
|
||||
| `groq` | LLM + **Chuyển đổi giọng nói** (Whisper)| [console.groq.com](https://console.groq.com) |
|
||||
| `cerebras` | LLM (Cerebras trực tiếp) | [cerebras.ai](https://cerebras.ai) |
|
||||
| `vivgrid` | LLM (Vivgrid trực tiếp) | [vivgrid.com](https://vivgrid.com) |
|
||||
|
||||
### Cấu Hình Mô Hình (model_list)
|
||||
|
||||
> **Tính năng mới:** PicoClaw hiện sử dụng cách tiếp cận **lấy mô hình làm trung tâm**. Chỉ cần chỉ định định dạng `vendor/model` (ví dụ: `zhipu/glm-4.7`) để thêm provider mới — **không cần thay đổi code!**
|
||||
|
||||
#### Tất Cả Vendor Được Hỗ Trợ
|
||||
|
||||
| Vendor | Tiền tố `model` | API Base mặc định | Giao thức | API Key |
|
||||
| ----------------------- | --------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
|
||||
| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Lấy](https://platform.openai.com) |
|
||||
| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Lấy](https://console.anthropic.com) |
|
||||
| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Lấy](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
|
||||
| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Lấy](https://platform.deepseek.com) |
|
||||
| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Lấy](https://aistudio.google.com/api-keys) |
|
||||
| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Lấy](https://console.groq.com) |
|
||||
| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Lấy](https://dashscope.console.aliyun.com) |
|
||||
| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Cục bộ (không cần key) |
|
||||
| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Lấy](https://openrouter.ai/keys) |
|
||||
| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Lấy](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
|
||||
| **Antigravity** | `antigravity/` | Google Cloud | Custom | Chỉ OAuth |
|
||||
|
||||
#### Cân Bằng Tải
|
||||
|
||||
Cấu hình nhiều endpoint cho cùng tên mô hình — PicoClaw sẽ tự động round-robin:
|
||||
|
||||
```json
|
||||
{
|
||||
"model_list": [
|
||||
{ "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" },
|
||||
{ "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Di Chuyển Từ Cấu Hình `providers` Cũ
|
||||
|
||||
Cấu hình `providers` cũ đã **bị deprecated** nhưng vẫn được hỗ trợ. Xem [docs/migration/model-list-migration.md](../migration/model-list-migration.md).
|
||||
|
||||
### Kiến Trúc Provider
|
||||
|
||||
PicoClaw định tuyến provider theo họ giao thức:
|
||||
|
||||
- **Tương thích OpenAI**: OpenRouter, Groq, Zhipu, endpoint kiểu vLLM và hầu hết các provider khác.
|
||||
- **Anthropic**: Hành vi API Claude gốc.
|
||||
- **Codex/OAuth**: Tuyến xác thực OAuth/token OpenAI.
|
||||
|
||||
### Tác Vụ Đã Lên Lịch / Nhắc Nhở
|
||||
|
||||
PicoClaw hỗ trợ tác vụ theo lịch qua công cụ `cron`.
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"cron": {
|
||||
"enabled": true,
|
||||
"exec_timeout_minutes": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Tác vụ đã lên lịch được lưu trữ bền vững sau khi khởi động lại tại `~/.picoclaw/workspace/cron/`.
|
||||
|
||||
### Chủ Đề Nâng Cao
|
||||
|
||||
| Chủ đề | Mô tả |
|
||||
| ------ | ----- |
|
||||
| [Hệ Thống Hook](../hooks/README.md) | Hook hướng sự kiện: observer, interceptor, approval hook |
|
||||
| [Steering](../steering.md) | Chèn tin nhắn vào vòng lặp agent đang chạy |
|
||||
| [SubTurn](../subturn.md) | Điều phối subagent, kiểm soát đồng thời, vòng đời |
|
||||
| [Quản Lý Ngữ Cảnh](../agent-refactor/context.md) | Phát hiện ranh giới ngữ cảnh, nén |
|
||||
|
||||
@@ -41,14 +41,6 @@ Cài đặt chung để tải và xử lý nội dung trang web.
|
||||
| `fetch_limit_bytes` | int | 10485760 | Kích thước tối đa của payload trang web cần tải, tính bằng byte (mặc định là 10MB). |
|
||||
| `format` | string | "plaintext" | Định dạng đầu ra của nội dung đã tải. Tùy chọn: `plaintext` hoặc `markdown` (khuyến nghị). |
|
||||
|
||||
### Brave
|
||||
|
||||
| Cấu hình | Kiểu | Mặc định | Mô tả |
|
||||
|----------------|--------|----------|----------------------------|
|
||||
| `enabled` | bool | false | Bật tìm kiếm Brave |
|
||||
| `api_key` | string | - | Khóa API Brave Search |
|
||||
| `max_results` | int | 5 | Số kết quả tối đa |
|
||||
|
||||
### DuckDuckGo
|
||||
|
||||
| Cấu hình | Kiểu | Mặc định | Mô tả |
|
||||
@@ -56,13 +48,73 @@ Cài đặt chung để tải và xử lý nội dung trang web.
|
||||
| `enabled` | bool | true | Bật tìm kiếm DuckDuckGo |
|
||||
| `max_results` | int | 5 | Số kết quả tối đa |
|
||||
|
||||
### Baidu Search
|
||||
|
||||
| Cấu hình | Kiểu | Mặc định | Mô tả |
|
||||
|----------------|--------|-----------------------------------------------------------------|------------------------------------|
|
||||
| `enabled` | bool | false | Bật tìm kiếm Baidu |
|
||||
| `api_key` | string | - | Khóa API Qianfan |
|
||||
| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | URL API Baidu Search |
|
||||
| `max_results` | int | 10 | Số kết quả tối đa |
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"web": {
|
||||
"baidu_search": {
|
||||
"enabled": true,
|
||||
"api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
|
||||
"max_results": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Perplexity
|
||||
|
||||
| Cấu hình | Kiểu | Mặc định | Mô tả |
|
||||
|----------------|--------|----------|-------------------------------|
|
||||
| `enabled` | bool | false | Bật tìm kiếm Perplexity |
|
||||
| `api_key` | string | - | Khóa API Perplexity |
|
||||
| `max_results` | int | 5 | Số kết quả tối đa |
|
||||
| `enabled` | bool | false | Bật tìm kiếm Perplexity |
|
||||
| `api_key` | string | - | Khóa API Perplexity |
|
||||
| `api_keys` | string[] | - | Nhiều khóa API Perplexity để xoay vòng (ưu tiên hơn `api_key`) |
|
||||
| `max_results` | int | 5 | Số kết quả tối đa |
|
||||
|
||||
### Brave
|
||||
|
||||
| Cấu hình | Kiểu | Mặc định | Mô tả |
|
||||
|----------------|--------|----------|----------------------------|
|
||||
| `enabled` | bool | false | Bật tìm kiếm Brave |
|
||||
| `api_key` | string | - | Khóa API Brave Search |
|
||||
| `api_keys` | string[] | - | Nhiều khóa API Brave Search để xoay vòng (ưu tiên hơn `api_key`) |
|
||||
| `max_results` | int | 5 | Số kết quả tối đa |
|
||||
|
||||
### Tavily
|
||||
|
||||
| Cấu hình | Kiểu | Mặc định | Mô tả |
|
||||
|----------------|--------|----------|------------------------------------|
|
||||
| `enabled` | bool | false | Bật tìm kiếm Tavily |
|
||||
| `api_key` | string | - | Khóa API Tavily |
|
||||
| `base_url` | string | - | URL cơ sở Tavily tùy chỉnh |
|
||||
| `max_results` | int | 0 | Số kết quả tối đa (0 = mặc định) |
|
||||
|
||||
### SearXNG
|
||||
|
||||
| Cấu hình | Kiểu | Mặc định | Mô tả |
|
||||
|----------------|--------|--------------------------|----------------------------|
|
||||
| `enabled` | bool | false | Bật tìm kiếm SearXNG |
|
||||
| `base_url` | string | `http://localhost:8888` | URL phiên bản SearXNG |
|
||||
| `max_results` | int | 5 | Số kết quả tối đa |
|
||||
|
||||
### GLM Search
|
||||
|
||||
| Cấu hình | Kiểu | Mặc định | Mô tả |
|
||||
|------------------|--------|------------------------------------------------------|----------------------------|
|
||||
| `enabled` | bool | false | Bật GLM Search |
|
||||
| `api_key` | string | - | Khóa API GLM |
|
||||
| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | URL API GLM Search |
|
||||
| `search_engine` | string | `search_std` | Loại công cụ tìm kiếm |
|
||||
| `max_results` | int | 5 | Số kết quả tối đa |
|
||||
|
||||
## Công cụ Exec
|
||||
|
||||
|
||||
+24
-8
@@ -15,7 +15,7 @@ PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方
|
||||
| **Telegram** | ⭐ 简单 | 推荐，支持语音转文字，长轮询无需公网 | [查看文档](../channels/telegram/README.zh.md) |
|
||||
| **Discord** | ⭐ 简单 | Socket Mode，支持群组/私信，Bot 生态成熟 | [查看文档](../channels/discord/README.zh.md) |
|
||||
| **WhatsApp** | ⭐ 简单 | 原生 (QR 扫码) 或 Bridge URL | [查看文档](#whatsapp) |
|
||||
| **Weixin** | ⭐ 简单 | 原生扫码登录 (腾讯 iLink API) | [查看文档](../channels/weixin/README.zh.md) |
|
||||
| **微信 (Weixin)** | ⭐ 简单 | 原生扫码（腾讯 iLink API） | [查看文档](#weixin) |
|
||||
| **Slack** | ⭐ 简单 | **Socket Mode** (无需公网 IP)，企业级支持 | [查看文档](../channels/slack/README.zh.md) |
|
||||
| **Matrix** | ⭐⭐ 中等 | 联邦协议，支持自建 homeserver 与公开服务器 | [查看文档](../channels/matrix/README.zh.md) |
|
||||
| **QQ** | ⭐⭐ 中等 | 官方机器人 API，适合国内社群 | [查看文档](../channels/qq/README.zh.md) |
|
||||
@@ -23,13 +23,14 @@ PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方
|
||||
| **LINE** | ⭐⭐⭐ 较难 | 需要 HTTPS Webhook | [查看文档](../channels/line/README.zh.md) |
|
||||
| **企业微信 (WeCom)** | ⭐⭐⭐ 较难 | 支持群机器人(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) |
|
||||
| **IRC** | ⭐⭐ 中等 | 服务器 + TLS 配置 | - |
|
||||
| **IRC** | ⭐⭐ 中等 | 服务器 + TLS 配置 | [查看文档](#irc) |
|
||||
| **OneBot** | ⭐⭐ 中等 | 兼容 NapCat/Go-CQHTTP，社区生态丰富 | [查看文档](../channels/onebot/README.zh.md) |
|
||||
| **MaixCam** | ⭐ 简单 | 专为 AI 摄像头设计的硬件集成通道 | [查看文档](../channels/maixcam/README.zh.md) |
|
||||
| **Pico** | ⭐ 简单 | PicoClaw 原生协议通道 | |
|
||||
|
||||
---
|
||||
|
||||
<a id="telegram"></a>
|
||||
<details>
|
||||
<summary><b>Telegram</b>（推荐）</summary>
|
||||
|
||||
@@ -70,6 +71,7 @@ Telegram 侧保留的是命令菜单注册能力；通用命令的实际执行
|
||||
|
||||
</details>
|
||||
|
||||
<a id="discord"></a>
|
||||
<details>
|
||||
<summary><b>Discord</b></summary>
|
||||
|
||||
@@ -144,6 +146,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="whatsapp"></a>
|
||||
<details>
|
||||
<summary><b>WhatsApp</b>（原生 whatsmeow）</summary>
|
||||
|
||||
@@ -171,27 +174,30 @@ PicoClaw 支持两种 WhatsApp 连接方式：
|
||||
|
||||
</details>
|
||||
|
||||
<a id="weixin"></a>
|
||||
<details>
|
||||
<summary><b>Weixin</b> (微信个人号)</summary>
|
||||
<summary><b>微信 (Weixin)</b></summary>
|
||||
|
||||
PicoClaw 支持使用腾讯官方 iLink API 连接您的个人微信账号。
|
||||
PicoClaw 通过腾讯 iLink 官方 API 支持连接微信个人号。
|
||||
|
||||
**1. 登录**
|
||||
|
||||
运行交互式扫码登录流程：
|
||||
```bash
|
||||
picoclaw onboard weixin
|
||||
```
|
||||
在终端扫描打印出的二维码。登录成功后，Token 将自动保存到您的配置文件中。
|
||||
用微信手机端扫描打印出的二维码。登录成功后，token 会自动保存到配置文件。
|
||||
|
||||
**2. 配置**
|
||||
（可选）更新 `allow_from` 填写微信 User ID，以限制哪些用户可以给机器人发消息：
|
||||
|
||||
（可选）在 `allow_from` 中填入你的微信用户 ID，限制可以与机器人对话的用户：
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"weixin": {
|
||||
"enabled": true,
|
||||
"token": "你的_TOKEN",
|
||||
"allow_from": ["你的_USER_ID"]
|
||||
"token": "YOUR_TOKEN",
|
||||
"allow_from": ["YOUR_USER_ID"]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -204,6 +210,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="matrix"></a>
|
||||
<details>
|
||||
<summary><b>Matrix</b></summary>
|
||||
|
||||
@@ -238,6 +245,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="qq"></a>
|
||||
<details>
|
||||
<summary><b>QQ</b></summary>
|
||||
|
||||
@@ -279,6 +287,7 @@ QQ 开放平台提供了一键创建 OpenClaw 兼容机器人的页面：
|
||||
|
||||
</details>
|
||||
|
||||
<a id="slack"></a>
|
||||
<details>
|
||||
<summary><b>Slack</b></summary>
|
||||
|
||||
@@ -312,6 +321,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="irc"></a>
|
||||
<details>
|
||||
<summary><b>IRC</b></summary>
|
||||
|
||||
@@ -345,6 +355,7 @@ Bot 将连接到 IRC 服务器并加入指定的频道。
|
||||
|
||||
</details>
|
||||
|
||||
<a id="dingtalk"></a>
|
||||
<details>
|
||||
<summary><b>钉钉 (DingTalk)</b></summary>
|
||||
|
||||
@@ -379,6 +390,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="line"></a>
|
||||
<details>
|
||||
<summary><b>LINE</b></summary>
|
||||
|
||||
@@ -427,6 +439,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="feishu"></a>
|
||||
<details>
|
||||
<summary><b>飞书 (Feishu)</b></summary>
|
||||
|
||||
@@ -468,6 +481,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="wecom"></a>
|
||||
<details>
|
||||
<summary><b>企业微信 (WeCom)</b></summary>
|
||||
|
||||
@@ -582,6 +596,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="onebot"></a>
|
||||
<details>
|
||||
<summary><b>OneBot（通过 OneBot 协议连接 QQ）</b></summary>
|
||||
|
||||
@@ -620,6 +635,7 @@ picoclaw gateway
|
||||
|
||||
</details>
|
||||
|
||||
<a id="maixcam"></a>
|
||||
<details>
|
||||
<summary><b>MaixCam</b></summary>
|
||||
|
||||
|
||||
@@ -256,3 +256,356 @@ Agent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具
|
||||
|
||||
- `PICOCLAW_HEARTBEAT_ENABLED=false` 禁用
|
||||
- `PICOCLAW_HEARTBEAT_INTERVAL=60` 更改间隔
|
||||
|
||||
#### 子 Agent 通信流程
|
||||
|
||||
```
|
||||
心跳触发
|
||||
↓
|
||||
Agent 读取 HEARTBEAT.md
|
||||
↓
|
||||
遇到耗时任务：spawn 子 Agent
|
||||
↓ ↓
|
||||
继续处理下一个任务 子 Agent 独立运行
|
||||
↓ ↓
|
||||
所有任务完成 子 Agent 使用 "message" 工具
|
||||
↓ ↓
|
||||
回复 HEARTBEAT_OK 用户直接收到结果
|
||||
```
|
||||
|
||||
子 Agent 拥有工具访问权限（message、web_search 等），可以独立与用户通信，无需经过主 Agent。
|
||||
|
||||
### Providers（模型提供商）
|
||||
|
||||
> [!NOTE]
|
||||
> Groq 通过 Whisper 提供免费语音转录。配置后，任意渠道的语音消息都会在 Agent 层自动转录为文字。
|
||||
|
||||
| 提供商 | 用途 | 获取 API Key |
|
||||
| ------------ | --------------------------------------- | ------------------------------------------------------------ |
|
||||
| `gemini` | LLM（Gemini 直连） | [aistudio.google.com](https://aistudio.google.com) |
|
||||
| `zhipu` | LLM（智谱直连） | [bigmodel.cn](https://bigmodel.cn) |
|
||||
| `volcengine` | LLM（火山引擎直连） | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
|
||||
| `openrouter` | LLM（推荐，可访问所有模型） | [openrouter.ai](https://openrouter.ai) |
|
||||
| `anthropic` | LLM（Claude 直连） | [console.anthropic.com](https://console.anthropic.com) |
|
||||
| `openai` | LLM（GPT 直连） | [platform.openai.com](https://platform.openai.com) |
|
||||
| `deepseek` | LLM（DeepSeek 直连） | [platform.deepseek.com](https://platform.deepseek.com) |
|
||||
| `qwen` | LLM（通义千问直连） | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
|
||||
| `groq` | LLM + **语音转录**（Whisper） | [console.groq.com](https://console.groq.com) |
|
||||
| `cerebras` | LLM（Cerebras 直连） | [cerebras.ai](https://cerebras.ai) |
|
||||
| `vivgrid` | LLM（Vivgrid 直连） | [vivgrid.com](https://vivgrid.com) |
|
||||
|
||||
### 模型配置 (model_list)
|
||||
|
||||
> **新特性：** PicoClaw 现在采用**以模型为中心**的配置方式。只需指定 `vendor/model` 格式（例如 `zhipu/glm-4.7`）即可接入新提供商——**无需修改任何代码！**
|
||||
|
||||
这一设计同时支持**多 Agent**场景，灵活选择提供商：
|
||||
|
||||
- **不同 Agent 使用不同提供商**：每个 Agent 可以使用独立的 LLM 提供商
|
||||
- **模型降级**：配置主模型和备用模型，提升可用性
|
||||
- **负载均衡**：将请求分发到多个端点
|
||||
- **集中管理**：在一处管理所有提供商配置
|
||||
|
||||
#### 所有支持的厂商
|
||||
|
||||
| 厂商 | `model` 前缀 | 默认 API Base | 协议 | API Key |
|
||||
| ----------------------- | ----------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
|
||||
| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [获取](https://platform.openai.com) |
|
||||
| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [获取](https://console.anthropic.com) |
|
||||
| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [获取](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
|
||||
| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [获取](https://platform.deepseek.com) |
|
||||
| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [获取](https://aistudio.google.com/api-keys) |
|
||||
| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [获取](https://console.groq.com) |
|
||||
| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [获取](https://platform.moonshot.cn) |
|
||||
| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [获取](https://dashscope.console.aliyun.com) |
|
||||
| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [获取](https://build.nvidia.com) |
|
||||
| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | 本地（无需 Key） |
|
||||
| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [获取](https://openrouter.ai/keys) |
|
||||
| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | 你的 LiteLLM 代理 Key |
|
||||
| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | 本地 |
|
||||
| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [获取](https://cerebras.ai) |
|
||||
| **火山引擎 (豆包)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [获取](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
|
||||
| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | — |
|
||||
| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [获取](https://www.byteplus.com) |
|
||||
| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [获取](https://vivgrid.com) |
|
||||
| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [获取](https://longcat.chat/platform) |
|
||||
| **ModelScope (魔搭)** | `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [获取](https://modelscope.cn/my/tokens) |
|
||||
| **Antigravity** | `antigravity/` | Google Cloud | Custom | 仅 OAuth |
|
||||
| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | — |
|
||||
|
||||
#### 基础配置
|
||||
|
||||
```json
|
||||
{
|
||||
"model_list": [
|
||||
{
|
||||
"model_name": "ark-code-latest",
|
||||
"model": "volcengine/ark-code-latest",
|
||||
"api_key": "sk-your-api-key"
|
||||
},
|
||||
{
|
||||
"model_name": "gpt-5.4",
|
||||
"model": "openai/gpt-5.4",
|
||||
"api_key": "sk-your-openai-key"
|
||||
},
|
||||
{
|
||||
"model_name": "claude-sonnet-4.6",
|
||||
"model": "anthropic/claude-sonnet-4.6",
|
||||
"api_key": "sk-ant-your-key"
|
||||
},
|
||||
{
|
||||
"model_name": "glm-4.7",
|
||||
"model": "zhipu/glm-4.7",
|
||||
"api_key": "your-zhipu-key"
|
||||
}
|
||||
],
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": "gpt-5.4"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 各厂商配置示例
|
||||
|
||||
<details>
|
||||
<summary><b>OpenAI</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "gpt-5.4",
|
||||
"model": "openai/gpt-5.4",
|
||||
"api_key": "sk-..."
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>火山引擎（豆包）</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "ark-code-latest",
|
||||
"model": "volcengine/ark-code-latest",
|
||||
"api_key": "sk-..."
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>智谱 AI (GLM)</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "glm-4.7",
|
||||
"model": "zhipu/glm-4.7",
|
||||
"api_key": "your-key"
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>DeepSeek</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "deepseek-chat",
|
||||
"model": "deepseek/deepseek-chat",
|
||||
"api_key": "sk-..."
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Anthropic</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "claude-sonnet-4.6",
|
||||
"model": "anthropic/claude-sonnet-4.6",
|
||||
"api_key": "sk-ant-your-key"
|
||||
}
|
||||
```
|
||||
|
||||
> 运行 `picoclaw auth login --provider anthropic` 粘贴 API Token。
|
||||
|
||||
如需直连 Anthropic 原生接口（不兼容 OpenAI 格式的端点）：
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "claude-opus-4-6",
|
||||
"model": "anthropic-messages/claude-opus-4-6",
|
||||
"api_key": "sk-ant-your-key",
|
||||
"api_base": "https://api.anthropic.com"
|
||||
}
|
||||
```
|
||||
|
||||
> 当端点不支持 OpenAI 兼容格式（`/v1/chat/completions`），需要 Anthropic 原生 `/v1/messages` 时使用 `anthropic-messages`。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Ollama（本地）</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "llama3",
|
||||
"model": "ollama/llama3"
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>自定义代理 / LiteLLM</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"model_name": "my-custom-model",
|
||||
"model": "openai/custom-model",
|
||||
"api_base": "https://my-proxy.com/v1",
|
||||
"api_key": "sk-..."
|
||||
}
|
||||
```
|
||||
|
||||
PicoClaw 只剥离最外层的 `litellm/` 前缀再发送请求，因此 `litellm/lite-gpt4` 发送 `lite-gpt4`，而 `litellm/openai/gpt-4o` 发送 `openai/gpt-4o`。
|
||||
|
||||
</details>
|
||||
|
||||
#### 负载均衡
|
||||
|
||||
为同一模型名称配置多个端点，PicoClaw 会自动轮询：
|
||||
|
||||
```json
|
||||
{
|
||||
"model_list": [
|
||||
{
|
||||
"model_name": "gpt-5.4",
|
||||
"model": "openai/gpt-5.4",
|
||||
"api_base": "https://api1.example.com/v1",
|
||||
"api_key": "sk-key1"
|
||||
},
|
||||
{
|
||||
"model_name": "gpt-5.4",
|
||||
"model": "openai/gpt-5.4",
|
||||
"api_base": "https://api2.example.com/v1",
|
||||
"api_key": "sk-key2"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 从旧版 `providers` 配置迁移
|
||||
|
||||
旧版 `providers` 配置**已废弃**，但仍向后兼容。完整迁移指南见 [docs/migration/model-list-migration.md](../migration/model-list-migration.md)。
|
||||
|
||||
### Provider 架构
|
||||
|
||||
PicoClaw 按协议族路由提供商：
|
||||
|
||||
- **OpenAI 兼容**：OpenRouter、Groq、智谱、vLLM 风格端点及大多数其他提供商。
|
||||
- **Anthropic**：Claude 原生 API 行为。
|
||||
- **Codex/OAuth**：OpenAI OAuth/Token 认证路由。
|
||||
|
||||
这使运行时保持轻量，同时让接入新的 OpenAI 兼容后端基本只需配置 `api_base` + `api_key`。
|
||||
|
||||
<details>
|
||||
<summary><b>智谱（旧版 providers 格式）</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"workspace": "~/.picoclaw/workspace",
|
||||
"model": "glm-4.7",
|
||||
"max_tokens": 8192,
|
||||
"temperature": 0.7,
|
||||
"max_tool_iterations": 20
|
||||
}
|
||||
},
|
||||
"providers": {
|
||||
"zhipu": {
|
||||
"api_key": "Your API Key",
|
||||
"api_base": "https://open.bigmodel.cn/api/paas/v4"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>完整配置示例</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": "anthropic/claude-opus-4-5"
|
||||
}
|
||||
},
|
||||
"session": {
|
||||
"dm_scope": "per-channel-peer",
|
||||
"backlog_limit": 20
|
||||
},
|
||||
"providers": {
|
||||
"openrouter": {
|
||||
"api_key": "sk-or-v1-xxx"
|
||||
},
|
||||
"groq": {
|
||||
"api_key": "gsk_xxx"
|
||||
}
|
||||
},
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"enabled": true,
|
||||
"token": "123456:ABC...",
|
||||
"allow_from": ["123456789"]
|
||||
}
|
||||
},
|
||||
"tools": {
|
||||
"web": {
|
||||
"duckduckgo": {
|
||||
"enabled": true,
|
||||
"max_results": 5
|
||||
}
|
||||
}
|
||||
},
|
||||
"heartbeat": {
|
||||
"enabled": true,
|
||||
"interval": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### 定时任务 / 提醒
|
||||
|
||||
PicoClaw 通过 `cron` 工具支持 cron 风格的定时任务。Agent 可以设置、列出和取消在指定时间触发的提醒或周期性任务。
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"cron": {
|
||||
"enabled": true,
|
||||
"exec_timeout_minutes": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
定时任务在重启后持久保存，存储于 `~/.picoclaw/workspace/cron/`。
|
||||
|
||||
### 进阶主题
|
||||
|
||||
| 主题 | 说明 |
|
||||
| ---- | ---- |
|
||||
| [Hook 系统](../hooks/README.zh.md) | 事件驱动 Hook：观察者、拦截器、审批 Hook |
|
||||
| [Steering](../steering.md) | 在工具调用间向运行中的 Agent 注入消息 |
|
||||
| [SubTurn](../subturn.md) | 子 Agent 协调、并发控制、生命周期管理 |
|
||||
| [上下文管理](../agent-refactor/context.md) | 上下文边界检测、主动预算检查、压缩策略 |
|
||||
|
||||
@@ -41,30 +41,30 @@ Web 工具用于网页搜索和抓取。
|
||||
| `fetch_limit_bytes` | int | 10485760 | 抓取网页负载的最大大小，单位为字节（默认 10MB）。 |
|
||||
| `format` | string | "plaintext" | 抓取内容的输出格式。选项：`plaintext` 或 `markdown`（推荐）。 |
|
||||
|
||||
### Brave
|
||||
### 百度搜索
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 描述 |
|
||||
|---------------|----------|--------|------------------------------------------------|
|
||||
| `enabled` | bool | false | 启用 Brave 搜索 |
|
||||
| `api_key` | string | - | Brave Search API 密钥 |
|
||||
| `api_keys` | string[] | - | 多个 API 密钥轮换（优先于 `api_key`） |
|
||||
| `max_results` | int | 5 | 最大结果数 |
|
||||
使用[千帆 AI 搜索 API](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5)，国内访问稳定，中文搜索效果好。
|
||||
|
||||
### DuckDuckGo
|
||||
| 配置项 | 类型 | 默认值 | 描述 |
|
||||
|---------------|--------|----------------------------------------------------------------|-----------------------|
|
||||
| `enabled` | bool | false | 启用百度搜索 |
|
||||
| `api_key` | string | - | 千帆 API 密钥 |
|
||||
| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | 百度搜索 API URL |
|
||||
| `max_results` | int | 10 | 最大结果数 |
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 描述 |
|
||||
|---------------|------|--------|-----------------------|
|
||||
| `enabled` | bool | true | 启用 DuckDuckGo 搜索 |
|
||||
| `max_results` | int | 5 | 最大结果数 |
|
||||
|
||||
### Perplexity
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 描述 |
|
||||
|---------------|----------|--------|------------------------------------------------|
|
||||
| `enabled` | bool | false | 启用 Perplexity 搜索 |
|
||||
| `api_key` | string | - | Perplexity API 密钥 |
|
||||
| `api_keys` | string[] | - | 多个 API 密钥轮换（优先于 `api_key`） |
|
||||
| `max_results` | int | 5 | 最大结果数 |
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"web": {
|
||||
"baidu_search": {
|
||||
"enabled": true,
|
||||
"api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
|
||||
"max_results": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Tavily
|
||||
|
||||
@@ -75,14 +75,6 @@ Web 工具用于网页搜索和抓取。
|
||||
| `base_url` | string | - | 自定义 Tavily API 基础 URL |
|
||||
| `max_results` | int | 0 | 最大结果数（0 = 默认） |
|
||||
|
||||
### SearXNG
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 描述 |
|
||||
|---------------|--------|--------------------------|-----------------------|
|
||||
| `enabled` | bool | false | 启用 SearXNG 搜索 |
|
||||
| `base_url` | string | `http://localhost:8888` | SearXNG 实例 URL |
|
||||
| `max_results` | int | 5 | 最大结果数 |
|
||||
|
||||
### GLM Search
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 描述 |
|
||||
@@ -93,6 +85,45 @@ Web 工具用于网页搜索和抓取。
|
||||
| `search_engine` | string | `search_std` | 搜索引擎类型 |
|
||||
| `max_results` | int | 5 | 最大结果数 |
|
||||
|
||||
### DuckDuckGo
|
||||
|
||||
> ⚠️ 国内访问困难，建议搭配代理使用。
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 描述 |
|
||||
|---------------|------|--------|-----------------------|
|
||||
| `enabled` | bool | true | 启用 DuckDuckGo 搜索 |
|
||||
| `max_results` | int | 5 | 最大结果数 |
|
||||
|
||||
### Perplexity
|
||||
|
||||
> ⚠️ 国内访问困难，建议搭配代理使用。
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 描述 |
|
||||
|---------------|----------|--------|------------------------------------------------|
|
||||
| `enabled` | bool | false | 启用 Perplexity 搜索 |
|
||||
| `api_key` | string | - | Perplexity API 密钥 |
|
||||
| `api_keys` | string[] | - | 多个 API 密钥轮换（优先于 `api_key`） |
|
||||
| `max_results` | int | 5 | 最大结果数 |
|
||||
|
||||
### Brave
|
||||
|
||||
> ⚠️ 国内访问困难，建议搭配代理使用。
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 描述 |
|
||||
|---------------|----------|--------|------------------------------------------------|
|
||||
| `enabled` | bool | false | 启用 Brave 搜索 |
|
||||
| `api_key` | string | - | Brave Search API 密钥 |
|
||||
| `api_keys` | string[] | - | 多个 API 密钥轮换（优先于 `api_key`） |
|
||||
| `max_results` | int | 5 | 最大结果数 |
|
||||
|
||||
### SearXNG
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 描述 |
|
||||
|---------------|--------|--------------------------|-----------------------|
|
||||
| `enabled` | bool | false | 启用 SearXNG 搜索 |
|
||||
| `base_url` | string | `http://localhost:8888` | SearXNG 实例 URL |
|
||||
| `max_results` | int | 5 | 最大结果数 |
|
||||
|
||||
### 其他 Web 设置
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 描述 |
|
||||
|
||||
Reference in New Issue
Block a user