Skip to content

README.md

Latest commit

 

History

History
148 lines (106 loc) · 5.59 KB

README.md

File metadata and controls

148 lines (106 loc) · 5.59 KB

Back to README

WeCom

PicoClaw exposes WeCom as a single channels.wecom channel built on the official WeCom AI Bot WebSocket API. This replaces the legacy wecom, wecom_app, and wecom_aibot split with one unified configuration model.

No public webhook callback URL is required. PicoClaw opens an outbound WebSocket connection to WeCom.

What This Channel Supports

  • Direct chat and group chat delivery
  • Channel-side streaming replies over WeCom's AI Bot protocol
  • Incoming text, voice, image, file, video, and mixed messages
  • Outbound text and media replies (image, file, voice, video)
  • QR-based onboarding via Web UI or CLI
  • Shared allowlist and reasoning_channel_id routing

Quick Start

Option 1: Web UI QR Binding (Recommended)

Open the Web UI, navigate to Channels → WeCom, and click the QR binding button. Scan the QR code with WeCom and confirm in the app — credentials are saved automatically.

WeCom QR binding in Web UI

Option 2: CLI QR Login

Run:

picoclaw auth wecom

The command:

  1. Requests a QR code from WeCom and prints it in the terminal
  2. Also prints a QR Code Link you can open in a browser if the terminal QR is hard to scan
  3. Polls for confirmation — after scanning, you must also confirm the login inside the WeCom app
  4. On success, writes bot_id and secret into channels.wecom and saves the config

The default timeout is 5 minutes. Use --timeout to extend it:

picoclaw auth wecom --timeout 10m

⚠️ Scanning the QR code is not enough — you must also tap Confirm inside the WeCom app, otherwise the command will time out.

Option 3: Configure Manually

If you already have a bot_id and secret from the WeCom AI Bot platform, configure directly:

{
  "channels": {
    "wecom": {
      "enabled": true,
      "bot_id": "YOUR_BOT_ID",
      "secret": "YOUR_SECRET",
      "websocket_url": "wss://openws.work.weixin.qq.com",
      "send_thinking_message": true,
      "allow_from": [],
      "reasoning_channel_id": ""
    }
  }
}

Configuration

Field Type Default Description
enabled bool false Enable the WeCom channel.
bot_id string — WeCom AI Bot identifier. Required when enabled.
secret string — WeCom AI Bot secret. Stored encrypted in .security.yml. Required when enabled.
websocket_url string wss://openws.work.weixin.qq.com WeCom WebSocket endpoint.
send_thinking_message bool true Send a Processing... message before the streamed reply begins.
allow_from array [] Sender allowlist. Empty means allow all senders.
reasoning_channel_id string "" Optional chat ID to route reasoning/thinking output to a separate conversation.

Environment Variables

All fields can be overridden via environment variables with the prefix PICOCLAW_CHANNELS_WECOM_:

Environment Variable Corresponding Field
PICOCLAW_CHANNELS_WECOM_ENABLED enabled
PICOCLAW_CHANNELS_WECOM_BOT_ID bot_id
PICOCLAW_CHANNELS_WECOM_SECRET secret
PICOCLAW_CHANNELS_WECOM_WEBSOCKET_URL websocket_url
PICOCLAW_CHANNELS_WECOM_SEND_THINKING_MESSAGE send_thinking_message
PICOCLAW_CHANNELS_WECOM_ALLOW_FROM allow_from
PICOCLAW_CHANNELS_WECOM_REASONING_CHANNEL_ID reasoning_channel_id

Runtime Behavior

  • PicoClaw maintains an active WeCom turn so streaming replies can continue on the same stream when possible.
  • Streaming replies have a maximum duration of 5.5 minutes and a minimum send interval of 500ms.
  • If streaming is no longer available, replies fall back to active push delivery.
  • Chat route associations expire after 30 minutes of inactivity.
  • Incoming media is downloaded into the local media store before being passed to the agent.
  • Outbound media is uploaded to WeCom as a temporary file and then sent as a media message.
  • Duplicate messages are detected and suppressed (ring buffer of last 1000 message IDs).

Migration from Legacy WeCom Config

Previous config Migration
channels.wecom (webhook bot) Replace with channels.wecom using bot_id + secret.
channels.wecom_app Remove. Use channels.wecom instead.
channels.wecom_aibot Move bot_id and secret to channels.wecom.
token, encoding_aes_key, webhook_url, webhook_path No longer used. Remove from config.
corp_id, corp_secret, agent_id No longer used. Remove from config.
welcome_message, processing_message, max_steps No longer part of the WeCom channel config.

Troubleshooting

QR binding times out

  • After scanning the QR code, you must also confirm the login inside the WeCom app. Scanning alone is not enough.
  • Re-run with a larger --timeout: picoclaw auth wecom --timeout 10m
  • If the QR code in the terminal is hard to scan, use the QR Code Link printed below it to open in a browser.

QR code expired

  • The QR code has a limited validity. Re-run picoclaw auth wecom to get a fresh one.

WebSocket connection fails

  • Verify bot_id and secret are correct.
  • Confirm the host can reach wss://openws.work.weixin.qq.com (outbound WebSocket, no inbound port needed).

Replies do not arrive

  • Check whether allow_from is blocking the sender.
  • Check that channels.wecom.bot_id and channels.wecom.secret are set and non-empty.