lzh/picoclaw
1
0
Fork 0
mirror of https://github.com/sipeed/picoclaw.git synced 2026-06-12 18:08:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: fix inaccuracies, add translations, and expand channel docs (#1837)

Browse Source 
## Config field fixes (cross-verified against Go source)
- MaixCam: server_address → host + port
- IRC: use_tls → tls, channels_to_join → channels (all 6 languages)
- WeCom AI Bot: callback port 18791 → 18790
- credential_encryption: base_url → api_base, add required model field,
  remove incorrect passphrase-only mode docs
- providers.md: agents.defaults.model → model_name (×4), remove
  non-existent session.backlog_limit
- migration guide, troubleshooting: agents.defaults.model → model_name
- ANTIGRAVITY_AUTH: fix file path, Go 1.21 → 1.25, model → model_name
- spawn-tasks: fix truncated file, add Heartbeat introduction
- tools_configuration: add Tavily/SearXNG/GLMSearch, exec allow_remote/
  timeout_seconds/custom_allow_patterns, cron allow_command, skills
  github/search_cache, clawhub timeout/max_zip_size/max_response_size
- configuration: fix builtin skills path (build-time embedded, not cwd),
  HEARTBEAT.md marked auto-generated

## Broken link fixes (15 total)
- chat-apps.md: WeCom/Matrix links with wrong relative paths
- providers.md: migration link with extra docs/ prefix
- hardware-compatibility.md: README links with wrong depth (all 5 langs)
- chat-apps.md: WhatsApp dead links → anchor links (zh/ja)

## Getting-started accuracy
- README (all 6 langs): add picoclaw.io as recommended download,
  add missing picoclaw model CLI command
- docker.md: clarify first-run trigger condition (all 6 langs)
- configuration.md: fix builtin skills path description (all 6 langs)

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

## Feishu channel
- Update setup flow: WebSocket/SDK mode, no webhook URL needed
- Preserve Lark international domain note (all 6 languages)

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

## New translations (25 files, 5 docs × 5 languages)
debug.md, credential_encryption.md, hardware-compatibility.md,
ANTIGRAVITY_AUTH.md, ANTIGRAVITY_USAGE.md → zh/ja/fr/pt-br/vi

## Channel docs (6 languages each, 60 new files)
telegram, discord, qq, feishu, maixcam, dingtalk, line, slack, onebot,
wecom/wecom_aibot, wecom/wecom_app, wecom/wecom_bot

Co-authored-by: BeaconCat <BeaconCat@users.noreply.github.com>
This commit is contained in:
BeaconCat
2026-03-20 22:37:05 +08:00
committed by GitHub
parent 0fe058254c
commit 403ceb39be
142 changed files with 11104 additions and 367 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ANTIGRAVITY_AUTH.md
+4 -4
View File
@@ -438,7 +438,7 @@ type ProviderAuthResult = {
### 1. Required Environment/Dependencies
- Go ≥ 1.21
- Go ≥ 1.25
- PicoClaw codebase (`pkg/providers/` and `pkg/auth/`)
- `crypto` and `net/http` standard library packages
@@ -584,7 +584,7 @@ Each SSE message (`data: {...}`) is wrapped in a `response` field:
],
"agents": {
"defaults": {
"model": "gemini-flash"
"model_name": "gemini-flash"
}
}
}
@@ -674,7 +674,7 @@ Add a default entry in `pkg/config/defaults.go`:
#### 5. Add Auth Support (Optional)
If your provider requires OAuth or special authentication, add a case to `cmd/picoclaw/cmd_auth.go`:
If your provider requires OAuth or special authentication, add a case to `cmd/picoclaw/internal/auth/helpers.go`:
```go
case "your-provider":
@@ -736,7 +736,7 @@ export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/m
- `pkg/auth/store.go` - Auth credential storage (`~/.picoclaw/auth.json`)
- `pkg/providers/factory.go` - Provider factory and protocol routing
- `pkg/providers/types.go` - Provider interface definitions
- `cmd/picoclaw/cmd_auth.go` - Auth CLI commands
- `cmd/picoclaw/internal/auth/helpers.go` - Auth CLI commands
- **Documentation:**
- `docs/ANTIGRAVITY_USAGE.md` - Antigravity usage guide
docs/channels/dingtalk/README.fr.md
+35
View File
@@ -0,0 +1,35 @@
> Retour au [README](../../../README.fr.md)
# DingTalk
DingTalk est la plateforme de communication d'entreprise d'Alibaba, très populaire dans les milieux professionnels chinois. Elle utilise un SDK de streaming pour maintenir des connexions persistantes.
## Configuration
```json
{
"channels": {
"dingtalk": {
"enabled": true,
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"allow_from": []
}
}
}
```
| Champ | Type | Requis | Description |
| ------------- | ------ | ------ | ---------------------------------------------------------------- |
| enabled | bool | Oui | Activer ou non le canal DingTalk |
| client_id | string | Oui | Client ID de l'application DingTalk |
| client_secret | string | Oui | Client Secret de l'application DingTalk |
| allow_from | array | Non | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs |
## Procédure de configuration
1. Rendez-vous sur la [plateforme ouverte DingTalk](https://open.dingtalk.com/)
2. Créez une application interne d'entreprise
3. Obtenez le Client ID et le Client Secret depuis les paramètres de l'application
4. Configurez OAuth et les abonnements aux événements (si nécessaire)
5. Renseignez le Client ID et le Client Secret dans le fichier de configuration
docs/channels/dingtalk/README.ja.md
+35
View File
@@ -0,0 +1,35 @@
> [README](../../../README.ja.md) に戻る
# DingTalk
DingTalkはアリババの企業向けコミュニケーションプラットフォームで、中国のビジネス環境で広く利用されています。ストリーミング SDK を使用して持続的な接続を維持します。
## 設定
```json
{
"channels": {
"dingtalk": {
"enabled": true,
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"allow_from": []
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ------------- | ------ | ---- | -------------------------------------------- |
| enabled | bool | はい | DingTalk チャンネルを有効にするかどうか |
| client_id | string | はい | DingTalk アプリケーションの Client ID |
| client_secret | string | はい | DingTalk アプリケーションの Client Secret |
| allow_from | array | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可 |
## セットアップ手順
1. [DingTalk オープンプラットフォーム](https://open.dingtalk.com/) にアクセスする
2. 企業内部アプリケーションを作成する
3. アプリケーション設定から Client ID と Client Secret を取得する
4. OAuth とイベントサブスクリプションを設定する（必要な場合）
5. Client ID と Client Secret を設定ファイルに入力する
docs/channels/dingtalk/README.md
+35
View File
@@ -0,0 +1,35 @@
> Back to [README](../../../README.md)
# DingTalk
DingTalk is Alibaba's enterprise communication platform, widely used in Chinese workplaces. It uses a streaming SDK to maintain persistent connections.
## Configuration
```json
{
"channels": {
"dingtalk": {
"enabled": true,
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"allow_from": []
}
}
}
```
| Field | Type | Required | Description |
| ------------- | ------ | -------- | -------------------------------------------------------- |
| enabled | bool | Yes | Whether to enable the DingTalk channel |
| client_id | string | Yes | Client ID of the DingTalk application |
| client_secret | string | Yes | Client Secret of the DingTalk application |
| allow_from | array | No | User ID whitelist; empty means all users are allowed |
## Setup
1. Go to the [DingTalk Open Platform](https://open.dingtalk.com/)
2. Create an internal enterprise application
3. Obtain the Client ID and Client Secret from the application settings
4. Configure OAuth and event subscriptions (if needed)
5. Fill in the Client ID and Client Secret in the configuration file
docs/channels/dingtalk/README.pt-br.md
+35
View File
@@ -0,0 +1,35 @@
> Voltar ao [README](../../../README.pt-br.md)
# DingTalk
DingTalk é a plataforma de comunicação empresarial da Alibaba, amplamente utilizada no ambiente corporativo chinês. Ela usa um SDK de streaming para manter conexões persistentes.
## Configuração
```json
{
"channels": {
"dingtalk": {
"enabled": true,
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"allow_from": []
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ------------- | ------ | ----------- | ---------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal DingTalk deve ser habilitado |
| client_id | string | Sim | Client ID do aplicativo DingTalk |
| client_secret | string | Sim | Client Secret do aplicativo DingTalk |
| allow_from | array | Não | Lista de permissão de IDs de usuário; vazio permite todos |
## Configuração passo a passo
1. Acesse a [Plataforma Aberta DingTalk](https://open.dingtalk.com/)
2. Crie um aplicativo interno corporativo
3. Obtenha o Client ID e o Client Secret nas configurações do aplicativo
4. Configure OAuth e assinaturas de eventos (se necessário)
5. Preencha o Client ID e o Client Secret no arquivo de configuração
docs/channels/dingtalk/README.vi.md
+35
View File
@@ -0,0 +1,35 @@
> Quay lại [README](../../../README.vi.md)
# DingTalk
DingTalk là nền tảng giao tiếp doanh nghiệp của Alibaba, được sử dụng rộng rãi trong môi trường làm việc tại Trung Quốc. Nền tảng này sử dụng SDK streaming để duy trì kết nối liên tục.
## Cấu hình
```json
{
"channels": {
"dingtalk": {
"enabled": true,
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"allow_from": []
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ------------- | ------ | -------- | ---------------------------------------------------------------- |
| enabled | bool | Có | Có bật kênh DingTalk hay không |
| client_id | string | Có | Client ID của ứng dụng DingTalk |
| client_secret | string | Có | Client Secret của ứng dụng DingTalk |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống cho phép tất cả |
## Quy trình thiết lập
1. Truy cập [Nền tảng mở DingTalk](https://open.dingtalk.com/)
2. Tạo một ứng dụng nội bộ doanh nghiệp
3. Lấy Client ID và Client Secret từ cài đặt ứng dụng
4. Cấu hình OAuth và đăng ký sự kiện (nếu cần)
5. Điền Client ID và Client Secret vào file cấu hình
docs/channels/dingtalk/README.zh.md
+2
View File
@@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# 钉钉
钉钉是阿里巴巴的企业通讯平台，在中国职场中广受欢迎。它采用流式 SDK 来维持持久连接。
docs/channels/discord/README.fr.md
+39
View File
@@ -0,0 +1,39 @@
> Retour au [README](../../../README.fr.md)
# Discord
Discord est une application gratuite de chat vocal, vidéo et textuel conçue pour les communautés. PicoClaw se connecte aux serveurs Discord via l'API Bot Discord, avec prise en charge de la réception et de l'envoi de messages.
## Configuration
```json
{
"channels": {
"discord": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"allow_from": ["YOUR_USER_ID"],
"group_trigger": {
"mention_only": false
}
}
}
}
```
| Champ | Type | Requis | Description |
| ------------- | ------ | ------ | --------------------------------------------------------------------------- |
| enabled | bool | Oui | Activer ou non le canal Discord |
| token | string | Oui | Token du bot Discord |
| allow_from | array | Non | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
| group_trigger | object | Non | Paramètres de déclenchement de groupe (exemple : { "mention_only": false }) |
## Configuration initiale
1. Accéder au [Portail des développeurs Discord](https://discord.com/developers/applications) et créer une nouvelle application
2. Activer les Intents :
- Message Content Intent
- Server Members Intent
3. Obtenir le Token du bot
4. Renseigner le Token du bot dans le fichier de configuration
5. Inviter le bot sur le serveur et lui accorder les permissions nécessaires (ex. envoyer des messages, lire l'historique des messages)
docs/channels/discord/README.ja.md
+39
View File
@@ -0,0 +1,39 @@
> [README](../../../README.ja.md) に戻る
# Discord
Discord はコミュニティ向けに設計された無料の音声・ビデオ・テキストチャットアプリケーションです。PicoClaw は Discord Bot API を通じて Discord サーバーに接続し、メッセージの受信と送信をサポートします。
## 設定
```json
{
"channels": {
"discord": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"allow_from": ["YOUR_USER_ID"],
"group_trigger": {
"mention_only": false
}
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ------------- | ------ | ------ | ----------------------------------------------------------------- |
| enabled | bool | はい | Discord チャンネルを有効にするかどうか |
| token | string | はい | Discord ボットトークン |
| allow_from | array | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可 |
| group_trigger | object | いいえ | グループトリガー設定（例: { "mention_only": false }） |
## セットアップ手順
1. [Discord 開発者ポータル](https://discord.com/developers/applications) にアクセスして新しいアプリケーションを作成する
2. Intents を有効にする:
- Message Content Intent
- Server Members Intent
3. Bot トークンを取得する
4. 設定ファイルに Bot トークンを入力する
5. ボットをサーバーに招待し、必要な権限を付与する（例: メッセージの送信、メッセージ履歴の読み取りなど）
docs/channels/discord/README.md
+39
View File
@@ -0,0 +1,39 @@
> Back to [README](../../../README.md)
# Discord
Discord is a free voice, video, and text chat application designed for communities. PicoClaw connects to Discord servers via the Discord Bot API, supporting both receiving and sending messages.
## Configuration
```json
{
"channels": {
"discord": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"allow_from": ["YOUR_USER_ID"],
"group_trigger": {
"mention_only": false
}
}
}
}
```
| Field | Type | Required | Description |
| ------------- | ------ | -------- | --------------------------------------------------------------------------- |
| enabled | bool | Yes | Whether to enable the Discord channel |
| token | string | Yes | Discord Bot Token |
| allow_from | array | No | Allowlist of user IDs; empty means all users are allowed |
| group_trigger | object | No | Group trigger settings (example: { "mention_only": false }) |
## Setup
1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and create a new application
2. Enable Intents:
- Message Content Intent
- Server Members Intent
3. Obtain the Bot Token
4. Fill in the Bot Token in the configuration file
5. Invite the bot to your server and grant the necessary permissions (e.g. Send Messages, Read Message History)
docs/channels/discord/README.pt-br.md
+39
View File
@@ -0,0 +1,39 @@
> Voltar ao [README](../../../README.pt-br.md)
# Discord
Discord é um aplicativo gratuito de chat de voz, vídeo e texto projetado para comunidades. O PicoClaw se conecta a servidores Discord via Discord Bot API, com suporte para receber e enviar mensagens.
## Configuração
```json
{
"channels": {
"discord": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"allow_from": ["YOUR_USER_ID"],
"group_trigger": {
"mention_only": false
}
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ------------- | ------ | ----------- | --------------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal Discord deve ser habilitado |
| token | string | Sim | Token do Bot Discord |
| allow_from | array | Não | Lista de IDs de usuários permitidos; vazio significa todos os usuários |
| group_trigger | object | Não | Configurações de gatilho de grupo (exemplo: { "mention_only": false }) |
## Configuração inicial
1. Acesse o [Portal de Desenvolvedores do Discord](https://discord.com/developers/applications) e crie uma nova aplicação
2. Habilite os Intents:
- Message Content Intent
- Server Members Intent
3. Obtenha o Token do Bot
4. Preencha o Token do Bot no arquivo de configuração
5. Convide o bot para o servidor e conceda as permissões necessárias (ex. enviar mensagens, ler histórico de mensagens)
docs/channels/discord/README.vi.md
+39
View File
@@ -0,0 +1,39 @@
> Quay lại [README](../../../README.vi.md)
# Discord
Discord là ứng dụng chat thoại, video và văn bản miễn phí được thiết kế cho cộng đồng. PicoClaw kết nối với máy chủ Discord qua Discord Bot API, hỗ trợ nhận và gửi tin nhắn.
## Cấu hình
```json
{
"channels": {
"discord": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"allow_from": ["YOUR_USER_ID"],
"group_trigger": {
"mention_only": false
}
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ------------- | ------ | -------- | --------------------------------------------------------------------------- |
| enabled | bool | Có | Có bật kênh Discord hay không |
| token | string | Có | Token Bot Discord |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả |
| group_trigger | object | Không | Cài đặt kích hoạt nhóm (ví dụ: { "mention_only": false }) |
## Hướng dẫn thiết lập
1. Truy cập [Discord Developer Portal](https://discord.com/developers/applications) và tạo ứng dụng mới
2. Bật các Intents:
- Message Content Intent
- Server Members Intent
3. Lấy Bot Token
4. Điền Bot Token vào file cấu hình
5. Mời bot vào máy chủ và cấp các quyền cần thiết (ví dụ: gửi tin nhắn, đọc lịch sử tin nhắn)
docs/channels/discord/README.zh.md
+2
View File
@@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# Discord
Discord 是一个专为社区设计的免费语音、视频和文本聊天应用。PicoClaw 通过 Discord Bot API 连接到 Discord 服务器，支持接收和发送消息。
docs/channels/feishu/README.fr.md
+48
View File
@@ -0,0 +1,48 @@
> Retour au [README](../../../README.fr.md)
# Feishu
Feishu (nom international : Lark) est une plateforme de collaboration d'entreprise de ByteDance. Elle prend en charge les marchés chinois et mondiaux via des connexions WebSocket pilotées par événements.
## Configuration
```json
{
"channels": {
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"allow_from": []
}
}
}
```
| Champ | Type | Requis | Description |
| --------------------- | ------ | ------ | --------------------------------------------------------------------------- |
| enabled | bool | Oui | Activer ou non le canal Feishu |
| app_id | string | Oui | App ID de l'application Feishu (commence par `cli_`) |
| app_secret | string | Oui | App Secret de l'application Feishu |
| encrypt_key | string | Non | Clé de chiffrement pour les callbacks d'événements |
| verification_token | string | Non | Token utilisé pour la vérification des événements Webhook |
| allow_from | array | Non | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
| random_reaction_emoji | array | Non | Liste d'emojis de réaction aléatoires ; vide utilise le "Pin" par défaut |
## Configuration initiale
1. Accéder à la [plateforme ouverte Feishu](https://open.feishu.cn/) et créer une application
2. Activer la capacité **Bot** dans les paramètres de l'application
3. Créer une version et publier l'application (la configuration prend effet après la publication)
4. Obtenir l'**App ID** (commence par `cli_`) et l'**App Secret**
5. Renseigner l'App ID et l'App Secret dans le fichier de configuration PicoClaw
6. Exécuter `picoclaw gateway` pour démarrer le service
7. Rechercher le nom du bot dans Feishu et commencer une conversation
> PicoClaw se connecte à Feishu en mode WebSocket/SDK — aucune adresse de callback publique ni URL Webhook n'est requise.
>
> `encrypt_key` et `verification_token` sont optionnels ; l'activation du chiffrement des événements est recommandée pour les environnements de production.
>
> Pour les références d'emojis personnalisés, voir : [Liste des emojis Feishu](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
docs/channels/feishu/README.ja.md
+48
View File
@@ -0,0 +1,48 @@
> [README](../../../README.ja.md) に戻る
# 飛書（Feishu）
飛書（国際名：Lark）は ByteDance が提供するエンタープライズコラボレーションプラットフォームです。イベント駆動型の WebSocket 接続を通じて、中国および世界市場の両方をサポートします。
## 設定
```json
{
"channels": {
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"allow_from": []
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| --------------------- | ------ | ------ | ----------------------------------------------------------------- |
| enabled | bool | はい | 飛書チャンネルを有効にするかどうか |
| app_id | string | はい | 飛書アプリケーションの App ID（`cli_` で始まる） |
| app_secret | string | はい | 飛書アプリケーションの App Secret |
| encrypt_key | string | いいえ | イベントコールバックの暗号化キー |
| verification_token | string | いいえ | Webhook イベント検証に使用するトークン |
| allow_from | array | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可 |
| random_reaction_emoji | array | いいえ | ランダムに追加する絵文字のリスト。空の場合はデフォルトの "Pin" を使用 |
## セットアップ手順
1. [飛書オープンプラットフォーム](https://open.feishu.cn/) にアクセスしてアプリケーションを作成する
2. アプリケーション設定で**ボット**機能を有効にする
3. バージョンを作成してアプリケーションを公開する（公開後に設定が有効になる）
4. **App ID**（`cli_` で始まる）と **App Secret** を取得する
5. PicoClaw 設定ファイルに App ID と App Secret を入力する
6. `picoclaw gateway` を実行してサービスを起動する
7. 飛書でボット名を検索して会話を始める
> PicoClaw は WebSocket/SDK モードで飛書に接続するため、公開コールバックアドレスや Webhook URL の設定は不要です。
>
> `encrypt_key` と `verification_token` はオプションですが、本番環境ではイベント暗号化を有効にすることを推奨します。
>
> カスタム絵文字の参考：[飛書絵文字リスト](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
docs/channels/feishu/README.md
+48
View File
@@ -0,0 +1,48 @@
> Back to [README](../../../README.md)
# Feishu
Feishu (international name: Lark) is an enterprise collaboration platform by ByteDance. It supports both Chinese and global markets through event-driven WebSocket connections.
## Configuration
```json
{
"channels": {
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"allow_from": []
}
}
}
```
| Field | Type | Required | Description |
| --------------------- | ------ | -------- | ------------------------------------------------------------------ |
| enabled | bool | Yes | Whether to enable the Feishu channel |
| app_id | string | Yes | App ID of the Feishu application (starts with `cli_`) |
| app_secret | string | Yes | App Secret of the Feishu application |
| encrypt_key | string | No | Encryption key for event callbacks |
| verification_token | string | No | Token used for Webhook event verification |
| allow_from | array | No | Allowlist of user IDs; empty means all users are allowed |
| random_reaction_emoji | array | No | List of random reaction emojis; empty uses the default "Pin" |
## Setup
1. Go to the [Feishu Open Platform](https://open.feishu.cn/) and create an application
2. Enable the **Bot** capability in the application settings
3. Create a version and publish the application (configuration takes effect only after publishing)
4. Obtain the **App ID** (starts with `cli_`) and **App Secret**
5. Fill in the App ID and App Secret in the PicoClaw configuration file
6. Run `picoclaw gateway` to start the service
7. Search for the bot name in Feishu and start a conversation
> PicoClaw connects to Feishu using WebSocket/SDK mode — no public callback address or Webhook URL is required.
>
> `encrypt_key` and `verification_token` are optional; enabling event encryption is recommended for production environments.
>
> For custom emoji references, see: [Feishu Emoji List](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
docs/channels/feishu/README.pt-br.md
+48
View File
@@ -0,0 +1,48 @@
> Voltar ao [README](../../../README.pt-br.md)
# Feishu
Feishu (nome internacional: Lark) é uma plataforma de colaboração empresarial da ByteDance. Suporta os mercados chinês e global por meio de conexões WebSocket orientadas a eventos.
## Configuração
```json
{
"channels": {
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"allow_from": []
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| --------------------- | ------ | ----------- | -------------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal Feishu deve ser habilitado |
| app_id | string | Sim | App ID da aplicação Feishu (começa com `cli_`) |
| app_secret | string | Sim | App Secret da aplicação Feishu |
| encrypt_key | string | Não | Chave de criptografia para callbacks de eventos |
| verification_token | string | Não | Token usado para verificação de eventos Webhook |
| allow_from | array | Não | Lista de IDs de usuários permitidos; vazio significa todos os usuários |
| random_reaction_emoji | array | Não | Lista de emojis de reação aleatórios; vazio usa o "Pin" padrão |
## Configuração inicial
1. Acesse a [Plataforma Aberta Feishu](https://open.feishu.cn/) e crie uma aplicação
2. Habilite a capacidade de **Bot** nas configurações da aplicação
3. Crie uma versão e publique a aplicação (a configuração entra em vigor após a publicação)
4. Obtenha o **App ID** (começa com `cli_`) e o **App Secret**
5. Preencha o App ID e o App Secret no arquivo de configuração do PicoClaw
6. Execute `picoclaw gateway` para iniciar o serviço
7. Pesquise o nome do bot no Feishu e inicie uma conversa
> O PicoClaw se conecta ao Feishu usando o modo WebSocket/SDK — nenhum endereço de callback público ou URL de Webhook é necessário.
>
> `encrypt_key` e `verification_token` são opcionais; recomenda-se habilitar a criptografia de eventos em ambientes de produção.
>
> Para referências de emojis personalizados, consulte: [Lista de Emojis do Feishu](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
docs/channels/feishu/README.vi.md
+48
View File
@@ -0,0 +1,48 @@
> Quay lại [README](../../../README.vi.md)
# Feishu
Feishu (tên quốc tế: Lark) là nền tảng cộng tác doanh nghiệp của ByteDance. Hỗ trợ cả thị trường Trung Quốc và toàn cầu thông qua kết nối WebSocket theo hướng sự kiện.
## Cấu hình
```json
{
"channels": {
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"allow_from": []
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| --------------------- | ------ | -------- | ------------------------------------------------------------------------ |
| enabled | bool | Có | Có bật kênh Feishu hay không |
| app_id | string | Có | App ID của ứng dụng Feishu (bắt đầu bằng `cli_`) |
| app_secret | string | Có | App Secret của ứng dụng Feishu |
| encrypt_key | string | Không | Khóa mã hóa cho callback sự kiện |
| verification_token | string | Không | Token dùng để xác minh sự kiện Webhook |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả |
| random_reaction_emoji | array | Không | Danh sách emoji phản ứng ngẫu nhiên; để trống dùng "Pin" mặc định |
## Hướng dẫn thiết lập
1. Truy cập [Nền tảng Mở Feishu](https://open.feishu.cn/) và tạo ứng dụng
2. Bật khả năng **Bot** trong cài đặt ứng dụng
3. Tạo phiên bản và xuất bản ứng dụng (cấu hình có hiệu lực sau khi xuất bản)
4. Lấy **App ID** (bắt đầu bằng `cli_`) và **App Secret**
5. Điền App ID và App Secret vào file cấu hình PicoClaw
6. Chạy `picoclaw gateway` để khởi động dịch vụ
7. Tìm kiếm tên bot trong Feishu và bắt đầu trò chuyện
> PicoClaw kết nối với Feishu bằng chế độ WebSocket/SDK — không cần cấu hình địa chỉ callback công khai hay Webhook URL.
>
> `encrypt_key` và `verification_token` là tùy chọn; nên bật mã hóa sự kiện trong môi trường sản xuất.
>
> Tham khảo emoji tùy chỉnh: [Danh sách Emoji Feishu](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
docs/channels/feishu/README.zh.md
+15 -6
View File
@@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# 飞书
飞书（国际版名称：Lark）是字节跳动旗下的企业协作平台。它通过事件驱动的 Webhook 同时支持中国和全球市场。
@@ -33,9 +35,16 @@
## 设置流程
1. 前往 [飞书开放平台](https://open.feishu.cn/)（国际版用户请前往 [Lark 开放平台](https://open.larksuite.com/)）创建应用程序
2. 获取 App ID 和 App Secret
3. 配置事件订阅和Webhook URL
4. 设置加密(可选,生产环境建议启用)
5. 将 App ID、App Secret、Encrypt Key 和 Verification Token(如果启用加密) 填入配置文件中
6. 自定义你希望 PicoClaw react 你消息时的表情（可选, Reference URL: [Feishu Emoji List](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce))
1. 前往 [飞书开放平台](https://open.feishu.cn/)（国际版用户请前往 [Lark 开放平台](https://open.larksuite.com/)）创建应用
2. 在应用设置中启用**机器人**能力
3. 创建版本并发布应用（应用发布后配置才会生效）
4. 获取 **App ID**（以 `cli_` 开头）和 **App Secret**
5. 将 App ID 和 App Secret 填入 PicoClaw 配置文件
6. 运行 `picoclaw gateway` 启动服务
7. 在飞书中搜索机器人名称，开始对话
> PicoClaw 使用 WebSocket/SDK 模式连接飞书，无需配置公网回调地址或 Webhook URL。
>
> `encrypt_key` 和 `verification_token` 为可选项，生产环境建议启用事件加密。
>
> 自定义表情参考：[飞书表情列表](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
docs/channels/line/README.fr.md
+40
View File
@@ -0,0 +1,40 @@
> Retour au [README](../../../README.fr.md)
# Line
PicoClaw prend en charge LINE via l'API LINE Messaging avec des callbacks webhook.
## Configuration
```json
{
"channels": {
"line": {
"enabled": true,
"channel_secret": "YOUR_CHANNEL_SECRET",
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
"webhook_path": "/webhook/line",
"allow_from": []
}
}
}
```
| Champ | Type | Requis | Description |
| -------------------- | ------ | ------ | ------------------------------------------------------------------------ |
| enabled | bool | Oui | Activer ou non le canal LINE |
| channel_secret | string | Oui | Channel Secret de l'API LINE Messaging |
| channel_access_token | string | Oui | Channel Access Token de l'API LINE Messaging |
| webhook_path | string | Non | Chemin du webhook (par défaut : /webhook/line) |
| allow_from | array | Non | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs |
## Procédure de configuration
1. Rendez-vous sur la [LINE Developers Console](https://developers.line.biz/console/) et créez un fournisseur de services ainsi qu'un canal Messaging API
2. Obtenez le Channel Secret et le Channel Access Token
3. Configurez le webhook :
- LINE exige que les webhooks utilisent HTTPS. Vous devez donc déployer un serveur compatible HTTPS ou utiliser un outil de proxy inverse comme ngrok pour exposer votre serveur local sur Internet
- PicoClaw utilise un serveur HTTP Gateway partagé pour recevoir les callbacks webhook de tous les canaux, écoutant par défaut sur 127.0.0.1:18790
- Définissez l'URL du webhook sur `https://your-domain.com/webhook/line`, puis configurez un proxy inverse de votre domaine externe vers le Gateway local (port par défaut 18790)
- Activez le webhook et vérifiez l'URL
4. Renseignez le Channel Secret et le Channel Access Token dans le fichier de configuration
docs/channels/line/README.ja.md
+40
View File
@@ -0,0 +1,40 @@
> [README](../../../README.ja.md) に戻る
# Line
PicoClaw は LINE Messaging API と Webhook コールバックを通じて LINE をサポートします。
## 設定
```json
{
"channels": {
"line": {
"enabled": true,
"channel_secret": "YOUR_CHANNEL_SECRET",
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
"webhook_path": "/webhook/line",
"allow_from": []
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| -------------------- | ------ | ------ | ------------------------------------------------------------------ |
| enabled | bool | はい | LINE チャンネルを有効にするかどうか |
| channel_secret | string | はい | LINE Messaging API の Channel Secret |
| channel_access_token | string | はい | LINE Messaging API の Channel Access Token |
| webhook_path | string | いいえ | Webhook のパス（デフォルト: /webhook/line） |
| allow_from | array | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可 |
## セットアップ手順
1. [LINE Developers Console](https://developers.line.biz/console/) にアクセスし、サービスプロバイダーと Messaging API チャンネルを作成する
2. Channel Secret と Channel Access Token を取得する
3. Webhook を設定する:
- LINE は Webhook に HTTPS が必要なため、HTTPS 対応サーバーをデプロイするか、ngrok などのリバースプロキシツールを使用してローカルサーバーをインターネットに公開する必要があります
- PicoClaw は共有の Gateway HTTP サーバーを使用してすべてのチャンネルの Webhook コールバックを受信します。デフォルトのリッスンアドレスは 127.0.0.1:18790 です
- Webhook URL を `https://your-domain.com/webhook/line` に設定し、外部ドメインをローカルの Gateway（デフォルトポート 18790）にリバースプロキシする
- Webhook を有効にして URL を検証する
4. Channel Secret と Channel Access Token を設定ファイルに入力する
docs/channels/line/README.md
+40
View File
@@ -0,0 +1,40 @@
> Back to [README](../../../README.md)
# Line
PicoClaw supports LINE through the LINE Messaging API with webhook callbacks.
## Configuration
```json
{
"channels": {
"line": {
"enabled": true,
"channel_secret": "YOUR_CHANNEL_SECRET",
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
"webhook_path": "/webhook/line",
"allow_from": []
}
}
}
```
| Field | Type | Required | Description |
| -------------------- | ------ | -------- | ------------------------------------------------------------------ |
| enabled | bool | Yes | Whether to enable the LINE channel |
| channel_secret | string | Yes | Channel Secret for the LINE Messaging API |
| channel_access_token | string | Yes | Channel Access Token for the LINE Messaging API |
| webhook_path | string | No | Webhook path (default: /webhook/line) |
| allow_from | array | No | User ID whitelist; empty means all users are allowed |
## Setup
1. Go to the [LINE Developers Console](https://developers.line.biz/console/) and create a provider and a Messaging API channel
2. Obtain the Channel Secret and Channel Access Token
3. Configure the webhook:
- LINE requires webhooks to use HTTPS, so you need to deploy a server with HTTPS support, or use a reverse proxy tool like ngrok to expose your local server to the internet
- PicoClaw uses a shared Gateway HTTP server to receive webhook callbacks for all channels, listening on 127.0.0.1:18790 by default
- Set the Webhook URL to `https://your-domain.com/webhook/line`, then reverse-proxy your external domain to the local Gateway (default port 18790)
- Enable the webhook and verify the URL
4. Fill in the Channel Secret and Channel Access Token in the configuration file
docs/channels/line/README.pt-br.md
+40
View File
@@ -0,0 +1,40 @@
> Voltar ao [README](../../../README.pt-br.md)
# Line
O PicoClaw suporta o LINE por meio da LINE Messaging API com callbacks de webhook.
## Configuração
```json
{
"channels": {
"line": {
"enabled": true,
"channel_secret": "YOUR_CHANNEL_SECRET",
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
"webhook_path": "/webhook/line",
"allow_from": []
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| -------------------- | ------ | ----------- | ---------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal LINE deve ser habilitado |
| channel_secret | string | Sim | Channel Secret da LINE Messaging API |
| channel_access_token | string | Sim | Channel Access Token da LINE Messaging API |
| webhook_path | string | Não | Caminho do webhook (padrão: /webhook/line) |
| allow_from | array | Não | Lista de permissão de IDs de usuário; vazio permite todos |
## Configuração passo a passo
1. Acesse o [LINE Developers Console](https://developers.line.biz/console/) e crie um provedor de serviços e um canal Messaging API
2. Obtenha o Channel Secret e o Channel Access Token
3. Configure o webhook:
- O LINE exige que os webhooks usem HTTPS, portanto é necessário implantar um servidor com suporte a HTTPS ou usar uma ferramenta de proxy reverso como o ngrok para expor seu servidor local à internet
- O PicoClaw usa um servidor HTTP Gateway compartilhado para receber callbacks de webhook de todos os canais, escutando em 127.0.0.1:18790 por padrão
- Defina a URL do webhook como `https://your-domain.com/webhook/line` e configure um proxy reverso do seu domínio externo para o Gateway local (porta padrão 18790)
- Ative o webhook e verifique a URL
4. Preencha o Channel Secret e o Channel Access Token no arquivo de configuração
docs/channels/line/README.vi.md
+40
View File
@@ -0,0 +1,40 @@
> Quay lại [README](../../../README.vi.md)
# Line
PicoClaw hỗ trợ LINE thông qua LINE Messaging API kết hợp với webhook callback.
## Cấu hình
```json
{
"channels": {
"line": {
"enabled": true,
"channel_secret": "YOUR_CHANNEL_SECRET",
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
"webhook_path": "/webhook/line",
"allow_from": []
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| -------------------- | ------ | -------- | ---------------------------------------------------------------------- |
| enabled | bool | Có | Có bật kênh LINE hay không |
| channel_secret | string | Có | Channel Secret của LINE Messaging API |
| channel_access_token | string | Có | Channel Access Token của LINE Messaging API |
| webhook_path | string | Không | Đường dẫn webhook (mặc định: /webhook/line) |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống cho phép tất cả |
## Quy trình thiết lập
1. Truy cập [LINE Developers Console](https://developers.line.biz/console/) và tạo một nhà cung cấp dịch vụ cùng một kênh Messaging API
2. Lấy Channel Secret và Channel Access Token
3. Cấu hình webhook:
- LINE yêu cầu webhook phải sử dụng HTTPS, vì vậy bạn cần triển khai máy chủ hỗ trợ HTTPS hoặc dùng công cụ reverse proxy như ngrok để expose máy chủ cục bộ ra internet
- PicoClaw sử dụng máy chủ HTTP Gateway dùng chung để nhận webhook callback cho tất cả các kênh, mặc định lắng nghe tại 127.0.0.1:18790
- Đặt Webhook URL thành `https://your-domain.com/webhook/line`, sau đó reverse proxy tên miền bên ngoài về Gateway cục bộ (cổng mặc định 18790)
- Bật webhook và xác minh URL
4. Điền Channel Secret và Channel Access Token vào file cấu hình
docs/channels/line/README.zh.md
+2
View File
@@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# Line
PicoClaw 通过 LINE Messaging API 配合 Webhook 回调功能实现对 LINE 的支持。
docs/channels/maixcam/README.fr.md
+35
View File
@@ -0,0 +1,35 @@
> Retour au [README](../../../README.fr.md)
# MaixCam
MaixCam est un canal dédié à la connexion aux caméras AI Sipeed MaixCAM et MaixCAM2. Il utilise des sockets TCP pour une communication bidirectionnelle et prend en charge les scénarios de déploiement d'IA en périphérie.
## Configuration
```json
{
"channels": {
"maixcam": {
"enabled": true,
"host": "0.0.0.0",
"port": 18790,
"allow_from": []
}
}
}
```
| Champ | Type | Requis | Description |
| ---------- | ------ | ------ | --------------------------------------------------------------------------- |
| enabled | bool | Oui | Activer ou non le canal MaixCam |
| host | string | Oui | Adresse d'écoute du serveur TCP |
| port | int | Oui | Port d'écoute du serveur TCP |
| allow_from | array | Non | Liste blanche d'identifiants d'appareils ; vide signifie tous les appareils |
## Cas d'utilisation
Le canal MaixCam permet à PicoClaw de fonctionner comme backend IA pour les appareils en périphérie :
- **Surveillance intelligente** : MaixCAM envoie des images ; PicoClaw les analyse via des modèles de vision
- **Contrôle IoT** : Les appareils envoient des données de capteurs ; PicoClaw coordonne les réponses
- **IA hors ligne** : Déployer PicoClaw sur un réseau local pour une inférence à faible latence
docs/channels/maixcam/README.ja.md
+35
View File
@@ -0,0 +1,35 @@
> [README](../../../README.ja.md) に戻る
# MaixCam
MaixCam は、Sipeed MaixCAM および MaixCAM2 AI カメラデバイスへの接続専用チャンネルです。TCP ソケットを使用した双方向通信を実装し、エッジ AI デプロイメントシナリオをサポートします。
## 設定
```json
{
"channels": {
"maixcam": {
"enabled": true,
"host": "0.0.0.0",
"port": 18790,
"allow_from": []
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------- | ------ | ------ | ------------------------------------------------------------- |
| enabled | bool | はい | MaixCam チャンネルを有効にするかどうか |
| host | string | はい | TCP サーバーのリッスンアドレス |
| port | int | はい | TCP サーバーのリッスンポート |
| allow_from | array | いいえ | 許可するデバイスIDのリスト。空の場合はすべてのデバイスを許可 |
## ユースケース
MaixCam チャンネルにより、PicoClaw はエッジデバイスの AI バックエンドとして機能できます：
- **スマート監視**：MaixCAM が画像フレームを送信し、PicoClaw がビジョンモデルで分析する
- **IoT 制御**：デバイスがセンサーデータを送信し、PicoClaw がレスポンスを調整する
- **オフライン AI**：ローカルネットワークに PicoClaw をデプロイして低遅延推論を実現する
docs/channels/maixcam/README.md
+35
View File
@@ -0,0 +1,35 @@
> Back to [README](../../../README.md)
# MaixCam
MaixCam is a dedicated channel for connecting to Sipeed MaixCAM and MaixCAM2 AI camera devices. It uses TCP sockets for bidirectional communication and supports edge AI deployment scenarios.
## Configuration
```json
{
"channels": {
"maixcam": {
"enabled": true,
"host": "0.0.0.0",
"port": 18790,
"allow_from": []
}
}
}
```
| Field | Type | Required | Description |
| ---------- | ------ | -------- | ---------------------------------------------------------------- |
| enabled | bool | Yes | Whether to enable the MaixCam channel |
| host | string | Yes | TCP server listening address |
| port | int | Yes | TCP server listening port |
| allow_from | array | No | Allowlist of device IDs; empty means all devices are allowed |
## Use Cases
The MaixCam channel enables PicoClaw to act as an AI backend for edge devices:
- **Smart Surveillance**: MaixCAM sends image frames; PicoClaw analyzes them using vision models
- **IoT Control**: Devices send sensor data; PicoClaw coordinates responses
- **Offline AI**: Deploy PicoClaw on a local network for low-latency inference
docs/channels/maixcam/README.pt-br.md
+35
View File
@@ -0,0 +1,35 @@
> Voltar ao [README](../../../README.pt-br.md)
# MaixCam
MaixCam é um canal dedicado para conectar dispositivos de câmera AI Sipeed MaixCAM e MaixCAM2. Utiliza sockets TCP para comunicação bidirecional e suporta cenários de implantação de IA na borda.
## Configuração
```json
{
"channels": {
"maixcam": {
"enabled": true,
"host": "0.0.0.0",
"port": 18790,
"allow_from": []
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ---------- | ------ | ----------- | -------------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal MaixCam deve ser habilitado |
| host | string | Sim | Endereço de escuta do servidor TCP |
| port | int | Sim | Porta de escuta do servidor TCP |
| allow_from | array | Não | Lista de IDs de dispositivos permitidos; vazio significa todos os dispositivos |
## Casos de uso
O canal MaixCam permite que o PicoClaw atue como backend de IA para dispositivos de borda:
- **Vigilância inteligente**: MaixCAM envia quadros de imagem; PicoClaw os analisa usando modelos de visão
- **Controle IoT**: Dispositivos enviam dados de sensores; PicoClaw coordena as respostas
- **IA offline**: Implante o PicoClaw em uma rede local para inferência de baixa latência
docs/channels/maixcam/README.vi.md
+35
View File
@@ -0,0 +1,35 @@
> Quay lại [README](../../../README.vi.md)
# MaixCam
MaixCam là kênh chuyên dụng để kết nối với các thiết bị camera AI Sipeed MaixCAM và MaixCAM2. Sử dụng TCP socket để giao tiếp hai chiều và hỗ trợ các kịch bản triển khai AI tại biên.
## Cấu hình
```json
{
"channels": {
"maixcam": {
"enabled": true,
"host": "0.0.0.0",
"port": 18790,
"allow_from": []
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
| enabled | bool | Có | Có bật kênh MaixCam hay không |
| host | string | Có | Địa chỉ lắng nghe của máy chủ TCP |
| port | int | Có | Cổng lắng nghe của máy chủ TCP |
| allow_from | array | Không | Danh sách trắng ID thiết bị; để trống nghĩa là cho phép tất cả thiết bị |
## Trường hợp sử dụng
Kênh MaixCam cho phép PicoClaw hoạt động như backend AI cho các thiết bị biên:
- **Giám sát thông minh**: MaixCAM gửi khung hình ảnh; PicoClaw phân tích bằng mô hình thị giác
- **Điều khiển IoT**: Thiết bị gửi dữ liệu cảm biến; PicoClaw điều phối phản hồi
- **AI ngoại tuyến**: Triển khai PicoClaw trên mạng nội bộ để suy luận độ trễ thấp
docs/channels/maixcam/README.zh.md
+10 -6
View File
@@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# MaixCam
MaixCam 是专用于连接矽速科技 MaixCAM 与 MaixCAM2 AI 摄像设备的通道。它采用 TCP 套接字实现双向通信，支持边缘 AI 部署场景。
@@ -9,18 +11,20 @@ MaixCam 是专用于连接矽速科技 MaixCAM 与 MaixCAM2 AI 摄像设备的
"channels": {
"maixcam": {
"enabled": true,
"server_address": "0.0.0.0:8899",
"host": "0.0.0.0",
"port": 18790,
"allow_from": []
}
}
}
```
| 字段 | 类型 | 必填 | 描述 |
| -------------- | ------ | ---- | -------------------------------- |
| enabled | bool | 是 | 是否启用 MaixCam 频道 |
| server_address | string | 是 | TCP 服务器监听地址和端口 |
| allow_from | array | 否 | 设备ID白名单，空表示允许所有设备 |
| 字段 | 类型 | 必填 | 描述 |
| ---------- | ------ | ---- | -------------------------------- |
| enabled | bool | 是 | 是否启用 MaixCam 频道 |
| host | string | 是 | TCP 服务器监听地址 |
| port | int | 是 | TCP 服务器监听端口 |
| allow_from | array | 否 | 设备ID白名单，空表示允许所有设备 |
## 使用场景
docs/channels/matrix/README.zh.md
+1
View File
@@ -42,6 +42,7 @@
| group_trigger | object | 否 | 群聊触发策略（支持 `mention_only` / `prefixes`） |
| placeholder | object | 否 | 占位消息配置 |
| reasoning_channel_id | string | 否 | 思维链输出目标通道 |
| message_format | string | 否 | 消息格式：`richtext`（富文本）或 `plain`（纯文本） |
## 3. 当前支持
docs/channels/onebot/README.fr.md
+33
View File
@@ -0,0 +1,33 @@
> Retour au [README](../../../README.fr.md)
# OneBot
OneBot est un standard de protocole ouvert pour les bots QQ, fournissant une interface unifiée pour diverses implémentations de bots QQ (par exemple go-cqhttp, Mirai). Il utilise WebSocket pour la communication.
## Configuration
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://localhost:8080",
"access_token": "",
"allow_from": []
}
}
}
```
| Champ | Type | Requis | Description |
| ------------ | ------ | ------ | -------------------------------------------------------------------- |
| enabled | bool | Oui | Activer ou non le canal OneBot |
| ws_url | string | Oui | URL WebSocket du serveur OneBot |
| access_token | string | Non | Jeton d'accès pour la connexion au serveur OneBot |
| allow_from | array | Non | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs |
## Procédure de configuration
1. Déployez une implémentation compatible OneBot (par exemple napcat)
2. Configurez l'implémentation OneBot pour activer le service WebSocket et définir un jeton d'accès (si nécessaire)
3. Renseignez l'URL WebSocket et le jeton d'accès dans le fichier de configuration
docs/channels/onebot/README.ja.md
+33
View File
@@ -0,0 +1,33 @@
> [README](../../../README.ja.md) に戻る
# OneBot
OneBot は QQ ボット向けのオープンプロトコル標準で、複数の QQ ボット実装（例: go-cqhttp、Mirai）に統一されたインターフェースを提供します。通信には WebSocket を使用します。
## 設定
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://localhost:8080",
"access_token": "",
"allow_from": []
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ------------ | ------ | ------ | ---------------------------------------------------------------- |
| enabled | bool | はい | OneBot チャンネルを有効にするかどうか |
| ws_url | string | はい | OneBot サーバーの WebSocket URL |
| access_token | string | いいえ | OneBot サーバーへの接続に使用するアクセストークン |
| allow_from | array | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可 |
## セットアップ手順
1. OneBot 互換の実装（例: napcat）をデプロイする
2. OneBot 実装で WebSocket サービスを有効にし、アクセストークンを設定する（必要な場合）
3. WebSocket URL とアクセストークンを設定ファイルに入力する
docs/channels/onebot/README.md
+33
View File
@@ -0,0 +1,33 @@
> Back to [README](../../../README.md)
# OneBot
OneBot is an open protocol standard for QQ bots, providing a unified interface for various QQ bot implementations (e.g. go-cqhttp, Mirai). It uses WebSocket for communication.
## Configuration
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://localhost:8080",
"access_token": "",
"allow_from": []
}
}
}
```
| Field | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------------------------------- |
| enabled | bool | Yes | Whether to enable the OneBot channel |
| ws_url | string | Yes | WebSocket URL of the OneBot server |
| access_token | string | No | Access token for connecting to the OneBot server |
| allow_from | array | No | User ID whitelist; empty means all users are allowed |
## Setup
1. Deploy a OneBot-compatible implementation (e.g. napcat)
2. Configure the OneBot implementation to enable the WebSocket service and set an access token (if needed)
3. Fill in the WebSocket URL and access token in the configuration file
docs/channels/onebot/README.pt-br.md
+33
View File
@@ -0,0 +1,33 @@
> Voltar ao [README](../../../README.pt-br.md)
# OneBot
OneBot é um padrão de protocolo aberto para bots QQ, fornecendo uma interface unificada para diversas implementações de bots QQ (ex.: go-cqhttp, Mirai). Utiliza WebSocket para comunicação.
## Configuração
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://localhost:8080",
"access_token": "",
"allow_from": []
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ------------ | ------ | ----------- | -------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal OneBot deve ser habilitado |
| ws_url | string | Sim | URL WebSocket do servidor OneBot |
| access_token | string | Não | Token de acesso para conexão ao servidor OneBot |
| allow_from | array | Não | Lista de permissão de IDs de usuário; vazio permite todos |
## Configuração passo a passo
1. Implante uma implementação compatível com OneBot (ex.: napcat)
2. Configure a implementação OneBot para habilitar o serviço WebSocket e definir um token de acesso (se necessário)
3. Preencha a URL WebSocket e o token de acesso no arquivo de configuração
docs/channels/onebot/README.vi.md
+33
View File
@@ -0,0 +1,33 @@
> Quay lại [README](../../../README.vi.md)
# OneBot
OneBot là tiêu chuẩn giao thức mở dành cho bot QQ, cung cấp giao diện thống nhất cho nhiều triển khai bot QQ khác nhau (ví dụ: go-cqhttp, Mirai). Nó sử dụng WebSocket để giao tiếp.
## Cấu hình
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://localhost:8080",
"access_token": "",
"allow_from": []
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ------------ | ------ | -------- | -------------------------------------------------------------------- |
| enabled | bool | Có | Có bật kênh OneBot hay không |
| ws_url | string | Có | URL WebSocket của máy chủ OneBot |
| access_token | string | Không | Token truy cập để kết nối với máy chủ OneBot |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống cho phép tất cả |
## Quy trình thiết lập
1. Triển khai một bản triển khai tương thích OneBot (ví dụ: napcat)
2. Cấu hình bản triển khai OneBot để bật dịch vụ WebSocket và đặt token truy cập (nếu cần)
3. Điền URL WebSocket và token truy cập vào file cấu hình
docs/channels/onebot/README.zh.md
+2
View File
@@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# OneBot
OneBot 是一个面向 QQ 机器人的开放协议标准，为多种 QQ 机器人实现（例如 go-cqhttp、Mirai）提供了统一的接口。它使用 WebSocket 进行通信。
docs/channels/qq/README.fr.md
+54
View File
@@ -0,0 +1,54 @@
> Retour au [README](../../../README.fr.md)
# QQ
PicoClaw prend en charge QQ via l'API Bot officielle de la plateforme ouverte QQ.
## Configuration
```json
{
"channels": {
"qq": {
"enabled": true,
"app_id": "YOUR_APP_ID",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
| Champ | Type | Requis | Description |
| ---------- | ------ | ------ | --------------------------------------------------------------------------- |
| enabled | bool | Oui | Activer ou non le canal QQ |
| app_id | string | Oui | App ID de l'application bot QQ |
| app_secret | string | Oui | App Secret de l'application bot QQ |
| allow_from | array | Non | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
## Configuration initiale
### Configuration rapide (recommandée)
La plateforme ouverte QQ propose une entrée de création en un clic :
1. Ouvrir [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) et se connecter en scannant le QR code
2. Le système crée automatiquement un bot — copier l'**App ID** et l'**App Secret**
3. Renseigner les identifiants dans le fichier de configuration PicoClaw
4. Exécuter `picoclaw gateway` pour démarrer le service
5. Ouvrir QQ et commencer à discuter avec le bot
> L'App Secret n'est affiché qu'une seule fois — sauvegardez-le immédiatement. Le consulter à nouveau forcera une réinitialisation.
>
> Les bots créés via l'entrée rapide sont réservés à l'usage personnel du créateur et ne prennent pas en charge les discussions de groupe. Pour la prise en charge des groupes, configurez le mode sandbox sur la [plateforme ouverte QQ](https://q.qq.com/).
### Configuration manuelle
1. Se connecter à la [plateforme ouverte QQ](https://q.qq.com/) avec son compte QQ et s'inscrire en tant que développeur
2. Créer un bot QQ et personnaliser son avatar et son nom
3. Obtenir l'**App ID** et l'**App Secret** dans les paramètres du bot
4. Renseigner les identifiants dans le fichier de configuration PicoClaw
5. Exécuter `picoclaw gateway` pour démarrer le service
6. Rechercher votre bot dans QQ et commencer à discuter
> Pendant le développement, il est recommandé d'activer le mode sandbox et d'y ajouter les utilisateurs et groupes de test pour le débogage.
docs/channels/qq/README.ja.md
+54
View File
@@ -0,0 +1,54 @@
> [README](../../../README.ja.md) に戻る
# QQ
PicoClaw は QQ オープンプラットフォームの公式 Bot API を通じて QQ をサポートします。
## 設定
```json
{
"channels": {
"qq": {
"enabled": true,
"app_id": "YOUR_APP_ID",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------- | ------ | ------ | ------------------------------------------------------------- |
| enabled | bool | はい | QQ チャンネルを有効にするかどうか |
| app_id | string | はい | QQ ボットアプリケーションの App ID |
| app_secret | string | はい | QQ ボットアプリケーションの App Secret |
| allow_from | array | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可 |
## セットアップ手順
### クイックセットアップ（推奨）
QQ オープンプラットフォームにはワンクリック作成エントリーが用意されています：
1. [QQ ボットクイック作成](https://q.qq.com/qqbot/openclaw/index.html) を開き、QR コードをスキャンしてログインする
2. システムが自動的にボットを作成するので、**App ID** と **App Secret** をコピーする
3. PicoClaw 設定ファイルに認証情報を入力する
4. `picoclaw gateway` を実行してサービスを起動する
5. QQ を開いてボットとの会話を始める
> App Secret は一度しか表示されません。すぐに保存してください。再度表示しようとすると強制的にリセットされます。
>
> クイックエントリーで作成したボットは作成者本人のみが使用でき、グループチャットには対応していません。グループチャット機能が必要な場合は、[QQ オープンプラットフォーム](https://q.qq.com/) でサンドボックスモードを設定してください。
### 手動セットアップ
1. QQ アカウントで [QQ オープンプラットフォーム](https://q.qq.com/) にログインし、開発者アカウントを登録する
2. QQ ボットを作成し、アバターと名前をカスタマイズする
3. ボット設定から **App ID** と **App Secret** を取得する
4. PicoClaw 設定ファイルに認証情報を入力する
5. `picoclaw gateway` を実行してサービスを起動する
6. QQ でボットを検索して会話を始める
> 開発段階ではサンドボックスモードを有効にし、テストユーザーとグループをサンドボックスに追加してデバッグすることを推奨します。
docs/channels/qq/README.md
+54
View File
@@ -0,0 +1,54 @@
> Back to [README](../../../README.md)
# QQ
PicoClaw provides QQ support via the official Bot API from the QQ Open Platform.
## Configuration
```json
{
"channels": {
"qq": {
"enabled": true,
"app_id": "YOUR_APP_ID",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
| Field | Type | Required | Description |
| ---------- | ------ | -------- | -------------------------------------------------------- |
| enabled | bool | Yes | Whether to enable the QQ channel |
| app_id | string | Yes | App ID of the QQ bot application |
| app_secret | string | Yes | App Secret of the QQ bot application |
| allow_from | array | No | Allowlist of user IDs; empty means all users are allowed |
## Setup
### Quick Setup (Recommended)
The QQ Open Platform provides a one-click creation entry:
1. Open [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) and log in by scanning the QR code
2. The system automatically creates a bot — copy the **App ID** and **App Secret**
3. Fill in the credentials in the PicoClaw configuration file
4. Run `picoclaw gateway` to start the service
5. Open QQ and start chatting with the bot
> The App Secret is only shown once — save it immediately. Viewing it again will force a reset.
>
> Bots created via the quick entry are for the creator's personal use only and do not support group chats. For group chat support, configure sandbox mode on the [QQ Open Platform](https://q.qq.com/).
### Manual Setup
1. Log in to the [QQ Open Platform](https://q.qq.com/) with your QQ account and register as a developer
2. Create a QQ bot and customize its avatar and name
3. Obtain the **App ID** and **App Secret** from the bot settings
4. Fill in the credentials in the PicoClaw configuration file
5. Run `picoclaw gateway` to start the service
6. Search for your bot in QQ and start chatting
> During development, it is recommended to enable sandbox mode and add test users and groups to the sandbox for debugging.
docs/channels/qq/README.pt-br.md
+54
View File
@@ -0,0 +1,54 @@
> Voltar ao [README](../../../README.pt-br.md)
# QQ
O PicoClaw oferece suporte ao QQ via API Bot oficial da Plataforma Aberta QQ.
## Configuração
```json
{
"channels": {
"qq": {
"enabled": true,
"app_id": "YOUR_APP_ID",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ---------- | ------ | ----------- | -------------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal QQ deve ser habilitado |
| app_id | string | Sim | App ID da aplicação bot QQ |
| app_secret | string | Sim | App Secret da aplicação bot QQ |
| allow_from | array | Não | Lista de IDs de usuários permitidos; vazio significa todos os usuários |
## Configuração inicial
### Configuração rápida (recomendada)
A Plataforma Aberta QQ oferece uma entrada de criação com um clique:
1. Abra o [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) e faça login escaneando o QR code
2. O sistema cria o bot automaticamente — copie o **App ID** e o **App Secret**
3. Preencha as credenciais no arquivo de configuração do PicoClaw
4. Execute `picoclaw gateway` para iniciar o serviço
5. Abra o QQ e comece a conversar com o bot
> O App Secret é exibido apenas uma vez — salve-o imediatamente. Visualizá-lo novamente forçará uma redefinição.
>
> Bots criados pela entrada rápida são apenas para uso pessoal do criador e não suportam chats em grupo. Para suporte a grupos, configure o modo sandbox na [Plataforma Aberta QQ](https://q.qq.com/).
### Configuração manual
1. Faça login na [Plataforma Aberta QQ](https://q.qq.com/) com sua conta QQ e registre-se como desenvolvedor
2. Crie um bot QQ e personalize seu avatar e nome
3. Obtenha o **App ID** e o **App Secret** nas configurações do bot
4. Preencha as credenciais no arquivo de configuração do PicoClaw
5. Execute `picoclaw gateway` para iniciar o serviço
6. Pesquise seu bot no QQ e comece a conversar
> Durante o desenvolvimento, recomenda-se habilitar o modo sandbox e adicionar usuários e grupos de teste ao sandbox para depuração.
docs/channels/qq/README.vi.md
+54
View File
@@ -0,0 +1,54 @@
> Quay lại [README](../../../README.vi.md)
# QQ
PicoClaw hỗ trợ QQ thông qua API Bot chính thức của Nền tảng Mở QQ.
## Cấu hình
```json
{
"channels": {
"qq": {
"enabled": true,
"app_id": "YOUR_APP_ID",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
| enabled | bool | Có | Có bật kênh QQ hay không |
| app_id | string | Có | App ID của ứng dụng bot QQ |
| app_secret | string | Có | App Secret của ứng dụng bot QQ |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả |
## Hướng dẫn thiết lập
### Thiết lập nhanh (Khuyến nghị)
Nền tảng Mở QQ cung cấp lối vào tạo bot một chạm:
1. Mở [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) và đăng nhập bằng cách quét mã QR
2. Hệ thống tự động tạo bot — sao chép **App ID** và **App Secret**
3. Điền thông tin xác thực vào file cấu hình PicoClaw
4. Chạy `picoclaw gateway` để khởi động dịch vụ
5. Mở QQ và bắt đầu trò chuyện với bot
> App Secret chỉ hiển thị một lần — hãy lưu lại ngay. Xem lại sẽ buộc phải đặt lại.
>
> Bot được tạo qua lối vào nhanh chỉ dành cho người tạo sử dụng cá nhân và chưa hỗ trợ chat nhóm. Để hỗ trợ chat nhóm, hãy cấu hình chế độ sandbox trên [Nền tảng Mở QQ](https://q.qq.com/).
### Tạo thủ công
1. Đăng nhập vào [Nền tảng Mở QQ](https://q.qq.com/) bằng tài khoản QQ và đăng ký tài khoản nhà phát triển
2. Tạo bot QQ, tùy chỉnh ảnh đại diện và tên
3. Lấy **App ID** và **App Secret** trong cài đặt bot
4. Điền thông tin xác thực vào file cấu hình PicoClaw
5. Chạy `picoclaw gateway` để khởi động dịch vụ
6. Tìm kiếm bot của bạn trong QQ và bắt đầu trò chuyện
> Trong giai đoạn phát triển, nên bật chế độ sandbox và thêm người dùng, nhóm thử nghiệm vào sandbox để gỡ lỗi.
docs/channels/qq/README.zh.md
+26 -4
View File
@@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# QQ
PicoClaw 通过 QQ 开放平台的官方机器人 API 提供对 QQ 的支持。
@@ -28,7 +30,27 @@ PicoClaw 通过 QQ 开放平台的官方机器人 API 提供对 QQ 的支持。
## 设置流程
1. 前往 [QQ 开放平台](https://q.qq.com/) 创建一个机器人
2. 通过仪表盘获取 App ID 和 App Secret
3. 开启机器人沙箱模式, 将用户和群添加到沙箱中
4. 将 App ID 和 App Secret 填入配置文件中
### 快捷方式（推荐）
QQ 开放平台提供了一键创建入口：
1. 打开 [QQ 机器人快速创建](https://q.qq.com/qqbot/openclaw/index.html)，扫码登录
2. 系统自动创建机器人，复制 **App ID** 和 **App Secret**
3. 将凭证填入 PicoClaw 配置文件
4. 运行 `picoclaw gateway` 启动服务
5. 打开 QQ，与机器人开始对话
> App Secret 仅显示一次，请立即保存。再次查看将强制重置。
>
> 通过快捷入口创建的机器人仅供创建人使用，暂不支持群聊。如需群聊功能，请在 [QQ 开放平台](https://q.qq.com/) 配置沙箱模式。
### 手动创建
1. 使用 QQ 账号登录 [QQ 开放平台](https://q.qq.com/)，注册开发者账号
2. 创建 QQ 机器人，自定义头像和名称
3. 在机器人设置中获取 **App ID** 和 **App Secret**
4. 将凭证填入 PicoClaw 配置文件
5. 运行 `picoclaw gateway` 启动服务
6. 在 QQ 中搜索你的机器人，开始对话
> 开发阶段建议开启沙箱模式，将测试用户和群添加到沙箱中进行调试。
docs/channels/slack/README.fr.md
+35
View File
@@ -0,0 +1,35 @@
> Retour au [README](../../../README.fr.md)
# Slack
Slack est l'une des principales plateformes de messagerie instantanée pour les entreprises. PicoClaw utilise le Socket Mode de Slack pour une communication bidirectionnelle en temps réel, sans nécessiter la configuration d'un endpoint webhook public.
## Configuration
```json
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-...",
"app_token": "xapp-...",
"allow_from": []
}
}
}
```
| Champ | Type | Requis | Description |
| ---------- | ------ | ------ | ---------------------------------------------------------------------------- |
| enabled | bool | Oui | Activer ou non le canal Slack |
| bot_token | string | Oui | Bot User OAuth Token du bot Slack (commence par xoxb-) |
| app_token | string | Oui | App Level Token Socket Mode de l'application Slack (commence par xapp-) |
| allow_from | array | Non | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs |
## Procédure de configuration
1. Rendez-vous sur [Slack API](https://api.slack.com/) et créez une nouvelle application Slack
2. Activez le Socket Mode et obtenez l'App Level Token
3. Ajoutez des Bot Token Scopes (par exemple `chat:write`, `im:history`, etc.)
4. Installez l'application dans votre espace de travail et obtenez le Bot User OAuth Token
5. Renseignez le Bot Token et l'App Token dans le fichier de configuration
docs/channels/slack/README.ja.md
+35
View File
@@ -0,0 +1,35 @@
> [README](../../../README.ja.md) に戻る
# Slack
Slack は世界をリードする企業向けインスタントメッセージングプラットフォームです。PicoClaw は Slack の Socket Mode を使用してリアルタイムの双方向通信を実現しており、公開 Webhook エンドポイントの設定は不要です。
## 設定
```json
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-...",
"app_token": "xapp-...",
"allow_from": []
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------- | ------ | ------ | ------------------------------------------------------------------------ |
| enabled | bool | はい | Slack チャンネルを有効にするかどうか |
| bot_token | string | はい | Slack ボットの Bot User OAuth Token（xoxb- で始まる） |
| app_token | string | はい | Slack アプリの Socket Mode App Level Token（xapp- で始まる） |
| allow_from | array | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可 |
## セットアップ手順
1. [Slack API](https://api.slack.com/) にアクセスして新しい Slack アプリを作成する
2. Socket Mode を有効にして App Level Token を取得する
3. Bot Token Scopes を追加する（例: `chat:write`、`im:history` など）
4. アプリをワークスペースにインストールして Bot User OAuth Token を取得する
5. Bot Token と App Token を設定ファイルに入力する
docs/channels/slack/README.md
+35
View File
@@ -0,0 +1,35 @@
> Back to [README](../../../README.md)
# Slack
Slack is a leading enterprise instant messaging platform. PicoClaw uses Slack's Socket Mode for real-time bidirectional communication, with no need to configure a public webhook endpoint.
## Configuration
```json
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-...",
"app_token": "xapp-...",
"allow_from": []
}
}
}
```
| Field | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
| enabled | bool | Yes | Whether to enable the Slack channel |
| bot_token | string | Yes | Bot User OAuth Token for the Slack bot (starts with xoxb-) |
| app_token | string | Yes | Socket Mode App Level Token for the Slack app (starts with xapp-) |
| allow_from | array | No | User ID whitelist; empty means all users are allowed |
## Setup
1. Go to [Slack API](https://api.slack.com/) and create a new Slack app
2. Enable Socket Mode and obtain the App Level Token
3. Add Bot Token Scopes (e.g. `chat:write`, `im:history`, etc.)
4. Install the app to your workspace and obtain the Bot User OAuth Token
5. Fill in the Bot Token and App Token in the configuration file
docs/channels/slack/README.pt-br.md
+35
View File
@@ -0,0 +1,35 @@
> Voltar ao [README](../../../README.pt-br.md)
# Slack
O Slack é uma das principais plataformas de mensagens instantâneas para empresas. O PicoClaw usa o Socket Mode do Slack para comunicação bidirecional em tempo real, sem necessidade de configurar um endpoint de webhook público.
## Configuração
```json
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-...",
"app_token": "xapp-...",
"allow_from": []
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ---------- | ------ | ----------- | ---------------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal Slack deve ser habilitado |
| bot_token | string | Sim | Bot User OAuth Token do bot Slack (começa com xoxb-) |
| app_token | string | Sim | App Level Token do Socket Mode do aplicativo Slack (começa com xapp-) |
| allow_from | array | Não | Lista de permissão de IDs de usuário; vazio permite todos |
## Configuração passo a passo
1. Acesse o [Slack API](https://api.slack.com/) e crie um novo aplicativo Slack
2. Ative o Socket Mode e obtenha o App Level Token
3. Adicione Bot Token Scopes (ex.: `chat:write`, `im:history`, etc.)
4. Instale o aplicativo no seu workspace e obtenha o Bot User OAuth Token
5. Preencha o Bot Token e o App Token no arquivo de configuração
docs/channels/slack/README.vi.md
+35
View File
@@ -0,0 +1,35 @@
> Quay lại [README](../../../README.vi.md)
# Slack
Slack là nền tảng nhắn tin tức thì hàng đầu dành cho doanh nghiệp. PicoClaw sử dụng Socket Mode của Slack để giao tiếp hai chiều theo thời gian thực, không cần cấu hình endpoint webhook công khai.
## Cấu hình
```json
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-...",
"app_token": "xapp-...",
"allow_from": []
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ---------- | ------ | -------- | ---------------------------------------------------------------------------- |
| enabled | bool | Có | Có bật kênh Slack hay không |
| bot_token | string | Có | Bot User OAuth Token của Slack bot (bắt đầu bằng xoxb-) |
| app_token | string | Có | App Level Token Socket Mode của ứng dụng Slack (bắt đầu bằng xapp-) |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống cho phép tất cả |
## Quy trình thiết lập
1. Truy cập [Slack API](https://api.slack.com/) và tạo một ứng dụng Slack mới
2. Bật Socket Mode và lấy App Level Token
3. Thêm Bot Token Scopes (ví dụ: `chat:write`, `im:history`, v.v.)
4. Cài đặt ứng dụng vào workspace và lấy Bot User OAuth Token
5. Điền Bot Token và App Token vào file cấu hình
docs/channels/slack/README.zh.md
+2
View File
@@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# Slack
Slack 是全球领先的企业级即时通讯平台。PicoClaw 采用 Slack 的 Socket Mode 实现实时双向通信，无需配置公开的 Webhook 端点。
docs/channels/telegram/README.fr.md
+35
View File
@@ -0,0 +1,35 @@
> Retour au [README](../../../README.fr.md)
# Telegram
Le canal Telegram utilise le long polling via l'API Bot Telegram pour une communication basée sur les bots. Il prend en charge les messages texte, les pièces jointes multimédias (photos, messages vocaux, audio, documents), la transcription vocale via Groq Whisper et la gestion des commandes intégrée.
## Configuration
```json
{
"channels": {
"telegram": {
"enabled": true,
"token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
"allow_from": ["123456789"],
"proxy": ""
}
}
}
```
| Champ | Type | Requis | Description |
| ---------- | ------ | ------ | ------------------------------------------------------------------------ |
| enabled | bool | Oui | Activer ou non le canal Telegram |
| token | string | Oui | Token de l'API Bot Telegram |
| allow_from | array | Non | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
| proxy | string | Non | URL du proxy pour se connecter à l'API Telegram (ex. http://127.0.0.1:7890) |
## Configuration initiale
1. Rechercher `@BotFather` dans Telegram
2. Envoyer la commande `/newbot` et suivre les instructions pour créer un nouveau bot
3. Obtenir le Token de l'API HTTP
4. Renseigner le Token dans le fichier de configuration
5. (Optionnel) Configurer `allow_from` pour restreindre les identifiants utilisateur autorisés à interagir (les IDs peuvent être obtenus via `@userinfobot`)
docs/channels/telegram/README.ja.md
+35
View File
@@ -0,0 +1,35 @@
> [README](../../../README.ja.md) に戻る
# Telegram
Telegram チャンネルは、Telegram Bot API を使用したロングポーリングによるボットベースの通信を実装しています。テキストメッセージ、メディア添付ファイル（写真、音声、オーディオ、ドキュメント）、Groq Whisper による音声文字起こし、および組み込みコマンドハンドラーをサポートしています。
## 設定
```json
{
"channels": {
"telegram": {
"enabled": true,
"token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
"allow_from": ["123456789"],
"proxy": ""
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------- | ------ | ---- | ----------------------------------------------------------------- |
| enabled | bool | はい | Telegram チャンネルを有効にするかどうか |
| token | string | はい | Telegram Bot API トークン |
| allow_from | array | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可 |
| proxy | string | いいえ | Telegram API への接続に使用するプロキシ URL (例: http://127.0.0.1:7890) |
## セットアップ手順
1. Telegram で `@BotFather` を検索する
2. `/newbot` コマンドを送信し、指示に従って新しいボットを作成する
3. HTTP API トークンを取得する
4. 設定ファイルにトークンを入力する
5. (任意) `allow_from` を設定して、対話を許可するユーザー ID を制限する（ID は `@userinfobot` で取得可能）
docs/channels/telegram/README.md
+35
View File
@@ -0,0 +1,35 @@
> Back to [README](../../../README.md)
# Telegram
The Telegram channel uses long polling via the Telegram Bot API for bot-based communication. It supports text messages, media attachments (photos, voice, audio, documents), voice transcription via Groq Whisper, and built-in command handling.
## Configuration
```json
{
"channels": {
"telegram": {
"enabled": true,
"token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
"allow_from": ["123456789"],
"proxy": ""
}
}
}
```
| Field | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------------------------------------ |
| enabled | bool | Yes | Whether to enable the Telegram channel |
| token | string | Yes | Telegram Bot API Token |
| allow_from | array | No | Allowlist of user IDs; empty means all users are allowed |
| proxy | string | No | Proxy URL for connecting to the Telegram API (e.g. http://127.0.0.1:7890) |
## Setup
1. Search for `@BotFather` in Telegram
2. Send the `/newbot` command and follow the prompts to create a new bot
3. Obtain the HTTP API Token
4. Fill in the Token in the configuration file
5. (Optional) Configure `allow_from` to restrict which user IDs can interact (you can get IDs via `@userinfobot`)
docs/channels/telegram/README.pt-br.md
+35
View File
@@ -0,0 +1,35 @@
> Voltar ao [README](../../../README.pt-br.md)
# Telegram
O canal Telegram utiliza long polling via a API de Bot do Telegram para comunicação baseada em bots. Suporta mensagens de texto, anexos de mídia (fotos, voz, áudio, documentos), transcrição de voz via Groq Whisper e tratamento de comandos integrado.
## Configuração
```json
{
"channels": {
"telegram": {
"enabled": true,
"token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
"allow_from": ["123456789"],
"proxy": ""
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ---------- | ------ | ----------- | -------------------------------------------------------------------------- |
| enabled | bool | Sim | Se o canal Telegram deve ser habilitado |
| token | string | Sim | Token da API de Bot do Telegram |
| allow_from | array | Não | Lista de IDs de usuários permitidos; vazio significa todos os usuários |
| proxy | string | Não | URL do proxy para conexão com a API do Telegram (ex. http://127.0.0.1:7890) |
## Configuração inicial
1. Pesquise por `@BotFather` no Telegram
2. Envie o comando `/newbot` e siga as instruções para criar um novo bot
3. Obtenha o Token da API HTTP
4. Preencha o Token no arquivo de configuração
5. (Opcional) Configure `allow_from` para restringir quais IDs de usuário podem interagir (os IDs podem ser obtidos via `@userinfobot`)
docs/channels/telegram/README.vi.md
+35
View File
@@ -0,0 +1,35 @@
> Quay lại [README](../../../README.vi.md)
# Telegram
Kênh Telegram sử dụng long polling qua Telegram Bot API để giao tiếp dựa trên bot. Hỗ trợ tin nhắn văn bản, tệp đính kèm đa phương tiện (ảnh, giọng nói, âm thanh, tài liệu), chuyển giọng nói thành văn bản qua Groq Whisper và xử lý lệnh tích hợp sẵn.
## Cấu hình
```json
{
"channels": {
"telegram": {
"enabled": true,
"token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
"allow_from": ["123456789"],
"proxy": ""
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
| enabled | bool | Có | Có bật kênh Telegram hay không |
| token | string | Có | Token API Bot Telegram |
| allow_from | array | Không | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả |
| proxy | string | Không | URL proxy để kết nối với Telegram API (ví dụ: http://127.0.0.1:7890) |
## Hướng dẫn thiết lập
1. Tìm kiếm `@BotFather` trong Telegram
2. Gửi lệnh `/newbot` và làm theo hướng dẫn để tạo bot mới
3. Lấy Token API HTTP
4. Điền Token vào file cấu hình
5. (Tùy chọn) Cấu hình `allow_from` để giới hạn ID người dùng được phép tương tác (có thể lấy ID qua `@userinfobot`)
docs/channels/telegram/README.zh.md
+2
View File
@@ -1,3 +1,5 @@
> 返回 [README](../../../README.zh.md)
# Telegram
Telegram Channel 通过 Telegram 机器人 API 使用长轮询实现基于机器人的通信。它支持文本消息、媒体附件（照片、语音、音频、文档）、通过 Groq Whisper 进行语音转录以及内置命令处理器。
docs/channels/wecom/wecom_aibot/README.fr.md
+118
View File
@@ -0,0 +1,118 @@
> Retour au [README](../../../../README.fr.md)
# WeCom AI Bot
Le WeCom AI Bot est une méthode d'intégration de conversation IA officiellement fournie par WeCom. Il prend en charge les conversations privées et de groupe, intègre un protocole de réponse en streaming et supporte l'envoi proactif de la réponse finale via `response_url` en cas de dépassement de délai.
## Comparaison avec les autres canaux WeCom
| Fonctionnalité | WeCom Bot | WeCom App | **WeCom AI Bot** |
|----------------|-----------|-----------|-----------------|
| Chat privé | ✅ | ✅ | ✅ |
| Chat de groupe | ✅ | ❌ | ✅ |
| Sortie en streaming | ❌ | ❌ | ✅ |
| Push proactif en cas de timeout | ❌ | ✅ | ✅ |
| Complexité de configuration | Faible | Élevée | Moyenne |
## Configuration
```json
{
"channels": {
"wecom_aibot": {
"enabled": true,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
"webhook_path": "/webhook/wecom-aibot",
"allow_from": [],
"welcome_message": "你好！有什么可以帮助你的吗？",
"max_steps": 10
}
}
}
```
| Champ | Type | Requis | Description |
| ---------------- | ------ | ------ | -------------------------------------------------- |
| token | string | Oui | Jeton de vérification du callback, configuré sur la page de gestion de l'AI Bot |
| encoding_aes_key | string | Oui | Clé AES de 43 caractères, générée aléatoirement sur la page de gestion de l'AI Bot |
| webhook_path | string | Non | Chemin du webhook (par défaut : /webhook/wecom-aibot) |
| allow_from | array | Non | Liste blanche d'ID utilisateurs ; un tableau vide autorise tous les utilisateurs |
| welcome_message | string | Non | Message de bienvenue envoyé à l'ouverture du chat ; laisser vide pour désactiver |
| reply_timeout | int | Non | Délai de réponse en secondes (par défaut : 5) |
| max_steps | int | Non | Nombre maximum d'étapes d'exécution de l'agent (par défaut : 10) |
## Procédure de configuration
1. Connectez-vous à la [console d'administration WeCom](https://work.weixin.qq.com/wework_admin)
2. Accédez à « Gestion des applications » → « AI Bot », puis créez ou sélectionnez un AI Bot
3. Sur la page de configuration de l'AI Bot, renseignez les informations de « Réception des messages » :
- **URL** : `http://<your-server-ip>:18790/webhook/wecom-aibot`
- **Token** : Généré aléatoirement ou personnalisé
- **EncodingAESKey** : Cliquez sur « Générer aléatoirement » pour obtenir une clé de 43 caractères
4. Saisissez le Token et l'EncodingAESKey dans le fichier de configuration PicoClaw, démarrez le service, puis revenez à la console d'administration pour enregistrer (WeCom enverra une requête de vérification)
> [!TIP]
> Le serveur doit être accessible par les serveurs WeCom. Si vous êtes sur un intranet ou en développement local, utilisez [ngrok](https://ngrok.com) ou frp pour le tunneling.
## Protocole de réponse en streaming
Le WeCom AI Bot utilise un protocole de « pull en streaming », différent de la réponse unique d'un webhook standard :
```
L'utilisateur envoie un message
│
▼
PicoClaw retourne immédiatement {finish: false} (l'agent commence le traitement)
│
▼
WeCom effectue un pull environ toutes les 1 seconde avec {msgtype: "stream", stream: {id: "..."}}
│
├─ Agent non terminé → retourne {finish: false} (continuer à attendre)
│
└─ Agent terminé → retourne {finish: true, content: "contenu de la réponse"}
```
**Gestion du timeout** (tâche dépassant 30 secondes) :
Si le traitement de l'agent dépasse environ 30 secondes (la fenêtre de polling maximale de WeCom est de 6 minutes), PicoClaw va :
1. Fermer immédiatement le stream et afficher à l'utilisateur : « ⏳ 正在处理中，请稍候，结果将稍后发送。 »
2. L'agent continue de s'exécuter en arrière-plan
3. Une fois l'agent terminé, la réponse finale est envoyée proactivement à l'utilisateur via le `response_url` inclus dans le message
> `response_url` est émis par WeCom, valable 1 heure, utilisable une seule fois, sans chiffrement requis — il suffit de POSTer directement le corps du message markdown.
## Message de bienvenue
Lorsque `welcome_message` est configuré, PicoClaw répond automatiquement avec ce message lorsqu'un utilisateur ouvre la fenêtre de chat avec l'AI Bot (événement `enter_chat`). Laisser vide pour ignorer silencieusement.
```json
"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
```
## FAQ
### Échec de la vérification de l'URL de callback
- Vérifiez que le pare-feu du serveur autorise le port concerné (par défaut 18790)
- Vérifiez que `token` et `encoding_aes_key` sont correctement renseignés
- Consultez les logs PicoClaw pour voir si une requête GET de WeCom a été reçue
### Les messages ne reçoivent pas de réponse
- Vérifiez que `allow_from` ne restreint pas accidentellement l'expéditeur
- Recherchez `context canceled` ou des erreurs d'agent dans les logs
- Vérifiez que la configuration de l'agent (ex. `model_name`) est correcte
### Pas de push final reçu pour les tâches longues
- Vérifiez que le callback du message inclut `response_url` (uniquement supporté par la nouvelle version du WeCom AI Bot)
- Vérifiez que le serveur peut effectuer des requêtes sortantes (nécessite un POST vers `response_url`)
- Consultez les logs pour les mots-clés `response_url mode` et `Sending reply via response_url`
## Références
- [Documentation d'intégration WeCom AI Bot](https://developer.work.weixin.qq.com/document/path/100719)
- [Description du protocole de réponse en streaming](https://developer.work.weixin.qq.com/document/path/100719)
- [Réponse proactive via response_url](https://developer.work.weixin.qq.com/document/path/101138)
docs/channels/wecom/wecom_aibot/README.ja.md
+118
View File
@@ -0,0 +1,118 @@
> [README](../../../../README.ja.md) に戻る
# 企業WeChat AIボット
企業WeChat AIボット（AI Bot）は、企業WeChatが公式に提供するAI会話連携方式です。プライベートチャットとグループチャットの両方をサポートし、ストリーミングレスポンスプロトコルを内蔵しており、タイムアウト後に `response_url` を通じて最終返信をプッシュする機能もサポートしています。
## 他のWeCom チャンネルとの比較
| 機能 | WeCom Bot | WeCom App | **WeCom AI Bot** |
|------|-----------|-----------|-----------------|
| プライベートチャット | ✅ | ✅ | ✅ |
| グループチャット | ✅ | ❌ | ✅ |
| ストリーミング出力 | ❌ | ❌ | ✅ |
| タイムアウト時のプッシュ | ❌ | ✅ | ✅ |
| 設定の複雑さ | 低 | 高 | 中 |
## 設定
```json
{
"channels": {
"wecom_aibot": {
"enabled": true,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
"webhook_path": "/webhook/wecom-aibot",
"allow_from": [],
"welcome_message": "你好！有什么可以帮助你的吗？",
"max_steps": 10
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------------- | ------ | ---- | -------------------------------------------------- |
| token | string | はい | コールバック検証トークン。AIボット管理ページで設定 |
| encoding_aes_key | string | はい | 43文字のAESキー。AIボット管理ページでランダム生成 |
| webhook_path | string | いいえ | Webhookパス（デフォルト：/webhook/wecom-aibot） |
| allow_from | array | いいえ | ユーザーIDの許可リスト。空配列は全ユーザーを許可 |
| welcome_message | string | いいえ | ユーザーがチャットを開いたときに送信するウェルカムメッセージ。空白の場合は送信しない |
| reply_timeout | int | いいえ | 返信タイムアウト（秒、デフォルト：5） |
| max_steps | int | いいえ | エージェントの最大実行ステップ数（デフォルト：10） |
## セットアップ手順
1. [企業WeChat管理コンソール](https://work.weixin.qq.com/wework_admin) にログイン
2. 「アプリ管理」→「AIボット」に進み、AIボットを作成または選択
3. AIボット設定ページで「メッセージ受信」情報を入力：
- **URL**：`http://<your-server-ip>:18790/webhook/wecom-aibot`
- **Token**：ランダム生成またはカスタム
- **EncodingAESKey**：「ランダム生成」をクリックして43文字のキーを取得
4. TokenとEncodingAESKeyをPicoClawの設定ファイルに入力し、サービスを起動してから管理コンソールに戻って保存（企業WeChatが検証リクエストを送信します）
> [!TIP]
> サーバーは企業WeChatのサーバーからアクセス可能である必要があります。イントラネットやローカル開発環境の場合は、[ngrok](https://ngrok.com) またはfrpを使用してトンネリングしてください。
## ストリーミングレスポンスプロトコル
WeCom AIボットは「ストリーミングプル」プロトコルを使用しており、通常のWebhookの一回限りの返信とは異なります：
```
ユーザーがメッセージを送信
│
▼
PicoClawが即座に {finish: false} を返す（エージェントが処理開始）
│
▼
企業WeChatが約1秒ごとに {msgtype: "stream", stream: {id: "..."}} でプル
│
├─ エージェント未完了 → {finish: false} を返す（待機継続）
│
└─ エージェント完了 → {finish: true, content: "返信内容"} を返す
```
**タイムアウト処理**（タスクが30秒を超える場合）：
エージェントの処理時間が約30秒を超えた場合（企業WeChatの最大ポーリングウィンドウは6分）、PicoClawは：
1. 即座にストリームを閉じ、ユーザーに「⏳ 正在处理中，请稍候，结果将稍后发送。」と表示
2. エージェントはバックグラウンドで処理を継続
3. エージェント完了後、メッセージに含まれる `response_url` を通じて最終返信をユーザーにプッシュ
> `response_url` は企業WeChatが発行し、有効期限は1時間、使用は1回限りで、暗号化不要。マークダウンメッセージ本文をそのままPOSTするだけです。
## ウェルカムメッセージ
`welcome_message` を設定すると、ユーザーがAIボットとのチャットウィンドウを開いたとき（`enter_chat` イベント）に、PicoClawが自動的にそのメッセージを返信します。空白の場合は無視されます。
```json
"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
```
## よくある質問
### コールバックURL検証の失敗
- サーバーのファイアウォールで該当ポートが開放されているか確認（デフォルト18790）
- `token` と `encoding_aes_key` が正しく入力されているか確認
- PicoClawのログに企業WeChatからのGETリクエストが届いているか確認
### メッセージに返信がない
- `allow_from` が誤って送信者を制限していないか確認
- ログに `context canceled` またはエージェントエラーが出ていないか確認
- エージェント設定（`model_name` など）が正しいか確認
### 長時間タスクで最終プッシュが届かない
- メッセージコールバックに `response_url` が含まれているか確認（新バージョンの企業WeChat AIボットのみ対応）
- サーバーが外部ネットワークへのアウトバウンドリクエストを送信できるか確認（`response_url` へのPOSTが必要）
- ログのキーワード `response_url mode` と `Sending reply via response_url` を確認
## 参考ドキュメント
- [企業WeChat AIボット連携ドキュメント](https://developer.work.weixin.qq.com/document/path/100719)
- [ストリーミングレスポンスプロトコルの説明](https://developer.work.weixin.qq.com/document/path/100719)
- [response_url によるプロアクティブ返信](https://developer.work.weixin.qq.com/document/path/101138)
docs/channels/wecom/wecom_aibot/README.md
+118
View File
@@ -0,0 +1,118 @@
> Back to [README](../../../../README.md)
# WeCom AI Bot
The WeCom AI Bot is an official AI conversation integration provided by WeCom. It supports both private and group chats, has a built-in streaming response protocol, and supports proactively pushing the final reply via `response_url` after a timeout.
## Comparison with Other WeCom Channels
| Feature | WeCom Bot | WeCom App | **WeCom AI Bot** |
|---------|-----------|-----------|-----------------|
| Private Chat | ✅ | ✅ | ✅ |
| Group Chat | ✅ | ❌ | ✅ |
| Streaming Output | ❌ | ❌ | ✅ |
| Proactive Push on Timeout | ❌ | ✅ | ✅ |
| Configuration Complexity | Low | High | Medium |
## Configuration
```json
{
"channels": {
"wecom_aibot": {
"enabled": true,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
"webhook_path": "/webhook/wecom-aibot",
"allow_from": [],
"welcome_message": "你好！有什么可以帮助你的吗？",
"max_steps": 10
}
}
}
```
| Field | Type | Required | Description |
| ---------------- | ------ | -------- | -------------------------------------------------- |
| token | string | Yes | Callback verification token, configured on the AI Bot management page |
| encoding_aes_key | string | Yes | 43-character AES key, randomly generated on the AI Bot management page |
| webhook_path | string | No | Webhook path (default: /webhook/wecom-aibot) |
| allow_from | array | No | User ID allowlist; empty array allows all users |
| welcome_message | string | No | Welcome message sent when a user opens the chat; leave empty to disable |
| reply_timeout | int | No | Reply timeout in seconds (default: 5) |
| max_steps | int | No | Maximum agent execution steps (default: 10) |
## Setup
1. Log in to the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin)
2. Go to "App Management" → "AI Bot", then create or select an AI Bot
3. On the AI Bot configuration page, fill in the "Message Reception" details:
- **URL**: `http://<your-server-ip>:18790/webhook/wecom-aibot`
- **Token**: Randomly generated or custom
- **EncodingAESKey**: Click "Random Generate" to get a 43-character key
4. Enter the Token and EncodingAESKey into the PicoClaw config file, start the service, then return to the admin console to save (WeCom will send a verification request)
> [!TIP]
> The server must be accessible by WeCom's servers. If you are on an intranet or developing locally, use [ngrok](https://ngrok.com) or frp for tunneling.
## Streaming Response Protocol
WeCom AI Bot uses a "streaming pull" protocol, which differs from the one-shot reply of a standard webhook:
```
User sends a message
│
▼
PicoClaw immediately returns {finish: false} (Agent starts processing)
│
▼
WeCom pulls approximately every 1 second with {msgtype: "stream", stream: {id: "..."}}
│
├─ Agent not done → returns {finish: false} (keep waiting)
│
└─ Agent done → returns {finish: true, content: "reply content"}
```
**Timeout Handling** (task exceeds 30 seconds):
If the Agent takes longer than approximately 30 seconds (WeCom's maximum polling window is 6 minutes), PicoClaw will:
1. Immediately close the stream and show the user: "⏳ 正在处理中，请稍候，结果将稍后发送。"
2. The Agent continues running in the background
3. Once the Agent finishes, the final reply is proactively pushed to the user via the `response_url` included in the message
> `response_url` is issued by WeCom, valid for 1 hour, can only be used once, requires no encryption — just POST the markdown message body directly.
## Welcome Message
When `welcome_message` is configured, PicoClaw will automatically reply with it when a user opens the chat window with the AI Bot (`enter_chat` event). Leave it empty to silently ignore the event.
```json
"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
```
## FAQ
### Callback URL Verification Failed
- Confirm the server firewall has the relevant port open (default 18790)
- Confirm `token` and `encoding_aes_key` are entered correctly
- Check PicoClaw logs to see if a GET request from WeCom was received
### Messages Not Getting a Reply
- Check whether `allow_from` is accidentally restricting the sender
- Look for `context canceled` or Agent errors in the logs
- Confirm the Agent configuration (e.g., `model_name`) is correct
### No Final Push Received for Long-Running Tasks
- Confirm the message callback includes `response_url` (only supported by the newer WeCom AI Bot)
- Confirm the server can make outbound requests (needs to POST to `response_url`)
- Check logs for keywords `response_url mode` and `Sending reply via response_url`
## Reference
- [WeCom AI Bot Integration Docs](https://developer.work.weixin.qq.com/document/path/100719)
- [Streaming Response Protocol](https://developer.work.weixin.qq.com/document/path/100719)
- [Proactive Reply via response_url](https://developer.work.weixin.qq.com/document/path/101138)
docs/channels/wecom/wecom_aibot/README.pt-br.md
+118
View File
@@ -0,0 +1,118 @@
> Voltar ao [README](../../../../README.pt-br.md)
# WeCom AI Bot
O WeCom AI Bot é uma forma oficial de integração de conversas com IA fornecida pelo WeCom. Suporta conversas privadas e em grupo, possui um protocolo de resposta em streaming integrado e suporta o envio proativo da resposta final via `response_url` após um timeout.
## Comparação com outros canais WeCom
| Recurso | WeCom Bot | WeCom App | **WeCom AI Bot** |
|---------|-----------|-----------|-----------------|
| Chat privado | ✅ | ✅ | ✅ |
| Chat em grupo | ✅ | ❌ | ✅ |
| Saída em streaming | ❌ | ❌ | ✅ |
| Push proativo em timeout | ❌ | ✅ | ✅ |
| Complexidade de configuração | Baixa | Alta | Média |
## Configuração
```json
{
"channels": {
"wecom_aibot": {
"enabled": true,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
"webhook_path": "/webhook/wecom-aibot",
"allow_from": [],
"welcome_message": "你好！有什么可以帮助你的吗？",
"max_steps": 10
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ---------------- | ------ | ----------- | -------------------------------------------------- |
| token | string | Sim | Token de verificação de callback, configurado na página de gerenciamento do AI Bot |
| encoding_aes_key | string | Sim | Chave AES de 43 caracteres, gerada aleatoriamente na página de gerenciamento do AI Bot |
| webhook_path | string | Não | Caminho do webhook (padrão: /webhook/wecom-aibot) |
| allow_from | array | Não | Lista de permissão de IDs de usuários; array vazio permite todos os usuários |
| welcome_message | string | Não | Mensagem de boas-vindas enviada quando o usuário abre o chat; deixe vazio para desativar |
| reply_timeout | int | Não | Timeout de resposta em segundos (padrão: 5) |
| max_steps | int | Não | Número máximo de etapas de execução do agente (padrão: 10) |
## Configuração passo a passo
1. Faça login no [Console de Administração do WeCom](https://work.weixin.qq.com/wework_admin)
2. Acesse "Gerenciamento de Apps" → "AI Bot", depois crie ou selecione um AI Bot
3. Na página de configuração do AI Bot, preencha as informações de "Recebimento de Mensagens":
- **URL**: `http://<your-server-ip>:18790/webhook/wecom-aibot`
- **Token**: Gerado aleatoriamente ou personalizado
- **EncodingAESKey**: Clique em "Gerar Aleatoriamente" para obter uma chave de 43 caracteres
4. Insira o Token e o EncodingAESKey no arquivo de configuração do PicoClaw, inicie o serviço e volte ao console de administração para salvar (o WeCom enviará uma requisição de verificação)
> [!TIP]
> O servidor precisa ser acessível pelos servidores do WeCom. Se estiver em uma intranet ou desenvolvendo localmente, use [ngrok](https://ngrok.com) ou frp para tunelamento.
## Protocolo de resposta em streaming
O WeCom AI Bot usa um protocolo de "pull em streaming", diferente da resposta única de um webhook padrão:
```
Usuário envia uma mensagem
│
▼
PicoClaw retorna imediatamente {finish: false} (Agente começa a processar)
│
▼
WeCom faz pull aproximadamente a cada 1 segundo com {msgtype: "stream", stream: {id: "..."}}
│
├─ Agente não concluído → retorna {finish: false} (continuar aguardando)
│
└─ Agente concluído → retorna {finish: true, content: "conteúdo da resposta"}
```
**Tratamento de timeout** (tarefa excede 30 segundos):
Se o processamento do agente demorar mais de aproximadamente 30 segundos (a janela máxima de polling do WeCom é de 6 minutos), o PicoClaw irá:
1. Fechar imediatamente o stream e exibir ao usuário: "⏳ 正在处理中，请稍候，结果将稍后发送。"
2. O agente continua executando em segundo plano
3. Após a conclusão do agente, a resposta final é enviada proativamente ao usuário via `response_url` incluído na mensagem
> `response_url` é emitido pelo WeCom, válido por 1 hora, pode ser usado apenas uma vez, sem necessidade de criptografia — basta fazer um POST com o corpo da mensagem em markdown diretamente.
## Mensagem de boas-vindas
Quando `welcome_message` está configurado, o PicoClaw responde automaticamente com essa mensagem quando um usuário abre a janela de chat com o AI Bot (evento `enter_chat`). Deixe vazio para ignorar silenciosamente.
```json
"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
```
## Perguntas frequentes
### Falha na verificação da URL de callback
- Confirme que o firewall do servidor tem a porta correspondente aberta (padrão 18790)
- Confirme que `token` e `encoding_aes_key` estão preenchidos corretamente
- Verifique os logs do PicoClaw para ver se uma requisição GET do WeCom foi recebida
### Mensagens sem resposta
- Verifique se `allow_from` está restringindo acidentalmente o remetente
- Procure por `context canceled` ou erros do agente nos logs
- Confirme que a configuração do agente (ex.: `model_name`) está correta
### Nenhum push final recebido para tarefas longas
- Confirme que o callback da mensagem inclui `response_url` (suportado apenas pelo novo WeCom AI Bot)
- Confirme que o servidor consegue fazer requisições de saída (precisa fazer POST para `response_url`)
- Verifique nos logs as palavras-chave `response_url mode` e `Sending reply via response_url`
## Referências
- [Documentação de integração do WeCom AI Bot](https://developer.work.weixin.qq.com/document/path/100719)
- [Descrição do protocolo de resposta em streaming](https://developer.work.weixin.qq.com/document/path/100719)
- [Resposta proativa via response_url](https://developer.work.weixin.qq.com/document/path/101138)
docs/channels/wecom/wecom_aibot/README.vi.md
+118
View File
@@ -0,0 +1,118 @@
> Quay lại [README](../../../../README.vi.md)
# WeCom AI Bot
WeCom AI Bot là phương thức tích hợp hội thoại AI chính thức do WeCom cung cấp. Hỗ trợ cả chat riêng tư và chat nhóm, tích hợp giao thức phản hồi streaming, và hỗ trợ chủ động đẩy phản hồi cuối cùng qua `response_url` sau khi hết thời gian chờ.
## So sánh với các kênh WeCom khác
| Tính năng | WeCom Bot | WeCom App | **WeCom AI Bot** |
|-----------|-----------|-----------|-----------------|
| Chat riêng tư | ✅ | ✅ | ✅ |
| Chat nhóm | ✅ | ❌ | ✅ |
| Đầu ra streaming | ❌ | ❌ | ✅ |
| Đẩy chủ động khi timeout | ❌ | ✅ | ✅ |
| Độ phức tạp cấu hình | Thấp | Cao | Trung bình |
## Cấu hình
```json
{
"channels": {
"wecom_aibot": {
"enabled": true,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
"webhook_path": "/webhook/wecom-aibot",
"allow_from": [],
"welcome_message": "你好！有什么可以帮助你的吗？",
"max_steps": 10
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ---------------- | ------ | --------- | -------------------------------------------------- |
| token | string | Có | Token xác minh callback, cấu hình trên trang quản lý AI Bot |
| encoding_aes_key | string | Có | Khóa AES 43 ký tự, được tạo ngẫu nhiên trên trang quản lý AI Bot |
| webhook_path | string | Không | Đường dẫn webhook (mặc định: /webhook/wecom-aibot) |
| allow_from | array | Không | Danh sách cho phép ID người dùng; mảng rỗng cho phép tất cả người dùng |
| welcome_message | string | Không | Tin nhắn chào mừng gửi khi người dùng mở chat; để trống để tắt |
| reply_timeout | int | Không | Thời gian chờ phản hồi tính bằng giây (mặc định: 5) |
| max_steps | int | Không | Số bước thực thi tối đa của agent (mặc định: 10) |
## Hướng dẫn thiết lập
1. Đăng nhập vào [Bảng điều khiển quản trị WeCom](https://work.weixin.qq.com/wework_admin)
2. Vào "Quản lý ứng dụng" → "AI Bot", sau đó tạo hoặc chọn một AI Bot
3. Trên trang cấu hình AI Bot, điền thông tin "Nhận tin nhắn":
- **URL**: `http://<your-server-ip>:18790/webhook/wecom-aibot`
- **Token**: Tạo ngẫu nhiên hoặc tùy chỉnh
- **EncodingAESKey**: Nhấp "Tạo ngẫu nhiên" để lấy khóa 43 ký tự
4. Nhập Token và EncodingAESKey vào file cấu hình PicoClaw, khởi động dịch vụ rồi quay lại bảng điều khiển quản trị để lưu (WeCom sẽ gửi yêu cầu xác minh)
> [!TIP]
> Máy chủ cần có thể truy cập được từ các máy chủ WeCom. Nếu bạn đang ở mạng nội bộ hoặc phát triển cục bộ, hãy sử dụng [ngrok](https://ngrok.com) hoặc frp để tạo tunnel.
## Giao thức phản hồi streaming
WeCom AI Bot sử dụng giao thức "pull streaming", khác với phản hồi một lần của webhook thông thường:
```
Người dùng gửi tin nhắn
│
▼
PicoClaw trả về ngay {finish: false} (Agent bắt đầu xử lý)
│
▼
WeCom pull khoảng mỗi 1 giây với {msgtype: "stream", stream: {id: "..."}}
│
├─ Agent chưa xong → trả về {finish: false} (tiếp tục chờ)
│
└─ Agent xong → trả về {finish: true, content: "nội dung phản hồi"}
```
**Xử lý timeout** (tác vụ vượt quá 30 giây):
Nếu thời gian xử lý của agent vượt quá khoảng 30 giây (cửa sổ polling tối đa của WeCom là 6 phút), PicoClaw sẽ:
1. Đóng stream ngay lập tức và hiển thị cho người dùng: "⏳ 正在处理中，请稍候，结果将稍后发送。"
2. Agent tiếp tục chạy ở nền
3. Sau khi agent hoàn thành, phản hồi cuối cùng được chủ động đẩy đến người dùng qua `response_url` có trong tin nhắn
> `response_url` do WeCom cấp, có hiệu lực 1 giờ, chỉ dùng được một lần, không cần mã hóa — chỉ cần POST trực tiếp nội dung tin nhắn markdown.
## Tin nhắn chào mừng
Khi `welcome_message` được cấu hình, PicoClaw sẽ tự động phản hồi bằng tin nhắn đó khi người dùng mở cửa sổ chat với AI Bot (sự kiện `enter_chat`). Để trống để bỏ qua im lặng.
```json
"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
```
## Câu hỏi thường gặp
### Xác minh URL callback thất bại
- Xác nhận tường lửa máy chủ đã mở cổng tương ứng (mặc định 18790)
- Xác nhận `token` và `encoding_aes_key` được điền đúng
- Kiểm tra log PicoClaw xem có nhận được yêu cầu GET từ WeCom không
### Tin nhắn không nhận được phản hồi
- Kiểm tra xem `allow_from` có vô tình hạn chế người gửi không
- Tìm `context canceled` hoặc lỗi agent trong log
- Xác nhận cấu hình agent (ví dụ: `model_name`) là đúng
### Không nhận được push cuối cùng cho tác vụ dài
- Xác nhận callback tin nhắn có chứa `response_url` (chỉ hỗ trợ bởi WeCom AI Bot phiên bản mới)
- Xác nhận máy chủ có thể thực hiện yêu cầu ra ngoài (cần POST đến `response_url`)
- Kiểm tra log với từ khóa `response_url mode` và `Sending reply via response_url`
## Tài liệu tham khảo
- [Tài liệu tích hợp WeCom AI Bot](https://developer.work.weixin.qq.com/document/path/100719)
- [Mô tả giao thức phản hồi streaming](https://developer.work.weixin.qq.com/document/path/100719)
- [Phản hồi chủ động qua response_url](https://developer.work.weixin.qq.com/document/path/101138)
docs/channels/wecom/wecom_aibot/README.zh.md
+4 -1
View File
@@ -1,3 +1,5 @@
> 返回 [README](../../../../README.zh.md)
# 企业微信智能机器人 (AI Bot)
企业微信智能机器人（AI Bot）是企业微信官方提供的 AI 对话接入方式，支持私聊与群聊，内置流式响应协议。PicoClaw 当前同时支持两种接入模式：
@@ -97,7 +99,7 @@
1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin)
2. 进入"应用管理" → "智能机器人"，创建或选择一个 AI Bot
3. 在 AI Bot 配置页面，填写"消息接收"信息：
- **URL**：`http://<your-server-ip>:18791/webhook/wecom-aibot`
- **URL**：`http://<your-server-ip>:18790/webhook/wecom-aibot`
- **Token**：随机生成或自定义
- **EncodingAESKey**：点击"随机生成"，得到 43 字符密钥
4. 将 Token 和 EncodingAESKey 填入 PicoClaw 配置文件，启动服务后回到管理后台保存
@@ -159,6 +161,7 @@ PicoClaw 立即返回 {finish: false}（Agent 开始处理）
### 回调 URL 验证失败
- 确认 `token` 与 `encoding_aes_key` 填写正确
- 确认服务器防火墙已开放对应端口
- 检查 PicoClaw 日志是否收到了来自企业微信的验证请求
docs/channels/wecom/wecom_app/README.fr.md
+47
View File
@@ -0,0 +1,47 @@
> Retour au [README](../../../../README.fr.md)
# Application interne WeCom
Une application interne WeCom est une application créée par une entreprise au sein de WeCom, principalement destinée à un usage interne. Grâce aux applications internes WeCom, les entreprises peuvent assurer une communication et une collaboration efficaces avec leurs employés, améliorant ainsi la productivité.
## Configuration
```json
{
"channels": {
"wecom_app": {
"enabled": true,
"corp_id": "wwxxxxxxxxxxxxxxxx",
"corp_secret": "YOUR_CORP_SECRET",
"agent_id": 1000002,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
"webhook_path": "/webhook/wecom-app",
"allow_from": [],
"reply_timeout": 5
}
}
}
```
| Champ | Type | Requis | Description |
| ---------------- | ------ | ------ | ---------------------------------------- |
| corp_id | string | Oui | ID de l'entreprise |
| corp_secret | string | Oui | Secret de l'application |
| agent_id | int | Oui | ID de l'agent de l'application |
| token | string | Oui | Jeton de vérification du callback |
| encoding_aes_key | string | Oui | Clé AES de 43 caractères |
| webhook_path | string | Non | Chemin du webhook (par défaut : /webhook/wecom-app) |
| allow_from | array | Non | Liste blanche d'ID utilisateurs |
| reply_timeout | int | Non | Délai de réponse en secondes |
## Procédure de configuration
1. Connectez-vous à la [console d'administration WeCom](https://work.weixin.qq.com/)
2. Accédez à « Gestion des applications » -> « Créer une application »
3. Obtenez l'ID d'entreprise (CorpID) et le Secret de l'application
4. Configurez « Réception des messages » dans les paramètres de l'application pour obtenir le Token et l'EncodingAESKey
5. Définissez l'URL de callback sur `http://<your-server-ip>:<port>/webhook/wecom-app`
6. Saisissez le CorpID, le Secret, l'AgentID et les autres informations dans le fichier de configuration
Remarque : PicoClaw utilise désormais un serveur HTTP Gateway partagé pour recevoir les callbacks webhook de tous les canaux. L'adresse d'écoute par défaut est 127.0.0.1:18790. Pour recevoir des callbacks depuis l'internet public, configurez un reverse proxy de votre domaine externe vers le Gateway (port par défaut 18790).
docs/channels/wecom/wecom_app/README.ja.md
+47
View File
@@ -0,0 +1,47 @@
> [README](../../../../README.ja.md) に戻る
# 企業WeChat 自社開発アプリ
企業WeChat 自社開発アプリとは、企業が企業WeChat内で作成するアプリケーションで、主に社内利用を目的としています。企業WeChat 自社開発アプリを通じて、企業は従業員との効率的なコミュニケーションと協業を実現し、業務効率を向上させることができます。
## 設定
```json
{
"channels": {
"wecom_app": {
"enabled": true,
"corp_id": "wwxxxxxxxxxxxxxxxx",
"corp_secret": "YOUR_CORP_SECRET",
"agent_id": 1000002,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
"webhook_path": "/webhook/wecom-app",
"allow_from": [],
"reply_timeout": 5
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------------- | ------ | ---- | ---------------------------------------- |
| corp_id | string | はい | 企業ID |
| corp_secret | string | はい | アプリケーションシークレット |
| agent_id | int | はい | アプリケーションエージェントID |
| token | string | はい | コールバック検証トークン |
| encoding_aes_key | string | はい | 43文字のAESキー |
| webhook_path | string | いいえ | Webhookパス（デフォルト：/webhook/wecom-app） |
| allow_from | array | いいえ | ユーザーIDの許可リスト |
| reply_timeout | int | いいえ | 返信タイムアウト（秒） |
## セットアップ手順
1. [企業WeChat管理コンソール](https://work.weixin.qq.com/) にログイン
2. 「アプリ管理」→「アプリを作成」に進む
3. 企業ID（CorpID）とアプリのSecretを取得
4. アプリ設定で「メッセージ受信」を設定し、TokenとEncodingAESKeyを取得
5. コールバックURLを `http://<your-server-ip>:<port>/webhook/wecom-app` に設定
6. CorpID、Secret、AgentIDなどの情報を設定ファイルに入力
注意：PicoClawは現在、すべてのチャンネルのwebhookコールバックを受信するために共有のGateway HTTPサーバーを使用しています。デフォルトのリスニングアドレスは127.0.0.1:18790です。公共インターネットからコールバックを受信するには、外部ドメインをGateway（デフォルトポート18790）にリバースプロキシしてください。
docs/channels/wecom/wecom_app/README.md
+47
View File
@@ -0,0 +1,47 @@
> Back to [README](../../../../README.md)
# WeCom Internal App
A WeCom Internal App is an application created by an enterprise within WeCom, primarily intended for internal use. Through WeCom Internal Apps, enterprises can achieve efficient communication and collaboration with employees, improving productivity.
## Configuration
```json
{
"channels": {
"wecom_app": {
"enabled": true,
"corp_id": "wwxxxxxxxxxxxxxxxx",
"corp_secret": "YOUR_CORP_SECRET",
"agent_id": 1000002,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
"webhook_path": "/webhook/wecom-app",
"allow_from": [],
"reply_timeout": 5
}
}
}
```
| Field | Type | Required | Description |
| ---------------- | ------ | -------- | ---------------------------------------- |
| corp_id | string | Yes | Enterprise ID |
| corp_secret | string | Yes | Application secret |
| agent_id | int | Yes | Application agent ID |
| token | string | Yes | Callback verification token |
| encoding_aes_key | string | Yes | 43-character AES key |
| webhook_path | string | No | Webhook path (default: /webhook/wecom-app) |
| allow_from | array | No | User ID allowlist |
| reply_timeout | int | No | Reply timeout in seconds |
## Setup
1. Log in to the [WeCom Admin Console](https://work.weixin.qq.com/)
2. Go to "App Management" -> "Create App"
3. Obtain the Enterprise ID (CorpID) and App Secret
4. Configure "Receive Messages" in the app settings to get the Token and EncodingAESKey
5. Set the callback URL to `http://<your-server-ip>:<port>/webhook/wecom-app`
6. Enter the CorpID, Secret, AgentID, and other details into the config file
Note: PicoClaw now uses a shared Gateway HTTP server to receive webhook callbacks for all channels. The default listening address is 127.0.0.1:18790. To receive callbacks from the public internet, reverse-proxy your external domain to the Gateway (default port 18790).
docs/channels/wecom/wecom_app/README.pt-br.md
+47
View File
@@ -0,0 +1,47 @@
> Voltar ao [README](../../../../README.pt-br.md)
# App Interno WeCom
Um App Interno WeCom é um aplicativo criado por uma empresa dentro do WeCom, destinado principalmente ao uso interno. Por meio dos Apps Internos WeCom, as empresas podem alcançar comunicação e colaboração eficientes com os funcionários, melhorando a produtividade.
## Configuração
```json
{
"channels": {
"wecom_app": {
"enabled": true,
"corp_id": "wwxxxxxxxxxxxxxxxx",
"corp_secret": "YOUR_CORP_SECRET",
"agent_id": 1000002,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
"webhook_path": "/webhook/wecom-app",
"allow_from": [],
"reply_timeout": 5
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ---------------- | ------ | ----------- | ---------------------------------------- |
| corp_id | string | Sim | ID da empresa |
| corp_secret | string | Sim | Segredo da aplicação |
| agent_id | int | Sim | ID do agente da aplicação |
| token | string | Sim | Token de verificação de callback |
| encoding_aes_key | string | Sim | Chave AES de 43 caracteres |
| webhook_path | string | Não | Caminho do webhook (padrão: /webhook/wecom-app) |
| allow_from | array | Não | Lista de permissão de IDs de usuários |
| reply_timeout | int | Não | Timeout de resposta em segundos |
## Configuração passo a passo
1. Faça login no [Console de Administração do WeCom](https://work.weixin.qq.com/)
2. Acesse "Gerenciamento de Apps" -> "Criar App"
3. Obtenha o ID da Empresa (CorpID) e o Secret do App
4. Configure "Receber Mensagens" nas configurações do app para obter o Token e o EncodingAESKey
5. Defina a URL de callback como `http://<your-server-ip>:<port>/webhook/wecom-app`
6. Insira o CorpID, Secret, AgentID e outras informações no arquivo de configuração
Nota: O PicoClaw agora usa um servidor HTTP Gateway compartilhado para receber callbacks de webhook de todos os canais. O endereço de escuta padrão é 127.0.0.1:18790. Para receber callbacks da internet pública, configure um reverse proxy do seu domínio externo para o Gateway (porta padrão 18790).
docs/channels/wecom/wecom_app/README.vi.md
+47
View File
@@ -0,0 +1,47 @@
> Quay lại [README](../../../../README.vi.md)
# Ứng dụng nội bộ WeCom
Ứng dụng nội bộ WeCom là ứng dụng được doanh nghiệp tạo ra trong WeCom, chủ yếu dùng cho mục đích nội bộ. Thông qua ứng dụng nội bộ WeCom, doanh nghiệp có thể thực hiện giao tiếp và cộng tác hiệu quả với nhân viên, nâng cao hiệu suất làm việc.
## Cấu hình
```json
{
"channels": {
"wecom_app": {
"enabled": true,
"corp_id": "wwxxxxxxxxxxxxxxxx",
"corp_secret": "YOUR_CORP_SECRET",
"agent_id": 1000002,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
"webhook_path": "/webhook/wecom-app",
"allow_from": [],
"reply_timeout": 5
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ---------------- | ------ | --------- | ---------------------------------------- |
| corp_id | string | Có | ID doanh nghiệp |
| corp_secret | string | Có | Secret của ứng dụng |
| agent_id | int | Có | ID agent của ứng dụng |
| token | string | Có | Token xác minh callback |
| encoding_aes_key | string | Có | Khóa AES 43 ký tự |
| webhook_path | string | Không | Đường dẫn webhook (mặc định: /webhook/wecom-app) |
| allow_from | array | Không | Danh sách cho phép ID người dùng |
| reply_timeout | int | Không | Thời gian chờ phản hồi tính bằng giây |
## Hướng dẫn thiết lập
1. Đăng nhập vào [Bảng điều khiển quản trị WeCom](https://work.weixin.qq.com/)
2. Vào "Quản lý ứng dụng" -> "Tạo ứng dụng"
3. Lấy ID doanh nghiệp (CorpID) và Secret của ứng dụng
4. Cấu hình "Nhận tin nhắn" trong cài đặt ứng dụng để lấy Token và EncodingAESKey
5. Đặt URL callback thành `http://<your-server-ip>:<port>/webhook/wecom-app`
6. Nhập CorpID, Secret, AgentID và các thông tin khác vào file cấu hình
Lưu ý: PicoClaw hiện sử dụng máy chủ HTTP Gateway dùng chung để nhận callback webhook cho tất cả các kênh. Địa chỉ lắng nghe mặc định là 127.0.0.1:18790. Để nhận callback từ internet công cộng, hãy cấu hình reverse proxy từ tên miền bên ngoài của bạn đến Gateway (cổng mặc định 18790).
docs/channels/wecom/wecom_app/README.zh.md
+2
View File
@@ -1,3 +1,5 @@
> 返回 [README](../../../../README.zh.md)
# 企业微信自建应用
企业微信自建应用是指企业在企业微信中创建的应用，主要用于企业内部使用。通过企业微信自建应用，企业可以实现与员工的高效沟通和协作，提高工作效率。
docs/channels/wecom/wecom_bot/README.fr.md
+41
View File
@@ -0,0 +1,41 @@
> Retour au [README](../../../../README.fr.md)
# WeCom Bot
Le WeCom Bot est une méthode d'intégration rapide fournie par WeCom, permettant de recevoir des messages via une URL Webhook.
## Configuration
```json
{
"channels": {
"wecom": {
"enabled": true,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
"webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
"webhook_path": "/webhook/wecom",
"allow_from": [],
"reply_timeout": 5
}
}
}
```
| Champ | Type | Requis | Description |
| ---------------- | ------ | ------ | -------------------------------------------- |
| token | string | Oui | Jeton de vérification de signature |
| encoding_aes_key | string | Oui | Clé AES de 43 caractères utilisée pour le déchiffrement |
| webhook_url | string | Oui | URL Webhook du bot de groupe WeCom utilisée pour envoyer les réponses |
| webhook_path | string | Non | Chemin de l'endpoint webhook (par défaut : /webhook/wecom) |
| allow_from | array | Non | Liste blanche d'ID utilisateurs (vide = autoriser tous les utilisateurs) |
| reply_timeout | int | Non | Délai de réponse en secondes (par défaut : 5) |
## Procédure de configuration
1. Ajouter un bot à un groupe WeCom
2. Obtenir l'URL Webhook
3. (Pour recevoir des messages) Configurer l'adresse API de réception des messages (URL de callback), le Token et l'EncodingAESKey sur la page de configuration du bot
4. Saisir les informations pertinentes dans le fichier de configuration
Remarque : PicoClaw utilise désormais un serveur HTTP Gateway partagé pour recevoir les callbacks webhook de tous les canaux. L'adresse d'écoute par défaut est 127.0.0.1:18790. Pour recevoir des callbacks depuis l'internet public, configurez un reverse proxy de votre domaine externe vers le Gateway (port par défaut 18790).
docs/channels/wecom/wecom_bot/README.ja.md
+41
View File
@@ -0,0 +1,41 @@
> [README](../../../../README.ja.md) に戻る
# 企業WeChat ボット
企業WeChat ボットは、企業WeChatが提供するWebhook URLを通じてメッセージを受信できる迅速な連携方式です。
## 設定
```json
{
"channels": {
"wecom": {
"enabled": true,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
"webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
"webhook_path": "/webhook/wecom",
"allow_from": [],
"reply_timeout": 5
}
}
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------------- | ------ | ---- | -------------------------------------------- |
| token | string | はい | 署名検証トークン |
| encoding_aes_key | string | はい | 復号化に使用する43文字のAESキー |
| webhook_url | string | はい | 返信送信に使用する企業WeChatグループボットのWebhook URL |
| webhook_path | string | いいえ | Webhookエンドポイントパス（デフォルト：/webhook/wecom） |
| allow_from | array | いいえ | ユーザーIDの許可リスト（空 = 全ユーザーを許可） |
| reply_timeout | int | いいえ | 返信タイムアウト（秒、デフォルト：5） |
## セットアップ手順
1. 企業WeChatグループにボットを追加
2. Webhook URLを取得
3. （メッセージを受信する場合）ボット設定ページでメッセージ受信APIアドレス（コールバックURL）、Token、EncodingAESKeyを設定
4. 関連情報を設定ファイルに入力
注意：PicoClawは現在、すべてのチャンネルのwebhookコールバックを受信するために共有のGateway HTTPサーバーを使用しています。デフォルトのリスニングアドレスは127.0.0.1:18790です。公共インターネットからコールバックを受信するには、外部ドメインをGateway（デフォルトポート18790）にリバースプロキシしてください。
docs/channels/wecom/wecom_bot/README.md
+41
View File
@@ -0,0 +1,41 @@
> Back to [README](../../../../README.md)
# WeCom Bot
WeCom Bot is a quick integration method provided by WeCom that can receive messages via a Webhook URL.
## Configuration
```json
{
"channels": {
"wecom": {
"enabled": true,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
"webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
"webhook_path": "/webhook/wecom",
"allow_from": [],
"reply_timeout": 5
}
}
}
```
| Field | Type | Required | Description |
| ---------------- | ------ | -------- | -------------------------------------------- |
| token | string | Yes | Signature verification token |
| encoding_aes_key | string | Yes | 43-character AES key used for decryption |
| webhook_url | string | Yes | WeCom group bot webhook URL used to send replies |
| webhook_path | string | No | Webhook endpoint path (default: /webhook/wecom) |
| allow_from | array | No | User ID allowlist (empty = allow all users) |
| reply_timeout | int | No | Reply timeout in seconds (default: 5) |
## Setup
1. Add a bot to a WeCom group
2. Obtain the Webhook URL
3. (To receive messages) Configure the message receiving API address (callback URL), Token, and EncodingAESKey on the bot configuration page
4. Enter the relevant information into the config file
Note: PicoClaw now uses a shared Gateway HTTP server to receive webhook callbacks for all channels. The default listening address is 127.0.0.1:18790. To receive callbacks from the public internet, reverse-proxy your external domain to the Gateway (default port 18790).
docs/channels/wecom/wecom_bot/README.pt-br.md
+41
View File
@@ -0,0 +1,41 @@
> Voltar ao [README](../../../../README.pt-br.md)
# WeCom Bot
O WeCom Bot é um método de integração rápida fornecido pelo WeCom que pode receber mensagens via URL de Webhook.
## Configuração
```json
{
"channels": {
"wecom": {
"enabled": true,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
"webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
"webhook_path": "/webhook/wecom",
"allow_from": [],
"reply_timeout": 5
}
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| ---------------- | ------ | ----------- | -------------------------------------------- |
| token | string | Sim | Token de verificação de assinatura |
| encoding_aes_key | string | Sim | Chave AES de 43 caracteres usada para descriptografia |
| webhook_url | string | Sim | URL do webhook do bot de grupo WeCom usada para enviar respostas |
| webhook_path | string | Não | Caminho do endpoint webhook (padrão: /webhook/wecom) |
| allow_from | array | Não | Lista de permissão de IDs de usuários (vazio = permitir todos) |
| reply_timeout | int | Não | Timeout de resposta em segundos (padrão: 5) |
## Configuração passo a passo
1. Adicione um bot a um grupo WeCom
2. Obtenha a URL do Webhook
3. (Para receber mensagens) Configure o endereço da API de recebimento de mensagens (URL de callback), Token e EncodingAESKey na página de configuração do bot
4. Insira as informações relevantes no arquivo de configuração
Nota: O PicoClaw agora usa um servidor HTTP Gateway compartilhado para receber callbacks de webhook de todos os canais. O endereço de escuta padrão é 127.0.0.1:18790. Para receber callbacks da internet pública, configure um reverse proxy do seu domínio externo para o Gateway (porta padrão 18790).
docs/channels/wecom/wecom_bot/README.vi.md
+41
View File
@@ -0,0 +1,41 @@
> Quay lại [README](../../../../README.vi.md)
# WeCom Bot
WeCom Bot là phương thức tích hợp nhanh do WeCom cung cấp, có thể nhận tin nhắn qua URL Webhook.
## Cấu hình
```json
{
"channels": {
"wecom": {
"enabled": true,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
"webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
"webhook_path": "/webhook/wecom",
"allow_from": [],
"reply_timeout": 5
}
}
}
```
| Trường | Kiểu | Bắt buộc | Mô tả |
| ---------------- | ------ | --------- | -------------------------------------------- |
| token | string | Có | Token xác minh chữ ký |
| encoding_aes_key | string | Có | Khóa AES 43 ký tự dùng để giải mã |
| webhook_url | string | Có | URL webhook của bot nhóm WeCom dùng để gửi phản hồi |
| webhook_path | string | Không | Đường dẫn endpoint webhook (mặc định: /webhook/wecom) |
| allow_from | array | Không | Danh sách cho phép ID người dùng (rỗng = cho phép tất cả) |
| reply_timeout | int | Không | Thời gian chờ phản hồi tính bằng giây (mặc định: 5) |
## Hướng dẫn thiết lập
1. Thêm bot vào một nhóm WeCom
2. Lấy URL Webhook
3. (Để nhận tin nhắn) Cấu hình địa chỉ API nhận tin nhắn (URL callback), Token và EncodingAESKey trên trang cấu hình bot
4. Nhập thông tin liên quan vào file cấu hình
Lưu ý: PicoClaw hiện sử dụng máy chủ HTTP Gateway dùng chung để nhận callback webhook cho tất cả các kênh. Địa chỉ lắng nghe mặc định là 127.0.0.1:18790. Để nhận callback từ internet công cộng, hãy cấu hình reverse proxy từ tên miền bên ngoài của bạn đến Gateway (cổng mặc định 18790).
docs/channels/wecom/wecom_bot/README.zh.md
+2
View File
@@ -1,3 +1,5 @@
> 返回 [README](../../../../README.zh.md)
# 企业微信机器人
企业微信机器人是企业微信提供的一种快速接入方式，可以通过 Webhook URL 接收消息。
docs/chat-apps.md
+181 -28
View File
@@ -8,22 +8,22 @@ Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk,
> **Note**: All webhook-based channels (LINE, WeCom, etc.) are served on a single shared Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). There are no per-channel ports to configure. Note: Feishu uses WebSocket/SDK mode and does not use the shared HTTP webhook server.
| Channel | Setup |
| ------------ | ---------------------------------- |
| **Telegram** | Easy (just a token) |
| **Discord** | Easy (bot token + intents) |
| **WhatsApp** | Easy (native: QR scan; or bridge URL) |
| **Matrix** | Medium (homeserver + bot access token) |
| **QQ** | Easy (AppID + AppSecret) |
| **DingTalk** | Medium (app credentials) |
| **LINE** | Medium (credentials + webhook URL) |
| **WeCom AI Bot** | Medium (Token + AES key) |
| **Feishu** | Medium (App ID + Secret, WebSocket mode) |
| **Slack** | Medium (Bot token + App token) |
| **IRC** | Medium (server + TLS config) |
| **OneBot** | Medium (QQ via OneBot protocol) |
| **MaixCam** | Easy (Sipeed hardware integration) |
| **Pico** | Native PicoClaw protocol |
| Channel | Difficulty | Description | Documentation |
| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Telegram** | ⭐ Easy | Recommended, voice-to-text, long polling (no public IP needed) | [Docs](../channels/telegram/README.md) |
| **Discord** | ⭐ Easy | Socket Mode, group/DM support, rich bot ecosystem | [Docs](../channels/discord/README.md) |
| **WhatsApp** | ⭐ Easy | Native (QR scan) or Bridge URL | [Docs](#whatsapp) |
| **Slack** | ⭐ Easy | **Socket Mode** (no public IP needed), enterprise | [Docs](../channels/slack/README.md) |
| **Matrix** | ⭐⭐ Medium | Federated protocol, self-hosting supported | [Docs](../channels/matrix/README.md) |
| **QQ** | ⭐⭐ Medium | Official bot API, Chinese community | [Docs](../channels/qq/README.md) |
| **DingTalk** | ⭐⭐ Medium | Stream mode (no public IP needed), enterprise | [Docs](../channels/dingtalk/README.md) |
| **LINE** | ⭐⭐⭐ Advanced | HTTPS Webhook required | [Docs](../channels/line/README.md) |
| **WeCom (企业微信)** | ⭐⭐⭐ Advanced | Group Bot (Webhook), custom App (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.md) / [App](../channels/wecom/wecom_app/README.md) / [AI Bot](../channels/wecom/wecom_aibot/README.md) |
| **Feishu (飞书)** | ⭐⭐⭐ Advanced | Enterprise collaboration, feature-rich | [Docs](../channels/feishu/README.md) |
| **IRC** | ⭐⭐ Medium | Server + TLS configuration | - |
| **OneBot** | ⭐⭐ Medium | NapCat/Go-CQHTTP compatible, community ecosystem | [Docs](../channels/onebot/README.md) |
| **MaixCam** | ⭐ Easy | Hardware integration channel for Sipeed AI cameras | [Docs](../channels/maixcam/README.md) |
| **Pico** | ⭐ Easy | Native PicoClaw protocol channel | |
<details>
<summary><b>Telegram</b> (Recommended)</summary>
@@ -172,12 +172,13 @@ If `session_store_path` is empty, the session is stored in `<workspace>/whatsapp
<details>
<summary><b>QQ</b></summary>
**1. Create a bot**
**Quick setup (recommended)**
- Go to [QQ Open Platform](https://q.qq.com/#)
- Create an application → Get **AppID** and **AppSecret**
QQ Open Platform provides a one-click setup page for OpenClaw-compatible bots:
**2. Configure**
1. Open [QQ Bot Quick Start](https://q.qq.com/qqbot/openclaw/index.html) and scan the QR code to log in
2. A bot is created automatically — copy the **App ID** and **App Secret**
3. Configure PicoClaw:
```json
{
@@ -192,13 +193,20 @@ If `session_store_path` is empty, the session is stored in `<workspace>/whatsapp
}
```
> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access.
4. Run `picoclaw gateway` and open QQ to chat with your bot
**3. Run**
> The App Secret is only shown once. Save it immediately — viewing it again will force a reset.
>
> Bots created via the quick setup page are initially for the creator only and do not support group chats. To enable group access, configure sandbox mode on the [QQ Open Platform](https://q.qq.com/).
```bash
picoclaw gateway
```
**Manual setup**
If you prefer to create the bot manually:
* Log in at [QQ Open Platform](https://q.qq.com/) to register as a developer
* Create a QQ bot — customize its avatar and name
* Copy the **App ID** and **App Secret** from the bot settings
* Configure as shown above and run `picoclaw gateway`
</details>
@@ -265,7 +273,7 @@ picoclaw gateway
picoclaw gateway
```
For full options (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), see [Matrix Channel Configuration Guide](docs/channels/matrix/README.md).
For full options (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), see [Matrix Channel Configuration Guide](channels/matrix/README.md).
</details>
@@ -326,7 +334,7 @@ PicoClaw supports three types of WeCom integration:
**Option 2: WeCom App (Custom App)** - More features, proactive messaging, private chat only
**Option 3: WeCom AI Bot (AI Bot)** - Official AI Bot, streaming replies, supports group & private chat
See [WeCom AI Bot Configuration Guide](docs/channels/wecom/wecom_aibot/README.zh.md) for detailed setup instructions.
See [WeCom AI Bot Configuration Guide](channels/wecom/wecom_aibot/README.md) for detailed setup instructions.
**Quick Setup - WeCom Bot:**
@@ -400,7 +408,7 @@ picoclaw gateway
**1. Create an AI Bot**
* Go to WeCom Admin Console → App Management → AI Bot
* In the AI Bot settings, configure callback URL: `http://your-server:18791/webhook/wecom-aibot`
* In the AI Bot settings, configure callback URL: `http://your-server:18790/webhook/wecom-aibot`
* Copy **Token** and click "Random Generate" for **EncodingAESKey**
**2. Configure**
@@ -430,3 +438,148 @@ picoclaw gateway
> **Note**: WeCom AI Bot uses streaming pull protocol — no reply timeout concerns. Long tasks (>30 seconds) automatically switch to `response_url` push delivery.
</details>
<details>
<summary><b>Feishu (Lark)</b></summary>
PicoClaw connects to Feishu via WebSocket/SDK mode — no public webhook URL or callback server needed.
**1. Create an app**
* Go to [Feishu Open Platform](https://open.feishu.cn/) and create an application
* In the app settings, enable the **Bot** capability
* Create a version and publish the app (the app must be published to take effect)
* Copy the **App ID** (starts with `cli_`) and **App Secret**
**2. Configure**
```json
{
"channels": {
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
Optional fields: `encrypt_key` and `verification_token` for event encryption (recommended for production).
**3. Run and chat**
```bash
picoclaw gateway
```
Open Feishu, search for your bot name, and start chatting. You can also add the bot to a group — use `group_trigger.mention_only: true` to only respond when @mentioned.
For full options, see [Feishu Channel Configuration Guide](channels/feishu/README.md).
</details>
<details>
<summary><b>Slack</b></summary>
**1. Create a Slack app**
* Go to [Slack API](https://api.slack.com/apps) and create a new app
* Under **OAuth & Permissions**, add bot scopes: `chat:write`, `app_mentions:read`, `im:history`, `im:read`, `im:write`
* Install the app to your workspace
* Copy the **Bot Token** (`xoxb-...`) and **App-Level Token** (`xapp-...`, enable Socket Mode to get this)
**2. Configure**
```json
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-YOUR-BOT-TOKEN",
"app_token": "xapp-YOUR-APP-TOKEN",
"allow_from": []
}
}
}
```
**3. Run**
```bash
picoclaw gateway
```
</details>
<details>
<summary><b>IRC</b></summary>
**1. Configure**
```json
{
"channels": {
"irc": {
"enabled": true,
"server": "irc.libera.chat:6697",
"tls": true,
"nick": "picoclaw-bot",
"channels": ["#your-channel"],
"password": "",
"allow_from": []
}
}
}
```
Optional: `nickserv_password` for NickServ authentication, `sasl_user`/`sasl_password` for SASL auth.
**2. Run**
```bash
picoclaw gateway
```
The bot will connect to the IRC server and join the specified channels.
</details>
<details>
<summary><b>OneBot (QQ via OneBot protocol)</b></summary>
OneBot is an open protocol for QQ bots. PicoClaw connects to any OneBot v11 compatible implementation (e.g., [Lagrange](https://github.com/LagrangeDev/Lagrange.Core), [NapCat](https://github.com/NapNeko/NapCatQQ)) via WebSocket.
**1. Set up a OneBot implementation**
Install and run a OneBot v11 compatible QQ bot framework. Enable its WebSocket server.
**2. Configure**
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://127.0.0.1:8080",
"access_token": "",
"allow_from": []
}
}
}
```
| Field | Description |
|-------|-------------|
| `ws_url` | WebSocket URL of the OneBot implementation |
| `access_token` | Access token for authentication (if configured in OneBot) |
| `reconnect_interval` | Reconnect interval in seconds (default: 5) |
**3. Run**
```bash
picoclaw gateway
```
</details>
docs/configuration.md
+1 -1
View File
@@ -57,7 +57,7 @@ By default, skills are loaded from:
1. `~/.picoclaw/workspace/skills` (workspace)
2. `~/.picoclaw/skills` (global)
3. `<current-working-directory>/skills` (builtin)
3. `<binary-embedded-path>/skills` (builtin, set at build time)
For advanced/test setups, you can override the builtin skills root with:
docs/credential_encryption.md
+9 -20
View File
@@ -30,8 +30,9 @@ enc://AAAA...base64...
"model_list": [
{
"model_name": "gpt-4o",
"model": "openai/gpt-4o",
"api_key": "enc://AAAA...base64...",
"base_url": "https://api.openai.com/v1"
"api_base": "https://api.openai.com/v1"
}
]
}
@@ -54,20 +55,12 @@ enc://AAAA...base64...
### Key Derivation
Encryption uses **HKDF-SHA256** with an optional SSH private key as a second factor.
Encryption uses **HKDF-SHA256** with an SSH private key as a second factor.
```
Without SSH key (passphrase only):
ikm = SHA256(passphrase)
aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
With SSH key (recommended):
sshHash = SHA256(ssh_private_key_file_bytes)
ikm = HMAC-SHA256(key=sshHash, message=passphrase)
aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
sshHash = SHA256(ssh_private_key_file_bytes)
ikm = HMAC-SHA256(key=sshHash, message=passphrase)
aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
```
### Encryption
@@ -125,7 +118,7 @@ This means a leaked config file alone is not sufficient to recover the API key,
| Variable | Required | Description |
|----------|----------|-------------|
| `PICOCLAW_KEY_PASSPHRASE` | Yes (for `enc://`) | Passphrase used for key derivation |
| `PICOCLAW_SSH_KEY_PATH` | No | Path to SSH private key. Set to `""` to disable auto-detection and use passphrase-only mode |
| `PICOCLAW_SSH_KEY_PATH` | No | Path to SSH private key. If not set, auto-detects from `~/.ssh/picoclaw_ed25519.key` |
### SSH Key Auto-Detection
@@ -140,11 +133,7 @@ Run `picoclaw onboard` to generate it automatically.
`os.UserHomeDir()` is used for cross-platform home directory resolution (reads `USERPROFILE` on Windows, `HOME` on Unix/macOS).
To explicitly disable SSH key usage and use passphrase-only mode:
```bash
export PICOCLAW_SSH_KEY_PATH=""
```
> **Note:** An SSH key file is required for credential encryption. If no key is found and `PICOCLAW_SSH_KEY_PATH` is not set, encryption/decryption will fail. Run `picoclaw onboard` to generate the key automatically.
---
@@ -162,7 +151,7 @@ No re-encryption is needed.
## Security Considerations
- **Passphrase strength matters in passphrase-only mode.** Without an SSH key, a weak passphrase can be brute-forced offline. Use `PICOCLAW_SSH_KEY_PATH=""` only in environments where no SSH key is available and the passphrase is sufficiently strong (≥ 32 random characters).
- **Both passphrase and SSH key are required.** The SSH key acts as a second factor — without it, encryption/decryption will fail. Run `picoclaw onboard` to generate the key if it doesn't exist.
- **The SSH key is read-only at runtime.** PicoClaw never writes to or modifies the SSH key file.
- **Plaintext keys remain supported.** Existing configs without `enc://` are unaffected.
- **The `enc://` format is versioned** via the HKDF `info` field (`picoclaw-credential-v1`), allowing future algorithm upgrades without breaking existing encrypted values.
docs/docker.md
+1
View File
@@ -12,6 +12,7 @@ git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
# 2. First run — auto-generates docker/data/config.json then exits
# (only triggers when both config.json and workspace/ are missing)
docker compose -f docker/docker-compose.yml --profile gateway up
# The container prints "First-run setup complete." and stops.
docs/fr/ANTIGRAVITY_AUTH.md
+809
View File
@@ -0,0 +1,809 @@
> Retour au [README](../../README.fr.md)
# Guide d'authentification et d'intégration Antigravity
## Aperçu
**Antigravity** (Google Cloud Code Assist) est un fournisseur de modèles IA soutenu par Google qui offre l'accès à des modèles tels que Claude Opus 4.6 et Gemini via l'infrastructure cloud de Google. Ce document fournit un guide complet sur le fonctionnement de l'authentification, la récupération des modèles et l'implémentation d'un nouveau fournisseur dans PicoClaw.
---
## Table des matières
1. [Flux d'authentification](#flux-dauthentification)
2. [Détails de l'implémentation OAuth](#détails-de-limplémentation-oauth)
3. [Gestion des jetons](#gestion-des-jetons)
4. [Récupération de la liste des modèles](#récupération-de-la-liste-des-modèles)
5. [Suivi de l'utilisation](#suivi-de-lutilisation)
6. [Structure du plugin fournisseur](#structure-du-plugin-fournisseur)
7. [Exigences d'intégration](#exigences-dintégration)
8. [Points de terminaison API](#points-de-terminaison-api)
9. [Configuration](#configuration)
10. [Créer un nouveau fournisseur dans PicoClaw](#créer-un-nouveau-fournisseur-dans-picoclaw)
---
## Flux d'authentification
### 1. OAuth 2.0 avec PKCE
Antigravity utilise **OAuth 2.0 avec PKCE (Proof Key for Code Exchange)** pour une authentification sécurisée :
```
┌─────────────┐ ┌─────────────────┐
│ Client │ ───(1) Generate PKCE Pair────────> │ │
│ │ ───(2) Open Auth URL─────────────> │ Google OAuth │
│ │ │ Server │
│ │ <──(3) Redirect with Code───────── │ │
│ │ └─────────────────┘
│ │ ───(4) Exchange Code for Tokens──> │ Token URL │
│ │ │ │
│ │ <──(5) Access + Refresh Tokens──── │ │
└─────────────┘ └─────────────────┘
```
### 2. Étapes détaillées
#### Étape 1 : Générer les paramètres PKCE
```typescript
function generatePkce(): { verifier: string; challenge: string } {
const verifier = randomBytes(32).toString("hex");
const challenge = createHash("sha256").update(verifier).digest("base64url");
return { verifier, challenge };
}
```
#### Étape 2 : Construire l'URL d'autorisation
```typescript
const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
const REDIRECT_URI = "http://localhost:51121/oauth-callback";
function buildAuthUrl(params: { challenge: string; state: string }): string {
const url = new URL(AUTH_URL);
url.searchParams.set("client_id", CLIENT_ID);
url.searchParams.set("response_type", "code");
url.searchParams.set("redirect_uri", REDIRECT_URI);
url.searchParams.set("scope", SCOPES.join(" "));
url.searchParams.set("code_challenge", params.challenge);
url.searchParams.set("code_challenge_method", "S256");
url.searchParams.set("state", params.state);
url.searchParams.set("access_type", "offline");
url.searchParams.set("prompt", "consent");
return url.toString();
}
```
**Portées requises :**
```typescript
const SCOPES = [
"https://www.googleapis.com/auth/cloud-platform",
"https://www.googleapis.com/auth/userinfo.email",
"https://www.googleapis.com/auth/userinfo.profile",
"https://www.googleapis.com/auth/cclog",
"https://www.googleapis.com/auth/experimentsandconfigs",
];
```
#### Étape 3 : Gérer le callback OAuth
**Mode automatique (développement local) :**
- Démarrer un serveur HTTP local sur le port 51121
- Attendre la redirection de Google
- Extraire le code d'autorisation des paramètres de requête
**Mode manuel (distant/sans interface graphique) :**
- Afficher l'URL d'autorisation à l'utilisateur
- L'utilisateur complète l'authentification dans son navigateur
- L'utilisateur colle l'URL de redirection complète dans le terminal
- Analyser le code depuis l'URL collée
#### Étape 4 : Échanger le code contre des jetons
```typescript
const TOKEN_URL = "https://oauth2.googleapis.com/token";
async function exchangeCode(params: {
code: string;
verifier: string;
}): Promise<{ access: string; refresh: string; expires: number }> {
const response = await fetch(TOKEN_URL, {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET,
code: params.code,
grant_type: "authorization_code",
redirect_uri: REDIRECT_URI,
code_verifier: params.verifier,
}),
});
const data = await response.json();
return {
access: data.access_token,
refresh: data.refresh_token,
expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000, // 5 min buffer
};
}
```
#### Étape 5 : Récupérer les données utilisateur supplémentaires
**E-mail de l'utilisateur :**
```typescript
async function fetchUserEmail(accessToken: string): Promise<string | undefined> {
const response = await fetch(
"https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
{ headers: { Authorization: `Bearer ${accessToken}` } }
);
const data = await response.json();
return data.email;
}
```
**ID du projet (requis pour les appels API) :**
```typescript
async function fetchProjectId(accessToken: string): Promise<string> {
const headers = {
Authorization: `Bearer ${accessToken}`,
"Content-Type": "application/json",
"User-Agent": "google-api-nodejs-client/9.15.1",
"X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
"Client-Metadata": JSON.stringify({
ideType: "IDE_UNSPECIFIED",
platform: "PLATFORM_UNSPECIFIED",
pluginType: "GEMINI",
}),
};
const response = await fetch(
"https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
{
method: "POST",
headers,
body: JSON.stringify({
metadata: {
ideType: "IDE_UNSPECIFIED",
platform: "PLATFORM_UNSPECIFIED",
pluginType: "GEMINI",
},
}),
}
);
const data = await response.json();
return data.cloudaicompanionProject || "rising-fact-p41fc"; // Valeur par défaut
}
```
---
## Détails de l'implémentation OAuth
### Identifiants client
**Important :** Ceux-ci sont encodés en base64 dans le code source pour la synchronisation avec pi-ai :
```typescript
const decode = (s: string) => Buffer.from(s, "base64").toString();
const CLIENT_ID = decode(
"MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ=="
);
const CLIENT_SECRET = decode("R09DU1BYLUs1OEZXUjQ4NkxkTEoxbUxCOHNYQzR6NnFEQWY=");
```
### Modes de flux OAuth
1. **Flux automatique** (machines locales avec navigateur) :
- Ouvre le navigateur automatiquement
- Le serveur de callback local capture la redirection
- Aucune interaction utilisateur requise après l'authentification initiale
2. **Flux manuel** (distant/sans interface/WSL2) :
- URL affichée pour copier-coller manuellement
- L'utilisateur complète l'authentification dans un navigateur externe
- L'utilisateur colle l'URL de redirection complète
```typescript
function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
return isRemote || isWSL2Sync();
}
```
---
## Gestion des jetons
### Structure du profil d'authentification
```typescript
type OAuthCredential = {
type: "oauth";
provider: "google-antigravity";
access: string; // Jeton d'accès
refresh: string; // Jeton de rafraîchissement
expires: number; // Horodatage d'expiration (ms depuis epoch)
email?: string; // E-mail de l'utilisateur
projectId?: string; // ID du projet Google Cloud
};
```
### Rafraîchissement des jetons
Les identifiants incluent un jeton de rafraîchissement qui peut être utilisé pour obtenir de nouveaux jetons d'accès lorsque le jeton actuel expire. L'expiration est définie avec un tampon de 5 minutes pour éviter les conditions de concurrence.
---
## Récupération de la liste des modèles
### Récupérer les modèles disponibles
```typescript
const BASE_URL = "https://cloudcode-pa.googleapis.com";
async function fetchAvailableModels(
accessToken: string,
projectId: string
): Promise<Model[]> {
const headers = {
Authorization: `Bearer ${accessToken}`,
"Content-Type": "application/json",
"User-Agent": "antigravity",
"X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
};
const response = await fetch(
`${BASE_URL}/v1internal:fetchAvailableModels`,
{
method: "POST",
headers,
body: JSON.stringify({ project: projectId }),
}
);
const data = await response.json();
// Retourne les modèles avec les informations de quota
return Object.entries(data.models).map(([modelId, modelInfo]) => ({
id: modelId,
displayName: modelInfo.displayName,
quotaInfo: {
remainingFraction: modelInfo.quotaInfo?.remainingFraction,
resetTime: modelInfo.quotaInfo?.resetTime,
isExhausted: modelInfo.quotaInfo?.isExhausted,
},
}));
}
```
### Format de réponse
```typescript
type FetchAvailableModelsResponse = {
models?: Record<string, {
displayName?: string;
quotaInfo?: {
remainingFraction?: number | string;
resetTime?: string; // Horodatage ISO 8601
isExhausted?: boolean;
};
}>;
};
```
---
## Suivi de l'utilisation
### Récupérer les données d'utilisation
```typescript
export async function fetchAntigravityUsage(
token: string,
timeoutMs: number
): Promise<ProviderUsageSnapshot> {
// 1. Récupérer les crédits et les informations du plan
const loadCodeAssistRes = await fetch(
`${BASE_URL}/v1internal:loadCodeAssist`,
{
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
metadata: {
ideType: "ANTIGRAVITY",
platform: "PLATFORM_UNSPECIFIED",
pluginType: "GEMINI",
},
}),
}
);
// Extraire les informations de crédits
const { availablePromptCredits, planInfo, currentTier } = data;
// 2. Récupérer les quotas des modèles
const modelsRes = await fetch(
`${BASE_URL}/v1internal:fetchAvailableModels`,
{
method: "POST",
headers: { Authorization: `Bearer ${token}` },
body: JSON.stringify({ project: projectId }),
}
);
// Construire les fenêtres d'utilisation
return {
provider: "google-antigravity",
displayName: "Google Antigravity",
windows: [
{ label: "Credits", usedPercent: calculateUsedPercent(available, monthly) },
// Quotas individuels des modèles...
],
plan: currentTier?.name || planType,
};
}
```
### Structure de la réponse d'utilisation
```typescript
type ProviderUsageSnapshot = {
provider: "google-antigravity";
displayName: string;
windows: UsageWindow[];
plan?: string;
error?: string;
};
type UsageWindow = {
label: string; // "Credits" ou ID du modèle
usedPercent: number; // 0-100
resetAt?: number; // Horodatage de réinitialisation du quota
};
```
---
## Structure du plugin fournisseur
### Définition du plugin
```typescript
const antigravityPlugin = {
id: "google-antigravity-auth",
name: "Google Antigravity Auth",
description: "OAuth flow for Google Antigravity (Cloud Code Assist)",
configSchema: emptyPluginConfigSchema(),
register(api: PicoClawPluginApi) {
api.registerProvider({
id: "google-antigravity",
label: "Google Antigravity",
docsPath: "/providers/models",
aliases: ["antigravity"],
auth: [
{
id: "oauth",
label: "Google OAuth",
hint: "PKCE + localhost callback",
kind: "oauth",
run: async (ctx: ProviderAuthContext) => {
// Implémentation OAuth ici
},
},
],
});
},
};
```
### ProviderAuthContext
```typescript
type ProviderAuthContext = {
config: PicoClawConfig;
agentDir?: string;
workspaceDir?: string;
prompter: WizardPrompter; // Invites/notifications UI
runtime: RuntimeEnv; // Journalisation, etc.
isRemote: boolean; // Exécution à distance ou non
openUrl: (url: string) => Promise<void>; // Ouverture du navigateur
oauth: {
createVpsAwareHandlers: Function;
};
};
```
### ProviderAuthResult
```typescript
type ProviderAuthResult = {
profiles: Array<{
profileId: string;
credential: AuthProfileCredential;
}>;
configPatch?: Partial<PicoClawConfig>;
defaultModel?: string;
notes?: string[];
};
```
---
## Exigences d'intégration
### 1. Environnement/dépendances requis
- Go ≥ 1.25
- Base de code PicoClaw (`pkg/providers/` et `pkg/auth/`)
- Packages de la bibliothèque standard `crypto` et `net/http`
### 2. En-têtes requis pour les appels API
```typescript
const REQUIRED_HEADERS = {
"Authorization": `Bearer ${accessToken}`,
"Content-Type": "application/json",
"User-Agent": "antigravity", // ou "google-api-nodejs-client/9.15.1"
"X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
};
// Pour les appels loadCodeAssist, inclure également :
const CLIENT_METADATA = {
ideType: "ANTIGRAVITY", // ou "IDE_UNSPECIFIED"
platform: "PLATFORM_UNSPECIFIED",
pluginType: "GEMINI",
};
```
### 3. Assainissement des schémas de modèles
Antigravity utilise des modèles compatibles Gemini, les schémas d'outils doivent donc être assainis :
```typescript
const GOOGLE_SCHEMA_UNSUPPORTED_KEYWORDS = new Set([
"patternProperties",
"additionalProperties",
"$schema",
"$id",
"$ref",
"$defs",
"definitions",
"examples",
"minLength",
"maxLength",
"minimum",
"maximum",
"multipleOf",
"pattern",
"format",
"minItems",
"maxItems",
"uniqueItems",
"minProperties",
"maxProperties",
]);
// Nettoyer le schéma avant l'envoi
function cleanToolSchemaForGemini(schema: Record<string, unknown>): unknown {
// Supprimer les mots-clés non supportés
// S'assurer que le niveau supérieur a type: "object"
// Aplatir les unions anyOf/oneOf
}
```
### 4. Gestion des blocs de réflexion (modèles Claude)
Pour les modèles Claude via Antigravity, les blocs de réflexion nécessitent un traitement spécial :
```typescript
const ANTIGRAVITY_SIGNATURE_RE = /^[A-Za-z0-9+/]+={0,2}$/;
export function sanitizeAntigravityThinkingBlocks(
messages: AgentMessage[]
): AgentMessage[] {
// Valider les signatures de réflexion
// Normaliser les champs de signature
// Rejeter les blocs de réflexion non signés
}
```
---
## Points de terminaison API
### Points de terminaison d'authentification
| Point de terminaison | Méthode | Objectif |
|---------------------|---------|----------|
| `https://accounts.google.com/o/oauth2/v2/auth` | GET | Autorisation OAuth |
| `https://oauth2.googleapis.com/token` | POST | Échange de jetons |
| `https://www.googleapis.com/oauth2/v1/userinfo` | GET | Informations utilisateur (e-mail) |
### Points de terminaison Cloud Code Assist
| Point de terminaison | Méthode | Objectif |
|---------------------|---------|----------|
| `https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist` | POST | Charger les infos du projet, crédits, plan |
| `https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels` | POST | Lister les modèles disponibles avec quotas |
| `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse` | POST | Point de terminaison de streaming de chat |
**Format de requête API (chat) :**
Le point de terminaison `v1internal:streamGenerateContent` attend une enveloppe encapsulant la requête Gemini standard :
```json
{
"project": "your-project-id",
"model": "model-id",
"request": {
"contents": [...],
"systemInstruction": {...},
"generationConfig": {...},
"tools": [...]
},
"requestType": "agent",
"userAgent": "antigravity",
"requestId": "agent-timestamp-random"
}
```
**Format de réponse API (SSE) :**
Chaque message SSE (`data: {...}`) est encapsulé dans un champ `response` :
```json
{
"response": {
"candidates": [...],
"usageMetadata": {...},
"modelVersion": "...",
"responseId": "..."
},
"traceId": "...",
"metadata": {}
}
```
---
## Configuration
### Configuration config.json
```json
{
"model_list": [
{
"model_name": "gemini-flash",
"model": "antigravity/gemini-3-flash",
"auth_method": "oauth"
}
],
"agents": {
"defaults": {
"model_name": "gemini-flash"
}
}
}
```
### Stockage du profil d'authentification
Les profils d'authentification sont stockés dans `~/.picoclaw/auth.json` :
```json
{
"credentials": {
"google-antigravity": {
"access_token": "ya29...",
"refresh_token": "1//...",
"expires_at": "2026-01-01T00:00:00Z",
"provider": "google-antigravity",
"auth_method": "oauth",
"email": "user@example.com",
"project_id": "my-project-id"
}
}
}
```
---
## Créer un nouveau fournisseur dans PicoClaw
Les fournisseurs PicoClaw sont implémentés en tant que packages Go sous `pkg/providers/`. Pour ajouter un nouveau fournisseur :
### Implémentation étape par étape
#### 1. Créer le fichier du fournisseur
Créez un nouveau fichier Go dans `pkg/providers/` :
```
pkg/providers/
└── your_provider.go
```
#### 2. Implémenter l'interface Provider
Votre fournisseur doit implémenter l'interface `Provider` définie dans `pkg/providers/types.go` :
```go
package providers
type YourProvider struct {
apiKey string
apiBase string
}
func NewYourProvider(apiKey, apiBase, proxy string) *YourProvider {
if apiBase == "" {
apiBase = "https://api.your-provider.com/v1"
}
return &YourProvider{apiKey: apiKey, apiBase: apiBase}
}
func (p *YourProvider) Chat(ctx context.Context, messages []Message, tools []Tool, cb StreamCallback) error {
// Implémenter la complétion de chat avec streaming
}
```
#### 3. Enregistrer dans la factory
Ajoutez votre fournisseur au switch de protocole dans `pkg/providers/factory.go` :
```go
case "your-provider":
return NewYourProvider(sel.apiKey, sel.apiBase, sel.proxy), nil
```
#### 4. Ajouter la configuration par défaut (optionnel)
Ajoutez une entrée par défaut dans `pkg/config/defaults.go` :
```go
{
ModelName: "your-model",
Model: "your-provider/model-name",
APIKey: "",
},
```
#### 5. Ajouter le support d'authentification (optionnel)
Si votre fournisseur nécessite OAuth ou une authentification spéciale, ajoutez un cas dans `cmd/picoclaw/internal/auth/helpers.go` :
```go
case "your-provider":
authLoginYourProvider()
```
#### 6. Configurer via `config.json`
```json
{
"model_list": [
{
"model_name": "your-model",
"model": "your-provider/model-name",
"api_key": "your-api-key",
"api_base": "https://api.your-provider.com/v1"
}
]
}
```
---
## Tester votre implémentation
### Commandes CLI
```bash
# S'authentifier avec un fournisseur
picoclaw auth login --provider your-provider
# Lister les modèles (pour Antigravity)
picoclaw auth models
# Démarrer la passerelle
picoclaw gateway
# Exécuter un agent avec un modèle spécifique
picoclaw agent -m "Hello" --model your-model
```
### Variables d'environnement pour les tests
```bash
# Remplacer le modèle par défaut
export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
# Remplacer les paramètres du fournisseur
export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
```
---
## Références
- **Fichiers source :**
- `pkg/providers/antigravity_provider.go` - Implémentation du fournisseur Antigravity
- `pkg/auth/oauth.go` - Implémentation du flux OAuth
- `pkg/auth/store.go` - Stockage des identifiants d'authentification (`~/.picoclaw/auth.json`)
- `pkg/providers/factory.go` - Factory des fournisseurs et routage de protocole
- `pkg/providers/types.go` - Définitions de l'interface fournisseur
- `cmd/picoclaw/internal/auth/helpers.go` - Commandes CLI d'authentification
- **Documentation :**
- `docs/ANTIGRAVITY_USAGE.md` - Guide d'utilisation d'Antigravity
- `docs/migration/model-list-migration.md` - Guide de migration
---
## Notes
1. **Projet Google Cloud :** Antigravity nécessite que Gemini for Google Cloud soit activé sur votre projet Google Cloud
2. **Quotas :** Utilise les quotas du projet Google Cloud (pas de facturation séparée)
3. **Accès aux modèles :** Les modèles disponibles dépendent de la configuration de votre projet Google Cloud
4. **Blocs de réflexion :** Les modèles Claude via Antigravity nécessitent un traitement spécial des blocs de réflexion avec signatures
5. **Assainissement des schémas :** Les schémas d'outils doivent être assainis pour supprimer les mots-clés JSON Schema non supportés
---
---
## Gestion des erreurs courantes
### 1. Limitation de débit (HTTP 429)
Antigravity retourne une erreur 429 lorsque les quotas du projet/modèle sont épuisés. La réponse d'erreur contient souvent un `quotaResetDelay` dans le champ `details`.
**Exemple d'erreur 429 :**
```json
{
"error": {
"code": 429,
"message": "You have exhausted your capacity on this model. Your quota will reset after 4h30m28s.",
"status": "RESOURCE_EXHAUSTED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"metadata": {
"quotaResetDelay": "4h30m28.060903746s"
}
}
]
}
}
```
### 2. Réponses vides (modèles restreints)
Certains modèles peuvent apparaître dans la liste des modèles disponibles mais retourner une réponse vide (200 OK mais flux SSE vide). Cela se produit généralement pour les modèles en préversion ou restreints que le projet actuel n'a pas la permission d'utiliser.
**Traitement :** Traiter les réponses vides comme des erreurs informant l'utilisateur que le modèle pourrait être restreint ou invalide pour son projet.
---
## Dépannage
### "Token expired" (jeton expiré)
- Rafraîchir les jetons OAuth : `picoclaw auth login --provider antigravity`
### "Gemini for Google Cloud is not enabled" (Gemini for Google Cloud n'est pas activé)
- Activer l'API dans votre Google Cloud Console
### "Project not found" (projet non trouvé)
- Vérifier que votre projet Google Cloud a les API nécessaires activées
- Vérifier que l'ID du projet est correctement récupéré lors de l'authentification
### Les modèles n'apparaissent pas dans la liste
- Vérifier que l'authentification OAuth s'est terminée avec succès
- Vérifier le stockage du profil d'authentification : `~/.picoclaw/auth.json`
- Relancer `picoclaw auth login --provider antigravity`
docs/fr/ANTIGRAVITY_USAGE.md
+72
View File
@@ -0,0 +1,72 @@
> Retour au [README](../../README.fr.md)
# Utiliser le fournisseur Antigravity dans PicoClaw
Ce guide explique comment configurer et utiliser le fournisseur **Antigravity** (Google Cloud Code Assist) dans PicoClaw.
## Prérequis
1. Un compte Google.
2. Google Cloud Code Assist activé (généralement disponible via l'intégration « Gemini for Google Cloud »).
## 1. Authentification
Pour vous authentifier avec Antigravity, exécutez la commande suivante :
```bash
picoclaw auth login --provider antigravity
```
### Authentification manuelle (Headless/VPS)
Si vous exécutez PicoClaw sur un serveur (Coolify/Docker) et ne pouvez pas accéder à `localhost`, suivez ces étapes :
1. Exécutez la commande ci-dessus.
2. Copiez l'URL fournie et ouvrez-la dans votre navigateur local.
3. Complétez la connexion.
4. Votre navigateur sera redirigé vers une URL `localhost:51121` (qui ne se chargera pas).
5. **Copiez cette URL finale** depuis la barre d'adresse de votre navigateur.
6. **Collez-la dans le terminal** où PicoClaw attend.
PicoClaw extraira automatiquement le code d'autorisation et terminera le processus.
## 2. Gestion des modèles
### Lister les modèles disponibles
Pour voir quels modèles sont accessibles à votre projet et vérifier leurs quotas :
```bash
picoclaw auth models
```
### Changer de modèle
Vous pouvez modifier le modèle par défaut dans `~/.picoclaw/config.json` ou le remplacer via le CLI :
```bash
# Remplacer pour une seule commande
picoclaw agent -m "Hello" --model claude-opus-4-6-thinking
```
## 3. Utilisation en production (Coolify/Docker)
Si vous déployez via Coolify ou Docker, suivez ces étapes pour tester :
1. **Variables d'environnement** :
* `PICOCLAW_AGENTS_DEFAULTS_MODEL=gemini-flash`
2. **Persistance de l'authentification** :
Si vous vous êtes connecté localement, vous pouvez copier vos identifiants vers le serveur :
```bash
scp ~/.picoclaw/auth.json user@your-server:~/.picoclaw/
```
*Alternativement*, exécutez la commande `auth login` une fois sur le serveur si vous avez un accès terminal.
## 4. Dépannage
* **Réponse vide** : Si un modèle renvoie une réponse vide, il peut être restreint pour votre projet. Essayez `gemini-3-flash` ou `claude-opus-4-6-thinking`.
* **429 Limite de débit** : Antigravity a des quotas stricts. PicoClaw affichera le « temps de réinitialisation » dans le message d'erreur si vous atteignez une limite.
* **404 Non trouvé** : Assurez-vous d'utiliser un ID de modèle provenant de la liste `picoclaw auth models`. Utilisez l'ID court (par ex. `gemini-3-flash`) et non le chemin complet.
## 5. Résumé des modèles fonctionnels
D'après les tests, les modèles suivants sont les plus fiables :
* `gemini-3-flash` (Rapide, haute disponibilité)
* `gemini-2.5-flash-lite` (Léger)
* `claude-opus-4-6-thinking` (Puissant, inclut le raisonnement)
docs/fr/chat-apps.md
+77 -55
View File
@@ -8,22 +8,22 @@ Communiquez avec votre PicoClaw via Telegram, Discord, WhatsApp, Matrix, QQ, Din
> **Note** : Tous les canaux basés sur les webhooks (LINE, WeCom, etc.) sont servis sur un seul serveur HTTP Gateway partagé (`gateway.host`:`gateway.port`, par défaut `127.0.0.1:18790`). Il n'y a pas de ports par canal à configurer. Note : Feishu utilise le mode WebSocket/SDK et n'utilise pas le serveur HTTP webhook partagé.
| Canal | Configuration |
| ------------ | -------------------------------------- |
| **Telegram** | Facile (juste un token) |
| **Discord** | Facile (bot token + intents) |
| **WhatsApp** | Facile (natif : scan QR ; ou bridge URL) |
| **Matrix** | Moyen (homeserver + bot access token) |
| **QQ** | Facile (AppID + AppSecret) |
| **DingTalk** | Moyen (identifiants de l'application) |
| **LINE** | Moyen (identifiants + webhook URL) |
| **WeCom AI Bot** | Moyen (Token + clé AES) |
| **Feishu** | Moyen (App ID + Secret, mode WebSocket) |
| **Slack** | Moyen (Bot token + App token) |
| **IRC** | Moyen (serveur + configuration TLS) |
| **OneBot** | Moyen (QQ via protocole OneBot) |
| **MaixCam** | Facile (intégration matérielle Sipeed) |
| **Pico** | Native PicoClaw protocol |
| Canal | Difficulté | Description | Documentation |
| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Telegram** | ⭐ Facile | Recommandé, transcription vocale, long polling (pas d'IP publique requise) | [Documentation](../channels/telegram/README.fr.md) |
| **Discord** | ⭐ Facile | Socket Mode, groupes/DM, écosystème bot riche | [Documentation](../channels/discord/README.fr.md) |
| **WhatsApp** | ⭐ Facile | Natif (scan QR) ou Bridge URL | [Documentation](#whatsapp) |
| **Slack** | ⭐ Facile | **Socket Mode** (pas d'IP publique requise), entreprise | [Documentation](../channels/slack/README.fr.md) |
| **Matrix** | ⭐⭐ Moyen | Protocole fédéré, auto-hébergement possible | [Documentation](../channels/matrix/README.fr.md) |
| **QQ** | ⭐⭐ Moyen | API bot officielle, communauté chinoise | [Documentation](../channels/qq/README.fr.md) |
| **DingTalk** | ⭐⭐ Moyen | Mode Stream (pas d'IP publique requise), entreprise | [Documentation](../channels/dingtalk/README.fr.md) |
| **LINE** | ⭐⭐⭐ Avancé | HTTPS Webhook requis | [Documentation](../channels/line/README.fr.md) |
| **WeCom (企业微信)** | ⭐⭐⭐ Avancé | Bot groupe (Webhook), app personnalisée (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.fr.md) / [App](../channels/wecom/wecom_app/README.fr.md) / [AI Bot](../channels/wecom/wecom_aibot/README.fr.md) |
| **Feishu (飞书)** | ⭐⭐⭐ Avancé | Collaboration entreprise, fonctionnalités riches | [Documentation](../channels/feishu/README.fr.md) |
| **IRC** | ⭐⭐ Moyen | Serveur + configuration TLS | - |
| **OneBot** | ⭐⭐ Moyen | Compatible NapCat/Go-CQHTTP, écosystème communautaire | [Documentation](../channels/onebot/README.fr.md) |
| **MaixCam** | ⭐ Facile | Canal d'intégration matérielle pour caméras AI Sipeed | [Documentation](../channels/maixcam/README.fr.md) |
| **Pico** | ⭐ Facile | Canal protocole natif PicoClaw | |
<details>
<summary><b>Telegram</b> (Recommandé)</summary>
@@ -168,12 +168,13 @@ Si `session_store_path` est vide, la session est stockée dans `<workspace>/what
<details>
<summary><b>QQ</b></summary>
**1. Créer un bot**
**Configuration rapide (recommandée)**
- Allez sur [QQ Open Platform](https://q.qq.com/#)
- Créez une application → Obtenez **AppID** et **AppSecret**
QQ Open Platform propose une page de configuration en un clic pour les bots compatibles OpenClaw :
**2. Configurer**
1. Ouvrez [QQ Bot Quick Start](https://q.qq.com/qqbot/openclaw/index.html) et scannez le QR code pour vous connecter
2. Un bot est créé automatiquement — copiez l'**App ID** et l'**App Secret**
3. Configurez PicoClaw :
```json
{
@@ -188,13 +189,20 @@ Si `session_store_path` est vide, la session est stockée dans `<workspace>/what
}
```
> Définissez `allow_from` vide pour autoriser tous les utilisateurs, ou spécifiez des numéros QQ pour restreindre l'accès.
4. Lancez `picoclaw gateway` et ouvrez QQ pour discuter avec votre bot
**3. Lancer**
> L'App Secret n'est affiché qu'une seule fois. Enregistrez-le immédiatement — le consulter à nouveau forcera une réinitialisation.
>
> Les bots créés via la page de configuration rapide sont initialement réservés au créateur et ne prennent pas en charge les discussions de groupe. Pour activer l'accès en groupe, configurez le mode sandbox sur la [QQ Open Platform](https://q.qq.com/).
```bash
picoclaw gateway
```
**Configuration manuelle**
Si vous préférez créer le bot manuellement :
* Connectez-vous sur [QQ Open Platform](https://q.qq.com/) pour vous inscrire en tant que développeur
* Créez un bot QQ — personnalisez son avatar et son nom
* Copiez l'**App ID** et l'**App Secret** depuis les paramètres du bot
* Configurez comme indiqué ci-dessus et lancez `picoclaw gateway`
</details>
@@ -261,7 +269,7 @@ picoclaw gateway
picoclaw gateway
```
Pour toutes les options (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), voir le [Guide de Configuration du Canal Matrix](docs/channels/matrix/README.md).
Pour toutes les options (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), voir le [Guide de Configuration du Canal Matrix](../channels/matrix/README.md).
</details>
@@ -322,7 +330,7 @@ PicoClaw prend en charge trois types d'intégration WeCom :
**Option 2 : WeCom App (Application personnalisée)** - Plus de fonctionnalités, messagerie proactive, chat privé uniquement
**Option 3 : WeCom AI Bot (Bot IA)** - Bot IA officiel, réponses en streaming, prend en charge les discussions de groupe et privées
Voir le [Guide de Configuration WeCom AI Bot](docs/channels/wecom/wecom_aibot/README.zh.md) pour les instructions détaillées.
Voir le [Guide de Configuration WeCom AI Bot](../channels/wecom/wecom_aibot/README.fr.md) pour les instructions détaillées.
**Configuration rapide - WeCom Bot :**
@@ -396,7 +404,7 @@ picoclaw gateway
**1. Créer un AI Bot**
* Allez dans la console d'administration WeCom → Gestion des applications → AI Bot
* Dans les paramètres du AI Bot, configurez l'URL de callback : `http://your-server:18791/webhook/wecom-aibot`
* Dans les paramètres du AI Bot, configurez l'URL de callback : `http://your-server:18790/webhook/wecom-aibot`
* Copiez **Token** et cliquez sur "Générer aléatoirement" pour **EncodingAESKey**
**2. Configurer**
@@ -430,10 +438,14 @@ picoclaw gateway
<details>
<summary><b>Feishu (飞书)</b></summary>
PicoClaw se connecte à Feishu via le mode WebSocket/SDK — aucune URL webhook publique ni serveur de callback nécessaire.
**1. Créer une application**
* Allez sur [Feishu Open Platform](https://open.feishu.cn/)
* Créez une application → Obtenez **App ID** et **App Secret**
* Allez sur [Feishu Open Platform](https://open.feishu.cn/) et créez une application
* Dans les paramètres de l'application, activez la capacité **Bot**
* Créez une version et publiez l'application (l'application doit être publiée pour prendre effet)
* Copiez l'**App ID** (commence par `cli_`) et l'**App Secret**
**2. Configurer**
@@ -443,23 +455,25 @@ picoclaw gateway
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
> Feishu utilise le mode WebSocket/SDK et ne nécessite pas de serveur webhook.
Optionnel : `encrypt_key` et `verification_token` pour le chiffrement des événements (recommandé en production).
**3. Lancer**
**3. Lancer et discuter**
```bash
picoclaw gateway
```
Ouvrez Feishu, recherchez le nom de votre bot et commencez à discuter. Vous pouvez aussi ajouter le bot à un groupe — utilisez `group_trigger.mention_only: true` pour ne répondre que lorsqu'il est @mentionné.
Pour toutes les options, voir le [Guide de Configuration du Canal Feishu](../channels/feishu/README.fr.md).
</details>
<details>
@@ -467,9 +481,10 @@ picoclaw gateway
**1. Créer une application Slack**
* Allez sur [Slack API](https://api.slack.com/apps)
* Créez une nouvelle application
* Obtenez le **Bot Token** et l'**App Token**
* Allez sur [Slack API](https://api.slack.com/apps) et créez une nouvelle application
* Sous **OAuth & Permissions**, ajoutez les scopes bot : `chat:write`, `app_mentions:read`, `im:history`, `im:read`, `im:write`
* Installez l'application dans votre workspace
* Copiez le **Bot Token** (`xoxb-...`) et l'**App-Level Token** (`xapp-...`, activez Socket Mode pour l'obtenir)
**2. Configurer**
@@ -478,8 +493,8 @@ picoclaw gateway
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-your-bot-token",
"app_token": "xapp-your-app-token",
"bot_token": "xoxb-YOUR-BOT-TOKEN",
"app_token": "xapp-YOUR-APP-TOKEN",
"allow_from": []
}
}
@@ -497,42 +512,44 @@ picoclaw gateway
<details>
<summary><b>IRC</b></summary>
**1. Configurer le serveur IRC**
* Préparez les informations de votre serveur IRC (adresse, port, canal)
**2. Configurer**
**1. Configurer**
```json
{
"channels": {
"irc": {
"enabled": true,
"server": "irc.example.com:6697",
"server": "irc.libera.chat:6697",
"tls": true,
"nick": "picoclaw-bot",
"channel": "#your-channel",
"use_tls": true,
"channels": ["#your-channel"],
"password": "",
"allow_from": []
}
}
}
```
**3. Lancer**
Optionnel : `nickserv_password` pour l'authentification NickServ, `sasl_user`/`sasl_password` pour l'authentification SASL.
**2. Lancer**
```bash
picoclaw gateway
```
Le bot se connectera au serveur IRC et rejoindra les canaux spécifiés.
</details>
<details>
<summary><b>OneBot</b></summary>
<summary><b>OneBot (QQ via protocole OneBot)</b></summary>
**1. Configurer OneBot**
OneBot est un protocole ouvert pour les bots QQ. PicoClaw se connecte à toute implémentation compatible OneBot v11 (par ex. [Lagrange](https://github.com/LagrangeDev/Lagrange.Core), [NapCat](https://github.com/NapNeko/NapCatQQ)) via WebSocket.
* Installez une implémentation OneBot compatible (par ex. go-cqhttp, Lagrange)
* Configurez la connexion WebSocket
**1. Configurer une implémentation OneBot**
Installez et exécutez un framework de bot QQ compatible OneBot v11. Activez son serveur WebSocket.
**2. Configurer**
@@ -541,14 +558,19 @@ picoclaw gateway
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://localhost:8080",
"ws_url": "ws://127.0.0.1:8080",
"access_token": "",
"allow_from": []
}
}
}
```
> OneBot permet d'utiliser QQ via le protocole OneBot standard.
| Champ | Description |
|-------|-------------|
| `ws_url` | URL WebSocket de l'implémentation OneBot |
| `access_token` | Token d'accès pour l'authentification (si configuré dans OneBot) |
| `reconnect_interval` | Intervalle de reconnexion en secondes (par défaut : 5) |
**3. Lancer**
docs/fr/configuration.md
+1 -1
View File
@@ -56,7 +56,7 @@ Par défaut, les compétences sont chargées depuis :
1. `~/.picoclaw/workspace/skills` (workspace)
2. `~/.picoclaw/skills` (global)
3. `<current-working-directory>/skills` (builtin)
3. `<chemin-intégré-à-la-compilation>/skills` (intégré)
Pour les configurations avancées/de test, vous pouvez remplacer la racine des compétences builtin avec :
docs/fr/credential_encryption.md
+159
View File
@@ -0,0 +1,159 @@
> Retour au [README](../../README.fr.md)
# Chiffrement des identifiants
PicoClaw prend en charge le chiffrement des valeurs `api_key` dans les entrées de configuration `model_list`.
Les clés chiffrées sont stockées sous forme de chaînes `enc://<base64>` et déchiffrées automatiquement au démarrage.
---
## Démarrage rapide
**1. Définir votre phrase secrète**
```bash
export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
```
**2. Chiffrer une clé API**
Exécutez `picoclaw onboard` — il vous demande votre phrase secrète et génère la clé SSH,
puis re-chiffre automatiquement toutes les entrées `api_key` en clair dans votre configuration
lors du prochain appel à `SaveConfig`. La valeur `enc://` résultante ressemblera à :
```
enc://AAAA...base64...
```
**3. Coller la sortie dans votre configuration**
```json
{
"model_list": [
{
"model_name": "gpt-4o",
"model": "openai/gpt-4o",
"api_key": "enc://AAAA...base64...",
"api_base": "https://api.openai.com/v1"
}
]
}
```
---
## Formats `api_key` pris en charge
| Format | Exemple | Comportement |
|--------|---------|--------------|
| Texte clair | `sk-abc123` | Utilisé tel quel |
| Référence fichier | `file://openai.key` | Contenu lu depuis le même répertoire que le fichier de configuration |
| Chiffré | `enc://<base64>` | Déchiffré au démarrage avec `PICOCLAW_KEY_PASSPHRASE` |
| Vide | `""` | Transmis tel quel (utilisé avec `auth_method: oauth`) |
---
## Conception cryptographique
### Dérivation de clé
Le chiffrement utilise **HKDF-SHA256** avec une clé privée SSH comme second facteur.
```
sshHash = SHA256(ssh_private_key_file_bytes)
ikm = HMAC-SHA256(key=sshHash, message=passphrase)
aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
```
### Chiffrement
```
AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
```
### Format de transmission
```
enc://<base64( salt[16] + nonce[12] + ciphertext )>
```
| Champ | Taille | Description |
|-------|--------|-------------|
| `salt` | 16 octets | Aléatoire par chiffrement ; fourni à HKDF |
| `nonce` | 12 octets | Aléatoire par chiffrement ; IV AES-GCM |
| `ciphertext` | variable | Texte chiffré AES-256-GCM + tag d'authentification de 16 octets |
Le tag d'authentification GCM est automatiquement ajouté au texte chiffré. Toute altération provoque l'échec du déchiffrement avec une erreur plutôt que de retourner un texte clair corrompu.
### Performance
| Opération | Durée (ARM Cortex-A) |
|-----------|----------------------|
| Dérivation de clé (HKDF) | < 1 ms |
| Déchiffrement AES-256-GCM | < 1 ms |
| **Surcoût total au démarrage** | **< 2 ms par clé** |
---
## Sécurité à deux facteurs avec clé SSH
Lorsqu'une clé privée SSH est fournie, casser le chiffrement nécessite **les deux** :
1. La **phrase secrète** (`PICOCLAW_KEY_PASSPHRASE`)
2. Le **fichier de clé privée SSH**
Cela signifie qu'un fichier de configuration divulgué seul ne suffit pas pour récupérer la clé API, même si la phrase secrète est faible. La clé SSH apporte 256 bits d'entropie (Ed25519) indépendamment de la force de la phrase secrète.
### Modèle de menace
| Ce que l'attaquant possède | Peut-il déchiffrer ? |
|---------------------------|---------------------|
| Fichier de configuration uniquement | Non — nécessite la phrase secrète + la clé SSH |
| Clé SSH uniquement | Non — nécessite la phrase secrète |
| Phrase secrète uniquement | Non — nécessite la clé SSH |
| Fichier de configuration + clé SSH + phrase secrète | Oui — compromission totale |
---
## Variables d'environnement
| Variable | Requis | Description |
|----------|--------|-------------|
| `PICOCLAW_KEY_PASSPHRASE` | Oui (pour `enc://`) | Phrase secrète utilisée pour la dérivation de clé |
| `PICOCLAW_SSH_KEY_PATH` | Non | Chemin vers la clé privée SSH. Si non défini, détection automatique depuis `~/.ssh/picoclaw_ed25519.key` |
### Détection automatique de la clé SSH
Si `PICOCLAW_SSH_KEY_PATH` n'est pas défini, PicoClaw recherche la clé dédiée :
```
~/.ssh/picoclaw_ed25519.key
```
Ce fichier dédié évite les conflits avec les clés SSH existantes de l'utilisateur.
Exécutez `picoclaw onboard` pour le générer automatiquement.
`os.UserHomeDir()` est utilisé pour la résolution multiplateforme du répertoire personnel (lit `USERPROFILE` sous Windows, `HOME` sous Unix/macOS).
> **Remarque :** Un fichier de clé SSH est requis pour le chiffrement des identifiants. Si aucune clé n'est trouvée et que `PICOCLAW_SSH_KEY_PATH` n'est pas défini, le chiffrement/déchiffrement échouera. Exécutez `picoclaw onboard` pour générer la clé automatiquement.
---
## Migration
Étant donné que les seuls éléments secrets sont `PICOCLAW_KEY_PASSPHRASE` et le fichier de clé privée SSH, la migration est simple :
1. Copiez le fichier de configuration sur la nouvelle machine.
2. Définissez `PICOCLAW_KEY_PASSPHRASE` avec la même valeur.
3. Copiez le fichier de clé privée SSH au même chemin (ou définissez `PICOCLAW_SSH_KEY_PATH` vers son nouvel emplacement).
Aucun re-chiffrement n'est nécessaire.
---
## Considérations de sécurité
- **La phrase secrète et la clé SSH sont toutes deux requises.** La clé SSH agit comme un second facteur — sans elle, le chiffrement/déchiffrement échouera. Exécutez `picoclaw onboard` pour générer la clé si elle n'existe pas.
- **La clé SSH est en lecture seule à l'exécution.** PicoClaw n'écrit ni ne modifie jamais le fichier de clé SSH.
- **Les clés en texte clair restent prises en charge.** Les configurations existantes sans `enc://` ne sont pas affectées.
- **Le format `enc://` est versionné** via le champ `info` de HKDF (`picoclaw-credential-v1`), permettant de futures mises à niveau d'algorithme sans casser les valeurs chiffrées existantes.
docs/fr/debug.md
+36
View File
@@ -0,0 +1,36 @@
# Débogage de PicoClaw
> Retour au [README](../../README.fr.md)
PicoClaw effectue de multiples interactions complexes en arrière-plan pour chaque requête qu'il reçoit — du routage des messages et de l'évaluation de la complexité, à l'exécution des outils et à l'adaptation aux défaillances de modèle. Pouvoir voir exactement ce qui se passe est crucial, non seulement pour résoudre les problèmes potentiels, mais aussi pour véritablement comprendre le fonctionnement de l'agent.
## Démarrer PicoClaw en mode débogage
Pour obtenir des informations détaillées sur ce que fait l'agent (requêtes LLM, appels d'outils, routage des messages), vous pouvez démarrer la passerelle PicoClaw avec le drapeau de débogage :
```bash
picoclaw gateway --debug
# or
picoclaw gateway -d
```
Dans ce mode, le système formate les logs de manière détaillée et affiche des aperçus des prompts système et des résultats d'exécution des outils.
## Désactiver la troncature des logs (logs complets)
Par défaut, PicoClaw tronque les chaînes très longues (comme le *Prompt Système* ou les résultats JSON volumineux) dans les logs de débogage afin de garder la console lisible.
Si vous avez besoin d'inspecter la sortie complète d'une commande ou le payload exact envoyé au modèle LLM, vous pouvez utiliser le drapeau `--no-truncate`.
**Remarque :** Ce drapeau fonctionne *uniquement* en combinaison avec le mode `--debug`.
```bash
picoclaw gateway --debug --no-truncate
```
Lorsque ce drapeau est actif, la fonction de troncature globale est désactivée. Cela est extrêmement utile pour :
* Vérifier la syntaxe exacte des messages envoyés au fournisseur.
* Lire la sortie complète d'outils comme `exec`, `web_fetch` ou `read_file`.
* Déboguer l'historique de session sauvegardé en mémoire.
docs/fr/docker.md
+1
View File
@@ -12,6 +12,7 @@ git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
# 2. Premier lancement — génère automatiquement docker/data/config.json puis s'arrête
# (se déclenche uniquement quand config.json et workspace/ sont tous deux absents)
docker compose -f docker/docker-compose.yml --profile gateway up
# Le conteneur affiche "First-run setup complete." et s'arrête.
docs/fr/hardware-compatibility.md
+152
View File
@@ -0,0 +1,152 @@
> Retour au [README](../../README.fr.md)
# 🖥️ PicoClaw Liste de compatibilité matérielle
PicoClaw fonctionne sur pratiquement n'importe quel appareil Linux. Cette page répertorie les puces, produits et cartes de développement vérifiés.
**Votre matériel n'est pas listé ?** Soumettez une PR pour l'ajouter ! Les fabricants de matériel sont invités à contribuer et à co-promouvoir.
---
## 1. Support de puces vérifié
### x86
| Fabricant | Puce | Notes |
|-----------|------|-------|
| Intel | Any x86 CPU (i386+) | Tous les processeurs de bureau/serveur/portable |
| AMD | Any x86 CPU | Tous les processeurs de bureau/serveur/portable |
### ARM
| Sous-arch | Puces typiques | Notes |
|-----------|----------------|-------|
| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | Monocœur ARM1176JZF-S |
| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | Monocœur Cortex-A7, utilisé dans LicheePi Zero |
| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | Quadricœur Cortex-A53, utilisé dans Orange Pi Zero 3 |
| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | Quadricœur Cortex-A72 |
| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | Quadricœur Cortex-A76 |
| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | Bicœur Cortex-A53 + NPU, utilisé dans NanoKVM-Pro / MaixCAM2 |
### RISC-V (riscv64)
| Fabricant | Puce | Cœur | Notes |
|-----------|------|------|-------|
| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 intégré, utilisé dans LicheeRV-Nano / NanoKVM / MaixCAM |
| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L intégré, 1 TOPS NPU, caméra AI 4K SiP |
| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | Série de caméras AI RISC-V |
| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | Utilisé dans HaaS506-LD1 RTU industriel |
| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | Utilisé dans Milk-V Jupiter, BananaPi BPI-F3 |
| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | Conforme RVA23, RVV 1024 bits, inférence AI FP8 |
| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8 cœurs, 16MB cache L3, classe bureau |
| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU, utilisé dans CanMV-K230 |
### MIPS
| Fabricant | Puce | Notes |
|-----------|------|-------|
| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz, utilisé dans de nombreux routeurs OpenWrt (ex. Xiaomi Router 3G) |
### LoongArch (loong64)
| Fabricant | Puce | Notes |
|-----------|------|-------|
| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | Quadricœur LA464 @ 2.5GHz, bureau/station de travail |
| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | Quadricœur 4C/8T @ 2.5GHz, IPC comparable à Intel 10e génération |
| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | Bicœur @ 1GHz, applications industrielles/IoT |
---
## 2. Produits vérifiés (par date de sortie)
Produits grand public, routeurs et appareils industriels testés avec PicoClaw.
| Année | Produit | Arch | SoC | RAM | Catégorie |
|-------|---------|------|-----|-----|-----------|
| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | Smartphone |
| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | Tablette |
| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | Routeur (OpenWrt) |
| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | Boîtier TV / Serveur domestique |
| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | Enceinte connectée |
| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | RTU industriel |
| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | IP-KVM Pro |
| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | Caméra AI 4K |
---
## 3. Cartes de développement vérifiées (par date de sortie)
| Année | Carte | Arch | SoC | RAM | Lien d'achat |
|-------|-------|------|-----|-----|--------------|
| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
---
## 4. Fonctionne également sur
### Téléphones Android (via Termux)
Tout téléphone Android ARM64 (2015+) avec 1 Go+ de RAM. Installez [Termux](https://github.com/termux/termux-app), utilisez `proot` pour exécuter PicoClaw.
> Voir [README : Exécuter sur d'anciens téléphones Android](../../README.fr.md#-run-on-old-android-phones) pour les instructions de configuration.
### Bureau / Serveur / Cloud
| Plateforme | Notes |
|------------|-------|
| x86_64 Linux | Binaire natif, aucune dépendance |
| x86_64 Windows | Binaire natif |
| macOS (Intel / Apple Silicon) | Binaire natif |
| Docker (any platform) | `docker compose` en une ligne, voir [Guide Docker](docker.md) |
| OpenWrt routers | Builds MIPS/ARM, nécessite >32 Mo de RAM libre |
| FreeBSD / NetBSD | Builds x86_64 et arm64 disponibles |
---
## 5. Configuration minimale requise
| Ressource | Minimum | Recommandé |
|-----------|---------|------------|
| RAM | 10 Mo libres | 32 Mo+ libres |
| Stockage | 20 Mo (binaire) | 50 Mo+ (avec espace de travail) |
| CPU | N'importe lequel (monocœur 0,6 GHz+) | — |
| OS | Linux (kernel 3.x+) | Linux 5.x+ |
| Réseau | Requis (pour les appels API LLM) | Ethernet ou WiFi |
---
## 6. Comment tester et contribuer
```bash
# 1. Télécharger pour votre architecture
wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
tar xzf picoclaw_Linux_arm64.tar.gz
# 2. Initialiser
./picoclaw onboard
# 3. Tester
./picoclaw agent -m "Hello, what board am I running on?"
```
Builds disponibles : `linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
### Ajouter votre matériel
1. Forkez ce dépôt
2. Ajoutez votre puce / produit / carte dans le tableau approprié
3. Incluez : nom, architecture, SoC, RAM, année et un lien si disponible
4. Soumettez une PR
Fabricants de matériel : vous souhaitez ajouter un support officiel ou co-promouvoir ? Ouvrez une issue ou contactez-nous via [Discord](https://discord.gg/V4sAZ9XWpN).
docs/fr/providers.md
+6 -7
View File
@@ -93,7 +93,7 @@ Cette conception permet également le **support multi-agents** avec une sélecti
],
"agents": {
"defaults": {
"model": "gpt-5.4"
"model_name": "gpt-5.4"
}
}
}
@@ -266,13 +266,13 @@ L'ancienne configuration `providers` est **dépréciée** mais toujours prise en
],
"agents": {
"defaults": {
"model": "glm-4.7"
"model_name": "glm-4.7"
}
}
}
```
Pour un guide de migration détaillé, voir [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md).
Pour un guide de migration détaillé, voir [migration/model-list-migration.md](../migration/model-list-migration.md).
### Architecture des Fournisseurs
@@ -298,7 +298,7 @@ Cela maintient le runtime léger tout en faisant des nouveaux backends compatibl
"agents": {
"defaults": {
"workspace": "~/.picoclaw/workspace",
"model": "glm-4.7",
"model_name": "glm-4.7",
"max_tokens": 8192,
"temperature": 0.7,
"max_tool_iterations": 20
@@ -328,12 +328,11 @@ picoclaw agent -m "Hello"
{
"agents": {
"defaults": {
"model": "anthropic/claude-opus-4-5"
"model_name": "anthropic/claude-opus-4-5"
}
},
"session": {
"dm_scope": "per-channel-peer",
"backlog_limit": 20
"dm_scope": "per-channel-peer"
},
"providers": {
"openrouter": {
docs/fr/troubleshooting.md
+2 -2
View File
@@ -16,7 +16,7 @@
**Correction :** Dans `~/.picoclaw/config.json` (ou votre chemin de configuration) :
1. **agents.defaults.model** doit correspondre à un `model_name` dans `model_list` (par ex. `"openrouter-free"`).
1. **agents.defaults.model_name** doit correspondre à un `model_name` dans `model_list` (par ex. `"openrouter-free"`).
2. Le **model** de cette entrée doit être un identifiant de modèle OpenRouter valide, par exemple :
- `"openrouter/free"` – niveau gratuit automatique
- `"google/gemini-2.0-flash-exp:free"`
@@ -28,7 +28,7 @@ Exemple :
{
"agents": {
"defaults": {
"model": "openrouter-free"
"model_name": "openrouter-free"
}
},
"model_list": [
docs/hardware-compatibility.md
+150
View File
@@ -0,0 +1,150 @@
# 🖥️ PicoClaw Hardware Compatibility List
PicoClaw runs on virtually any Linux device. This page tracks verified chips, products, and development boards.
**Your hardware not listed?** Submit a PR to add it! Hardware vendors are welcome to contribute and co-promote.
---
## 1. Verified Chip Support
### x86
| Vendor | Chip | Notes |
|--------|------|-------|
| Intel | Any x86 CPU (i386+) | All desktop/server/laptop processors |
| AMD | Any x86 CPU | All desktop/server/laptop processors |
### ARM
| Sub-arch | Typical Chips | Notes |
|----------|--------------|-------|
| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | Single-core ARM1176JZF-S |
| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | Single-core Cortex-A7, used in LicheePi Zero |
| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | Quad-core Cortex-A53, used in Orange Pi Zero 3 |
| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | Quad-core Cortex-A72 |
| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | Quad-core Cortex-A76 |
| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | Dual-core Cortex-A53 + NPU, used in NanoKVM-Pro / MaixCAM2 |
### RISC-V (riscv64)
| Vendor | Chip | Core | Notes |
|--------|------|------|-------|
| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 on-chip, used in LicheeRV-Nano / NanoKVM / MaixCAM |
| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L on-chip, 1 TOPS NPU, 4K AI camera SiP |
| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | RISC-V AI camera series |
| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | Used in HaaS506-LD1 industrial RTU |
| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | Used in Milk-V Jupiter, BananaPi BPI-F3 |
| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | RVA23 compliant, 1024-bit RVV, FP8 AI inference |
| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8-core, 16MB L3 cache, desktop-class |
| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU, used in CanMV-K230 |
### MIPS
| Vendor | Chip | Notes |
|--------|------|-------|
| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz, used in many OpenWrt routers (e.g. Xiaomi Router 3G) |
### LoongArch (loong64)
| Vendor | Chip | Notes |
|--------|------|-------|
| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | Quad-core LA464 @ 2.5GHz, desktop/workstation |
| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | Quad-core 4C/8T @ 2.5GHz, IPC comparable to Intel 10th gen |
| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | Dual-core @ 1GHz, industrial/IoT applications |
---
## 2. Verified Products (by release date)
Consumer products, routers, and industrial devices that have been tested with PicoClaw.
| Year | Product | Arch | SoC | RAM | Category |
|------|---------|------|-----|-----|----------|
| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | Smartphone |
| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | Tablet |
| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | Router (OpenWrt) |
| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | TV Box / Home Server |
| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | Smart Speaker |
| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | Industrial RTU |
| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | Pro IP-KVM |
| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | 4K AI Camera |
---
## 3. Verified Development Boards (by release date)
| Year | Board | Arch | SoC | RAM | Buy Link |
|------|-------|------|-----|-----|----------|
| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
---
## 4. Also Works On
### Android Phones (via Termux)
Any ARM64 Android phone (2015+) with 1GB+ RAM. Install [Termux](https://github.com/termux/termux-app), use `proot` to run PicoClaw.
> See [README: Run on old Android Phones](../README.md#-run-on-old-android-phones) for setup instructions.
### Desktop / Server / Cloud
| Platform | Notes |
|----------|-------|
| x86_64 Linux | Native binary, no dependencies |
| x86_64 Windows | Native binary |
| macOS (Intel / Apple Silicon) | Native binary |
| Docker (any platform) | `docker compose` one-liner, see [Docker Guide](docker.md) |
| OpenWrt routers | MIPS/ARM builds, requires >32MB free RAM |
| FreeBSD / NetBSD | x86_64 and arm64 builds available |
---
## 5. Minimum Requirements
| Resource | Minimum | Recommended |
|----------|---------|-------------|
| RAM | 10MB free | 32MB+ free |
| Storage | 20MB (binary) | 50MB+ (with workspace) |
| CPU | Any (single core 0.6GHz+) | — |
| OS | Linux (kernel 3.x+) | Linux 5.x+ |
| Network | Required (for LLM API calls) | Ethernet or WiFi |
---
## 6. How to Test & Contribute
```bash
# 1. Download for your architecture
wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
tar xzf picoclaw_Linux_arm64.tar.gz
# 2. Initialize
./picoclaw onboard
# 3. Test
./picoclaw agent -m "Hello, what board am I running on?"
```
Available builds: `linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
### Add Your Hardware
1. Fork this repo
2. Add your chip / product / board to the appropriate table
3. Include: name, arch, SoC, RAM, year, and a link if available
4. Submit a PR
Hardware vendors: want to add official support or co-promote? Open an issue or reach out via [Discord](https://discord.gg/V4sAZ9XWpN).
docs/ja/ANTIGRAVITY_AUTH.md
+809
View File
@@ -0,0 +1,809 @@
> [README](../../README.ja.md) に戻る
# Antigravity 認証・統合ガイド
## 概要
**Antigravity**（Google Cloud Code Assist）は、Google が提供する AI モデルプロバイダーで、Google のクラウドインフラストラクチャを通じて Claude Opus 4.6 や Gemini などのモデルへのアクセスを提供します。本ドキュメントでは、認証の仕組み、モデルの取得方法、PicoClaw での新しいプロバイダーの実装方法について完全なガイドを提供します。
---
## 目次
1. [認証フロー](#認証フロー)
2. [OAuth 実装の詳細](#oauth-実装の詳細)
3. [トークン管理](#トークン管理)
4. [モデルリストの取得](#モデルリストの取得)
5. [使用量トラッキング](#使用量トラッキング)
6. [プロバイダープラグイン構造](#プロバイダープラグイン構造)
7. [統合要件](#統合要件)
8. [API エンドポイント](#api-エンドポイント)
9. [設定](#設定)
10. [PicoClaw での新しいプロバイダーの作成](#picoclaw-での新しいプロバイダーの作成)
---
## 認証フロー
### 1. PKCE 付き OAuth 2.0
Antigravity はセキュアな認証のために **OAuth 2.0 with PKCE（Proof Key for Code Exchange）** を使用します：
```
┌─────────────┐ ┌─────────────────┐
│ Client │ ───(1) Generate PKCE Pair────────> │ │
│ │ ───(2) Open Auth URL─────────────> │ Google OAuth │
│ │ │ Server │
│ │ <──(3) Redirect with Code───────── │ │
│ │ └─────────────────┘
│ │ ───(4) Exchange Code for Tokens──> │ Token URL │
│ │ │ │
│ │ <──(5) Access + Refresh Tokens──── │ │
└─────────────┘ └─────────────────┘
```
### 2. 詳細手順
#### ステップ 1：PKCE パラメータの生成
```typescript
function generatePkce(): { verifier: string; challenge: string } {
const verifier = randomBytes(32).toString("hex");
const challenge = createHash("sha256").update(verifier).digest("base64url");
return { verifier, challenge };
}
```
#### ステップ 2：認可 URL の構築
```typescript
const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
const REDIRECT_URI = "http://localhost:51121/oauth-callback";
function buildAuthUrl(params: { challenge: string; state: string }): string {
const url = new URL(AUTH_URL);
url.searchParams.set("client_id", CLIENT_ID);
url.searchParams.set("response_type", "code");
url.searchParams.set("redirect_uri", REDIRECT_URI);
url.searchParams.set("scope", SCOPES.join(" "));
url.searchParams.set("code_challenge", params.challenge);
url.searchParams.set("code_challenge_method", "S256");
url.searchParams.set("state", params.state);
url.searchParams.set("access_type", "offline");
url.searchParams.set("prompt", "consent");
return url.toString();
}
```
**必要なスコープ：**
```typescript
const SCOPES = [
"https://www.googleapis.com/auth/cloud-platform",
"https://www.googleapis.com/auth/userinfo.email",
"https://www.googleapis.com/auth/userinfo.profile",
"https://www.googleapis.com/auth/cclog",
"https://www.googleapis.com/auth/experimentsandconfigs",
];
```
#### ステップ 3：OAuth コールバックの処理
**自動モード（ローカル開発）：**
- ポート 51121 でローカル HTTP サーバーを起動
- Google からのリダイレクトを待機
- クエリパラメータから認可コードを抽出
**手動モード（リモート/ヘッドレス）：**
- ユーザーに認可 URL を表示
- ユーザーがブラウザで認証を完了
- ユーザーが完全なリダイレクト URL をターミナルに貼り付け
- 貼り付けられた URL からコードを解析
#### ステップ 4：コードをトークンに交換
```typescript
const TOKEN_URL = "https://oauth2.googleapis.com/token";
async function exchangeCode(params: {
code: string;
verifier: string;
}): Promise<{ access: string; refresh: string; expires: number }> {
const response = await fetch(TOKEN_URL, {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET,
code: params.code,
grant_type: "authorization_code",
redirect_uri: REDIRECT_URI,
code_verifier: params.verifier,
}),
});
const data = await response.json();
return {
access: data.access_token,
refresh: data.refresh_token,
expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000, // 5 min buffer
};
}
```
#### ステップ 5：追加のユーザーデータの取得
**ユーザーメール：**
```typescript
async function fetchUserEmail(accessToken: string): Promise<string | undefined> {
const response = await fetch(
"https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
{ headers: { Authorization: `Bearer ${accessToken}` } }
);
const data = await response.json();
return data.email;
}
```
**プロジェクト ID（API 呼び出しに必須）：**
```typescript
async function fetchProjectId(accessToken: string): Promise<string> {
const headers = {
Authorization: `Bearer ${accessToken}`,
"Content-Type": "application/json",
"User-Agent": "google-api-nodejs-client/9.15.1",
"X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
"Client-Metadata": JSON.stringify({
ideType: "IDE_UNSPECIFIED",
platform: "PLATFORM_UNSPECIFIED",
pluginType: "GEMINI",
}),
};
const response = await fetch(
"https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
{
method: "POST",
headers,
body: JSON.stringify({
metadata: {
ideType: "IDE_UNSPECIFIED",
platform: "PLATFORM_UNSPECIFIED",
pluginType: "GEMINI",
},
}),
}
);
const data = await response.json();
return data.cloudaicompanionProject || "rising-fact-p41fc"; // デフォルトのフォールバック
}
```
---
## OAuth 実装の詳細
### クライアント認証情報
**重要：** これらは pi-ai との同期のためにソースコード内で base64 エンコードされています：
```typescript
const decode = (s: string) => Buffer.from(s, "base64").toString();
const CLIENT_ID = decode(
"MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ=="
);
const CLIENT_SECRET = decode("R09DU1BYLUs1OEZXUjQ4NkxkTEoxbUxCOHNYQzR6NnFEQWY=");
```
### OAuth フローモード
1. **自動フロー**（ブラウザのあるローカルマシン）：
- ブラウザを自動的に開く
- ローカルコールバックサーバーがリダイレクトをキャプチャ
- 初回認証後はユーザー操作不要
2. **手動フロー**（リモート/ヘッドレス/WSL2）：
- 手動コピー＆ペースト用の URL を表示
- ユーザーが外部ブラウザで認証を完了
- ユーザーが完全なリダイレクト URL を貼り付け
```typescript
function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
return isRemote || isWSL2Sync();
}
```
---
## トークン管理
### 認証プロファイル構造
```typescript
type OAuthCredential = {
type: "oauth";
provider: "google-antigravity";
access: string; // アクセストークン
refresh: string; // リフレッシュトークン
expires: number; // 有効期限タイムスタンプ（エポックからのミリ秒）
email?: string; // ユーザーメール
projectId?: string; // Google Cloud プロジェクト ID
};
```
### トークンの更新
認証情報にはリフレッシュトークンが含まれており、現在のアクセストークンが期限切れになった際に新しいアクセストークンを取得するために使用できます。有効期限は競合状態を防ぐために 5 分のバッファを設けています。
---
## モデルリストの取得
### 利用可能なモデルの取得
```typescript
const BASE_URL = "https://cloudcode-pa.googleapis.com";
async function fetchAvailableModels(
accessToken: string,
projectId: string
): Promise<Model[]> {
const headers = {
Authorization: `Bearer ${accessToken}`,
"Content-Type": "application/json",
"User-Agent": "antigravity",
"X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
};
const response = await fetch(
`${BASE_URL}/v1internal:fetchAvailableModels`,
{
method: "POST",
headers,
body: JSON.stringify({ project: projectId }),
}
);
const data = await response.json();
// クォータ情報付きのモデルを返す
return Object.entries(data.models).map(([modelId, modelInfo]) => ({
id: modelId,
displayName: modelInfo.displayName,
quotaInfo: {
remainingFraction: modelInfo.quotaInfo?.remainingFraction,
resetTime: modelInfo.quotaInfo?.resetTime,
isExhausted: modelInfo.quotaInfo?.isExhausted,
},
}));
}
```
### レスポンス形式
```typescript
type FetchAvailableModelsResponse = {
models?: Record<string, {
displayName?: string;
quotaInfo?: {
remainingFraction?: number | string;
resetTime?: string; // ISO 8601 タイムスタンプ
isExhausted?: boolean;
};
}>;
};
```
---
## 使用量トラッキング
### 使用量データの取得
```typescript
export async function fetchAntigravityUsage(
token: string,
timeoutMs: number
): Promise<ProviderUsageSnapshot> {
// 1. クレジットとプラン情報を取得
const loadCodeAssistRes = await fetch(
`${BASE_URL}/v1internal:loadCodeAssist`,
{
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
metadata: {
ideType: "ANTIGRAVITY",
platform: "PLATFORM_UNSPECIFIED",
pluginType: "GEMINI",
},
}),
}
);
// クレジット情報を抽出
const { availablePromptCredits, planInfo, currentTier } = data;
// 2. モデルクォータを取得
const modelsRes = await fetch(
`${BASE_URL}/v1internal:fetchAvailableModels`,
{
method: "POST",
headers: { Authorization: `Bearer ${token}` },
body: JSON.stringify({ project: projectId }),
}
);
// 使用量ウィンドウを構築
return {
provider: "google-antigravity",
displayName: "Google Antigravity",
windows: [
{ label: "Credits", usedPercent: calculateUsedPercent(available, monthly) },
// 個別モデルクォータ...
],
plan: currentTier?.name || planType,
};
}
```
### 使用量レスポンス構造
```typescript
type ProviderUsageSnapshot = {
provider: "google-antigravity";
displayName: string;
windows: UsageWindow[];
plan?: string;
error?: string;
};
type UsageWindow = {
label: string; // "Credits" またはモデル ID
usedPercent: number; // 0-100
resetAt?: number; // クォータがリセットされるタイムスタンプ
};
```
---
## プロバイダープラグイン構造
### プラグイン定義
```typescript
const antigravityPlugin = {
id: "google-antigravity-auth",
name: "Google Antigravity Auth",
description: "OAuth flow for Google Antigravity (Cloud Code Assist)",
configSchema: emptyPluginConfigSchema(),
register(api: PicoClawPluginApi) {
api.registerProvider({
id: "google-antigravity",
label: "Google Antigravity",
docsPath: "/providers/models",
aliases: ["antigravity"],
auth: [
{
id: "oauth",
label: "Google OAuth",
hint: "PKCE + localhost callback",
kind: "oauth",
run: async (ctx: ProviderAuthContext) => {
// OAuth 実装はここに記述
},
},
],
});
},
};
```
### ProviderAuthContext
```typescript
type ProviderAuthContext = {
config: PicoClawConfig;
agentDir?: string;
workspaceDir?: string;
prompter: WizardPrompter; // UI プロンプト/通知
runtime: RuntimeEnv; // ログなど
isRemote: boolean; // リモート実行かどうか
openUrl: (url: string) => Promise<void>; // ブラウザオープナー
oauth: {
createVpsAwareHandlers: Function;
};
};
```
### ProviderAuthResult
```typescript
type ProviderAuthResult = {
profiles: Array<{
profileId: string;
credential: AuthProfileCredential;
}>;
configPatch?: Partial<PicoClawConfig>;
defaultModel?: string;
notes?: string[];
};
```
---
## 統合要件
### 1. 必要な環境/依存関係
- Go ≥ 1.25
- PicoClaw コードベース（`pkg/providers/` および `pkg/auth/`）
- `crypto` および `net/http` 標準ライブラリパッケージ
### 2. API 呼び出しに必要なヘッダー
```typescript
const REQUIRED_HEADERS = {
"Authorization": `Bearer ${accessToken}`,
"Content-Type": "application/json",
"User-Agent": "antigravity", // または "google-api-nodejs-client/9.15.1"
"X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
};
// loadCodeAssist 呼び出しには以下も含める：
const CLIENT_METADATA = {
ideType: "ANTIGRAVITY", // または "IDE_UNSPECIFIED"
platform: "PLATFORM_UNSPECIFIED",
pluginType: "GEMINI",
};
```
### 3. モデルスキーマのサニタイズ
Antigravity は Gemini 互換モデルを使用するため、ツールスキーマのサニタイズが必要です：
```typescript
const GOOGLE_SCHEMA_UNSUPPORTED_KEYWORDS = new Set([
"patternProperties",
"additionalProperties",
"$schema",
"$id",
"$ref",
"$defs",
"definitions",
"examples",
"minLength",
"maxLength",
"minimum",
"maximum",
"multipleOf",
"pattern",
"format",
"minItems",
"maxItems",
"uniqueItems",
"minProperties",
"maxProperties",
]);
// 送信前にスキーマをクリーンアップ
function cleanToolSchemaForGemini(schema: Record<string, unknown>): unknown {
// サポートされていないキーワードを削除
// トップレベルに type: "object" があることを確認
// anyOf/oneOf ユニオンをフラット化
}
```
### 4. 思考ブロックの処理（Claude モデル）
Antigravity の Claude モデルでは、思考ブロックに特別な処理が必要です：
```typescript
const ANTIGRAVITY_SIGNATURE_RE = /^[A-Za-z0-9+/]+={0,2}$/;
export function sanitizeAntigravityThinkingBlocks(
messages: AgentMessage[]
): AgentMessage[] {
// 思考シグネチャを検証
// シグネチャフィールドを正規化
// 署名されていない思考ブロックを破棄
}
```
---
## API エンドポイント
### 認証エンドポイント
| エンドポイント | メソッド | 用途 |
|---------------|---------|------|
| `https://accounts.google.com/o/oauth2/v2/auth` | GET | OAuth 認可 |
| `https://oauth2.googleapis.com/token` | POST | トークン交換 |
| `https://www.googleapis.com/oauth2/v1/userinfo` | GET | ユーザー情報（メール） |
### Cloud Code Assist エンドポイント
| エンドポイント | メソッド | 用途 |
|---------------|---------|------|
| `https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist` | POST | プロジェクト情報、クレジット、プランの読み込み |
| `https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels` | POST | クォータ付き利用可能モデルの一覧 |
| `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse` | POST | チャットストリーミングエンドポイント |
**API リクエスト形式（チャット）：**
`v1internal:streamGenerateContent` エンドポイントは、標準の Gemini リクエストをラップするエンベロープ形式を期待します：
```json
{
"project": "your-project-id",
"model": "model-id",
"request": {
"contents": [...],
"systemInstruction": {...},
"generationConfig": {...},
"tools": [...]
},
"requestType": "agent",
"userAgent": "antigravity",
"requestId": "agent-timestamp-random"
}
```
**API レスポンス形式（SSE）：**
各 SSE メッセージ（`data: {...}`）は `response` フィールドでラップされます：
```json
{
"response": {
"candidates": [...],
"usageMetadata": {...},
"modelVersion": "...",
"responseId": "..."
},
"traceId": "...",
"metadata": {}
}
```
---
## 設定
### config.json の設定
```json
{
"model_list": [
{
"model_name": "gemini-flash",
"model": "antigravity/gemini-3-flash",
"auth_method": "oauth"
}
],
"agents": {
"defaults": {
"model_name": "gemini-flash"
}
}
}
```
### 認証プロファイルの保存
認証プロファイルは `~/.picoclaw/auth.json` に保存されます：
```json
{
"credentials": {
"google-antigravity": {
"access_token": "ya29...",
"refresh_token": "1//...",
"expires_at": "2026-01-01T00:00:00Z",
"provider": "google-antigravity",
"auth_method": "oauth",
"email": "user@example.com",
"project_id": "my-project-id"
}
}
}
```
---
## PicoClaw での新しいプロバイダーの作成
PicoClaw のプロバイダーは `pkg/providers/` 配下の Go パッケージとして実装されます。新しいプロバイダーを追加するには：
### ステップバイステップの実装
#### 1. プロバイダーファイルの作成
`pkg/providers/` に新しい Go ファイルを作成します：
```
pkg/providers/
└── your_provider.go
```
#### 2. Provider インターフェースの実装
プロバイダーは `pkg/providers/types.go` で定義された `Provider` インターフェースを実装する必要があります：
```go
package providers
type YourProvider struct {
apiKey string
apiBase string
}
func NewYourProvider(apiKey, apiBase, proxy string) *YourProvider {
if apiBase == "" {
apiBase = "https://api.your-provider.com/v1"
}
return &YourProvider{apiKey: apiKey, apiBase: apiBase}
}
func (p *YourProvider) Chat(ctx context.Context, messages []Message, tools []Tool, cb StreamCallback) error {
// ストリーミング付きチャット補完を実装
}
```
#### 3. ファクトリーへの登録
`pkg/providers/factory.go` のプロトコルスイッチにプロバイダーを追加します：
```go
case "your-provider":
return NewYourProvider(sel.apiKey, sel.apiBase, sel.proxy), nil
```
#### 4. デフォルト設定の追加（オプション）
`pkg/config/defaults.go` にデフォルトエントリを追加します：
```go
{
ModelName: "your-model",
Model: "your-provider/model-name",
APIKey: "",
},
```
#### 5. 認証サポートの追加（オプション）
プロバイダーが OAuth や特別な認証を必要とする場合、`cmd/picoclaw/internal/auth/helpers.go` にケースを追加します：
```go
case "your-provider":
authLoginYourProvider()
```
#### 6. `config.json` での設定
```json
{
"model_list": [
{
"model_name": "your-model",
"model": "your-provider/model-name",
"api_key": "your-api-key",
"api_base": "https://api.your-provider.com/v1"
}
]
}
```
---
## 実装のテスト
### CLI コマンド
```bash
# プロバイダーで認証
picoclaw auth login --provider your-provider
# モデルの一覧表示（Antigravity 用）
picoclaw auth models
# ゲートウェイの起動
picoclaw gateway
# 特定のモデルでエージェントを実行
picoclaw agent -m "Hello" --model your-model
```
### テスト用環境変数
```bash
# デフォルトモデルの上書き
export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
# プロバイダー設定の上書き
export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
```
---
## 参考資料
- **ソースファイル：**
- `pkg/providers/antigravity_provider.go` - Antigravity プロバイダー実装
- `pkg/auth/oauth.go` - OAuth フロー実装
- `pkg/auth/store.go` - 認証情報ストレージ（`~/.picoclaw/auth.json`）
- `pkg/providers/factory.go` - プロバイダーファクトリーとプロトコルルーティング
- `pkg/providers/types.go` - プロバイダーインターフェース定義
- `cmd/picoclaw/internal/auth/helpers.go` - 認証 CLI コマンド
- **ドキュメント：**
- `docs/ANTIGRAVITY_USAGE.md` - Antigravity 使用ガイド
- `docs/migration/model-list-migration.md` - 移行ガイド
---
## 注意事項
1. **Google Cloud プロジェクト：** Antigravity は Google Cloud プロジェクトで Gemini for Google Cloud が有効になっている必要があります
2. **クォータ：** Google Cloud プロジェクトのクォータを使用します（個別の課金ではありません）
3. **モデルアクセス：** 利用可能なモデルは Google Cloud プロジェクトの設定に依存します
4. **思考ブロック：** Antigravity 経由の Claude モデルは、署名付き思考ブロックの特別な処理が必要です
5. **スキーマサニタイズ：** ツールスキーマはサポートされていない JSON Schema キーワードを削除するためにサニタイズが必要です
---
---
## 一般的なエラー処理
### 1. レート制限（HTTP 429）
プロジェクト/モデルのクォータが枯渇すると、Antigravity は 429 エラーを返します。エラーレスポンスには通常、`details` フィールドに `quotaResetDelay` が含まれます。
**429 エラーの例：**
```json
{
"error": {
"code": 429,
"message": "You have exhausted your capacity on this model. Your quota will reset after 4h30m28s.",
"status": "RESOURCE_EXHAUSTED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"metadata": {
"quotaResetDelay": "4h30m28.060903746s"
}
}
]
}
}
```
### 2. 空のレスポンス（制限付きモデル）
一部のモデルは利用可能モデルリストに表示されますが、空のレスポンスを返す場合があります（200 OK だが SSE ストリームが空）。これは通常、現在のプロジェクトに使用権限がないプレビュー版または制限付きモデルで発生します。
**対処法：** 空のレスポンスをエラーとして扱い、そのモデルがプロジェクトに対して制限されているか無効である可能性があることをユーザーに通知します。
---
## トラブルシューティング
### "Token expired"（トークン期限切れ）
- OAuth トークンを更新：`picoclaw auth login --provider antigravity`
### "Gemini for Google Cloud is not enabled"（Gemini for Google Cloud が有効になっていない）
- Google Cloud Console で API を有効にしてください
### "Project not found"（プロジェクトが見つからない）
- Google Cloud プロジェクトで必要な API が有効になっていることを確認してください
- 認証中にプロジェクト ID が正しく取得されているか確認してください
### モデルがリストに表示されない
- OAuth 認証が正常に完了したことを確認してください
- 認証プロファイルストレージを確認：`~/.picoclaw/auth.json`
- `picoclaw auth login --provider antigravity` を再実行してください
docs/ja/ANTIGRAVITY_USAGE.md
+72
View File
@@ -0,0 +1,72 @@
> [README](../../README.ja.md) に戻る
# PicoClaw で Antigravity プロバイダーを使用する
このガイドでは、PicoClaw で **Antigravity**（Google Cloud Code Assist）プロバイダーをセットアップして使用する方法を説明します。
## 前提条件
1. Google アカウント。
2. Google Cloud Code Assist が有効であること（通常「Gemini for Google Cloud」のオンボーディングから利用可能）。
## 1. 認証
Antigravity で認証するには、以下のコマンドを実行します：
```bash
picoclaw auth login --provider antigravity
```
### 手動認証（ヘッドレス/VPS）
サーバー（Coolify/Docker）上で実行しており、`localhost` にアクセスできない場合は、以下の手順に従ってください：
1. 上記のコマンドを実行します。
2. 表示された URL をコピーし、ローカルブラウザで開きます。
3. ログインを完了します。
4. ブラウザが `localhost:51121` URL にリダイレクトされます（ページは読み込めません）。
5. **ブラウザのアドレスバーからその最終 URL をコピーします**。
6. **PicoClaw が待機しているターミナルにそれを貼り付けます**。
PicoClaw が自動的に認証コードを抽出し、プロセスを完了します。
## 2. モデルの管理
### 利用可能なモデルの一覧
プロジェクトがアクセスできるモデルとそのクォータを確認するには：
```bash
picoclaw auth models
```
### モデルの切り替え
`~/.picoclaw/config.json` でデフォルトモデルを変更するか、CLI でオーバーライドできます：
```bash
# 単一コマンドでオーバーライド
picoclaw agent -m "Hello" --model claude-opus-4-6-thinking
```
## 3. 実際の使用方法（Coolify/Docker）
Coolify または Docker でデプロイしている場合、以下の手順でテストしてください：
1. **環境変数**：
* `PICOCLAW_AGENTS_DEFAULTS_MODEL=gemini-flash`
2. **認証の永続化**：
ローカルでログイン済みの場合、認証情報をサーバーにコピーできます：
```bash
scp ~/.picoclaw/auth.json user@your-server:~/.picoclaw/
```
*または*、ターミナルアクセスがある場合、サーバー上で `auth login` コマンドを一度実行してください。
## 4. トラブルシューティング
* **空のレスポンス**：モデルが空の応答を返す場合、プロジェクトで制限されている可能性があります。`gemini-3-flash` または `claude-opus-4-6-thinking` を試してください。
* **429 レート制限**：Antigravity には厳格なクォータがあります。制限に達した場合、PicoClaw はエラーメッセージに「リセット時間」を表示します。
* **404 Not Found**：`picoclaw auth models` リストのモデル ID を使用していることを確認してください。フルパスではなく、短い ID（例：`gemini-3-flash`）を使用してください。
## 5. 動作確認済みモデルのまとめ
テストに基づき、以下のモデルが最も信頼性が高いです：
* `gemini-3-flash`（高速、高可用性）
* `gemini-2.5-flash-lite`（軽量）
* `claude-opus-4-6-thinking`（高性能、推論機能を含む）
docs/ja/chat-apps.md
+74 -41
View File
@@ -12,19 +12,19 @@ PicoClaw は複数のチャットプラットフォームをサポートして
| チャネル | セットアップ難易度 | 特徴 | ドキュメント |
| -------------------- | ------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Telegram** | ⭐ 簡単 | 推奨、音声テキスト変換対応、ロングポーリング（公開 IP 不要） | [ドキュメント](../channels/telegram/README.zh.md) |
| **Discord** | ⭐ 簡単 | Socket Mode、グループ/DM 対応、Bot エコシステム充実 | [ドキュメント](../channels/discord/README.zh.md) |
| **WhatsApp** | ⭐ 簡単 | ネイティブ (QR スキャン) または Bridge URL | [ドキュメント](../channels/whatsapp/README.zh.md) |
| **Slack** | ⭐ 簡単 | **Socket Mode** (公開 IP 不要)、エンタープライズ対応 | [ドキュメント](../channels/slack/README.zh.md) |
| **Matrix** | ⭐⭐ 中程度 | フェデレーションプロトコル、セルフホスト対応 | [ドキュメント](../channels/matrix/README.zh.md) |
| **QQ** | ⭐⭐ 中程度 | 公式ボット API、中国コミュニティ向け | [ドキュメント](../channels/qq/README.zh.md) |
| **DingTalk** | ⭐⭐ 中程度 | Stream モード（公開 IP 不要）、企業向け | [ドキュメント](../channels/dingtalk/README.zh.md) |
| **LINE** | ⭐⭐⭐ やや難 | HTTPS Webhook が必要 | [ドキュメント](../channels/line/README.zh.md) |
| **WeCom (企業微信)** | ⭐⭐⭐ やや難 | グループ Bot (Webhook)、カスタムアプリ (API)、AI Bot 対応 | [Bot](../channels/wecom/wecom_bot/README.zh.md) / [App](../channels/wecom/wecom_app/README.zh.md) / [AI Bot](../channels/wecom/wecom_aibot/README.zh.md) |
| **Feishu (飛書)** | ⭐⭐⭐ やや難 | エンタープライズコラボレーション、機能豊富 | [ドキュメント](../channels/feishu/README.zh.md) |
| **Telegram** | ⭐ 簡単 | 推奨、音声テキスト変換対応、ロングポーリング（公開 IP 不要） | [ドキュメント](../channels/telegram/README.ja.md) |
| **Discord** | ⭐ 簡単 | Socket Mode、グループ/DM 対応、Bot エコシステム充実 | [ドキュメント](../channels/discord/README.ja.md) |
| **WhatsApp** | ⭐ 簡単 | ネイティブ (QR スキャン) または Bridge URL | [ドキュメント](#whatsapp) |
| **Slack** | ⭐ 簡単 | **Socket Mode** (公開 IP 不要)、エンタープライズ対応 | [ドキュメント](../channels/slack/README.ja.md) |
| **Matrix** | ⭐⭐ 中程度 | フェデレーションプロトコル、セルフホスト対応 | [ドキュメント](../channels/matrix/README.ja.md) |
| **QQ** | ⭐⭐ 中程度 | 公式ボット API、中国コミュニティ向け | [ドキュメント](../channels/qq/README.ja.md) |
| **DingTalk** | ⭐⭐ 中程度 | Stream モード（公開 IP 不要）、企業向け | [ドキュメント](../channels/dingtalk/README.ja.md) |
| **LINE** | ⭐⭐⭐ やや難 | HTTPS Webhook が必要 | [ドキュメント](../channels/line/README.ja.md) |
| **WeCom (企業微信)** | ⭐⭐⭐ やや難 | グループ Bot (Webhook)、カスタムアプリ (API)、AI Bot 対応 | [Bot](../channels/wecom/wecom_bot/README.ja.md) / [App](../channels/wecom/wecom_app/README.ja.md) / [AI Bot](../channels/wecom/wecom_aibot/README.ja.md) |
| **Feishu (飛書)** | ⭐⭐⭐ やや難 | エンタープライズコラボレーション、機能豊富 | [ドキュメント](../channels/feishu/README.ja.md) |
| **IRC** | ⭐⭐ 中程度 | サーバー + TLS 設定 | - |
| **OneBot** | ⭐⭐ 中程度 | NapCat/Go-CQHTTP 互換、コミュニティエコシステム充実 | [ドキュメント](../channels/onebot/README.zh.md) |
| **MaixCam** | ⭐ 簡単 | Sipeed AI カメラハードウェア統合チャネル | [ドキュメント](../channels/maixcam/README.zh.md) |
| **OneBot** | ⭐⭐ 中程度 | NapCat/Go-CQHTTP 互換、コミュニティエコシステム充実 | [ドキュメント](../channels/onebot/README.ja.md) |
| **MaixCam** | ⭐ 簡単 | Sipeed AI カメラハードウェア統合チャネル | [ドキュメント](../channels/maixcam/README.ja.md) |
| **Pico** | ⭐ 簡単 | PicoClaw ネイティブプロトコルチャネル | |
---
@@ -207,12 +207,13 @@ picoclaw gateway
<details>
<summary><b>QQ</b></summary>
**1. Bot を作成**
**クイックセットアップ（推奨）**
- [QQ 開放プラットフォーム](https://q.qq.com/#) にアクセス
- アプリケーションを作成 → **AppID** と **AppSecret** を取得
QQ 開放プラットフォームでは、OpenClaw 互換ボットのワンクリックセットアップページが提供されています：
**2. 設定**
1. [QQ Bot クイックスタート](https://q.qq.com/qqbot/openclaw/index.html) を開き、QR コードをスキャンしてログイン
2. ボットが自動的に作成されます — **App ID** と **App Secret** をコピー
3. PicoClaw を設定：
```json
{
@@ -227,13 +228,20 @@ picoclaw gateway
}
```
> `allow_from` を空にするとすべてのユーザーを許可します。QQ 番号を指定してアクセスを制限することもできます。
4. `picoclaw gateway` を実行し、QQ を開いてボットとチャット
**3. 実行**
> App Secret は一度しか表示されません。すぐに保存してください — 再度表示するとリセットされます。
>
> クイックセットアップで作成されたボットは、最初は作成者のみが使用でき、グループチャットには対応していません。グループアクセスを有効にするには、[QQ 開放プラットフォーム](https://q.qq.com/) でサンドボックスモードを設定してください。
```bash
picoclaw gateway
```
**手動セットアップ**
ボットを手動で作成する場合：
* [QQ 開放プラットフォーム](https://q.qq.com/) にログインして開発者登録
* QQ ボットを作成 — アバターと名前をカスタマイズ
* ボット設定から **App ID** と **App Secret** をコピー
* 上記の設定を行い、`picoclaw gateway` を実行
</details>
@@ -242,9 +250,10 @@ picoclaw gateway
**1. Slack App を作成**
* [Slack API](https://api.slack.com/apps) でアプリを作成
* **Socket Mode** を有効化
* **Bot Token** と **App-Level Token** を取得
* [Slack API](https://api.slack.com/apps) にアクセスして新しいアプリを作成
* **OAuth & Permissions** で Bot スコープを追加：`chat:write`、`app_mentions:read`、`im:history`、`im:read`、`im:write`
* アプリをワークスペースにインストール
* **Bot Token**（`xoxb-...`）と **App-Level Token**（`xapp-...`、Socket Mode を有効にして取得）をコピー
**2. 設定**
@@ -253,8 +262,8 @@ picoclaw gateway
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-YOUR_BOT_TOKEN",
"app_token": "xapp-YOUR_APP_TOKEN",
"bot_token": "xoxb-YOUR-BOT-TOKEN",
"app_token": "xapp-YOUR-APP-TOKEN",
"allow_from": []
}
}
@@ -280,21 +289,26 @@ picoclaw gateway
"irc": {
"enabled": true,
"server": "irc.libera.chat:6697",
"tls": true,
"nick": "picoclaw-bot",
"use_tls": true,
"channels_to_join": ["#your-channel"],
"channels": ["#your-channel"],
"password": "",
"allow_from": []
}
}
}
```
オプション：NickServ 認証用の `nickserv_password`、SASL 認証用の `sasl_user`/`sasl_password`。
**2. 実行**
```bash
picoclaw gateway
```
ボットは IRC サーバーに接続し、指定されたチャネルに参加します。
</details>
<details>
@@ -382,11 +396,14 @@ picoclaw gateway
<details>
<summary><b>Feishu (飛書)</b></summary>
PicoClaw は WebSocket/SDK モードで飛書に接続します — 公開 Webhook URL やコールバックサーバーは不要です。
**1. アプリを作成**
* [飛書開放プラットフォーム](https://open.feishu.cn/) にアクセス
* 企業カスタムアプリを作成
* **App ID** と **App Secret** を取得
* [飛書開放プラットフォーム](https://open.feishu.cn/) にアクセスしてアプリケーションを作成
* アプリ設定で **ボット** 機能を有効化
* バージョンを作成してアプリを公開（アプリは公開しないと有効になりません）
* **App ID**（`cli_` で始まる）と **App Secret** をコピー
**2. 設定**
@@ -396,21 +413,25 @@ picoclaw gateway
"feishu": {
"enabled": true,
"app_id": "cli_xxx",
"app_secret": "xxx",
"encrypt_key": "",
"verification_token": "",
"app_secret": "YOUR_APP_SECRET",
"allow_from": []
}
}
}
```
**3. 実行**
オプション：`encrypt_key` と `verification_token` でイベント暗号化（本番環境推奨）。
**3. 実行してチャット**
```bash
picoclaw gateway
```
飛書を開き、ボット名を検索してチャットを開始できます。ボットをグループに追加することもできます — `group_trigger.mention_only: true` を設定すると @メンション時のみ応答します。
詳細なオプションについては [飛書チャネル設定ガイド](../channels/feishu/README.ja.md) を参照してください。
</details>
<details>
@@ -422,7 +443,7 @@ PicoClaw は 3 種類の WeCom 統合をサポートしています：
**方式 2: カスタムアプリ (App)** — より多機能、プロアクティブメッセージング、プライベートチャットのみ
**方式 3: AI Bot** — 公式 AI Bot、ストリーミング返信、グループ・プライベートチャット対応
詳細なセットアップ手順は [WeCom AI Bot 設定ガイド](../channels/wecom/wecom_aibot/README.zh.md) を参照してください。
詳細なセットアップ手順は [WeCom AI Bot 設定ガイド](../channels/wecom/wecom_aibot/README.ja.md) を参照してください。
**クイックセットアップ — グループ Bot：**
@@ -496,7 +517,7 @@ picoclaw gateway
**1. AI Bot を作成**
* WeCom 管理コンソール → アプリ管理 → AI Bot
* AI Bot 設定でコールバック URL を設定：`http://your-server:18791/webhook/wecom-aibot`
* AI Bot 設定でコールバック URL を設定：`http://your-server:18790/webhook/wecom-aibot`
* **Token** をコピーし、「ランダム生成」をクリックして **EncodingAESKey** を取得
**2. 設定**
@@ -528,24 +549,36 @@ picoclaw gateway
</details>
<details>
<summary><b>OneBot</b></summary>
<summary><b>OneBot（OneBot プロトコル経由の QQ）</b></summary>
**1. 設定**
OneBot は QQ ボット向けのオープンプロトコルです。PicoClaw は OneBot v11 互換の実装（例：[Lagrange](https://github.com/LagrangeDev/Lagrange.Core)、[NapCat](https://github.com/NapNeko/NapCatQQ)）に WebSocket で接続します。
NapCat / Go-CQHTTP などの OneBot 実装と互換性があります。
**1. OneBot 実装をセットアップ**
OneBot v11 互換の QQ ボットフレームワークをインストールして実行します。WebSocket サーバーを有効にしてください。
**2. 設定**
```json
{
"channels": {
"onebot": {
"enabled": true,
"ws_url": "ws://127.0.0.1:8080",
"access_token": "",
"allow_from": []
}
}
}
```
**2. 実行**
| フィールド | 説明 |
|-------|-------------|
| `ws_url` | OneBot 実装の WebSocket URL |
| `access_token` | 認証用アクセストークン（OneBot 側で設定している場合） |
| `reconnect_interval` | 再接続間隔（秒）（デフォルト：5） |
**3. 実行**
```bash
picoclaw gateway
docs/ja/configuration.md
+1 -1
View File
@@ -57,7 +57,7 @@ PicoClaw は設定されたワークスペース（デフォルト: `~/.picoclaw
1. `~/.picoclaw/workspace/skills`（ワークスペース）
2. `~/.picoclaw/skills`（グローバル）
3. `<current-working-directory>/skills`（ビルトイン）
3. `<ビルド時埋め込みパス>/skills`（ビルトイン）
高度な/テスト用セットアップでは、以下の環境変数でビルトインスキルのルートを上書きできます：
docs/ja/credential_encryption.md
+158
View File
@@ -0,0 +1,158 @@
> [README](../../README.ja.md) に戻る
# クレデンシャル暗号化
PicoClaw は `model_list` 設定エントリの `api_key` 値の暗号化をサポートしています。
暗号化されたキーは `enc://<base64>` 文字列として保存され、起動時に自動的に復号されます。
---
## クイックスタート
**1. パスフレーズを設定する**
```bash
export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
```
**2. API キーを暗号化する**
`picoclaw onboard` を実行します — パスフレーズの入力を求められ、SSH キーが生成されます。
その後、次の `SaveConfig` 呼び出し時に、設定内のすべての平文 `api_key` エントリが自動的に再暗号化されます。生成される `enc://` 値は以下のようになります：
```
enc://AAAA...base64...
```
**3. 出力を設定に貼り付ける**
```json
{
"model_list": [
{
"model_name": "gpt-4o",
"model": "openai/gpt-4o",
"api_key": "enc://AAAA...base64...",
"api_base": "https://api.openai.com/v1"
}
]
}
```
---
## サポートされる `api_key` 形式
| 形式 | 例 | 動作 |
|------|---|------|
| 平文 | `sk-abc123` | そのまま使用 |
| ファイル参照 | `file://openai.key` | 設定ファイルと同じディレクトリから内容を読み取り |
| 暗号化 | `enc://<base64>` | 起動時に `PICOCLAW_KEY_PASSPHRASE` を使用して復号 |
| 空 | `""` | そのまま渡される（`auth_method: oauth` で使用） |
---
## 暗号設計
### 鍵導出
暗号化には **HKDF-SHA256** を使用し、SSH 秘密鍵を第二要素とします。
```
sshHash = SHA256(ssh_private_key_file_bytes)
ikm = HMAC-SHA256(key=sshHash, message=passphrase)
aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
```
### 暗号化
```
AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
```
### ワイヤーフォーマット
```
enc://<base64( salt[16] + nonce[12] + ciphertext )>
```
| フィールド | サイズ | 説明 |
|-----------|--------|------|
| `salt` | 16 バイト | 暗号化ごとにランダム生成；HKDF に入力 |
| `nonce` | 12 バイト | 暗号化ごとにランダム生成；AES-GCM IV |
| `ciphertext` | 可変 | AES-256-GCM 暗号文 + 16 バイト認証タグ |
GCM 認証タグは暗号文に自動的に付加されます。改ざんがあった場合、破損した平文を返すのではなく、エラーで復号が失敗します。
### パフォーマンス
| 操作 | 所要時間 (ARM Cortex-A) |
|------|------------------------|
| 鍵導出 (HKDF) | < 1 ms |
| AES-256-GCM 復号 | < 1 ms |
| **起動時の総オーバーヘッド** | **キーあたり < 2 ms** |
---
## SSH キーによる二要素セキュリティ
SSH 秘密鍵が提供されている場合、暗号を破るには**両方**が必要です：
1. **パスフレーズ** (`PICOCLAW_KEY_PASSPHRASE`)
2. **SSH 秘密鍵ファイル**
これは、設定ファイルが漏洩しただけでは、パスフレーズが弱い場合でも API キーを復元できないことを意味します。SSH キーはパスフレーズの強度に関係なく、256 ビットのエントロピー（Ed25519）を提供します。
### 脅威モデル
| 攻撃者が持っているもの | 復号可能か？ |
|----------------------|-------------|
| 設定ファイルのみ | いいえ — パスフレーズ + SSH キーが必要 |
| SSH キーのみ | いいえ — パスフレーズが必要 |
| パスフレーズのみ | いいえ — SSH キーが必要 |
| 設定ファイル + SSH キー + パスフレーズ | はい — 完全な侵害 |
---
## 環境変数
| 変数 | 必須 | 説明 |
|------|------|------|
| `PICOCLAW_KEY_PASSPHRASE` | はい（`enc://` 使用時） | 鍵導出に使用するパスフレーズ |
| `PICOCLAW_SSH_KEY_PATH` | いいえ | SSH 秘密鍵のパス。未設定の場合、`~/.ssh/picoclaw_ed25519.key` から自動検出 |
### SSH キーの自動検出
`PICOCLAW_SSH_KEY_PATH` が設定されていない場合、PicoClaw は専用キーを探します：
```
~/.ssh/picoclaw_ed25519.key
```
この専用ファイルにより、ユーザーの既存の SSH キーとの競合を回避します。
`picoclaw onboard` を実行すると自動的に生成されます。
`os.UserHomeDir()` はクロスプラットフォームのホームディレクトリ解決に使用されます（Windows では `USERPROFILE`、Unix/macOS では `HOME` を読み取ります）。
> **注意：** SSH キーファイルはクレデンシャル暗号化に必須です。キーが見つからず `PICOCLAW_SSH_KEY_PATH` も設定されていない場合、暗号化/復号は失敗します。`picoclaw onboard` を実行してキーを自動生成してください。
---
## 移行
唯一の秘密情報は `PICOCLAW_KEY_PASSPHRASE` と SSH 秘密鍵ファイルであるため、移行は簡単です：
1. 設定ファイルを新しいマシンにコピーします。
2. `PICOCLAW_KEY_PASSPHRASE` を同じ値に設定します。
3. SSH 秘密鍵ファイルを同じパスにコピーします（または `PICOCLAW_SSH_KEY_PATH` を新しい場所に設定します）。
再暗号化は不要です。
---
## セキュリティに関する考慮事項
- **パスフレーズと SSH キーの両方が必須です。** SSH キーは第二要素として機能します — これがなければ暗号化/復号は失敗します。キーが存在しない場合は `picoclaw onboard` を実行して生成してください。
- **SSH キーは実行時に読み取り専用です。** PicoClaw は SSH キーファイルへの書き込みや変更を行いません。
- **平文キーは引き続きサポートされます。** `enc://` を使用しない既存の設定は影響を受けません。
- **`enc://` 形式はバージョン管理されています。** HKDF `info` フィールド（`picoclaw-credential-v1`）により、既存の暗号化値を壊すことなく将来のアルゴリズムアップグレードが可能です。
docs/ja/debug.md
+36
View File
@@ -0,0 +1,36 @@
# PicoClaw のデバッグ
> [README](../../README.ja.md) に戻る
PicoClaw は、受信するすべてのリクエストに対して、メッセージのルーティングや複雑度の評価、ツールの実行、モデル障害への適応など、多くの複雑な処理をバックグラウンドで実行しています。何が起きているかを正確に把握できることは、潜在的な問題のトラブルシューティングだけでなく、エージェントの動作を真に理解するためにも非常に重要です。
## デバッグモードで PicoClaw を起動する
エージェントの動作に関する詳細情報（LLM リクエスト、ツール呼び出し、メッセージルーティング）を取得するには、デバッグフラグを付けて PicoClaw ゲートウェイを起動します：
```bash
picoclaw gateway --debug
# or
picoclaw gateway -d
```
このモードでは、システムがログを詳細にフォーマットし、システムプロンプトやツール実行結果のプレビューを表示します。
## ログの切り詰めを無効にする（完全なログ）
デフォルトでは、PicoClaw はコンソールの可読性を保つために、デバッグログ内の非常に長い文字列（*システムプロンプト*や大きな JSON 出力結果など）を切り詰めます。
コマンドの完全な出力や、LLM モデルに送信された正確なペイロードを確認する必要がある場合は、`--no-truncate` フラグを使用できます。
**注意：** このフラグは `--debug` モードと組み合わせた場合に*のみ*機能します。
```bash
picoclaw gateway --debug --no-truncate
```
このフラグが有効な場合、グローバルな切り詰め機能が無効になります。これは以下の場合に非常に便利です：
* プロバイダーに送信されるメッセージの正確な構文を確認する。
* `exec`、`web_fetch`、`read_file` などのツールの完全な出力を読む。
* メモリに保存されたセッション履歴をデバッグする。
docs/ja/docker.md
+1
View File
@@ -12,6 +12,7 @@ git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
# 2. 初回実行 — docker/data/config.json を自動生成して終了
# （config.json と workspace/ の両方が存在しない場合のみ実行）
docker compose -f docker/docker-compose.yml --profile gateway up
# コンテナが "First-run setup complete." と表示して停止します
docs/ja/hardware-compatibility.md
+152
View File
@@ -0,0 +1,152 @@
> [README](../../README.ja.md) に戻る
# 🖥️ PicoClaw ハードウェア互換性リスト
PicoClaw はほぼすべての Linux デバイスで動作します。このページでは、検証済みのチップ、製品、開発ボードを記録しています。
**お使いのハードウェアがリストにない場合は？** PR を送信して追加してください！ハードウェアベンダーの貢献と共同プロモーションを歓迎します。
---
## 1. 検証済みチップサポート
### x86
| ベンダー | チップ | 備考 |
|----------|--------|------|
| Intel | Any x86 CPU (i386+) | すべてのデスクトップ/サーバー/ノートPC プロセッサ |
| AMD | Any x86 CPU | すべてのデスクトップ/サーバー/ノートPC プロセッサ |
### ARM
| サブアーキテクチャ | 代表的なチップ | 備考 |
|--------------------|----------------|------|
| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | シングルコア ARM1176JZF-S |
| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | シングルコア Cortex-A7、LicheePi Zero で使用 |
| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | クアッドコア Cortex-A53、Orange Pi Zero 3 で使用 |
| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | クアッドコア Cortex-A72 |
| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | クアッドコア Cortex-A76 |
| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | デュアルコア Cortex-A53 + NPU、NanoKVM-Pro / MaixCAM2 で使用 |
### RISC-V (riscv64)
| ベンダー | チップ | コア | 備考 |
|----------|--------|------|------|
| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 オンチップ、LicheeRV-Nano / NanoKVM / MaixCAM で使用 |
| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L オンチップ、1 TOPS NPU、4K AI カメラ SiP |
| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | RISC-V AI カメラシリーズ |
| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | HaaS506-LD1 産業用 RTU で使用 |
| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | Milk-V Jupiter, BananaPi BPI-F3 で使用 |
| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | RVA23 準拠、1024 ビット RVV、FP8 AI 推論 |
| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8 コア、16MB L3 キャッシュ、デスクトップクラス |
| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU、CanMV-K230 で使用 |
### MIPS
| ベンダー | チップ | 備考 |
|----------|--------|------|
| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz、多くの OpenWrt ルーターで使用（例：Xiaomi Router 3G） |
### LoongArch (loong64)
| ベンダー | チップ | 備考 |
|----------|--------|------|
| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | クアッドコア LA464 @ 2.5GHz、デスクトップ/ワークステーション |
| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | クアッドコア 4C/8T @ 2.5GHz、IPC は Intel 第10世代に匹敵 |
| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | デュアルコア @ 1GHz、産業/IoT アプリケーション |
---
## 2. 検証済み製品（発売日順）
PicoClaw でテスト済みのコンシューマー製品、ルーター、産業用デバイス。
| 年 | 製品 | アーキテクチャ | SoC | RAM | カテゴリ |
|----|------|----------------|-----|-----|----------|
| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | スマートフォン |
| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | タブレット |
| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | ルーター (OpenWrt) |
| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | TV ボックス / ホームサーバー |
| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | スマートスピーカー |
| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | 産業用 RTU |
| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | プロ IP-KVM |
| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | 4K AI カメラ |
---
## 3. 検証済み開発ボード（発売日順）
| 年 | ボード | アーキテクチャ | SoC | RAM | 購入リンク |
|----|--------|----------------|-----|-----|------------|
| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
---
## 4. その他の対応環境
### Android スマートフォン（Termux 経由）
1GB 以上の RAM を搭載した ARM64 Android スマートフォン（2015年以降）。[Termux](https://github.com/termux/termux-app) をインストールし、`proot` を使用して PicoClaw を実行します。
> セットアップ手順は [README：古い Android スマートフォンで実行](../../README.ja.md#-run-on-old-android-phones) を参照してください。
### デスクトップ / サーバー / クラウド
| プラットフォーム | 備考 |
|------------------|------|
| x86_64 Linux | ネイティブバイナリ、依存関係なし |
| x86_64 Windows | ネイティブバイナリ |
| macOS (Intel / Apple Silicon) | ネイティブバイナリ |
| Docker (any platform) | `docker compose` ワンライナー、[Docker ガイド](docker.md) を参照 |
| OpenWrt routers | MIPS/ARM ビルド、32MB 以上の空きメモリが必要 |
| FreeBSD / NetBSD | x86_64 および arm64 ビルドが利用可能 |
---
## 5. 最小要件
| リソース | 最小 | 推奨 |
|----------|------|------|
| RAM | 10MB 空き | 32MB 以上空き |
| ストレージ | 20MB（バイナリ） | 50MB 以上（ワークスペース含む） |
| CPU | 任意（シングルコア 0.6GHz 以上） | — |
| OS | Linux (kernel 3.x+) | Linux 5.x+ |
| ネットワーク | 必須（LLM API 呼び出し用） | イーサネットまたは WiFi |
---
## 6. テストと貢献の方法
```bash
# 1. お使いのアーキテクチャ向けをダウンロード
wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
tar xzf picoclaw_Linux_arm64.tar.gz
# 2. 初期化
./picoclaw onboard
# 3. テスト
./picoclaw agent -m "Hello, what board am I running on?"
```
利用可能なビルド：`linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
### ハードウェアを追加する
1. このリポジトリをフォーク
2. 該当するテーブルにチップ/製品/ボードを追加
3. 名前、アーキテクチャ、SoC、RAM、年、リンク（あれば）を含める
4. PR を送信
ハードウェアベンダーの方へ：公式サポートの追加や共同プロモーションをご希望ですか？Issue を作成するか、[Discord](https://discord.gg/V4sAZ9XWpN) でお問い合わせください。
docs/ja/providers.md
+5 -6
View File
@@ -93,7 +93,7 @@
],
"agents": {
"defaults": {
"model": "gpt-5.4"
"model_name": "gpt-5.4"
}
}
}
@@ -266,7 +266,7 @@ PicoClaw はリクエスト送信前に外側の `litellm/` プレフィック
],
"agents": {
"defaults": {
"model": "glm-4.7"
"model_name": "glm-4.7"
}
}
}
@@ -298,7 +298,7 @@ PicoClaw はプロトコルファミリーごとに Provider をルーティン
"agents": {
"defaults": {
"workspace": "~/.picoclaw/workspace",
"model": "glm-4.7",
"model_name": "glm-4.7",
"max_tokens": 8192,
"temperature": 0.7,
"max_tool_iterations": 20
@@ -328,12 +328,11 @@ picoclaw agent -m "こんにちは"
{
"agents": {
"defaults": {
"model": "anthropic/claude-opus-4-5"
"model_name": "anthropic/claude-opus-4-5"
}
},
"session": {
"dm_scope": "per-channel-peer",
"backlog_limit": 20
"dm_scope": "per-channel-peer"
},
"providers": {
"openrouter": {
docs/ja/troubleshooting.md
+2 -2
View File
@@ -16,7 +16,7 @@
**修正方法：** `~/.picoclaw/config.json`（またはお使いの設定パス）で：
1. **agents.defaults.model** は `model_list` 内の `model_name` と一致する必要があります（例：`"openrouter-free"`）。
1. **agents.defaults.model_name** は `model_list` 内の `model_name` と一致する必要があります（例：`"openrouter-free"`）。
2. そのエントリの **model** は有効な OpenRouter モデル ID である必要があります。例：
- `"openrouter/free"` – 自動無料枠
- `"google/gemini-2.0-flash-exp:free"`
@@ -28,7 +28,7 @@
{
"agents": {
"defaults": {
"model": "openrouter-free"
"model_name": "openrouter-free"
}
},
"model_list": [
docs/migration/model-list-migration.md
+3 -3
View File
@@ -70,7 +70,7 @@ The new `model_list` configuration offers several advantages:
],
"agents": {
"defaults": {
"model": "gpt4"
"model_name": "gpt4"
}
}
}
@@ -184,7 +184,7 @@ During the migration period, your existing `providers` configuration will contin
- [ ] Identify all providers you're currently using
- [ ] Create `model_list` entries for each provider
- [ ] Use appropriate protocol prefixes
- [ ] Update `agents.defaults.model` to reference the new `model_name`
- [ ] Update `agents.defaults.model_name` to reference the new `model_name`
- [ ] Test that all models work correctly
- [ ] Remove or comment out the old `providers` section
@@ -196,7 +196,7 @@ During the migration period, your existing `providers` configuration will contin
model "xxx" not found in model_list or providers
```
**Solution**: Ensure the `model_name` in `model_list` matches the value in `agents.defaults.model`.
**Solution**: Ensure the `model_name` in `model_list` matches the value in `agents.defaults.model_name`.
### Unknown protocol error

Some files were not shown because too many files have changed in this diff Show More