WorkPhone WeChat Channel Plugin

OpenClaw channel plugin for connecting to WorkPhone's WeChat API. Enables sending and receiving WeChat messages through the WorkPhone platform.

⚠️ Important: Human Account Model

Unlike Telegram/WhatsApp bots, this channel connects to a real human WeChat account:

• Bot Mode (Telegram/WhatsApp): One bot account → communicates with many users
• Human Mode (This plugin): One real WeChat account → Agent manages ALL their friends and groups

The agent needs to handle conversations with:

• All friends (1-on-1 DM)
• All group chats (chatrooms)
• Friend requests
• Moments interactions

Features

• Send/Receive Messages: Send text, media, links, and more to WeChat friends and groups
• Friend Management: Get friend list, update remarks, manage labels
• Group Chat: Send messages to WeChat chatrooms (groups)
• Moments (朋友圈): Read and post to WeChat Moments
• Webhook Integration: Receive real-time message callbacks from WorkPhone

Requirements

• OpenClaw instance
• WorkPhone account with WeChat API access
• WorkPhone API key

Installation

# If using as a local plugin
pnpm add ./channels/celphone-wechat-plugin

# Or link from your plugin registry
pnpm add @gloablehive/celphone-wechat-plugin

Configuration

Add to your OpenClaw config:

{
  "channels": {
    "celphone-wechat": {
      "apiKey": "your-workphone-api-key",
      "baseUrl": "https://api.workphone.example.com",
      "accountId": "your-workphone-account-id",
      "wechatAccountId": "workphone-wechat-account-id",  // REQUIRED
      "wechatId": "wxid_xxxxx",  // Actual WeChat ID
      "nickName": "My WeChat",
      "allowFrom": ["friend-wxid-1", "friend-wxid-2"],
      "dmSecurity": "allowlist"
    }
  }
}

Configuration Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | WorkPhone API key for authentication | | wechatAccountId | string | Yes | WeChat account ID from WorkPhone | | baseUrl | string | No | WorkPhone API base URL (default: provided by WorkPhone) | | accountId | string | No | WorkPhone account ID | | wechatId | string | No | Actual WeChat ID (wxid_xxx) | | nickName | string | No | Display name for this account | | allowFrom | string[] | No | WeChat IDs that can DM the agent | | dmSecurity | string | No | Policy: allowlist, blocklist, or allowall | | webhookSecret | string | No | Secret for webhook signature verification |

OpenClaw Configuration (bindings)

To route WeChat messages to the correct agent, configure in openclaw.json:

{
  // ... other config ...

  bindings: [
    // Internal management agents
    {
      agentId: "merchant-setup",
      match: {
        channel: "celphone-wechat",
        accountId: "wechat-admin-001",
      },
    },
    {
      agentId: "merchant-ops",
      match: {
        channel: "celphone-wechat",
        accountId: "wechat-ops-001",
      },
    },

    // Service agents (customer-facing)
    {
      agentId: "service-frontdesk",
      match: {
        channel: "celphone-wechat",
        accountId: "wechat-service-001",
      },
    },
    {
      agentId: "service-orders",
      match: {
        channel: "celphone-wechat",
        accountId: "wechat-service-002",
      },
    }
  ]
}

Multi-WeChat Account Support

For enterprises managing multiple WeChat accounts:

{
  "channels": {
    "celphone-wechat": {
      // Account 1: Customer service
      "apiKey": "xxx",
      "wechatAccountId": "wp-wechat-001",
      "wechatId": "wxid_customer_service",
      "nickName": "客服小微",
      "accountId": "wechat-service-001"
    }
  }
}

Each WeChat account maps to a different accountId in bindings for routing.

Webhook Setup

To receive messages, configure WorkPhone to send webhooks to your OpenClaw instance:

Your OpenClaw URL: https://your-instance.com/celphone-wechat/webhook

The webhook will POST message events to OpenClaw in real-time.

Supported Message Types

Outbound (Sending) - Both DM and Group

• Direct Messages (DM): Text, images, videos, files, links to friends
• Group Messages: Text, images, videos, files to chatrooms (supports @mention)

Inbound (Receiving)

• Text messages from friends
• Text messages from group chats
• Media messages (images, videos, files)
• Friend requests
• Group invitations (if enabled)

API Coverage

This plugin integrates with the WorkPhone WeChat API (131 APIs). Key covered areas:

• WeChat Accounts: List accounts, get account info
• Friends: Get friends, add friends, accept requests, update remarks/labels
• Chatrooms: Get group list, send to groups, update group name/announcement
• Messages: Send/receive friend messages and chatroom messages
• Moments: Read posts, publish moments, comment, like

See API Manual for full API documentation.

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Test
pnpm test

File Structure

celphone-wechat-plugin/
├── package.json              # Plugin manifest
├── openclaw.plugin.json      # Plugin config schema
├── index.ts                  # Entry point
├── setup-entry.ts            # Lightweight setup entry
├── src/
│   ├── channel.ts            # Channel plugin implementation
│   └── client.ts             # WorkPhone API client
└── README.md

License

附录：与企业平台集成要点

根据企业场景总方案，这个 channel 需要与外部平台集成：

1. 用户画像查询（外部平台提供）

Service agent 应通过外部平台 API 查询用户画像：

Service Agent -> 外部平台 API -> 返回: displayTier, serviceState, riskFlags, preferenceHints

2. 沟通记录归档

消息需要回写到外部平台：

WorkPhone Webhook -> OpenClaw -> 外部平台 ConversationLog

具体实现：在 handleInboundMessage 中添加归档逻辑。

3. 外部平台作为 Source of Truth

按照总方案：

• 用户主数据外置 - 不存 OpenClaw
• 沟通记录归档 - 写到外部平台
• OpenClaw 只保留运行时缓存

4. Security 注意事项

• dmSecurity: "allowlist" - 只接受白名单用户消息
• Service agent 权限最小化（workspace 只读）
• 敏感操作需要审批

附录：API 文档关联

配套的 WorkPhone WeChat API 手册位置：

• 完整手册：../../data/apifox-workphone-3/handbooks/apifox-workphone-api-manual.md
• JSON 索引：../../data/apifox-workphone-3/handbooks/apifox-workphone-api-manual.json
• 原始 API：../../data/apifox-workphone-3/raw/*.json

如有 OpenClaw skill 需要基于这些文档回答问题，可参考 ../../skills/workphone-apifox-api/

License

MIT