openclaw-wechat

KO | EN

gitlite — search

#python #hacktoberfest #react #go #machine-learning #docker #java #awesome #cli #awesome-list #security #ios #mcp #open-source

openclaw-wechat

(★ 13)

OpenClaw 微信个人号 AI 助手插件 — 基于 WeChatPadPro (iPad 协议)，支持文字/图片/文件双向交换、关键词触发、多账号管理

openclaw-wechat Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# @icesword760/openclaw-wechat

[English](./README.en.md) | **中文**

OpenClaw 微信个人号频道插件，基于 [WeChatPadPro](https://github.com/WeChatPadPro/WeChatPadPro)（iPad 协议）。

让你的微信个人号秒变 AI 助手——收发消息、图片、文件，与大模型无缝对话。

## 功能特性

- 支持私聊和群聊
- 关键词触发（如 `@ai`），与个人日常使用互不干扰
- AI 回复前缀（如 `🤖`），一眼区分人和 AI
- 按联系人独立会话上下文，互不串扰
- 引用回复支持（自动提取被引用消息的上下文）
- 双向文件交换（图片、文档、压缩包等）
- 终端二维码扫码登录
- DM 配对 / 白名单 / 开放访问策略
- 多账号支持

## 快速开始

### 一键安装（推荐）

只需一条命令，自动完成所有部署和配置：

```bash
curl -fsSL https://raw.githubusercontent.com/icesword0760/openclaw-wechat/main/setup.sh | bash
```

> **前提条件**：已安装 [Node.js 22+](https://nodejs.org/) 和 [Docker](https://www.docker.com/products/docker-desktop)。
>
> 脚本会自动完成：部署 WeChatPadPro → 生成 TOKEN → 安装 OpenClaw 和插件 → 交互式配置 AI 模型 → 启动网关。
>
> 你只需要：输入 AI 的 API Key → 扫码登录微信 → 完成。

---

### 手动安装（分步进行）

如果你想了解每一步的细节，或者一键安装遇到问题，可以按以下步骤手动操作。

<details>
<summary>点击展开手动安装步骤</summary>

### 第 1 步：安装 Node.js

需要 Node.js **22 或更高版本**。

```bash
# macOS（使用 Homebrew）
brew install node@22

# Linux（使用 NodeSource）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows
# 从 https://nodejs.org/ 下载安装包
```

验证安装：

```bash
node --version  # 应输出 v22.x.x 或更高
```

### 第 2 步：安装 OpenClaw

```bash
npm install -g openclaw
```

验证安装：

```bash
openclaw --version
```

### 第 3 步：部署 WeChatPadPro

WeChatPadPro 是微信 iPad 协议的开源实现，本插件通过它的 HTTP API 与微信通信。

#### 方式 A：Docker 部署（推荐）

```bash
# 1. 克隆 WeChatPadPro 仓库
git clone https://github.com/WeChatPadPro/WeChatPadPro.git
cd WeChatPadPro/deploy

# 2. 编辑 .env 配置（按需修改密码和端口）
#    重点关注：
#    - ADMIN_KEY：管理密钥，后续生成 TOKEN 需要用到
#    - WECHAT_PORT：WeChatPadPro HTTP 服务端口
#    - MySQL 和 Redis 的密码

# 3. 启动所有服务（MySQL + Redis + WeChatPadPro）
docker-compose up -d

# 4. 检查服务状态
docker-compose ps
```

#### 方式 B：直接运行二进制文件

从 [WeChatPadPro Releases](https://github.com/WeChatPadPro/WeChatPadPro/releases) 下载对应系统的二进制包。

前提条件：
- 本地已安装 MySQL 5.7+ 和 Redis
- 创建数据库 `weixin`（或按 WeChatPadPro 文档配置）

```bash
# 解压后运行
chmod +x wechatpadpro    # Linux/macOS
./wechatpadpro           # Linux/macOS
# 或双击 wechatpadpro.exe  # Windows
```

> 详细部署说明请参考 [WeChatPadPro 官方文档](https://github.com/WeChatPadPro/WeChatPadPro)。

### 第 4 步：生成 TOKEN_KEY

WeChatPadPro 启动后，通过管理 API 生成一个专属 TOKEN_KEY。

```bash
# 将 ADMIN_KEY 替换为你在 .env 或 setting.json 中配置的管理密钥
# 将端口号替换为你的 WeChatPadPro 实际端口
curl "http://localhost:8849/login/GenAuthKey2?key=YOUR_ADMIN_KEY&count=1&days=365"
```

响应示例：

```json
{
  "Code": 200,
  "Data": {
    "authKeys": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"]
  }
}
```

> 如果返回的 API 路径不对，也可以尝试 `/admin/GenAuthKey1`，不同版本接口可能略有差异。
>
> 记下返回的 `authKeys` 值，这就是你的 **TOKEN_KEY**。

### 第 5 步：安装微信插件

```bash
openclaw plugins install @icesword760/openclaw-wechat
```

### 第 6 步：配置 OpenClaw

#### 基础配置（必填）

```bash
# 启用微信频道
openclaw config set channels.wechat.enabled true

# 设置 WeChatPadPro 的 HTTP 地址（端口按你的实际部署填写）
openclaw config set channels.wechat.serverUrl http://localhost:8849

# 设置第 4 步获取的 TOKEN_KEY
openclaw config set channels.wechat.token YOUR_TOKEN_KEY
```

#### 推荐配置（可选但强烈建议）

```bash
# 只处理以 "@ai" 开头的消息（让微信号可以正常个人使用）
openclaw config set channels.wechat.triggerPrefix "@ai"

# AI 回复加前缀，方便区分
openclaw config set channels.wechat.replyPrefix "🤖 "

# 每个联系人独立对话上下文
openclaw config set session.dmScope "per-peer"
```

#### 完整配置参考

如果你想直接编辑配置文件（`~/.openclaw/openclaw.json`），以下是完整示例：

```json
{
  "channels": {
    "wechat": {
      "enabled": true,
      "serverUrl": "http://localhost:8849",
      "token": "YOUR_TOKEN_KEY",
      "triggerPrefix": "@ai",
      "replyPrefix": "🤖 ",
      "dmPolicy": "open",
      "allowFrom": ["*"],
      "debugMessages": false
    }
  },
  "session": {
    "dmScope": "per-peer"
  }
}
```

<details>
<summary>所有配置项说明</summary>

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `enabled` | boolean | `false` | 是否启用微信频道 |
| `serverUrl` | string | - | WeChatPadPro HTTP API 地址（必填） |
| `token` | string | - | WeChatPadPro TOKEN_KEY（必填） |
| `triggerPrefix` | string | - | 消息触发前缀，不设置则所有消息都会被处理 |
| `replyPrefix` | string | - | AI 回复前缀 |
| `dmPolicy` | string | `"pairing"` | 私聊策略：`"open"`（开放）、`"pairing"`（需配对）、`"allowlist"`（白名单）、`"disabled"`（禁用） |
| `allowFrom` | array | `[]` | 私聊白名单（微信 ID 或昵称），`dmPolicy="open"` 时需包含 `"*"` |
| `groupPolicy` | string | `"allowlist"` | 群聊策略：`"open"`、`"allowlist"`、`"disabled"` |
| `groupAllowFrom` | array | `[]` | 群聊白名单（群 ID，如 `"xxx@chatroom"`） |
| `requireMention` | boolean | `true` | 群聊中是否需要 @机器人 才响应 |
| `historyLimit` | number | `10` | 群聊中保留的历史消息条数 |
| `textChunkLimit` | number | `2000` | 单条消息最大字符数（超出自动分段） |
| `debugMessages` | boolean | `false` | 是否在控制台输出调试日志 |
| `wxid` | string | - | 机器人自身的微信 ID（通常自动检测） |

</details>

### 第 7 步：配置 AI 模型

如果你还没有配置过 AI 模型，需要先设置：

```bash
# 以 OpenAI 为例
openclaw config set ai.provider openai
openclaw config set ai.apiKey YOUR_API_KEY

# 或使用兼容 OpenAI 接口的第三方服务
openclaw config set ai.provider openai
openclaw config set ai.baseUrl https://your-api-provider.com/v1
openclaw config set ai.apiKey YOUR_API_KEY
openclaw config set ai.model gpt-4o
```

### 第 8 步：启动网关并扫码登录

```bash
openclaw gateway
```

终端会显示一个二维码，使用微信扫描即可登录。

```
[wechat][default] scan this QR code with WeChat to login:
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
█ ▄▄▄▄▄ █...█ ▄▄▄▄▄ █
█ █   █ █...█ █   █ █
...（二维码）
```

登录成功后会看到：

```
[wechat][default] login confirmed
[wechat][default] polling for messages via HttpSyncMsg
```

### 第 9 步：测试

在微信中给机器人发送消息：

```
@ai 你好，请介绍一下你自己
```

如果一切正常，你会收到 AI 的回复（带有 🤖 前缀）。

> **访问控制提示**：如果使用默认的 `pairing`（配对）策略，发送者需要先通过配对审批：
>
> ```bash
> openclaw pairing approve wechat <CODE>
> ```
>
> 如果想让所有人都能直接使用，把 `dmPolicy` 设为 `"open"` 并将 `allowFrom` 设为 `["*"]`。

</details>

## 文件交换

插件支持双向文件交换：

### 接收用户发送的文件

- **图片**：自动注入 AI 视觉上下文（如果模型支持多模态，AI 可以直接"看到"图片）
- **文档/文件**：自动下载到本地 `~/.openclaw/media/wechat/`，文件路径会传递给 AI

### 让 AI 发送文件给用户

AI 在回复中使用 `MEDIA:/绝对路径` 格式即可发送文件：

- **图片**（png/jpg/gif/webp）→ 作为微信图片消息发送
- **其他文件**（PDF、Excel、zip 等）→ 上传至微信 CDN 后作为文件附件发送

示例对话：

```
用户: @ai 帮我生成一份本月销售报表的 Excel 文件
AI:   🤖 已为您生成销售报表。
      MEDIA:/Users/xxx/.openclaw/workspace/sales_report.xlsx
```

## 常见问题

### Q: 扫码后立即掉线怎么办？

这是 WeChatPadPro 的正常现象。首次登录 24 小时内可能掉线一次，重新扫码登录 1-2 次后即可稳定。之后通常可以保持 3 个月以上在线。

### Q: 如何让微信号既当 AI 助手又正常使用？

设置 `triggerPrefix`（如 `"@ai"`），这样只有以 `@ai` 开头的消息才会被 AI 处理，其他消息不受影响。

### Q: AI 回复太慢？

- 检查 AI 模型本身的响应速度（可用 `curl` 直接测试 API）
- 确认 `ai.thinking` 未设为高级别（推理等级越高越慢）
- 网络延迟也可能是原因

### Q: 群聊中如何使用？

1. 将群 ID 添加到 `groupAllowFrom` 白名单
2. 默认需要 @机器人 才会响应（可通过 `requireMention: false` 关闭）
3. 群聊中同样支持 `triggerPrefix`

### Q: 多账号如何配置？

在 `channels.wechat.accounts` 中添加多个账号配置：

```json
{
  "channels": {
    "wechat": {
      "enabled": true,
      "serverUrl": "http://localhost:8849",
      "token": "DEFAULT_TOKEN",
      "accounts": {
        "work": {
          "token": "WORK_ACCOUNT_TOKEN",
          "triggerPrefix": "@bot"
        },
        "personal": {
          "token": "PERSONAL_ACCOUNT_TOKEN",
          "triggerPrefix": "@ai"
        }
      }
    }
  }
}
```

## 架构

```
用户 (微信) <-> WeChatPadPro (iPad 协议) <-> 本插件 <-> OpenClaw Agent <-> AI 模型
```

| 方向 | 接口 | 说明 |
|------|------|------|
| 接收消息 | `POST /message/HttpSyncMsg` | HTTP 轮询拉取新消息 |
| 发送文字 | `POST /message/SendTextMessage` | 纯文本消息 |
| 发送图片 | `POST /message/SendImageNewMessage` | 图片消息 |
| 发送文件 | `POST /message/UploadFileToCDN` + `POST /message/SendAppMessage` | 先上传 CDN 再发送 |

## 许可证

MIT

openclaw-wechat

openclaw-wechat Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

openclaw-wechat

openclaw-wechat Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README