# 微信公众号

Source: https://langbot.app/docs/zh/usage/platforms/wxoa

通过微信开发者平台配置消息推送，将微信公众号接入 LangBot。

本教程使用微信公众平台完成账号注册和主体实名认证，在微信开发者平台配置应用密钥、消息推送和 API IP 白名单。

## 1. 注册公众号并完成主体实名认证

进入[微信公众平台](https://mp.weixin.qq.com/)。已有公众号可直接扫码登录；尚未注册时，点击「立即注册」，选择「公众号」，按提示完成注册。

进入「设置与开发 → 账号设置 → 账号详情」，找到页面底部的「主体信息」，点击「详情」。如果显示「待完善」，请先完成主体信息。

![账号详情页面底部的主体信息入口](https://langbot.app/docs/images/zh/deploy/bots/wxoa/account-details.png)

在主体信息页面点击「实名验证」，按照微信提示完成实名认证。

![主体信息页面的实名验证按钮](https://langbot.app/docs/images/zh/deploy/bots/wxoa/identity-verification.png)

> info:
>
> 这里需要完成的是「主体信息」中的实名验证。账号详情中还有「申请微信认证」「个人认证」等入口，请按截图进入主体信息页面操作。

## 2. 获取应用信息并创建 LangBot 机器人

前往[微信开发者平台](https://developers.weixin.qq.com/platform)，进入公众号设置，选择要接入的公众号，打开「基础信息」。页面包含 AppID、「开发密钥」以及「域名与消息推送配置」。

![微信开发者平台的公众号基础信息、开发密钥及消息推送入口](https://langbot.app/docs/images/zh/deploy/bots/wxoa/developer-platform.png)

在 LangBot 中新建机器人，选择「微信公众号」适配器，进入机器人配置页：

1. 复制微信开发者平台中的 **AppID**，填写到 LangBot 的「应用 ID」。
2. 在微信开发者平台的「开发密钥」区域点击 AppSecret 的「重置」，按提示获取密钥，填写到 LangBot 的「应用密钥」。首次使用时，如果按钮显示为「启用」，先按提示启用 AppSecret。
3. 点击 LangBot 的「保存并启用」，保存机器人并启用。

下面是 LangBot 适配器配置区域。图中的「令牌」和「消息加解密密钥」会在下一步与微信平台一起配置。

![LangBot 微信公众号适配器的回调地址及配置字段](https://langbot.app/docs/images/zh/deploy/bots/wxoa/langbot-adapter-settings.png)

## 3. 启用消息推送并配置回调

回到微信开发者平台，在「基础信息」页面下方的「域名与消息推送配置」区域，点击「消息推送」旁的「启用」。

在「配置消息推送」弹窗中按以下顺序填写，暂时不要点击「确定」：

1. **URL**：复制 LangBot 机器人配置页显示的完整「Webhook 回调地址」并粘贴。地址通常为 `https://你的域名/bots/机器人UUID`，请保留完整路径。
2. **Token**：自行设置一个符合微信页面要求的 Token，并将同一个值填入 LangBot 的「令牌」。两边必须完全一致。
3. **EncodingAESKey**：点击微信平台的「随机生成」，复制生成的值，填入 LangBot 的「消息加解密密钥」。
4. **消息加密**：选择「安全模式（推荐）」。
5. **数据格式**：选择 **XML**。

![微信开发者平台的配置消息推送弹窗](https://langbot.app/docs/images/zh/deploy/bots/wxoa/message-push.png)

两个平台的配置对应关系如下：

| 微信开发者平台        | LangBot                    |
| -------------- | -------------------------- |
| AppID          | 应用 ID                      |
| AppSecret      | 应用密钥                       |
| URL            | Webhook 回调地址（从 LangBot 复制） |
| Token          | 令牌                         |
| EncodingAESKey | 消息加解密密钥                    |

保持微信平台弹窗开启，回到 LangBot **再次保存机器人**。确认机器人已启用且配置成功应用后，再回到微信平台点击「确定」。微信会访问回调地址进行验证，通过后消息推送配置即完成。

> idea:
>
> Webhook 回调地址需要能够从公网访问，建议使用 HTTPS。自部署可参考[配置 HTTP 反向代理和 SSL](https://langbot.app/docs/zh/workshop/production/proxy-and-ssl.md)，将公网域名转发到 LangBot 服务。使用 HTTP 时需使用 80 端口，HTTPS 使用 443 端口。
>
> 如页面显示的仍是本地地址，请将实例 `data/config.yaml` 中的 `api.webhook_prefix` 设置为公网地址，例如 `https://bot.example.com`，重启 LangBot 后重新复制回调地址。[LangBot Cloud](https://space.langbot.app/cloud) 提供可直接使用的公网回调地址。

### 常见错误：请求失败，HTTP 返回非 200

如果点击微信平台的「确定」后出现此提示，请依次检查：

- **URL 正确且公网可达**：使用 LangBot 显示的完整回调地址，包含 `/bots/机器人UUID`。本机地址、内网地址或仅填写域名首页均不能作为此机器人的回调地址。
- **机器人已保存并启用**：填写 Token 和 EncodingAESKey 后，需要先在 LangBot 保存，再在微信平台确认。
- **字段一致**：Token、EncodingAESKey 必须与 LangBot 完全一致；AppID、AppSecret 必须属于当前选择的公众号，复制时不要带入多余空格或换行。
- **转发配置有效**：检查反向代理或隧道是否仍在运行、HTTPS 证书是否有效，以及回调是否被登录验证或访问控制拦截。

旧界面可能显示「系统发生错误，请稍后重试」，同样可以按上述项目检查，并查看 LangBot 的机器人日志定位错误。

## 4. 配置 API IP 白名单

在微信开发者平台「基础信息 → 开发密钥」中找到 **API IP 白名单**，填入部署 LangBot 的服务器访问微信 API 时使用的**公网出站 IP**，保存配置。截图中未启用 AppSecret 时，该项会提示「启用 AppSecret 后，可配置」。

可以从服务器或云平台的网络配置中查找出站 IP。如果 LangBot 通过 NAT 网关或代理访问微信 API，应填写实际出口的公网 IP；存在多个出口时，按微信页面要求将它们加入白名单。

> info:
>
> 回调 URL 用于微信向 LangBot 推送事件；API IP 白名单用于 LangBot 调用微信接口。使用反向代理或 Cloudflare Tunnel 提供回调地址时，白名单仍应填写 LangBot 访问微信 API 的出站 IP，而不是回调域名解析出的 CDN 地址。

## 接入模式与后续使用

在新版「微信公众号」适配器的「接入模式」中选择回复方式，保存后生效。已有机器人不会自动切换模式；默认值仍为 `drop`。旧版适配器不提供 `auto`，请使用新版适配器。

| 接入模式（Mode） | 回复机制                                  | 适用场景                            |
| ---------- | ------------------------------------- | ------------------------------- |
| `auto`     | 先返回加载提示，后台生成回复；通过客服接口发送，受限时改为下一条消息领取。 | 希望生成完成后直接收到回复，或不确定账号是否具有客服接口权限。 |
| `passive`  | 先返回加载提示，后台生成回复；用户再发任意内容领取，不调用客服接口。    | 没有客服接口权限，或希望始终使用领取方式。           |
| `drop`（默认） | 在当前微信回调内直接返回回复，不调用客服接口，也不会自动转为领取方式。   | 能在 5 秒内完成的快速回复；不适合耗时较长的 AI 生成。  |

### auto 如何自动选择回复方式？

`auto` 不会预先查询或要求填写账号认证状态，而是在处理器发送回复时，根据微信客服接口的实际返回结果决定：

1. 收到用户消息后，先返回加载提示，处理器在后台继续运行。
2. 处理器生成并发送回复时，LangBot 尝试调用客服接口。成功后，用户直接收到回复，不必再发消息领取。
3. 微信明确返回无接口权限（`48001`）、超过回复时限（`45015`）、下发额度用尽（`45047`）或接收者未关注（`43004`）时，LangBot 缓存回复。用户随后向公众号发送任意内容，即可通过这次回调领取。

这个判断针对每次回复，不会把账号永久标记为“无权限”。AppID、AppSecret、IP 白名单错误以及网络异常等其他失败会记录报错，不会一律当作权限不足并回退。收到加载提示只能说明消息已进入处理流程；排查未收到回答时，还需要查看处理器执行日志。

### 认证与回复窗口有什么关系？

**被动回调和客服消息是两种不同的回复渠道。** 微信要求被动回调在 **5 秒内**响应；认证不会延长这个时间。`drop` 使用的就是被动回调，不能把微信重试当成稳定的 15 秒生成窗口。[被动回复官方说明](https://developers.weixin.qq.com/doc/service/guide/product/message/Passive_user_reply_message.html)

客服接口允许在回调结束后发送回复。微信官方当前标明，公众号、服务号需企业主体已认证才能调用；前文的「主体实名验证」不等于取得客服接口权限。具体以账号实际权限和微信接口返回为准。

| 用户操作                  | 客服消息下发额度 | 有效期   |
| --------------------- | -------- | ----- |
| 发送消息                  | 5 条      | 48 小时 |
| 点击符合条件的自定义菜单、关注、扫描二维码 | 3 条      | 1 分钟  |

这些是微信客服接口的限制，不是 AI 的生成超时设置，也不是所有事件都享有 48 小时窗口。规则可能调整，请以[微信客服消息官方文档](https://developers.weixin.qq.com/doc/service/api/customer/message/api_sendcustommessage)为准。

### 如何领取回复和设置加载提示？

在 `passive` 或 `auto` 回退后，用户发送的下一条消息用于领取上一轮回答，**不会同时作为新的问题交给处理器**。如果回答尚未生成，仍会返回加载提示；稍后再发送任意内容即可。领取完成后，再发送新的问题。

`LoadingMessage` 对 `auto` 和 `passive` 都有效，对 `drop` 无效。可以按模式修改，例如：

- `auto`：「正在处理，请稍候。若未收到回复，请稍后发送任意内容领取。」
- `passive`：「AI 正在思考中，请稍后发送任意内容获取回复。」

将加载提示留空时，LangBot 只向微信确认接收，不发送可见的加载消息。待领取回复保存在内存中，重启 LangBot 或重新加载机器人配置会清空，因此请在修改配置后重新发起对话。三种模式仍受微信消息内容和长度限制。

### 连接处理器

完成平台配置后，在 LangBot 的「事件路由」中将「收到消息」连接到需要使用的流水线、Agent 或插件处理器，再关注公众号并发送消息。

接入模式只决定回复如何送达，不会自动把 Agent 的所有文本输出发送到微信。使用 Agent 时，请批准「回复当前会话」工具，并在指令中要求使用该工具回复；使用插件处理器时，需要插件调用回复接口。