OpenClaw WeChat Channel Setup: A Real-World Troubleshooting Guide
Setting up OpenClaw’s WeChat channel integration sounds straightforward—until you hit a wall of cryptic error messages. This guide walks through a complete, real-world debugging session, turning each failure into a reusable fix you can apply right now.
Environment
-
OS: Windows (including Alibaba Cloud ECS Windows Server) -
OpenClaw version: 2026.4.1 -
Plugin: @tencent-weixin/openclaw-weixin -
Package manager: pnpm
Problem 1 — Gateway Startup Blocked
What you see
Gateway start blocked: set gateway.mode=local (current: remote)
or pass --allow-unconfigured.
Why it happens
OpenClaw detected a mismatch: your config says gateway.mode = remote, but you tried to start a local gateway without explicitly authorizing it. The system blocks the startup as a safeguard.
How to fix it
Option A (recommended) — Change the mode permanently:
openclaw config set gateway.mode local
openclaw gateway
Option B — Skip the check just this once:
openclaw gateway --allow-unconfigured
Use Option A if you’re running a local gateway long-term. Use Option B for a quick test without touching your config.
A syntax mistake that catches everyone
If you write:
openclaw config set gateway.mode=local
You’ll get:
config set mode error: value/json mode requires <value>.
The config set command expects key and value as separate arguments, not joined by =:
openclaw config set gateway.mode local
Problem 2 — Plugin Not in the Allow List
What you see
plugins.allow is empty; discovered non-bundled plugins may auto-load:
openclaw-weixin. Set plugins.allow to explicit trusted ids.
This warning means OpenClaw found openclaw-weixin in the extensions directory but has no explicit permission to load it. The plugin may be silently interrupted during initialization.
How to fix it
The plugins.allow field expects a JSON array, not a plain string:
openclaw config set plugins.allow "[\"openclaw-weixin\"]"
If you pass it as a plain string:
openclaw config set plugins.allow openclaw-weixin
You’ll get:
Config validation failed: plugins.allow: Invalid input: expected array, received string
Problem 3 — WeChat Login Fails With AbortError
This is the trickiest issue in the entire setup process. Everything looks configured correctly, yet login keeps failing at the same point.
What you see
正在启动微信扫码登录...
Failed to start login: AbortError: This operation was aborted
Channel login failed: Error: Failed to start login: AbortError: This operation was aborted
Step-by-step diagnosis
Step 1 — Rule out network blocking
The server is hosted on Alibaba Cloud ECS. The first concern is whether outbound traffic to Tencent’s servers is blocked by a security group rule.
Test connectivity directly:
curl https://login.weixin.qq.com
Result: Connected successfully. Network blocking is not the cause.
Step 2 — Rule out a timeout issue
The gateway logs show every WebSocket response taking over 18 seconds:
[ws] ⇄ res ✓ chat.history 18736ms
[ws] ⇄ res ✓ models.list 18683ms
[ws] ⇄ res ✓ node.list 18774ms
There’s also this error:
[model-pricing] pricing bootstrap failed: TimeoutError: The operation was aborted due to timeout
This raises a reasonable hypothesis: the gateway is sluggish, and the login request hits the plugin’s internal timeout before anything happens.
Try increasing the timeout:
openclaw channels login --channel openclaw-weixin --timeout 60000
Result: Same error. Timeout tuning doesn’t help.
Step 3 — Find out when exactly the failure occurs
Enable Node.js network-level debugging to capture every outbound request:
set NODE_DEBUG=http,https,net && openclaw channels login --channel openclaw-weixin
Clean up afterward:
set NODE_DEBUG=
Result: No network output at all. Not a single HTTP or TCP event was logged.
This is the key insight: the AbortError fires before any network request is made. The failure is happening inside the plugin’s initialization logic, not during a login API call.
Step 4 — Root cause
Combining all the evidence:
-
Installed plugin version: 2.1.3 -
Failure occurs at initialization, before any network activity -
--verboseproduces no additional output (error happens too early) -
Downgrading to 2.0.1resolves the issue immediately
Conclusion: openclaw-weixin version 2.1.3 contains a bug that aborts the login flow during plugin startup.
The Fix That Works
Uninstall the broken version and install the stable one:
openclaw plugins uninstall openclaw-weixin
openclaw plugins install "@tencent-weixin/openclaw-weixin@2.0.1" --dangerously-force-unsafe-install
openclaw channels login --channel openclaw-weixin
What does --dangerously-force-unsafe-install mean?
OpenClaw validates plugin integrity using cryptographic signatures. Version 2.0.1 predates the current signature scheme, so it fails the built-in check. This flag bypasses that validation.
Is it safe? Yes, as long as you’re installing from the official npm registry (@tencent-weixin/openclaw-weixin). The flag skips OpenClaw’s signature check—it doesn’t bypass npm’s own package verification. The package origin is trustworthy.
Complete Setup Checklist
If you’re starting from scratch, run these commands in order:
# Step 1: Set gateway to local mode
openclaw config set gateway.mode local
# Step 2: Add the plugin to the allow list
openclaw config set plugins.allow "[\"openclaw-weixin\"]"
# Step 3: Remove the broken version
openclaw plugins uninstall openclaw-weixin
# Step 4: Install the stable version
openclaw plugins install "@tencent-weixin/openclaw-weixin@2.0.1" --dangerously-force-unsafe-install
# Step 5: Trigger WeChat QR code login
openclaw channels login --channel openclaw-weixin
Where Are the Log Files?
When something goes wrong, logs are your best resource. OpenClaw writes to two separate locations:
| Log type | Path |
|---|---|
| Gateway runtime log | C:\Users\admin\AppData\Local\Temp\openclaw\openclaw-YYYY-MM-DD.log |
| Config change audit log | C:\Users\admin\.openclaw\logs\config-audit.jsonl |
One important caveat: channels login errors do not appear in the gateway log. To capture them, use --verbose or enable NODE_DEBUG in the terminal where you’re running the command.
Why openclaw channels add --channel weixin Doesn’t Work
The channels add command supports these built-in channels via the --channel flag:
telegram | whatsapp | discord | irc | googlechat | slack | signal | imessage | line
WeChat is not on this list. It’s implemented as an external plugin, and the correct entry point is:
openclaw channels login --channel openclaw-weixin
These are two distinct integration paths. channels add is for native channels. channels login is for plugin-based channels like WeChat.
Other Log Warnings Worth Knowing
The logs surface a few other warnings unrelated to WeChat. Here’s what they mean and whether you need to act on them:
Slack module not found
stage "slack" threw — skipping: Error: Cannot find module '@slack/web-api'
The Slack integration dependency isn’t installed. If you’re not using Slack, ignore it. Install @slack/web-api only when you need Slack support.
Amazon Bedrock plugin failed to load
amazon-bedrock failed to load: Error: Cannot find module '@aws-sdk/client-bedrock'
The config file has amazon-bedrock set to "enabled": false. This is expected behavior—the plugin is disabled and skipped. No action needed.
Bonjour advertiser keeps restarting
[bonjour] restarting advertiser (service stuck in announcing for 21411ms)
Bonjour handles local network device discovery via mDNS. Cloud servers often restrict mDNS broadcast traffic, causing this loop. It doesn’t affect WeChat channel functionality.
Frequently Asked Questions
Why can’t I use = in openclaw config set?
The command parses key and value as positional arguments separated by a space. Using = merges them into a single argument, which the parser doesn’t recognize as a valid key-value pair.
Correct syntax:
openclaw config set gateway.mode local
Why does plugins.allow require JSON array syntax?
The field is typed as an array in OpenClaw’s config schema, which allows multiple plugins to be whitelisted at once. Passing a plain string fails schema validation. Always wrap the value in ["..."].
What exactly is the bug in version 2.1.3?
Based on the diagnostic evidence, the abort occurs before any network request is dispatched, which points to a logic error in the plugin’s initialization or startup sequence. The plugin source is located at:
C:\Users\admin\.openclaw\extensions\openclaw-weixin\index.ts
For the specific bug details, inspect the startLogin function or wait for an official patch from @tencent-weixin.
Is --dangerously-force-unsafe-install risky?
Only if the package source is untrusted. Since @tencent-weixin/openclaw-weixin is published on the official npm registry, the package itself is verified by npm. The flag only bypasses OpenClaw’s internal signature check for older versions that predate the current signing scheme.
How do I verify the WeChat channel is working after login?
openclaw channels list
Check that the WeChat channel appears with an active status.
How do I upgrade once a fixed version is released?
openclaw plugins uninstall openclaw-weixin
openclaw plugins install "@tencent-weixin/openclaw-weixin@<new-version>"
Before upgrading on a production server, test the new version in a staging environment first. Version 2.1.3 is a good reminder that “latest” isn’t always stable.
Summary
The WeChat channel login failure in OpenClaw 2026.4.1 is caused by a bug in openclaw-weixin version 2.1.3. The AbortError occurs at plugin initialization—before any network request is made—which is why network diagnostics and timeout adjustments have no effect. The reliable fix is to downgrade to version 2.0.1.
The other configuration issues (gateway mode mismatch, plugin allow-list type error) are straightforward once you know the correct syntax. Keeping these in a checklist saves significant time on fresh installations.
