npm package: @gloablehive/celphone-wechat-plugin
Description: OpenClaw channel plugin for workphone-wechat API - enables sending/receiving WeChat messages through workphone. Supports multi-account with per-account agent binding.
Latest version: 1.2.0

# 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

```bash
# 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:

```json
{
  "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`:

```json5
{
  // ... 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:

```json
{
  "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](./docs/apifox-workphone-api-manual.md) for full API documentation.

## Development

```bash
# 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