1. 引言

个人微信自动化项目里，登录往往比发消息更折磨。搜索词通常是「个人微信扫码登录API」「微信掉线重连」「微信设置回调地址」。登录不稳，后面所有能力都会假死。

2. 登录最短路径

1. 控制台获取 Token
2. 获取登录二维码
3. 执行登录 / 确认扫码结果
4. 设置 Webhook 回调地址
5. 发一条测试消息验证在线

个微登录与在线检查走 GeWe API 登录模块、账号管理模块。企微是另一套设备模型，走 QIWe API，不要把个微的 appId 当成企微 guid 用。

3. 状态机

INIT → WAIT_LOGIN → ONLINE → DEGRADED → RECONNECTING → ONLINE
                                 ↘ OFFLINE → ALERT

实践建议：

• 定时检查是否在线，不要只在发送失败时才发现掉线
• 掉线告警通知值班
• 重连失败指数退避，避免把登录接口打满
• OFFLINE 时拒绝新的群发，任务失败回传
• 重连成功后客服场景通常只处理增量消息

4. 回调要在登录后立刻配

未设置回调地址，等于只能发不能收。登录成功后把回调 URL 写入通道配置，并用测试消息验证。

代理、Aid 本地代理、弹框登录等细节，以 GeWe API文档（http://doc.geweapi.com/）登录模块为准。先走通「二维码 → 在线 → 设置回调 → 发 filehelper」。

5. 代码示意

def ensure_online(app_id: str) -> None:
    if check_online(app_id):
        return
    alert("个微掉线，开始重连")
    reconnect(app_id)
    if not check_online(app_id):
        raise RuntimeError("reconnect failed")

发送前调用 ensure_online，比失败后再重试更干净。

6. 安全与运维

• GeWe API Token 只放服务端
• 二维码不要输出到前端公开页面
• 登录设备和业务服务器的网络环境尽量稳定
• 和 QIWe API 凭证分环境、分密钥管理

7. 总结

个人微信API登录要当成基础设施：状态可观测、掉线可告警、重连有冷却、回调必配置。这层稳了，机器人和私域才跑得住。