WeChat Work OpenClaw Adapter

WeChat Work → OpenClaw Adapter

Quick Start

# 1. Deploy
bash /scripts/deploy.sh
2. Edit .env with your WeChat Work credentials
nano ~/wecom-adapter/.env
3. Start
cd ~/wecom-adapter && npm start
4. Expose publicly
cloudflared tunnel --url http://localhost:8090
5. Copy tunnel URL → WeChat Work admin → webhook URL

Architecture

WeChat Work → HTTPS → Cloudflare Tunnel → Node.js Adapter (8090)
                                              ├─ Verify msg_signature (SHA1)
                                              ├─ Decrypt message (AES-256-CBC)
                                              ├─ Return "success" within 5s
                                              └─ Async: call OpenClaw → send reply via WeCom API

Key: Adapter returns success immediately, then sends AI reply asynchronously via WeChat Work's message/send API. This avoids the 5-second timeout.

⚠️ Critical Gotchas (Learned the Hard Way)

1. Parameter name is msg_signature, NOT signature

WeChat Work sends ?msg_signature=xxx, not ?signature=xxx. Reading req.query.signature will always be undefined.

2. Signature must include echostr/encrypt

GET verification: SHA1(sort([token, timestamp, nonce, echostr])) POST messages: SHA1(sort([token, timestamp, nonce, encrypt]))

NOT SHA1(sort([token, timestamp, nonce])) — the encrypted payload MUST participate in the signature.

3. echostr must be DECRYPTED before returning

WeChat Work sends an AES-encrypted echostr. You must: 1. Verify msg_signature 2. AES-256-CBC decrypt the echostr 3. Strip PKCS#7 padding 4. Extract message from format: 16-byte random + 4-byte length (BE) + message + CorpID 5. Return the decrypted message (not the raw echostr)

4. APP_SECRET ≠ EncodingAESKey

5. Express body parser must accept multiple Content-Types

WeChat Work may send XML as text/xml, application/xml, or other types:

app.use(express.text({ type: ['application/xml', 'text/xml', 'text/plain', '*/*'] }));

6. Async reply pattern is mandatory

WeChat Work requires response within 5 seconds. AI responses take 5-30s. Solution: 1. Return res.status(200).send('success') immediately 2. Call OpenClaw asynchronously 3. Send reply via POST /cgi-bin/message/send?access_token=xxx

7. IP whitelist required for sending messages

WeChat Work API (qyapi.weixin.qq.com) requires your server's public IP in the app's trusted IP list. Error 60020 means IP not whitelisted.

8. Enterprise verification required

⚠️ Unverified enterprises risk account suspension. WeChat may ban accounts that use API automation without proper enterprise verification. Complete verification before production use.

9. Cloudflare quick tunnels are unstable

Quick (account-less) tunnels generate new URLs on restart and may disconnect unexpectedly. For production, use Named Tunnels ($7/mo) or a static IP.

Environment Variables

CORP_ID=ww...              # From WeChat Work admin
AGENT_ID=1000003           # Application agent ID
AGENT_SECRET=xxx           # EncodingAESKey (43-char Base64, for encryption)
APP_SECRET=xxx             # Application Secret (for access_token)
WEBHOOK_TOKEN=xxx          # Token configured in webhook settings
OPENCLAW_TOKEN=xxx         # OpenClaw gateway bearer token
OPENCLAW_BASE_URL=http://localhost:18789  # OpenClaw gateway URL
CLAUDE_MODEL=claude-haiku-4-5             # AI model

Files

Troubleshooting

| Symptom | Cause | Fix | |---------|-------|-----| | signature=undefined | Using req.query.signature | Use req.query.msg_signature | | Signature mismatch | echostr/encrypt not in calculation | Include 4th element in sort array | | -30065 error | Returning encrypted echostr | Decrypt before returning | | bad decrypt | Wrong key or setAutoPadding(true) | Use setAutoPadding(false) + manual PKCS#7 | | body长度=undefined | Body parser doesn't match Content-Type | Accept */* in express.text() | | 60020 IP error | Server IP not whitelisted | Add public IP in WeChat Work console | | Timeout | 5s limit exceeded | Use async pattern: return success, send via API | | Account banned | Unverified + automated messages | Verify enterprise first |

# 1. Deploy
bash /scripts/deploy.sh
2. Edit .env with your WeChat Work credentials
nano ~/wecom-adapter/.env
3. Start
cd ~/wecom-adapter && npm start
4. Expose publicly
cloudflared tunnel --url http://localhost:8090
5. Copy tunnel URL → WeChat Work admin → webhook URL

| Symptom | Cause | Fix | |---------|-------|-----| | signature=undefined | Using req.query.signature | Use req.query.msg_signature | | Signature mismatch | echostr/encrypt not in calculation | Include 4th element in sort array | | -30065 error | Returning encrypted echostr | Decrypt before returning | | bad decrypt | Wrong key or setAutoPadding(true) | Use setAutoPadding(false) + manual PKCS#7 | | body长度=undefined | Body parser doesn't match Content-Type | Accept */* in express.text() | | 60020 IP error | Server IP not whitelisted | Add public IP in WeChat Work console | | Timeout | 5s limit exceeded | Use async pattern: return success, send via API | | Account banned | Unverified + automated messages | Verify enterprise first |