NeoClaw Weixin Plugin

中文 / English 对照项目说明（Bilingual Project Introduction）

1. 项目简介 | Project Overview

中文： NeoClaw Weixin Plugin 是一个将微信能力接入 NeoClaw Gateway 架构的适配项目。它通过原生网关方式（非 OpenClaw plugin-sdk 依赖）提供登录、轮询同步、消息收发和状态持久化能力。

English: NeoClaw Weixin Plugin integrates Weixin capabilities into the NeoClaw Gateway architecture. It uses a native gateway approach (without OpenClaw plugin-sdk coupling) to provide login, polling sync, message send/receive, and state persistence.

---

2. 核心功能 | Core Features

中文功能	English Feature
原生 Weixin Gateway 接入	Native Weixin Gateway integration
二维码登录流程（CLI 触发）	QR-code login flow (CLI driven)
轮询消息同步与去重/防抖处理	Polling-based sync with dedup/debounce
标准化入站消息到 InboundMessage	Normalize inbound events into InboundMessage
统一状态目录 ~/.neoclaw/weixin/	Unified state dir ~/.neoclaw/weixin/
CLI 管理命令（init/login/status/logout）	CLI management commands (init/login/status/logout)

---

3. CLI 命令 | CLI Commands

# 初始化微信配置模板 | Initialize Weixin config
neoclaw weixin init

# 二维码登录并写入 token | QR login and persist token
neoclaw weixin login

# 查看账号状态与同步游标 | Check account status and sync cursor
neoclaw weixin status

# 清理本地凭证 | Clear local credentials
neoclaw weixin logout

---

4. 配置示例 | Config Example

{
  "weixin": {
    "enabled": true,
    "accountId": "YOUR_WEIXIN_ACCOUNT_ID",
    "routeTag": "default",
    "pollInterval": 3000,
    "apiBaseUrl": "http://127.0.0.1:17888",
    "stateDir": "~/.neoclaw/weixin"
  }
}

---

5. 项目结构 | Project Structure

src/
  gateway/
    weixin/
      gateway.ts   # 网关主适配器 | gateway adapter
      client.ts    # 协议请求与状态管理 | protocol client + state
      types.ts     # 类型定义 | type definitions
  cli/
    commands/
      weixin.ts    # CLI 子命令 | CLI subcommands

---

6. 安装与运行 | Install & Run

中文：

1. 安装依赖：bun install
2. 初始化配置：neoclaw weixin init
3. 修改配置中的 apiBaseUrl/accountId
4. 执行登录：neoclaw weixin login
5. 启动服务：neoclaw start

English:

1. Install dependencies: bun install
2. Initialize config: neoclaw weixin init
3. Update apiBaseUrl/accountId in config
4. Run login: neoclaw weixin login
5. Start daemon: neoclaw start

---

7. 注意事项 | Notes

中文：

• 若登录失败，请先检查 weixin.apiBaseUrl 对应服务是否可达。
• 状态文件只写入 ~/.neoclaw/weixin/，避免与 ~/.openclaw 双栈冲突。

English:

• If login fails, verify that weixin.apiBaseUrl is reachable.
• State is persisted only under ~/.neoclaw/weixin/ to avoid dual-stack drift with ~/.openclaw.