openclaw-weixin 3.0.2 → 3.1.0

package/CHANGELOG.md

@@ -6,6 +6,26 @@
 
 ## [未发布]
 
+## [3.1.0] - 2026-08-10
+
+### 修复
+
+- **OpenClaw SDK 入口兼容：** `createTypingCallbacks` 改从
+  `openclaw/plugin-sdk/channel-message` 导入，同时兼容仍提供旧入口的最低宿主和已经移除
+  `channel-runtime` 的新版宿主；CI 针对两类实际 SDK 构建并导入该边界，且执行无 mock
+  插件注册冒烟。
+- **context token 用户 ID 大小写规范化（发送 ret=-3）：** context token 的账号级内存键和
+  持久化键统一对用户 ID 做小写规范化；getUpdates 返回混合大小写 ID、OpenClaw 会话目标
+  为小写或重启恢复旧格式文件时，仍能命中正确 token
+  （见 Tencent/openclaw-weixin#243）。
+- **QR 登录保留稳定 `--account` 别名（逻辑映射）：** `channels login --account <alias>`
+  成功后凭证与状态仍落在服务端 `ilink_bot_id`（primary hash）下，并写入一对一
+  `alias → hash` 映射供 bindings / 出站解析；`listAccountIds` / monitor 只使用
+  primary；`config.isEnabled` 对别名返回 false，避免宿主 `start(alias)` 建 task
+  后触发重启循环。宿主 `default` 哨兵不会变成别名；`alreadyConnected` 在不歧义时
+  只登记映射，对已有 primary hash 重登为 no-op；拒绝与其它 bot 冲突的别名凭证，
+  不搬迁 sync/context/allow-list；索引原子写入，失败时保留原索引。
+
 ## [3.0.2] - 2026-08-05
 
 ### 变更

package/CHANGELOG_EN.md

@@ -6,6 +6,31 @@ This project follows the [Keep a Changelog](https://keepachangelog.com/) format.
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-08-10
+
+### Fixed
+
+- **OpenClaw SDK entry compatibility:** `createTypingCallbacks` now imports from
+  `openclaw/plugin-sdk/channel-message`, supporting both the minimum host that
+  still exposes the legacy entry and modern hosts that removed `channel-runtime`.
+  CI builds and imports this boundary and runs an unmocked plugin-registration
+  smoke against both real SDK profiles.
+- **Context-token user ID case normalization (outbound ret=-3):** account-scoped
+  in-memory and persisted context-token keys now lowercase the user ID. Mixed-case
+  IDs from getUpdates, lowercased OpenClaw session targets, and legacy persisted
+  files therefore resolve the same token after restart
+  (see Tencent/openclaw-weixin#243).
+- **Persist stable `--account` aliases on QR login (logical mapping):** after
+  `channels login --account <alias>` succeeds, credentials and state stay under
+  the server `ilink_bot_id` (primary hash) and a 1:1 `alias → hash` map is stored
+  for bindings / outbound resolution. `listAccountIds` / monitors use only the
+  primary; `config.isEnabled` returns false for aliases so host `start(alias)` is
+  rejected before a lifecycle task (no restart loop). The host `default` sentinel
+  is never treated as an alias; `alreadyConnected` only records the mapping when
+  unambiguous and is a no-op for existing primary-hash relogin; conflicting alias
+  credentials are rejected without moving sync/context/allow-list state; the
+  account index is written atomically and left intact if publish fails.
+
 ## [3.0.2] - 2026-08-05
 
 ### Changed

package/README.md

@@ -1,98 +1,149 @@
 # openclaw-weixin
 
-[English](./README_EN.md) · [文档站点](https://openclaw-weixin.newfuture.cc/)
+<!-- docs-site:repo-only:start -->
+[English](./README_EN.md) · [在线文档](https://openclaw-weixin.newfuture.cc/)
+<!-- docs-site:repo-only:end -->
 
-这是 [Tencent/openclaw-weixin](https://github.com/Tencent/openclaw-weixin)
-的社区维护发行版，用于连接 OpenClaw 与微信，并提供更好的使用体验。
+<p class="product-tagline">把 OpenClaw 接入微信</p>
 
-## 安装或替换
+<p class="product-summary">
+这是 <a href="https://github.com/Tencent/openclaw-weixin">Tencent/openclaw-weixin</a>
+的社区维护发行版。提示词或命令行任选一种，即可完成安装或原位替换。
+</p>
 
-需要 [OpenClaw](https://docs.openclaw.ai/install) `>=2026.6.1`。请使用运行
-OpenClaw 的同一用户，并在同一环境中执行。
+<h2 id="connect-wechat">选择一种安装方式</h2>
 
-**命令行——一行安装或替换：**
+<p class="choice-lead"><strong>推荐复制提示词，也可以直接运行命令。</strong>
+两种方式效果相同，任选一种即可，不必重复执行。直接运行命令时，请使用运行 OpenClaw
+的同一用户和同一环境。</p>
 
-> 提示：**不要**先卸载 `@tencent-weixin/openclaw-weixin`；直接原位替换通常会保留现有配置和登录状态。
+<div class="install-choice">
+  <a href="#agent-install"><strong>复制提示词</strong><span>粘贴到 OpenClaw 聊天框</span></a>
+  <span class="choice-or" aria-hidden="true">或</span>
+  <a href="#cli-install"><strong>运行命令</strong><span>在终端执行一行命令</span></a>
+</div>
+
+<h3 id="agent-install">复制提示词</h3>
+
+<p class="prompt-lead">复制下面这段话，粘贴到 OpenClaw 聊天框并发送：</p>
+
+```text
+请使用 OpenClaw 插件安装命令
+`openclaw plugins install npm:openclaw-weixin --force` 安装或原位替换插件。
+不要先卸载或改用普通的 `npm install`，也不要删除现有配置或登录数据。若不能运行
+终端命令，请直接说明。安装成功后，若 Gateway 已自动重启，执行
+`openclaw channels status --probe` 检查连接；若未自动重启，先询问我是否重启，
+并在确认重启完成后再执行该探测。若探测显示微信尚未登录，再提示我运行
+`openclaw channels login --channel openclaw-weixin` 扫码。最后报告实际结果。
+```
+
+<h3 id="cli-install">运行一条命令</h3>
 
 ```bash
 openclaw plugins install npm:openclaw-weixin --force
 ```
 
-<details>
-<summary>绑定微信账号（全新安装）</summary>
+<p class="replacement-note"><strong>替换腾讯版时不要先卸载。</strong>
+直接安装会保留现有配置和登录状态；<code>--force</code> 用于覆盖现有插件安装，
+不改变来源信任或安全策略。
+OpenClaw 会自动轮换配置备份。</p>
+
+<p class="install-done"><strong>如果当前 OpenClaw 已有微信登录状态，完成任一种方式后通常即可使用。</strong>
+全新安装需要展开完整检查并扫码绑定；安装报错、未自动恢复连接或需要确认目标账号时，
+也在此检查。</p>
+
+<details id="verify-connection" class="full-check">
+<summary>完整检查、扫码与恢复</summary>
+
+### 安装命令报告版本不兼容
 
-如需将微信账号绑定到当前 OpenClaw，请启用插件并开始扫码绑定：
+仅在安装命令报告版本不兼容时检查；需要
+[OpenClaw](https://docs.openclaw.ai/install) `>=2026.6.1`：
 
 ```bash
-openclaw plugins enable openclaw-weixin
-openclaw channels login --channel openclaw-weixin
+openclaw --version
 ```
 
-登录命令会在终端显示二维码。
+若版本过低或 Nix 模式禁止安装，请不要卸载现有插件；按
+[安装限制与故障排查](docs/guide.md#安装限制)处理。
 
-</details>
-
-<details>
-<summary>重载检查</summary>
+### 安装后没有自动连接
 
-确保正在运行的 Gateway 已重载插件。必要时重启承载 OpenClaw 的服务、容器或
-Pod，然后执行：
+安装可能使启用了配置重载的受管 Gateway 自动重载。若仍未连接，请重启实际承载
+OpenClaw 的服务、容器或 Pod，然后执行：
 
 ```bash
 openclaw plugins list
 openclaw channels status --probe
 ```
 
-插件无加载错误且目标账号探测成功即完成；若显示未登录，请执行上面的登录命令。
-
-</details>
+<div class="connection-criteria">
+  <strong>满足以下条件即表示连接成功</strong>
+  <ul>
+    <li><code>openclaw plugins list</code> 显示插件已启用，并且没有加载错误。</li>
+    <li><code>openclaw channels status --probe</code> 对目标微信账号探测成功。</li>
+    <li>使用多账号时，探测结果对应你准备使用的别名或账号 ID。</li>
+  </ul>
+</div>
 
+| 检查结果 | 下一步 |
+| --- | --- |
+| 插件显示已停用 | 执行 `openclaw plugins enable openclaw-weixin`，重载 Gateway，然后重新探测 |
+| 插件无加载错误，且目标账号探测成功 | 已完成，无需继续操作 |
+| 账号显示未登录 | 继续下面的扫码绑定 |
+| Channel 显示 `OK` 但未连接 | 按[连接故障排查](docs/guide.md#channel-显示-ok-但未连接)重载实际运行单元 |
 
-### 提示词自动安装
+<h3 id="bind-account">状态显示未登录</h3>
 
-将下面的提示词直接发送 OpenClaw Agent，用于安全安装或原位替换插件：
+仅在探测显示目标账号未登录时执行：
 
-```text
-请在不改变现有配置和登录状态的前提下，安装或原位替换 `openclaw-weixin`：
-1. 先确认 `openclaw --version` 不低于 2026.6.1。
-2. 我信任 npm 来源 `openclaw-weixin`。执行
-   `openclaw plugins install npm:openclaw-weixin --force`，不要先卸载。
-3. 仅在 `openclaw plugins list` 显示已停用时启用插件。不要主动重启 Gateway 或发起
-   扫码登录；安装可能使启用了配置重载的受管 Gateway 自动重启。若已自动重启，执行
-   `openclaw channels status --probe`；否则询问是否重启 Gateway。
-4. 只报告结果；若未登录过微信，提示我手动运行
-   `openclaw channels login --channel openclaw-weixin` 扫码绑定微信。
+```bash
+openclaw plugins enable openclaw-weixin
+openclaw channels login --channel openclaw-weixin
 ```
 
-### 通过 Agent 命令安装
-
-OpenClaw `>=2026.7.2-beta.1` 时，如果已设置 `commands.plugins: true`，并且你是
-owner/admin，直接发送：
+登录命令会在终端显示二维码。扫码并等待登录完成，然后再次执行：
 
-```text
-/plugins install npm:openclaw-weixin --force
+```bash
+openclaw channels status --probe
 ```
 
-然后按上面的**重载检查**操作。
+</details>
 
 ## 多账号
 
-再次执行登录命令即可绑定其他微信账号：
+如果会同时使用多个微信账号，建议先按「账号 + 渠道 + 对端」隔离私聊上下文：
 
 ```bash
-openclaw channels login --channel openclaw-weixin
+openclaw config set session.dmScope per-account-channel-peer
 ```
 
-多个账号同时登录时，建议按「账号 + 渠道 + 对端」隔离上下文：
+这是 OpenClaw 的全局会话设置，会影响所有渠道；它不影响账号登录，只决定之后收到的
+私聊消息如何分配会话。
+
+再次执行登录命令即可绑定其他微信账号。建议为每个号使用**稳定别名**，以便
+`openclaw.json` / bindings 用可读 `accountId`（而不是仅服务端 hash）：
 
 ```bash
-openclaw config set session.dmScope per-account-channel-peer
+openclaw channels login --channel openclaw-weixin --account wukong
+openclaw channels login --channel openclaw-weixin --account nezha
 ```
 
+<details>
+<summary>账号 ID 与状态文件</summary>
+
+登录成功后会写入：
+
+- `openclaw-weixin/accounts/<ilink_bot_id 规范化>.json`（凭证与状态命名空间；`listAccountIds` / monitor 只用此 id）
+- `openclaw-weixin/account-aliases.json`（一对一 `alias → hash` 逻辑映射，供 bindings / 出站解析；别名不会再起一条 transport）
+
+未传 `--account` 时（宿主会传入 `default` 哨兵）只索引服务端 bot id，不会创建名为 `default` 的账号。已绑定过的 hash 账号再执行 `login --account <alias>` 时，会在不歧义的情况下登记别名映射（不在线改名、不搬迁状态命名空间）。
+
+</details>
+
 ## 文档
 
-- [详细指南](docs/guide.zh_CN.md)：安装行为、BotAgent、卸载和故障排查
-- [后端 API 协议](docs/backend-api.zh_CN.md)
+- [详细指南](docs/guide.md)：安装行为、BotAgent、卸载和故障排查
+- [后端 API 协议](docs/backend-api.md)
 - [架构说明](docs/architecture.md)
-- [文档站点](https://openclaw-weixin.newfuture.cc/)：多语言在线文档，同时提供
-  Markdown 原文与 [llms.txt](https://openclaw-weixin.newfuture.cc/llms.txt) 索引
+- [llms.txt](https://openclaw-weixin.newfuture.cc/llms.txt)：面向智能体的文档索引

package/README_EN.md

@@ -1,106 +1,162 @@
 # openclaw-weixin
 
+<!-- docs-site:repo-only:start -->
 [简体中文](./README.md) · [Documentation site](https://openclaw-weixin.newfuture.cc/en/)
+<!-- docs-site:repo-only:end -->
 
-Community-maintained distribution of
-[Tencent/openclaw-weixin](https://github.com/Tencent/openclaw-weixin) that
-connects OpenClaw with WeChat for a better messaging experience.
+<p class="product-tagline">Bring OpenClaw into WeChat</p>
 
-## Install or Replace
+<p class="product-summary">
+This community-maintained distribution of
+<a href="https://github.com/Tencent/openclaw-weixin">Tencent/openclaw-weixin</a>
+installs or replaces the plugin using either one prompt or one command.
+</p>
 
-Requires [OpenClaw](https://docs.openclaw.ai/install) `>=2026.6.1`. Run commands
-as the same user and in the same environment as OpenClaw.
+<h2 id="connect-wechat">Choose one installation method</h2>
 
-**CLI—one-command install or replacement:**
+<p class="choice-lead"><strong>We recommend the prompt; you can also run the command directly.</strong>
+Both produce the same result. Choose one; do not run both. If you run the
+command directly, use the same user and environment that run OpenClaw.</p>
 
-> Tip: **Do not** uninstall `@tencent-weixin/openclaw-weixin` first; replacing it
-> in place usually preserves the existing configuration and login state.
+<div class="install-choice">
+  <a href="#agent-install"><strong>Copy a prompt</strong><span>Paste it into an OpenClaw chat</span></a>
+  <span class="choice-or" aria-hidden="true">or</span>
+  <a href="#cli-install"><strong>Run a command</strong><span>Execute one line in your terminal</span></a>
+</div>
+
+<h3 id="agent-install">Copy the prompt</h3>
+
+<p class="prompt-lead">Copy this prompt, paste it into an OpenClaw chat, and send it:</p>
+
+```text
+Install or replace the plugin with OpenClaw's plugin installer by running exactly
+`openclaw plugins install npm:openclaw-weixin --force`. Do not uninstall first or
+use plain `npm install`; do not delete existing configuration or login data.
+If you cannot run terminal commands, say so. After a successful install, run
+`openclaw channels status --probe` if the Gateway restarted automatically. If it
+did not, ask me whether to restart it and run the probe only after the restart is
+confirmed complete. If the probe reports that WeChat is not logged in, tell me to run
+`openclaw channels login --channel openclaw-weixin` and scan the QR code. Finally,
+report the actual result.
+```
+
+<h3 id="cli-install">Run one command</h3>
 
 ```bash
 openclaw plugins install npm:openclaw-weixin --force
 ```
 
-<details>
-<summary>Bind a WeChat account (new installations)</summary>
+<p class="replacement-note"><strong>Do not uninstall Tencent's package first.</strong>
+Installing directly preserves the existing configuration and login state.
+<code>--force</code> overwrites an existing plugin installation; it does not
+change source-trust or security policy. OpenClaw rotates configuration backups
+automatically.</p>
+
+<p class="install-done"><strong>If this OpenClaw instance already has a WeChat login,
+either option is usually all you need.</strong> For a new installation, open the full
+check and scan the QR code. Use it as well when installation fails, the connection
+does not return automatically, or you need to confirm the intended account.</p>
+
+<details id="verify-connection" class="full-check">
+<summary>Full check, QR login, and recovery</summary>
 
-To bind a WeChat account to this OpenClaw instance, enable the plugin and start
-the QR flow:
+### The install command reports an incompatible version
+
+Check only when installation reports an incompatible version. Requires
+[OpenClaw](https://docs.openclaw.ai/install) `>=2026.6.1`:
 
 ```bash
-openclaw plugins enable openclaw-weixin
-openclaw channels login --channel openclaw-weixin
+openclaw --version
 ```
 
-The login command displays a QR code in the terminal.
+If the version is too old or Nix mode disables installation, do not uninstall the
+existing plugin. Follow the
+[installation limitations and troubleshooting](docs/guide_EN.md#limitations).
 
-</details>
+### The connection does not return after installation
 
-<details>
-<summary>Reload check</summary>
-
-Ensure the running Gateway has reloaded the plugin. If needed, restart the
-service, container, or pod that runs OpenClaw, then run:
+Installation can automatically reload a managed Gateway with configuration
+reload enabled. If it remains disconnected, restart the service, container, or
+pod that actually runs OpenClaw, then run:
 
 ```bash
 openclaw plugins list
 openclaw channels status --probe
 ```
 
-It is ready when the plugin has no load error and the intended account passes
-the probe. If the probe reports no login, use the login command above.
+<div class="connection-criteria">
+  <strong>You are connected when all of these are true</strong>
+  <ul>
+    <li><code>openclaw plugins list</code> shows the plugin enabled with no load error.</li>
+    <li><code>openclaw channels status --probe</code> succeeds for the intended WeChat account.</li>
+    <li>With multiple accounts, the result belongs to the alias or account ID you intend to use.</li>
+  </ul>
+</div>
 
-</details>
+| Result | Next action |
+| --- | --- |
+| Plugin is disabled | Run `openclaw plugins enable openclaw-weixin`, reload the Gateway, then probe again |
+| Plugin has no load error and the intended account passes the probe | You are done |
+| Account is not logged in | Continue to QR login below |
+| Channel shows `OK` but does not connect | Follow [connection troubleshooting](docs/guide_EN.md#channel-shows-ok-but-doesnt-connect) to reload the actual runtime |
 
-### Automatic Installation Prompt
+<h3 id="bind-account">The status reports no login</h3>
 
-Send the following prompt directly to an OpenClaw Agent to safely install or
-replace the plugin in place:
+Run this only when the probe reports that the intended account is not logged in:
 
-```text
-Install or replace `openclaw-weixin` without changing the existing configuration
-or login state:
-1. Verify that `openclaw --version` is at least 2026.6.1.
-2. I trust the npm source `openclaw-weixin`. Run
-   `openclaw plugins install npm:openclaw-weixin --force`; do not uninstall first.
-3. Enable the plugin only if `openclaw plugins list` shows it disabled. Do not
-   restart the Gateway yourself or start QR login. Installation may automatically
-   restart a managed Gateway with config reload enabled. If it does, run
-   `openclaw channels status --probe`; otherwise, ask whether to restart the Gateway.
-4. Report only the result. If WeChat is not logged in, ask me to manually run
-   `openclaw channels login --channel openclaw-weixin` and scan the QR code.
+```bash
+openclaw plugins enable openclaw-weixin
+openclaw channels login --channel openclaw-weixin
 ```
 
-### Install Through an Agent Command
-
-On OpenClaw `>=2026.7.2-beta.1`, if `commands.plugins: true` is set and you are
-an owner/admin, send:
+The login command displays a QR code in the terminal. Scan it, wait for login to
+finish, then run:
 
-```text
-/plugins install npm:openclaw-weixin --force
+```bash
+openclaw channels status --probe
 ```
 
-Then follow **Reload check** above.
+</details>
 
 ## Multiple Accounts
 
-Run the login command again to bind another WeChat account:
+Before using multiple WeChat accounts, consider isolating direct-message context
+by account + channel + sender:
 
 ```bash
-openclaw channels login --channel openclaw-weixin
+openclaw config set session.dmScope per-account-channel-peer
 ```
 
-For multiple logged-in accounts, isolate context by account + channel + sender:
+This is a global OpenClaw session setting that affects every channel. It does not
+change account login; it controls how subsequent direct messages are assigned to
+sessions.
+
+Run the login command again to bind another WeChat account. Prefer a **stable
+alias** per number so `openclaw.json` / bindings can use a readable `accountId`
+instead of only the server hash:
 
 ```bash
-openclaw config set session.dmScope per-account-channel-peer
+openclaw channels login --channel openclaw-weixin --account alice
+openclaw channels login --channel openclaw-weixin --account bob
 ```
 
+<details>
+<summary>Account IDs and state files</summary>
+
+A successful login writes:
+
+- `openclaw-weixin/accounts/<normalized ilink_bot_id>.json` (credential + state namespace; `listAccountIds` / monitors use only this id)
+- `openclaw-weixin/account-aliases.json` (1:1 `alias → hash` map for bindings / outbound resolution; aliases never start a second transport)
+
+Without `--account` (the host passes its `default` sentinel) only the server bot id is indexed; a `default` account file is never created. Re-running `login --account <alias>` against an already-bound hash-only install records an alias mapping when unambiguous (no online rename, no state-namespace move).
+
+</details>
+
 ## Documentation
 
-- [Detailed guide](docs/guide.md): install behavior, BotAgent, uninstall, and
+- [Detailed guide](docs/guide_EN.md): install behavior, BotAgent, uninstall, and
   troubleshooting
-- [Backend API protocol](docs/backend-api.md)
-- [Architecture](docs/architecture.md)
-- [Documentation site](https://openclaw-weixin.newfuture.cc/en/): multilingual
-  documentation that also serves the raw Markdown and an
-  [llms.txt](https://openclaw-weixin.newfuture.cc/llms.txt) index
+- [Backend API protocol](docs/backend-api_EN.md)
+- [Architecture](docs/architecture_EN.md)
+- [llms.txt](https://openclaw-weixin.newfuture.cc/llms.txt): machine-readable
+  documentation index