feat(wecom): update WeCom AI Bot setup instructions and configuration parameters
This commit is contained in:
Zhang Rui
parent
ed810259eb
commit
47d576786e
2 changed files with 512 additions and 67 deletions
513
README.md
513
README.md
|
|
@ -191,15 +191,510 @@ make install
|
||||||
|
|
||||||
For detailed guides, see the docs below. The README covers quick start only.
|
For detailed guides, see the docs below. The README covers quick start only.
|
||||||
|
|
||||||
| Topic | Description |
|
```bash
|
||||||
|-------|-------------|
|
# 1. Clone this repo
|
||||||
| 🐳 [Docker & Quick Start](docs/docker.md) | Docker Compose setup, Launcher/Agent modes, Quick Start configuration |
|
git clone https://github.com/sipeed/picoclaw.git
|
||||||
| 💬 [Chat Apps](docs/chat-apps.md) | Telegram, Discord, WhatsApp, Matrix, QQ, Slack, IRC, DingTalk, LINE, Feishu, WeCom, and more |
|
cd picoclaw
|
||||||
| ⚙️ [Configuration](docs/configuration.md) | Environment variables, workspace layout, skill sources, security sandbox, heartbeat |
|
|
||||||
| 🔌 [Providers & Models](docs/providers.md) | 20+ LLM providers, model routing, model_list configuration, provider architecture |
|
# 2. First run — auto-generates docker/data/config.json then exits
|
||||||
| 🔄 [Spawn & Async Tasks](docs/spawn-tasks.md) | Quick tasks, long tasks with spawn, async sub-agent orchestration |
|
docker compose -f docker/docker-compose.yml --profile gateway up
|
||||||
| 🐛 [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
|
# The container prints "First-run setup complete." and stops.
|
||||||
| 🔧 [Tools Configuration](docs/tools_configuration.md) | Per-tool enable/disable, exec policies |
|
|
||||||
|
# 3. Set your API keys
|
||||||
|
vim docker/data/config.json # Set provider API keys, bot tokens, etc.
|
||||||
|
|
||||||
|
# 4. Start
|
||||||
|
docker compose -f docker/docker-compose.yml --profile gateway up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
> [!TIP]
|
||||||
|
> **Docker Users**: By default, the Gateway listens on `127.0.0.1` which is not accessible from the host. If you need to access the health endpoints or expose ports, set `PICOCLAW_GATEWAY_HOST=0.0.0.0` in your environment or update `config.json`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 5. Check logs
|
||||||
|
docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
|
||||||
|
|
||||||
|
# 6. Stop
|
||||||
|
docker compose -f docker/docker-compose.yml --profile gateway down
|
||||||
|
```
|
||||||
|
|
||||||
|
### Launcher Mode (Web Console)
|
||||||
|
|
||||||
|
The `launcher` image includes all three binaries (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) and starts the web console by default, which provides a browser-based UI for configuration and chat.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose -f docker/docker-compose.yml --profile launcher up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
Open http://localhost:18800 in your browser. The launcher manages the gateway process automatically.
|
||||||
|
|
||||||
|
> [!WARNING]
|
||||||
|
> The web console does not yet support authentication. Avoid exposing it to the public internet.
|
||||||
|
|
||||||
|
### Agent Mode (One-shot)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Ask a question
|
||||||
|
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
|
||||||
|
|
||||||
|
# Interactive mode
|
||||||
|
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
|
||||||
|
```
|
||||||
|
|
||||||
|
### Update
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose -f docker/docker-compose.yml pull
|
||||||
|
docker compose -f docker/docker-compose.yml --profile gateway up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🚀 Quick Start
|
||||||
|
|
||||||
|
> [!TIP]
|
||||||
|
> Set your API Key in `~/.picoclaw/config.json`. Get API Keys: [Volcengine (CodingPlan)](https://console.volcengine.com) (LLM) · [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM). Web search is optional — get a free [Tavily API](https://tavily.com) (1000 free queries/month) or [Brave Search API](https://brave.com/search/api) (2000 free queries/month).
|
||||||
|
|
||||||
|
**1. Initialize**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
picoclaw onboard
|
||||||
|
```
|
||||||
|
|
||||||
|
**2. Configure** (`~/.picoclaw/config.json`)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agents": {
|
||||||
|
"defaults": {
|
||||||
|
"workspace": "~/.picoclaw/workspace",
|
||||||
|
"model_name": "gpt-5.4",
|
||||||
|
"max_tokens": 8192,
|
||||||
|
"temperature": 0.7,
|
||||||
|
"max_tool_iterations": 20
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"model_list": [
|
||||||
|
{
|
||||||
|
"model_name": "ark-code-latest",
|
||||||
|
"model": "volcengine/ark-code-latest",
|
||||||
|
"api_key": "sk-your-api-key"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"model_name": "gpt-5.4",
|
||||||
|
"model": "openai/gpt-5.4",
|
||||||
|
"api_key": "your-api-key",
|
||||||
|
"request_timeout": 300
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"model_name": "claude-sonnet-4.6",
|
||||||
|
"model": "anthropic/claude-sonnet-4.6",
|
||||||
|
"api_key": "your-anthropic-key"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"tools": {
|
||||||
|
"web": {
|
||||||
|
"brave": {
|
||||||
|
"enabled": false,
|
||||||
|
"api_key": "YOUR_BRAVE_API_KEY",
|
||||||
|
"max_results": 5
|
||||||
|
},
|
||||||
|
"tavily": {
|
||||||
|
"enabled": false,
|
||||||
|
"api_key": "YOUR_TAVILY_API_KEY",
|
||||||
|
"max_results": 5
|
||||||
|
},
|
||||||
|
"duckduckgo": {
|
||||||
|
"enabled": true,
|
||||||
|
"max_results": 5
|
||||||
|
},
|
||||||
|
"perplexity": {
|
||||||
|
"enabled": false,
|
||||||
|
"api_key": "YOUR_PERPLEXITY_API_KEY",
|
||||||
|
"max_results": 5
|
||||||
|
},
|
||||||
|
"searxng": {
|
||||||
|
"enabled": false,
|
||||||
|
"base_url": "http://your-searxng-instance:8888",
|
||||||
|
"max_results": 5
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> **New**: The `model_list` configuration format allows zero-code provider addition. See [Model Configuration](#model-configuration-model_list) for details.
|
||||||
|
> `request_timeout` is optional and uses seconds. If omitted or set to `<= 0`, PicoClaw uses the default timeout (120s).
|
||||||
|
|
||||||
|
**3. Get API Keys**
|
||||||
|
|
||||||
|
* **LLM Provider**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
|
||||||
|
* **Web Search** (optional):
|
||||||
|
* [Brave Search](https://brave.com/search/api) - Paid ($5/1000 queries, ~$5-6/month)
|
||||||
|
* [Perplexity](https://www.perplexity.ai) - AI-powered search with chat interface
|
||||||
|
* [SearXNG](https://github.com/searxng/searxng) - Self-hosted metasearch engine (free, no API key needed)
|
||||||
|
* [Tavily](https://tavily.com) - Optimized for AI Agents (1000 requests/month)
|
||||||
|
* DuckDuckGo - Built-in fallback (no API key required)
|
||||||
|
|
||||||
|
> **Note**: See `config.example.json` for a complete configuration template.
|
||||||
|
|
||||||
|
**4. Chat**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
picoclaw agent -m "What is 2+2?"
|
||||||
|
```
|
||||||
|
|
||||||
|
That's it! You have a working AI assistant in 2 minutes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💬 Chat Apps
|
||||||
|
|
||||||
|
Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, or WeCom
|
||||||
|
|
||||||
|
> **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) |
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>Telegram</b> (Recommended)</summary>
|
||||||
|
|
||||||
|
**1. Create a bot**
|
||||||
|
|
||||||
|
* Open Telegram, search `@BotFather`
|
||||||
|
* Send `/newbot`, follow prompts
|
||||||
|
* Copy the token
|
||||||
|
|
||||||
|
**2. Configure**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"channels": {
|
||||||
|
"telegram": {
|
||||||
|
"enabled": true,
|
||||||
|
"token": "YOUR_BOT_TOKEN",
|
||||||
|
"allow_from": ["YOUR_USER_ID"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> Get your user ID from `@userinfobot` on Telegram.
|
||||||
|
|
||||||
|
**3. Run**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
picoclaw gateway
|
||||||
|
```
|
||||||
|
|
||||||
|
**4. Telegram command menu (auto-registered at startup)**
|
||||||
|
|
||||||
|
PicoClaw now keeps command definitions in one shared registry. On startup, Telegram will automatically register supported bot commands (for example `/start`, `/help`, `/show`, `/list`) so command menu and runtime behavior stay in sync.
|
||||||
|
Telegram command menu registration remains channel-local discovery UX; generic command execution is handled centrally in the agent loop via the commands executor.
|
||||||
|
|
||||||
|
If command registration fails (network/API transient errors), the channel still starts and PicoClaw retries registration in the background.
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>Discord</b></summary>
|
||||||
|
|
||||||
|
**1. Create a bot**
|
||||||
|
|
||||||
|
* Go to <https://discord.com/developers/applications>
|
||||||
|
* Create an application → Bot → Add Bot
|
||||||
|
* Copy the bot token
|
||||||
|
|
||||||
|
**2. Enable intents**
|
||||||
|
|
||||||
|
* In the Bot settings, enable **MESSAGE CONTENT INTENT**
|
||||||
|
* (Optional) Enable **SERVER MEMBERS INTENT** if you plan to use allow lists based on member data
|
||||||
|
|
||||||
|
**3. Get your User ID**
|
||||||
|
* Discord Settings → Advanced → enable **Developer Mode**
|
||||||
|
* Right-click your avatar → **Copy User ID**
|
||||||
|
|
||||||
|
**4. Configure**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"channels": {
|
||||||
|
"discord": {
|
||||||
|
"enabled": true,
|
||||||
|
"token": "YOUR_BOT_TOKEN",
|
||||||
|
"allow_from": ["YOUR_USER_ID"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**5. Invite the bot**
|
||||||
|
|
||||||
|
* OAuth2 → URL Generator
|
||||||
|
* Scopes: `bot`
|
||||||
|
* Bot Permissions: `Send Messages`, `Read Message History`
|
||||||
|
* Open the generated invite URL and add the bot to your server
|
||||||
|
|
||||||
|
**Optional: Group trigger mode**
|
||||||
|
|
||||||
|
By default the bot responds to all messages in a server channel. To restrict responses to @-mentions only, add:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"channels": {
|
||||||
|
"discord": {
|
||||||
|
"group_trigger": { "mention_only": true }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
You can also trigger by keyword prefixes (e.g. `!bot`):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"channels": {
|
||||||
|
"discord": {
|
||||||
|
"group_trigger": { "prefixes": ["!bot"] }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**6. Run**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
picoclaw gateway
|
||||||
|
```
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>WhatsApp</b> (native via whatsmeow)</summary>
|
||||||
|
|
||||||
|
PicoClaw can connect to WhatsApp in two ways:
|
||||||
|
|
||||||
|
- **Native (recommended):** In-process using [whatsmeow](https://github.com/tulir/whatsmeow). No separate bridge. Set `"use_native": true` and leave `bridge_url` empty. On first run, scan the QR code with WhatsApp (Linked Devices). Session is stored under your workspace (e.g. `workspace/whatsapp/`). The native channel is **optional** to keep the default binary small; build with `-tags whatsapp_native` (e.g. `make build-whatsapp-native` or `go build -tags whatsapp_native ./cmd/...`).
|
||||||
|
- **Bridge:** Connect to an external WebSocket bridge. Set `bridge_url` (e.g. `ws://localhost:3001`) and keep `use_native` false.
|
||||||
|
|
||||||
|
**Configure (native)**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"channels": {
|
||||||
|
"whatsapp": {
|
||||||
|
"enabled": true,
|
||||||
|
"use_native": true,
|
||||||
|
"session_store_path": "",
|
||||||
|
"allow_from": []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
If `session_store_path` is empty, the session is stored in `<workspace>/whatsapp/`. Run `picoclaw gateway`; on first run, scan the QR code printed in the terminal with WhatsApp → Linked Devices.
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>QQ</b></summary>
|
||||||
|
|
||||||
|
**1. Create a bot**
|
||||||
|
|
||||||
|
- Go to [QQ Open Platform](https://q.qq.com/#)
|
||||||
|
- Create an application → Get **AppID** and **AppSecret**
|
||||||
|
|
||||||
|
**2. Configure**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"channels": {
|
||||||
|
"qq": {
|
||||||
|
"enabled": true,
|
||||||
|
"app_id": "YOUR_APP_ID",
|
||||||
|
"app_secret": "YOUR_APP_SECRET",
|
||||||
|
"allow_from": []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access.
|
||||||
|
|
||||||
|
**3. Run**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
picoclaw gateway
|
||||||
|
```
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>DingTalk</b></summary>
|
||||||
|
|
||||||
|
**1. Create a bot**
|
||||||
|
|
||||||
|
* Go to [Open Platform](https://open.dingtalk.com/)
|
||||||
|
* Create an internal app
|
||||||
|
* Copy Client ID and Client Secret
|
||||||
|
|
||||||
|
**2. Configure**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"channels": {
|
||||||
|
"dingtalk": {
|
||||||
|
"enabled": true,
|
||||||
|
"client_id": "YOUR_CLIENT_ID",
|
||||||
|
"client_secret": "YOUR_CLIENT_SECRET",
|
||||||
|
"allow_from": []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> Set `allow_from` to empty to allow all users, or specify DingTalk user IDs to restrict access.
|
||||||
|
|
||||||
|
**3. Run**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
picoclaw gateway
|
||||||
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>Matrix</b></summary>
|
||||||
|
|
||||||
|
**1. Prepare bot account**
|
||||||
|
|
||||||
|
* Use your preferred homeserver (e.g. `https://matrix.org` or self-hosted)
|
||||||
|
* Create a bot user and obtain its access token
|
||||||
|
|
||||||
|
**2. Configure**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"channels": {
|
||||||
|
"matrix": {
|
||||||
|
"enabled": true,
|
||||||
|
"homeserver": "https://matrix.org",
|
||||||
|
"user_id": "@your-bot:matrix.org",
|
||||||
|
"access_token": "YOUR_MATRIX_ACCESS_TOKEN",
|
||||||
|
"allow_from": []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**3. Run**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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).
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>LINE</b></summary>
|
||||||
|
|
||||||
|
**1. Create a LINE Official Account**
|
||||||
|
|
||||||
|
- Go to [LINE Developers Console](https://developers.line.biz/)
|
||||||
|
- Create a provider → Create a Messaging API channel
|
||||||
|
- Copy **Channel Secret** and **Channel Access Token**
|
||||||
|
|
||||||
|
**2. Configure**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"channels": {
|
||||||
|
"line": {
|
||||||
|
"enabled": true,
|
||||||
|
"channel_secret": "YOUR_CHANNEL_SECRET",
|
||||||
|
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
|
||||||
|
"webhook_path": "/webhook/line",
|
||||||
|
"allow_from": []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> LINE webhook is served on the shared Gateway server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`).
|
||||||
|
|
||||||
|
**3. Set up Webhook URL**
|
||||||
|
|
||||||
|
LINE requires HTTPS for webhooks. Use a reverse proxy or tunnel:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Example with ngrok (gateway default port is 18790)
|
||||||
|
ngrok http 18790
|
||||||
|
```
|
||||||
|
|
||||||
|
Then set the Webhook URL in LINE Developers Console to `https://your-domain/webhook/line` and enable **Use webhook**.
|
||||||
|
|
||||||
|
**4. Run**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
picoclaw gateway
|
||||||
|
```
|
||||||
|
|
||||||
|
> In group chats, the bot responds only when @mentioned. Replies quote the original message.
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>WeCom (企业微信)</b></summary>
|
||||||
|
|
||||||
|
PicoClaw supports three types of WeCom integration:
|
||||||
|
|
||||||
|
**Option 1: WeCom Bot (Bot)** - Easier setup, supports group chats
|
||||||
|
**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.
|
||||||
|
|
||||||
|
**Quick Setup - WeCom AI Bot:**
|
||||||
|
|
||||||
|
**1. Create an AI Bot**
|
||||||
|
|
||||||
|
* Go to WeCom Admin Console → AI Bot
|
||||||
|
* Create a new AI Bot → Set name, avatar, etc.
|
||||||
|
* Copy **Bot ID** and **Secret**
|
||||||
|
|
||||||
|
**2. Configure**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"channels": {
|
||||||
|
"wecom_aibot": {
|
||||||
|
"enabled": true,
|
||||||
|
"bot_id": "YOUR_BOT_ID",
|
||||||
|
"secret": "YOUR_SECRET",
|
||||||
|
"allow_from": [],
|
||||||
|
"welcome_message": "Hello! How can I help you?"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**3. Run**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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>
|
||||||
|
|
||||||
## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Join the Agent Social Network
|
## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Join the Agent Social Network
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
# 企业微信智能机器人 (AI Bot)
|
# 企业微信智能机器人 (AI Bot)
|
||||||
|
|
||||||
企业微信智能机器人（AI Bot）是企业微信官方提供的 AI 对话接入方式，支持私聊与群聊，内置流式响应协议，并支持超时后通过 `response_url` 主动推送最终回复。
|
企业微信智能机器人（AI Bot）是企业微信官方提供的 AI 对话接入方式，支持私聊与群聊，内置流式响应协议。
|
||||||
|
|
||||||
## 与其他 WeCom 通道的对比
|
## 与其他 WeCom 通道的对比
|
||||||
|
|
||||||
|
|
@ -19,9 +19,8 @@
|
||||||
"channels": {
|
"channels": {
|
||||||
"wecom_aibot": {
|
"wecom_aibot": {
|
||||||
"enabled": true,
|
"enabled": true,
|
||||||
"token": "YOUR_TOKEN",
|
"bot_id": "YOUR_BOT_ID",
|
||||||
"encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
|
"secret": "YOUR_SECRET",
|
||||||
"webhook_path": "/webhook/wecom-aibot",
|
|
||||||
"allow_from": [],
|
"allow_from": [],
|
||||||
"welcome_message": "你好！有什么可以帮助你的吗？",
|
"welcome_message": "你好！有什么可以帮助你的吗？",
|
||||||
"max_steps": 10
|
"max_steps": 10
|
||||||
|
|
@ -32,9 +31,8 @@
|
||||||
|
|
||||||
| 字段 | 类型 | 必填 | 描述 |
|
| 字段 | 类型 | 必填 | 描述 |
|
||||||
| ---------------- | ------ | ---- | -------------------------------------------------- |
|
| ---------------- | ------ | ---- | -------------------------------------------------- |
|
||||||
| token | string | 是 | 回调验证令牌，在 AI Bot 管理页面配置 |
|
| bot_id | string | 是 | AI Bot 的唯一标识，在 AI Bot 管理页面配置 |
|
||||||
| encoding_aes_key | string | 是 | 43 字符 AES 密钥，在 AI Bot 管理页面随机生成 |
|
| secret | string | 是 | AI Bot 的密钥，在 AI Bot 管理页面配置 |
|
||||||
| webhook_path | string | 否 | Webhook 路径（默认：/webhook/wecom-aibot） |
|
|
||||||
| allow_from | array | 否 | 用户 ID 白名单，空数组表示允许所有用户 |
|
| allow_from | array | 否 | 用户 ID 白名单，空数组表示允许所有用户 |
|
||||||
| welcome_message | string | 否 | 用户进入聊天时发送的欢迎语，留空则不发送 |
|
| welcome_message | string | 否 | 用户进入聊天时发送的欢迎语，留空则不发送 |
|
||||||
| reply_timeout | int | 否 | 回复超时时间（秒，默认：5） |
|
| reply_timeout | int | 否 | 回复超时时间（秒，默认：5） |
|
||||||
|
|
@ -44,42 +42,8 @@
|
||||||
|
|
||||||
1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin)
|
1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin)
|
||||||
2. 进入"应用管理" → "智能机器人"，创建或选择一个 AI Bot
|
2. 进入"应用管理" → "智能机器人"，创建或选择一个 AI Bot
|
||||||
3. 在 AI Bot 配置页面，填写"消息接收"信息：
|
3. 在 AI Bot 配置页面，配置Bot的名称、头像等信息，获取 `Bot ID` 和 `Secret`
|
||||||
- **URL**：`http://<your-server-ip>:18791/webhook/wecom-aibot`
|
4. 在 PicoClaw 配置文件中添加上述配置，重启 PicoClaw
|
||||||
- **Token**：随机生成或自定义
|
|
||||||
- **EncodingAESKey**：点击"随机生成"，得到 43 字符密钥
|
|
||||||
4. 将 Token 和 EncodingAESKey 填入 PicoClaw 配置文件，启动服务后回到管理后台保存（企业微信会发送验证请求）
|
|
||||||
|
|
||||||
> [!TIP]
|
|
||||||
> 服务器需要能被企业微信服务器访问。如在内网/本地开发，可使用 [ngrok](https://ngrok.com) 或 frp 做内网穿透。
|
|
||||||
|
|
||||||
## 流式响应协议
|
|
||||||
|
|
||||||
WeCom AI Bot 使用"流式拉取"协议，区别于普通 Webhook 的一次性回复：
|
|
||||||
|
|
||||||
```
|
|
||||||
用户发消息
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
PicoClaw 立即返回 {finish: false}（Agent 开始处理）
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
企业微信每隔约 1 秒拉取一次 {msgtype: "stream", stream: {id: "..."}}
|
|
||||||
│
|
|
||||||
├─ Agent 未完成 → 返回 {finish: false}（继续等待）
|
|
||||||
│
|
|
||||||
└─ Agent 完成 → 返回 {finish: true, content: "回答内容"}
|
|
||||||
```
|
|
||||||
|
|
||||||
**超时处理**（任务超过 30 秒）：
|
|
||||||
|
|
||||||
若 Agent 处理时间超过约 30 秒（企业微信最大轮询窗口为 6 分钟），PicoClaw 会：
|
|
||||||
|
|
||||||
1. 立即关闭流，向用户显示「⏳ 正在处理中，请稍候，结果将稍后发送。」
|
|
||||||
2. Agent 继续在后台运行
|
|
||||||
3. Agent 完成后，通过消息中携带的 `response_url` 将最终回复主动推送给用户
|
|
||||||
|
|
||||||
> `response_url` 由企业微信颁发，有效期 1 小时，只可使用一次，无需加密，直接 POST markdown 消息体即可。
|
|
||||||
|
|
||||||
## 欢迎语
|
## 欢迎语
|
||||||
|
|
||||||
|
|
@ -91,26 +55,12 @@ PicoClaw 立即返回 {finish: false}（Agent 开始处理）
|
||||||
|
|
||||||
## 常见问题
|
## 常见问题
|
||||||
|
|
||||||
### 回调 URL 验证失败
|
|
||||||
|
|
||||||
- 确认服务器防火墙已开放对应端口（默认 18791）
|
|
||||||
- 确认 `token` 与 `encoding_aes_key` 填写正确
|
|
||||||
- 检查 PicoClaw 日志是否收到了来自企业微信的 GET 请求
|
|
||||||
|
|
||||||
### 消息没有回复
|
### 消息没有回复
|
||||||
|
|
||||||
- 检查 `allow_from` 是否意外限制了发送者
|
- 检查 `allow_from` 是否意外限制了发送者
|
||||||
- 查看日志中是否出现 `context canceled` 或 Agent 错误
|
- 查看日志中是否出现 `context canceled` 或 Agent 错误
|
||||||
- 确认 Agent 配置（`model_name` 等）正确
|
- 确认 Agent 配置（`model_name` 等）正确
|
||||||
|
|
||||||
### 超长任务没有收到最终推送
|
|
||||||
|
|
||||||
- 确认消息回调中携带了 `response_url`（仅企业微信新版 AI Bot 支持）
|
|
||||||
- 确认服务器能主动访问外网（需向 `response_url` POST 请求）
|
|
||||||
- 查看日志关键词 `response_url mode` 和 `Sending reply via response_url`
|
|
||||||
|
|
||||||
## 参考文档
|
## 参考文档
|
||||||
|
|
||||||
- [企业微信 AI Bot 接入文档](https://developer.work.weixin.qq.com/document/path/100719)
|
- [企业微信 AI Bot 接入文档](https://developer.work.weixin.qq.com/document/path/101463)
|
||||||
- [流式响应协议说明](https://developer.work.weixin.qq.com/document/path/100719)
|
|
||||||
- [response_url 主动回复](https://developer.work.weixin.qq.com/document/path/101138)
|
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue