OpenClaw Codex

Recipe

Connect OpenClaw to WeCom

WeCom (WeChat Work) is heavily used by enterprises. Connecting it to OpenClaw allows you to bring your AI agent directly into your company's communication hub. This guide covers setup, webhook configuration, and known plugin API fixes.

Prerequisites

  • A running OpenClaw gateway (see VPS Deploy Recipe)
  • A public URL for your gateway (via Cloudflare Tunnel or Reverse Proxy)
  • Administrator access to a WeCom Enterprise workspace

Concept: Agent Mode vs. Bot Mode

In WeCom, you can integrate an AI in two ways:

  • Internal App (Agent Mode): The AI lives as a standalone app in the WeCom workspace. Users click the app to chat with it. Good for general company assistants.
  • Group Bot (Bot Mode): You add the AI to specific group chats via a Webhook URL. It only reads messages where it is @mentioned. Good for DevOps or specific project groups.

This guide focuses on the Internal App (Agent Mode), which is the most robust integration.

Step 1 — Create an Internal App

  1. Log into the WeCom Admin Console.
  2. Go to App Management (应用管理) -> Create App (创建应用).
  3. Upload an icon, give it a name, and select the users who are allowed to see it.
  4. Once created, note down your AgentId and Secret.
  5. Go to My Enterprise (我的企业) at the bottom of the sidebar to find your CorpId (企业ID).

Step 2 — Configure OpenClaw Secrets

Add the WeCom credentials to your secrets.env file.

bash ~/.config/openclaw/secrets.env 
WECOM_CORP_ID=ww_your_corp_id
WECOM_AGENT_ID=1000002
WECOM_CORP_SECRET=your_app_secret
WECOM_TOKEN=your_token_from_step_3
WECOM_ENCODING_AES_KEY=your_aes_key_from_step_3

Restart the gateway: systemctl --user restart openclaw-gateway.

Step 3 — Configure the API Webhook

  1. In your WeCom App settings page, look for Receive API (接收消息) and click Set via API (设置API接收).
  2. For the URL, enter your OpenClaw public address: e.g., https://your-public-url.com/webhook/wecom.
  3. Click Randomly Generate for both the Token and the EncodingAESKey.
  4. Copy these two values and put them into your secrets.env (as shown in Step 2).
  5. Restart your OpenClaw gateway again so it picks up the new Token and AES Key.
  6. Go back to the WeCom console and click Save (保存). WeCom will send a test handshake to OpenClaw. If the tokens match, it will save successfully.

⚠️ Known Issue: Plugin API Breaking Change

If your OpenClaw gateway crashes on startup with the error TypeError: api.registerHttpHandler is not a function when loading the WeCom plugin, it means you are hitting a breaking change introduced in OpenClaw v2026.3.2.

The Fix: OpenClaw removed the direct HTTP handler exposure from the plugin API. You need to manually patch the plugin code.

bash Patching the compiled plugin 
# Go to your global npm installation directory for openclaw
# Find the WeCom index.ts or compiled js file where registerHttpHandler is called
# Example using sed to remove the offending line:

sed -i 's/api.registerHttpHandler(handleWecomWebhookRequest);//g' path/to/openclaw/plugins/wecom/dist/index.js

# Restart the gateway
systemctl --user restart openclaw-gateway

After this fix, message routing handles the webhook internally.

Step 4 — Test the Integration

  1. Open your WeCom client (desktop or mobile).
  2. Find the app in your workspace.
  3. Send it a message. Check the gateway logs with journalctl --user -u openclaw -f.

Related