OpenClaw连接微信教程

前言

微信是中国最主流的即时通讯工具，将 OpenClaw 连接到微信可以让你拥有一个私人 AI 助手，也能在群聊中为群友提供智能问答服务。本文将详细讲解微信接入的各种方式及其配置方法。

接入方式概览

由于微信没有官方开放的 Bot API，OpenClaw 通过第三方桥接方案来实现微信接入：

方式	原理	稳定性	风险等级
Web 协议 (UOS)	模拟网页微信登录	中等	中
Wechaty Puppet	通过 Wechaty 框架桥接	较高	低-中
iPad 协议	模拟 iPad 客户端	高	低
企业微信 API	使用企业微信官方接口	最高	最低

重要提示

注意：个人微信接入属于非官方方式，存在被限制登录的风险。
建议使用小号进行测试，切勿使用主力微信号。
企业微信 API 是官方支持的方式，适合企业级部署。

方式一：Wechaty 桥接（推荐）

Wechaty 是一个成熟的聊天机器人 SDK，OpenClaw 内置了对 Wechaty 的支持。

1.1 安装 Wechaty 依赖

确保你的系统已安装 Node.js 22+，然后安装 Wechaty：

npm install -g wechaty

1.2 选择 Puppet

Wechaty 通过 Puppet 来对接不同的微信协议：

Puppet	协议	费用	说明
wechaty-puppet-wechat4u	Web 协议	免费	功能受限，部分账号不支持
wechaty-puppet-padlocal	iPad 协议	付费	功能完整，推荐
wechaty-puppet-xp	Windows Hook	免费	需要 Windows 环境
wechaty-puppet-service	远程服务	按需	连接远程 Puppet 服务

免费方案使用 wechat4u：

npm install wechaty-puppet-wechat4u

1.3 配置 OpenClaw

编辑 ~/.config/openclaw/openclaw.json5：

{
  channels: {
    wechat: {
      enabled: true,
      // 桥接方式
      bridge: "wechaty",

      // Wechaty Puppet 配置
      puppet: {
        // puppet 名称
        name: "wechaty-puppet-wechat4u",
        // 如果使用付费 puppet，填入 token
        token: ""
      },

      // 触发方式
      trigger: {
        // 私聊是否自动回复（无需关键词）
        privateAutoReply: true,
        // 群聊触发关键词（需要以这些词开头才回复）
        groupKeywords: ["@AI", "问一下", "/ask"],
        // 群聊中是否需要 @Bot 才回复
        groupMentionRequired: true,
        // 是否响应自己发的消息
        selfMessage: false
      },

      // 回复配置
      reply: {
        // 群聊回复时是否引用原消息
        quoteReply: true,
        // 是否显示"正在输入"状态
        showTyping: true,
        // 长文本自动分割的字符数
        maxLength: 4000
      }
    }
  }
}

1.4 启动并扫码登录

配置完成后重启 OpenClaw：

openclaw restart

查看日志获取登录二维码：

openclaw logs -f --component channel:wechat

日志中会显示一个二维码（终端字符画形式）。用你要登录的微信号扫描该二维码，在手机上确认登录。

[INFO] [channel:wechat] 等待扫码登录...
[INFO] [channel:wechat] 请使用微信扫描以下二维码:
[INFO] [channel:wechat] ████████████████████████████████
[INFO] [channel:wechat] █                              █
[INFO] [channel:wechat] █  ▄▄▄▄▄ █ █ ▄ █▀▄▀ █ ▄▄▄▄▄  █
[INFO] [channel:wechat] █  ...（二维码内容）...         █
[INFO] [channel:wechat] ████████████████████████████████

扫码成功后：

[INFO] [channel:wechat] 扫码成功，等待确认...
[INFO] [channel:wechat] 登录成功! 当前账号: AI助手
[INFO] [channel:wechat] 联系人数量: 256, 群聊数量: 15

方式二：企业微信 API

企业微信提供了官方的 API 接口，更加稳定和安全。

2.1 创建企业微信应用

登录企业微信管理后台
进入 应用管理 → 自建应用 → 创建应用
填写应用名称、上传图标、选择可见范围
创建后记录 AgentId 和 Secret

2.2 获取必要信息

你需要以下信息：

参数	来源	示例
CorpId	我的企业 → 企业信息	`ww1234567890abcdef`
AgentId	应用管理 → 应用详情	`1000002`
Secret	应用管理 → 应用详情	`xxxxxxxxxxxxxxxxxxxx`
Token	接收消息 → API 接收	`your-token-string`
EncodingAESKey	接收消息 → API 接收	`your-encoding-aes-key`

2.3 配置回调地址

在应用的 接收消息 设置中，配置回调 URL：

https://your-domain.com/webhook/wechat-work/callback

OpenClaw 会自动处理企业微信的 URL 验证请求。

2.4 OpenClaw 配置

{
  channels: {
    wechatWork: {
      enabled: true,
      corpId: "ww1234567890abcdef",
      agentId: 1000002,
      secret: "your-app-secret",
      token: "your-callback-token",
      encodingAESKey: "your-encoding-aes-key",

      // 允许使用的用户/部门（空数组表示应用可见范围内所有人）
      allowedUsers: [],
      allowedDepartments: []
    }
  }
}

群聊配置详解

群聊触发规则

在群聊中，为了避免 Bot 频繁打扰，通常需要特定触发方式：

{
  channels: {
    wechat: {
      trigger: {
        groupMentionRequired: true,
        groupKeywords: ["@AI", "问一下"],
        // 仅在指定群聊中启用
        allowedGroups: ["技术讨论群", "AI助手测试群"],
        // 或者排除某些群
        ignoredGroups: ["家人群", "工作群"]
      }
    }
  }
}

群聊上下文管理

{
  channels: {
    wechat: {
      context: {
        // 群聊中每个用户独立上下文
        groupContextMode: "per-user",  // "per-user" | "shared"
        // 上下文保持时间（分钟）
        contextTimeout: 30,
        // 最大上下文消息轮数
        maxContextTurns: 20
      }
    }
  }
}

消息类型支持

OpenClaw 对微信不同消息类型的支持情况：

消息类型	接收	发送	说明
文本消息	支持	支持	完整支持
图片消息	支持	支持	可识别图片内容（需多模态模型）
语音消息	支持	不支持	自动转文字后处理
文件消息	支持	支持	支持文档分析
链接消息	支持	不支持	可提取链接内容
表情包	不支持	不支持	忽略处理
小程序	不支持	不支持	忽略处理
视频消息	部分	不支持	取决于 Puppet 能力

持久化登录

为了避免每次重启都需要重新扫码，OpenClaw 会自动保存登录会话：

{
  channels: {
    wechat: {
      // 会话数据保存路径
      sessionDir: "~/.openclaw/wechat-session/",
      // 会话刷新间隔（小时）
      sessionRefresh: 12
    }
  }
}

会话数据保存后，重启 OpenClaw 时会自动恢复登录状态，无需再次扫码。但如果长时间未活动（通常超过一周），会话可能会过期，需要重新扫码。

故障排查

扫码后无法登录

# 检查是否是账号受限
# 部分新注册或久不使用的账号可能无法使用 Web 协议
# 解决方案：更换为 iPad 协议或企业微信方式

# 检查网络连接
openclaw doctor

消息收发延迟

# 查看消息处理日志
openclaw logs --component channel:wechat --level debug

# 常见原因：
# 1. AI 模型响应慢 - 检查模型 API 延迟
# 2. 代理网络慢 - 优化代理配置
# 3. 消息队列积压 - 检查并发设置

群聊中不响应

确认以下几点：

Bot 账号在该群聊中
群聊名称在 allowedGroups 列表中（如果配置了的话）
消息是否满足触发条件（关键词或 @）
检查日志中是否有该群聊的消息记录

总结

微信接入是 OpenClaw 在中国场景下最实用的功能之一。几点建议：

个人使用：推荐 Wechaty + wechat4u（免费）方式快速体验
稳定需求：考虑付费 iPad 协议 Puppet，稳定性更好
企业场景：强烈推荐企业微信 API，官方支持且无封号风险
安全意识：使用非官方协议时用小号测试，做好风险评估