ContextQMD
Back to Picoclaw

WeCom

docs/channels/wecom/README.md

0.2.85.6 KB
Original Source

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.

<p align="center"> </p>

Option 2: CLI QR Login

Run:

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

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

json
{
  "channel_list": {
    "wecom": {
      "enabled": true,
      "type": "wecom",
      "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

FieldTypeDefaultDescription
enabledboolfalseEnable the WeCom channel.
bot_idstring—WeCom AI Bot identifier. Required when enabled.
secretstring—WeCom AI Bot secret. Stored encrypted in .security.yml. Required when enabled.
websocket_urlstringwss://openws.work.weixin.qq.comWeCom WebSocket endpoint.
send_thinking_messagebooltrueSend a Processing... message before the streamed reply begins.
allow_fromarray[]Sender allowlist. Empty means allow all senders.
reasoning_channel_idstring""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 VariableCorresponding Field
PICOCLAW_CHANNELS_WECOM_ENABLEDenabled
PICOCLAW_CHANNELS_WECOM_BOT_IDbot_id
PICOCLAW_CHANNELS_WECOM_SECRETsecret
PICOCLAW_CHANNELS_WECOM_WEBSOCKET_URLwebsocket_url
PICOCLAW_CHANNELS_WECOM_SEND_THINKING_MESSAGEsend_thinking_message
PICOCLAW_CHANNELS_WECOM_ALLOW_FROMallow_from
PICOCLAW_CHANNELS_WECOM_REASONING_CHANNEL_IDreasoning_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 configMigration
channels.wecom (webhook bot)Replace with channels.wecom using bot_id + secret.
channels.wecom_appRemove. Use channels.wecom instead.
channels.wecom_aibotMove bot_id and secret to channels.wecom.
token, encoding_aes_key, webhook_url, webhook_pathNo longer used. Remove from config.
corp_id, corp_secret, agent_idNo longer used. Remove from config.
welcome_message, processing_message, max_stepsNo 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.