微信公众号/小程序 - 微信生态接入

微信是中国用户基数最大的社交平台，月活跃用户超过 13 亿。通过将 OpenClaw 接入微信公众号 (Official Account) 和微信小程序 (Mini Program)，您可以将 AI 能力直接触达终端用户，无需安装任何额外应用。

微信生态的独特价值

微信公众号和小程序面向的是外部用户（客户、粉丝、公众），而企业微信面向的是内部员工。如果您需要为企业客户或公众提供 AI 服务（如智能客服、知识问答），微信生态是最佳选择。

概述：微信生态接入方式

OpenClaw 支持两种微信生态接入方式：

接入方式	适用场景	用户体验	技术复杂度
微信公众号（服务号）	智能客服、知识问答、业务咨询	对话式交互	⭐⭐
微信小程序	完整的 AI 应用界面、复杂交互场景	富交互 UI	⭐⭐⭐

公众号类型注意

微信公众号分为订阅号和服务号两种。只有已认证的服务号才具有完整的消息交互 API 能力。订阅号仅支持被动回复，不支持客服消息等高级功能。请确保您使用的是服务号。

第一部分：微信公众号（服务号）接入

前提条件

条件	说明
OpenClaw 环境	已安装并初始化（参考快速启动）
已认证的微信服务号	需完成微信认证（每年 300 元认证费）
公网服务器	需要有公网可访问的服务器并配置 HTTPS
ICP 备案域名	服务器域名必须完成 ICP 备案（中国大陆法律要求）

ICP 备案要求

根据中国大陆法律法规，用于微信公众号开发的服务器域名必须完成 ICP 备案。未备案域名将无法通过微信的服务器配置验证。如果您的服务器部署在中国大陆境外，建议使用已备案的国内 CDN 或反向代理 (Reverse Proxy) 服务。

步骤一：登录微信公众平台

打开微信公众平台
使用公众号管理员微信扫码登录

步骤二：启用开发者模式

在左侧菜单中，点击 设置与开发 → 基本配置
在公众号开发信息中查看 开发者ID (AppID) 和 开发者密码 (AppSecret)
如果 AppSecret 尚未生成，点击重置生成新的密码（需管理员扫码验证）

开发者模式与自定义菜单

启用开发者模式后，微信公众平台自带的自动回复和自定义菜单功能将被接管。所有消息处理和菜单响应将由您的 OpenClaw 服务器负责。请确保 Gateway 已正确配置后再启用。

步骤三：获取 AppID 和 AppSecret

在基本配置页面复制 AppID（格式如 wx1234567890abcdef）
复制 AppSecret（仅显示一次，请妥善保管）

步骤四：配置服务器地址

在基本配置页面，点击服务器配置中的修改配置
填写以下信息：

字段	值	说明
服务器地址 (URL)	`https://your-domain.com/api/channels/wechat/webhook`	OpenClaw Gateway 回调地址
令牌 (Token)	自定义字符串	消息签名验证令牌
消息加解密密钥	自动生成或自定义（43 位字符）	EncodingAESKey
消息加解密方式	安全模式（推荐）	明文/兼容/安全模式三选一

点击提交，微信会向服务器地址发送 GET 验证请求
验证通过后，点击启用

消息加解密方式

明文模式：消息不加密，适合开发调试
兼容模式：同时支持明文和密文，适合迁移过渡
安全模式：所有消息加密传输，推荐生产环境使用

步骤五：安装微信插件

npm手动下载

bash

openclaw plugins install @openclaw/wechat

bash

wget https://github.com/openclaw/plugin-wechat/releases/latest/download/wechat.tar.gz
openclaw plugins install ./wechat.tar.gz

安装完成后验证：

bash

openclaw plugins list
# 输出应包含: @openclaw/wechat (v1.x.x) - active

步骤六：配置 OpenClaw

配置文件方式环境变量方式

json5

{
  channels: {
    wechat: {
      enabled: true,
      // 公众号 AppID
      appId: "wx1234567890abcdef",
      // 公众号 AppSecret
      appSecret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      // 服务器配置中填写的 Token
      token: "your_custom_token",
      // 消息加解密密钥 (安全模式必填)
      encodingAESKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      // 加密方式: "plain" | "compatible" | "safe"
      encryptMode: "safe",
      // 消息策略
      dmPolicy: "open"
    }
  }
}

bash

export WECHAT_APP_ID="wx1234567890abcdef"
export WECHAT_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export WECHAT_TOKEN="your_custom_token"
export WECHAT_ENCODING_AES_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export WECHAT_ENCRYPT_MODE="safe"
export WECHAT_DM_POLICY="open"

启动并验证

bash

openclaw gateway

启动成功日志：

[INFO] WeChat Official Account channel initialized
[INFO] Gateway listening on :3000
[INFO] WeChat webhook ready at /api/channels/wechat/webhook

消息类型支持

OpenClaw 支持微信公众号的多种消息类型：

消息类型	接收	回复	说明
文本 (Text)	✅	✅	最常用的文字消息交互
图片 (Image)	✅	✅	支持 AI 图片理解和图片生成
语音 (Voice)	✅	✅	需开通语音识别功能
视频 (Video)	✅	✅	视频消息处理
位置 (Location)	✅	-	用户发送的地理位置信息
链接 (Link)	✅	-	用户分享的链接
事件 (Event)	✅	-	关注/取关/菜单点击等事件

自动回复配置

json5

{
  channels: {
    wechat: {
      // ... 基础配置 ...
      autoReply: {
        // 用户关注时自动回复
        subscribe: "🎉 欢迎关注！我是 AI 智能助手，有什么可以帮您的吗？",
        // 默认回复（当 AI 无法处理时）
        fallback: "抱歉，我暂时无法理解您的问题，请换种方式描述。",
        // 关键词自动回复（优先于 AI 处理）
        keywords: {
          "人工客服": { action: "transfer_customer_service" },
          "帮助": { action: "reply", content: "请直接输入您的问题，我会为您解答。" }
        }
      }
    }
  }
}

客服会话管理 (Customer Service Session)

微信公众号的被动回复有严格的时间限制（5 秒内必须响应）。对于 AI 生成较慢的场景，推荐使用客服消息接口：

json5

{
  channels: {
    wechat: {
      // ... 基础配置 ...
      customerService: {
        enabled: true,
        // 超过此时间（毫秒）切换为客服消息模式
        switchThreshold: 4000,
        // 切换时发送的占位回复
        pendingReply: "正在思考中，请稍候..."
      }
    }
  }
}

客服消息 48 小时窗口

微信公众号的客服消息接口有严格的 48 小时回复窗口限制：自用户最后一次发送消息起 48 小时内，公众号才可以通过客服消息接口向该用户发送消息。超过 48 小时则无法主动推送，只能等待用户再次发消息。

模板消息 (Template Message)

模板消息可用于向用户推送通知（如 AI 任务完成通知、定时报告等）：

json5

{
  channels: {
    wechat: {
      // ... 基础配置 ...
      templateMessage: {
        enabled: true,
        // 模板ID（需在公众平台→模板消息中添加）
        templates: {
          taskComplete: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          dailyReport: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        }
      }
    }
  }
}

模板消息限制

模板消息内容必须严格遵循模板格式，不支持自定义样式
模板消息需要用户主动关注公众号后才能推送
发送频率受限：认证服务号每日 10 万条
2025 年起微信逐步收紧模板消息政策，部分行业可能迁移至订阅通知机制

IP 白名单

微信公众号 API 调用需要配置 IP 白名单：

在微信公众平台 → 设置与开发 → 基本配置
在IP白名单中添加您的 OpenClaw Gateway 服务器公网 IP
多个 IP 用换行分隔

第二部分：微信小程序接入

概述

微信小程序 (Mini Program) 是运行在微信客户端内的轻量级应用，无需安装即可使用。相比公众号的纯消息交互，小程序可以提供完整的图形化 UI 界面，实现更丰富的 AI 交互体验。

架构说明

微信小程序接入 OpenClaw 的架构如下：

用户 ←→ 微信小程序 (前端) ←→ OpenClaw API (后端)
                                    ↓
                              AI 模型 (推理)

小程序前端通过 WebSocket 或 HTTP 请求与 OpenClaw 后端 API 通信，实现实时对话。

前提条件

条件	说明
小程序开发者账号	在微信公众平台注册小程序
小程序 AppID	从小程序管理后台获取
ICP 备案域名	后端 API 域名必须完成 ICP 备案
HTTPS 证书	小程序只允许 HTTPS 协议请求

后端 API 集成

OpenClaw 提供专门的小程序 API 端点：

json5

{
  channels: {
    wechatMiniProgram: {
      enabled: true,
      appId: "wx_miniprogram_appid",
      appSecret: "xxx",
      // API 模式: "http" 普通请求 或 "websocket" 实时流式
      apiMode: "websocket",
      // 会话管理
      session: {
        // 会话超时（秒）
        timeout: 1800,
        // 最大并发会话数
        maxConcurrent: 1000
      }
    }
  }
}

用户认证流程

微信小程序通过 wx.login() 获取临时登录凭证 (code)，再由后端换取用户身份信息：

1. 小程序调用 wx.login() 获取 code
2. 小程序将 code 发送给 OpenClaw 后端
3. OpenClaw 用 code 换取 openid 和 session_key
4. 返回自定义登录态 (JWT Token)
5. 后续请求携带 Token 进行身份验证

小程序端示例代码：

小程序端 - 登录小程序端 - WebSocket 对话

javascript

// app.js
App({
  onLaunch() {
    wx.login({
      success: (res) => {
        wx.request({
          url: 'https://your-domain.com/api/wechat-mp/login',
          method: 'POST',
          data: { code: res.code },
          success: (loginRes) => {
            // 保存登录态
            wx.setStorageSync('token', loginRes.data.token)
          }
        })
      }
    })
  }
})

javascript

// pages/chat/chat.js
Page({
  connectWebSocket() {
    const token = wx.getStorageSync('token')
    wx.connectSocket({
      url: `wss://your-domain.com/api/wechat-mp/ws?token=${token}`
    })

    wx.onSocketMessage((res) => {
      const data = JSON.parse(res.data)
      // 处理 AI 回复（支持流式输出）
      this.appendMessage(data)
    })
  },

  sendMessage(content) {
    wx.sendSocketMessage({
      data: JSON.stringify({
        type: 'chat',
        content: content
      })
    })
  }
})

小程序服务器域名配置

在微信公众平台 → 小程序管理后台 → 开发管理 → 开发设置 → 服务器域名中配置：

域名类型	值	说明
request 合法域名	`https://your-domain.com`	HTTP API 请求域名
socket 合法域名	`wss://your-domain.com`	WebSocket 连接域名
uploadFile 合法域名	`https://your-domain.com`	文件上传域名（可选）
downloadFile 合法域名	`https://your-domain.com`	文件下载域名（可选）

域名配置限制

所有域名必须经过 ICP 备案
域名必须使用 HTTPS/WSS 协议
每月最多修改 50 次域名配置
不支持 IP 地址，必须使用域名

重要限制与注意事项

公众号消息限制

限制项	说明
被动回复时间	5 秒内必须响应，否则微信提示"该公众号暂时无法提供服务"
客服消息窗口	用户最后消息后 48 小时内有效
模板消息频率	认证服务号每日 10 万条
单条消息长度	文本消息最长 600 字符
图文消息数量	单次最多 1 条图文消息（2024 年后限制）

小程序限制

限制项	说明
WebSocket 连接数	同一小程序最多 5 个并发 WebSocket 连接
HTTP 请求并发	同一域名最多 10 个并发请求
包体大小	小程序总包体积不超过 20MB

API 调用频率

API 类型	频率限制	说明
获取 AccessToken	每日 2000 次	OpenClaw 自动缓存和刷新
客服消息发送	每日 500000 次（服务号）	仅在 48 小时窗口内有效
模板消息发送	每日 100000 次	需用户关注且有模板消息授权

🇨🇳 微信生态合规与最佳实践

ICP 备案

根据《互联网信息服务管理办法》，在中国大陆提供互联网信息服务的网站和应用后端，其服务器域名必须完成 ICP 备案。

备案流程概述推荐云服务商

text

1. 选择云服务商（阿里云、腾讯云、华为云等）
2. 在云服务商控制台提交 ICP 备案申请
3. 提供营业执照、法人身份证、网站负责人信息
4. 等待管局审核（通常 7-20 个工作日）
5. 审核通过后获取 ICP 备案号
6. 在网站底部展示备案号

text

- 腾讯云：与微信生态联动最紧密，有微信云托管服务
- 阿里云：备案流程最成熟，审核速度快
- 华为云：政务和国企场景首选

内容安全

微信对公众号和小程序的内容有严格的审核要求。OpenClaw 需要配置内容安全过滤：

json5

{
  channels: {
    wechat: {
      // ... 基础配置 ...
      contentSecurity: {
        enabled: true,
        // 使用微信内容安全 API 进行文本检测
        useWechatMsgSecCheck: true,
        // 自定义敏感词过滤
        sensitiveWords: ["自定义敏感词列表"],
        // 触发过滤时的回复
        blockedReply: "抱歉，您的问题涉及敏感内容，我无法回答。"
      }
    }
  }
}

内容合规

微信对 AI 生成内容有严格要求。根据《生成式人工智能服务管理暂行办法》，AI 生成的内容不得包含违反法律法规的内容。建议：

启用微信内容安全 API 对 AI 回复进行检测
配置自定义敏感词过滤规则
对 AI 回复添加明确的 AI 生成标识
保留完整的对话日志，以备审计需要

数据存储合规

用户个人数据（openid、聊天记录等）需存储在中国大陆境内的服务器
遵循《个人信息保护法》要求，明确告知用户数据收集和使用目的
提供用户数据删除功能

微信云托管推荐

腾讯云提供微信云托管服务，专为微信小程序和公众号设计，可以简化部署流程：

免域名、免备案（使用微信提供的域名）
自动 HTTPS 证书
与微信登录体系天然集成
按量计费，适合初创团队

环境变量参考

环境变量	对应配置项	说明
`WECHAT_APP_ID`	`wechat.appId`	公众号 AppID
`WECHAT_APP_SECRET`	`wechat.appSecret`	公众号 AppSecret
`WECHAT_TOKEN`	`wechat.token`	服务器验证 Token
`WECHAT_ENCODING_AES_KEY`	`wechat.encodingAESKey`	消息加解密密钥
`WECHAT_ENCRYPT_MODE`	`wechat.encryptMode`	加密方式
`WECHAT_MP_APP_ID`	`wechatMiniProgram.appId`	小程序 AppID
`WECHAT_MP_APP_SECRET`	`wechatMiniProgram.appSecret`	小程序 AppSecret

下一步

企业微信接入 - 企业内部 AI 接入（面向员工）
飞书接入 - 接入字节跳动飞书
钉钉接入 - 接入阿里钉钉
国产大模型配置 - 配置 DeepSeek、通义千问等国产模型

微信公众号/小程序 - 微信生态接入 ​

概述：微信生态接入方式 ​

第一部分：微信公众号（服务号）接入 ​

前提条件 ​

步骤一：登录微信公众平台 ​

步骤二：启用开发者模式 ​

步骤三：获取 AppID 和 AppSecret ​

步骤四：配置服务器地址 ​

步骤五：安装微信插件 ​

步骤六：配置 OpenClaw ​

启动并验证 ​

消息类型支持 ​

自动回复配置 ​

客服会话管理 (Customer Service Session) ​

模板消息 (Template Message) ​

IP 白名单 ​

第二部分：微信小程序接入 ​

概述 ​

架构说明 ​

前提条件 ​

后端 API 集成 ​

用户认证流程 ​

小程序服务器域名配置 ​

重要限制与注意事项 ​

公众号消息限制 ​

小程序限制 ​

API 调用频率 ​

🇨🇳 微信生态合规与最佳实践 ​

ICP 备案 ​

内容安全 ​

数据存储合规 ​

微信云托管推荐 ​

环境变量参考 ​

下一步 ​

微信公众号/小程序 - 微信生态接入

概述：微信生态接入方式

第一部分：微信公众号（服务号）接入

前提条件

步骤一：登录微信公众平台

步骤二：启用开发者模式

步骤三：获取 AppID 和 AppSecret

步骤四：配置服务器地址

步骤五：安装微信插件

步骤六：配置 OpenClaw

启动并验证

消息类型支持

自动回复配置

客服会话管理 (Customer Service Session)

模板消息 (Template Message)

IP 白名单

第二部分：微信小程序接入

概述

架构说明

前提条件

后端 API 集成

用户认证流程

小程序服务器域名配置

重要限制与注意事项

公众号消息限制

小程序限制

API 调用频率

🇨🇳 微信生态合规与最佳实践

ICP 备案

内容安全

数据存储合规

微信云托管推荐

环境变量参考

下一步