picoclaw

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

Run:

picoclaw auth wecom

The command:

Requests a QR code from WeCom and prints it in the terminal
Also prints a QR Code Link you can open in a browser if the terminal QR is hard to scan
Polls for confirmation — after scanning, you must also confirm the login inside the WeCom app
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:

{
  "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

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.

This site is open source. Improve this page.