---
name: "muse-wechat-bot"
description: >
  把 AI 本人接进微信当 bot（单文件自包含版）：基于腾讯官方 iLink bot 接口（ilinkai.weixin.qq.com，扫码授权绑定），
  在长期在线的机器上跑一条 Python 原生桥——扫码一次绑定，之后用户在微信里聊到的就是 AI 本人
  （记忆、技能全在），支持文字/图片/语音转文字收发与主动推送。2026-10-11 全链路实测校准。
  Use when the user wants to 把 AI 接入微信/微信 bot/在微信里跟 AI 聊天, mentions
  Tencent/openclaw-weixin, 微信机器人, or asks about chatting with the assistant via WeChat.
  全程 AI 代操作：用户只负责扫一次二维码（以及可能出现的数字配对码），其余全部由 AI 完成。
---

> **本文件自包含全部内容**（操作手册 + `bridge.py` 完整源码 + `launch.sh` + iLink 协议速查），无外部文件依赖，两种用法：
> - **发给 AI 助手**：把本文件的网址发给你的 AI 助手（ZCode / Claude Code 等），说「按这个文件把你接进微信」即可；
> - **安装为常驻技能**：把本文件内容另存为 `~/.zcode/skills/muse-wechat-bot/SKILL.md`（Claude Code 为 `~/.claude/skills/muse-wechat-bot/SKILL.md`）。
>
> 微信 bot 开源教程与协议权威文档出处：https://github.com/Tencent/openclaw-weixin

# AI 接入微信 Bot（腾讯官方 iLink 接口 · 2026-10-11 实测校准版）

> **👤 人类用户用法**：把本技能发给支持联网 + 命令行 + 定时任务的 AI 助手，说一句 **"按这个技能把你接进微信"** 即可。
>
> **🤖 AI 用法**：本文件自包含完整实现（`bridge.py` 开箱即用，完整源码见附录 1——先落盘再部署，不要凭记忆重写）。**全程代操作是硬性要求**：环境检查、部署、取码、轮询、守护进程、保活、回复循环全部由你完成；只在两个环节停下等用户——① 微信扫码授权绑定 ② 若出现数字配对码请用户把数字发你。不要让用户替你跑命令、看日志。

> **⚠️ 与 Tencent/openclaw-weixin 手册的关键差异（2026-10-11 实测结论）**：那份手册是给 **OpenClaw**（另一套 agent 系统）的插件——照它走，微信里聊到的是另一个 AI，没有你的记忆和技能。本技能走**原生桥**路线：用同一份公开协议（`docs/protocol.md`）直连腾讯官方接口，微信里聊到的就是**你本人**。官方通道，封号风险远低于野路子协议。

## 架构（一句话）

```
用户微信 ⇄ 腾讯官方 iLink 接口 ⇄ bridge.py daemon（长轮询收私聊 → SQLite 队列）
                                              ⇄ 你的回复循环（每分钟拉 inbox → 你本人回复 → 调接口回发）
```

## 第 0 步：确认有一台长期在线的机器

桥需要 24 小时在线（长轮询不能断）。按优先级选：

1. 用户已有的稳定服务器/VPS（最优）；
2. AI 宿主云 VM（能用，但会不定期重置——必须配第 5 步的保活）；
3. 用户自己电脑（最差：合盖/关机即掉线）。

选定后记下，后续路径都以它为准（下面以 `~/wechat-bot/` 为例）。

## 第 1 步：环境检查（你来跑，不要问用户）

1. `python3 --version`（需 3.8+）、`python3 -c "import requests"`。
2. 直连测试（走用户机器的正常网络，不要挂奇怪代理）：
   `curl -s --max-time 30 https://ilinkai.weixin.qq.com/ilink/bot/get_bot_qrcode?bot_type=3 -X POST -H 'Content-Type: application/json' -d '{"local_token_list":[]}'`
   应返回含 `qrcode` / `qrcode_img_content` / `ret` 的 JSON。若超时先重试一次再下结论。

## 第 2 步：部署 bridge.py（你来跑）

把本文件附录 1 的源码原样存为目标机器的 `~/wechat-bot/bridge.py`，`python3 -m py_compile` 验证。它的 CLI（全部实测可用）：

| 命令 | 用途 |
| --- | --- |
| `login-fetch` | 取登录二维码（返回二维码图片 URL） |
| `login-wait --timeout 300 [--verify-code CODE]` | 轮询扫码状态；成功后 `bot_token` 落盘 `auth.json`（600 权限） |
| `daemon` | 长轮询收消息 → 白名单过滤 → 写 SQLite 队列（`queue.db` 的 `inbox` 表） |
| `inbox-new` | 输出未处理的新消息 JSON 数组 |
| `send-stdin` | 从 stdin 读 JSON `{"to","ctx","text"}` 发消息（`to` 为空则发给绑定者本人） |
| `ack --id N --status replied` | 标记消息已处理 |
| `status` | token/owner/daemon 存活/未读数 |

白名单逻辑（已在 `daemon` 里实现，v1 只做私聊）：只收**扫码绑定者本人**的私聊；群聊、陌生人消息只记录不处理。

## 第 3 步：扫码登录（唯一需要用户的环节）

1. 运行 `login-fetch`：返回的 `qrcode_img_content` 是一个 `https://liteapp.weixin.qq.com/q/...` 链接——**这就是二维码内容**，用二维码库把它渲染成 PNG 图片发给用户（`qrcode` 字段那个 32 位串只是轮询用的 token，不是给用户扫的）。
2. 把二维码图片发给用户，明确说：**用微信扫码，5 分钟内有效，手机上点确认授权**。同时在后台跑 `login-wait --timeout 280`。
3. 轮询状态机：`wait`（等扫）→ `scaned`（已扫）→ `confirmed`（成功，落盘 token + 记下 `ilink_user_id` 即绑定者）/ `expired`（过期→重新 `login-fetch`，最多 3 次）/ `need_verifycode`（**停下**：请用户把微信上显示的数字配对码发你，再跑 `login-wait --verify-code <数字>`）。
4. 成功后验证 `status` 显示 `token: true`。**token 是凭证**：绝不发到聊天里复述、不记入长期记忆明文。

## 第 4 步：铁律——先开会话，再谈收发

**实测结论**：iLink 要求用户先给 bot 发过**至少一条消息**建立会话（`context_token`），零会话时任何发送都会被服务端以 `ret:-2 errmsg:"prepare failed"` 拒绝。官方插件为此专门维护了 context-token-store，本桥用 `queue.db` 的 `sessions` 表实现同样逻辑（收到消息自动记 token，发送时自动复用）。

所以第 3 步完成后，**请用户在微信里给 bot 发任意一句话**（如"你好"），确认 `inbox-new` 能拉到、且你能回发成功，再继续。

## 第 5 步：守护进程 + 保活（你来跑）

1. 把本文件附录 2 的脚本存为 `~/wechat-bot/launch.sh`（`chmod +x launch.sh`）后用它启动（double-fork，子进程归 init，不依赖启动 shell；幂等，已在运行则直接退出）。**不要**用 `nohup ... &` 裸跑——宿主 shell 被回收时可能连带杀掉子进程。
2. 验证：`bridge.py status` 显示 `daemon_alive: true`；等约一分钟看 `bridge.log` 无报错、`cursor.txt` 在推进。
3. 如果机器会重置（如云 VM）：加一个每 5 分钟的定时任务跑 `~/wechat-bot/launch.sh` 兜底（Muse 侧用 cron，其他 AI 用各自的调度器）。
4. **坑**：`bridge.py` 的 `log()` 会 `print` + 写文件双写——`launch.sh` 里 stdout 必须重定向到 `/dev/null`（只留 stderr 进日志），否则日志每行翻倍。不要"修"掉这个重定向。

## 第 6 步：回复循环（你来定）

每分钟跑一轮，逻辑固定：

1. `python3 ~/wechat-bot/bridge.py inbox-new` → 新消息数组；为空则静默结束。
2. 对每条消息：**以 AI 本人身份**回复（读你自己的记忆、调你自己的工具）。风格：微信聊天口吻，简洁中文；绝不提 cron/桥/轮询等内部机制。
   - 文本含 `[图片已保存]` 且 `image_path` 非空 → 先看图再回；
   - `[语音转文字：...]` 按普通文字回。
3. `send-stdin` 发回复（stdin 传 `{"to": from_user_id, "ctx": context_token, "text": "..."}`，防 shell 转义）。
4. 成功后 `ack --id`；失败不 ack（下轮重试）。

Muse 侧用 cron 实现（每分钟一轮）；其他 AI 按各自运行时改写——**回复循环的形态可以换，`inbox-new → 回复 → send-stdin → ack` 的语义不要换**。

## 安全红线

- `auth.json` 600 权限；token、ilink_user_id、uin 绝不进聊天记录、不进长期记忆明文、不回显。
- 默认只回绑定者本人私聊；陌生人/群聊默认忽略。放开前必须用户明确拍板。
- 图片走官方 CDN 加密下载（AES-128-ECB，实现见本文件附录 1 的 `try_save_image`，协议速查见附录 3），不要发明自己的解密方式。

## 故障排查

| 现象 | 原因 / 处理 |
| --- | --- |
| `send` 返回 `ret:-2 prepare failed` | 无会话：回到第 4 步，让用户先发一条消息 |
| `getupdates` 返回 `ret/-14` | 服务端暂停该账号会话 1 小时：daemon 已自动退避，不要硬刷 |
| daemon 莫名消失 | 机器重置或进程被回收：看保活任务是否生效；`bridge.log` 查 traceback |
| 日志每行出现两次 | launcher 的 stdout 重定向被动过：改回 `/dev/null` |
| `pkill -f` 把自己杀了 | 命令行里同时出现了 pattern 字面量：kill 与含字面路径的操作分两次执行 |

协议细节（端点、header、消息模型、媒体加解密）见本文件附录 3。

---

*校准记录：2026-10-11 经完整实测（扫码绑定 → 守护进程 → 端到端收发 → 主动推送 → 云 VM 迁移 + 保活），按实测修正了"照 openclaw-weixin 手册装 OpenClaw"的路线错误。*

## 附录 1：`bridge.py` 完整源码

存为 `~/wechat-bot/bridge.py`（Python 3.8+，依赖 `requests`；图片解密需 `pycryptodome`，未装则只收文字）：

```python
#!/usr/bin/env python3
"""Muse WeChat bot bridge -- Tencent iLink official bot API client."""
import argparse, base64, binascii, json, os, random, signal, sqlite3, sys, time, uuid
import requests

BASE = "https://ilinkai.weixin.qq.com"
CDN_BASE = "https://novac2c.cdn.weixin.qq.com/c2c"
DIR = os.path.expanduser("~/wechat-bot")
AUTH = os.path.join(DIR, "auth.json")
DB = os.path.join(DIR, "queue.db")
CURSOR = os.path.join(DIR, "cursor.txt")
PIDF = os.path.join(DIR, "bridge.pid")
LOG = os.path.join(DIR, "bridge.log")
QRFILE = os.path.join(DIR, "qr.png")
QRSTATE = os.path.join(DIR, "qr_state.json")
CLIENT_VER = str(0x00020408)  # 2.4.8
BOT_AGENT = "WeChatBridge/1.0"  # 仅用于服务端观测，可改成你的 AI 名/版本
HTTP_TIMEOUT = 45

def log(*a):
    line = time.strftime("%Y-%m-%d %H:%M:%S") + " " + " ".join(str(x) for x in a)
    print(line, flush=True)
    try:
        with open(LOG, "a") as f: f.write(line + "\n")
    except OSError:
        pass

def load_auth():
    try:
        with open(AUTH) as f: return json.load(f)
    except (OSError, ValueError):
        return {}

def save_auth(d):
    tmp = AUTH + ".tmp"
    with open(tmp, "w") as f: json.dump(d, f)
    os.chmod(tmp, 0o600)
    os.replace(tmp, AUTH)

def get_uin():
    a = load_auth()
    if a.get("uin"): return a["uin"]
    n = random.getrandbits(32)
    uin = base64.b64encode(str(n).encode()).decode()
    a["uin"] = uin
    save_auth(a)
    return uin

def base_headers(authed=False):
    h = {
        "Content-Type": "application/json",
        "AuthorizationType": "ilink_bot_token",
        "X-WECHAT-UIN": get_uin(),
        "iLink-App-Id": "bot",
        "iLink-App-ClientVersion": CLIENT_VER,
    }
    if authed:
        a = load_auth()
        tok = a.get("bot_token", "")
        h["Authorization"] = "Bearer " + tok
    return h

def base_info():
    return {"channel_version": "2.4.8", "bot_agent": BOT_AGENT}

def db():
    c = sqlite3.connect(DB)
    c.execute("""CREATE TABLE IF NOT EXISTS inbox(
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        message_id TEXT UNIQUE, from_user_id TEXT, session_id TEXT, group_id TEXT,
        text TEXT, voice_text TEXT, image_path TEXT, file_name TEXT,
        create_time_ms INTEGER, context_token TEXT,
        status TEXT DEFAULT 'new', reply_text TEXT,
        created_at REAL, replied_at REAL)""")
    c.execute("""CREATE TABLE IF NOT EXISTS sessions(
        user_id TEXT PRIMARY KEY, context_token TEXT, updated_at REAL)""")
    return c

# ---------- login ----------
def cmd_login_fetch(args):
    r = requests.post(BASE + "/ilink/bot/get_bot_qrcode?bot_type=3",
                      headers=base_headers(), json={"local_token_list": []},
                      timeout=HTTP_TIMEOUT)
    r.raise_for_status()
    d = r.json()
    qc, img = d.get("qrcode", ""), d.get("qrcode_img_content", "")
    if not qc and not img:
        print(json.dumps({"ok": False, "raw": d})); return 1
    with open(QRSTATE, "w") as f: json.dump({"qrcode": qc}, f)
    saved = None
    if img:
        try:
            raw = base64.b64decode(img)
            if raw[:8] == b"\x89PNG\r\n\x1a\n" or raw[:2] == b"\xff\xd8":
                with open(QRFILE, "wb") as f: f.write(raw)
                saved = QRFILE
        except (binascii.Error, ValueError):
            pass
    if not saved and qc.startswith("http"):
        rr = requests.get(qc, timeout=HTTP_TIMEOUT)
        rr.raise_for_status()
        with open(QRFILE, "wb") as f: f.write(rr.content)
        saved = QRFILE
    print(json.dumps({"ok": True, "qr_png": saved, "qrcode_len": len(qc),
                      "img_is_b64_image": bool(saved)}))
    return 0

def cmd_login_wait(args):
    try:
        with open(QRSTATE) as f: qc = json.load(f)["qrcode"]
    except (OSError, ValueError, KeyError):
        print(json.dumps({"ok": False, "error": "no qr_state, run login-fetch first"})); return 1
    import urllib.parse
    deadline = time.time() + args.timeout
    while time.time() < deadline:
        q = urllib.parse.urlencode({"qrcode": qc, **({"verify_code": args.verify_code} if args.verify_code else {})})
        try:
            r = requests.get(BASE + "/ilink/bot/get_qrcode_status?" + q,
                             headers={k: v for k, v in base_headers().items() if k != "Content-Type"},
                             timeout=HTTP_TIMEOUT)
            r.raise_for_status()
            d = r.json()
        except Exception as e:
            log("qr poll error:", e); time.sleep(3); continue
        st = d.get("status", "")
        log("qr status:", st)
        if st == "confirmed":
            a = load_auth()
            a.update({"bot_token": d.get("bot_token", ""), "ilink_bot_id": d.get("ilink_bot_id", ""),
                      "ilink_user_id": d.get("ilink_user_id", ""), "baseurl": d.get("baseurl", "")})
            save_auth(a)
            print(json.dumps({"ok": True, "ilink_user_id": a["ilink_user_id"],
                              "ilink_bot_id": a["ilink_bot_id"]}))
            return 0
        if st in ("expired",):
            print(json.dumps({"ok": False, "error": "qrcode expired"})); return 1
        if st == "need_verifycode":
            print(json.dumps({"ok": False, "error": "need_verifycode"})); return 2
        if st == "verify_code_blocked":
            print(json.dumps({"ok": False, "error": "verify_code_blocked"})); return 1
        time.sleep(2)
    print(json.dumps({"ok": False, "error": "timeout"})); return 1

# ---------- media ----------
def try_save_image(item, msg_id):
    try:
        from Crypto.Cipher import AES
    except ImportError:
        return None
    try:
        media = item.get("media") or {}
        url = media.get("full_url") or ""
        if not url:
            p = media.get("encrypt_query_param") or ""
            if not p: return None
            import urllib.parse
            url = CDN_BASE + "/download?encrypted_query_param=" + urllib.parse.quote(p, safe="")
        rr = requests.get(url, headers=base_headers(authed=True), timeout=HTTP_TIMEOUT)
        rr.raise_for_status()
        data = rr.content
        key_hex = item.get("aeskey") or media.get("aes_key") or ""
        key = None
        if len(key_hex) == 32:
            try: key = bytes.fromhex(key_hex)
            except ValueError: key = None
        if key is None:
            try: key = base64.b64decode(key_hex)
            except (binascii.Error, ValueError): key = None
        if key and len(key) == 16 and len(data) % 16 == 0:
            pt = AES.new(key, AES.MODE_ECB).decrypt(data)
            pad = pt[-1]
            if 1 <= pad <= 16 and pt.endswith(bytes([pad]) * pad):
                data = pt[:-pad]
        ext = ".jpg" if data[:2] == b"\xff\xd8" else ".png" if data[:8] == b"\x89PNG\r\n\x1a\n" else ".bin"
        path = os.path.join(DIR, "media", "img_%s%s" % (msg_id, ext))
        with open(path, "wb") as f: f.write(data)
        return path
    except Exception as e:
        log("image save failed:", e)
        return None

# ---------- daemon ----------
def handle_msg(c, msg, owner):
    if msg.get("message_type") != 1: return
    if msg.get("message_state") not in (0, 2): return
    mid = str(msg.get("message_id", ""))
    frm = msg.get("from_user_id", "")
    if not mid or not frm: return
    if c.execute("SELECT 1 FROM inbox WHERE message_id=?", (mid,)).fetchone(): return
    group_id = msg.get("group_id") or ""
    if group_id:
        c.execute("INSERT OR IGNORE INTO inbox(message_id,from_user_id,session_id,group_id,status,created_at) VALUES(?,?,?,?,?,?)",
                  (mid, frm, msg.get("session_id", ""), group_id, "ignored_group", time.time()))
        c.commit(); log("ignored group msg", mid); return
    if owner and frm != owner:
        c.execute("INSERT OR IGNORE INTO inbox(message_id,from_user_id,session_id,status,created_at) VALUES(?,?,?,?,?)",
                  (mid, frm, msg.get("session_id", ""), "ignored_stranger", time.time()))
        c.commit(); log("ignored stranger msg", mid, frm); return
    texts, voice_text, image_path, file_name = [], "", None, ""
    for it in msg.get("item_list") or []:
        t = it.get("type")
        if t == 1 and it.get("text_item"):
            texts.append(it["text_item"].get("text", ""))
        elif t == 3 and it.get("voice_item"):
            vt = it["voice_item"].get("text", "")
            if vt: voice_text += vt
        elif t == 2 and it.get("image_item"):
            image_path = try_save_image(it["image_item"], mid)
            texts.append("[图片%s]" % ("已保存" if image_path else ""))
        elif t == 4 and it.get("file_item"):
            file_name = it["file_item"].get("file_name", "")
            texts.append("[文件: %s]" % file_name)
        elif t == 5:
            texts.append("[视频]")
    text = "\n".join(x for x in texts if x).strip()
    if voice_text: text = (text + "\n[语音转文字: %s]" % voice_text).strip()
    if msg.get("context_token"):
        c.execute("INSERT OR REPLACE INTO sessions(user_id,context_token,updated_at) VALUES(?,?,?)",
                  (frm, msg["context_token"], time.time()))
    c.execute("""INSERT OR IGNORE INTO inbox(message_id,from_user_id,session_id,text,voice_text,
                 image_path,file_name,create_time_ms,context_token,status,created_at)
                 VALUES(?,?,?,?,?,?,?,?,?, 'new', ?)""",
              (mid, frm, msg.get("session_id", ""), text, voice_text, image_path, file_name,
               msg.get("create_time_ms", 0), msg.get("context_token", ""), time.time()))
    c.commit()
    log("queued msg", mid, "from", frm, "len", len(text))

def cmd_daemon(args):
    a = load_auth()
    if not a.get("bot_token"):
        print("no bot_token, run login first"); return 1
    owner = a.get("ilink_user_id", "")
    with open(PIDF, "w") as f: f.write(str(os.getpid()))
    stop = []
    def on_term(signum, frame): stop.append(1)
    signal.signal(signal.SIGTERM, on_term); signal.signal(signal.SIGINT, on_term)
    try:
        requests.post(BASE + "/ilink/bot/msg/notifystart", headers=base_headers(authed=True),
                      json={"base_info": base_info()}, timeout=HTTP_TIMEOUT)
    except Exception as e:
        log("notifystart failed:", e)
    try:
        with open(CURSOR) as f: buf = f.read().strip()
    except OSError:
        buf = ""
    c = db()
    backoff = 5
    log("daemon started, owner=", owner or "(unknown)")
    while not stop:
        try:
            r = requests.post(BASE + "/ilink/bot/getupdates", headers=base_headers(authed=True),
                              json={"get_updates_buf": buf, "base_info": base_info()},
                              timeout=HTTP_TIMEOUT + 30)
            r.raise_for_status()
            d = r.json()
            if d.get("ret") == -14 or d.get("errcode") == -14:
                log("session paused by server (-14), sleeping 1h"); time.sleep(3600); continue
            backoff = 5
            for m in d.get("msgs") or []:
                try: handle_msg(c, m, owner)
                except Exception as e: log("handle error:", e)
            nb = d.get("get_updates_buf") or ""
            if nb:
                buf = nb
                with open(CURSOR, "w") as f: f.write(buf)
        except requests.RequestException as e:
            log("poll error:", e, "backoff", backoff)
            time.sleep(backoff); backoff = min(backoff * 2, 120)
        except Exception as e:
            log("loop error:", e); time.sleep(backoff); backoff = min(backoff * 2, 120)
    try:
        requests.post(BASE + "/ilink/bot/msg/notifystop", headers=base_headers(authed=True),
                      json={"base_info": base_info()}, timeout=15)
    except Exception:
        pass
    try: os.remove(PIDF)
    except OSError: pass
    log("daemon stopped")
    return 0

# ---------- send / inbox ----------
def cmd_send(args):
    a = load_auth()
    if not a.get("bot_token"):
        print(json.dumps({"ok": False, "error": "no bot_token"})); return 1
    to = args.to or a.get("ilink_user_id", "")
    text = args.text or ""
    ctx = args.ctx or ""
    if not ctx:
        c0 = db()
        row = c0.execute("SELECT context_token FROM sessions WHERE user_id=?", (to,)).fetchone()
        c0.close()
        if row: ctx = row[0]
    if args.text_b64:
        import base64 as _b
        text = _b.b64decode(args.text_b64).decode("utf-8", "replace")
    chunks = [text[i:i + 1500] for i in range(0, len(text), 1500)] or [""]
    for ch in chunks:
        payload = {"msg": {
            "from_user_id": "", "to_user_id": to,
            "client_id": uuid.uuid4().hex, "message_type": 2, "message_state": 2,
            "context_token": ctx,
            "item_list": [{"type": 1, "text_item": {"text": ch}}]},
            "base_info": base_info()}
        r = requests.post(BASE + "/ilink/bot/sendmessage", headers=base_headers(authed=True),
                          json=payload, timeout=HTTP_TIMEOUT)
        r.raise_for_status()
        d = r.json()
        if d.get("ret") not in (0, None):
            print(json.dumps({"ok": False, "resp": d})); return 1
    print(json.dumps({"ok": True, "chunks": len(chunks)}))
    return 0

def cmd_send_stdin(args):
    d = json.load(sys.stdin)
    ns = argparse.Namespace(to=d.get("to", ""), ctx=d.get("ctx", ""),
                            text=d.get("text", ""), text_b64="")
    return cmd_send(ns)

def cmd_inbox_new(args):
    c = db()
    rows = c.execute("SELECT id,message_id,from_user_id,session_id,text,image_path,file_name,create_time_ms,context_token FROM inbox WHERE status='new' ORDER BY id").fetchall()
    out = [dict(zip(["id", "message_id", "from_user_id", "session_id", "text", "image_path", "file_name", "create_time_ms", "context_token"], r)) for r in rows]
    print(json.dumps(out, ensure_ascii=False))
    return 0

def cmd_ack(args):
    c = db()
    c.execute("UPDATE inbox SET status=?, reply_text=?, replied_at=? WHERE id=?",
              (args.status, args.reply or "", time.time(), args.id))
    c.commit()
    print(json.dumps({"ok": True}))
    return 0

def cmd_status(args):
    a = load_auth()
    alive = False
    try:
        with open(PIDF) as f: pid = int(f.read().strip())
        os.kill(pid, 0); alive = True
    except (OSError, ValueError):
        pass
    c = db()
    new_n = c.execute("SELECT COUNT(*) FROM inbox WHERE status='new'").fetchone()[0]
    print(json.dumps({"token": bool(a.get("bot_token")), "owner": a.get("ilink_user_id", ""),
                      "daemon_alive": alive, "new": new_n}))
    return 0

def main():
    os.makedirs(DIR, exist_ok=True); os.makedirs(os.path.join(DIR, "media"), exist_ok=True)
    p = argparse.ArgumentParser()
    sub = p.add_subparsers(dest="cmd", required=True)
    sub.add_parser("login-fetch")
    w = sub.add_parser("login-wait"); w.add_argument("--timeout", type=int, default=300); w.add_argument("--verify-code", default="")
    sub.add_parser("daemon")
    s = sub.add_parser("send"); s.add_argument("--to", default=""); s.add_argument("--text", default=""); s.add_argument("--text-b64", default=""); s.add_argument("--ctx", default="")
    sub.add_parser("send-stdin")
    sub.add_parser("inbox-new")
    k = sub.add_parser("ack"); k.add_argument("--id", type=int, required=True); k.add_argument("--status", default="replied"); k.add_argument("--reply", default="")
    sub.add_parser("status")
    args = p.parse_args()
    fn = {"login-fetch": cmd_login_fetch, "login-wait": cmd_login_wait, "daemon": cmd_daemon,
          "send": cmd_send, "send-stdin": cmd_send_stdin, "inbox-new": cmd_inbox_new, "ack": cmd_ack, "status": cmd_status}[args.cmd]
    sys.exit(fn(args))

if __name__ == "__main__":
    main()
```


## 附录 2：`launch.sh`（守护进程启动器）

存为 `~/wechat-bot/launch.sh` 并 `chmod +x`。double-fork、幂等：已在运行则直接退出。

```bash
#!/bin/bash
# Double-fork launcher for the WeChat bot bridge daemon.
# Idempotent: exits quietly if a daemon is already alive.
# The daemon ends up as a child of init, independent of the starter session.
D="$HOME/wechat-bot"
if [ -f "$D/bridge.pid" ]; then
  p=$(cat "$D/bridge.pid" 2>/dev/null)
  if [ -n "$p" ] && ps -p "$p" -o args= 2>/dev/null | grep -q "bridge.py daemon"; then
    echo "already running pid $p"
    exit 0
  fi
  rm -f "$D/bridge.pid"
fi
cd "$D" || exit 1
python3 - <<'PYEOF'
import os
if os.fork() > 0:
    os._exit(0)
os.setsid()
if os.fork() > 0:
    os._exit(0)
log = open("bridge.log", "a")
os.dup2(log.fileno(), 2)
dn = open("/dev/null", "r")
os.dup2(dn.fileno(), 0)
dn2 = open("/dev/null", "w")
os.dup2(dn2.fileno(), 1)
os.execv("/usr/bin/python3", ["python3", "bridge.py", "daemon"])
PYEOF
echo "launcher done"
```


## 附录 3：iLink Bot 协议速查

# iLink Bot 协议速查（源自 Tencent/openclaw-weixin 公开文档，实测校准 2026-10-11）

> 完整权威文档见 https://github.com/Tencent/openclaw-weixin/blob/main/docs/protocol.md。
> 下面是实现本技能 `bridge.py`（附录 1）所需的最小子集。

## 基础

- Base URL：`https://ilinkai.weixin.qq.com`；CDN：`https://novac2c.cdn.weixin.qq.com/c2c`
- JSON over HTTPS；除二维码状态轮询用 GET，其余 POST。

## 通用请求头

| Header | 值 |
| --- | --- |
| `Content-Type` | `application/json`（POST） |
| `AuthorizationType` | `ilink_bot_token` |
| `Authorization` | `Bearer <bot_token>`（登录后的鉴权请求） |
| `X-WECHAT-UIN` | base64(随机 uint32 的十进制字符串)，登录时生成一次后固定 |
| `iLink-App-Id` | `bot` |
| `iLink-App-ClientVersion` | 版本号按 `0x00MMNNPP` 转十进制字符串（如 2.4.8 → `132104`） |

鉴权 POST 还需 `base_info: {"channel_version": "2.4.8", "bot_agent": "<UA 风格标识，仅观测用>"}`。

## 扫码登录

1. `POST /ilink/bot/get_bot_qrcode?bot_type=3`，body `{"local_token_list": []}`
   → 返回 `qrcode`（32 位轮询 token）+ `qrcode_img_content`（**二维码内容**，形如 `https://liteapp.weixin.qq.com/q/...`，渲染成图片给用户扫）。
2. `GET /ilink/bot/get_qrcode_status?qrcode=<urlencode>`（长轮询，建议 35s 超时）
   → `status`：`wait` / `scaned` / `confirmed`（得 `bot_token`、`ilink_bot_id`、`ilink_user_id`）/ `expired` / `need_verifycode`（加 `&verify_code=` 重轮询）/ `verify_code_blocked` / `scaned_but_redirect`（按 `redirect_host` 换 base URL 继续）。

二维码约 5 分钟有效。

## 收发消息

- `POST /ilink/bot/getupdates` body `{"get_updates_buf": "<上次返回的游标，首次空串>", "base_info": {...}}`
  → `{"ret":0, "msgs":[...], "get_updates_buf":"...", "longpolling_timeout_ms":35000}`。
  `ret`/`errcode` 为 `-14` → 停 1 小时再试。
- `POST /ilink/bot/sendmessage`，文本消息体：
  `{"msg": {"from_user_id": "", "to_user_id": "<用户>", "client_id": "<uuid>", "message_type": 2, "message_state": 2, "context_token": "<回传收到的>", "item_list": [{"type": 1, "text_item": {"text": "..."}}]}, "base_info": {...}}`
  注意 `from_user_id` 置空（官方插件即如此）；`message_type: 1`=用户，`2`=bot。
- `POST /ilink/bot/msg/notifystart` / `notifystop`：daemon 起停时各调一次（失败只记日志）。

**铁律**：`context_token` 来自某条收到的消息；零会话时发送会被拒（`ret:-2 prepare failed`）。回复务必回传该会话的 token。

## 消息模型（收）

`WeixinMessage`：`message_id`、`from_user_id`、`to_user_id`、`session_id`、`group_id`（群聊才有）、`message_type`、`message_state`（0 新 / 1 生成中 / 2 完成，只处理 2）、`item_list`、`context_token`、`create_time_ms`。

`item_list` 的 `type`：`1` 文本（`text_item.text`）、`2` 图片、`3` 语音（`voice_item.text` 可能自带转写）、`4` 文件（`file_item.file_name`）、`5` 视频。

## 媒体下载（图片）

1. 取 `image_item.media.full_url`，没有则拼 `CDN_BASE/download?encrypted_query_param=<...>`。
2. GET 下载字节流；密钥优先 `image_item.aeskey`（32 位 hex = 16 字节），无则 `media.aes_key`。
3. AES-128-ECB 解密 + PKCS#7 去填充（长度不是 16 倍数或无密钥时按明文处理）。

上传流程（`getuploadurl` → AES-128-ECB 加密 → POST octet-stream → 取 `x-encrypted-param` 响应头）本桥 v1 未实现，按需看官方文档。
