OpenClaw WeCom Integration Guide: A Real-World Troubleshooting Story From Errors to Success

This guide documents the complete process of connecting an OpenClaw AI gateway to a WeCom (Enterprise WeChat) intelligent bot on a self-hosted server — including every mistake made along the way and exactly how each one was fixed. If you’re a developer or system administrator with basic Linux experience, this walkthrough is written for you.

What Problems Does This Article Solve?

If you’re trying to integrate OpenClaw with WeCom (Enterprise WeChat), you’ve probably already run into one or more of the following issues:

Gateway startup fails with Invalid config, reporting unrecognized fields
The gateway process is running, but port 18789 stays free and health checks keep timing out
The WeCom plugin fails to load with a missing module error: Cannot find module '@wecom/aibot-node-sdk'
You accidentally filled the Webhook callback URL into the secret field
You’re confused about the difference between WebSocket long-connection mode and HTTP callback mode, which leads to misconfiguration

Every one of these problems has a clear, actionable fix. This guide walks through each one in detail.

Part 1: Understanding the Two WeCom Bot Connection Modes

Before touching any configuration file, you need to understand the two ways WeCom bots can connect to your server. Getting this wrong is the root cause of most configuration mistakes.

Long Connection (WebSocket) vs. Callback (Webhook/HTTP)

Comparison	Long Connection (WebSocket)	Callback Mode (Webhook / HTTP)
Connection direction	Your server connects to WeCom	WeCom sends requests to your server
Requires public IP	No	Yes
Configuration fields	`botId` + `secret`	`token` + `encodingAESKey` + public callback URL
Best use case	Internal servers, cloud VMs without fixed domain	Production environments with a fixed public domain
OpenClaw recommendation	✅ Recommended	Optional

Bottom line: If you’re running on a standard cloud server or an internal network machine, choose long-connection (WebSocket) mode. This is what the rest of this guide covers.

A lot of configuration headaches come from mixing fields from both modes. For example, putting a callback URL into the secret field, or including token and encodingAESKey (which belong to callback mode) inside a long-connection configuration. Once you’re clear on which mode you’re using, the config becomes much simpler.

Part 2: Creating a WeCom Intelligent Bot in the Admin Console

This step trips up a lot of people because it’s easy to take the wrong entry point. Here’s the exact path.

Step 1: Log Into the WeCom Admin Console

Open work.weixin.qq.com in your browser and sign in with an enterprise administrator account. A regular employee account won’t have access to the bot management section.

Step 2: Navigate to Intelligent Bots

In the left-side menu, click through: Security & Management → Management Tools → Intelligent Bots

Step 3: Create in API Mode — This Step Is Critical

Click “Create Bot” → “Manual Creation.” The default screen shows a standard bot, but that won’t give you API capabilities. Scroll to the bottom of the page and click “Create in API Mode.”

⚠️ Important: A standard bot created without API mode cannot be controlled programmatically. You must use API mode to get the credentials OpenClaw needs.

Step 4: Select “Long Connection” as the Connection Type

Inside the API creation flow, you’ll see two connection options. Select “Long Connection”, not “Callback.” This is what allows your server to initiate and maintain the connection outbound — no public IP or open inbound ports needed.

Step 5: Retrieve Your Bot ID and Secret

After the bot is created, navigate to its API configuration page and click “Click to Retrieve.” You’ll see two values:

Bot ID: Starts with aib-, for example: aib-xxxxxxxxxx
Secret: A random alphanumeric string, for example: aXk9Tz2mQpRv...

Copy both values and save them somewhere secure. You’ll need them when configuring OpenClaw.

Part 3: OpenClaw Configuration File Explained

The main configuration file lives at ~/.openclaw/openclaw.json. Getting this file right is the most important step in the whole process.

The Correct Long-Connection Configuration

Here’s what a correct WeCom long-connection configuration looks like:

{
  "channels": {
    "wecom": {
      "enabled": true,
      "botId": "aib-your-bot-id-here",
      "secret": "your-secret-string-from-wecom-console",
      "bot": {
        "streamPlaceholderContent": "Thinking...",
        "welcomeText": "Hello! I'm your AI assistant.",
        "dm": {
          "policy": "open"
        }
      }
    }
  }
}

Notice what’s not in this config: no token, no encodingAESKey, no callback URL, no path field. Those belong to other modes or other sections entirely.

Common Configuration Mistakes (With Fixes)

These are real mistakes made during the actual setup process documented in this guide.

Mistake #1: Putting the Callback URL Into the `secret` Field

// ❌ Wrong — this is a callback URL, not a secret
"secret": "http://159.75.78.224:18789/wecom"

// ✅ Correct — secret is a random string, never a URL
"secret": "aXk9Tz2mQpRv..."

The secret field must contain the random string that WeCom generates in the API configuration panel. It is never a URL. If you paste a URL here, the bot authentication will fail silently or throw a cryptic error.

Mistake #2: Including Callback-Mode Fields Inside Long-Connection Config

// ❌ Wrong — token and encodingAESKey are for callback mode only
"bot": {
  "token": "jriCmneLxJKoKSs1dwIxzutLVMzL68",
  "encodingAESKey": "wBEdfD7GJkrbi3HgFcBH9XzGfKs5nDB1AaCXYAhX1kY"
}

In long-connection mode, you don’t need token or encodingAESKey. Leaving them in won’t necessarily stop the gateway from starting, but it can cause unexpected behavior in the plugin and will confuse your future self when debugging.

Mistake #3: Adding a `path` Field Inside `plugins.entries.wecom`

// ❌ Wrong — "path" is not a valid key inside plugins.entries
"plugins": {
  "entries": {
    "wecom": {
      "path": "/some/local/path",
      "enabled": true
    }
  }
}

This causes the startup error:

Invalid config at /root/.openclaw/openclaw.json:
- plugins.entries.wecom: Unrecognized key: "path"

The correct place to specify a local plugin path is under plugins.load.paths, not inside entries. The entries section only accepts enabled and config as valid keys.

// ✅ Correct — local plugin path goes here
"plugins": {
  "load": {
    "paths": ["/some/local/path"]
  },
  "entries": {
    "wecom": {
      "enabled": true
    }
  }
}

How to Automatically Remove the Illegal `path` Field

If you’d rather not hand-edit JSON, this Python script will cleanly remove the offending field:

python3 -c "
import json
with open('/root/.openclaw/openclaw.json') as f:
    cfg = json.load(f)

wecom = cfg.get('plugins', {}).get('entries', {}).get('wecom', {})
removed = wecom.pop('path', None)
print(f'Removed path: {removed}')

with open('/root/.openclaw/openclaw.json', 'w') as f:
    json.dump(cfg, f, indent=2, ensure_ascii=False)
print('Done.')
"

⚠️ Known issue: openclaw doctor --fix will report that it found and fixed invalid keys, but it does not actually remove them from the file. You must fix the config manually or with a script like the one above.

Part 4: Installing the WeCom Plugin

There are several ways to install the plugin depending on your setup.

Option 1: Install via the Official Plugin Command

openclaw plugins install @wecom/wecom-openclaw-plugin

Option 2: Use the Interactive Setup Wizard (Recommended for First-Time Users)

openclaw channels add
# Choose WeCom → Enter botId → Enter secret → Select finish

This is the safest way to install because the wizard validates your input before writing to the config file.

Option 3: Write Configuration Directly via CLI

openclaw config set channels.wecom.enabled true
openclaw config set channels.wecom.botId "aib-your-bot-id"
openclaw config set channels.wecom.secret "your-secret-string"
openclaw config set gateway.bind lan

Part 5: Diagnosing and Fixing Common Errors

Error 1: Cannot find module ‘@wecom/aibot-node-sdk’

Full error message:

wecom failed to load from /root/.openclaw/extensions/wecom/index.ts:
Error: Cannot find module '@wecom/aibot-node-sdk'
Require stack:
- /root/.openclaw/extensions/wecom/src/ws-adapter.ts

What this means: The plugin directory is missing its npm dependency. The plugin code exists, but the library it depends on is not installed.

Fix:

# Navigate to the plugin directory
cd /root/.openclaw/extensions/wecom

# Install the missing dependency
# Use the Chinese npm mirror to avoid timeout on international connections
npm install @wecom/aibot-node-sdk --registry=https://registry.npmmirror.com

# Verify the installation succeeded
ls node_modules/@wecom/aibot-node-sdk/

If the install hangs indefinitely, the issue is almost always a slow or blocked connection to the default npm registry. Set the mirror permanently and retry:

npm config set registry https://registry.npmmirror.com
npm install @wecom/aibot-node-sdk

After a successful install, restart the gateway:

openclaw gateway restart

If installation keeps failing, uninstall and reinstall the entire plugin from scratch:

openclaw plugins uninstall wecom
openclaw plugins install @wecom/wecom-openclaw-plugin
openclaw gateway restart

Error 2: Gateway Times Out — Port 18789 Always Shows as Free

Full error message:

Timed out after 60s waiting for gateway port 18789 to become healthy.
Gateway process is running but port 18789 is still free 
(startup hang/crash loop or very slow VM startup).
Service runtime: status=running, state=active, pid=65829, lastExit=0
Gateway port 18789 status: free.
Gateway restart timed out after 60s waiting for health checks.

This error means the gateway process started but never began accepting connections. The most common cause is a configuration error that causes the gateway to crash before it can bind to the port.

Diagnostic steps:

# Step 1: Check the gateway logs
journalctl -u openclaw -n 100 --no-pager

# Or check OpenClaw's own log file
tail -100 ~/.openclaw/logs/gateway.log 2>/dev/null || \
tail -100 ~/.openclaw/gateway.log 2>/dev/null

# Step 2: Confirm the port status
ss -tlnp | grep 18789

# Step 3: Kill the hung process and run in foreground to see errors directly
kill -9 65829   # Use the PID from the error message
openclaw gateway

Running in the foreground instead of as a daemon makes it much easier to see exactly where the startup process fails. Fix the configuration issue shown in the output, then restart normally.

In most cases, the gateway timeout is caused by an invalid configuration file. Fix the config (see Part 3), and the gateway will start successfully.

Error 3: Invalid Config — Unrecognized Key

Full error message:

Invalid config at /root/.openclaw/openclaw.json:
- plugins.entries.wecom: Unrecognized key: "path"

This is a schema validation error. The path key is not a recognized field inside plugins.entries.wecom. See Part 3, Mistake #3 for the complete fix.

Error 4: skillhub Plugin Warning

plugins.entries.skillhub: plugin disabled (not in allowlist) but config is present

This is a warning, not an error. It will not affect WeCom functionality. If you want to suppress it, either remove the plugins.entries.skillhub section from your config file or set its enabled value to false.

Part 6: Completing the Pairing Process

Once the plugin is installed and the gateway is running, you need to complete a one-time pairing step before the bot can process messages.

How to Pair

Step 1: Open WeCom and find the intelligent bot you created (search by name or find it in your contacts).

Step 2: Send the bot any message — “Hello” works fine.

Step 3: The bot will automatically reply with a Pairing Code (also called a configuration key).

Step 4: Copy the key from the last line of the bot’s reply, paste it into your terminal when prompted, and press Enter. Pairing is complete.

What If the Pairing Code Expires?

Pairing codes expire after a short period. If yours has expired:

Send the bot another message in WeCom to generate a new code
Run the following command in your terminal:

openclaw pairing approve

Enter the new pairing code when prompted

Part 7: Uninstalling the WeCom Plugin

If you need to reinstall or switch to a different integration approach, here’s how to cleanly remove the plugin.

Method 1: Use the Plugin Command

openclaw plugins uninstall wecom
openclaw gateway restart

Method 2: Manual Removal (If the Command Doesn’t Fully Clean Up)

# Remove the plugin directory
rm -rf /root/.openclaw/extensions/wecom

# Remove the wecom entry from the config file
python3 -c "
import json
with open('/root/.openclaw/openclaw.json') as f:
    cfg = json.load(f)
cfg.get('plugins', {}).get('entries', {}).pop('wecom', None)
with open('/root/.openclaw/openclaw.json', 'w') as f:
    json.dump(cfg, f, indent=2, ensure_ascii=False)
print('Done.')
"

openclaw gateway restart

Part 8: Complete Setup Checklist

Use this checklist to go through the entire process in the correct order and avoid the most common mistakes:

□ 1. WeCom Admin Console
      → Management Tools → Intelligent Bots
      → Create Bot → API Mode → Long Connection
      → Retrieve and save botId and Secret

□ 2. Edit ~/.openclaw/openclaw.json
      → Set channels.wecom.botId  (starts with "aib-")
      → Set channels.wecom.secret (random string, NOT a URL)
      → Remove token, encodingAESKey, path (these don't belong here)

□ 3. Install the npm dependency
      cd /root/.openclaw/extensions/wecom
      npm install @wecom/aibot-node-sdk --registry=https://registry.npmmirror.com

□ 4. Start the gateway
      openclaw gateway

□ 5. Complete pairing
      → Send a message to the bot in WeCom
      → Copy the pairing code
      → Paste it into the terminal

□ 6. Test
      → Send another message to the bot
      → Confirm the AI response comes back

Frequently Asked Questions

Q: Does long-connection mode require me to open any inbound firewall ports?

No. Long-connection mode works by having your server initiate an outbound WebSocket connection to WeCom’s servers. WeCom does not need to send HTTP requests to your machine, so there is no need to open inbound ports or set up a public callback URL.

Q: What format is the Bot ID in?

Bot IDs always start with aib- followed by a string of alphanumeric characters. For example: aib-vdou5SX2cSLvDZxBwy7DViJ29iXYjIQF. If what you have doesn’t start with aib-, double-check that you selected API mode and long-connection type when creating the bot.

Q: What happens if I put the wrong value in the secret field?

The plugin will fail to authenticate with WeCom during the WebSocket handshake. The gateway log will show an authentication error. To fix it, go back to the WeCom admin console, copy the correct Secret value, update channels.wecom.secret in your config file, and restart the gateway.

Q: npm install keeps hanging. What do I do?

The default npm registry points to servers that may be slow or blocked depending on your network location. Switch to the npmmirror registry:

npm config set registry https://registry.npmmirror.com
npm install @wecom/aibot-node-sdk

This mirror is typically much faster for servers hosted in mainland China or similar environments.

Q: Do I need to restart the gateway every time I change the config file?

Yes. OpenClaw reads the configuration file at startup. Any changes to openclaw.json require a gateway restart to take effect:

openclaw gateway restart

Q: The gateway is running and WeCom shows the bot as online, but it doesn’t respond to messages. How do I debug this?

Check the gateway logs in real time:

openclaw logs --follow

Look for WeCom-related entries. Key things to check:

Did the plugin load successfully? (Look for any failed to load messages)
Is the botId and secret correct?
Was the pairing step completed successfully?
Is the AI model configured properly? (Check gateway.agent.model in your config)

Q: Can I run multiple channels alongside WeCom (e.g., Slack and WeCom at the same time)?

Yes. OpenClaw supports multiple channels running simultaneously. Each channel gets its own entry under channels in the config file:

{
  "channels": {
    "wecom": {
      "enabled": true,
      "botId": "aib-...",
      "secret": "..."
    },
    "slack": {
      "enabled": true,
      "botToken": "xoxb-..."
    }
  }
}

Q: The openclaw doctor --fix command said it fixed the config, but I’m still seeing the same error. Why?

This is a known bug. The doctor --fix command detects invalid keys and reports that it has fixed them, but in practice it does not actually remove the problematic fields from the file. You need to fix the config manually or use the Python script provided in Part 3 of this guide.

Summary

Integrating OpenClaw with WeCom involves more steps than it might first appear, but the failure points are predictable and consistent. Nearly every problem encountered during this integration fell into one of three categories:

Wrong configuration fields — mixing long-connection and callback-mode settings, or putting a URL where a string is expected
Missing npm dependencies — the plugin directory exists but the SDK package is not installed
Mode confusion — not understanding the difference between WebSocket long-connection and HTTP callback, which leads to the wrong fields being configured

Fix these three things, and the rest of the integration tends to fall into place quickly.

If you’ve followed this guide and are still running into issues, pull up the full gateway logs and look for specific error messages — they almost always tell you exactly what’s wrong:

openclaw gateway 2>&1 | grep -A 5 wecom

Most problems are one config change and one restart away from being resolved.

OpenClaw WeCom Integration: Solving Gateway Errors, Missing Modules & Bot Setup

OpenClaw WeCom Integration Guide: A Real-World Troubleshooting Story From Errors to Success

What Problems Does This Article Solve?

Part 1: Understanding the Two WeCom Bot Connection Modes

Long Connection (WebSocket) vs. Callback (Webhook/HTTP)

Part 2: Creating a WeCom Intelligent Bot in the Admin Console

Step 1: Log Into the WeCom Admin Console

Step 2: Navigate to Intelligent Bots

Step 3: Create in API Mode — This Step Is Critical

Step 4: Select “Long Connection” as the Connection Type

Step 5: Retrieve Your Bot ID and Secret

Part 3: OpenClaw Configuration File Explained

The Correct Long-Connection Configuration

Common Configuration Mistakes (With Fixes)

Mistake #1: Putting the Callback URL Into the secret Field

Mistake #2: Including Callback-Mode Fields Inside Long-Connection Config

Mistake #3: Adding a path Field Inside plugins.entries.wecom

How to Automatically Remove the Illegal path Field

Part 4: Installing the WeCom Plugin

Option 1: Install via the Official Plugin Command

Option 2: Use the Interactive Setup Wizard (Recommended for First-Time Users)

Option 3: Write Configuration Directly via CLI

Part 5: Diagnosing and Fixing Common Errors

Error 1: Cannot find module ‘@wecom/aibot-node-sdk’

Error 2: Gateway Times Out — Port 18789 Always Shows as Free

Error 3: Invalid Config — Unrecognized Key

Error 4: skillhub Plugin Warning

Part 6: Completing the Pairing Process

How to Pair

What If the Pairing Code Expires?

Part 7: Uninstalling the WeCom Plugin

Method 1: Use the Plugin Command

Method 2: Manual Removal (If the Command Doesn’t Fully Clean Up)

Part 8: Complete Setup Checklist

Frequently Asked Questions

Summary

Related Posts

Mistake #1: Putting the Callback URL Into the `secret` Field

Mistake #3: Adding a `path` Field Inside `plugins.entries.wecom`

How to Automatically Remove the Illegal `path` Field