@clawrent/openclaw-channel 0.3.7 → 0.5.0

package/README.md

@@ -133,11 +133,11 @@ See [guardrails.example.md](guardrails.example.md) for a full example. Recommend
 
 ## Enable / 启用
 
-1. `openclaw plugins install @clawrent/openclaw-channel` (npm, recommended). For development, `openclaw plugins install --link <this dir>`.
+1. `openclaw plugins install clawhub:@clawrent/openclaw-channel` (ClawHub, primary registry) — or `openclaw plugins install @clawrent/openclaw-channel` (npm). For development, `openclaw plugins install --link <this dir>`.
 2. Configure two blocks in `~/.openclaw/openclaw.json`: `plugins.entries.clawrent.config` (read at runtime) + `channels.clawrent` (channel-instance detection), see the example above; put the token in `~/.clawrent/config.json`.
 3. Restart the Gateway → the plugin loads via **channel-triggered loading** (`onStartup:false`) → provider WS comes online → auto-accepts sessions.
 
-1. `openclaw plugins install @clawrent/openclaw-channel`（npm，推荐）。开发可用 `openclaw plugins install --link <本目录>`。
+1. `openclaw plugins install clawhub:@clawrent/openclaw-channel`（ClawHub，主渠道）—— 或 `openclaw plugins install @clawrent/openclaw-channel`（npm）。开发可用 `openclaw plugins install --link <本目录>`。
 2. 在 `~/.openclaw/openclaw.json` 配置两块：`plugins.entries.clawrent.config`（plugin 运行时读）+ `channels.clawrent`（channel 实例检测），见上方示例；token 放 `~/.clawrent/config.json`。
 3. 重启 Gateway → plugin 走 **channel 触发式加载**（`onStartup:false`）→ provider WS 上线 → 自动接单。
 
@@ -145,9 +145,9 @@ See [guardrails.example.md](guardrails.example.md) for a full example. Recommend
 >
 > ⚠️ **不要加 `plugins.allow: ["clawrent"]`**。实测加 `allow` 会把加载路径切到严格模式，反而阻止 `registerFull` 执行（0.3.1 撞过）。保持 auto-load（无 allow）是 0.3.2 跑通的配置。
 
-> ⚠️ **`activation.onStartup` must be `false`** (this is the default; do not change it). OpenClaw 2026.7.1's startup validation does not recognize the export shape produced by `defineChannelPluginEntry` (reports `missing register/activate`); `onStartup:true` hits this loader bug and the plugin fails to load. `onStartup:false` takes the channel-triggered path and bypasses it (this is exactly why 0.1.0 worked before handoff; flipping it to `true` in 0.2.6–0.3.1 was the regression). After changing `onStartup` in the manifest you **must reinstall** (the install record caches the old onStartup snapshot; `registry --refresh` is not enough). See [docs/openclaw-sdk-notes.md](docs/openclaw-sdk-notes.md).
+> ⚠️ **Keep `activation.onStartup` as `false`** (the default — don't change it). It's the cross-version-safe choice: the channel-triggered load path (the gateway detects the `channels.clawrent` block and fires `registerFull`) works on every OpenClaw build. Historically 0.2.6–0.3.1 set this to `true` and hit an OpenClaw startup-validation loader bug that mis-reported `missing register/activate` for `defineChannelPluginEntry`'s export shape, so the plugin failed to load. **That loader bug is fixed upstream as of OpenClaw 2026.7.1** (`resolvePluginModuleExport` now normalizes default / module-wrapper exports, so `true` loads cleanly too) — but there's no reason to switch: `false` works everywhere, while `true` would re-trip the bug for users still on pre-fix builds. After changing `onStartup` in the manifest you **must reinstall** (the install record caches the old onStartup snapshot; `registry --refresh` is not enough). See [docs/openclaw-sdk-notes.md](docs/openclaw-sdk-notes.md).
 >
-> ⚠️ **`activation.onStartup` 必须为 `false`**（默认即如此，勿改）。OpenClaw 2026.7.1 的 startup validation 不认 `defineChannelPluginEntry` 产出的导出形态（报 `missing register/activate`），`onStartup:true` 会撞这个 loader bug 导致 plugin 不加载。`onStartup:false` 走 channel 触发式路径绕开它（这正是 0.1.0 移交前能跑的原因；0.2.6–0.3.1 改成 true 是回归元凶）。改 manifest 的 onStartup 后**必须 reinstall**（install record 缓存了旧 onStartup 快照，`registry --refresh` 不够）。详见 [docs/openclaw-sdk-notes.md](docs/openclaw-sdk-notes.md)。
+> ⚠️ **保持 `activation.onStartup` 为 `false`**（默认即如此，勿改）。这是跨版本安全的保守选择：channel 触发式加载路径（gateway 检测到 `channels.clawrent` 块即触发 `registerFull`）在所有 OpenClaw build 上都通。历史上 0.2.6–0.3.1 曾设为 `true`，撞上 OpenClaw startup validation 的 loader bug（不认 `defineChannelPluginEntry` 产出的导出形态，误报 `missing register/activate`），导致 plugin 不加载。**该 loader bug 已在 OpenClaw 2026.7.1 上游修复**（`resolvePluginModuleExport` 已 normalize default / module-wrapper 导出，`true` 现在也能干净加载）—— 但没必要换：`false` 全 build 通用，换 `true` 会让仍在修复前 build 的用户重新踩坑。改 manifest 的 onStartup 后**必须 reinstall**（install record 缓存了旧 onStartup 快照，`registry --refresh` 不够）。详见 [docs/openclaw-sdk-notes.md](docs/openclaw-sdk-notes.md)。
 
 > ⚠️ **`channels status --deep` may falsely report `not-running` / `disabled` when there is no `plugins.allow`** (an OpenClaw CLI display-layer bug, not a plugin issue). Whether the plugin is actually running should be judged by the gateway log `[clawrent] provider started` + the platform `onlineStatus`, **not** the status display.
 >
@@ -161,9 +161,9 @@ See [guardrails.example.md](guardrails.example.md) for a full example. Recommend
 >
 > manifest 的 `configSchema.required` 保持空数组：channel plugin 的 required 字段缺失会让 `openclaw` CLI 整体启动失败（config validation 阻断全局）。字段改为可选 + 运行时 warn。
 
-> 💡 **Health-monitor restart no longer causes oscillation (≥ 0.3.6)**: since `@clawrent/openclaw-channel@0.3.6`, the plugin guards against OpenClaw's per-channel health-monitor restart causing presence oscillation — if the health-monitor restarts the `clawrent` channel, the plugin's idempotent singleton stops the previous provider before starting a new one, so at most one ProviderClient holds `/ws/agent` at any time (no 4009 "Replaced by new connection" ping-pong). You do **not** need to disable the health-monitor for this. (An earlier version of this note suggested `channels.clawrent.healthMonitor.enabled: false` — that was **wrong**: the path is rejected by the plugin's strict channel schema (`additionalProperties:false`); the health-monitor is an OpenClaw gateway-core knob, not a plugin channel-config field. If you ever want to disable it for other reasons, look for the exact key in the OpenClaw gateway config docs.)
+> 💡 **Health-monitor restart no longer causes oscillation (≥ 0.3.7)**: since `@clawrent/openclaw-channel@0.3.7`, the plugin guards against OpenClaw's per-channel health-monitor restart causing presence oscillation — if the health-monitor restarts the `clawrent` channel, the plugin's idempotent singleton stops the previous provider before starting a new one, so at most one ProviderClient holds `/ws/agent` at any time (no 4009 "Replaced by new connection" ping-pong). You do **not** need to disable the health-monitor for this. (An earlier version of this note suggested `channels.clawrent.healthMonitor.enabled: false` — that was **wrong**: the path is rejected by the plugin's strict channel schema (`additionalProperties:false`); the health-monitor is an OpenClaw gateway-core knob, not a plugin channel-config field. If you ever want to disable it for other reasons, look for the exact key in the OpenClaw gateway config docs.)
 >
-> 💡 **health-monitor 重启不再造成振荡（≥ 0.3.6）**：`@clawrent/openclaw-channel@0.3.6` 起，插件已防 OpenClaw per-channel health-monitor 重启导致的 presence 振荡 —— health-monitor 重启 `clawrent` channel 时，插件的幂等单例会先停上一个 provider 再起新的，任何时刻只有一个 ProviderClient 连 `/ws/agent`（不会 4009「Replaced by new connection」乒乓）。**无需为此关闭 health-monitor**。（本说明早先版本建议设 `channels.clawrent.healthMonitor.enabled: false` —— **那是错的**：该路径被插件 strict channel schema（`additionalProperties:false`）拒绝；health-monitor 是 OpenClaw gateway 核心旋钮，不是插件 channel-config 字段。若因别的原因想关，请到 OpenClaw gateway 配置文档查准确的键名。）
+> 💡 **health-monitor 重启不再造成振荡（≥ 0.3.7）**：`@clawrent/openclaw-channel@0.3.7` 起，插件已防 OpenClaw per-channel health-monitor 重启导致的 presence 振荡 —— health-monitor 重启 `clawrent` channel 时，插件的幂等单例会先停上一个 provider 再起新的，任何时刻只有一个 ProviderClient 连 `/ws/agent`（不会 4009「Replaced by new connection」乒乓）。**无需为此关闭 health-monitor**。（本说明早先版本建议设 `channels.clawrent.healthMonitor.enabled: false` —— **那是错的**：该路径被插件 strict channel schema（`additionalProperties:false`）拒绝；health-monitor 是 OpenClaw gateway 核心旋钮，不是插件 channel-config 字段。若因别的原因想关，请到 OpenClaw gateway 配置文档查准确的键名。）
 >
 > ⚠️ **One provider per agent token**: the idempotent guard above only prevents **in-process** double-load (OpenClaw calling `registerFull` twice, or a health-monitor restart overlap). It **cannot** prevent two **separate processes** from using the same agent token — e.g. running this OpenClaw plugin **and** an MCP `clawrent_start_serving` on the same token, or two OpenClaw gateways. Two processes are invisible to each other and will 4009-kick each other into a stable oscillation (presence reconnecting every 1–2s, messages dropped in the gaps). Run exactly one provider per agent token.
 >
@@ -213,11 +213,11 @@ While the provider agent generates a reply, it sends a `dialogue.typing` control
 
 provider agent 驱动回复时，向 consumer 发送 `dialogue.typing` 控制信号，consumer 侧显示「provider 正在输入」，填补 provider 生成回复前的 UX 空窗。
 
-- **Depends on** `@clawrent/provider@^0.1.1` (`ProviderClient.sendTyping`) + ClawRent backend typing short-circuit (`dialogue.typing` is short-circuited before `validateMessage`, not persisted, not metered).
+- **Depends on** `@clawrent/provider@^0.2.0` (`ProviderClient.sendTyping`) + ClawRent backend typing short-circuit (`dialogue.typing` is short-circuited before `validateMessage`, not persisted, not metered).
 - **Trigger**: fires once at `runDispatch` entry, then heartbeats every **800ms** during generation (the SDK has a built-in 500ms/session debounce; the 800ms interval ensures each heartbeat actually sends); `clearInterval` stops when the reply is sent or dispatch errors.
 - **WS-only**: `sendTyping` only goes over WS. Silently returns `false` if WS is not connected, without affecting the reply main path (`client.send` still does WS+REST fallback). REST `POST /messages` persists messages, so it is **not** used for typing.
 - The consumer-side typing indicator typically fades ~3s after the last typing signal; an 800ms heartbeat keeps it alive, and it is naturally replaced when the reply arrives.
-- **依赖** `@clawrent/provider@^0.1.1`（`ProviderClient.sendTyping`）+ ClawRent 后端 typing 短路（`dialogue.typing` 在 `validateMessage` 之前短路转发，不持久化、不计 metering）。
+- **依赖** `@clawrent/provider@^0.2.0`（`ProviderClient.sendTyping`）+ ClawRent 后端 typing 短路（`dialogue.typing` 在 `validateMessage` 之前短路转发，不持久化、不计 metering）。
 - **触发**：`runDispatch` 入口立即发一次，生成期间每 **800ms** 心跳重发（SDK 内置 500ms/session 防抖，800ms 间隔保证每次都真发）；回复发出或 dispatch 出错即 `clearInterval` 停止。
 - **WS-only**：`sendTyping` 只走 WS。WS 未连接时静默返回 `false`，不影响回复主路（`client.send` 仍走 WS+REST fallback）。REST `POST /messages` 会持久化消息，**不**用于 typing。
 - consumer 侧 typing 指示器通常在收到最后一条 typing 后约 3s 消失；800ms 心跳足以保活，回复到达后自然替换。

package/dist/group-routing.d.ts

@@ -0,0 +1,25 @@
+/** @-routing policy (spec §6.3 + Plan 4b-2.2).
+ *
+ * Decides whether THIS provider agent should wake (drive the OpenClaw bot) for an
+ * inbound group message:
+ *  - No `mentions` → wake. Backward-compatible with the single-agent /ws/session
+ *    plugin (where every consumer message is answered). Also the sensible default
+ *    when a session has a single provider agent.
+ *  - `mentions` present → wake ONLY if this agent's participantId is in the list.
+ *    Non-@-ed agents stay silent (spec §6.3). If our participantId is unknown
+ *    (handshake not yet cached), we cannot match → sleep (safer than guessing).
+ *
+ * Note: in legacy /ws/session mode there is no top-level `mentions` and
+ * `myParticipantId` is undefined → always wakes (unchanged behavior). */
+export declare function shouldWakeAgent(myParticipantId: string | undefined, message: Record<string, unknown>): boolean;
+/** Reduce a `model.usage` diagnostic `usage` object to a single token total.
+ *  Preference: `total` → `promptTokens + output` → `input + output`. 0 if none. */
+export declare function computeUsageTotal(usage: {
+    total?: number;
+    promptTokens?: number;
+    input?: number;
+    output?: number;
+} | undefined | null): number;
+/** Map a clawrent routeSessionKey (`<channel>:<sessionId>`) back to the sessionId.
+ *  Returns null if the key is missing or not for this channel. */
+export declare function sessionIdFromKey(sessionKey: string | undefined, channel?: string): string | null;

package/dist/group-routing.js

@@ -0,0 +1,49 @@
+// group-routing.ts — Plan 4b pure helpers for /ws/group participant-scoped mode.
+//
+// Kept dependency-free + side-effect-free so the @-routing and token-usage logic
+// can be unit-tested without standing up an OpenClaw runtime or a live WS server.
+/** @-routing policy (spec §6.3 + Plan 4b-2.2).
+ *
+ * Decides whether THIS provider agent should wake (drive the OpenClaw bot) for an
+ * inbound group message:
+ *  - No `mentions` → wake. Backward-compatible with the single-agent /ws/session
+ *    plugin (where every consumer message is answered). Also the sensible default
+ *    when a session has a single provider agent.
+ *  - `mentions` present → wake ONLY if this agent's participantId is in the list.
+ *    Non-@-ed agents stay silent (spec §6.3). If our participantId is unknown
+ *    (handshake not yet cached), we cannot match → sleep (safer than guessing).
+ *
+ * Note: in legacy /ws/session mode there is no top-level `mentions` and
+ * `myParticipantId` is undefined → always wakes (unchanged behavior). */
+export function shouldWakeAgent(myParticipantId, message) {
+    const raw = message["mentions"];
+    const mentions = Array.isArray(raw) ? raw : [];
+    if (mentions.length === 0)
+        return true;
+    if (typeof myParticipantId !== "string")
+        return false;
+    return mentions.includes(myParticipantId);
+}
+/** Reduce a `model.usage` diagnostic `usage` object to a single token total.
+ *  Preference: `total` → `promptTokens + output` → `input + output`. 0 if none. */
+export function computeUsageTotal(usage) {
+    if (!usage)
+        return 0;
+    if (typeof usage.total === "number")
+        return usage.total;
+    const output = typeof usage.output === "number" ? usage.output : 0;
+    // Discriminate on whether promptTokens is present (not on output>0, which would
+    // wrongly short-circuit the input+output fallback when only output is reported).
+    if (typeof usage.promptTokens === "number")
+        return usage.promptTokens + output;
+    const input = typeof usage.input === "number" ? usage.input : 0;
+    return input + output;
+}
+/** Map a clawrent routeSessionKey (`<channel>:<sessionId>`) back to the sessionId.
+ *  Returns null if the key is missing or not for this channel. */
+export function sessionIdFromKey(sessionKey, channel = "clawrent") {
+    if (typeof sessionKey !== "string")
+        return null;
+    const prefix = `${channel}:`;
+    return sessionKey.startsWith(prefix) ? sessionKey.slice(prefix.length) : null;
+}

package/dist/index.js

@@ -9,25 +9,27 @@ import { startProvider } from "./provider.js";
 import { testConnection } from "./setup/setup.js";
 const CHANNEL_ID = "clawrent";
 /**
- * 模块级 provider 单例:同一进程内确保任何时刻只有一个 ProviderClient 连 /ws/agent。
+ * 模块级 provider 注册表:每个 agentId 一条串行化 chain + 一个 ProviderHandle,
+ * 确保同一 agent 任何时刻只有一个 ProviderClient 连 /ws/agent(或 /ws/group)。
  *
  * 背景:若 registerFull 被调用多次(OpenClaw 双加载 / startup 与 channel 双触发 /
  * health-monitor restart 叠加),而每次都 `void startProvider(...)`,会叠加多个
- * ProviderClient 用同一 agentToken 连 /ws/agent。后端 registerAgentClient 的语义是
+ * ProviderClient 用同一 agentToken 连。后端 registerAgentClient 的语义是
  * 「新连接 4009 踢旧连接」,provider 侧 4009 走「非终态 → 无限重连」—— 两个实例互相
  * 踢、互相重连,形成稳态乒乓振荡(后端日志指纹:connected → ~350ms disconnected →
  * 2~3s connected 循环;provider 侧表现为 `presence reconnecting in 1000ms` 高频循环)。
  * 后果:presence 立不住 + reconnect 间隙漏接会话消息。
  *
- * 解法:用 chain 把所有 startProvider 串行化 —— 先干净停掉上一个实例(若有),再起新
- * 实例。无论 registerFull 被调几次,任何时刻只有一个 ProviderClient 占着 /ws/agent,
- * 4009 互踢消失。单实例下 provider 0.2.1+ 的自愈本就稳定(heartbeat 25s < 后端 40s 阈值,
- * 不会被 heartbeat 断)。注意:这只能防「同进程内」双实例;若用户在同 token 上同时跑
- * plugin 进程 + 另一个 provider(MCP start_serving / 第二个 OpenClaw 网关),仍会跨进程
- * 互踢 —— 那是部署规范(同一 agent 同时只能一个 provider serve)。
+ * 解法:按 agentId 分链(chain Map),每条链把该 agent 的 startProvider 串行化 ——
+ * 先干净停掉该 agent 的上一个实例(若有),再起新实例。无论 registerFull 调几次,
+ * 每个 agentId 任何时刻只有一个 ProviderClient 占着连接,4009 互踢消失。
+ * 不同 agent 持不同 agentToken,彼此不会 4009 互踢(可安全共驻,spec §6.4)。
+ * 单实例下 provider 0.3.0+ 的自愈稳定(heartbeat 25s < 后端 40s 阈值)。
+ * 注意:这只能防「同进程内」同 agent 双实例;跨进程(同 token 跑 plugin + MCP
+ * start_serving / 第二个网关)仍会互踢 —— 那是部署规范(同一 agent 同时只一个 provider serve)。
  */
-let providerChain = Promise.resolve();
-let activeProvider = null;
+const providerChains = new Map();
+const activeProviders = new Map();
 let shutdownRegistered = false;
 // Minimal setup adapter required by createChannelPluginBase.
 const setupAdapter = {
@@ -58,86 +60,124 @@ const entry = defineChannelPluginEntry({
     registerFull(ctx) {
         try {
             const config = ctx.config ?? {};
-            // token 优先取 openclaw 配置;缺失时回退读 ~/.clawrent/config.json,避免密钥写入 openclaw.json。
-            let token = config.token;
-            if (!token) {
-                try {
-                    const crPath = path.join(homedir(), ".clawrent", "config.json");
-                    let raw = readFileSync(crPath, "utf8");
-                    if (raw.charCodeAt(0) === 0xfeff)
-                        raw = raw.slice(1); // strip BOM
-                    const cr = JSON.parse(raw);
-                    token = cr.token ?? cr.agentToken;
+            // Plan 4b: /ws/group participant-scoped channel is the default. Set false to
+            // fall back to legacy /ws/session (e.g. before the server auto-provisions the
+            // provider-agent participant — Plan 4b Part A — else new sessions reject 4013).
+            const useGroupChannel = config.useGroupChannel ?? true;
+            // --- resolve the agents to serve (multi-agent array, else single token) ---
+            // multi: config.agents:[{agentId,token}] → one ProviderClient per agent.
+            // single: config.token (+ optional config.agentId), with ~/.clawrent/config.json
+            // fallback so secrets need not live in openclaw.json.
+            const resolveSingleToken = () => {
+                let token = config.token;
+                if (!token) {
+                    try {
+                        const crPath = path.join(homedir(), ".clawrent", "config.json");
+                        let raw = readFileSync(crPath, "utf8");
+                        if (raw.charCodeAt(0) === 0xfeff)
+                            raw = raw.slice(1); // strip BOM
+                        const cr = JSON.parse(raw);
+                        token = cr.token ?? cr.agentToken;
+                    }
+                    catch (e) {
+                        ctx.logger?.warn?.(`[clawrent] token fallback read failed: ${e?.message ?? e}`);
+                    }
                 }
-                catch (e) {
-                    ctx.logger?.warn?.(`[clawrent] token fallback read failed: ${e?.message ?? e}`);
+                return token;
+            };
+            let entries;
+            if (Array.isArray(config.agents) && config.agents.length > 0) {
+                entries = config.agents
+                    .filter((a) => a && typeof a.token === "string" && a.token)
+                    .map((a) => ({
+                    agentId: typeof a.agentId === "string" ? a.agentId : undefined,
+                    token: a.token,
+                }));
+                if (entries.length === 0) {
+                    ctx.logger?.warn?.("[clawrent] agents array configured but has no valid entries; channel inactive");
+                    return;
                 }
             }
-            if (!token) {
-                ctx.logger?.warn?.("[clawrent] no token configured; channel inactive");
-                return;
+            else {
+                const token = resolveSingleToken();
+                if (!token) {
+                    ctx.logger?.warn?.("[clawrent] no token configured; channel inactive");
+                    return;
+                }
+                entries = [{ agentId: config.agentId, token }];
             }
             const apiBaseUrl = config.apiBaseUrl;
             const wsUrl = config.wsUrl;
-            const agentId = config.agentId;
             const autoApprove = config.autoApproveSessions ?? true;
             const guardrailsFile = config.guardrailsFile;
-            const accountId = agentId ?? "clawrent-provider";
-            const cursorPath = config.cursorPath ??
-                path.join(homedir(), ".clawrent", "openclaw-provider-cursor.json");
+            const baseCursorPath = config.cursorPath ?? path.join(homedir(), ".clawrent", "openclaw-provider-cursor.json");
             const runtime = ctx.runtime;
             const cfg = typeof runtime?.config?.current === "function"
                 ? runtime.config.current()
                 : runtime?.cfg ?? {};
-            // 串行化:先停上一个 provider 实例(幂等保护,防 registerFull 多次调用叠加多个
-            // ProviderClient → 4009 乒乓),再起新实例。任何时刻只有一个 ProviderClient 连
-            // /ws/agent(见模块级 providerChain 注释)。chain 排队也消除了「startProvider 异步
-            // 启动期间第二次 registerClean 进入」的竞态(那时 activeProvider 尚未赋值)。
-            const start = () => startProvider({
-                agentToken: token,
-                apiBaseUrl,
-                wsUrl,
-                cursorPath,
-                agentId,
-                autoApprove,
-                guardrailsFile,
-                channelId: CHANNEL_ID,
-                accountId,
-                cfg,
-                deps: {
-                    runChannelInboundEvent,
-                    recordInboundSession: recordInboundSession,
-                    dispatchReplyWithBufferedBlockDispatcher: dispatchReplyWithBufferedBlockDispatcher,
-                },
-                onLog: (m) => ctx.logger?.info?.(`[clawrent] ${m}`),
-            }).catch((e) => {
-                ctx.logger?.error?.(`[clawrent] startProvider failed: ${String(e)}`);
-                return null;
-            });
-            providerChain = providerChain.then(async () => {
-                if (activeProvider) {
-                    try {
-                        await activeProvider.stop();
+            // (Re)start one ProviderClient per agent, each on its OWN per-agentId chain so the
+            // same agent never has two concurrent clients (4009 protection; see module doc).
+            // Different agents use different tokens and never 4009 each other (spec §6.4).
+            for (const entry of entries) {
+                const agentKey = entry.agentId ?? "default";
+                // per-agent cursor file when serving multiple agents (independent dedupe state)
+                const cursorPath = entries.length > 1 ? `${baseCursorPath}.${agentKey}` : baseCursorPath;
+                const accountId = entry.agentId ?? "clawrent-provider";
+                const start = () => startProvider({
+                    agentToken: entry.token,
+                    apiBaseUrl,
+                    wsUrl,
+                    cursorPath,
+                    agentId: entry.agentId,
+                    autoApprove,
+                    guardrailsFile,
+                    channelId: CHANNEL_ID,
+                    accountId,
+                    cfg,
+                    deps: {
+                        runChannelInboundEvent,
+                        recordInboundSession: recordInboundSession,
+                        dispatchReplyWithBufferedBlockDispatcher: dispatchReplyWithBufferedBlockDispatcher,
+                    },
+                    onLog: (m) => ctx.logger?.info?.(`[clawrent] ${m}`),
+                    useGroupChannel,
+                }).catch((e) => {
+                    ctx.logger?.error?.(`[clawrent] startProvider failed (agent=${agentKey}): ${String(e)}`);
+                    return null;
+                });
+                const prevChain = providerChains.get(agentKey) ?? Promise.resolve();
+                providerChains.set(agentKey, prevChain.then(async () => {
+                    const prev = activeProviders.get(agentKey);
+                    if (prev) {
+                        try {
+                            await prev.stop();
+                        }
+                        catch { }
+                        activeProviders.delete(agentKey);
                     }
-                    catch { }
-                    activeProvider = null;
-                }
-                activeProvider = await start();
-            });
-            // shutdown 只注册一次(多次 registerFull 不叠加 shutdown 回调);回调本身停当前
-            // activeProvider 并入队 chain,保证停的是最终存活的那个实例。
+                    const handle = await start();
+                    if (handle)
+                        activeProviders.set(agentKey, handle);
+                }));
+            }
+            // shutdown 只注册一次(多次 registerFull 不叠加);停掉所有 active provider,每个走自己的 chain,
+            // 保证停的是最终存活的实例。
             if (!shutdownRegistered) {
                 shutdownRegistered = true;
                 ctx.registerShutdown?.(() => {
-                    providerChain = providerChain.then(async () => {
-                        if (activeProvider) {
-                            try {
-                                await activeProvider.stop();
+                    for (const key of Array.from(providerChains.keys())) {
+                        const prev = providerChains.get(key) ?? Promise.resolve();
+                        providerChains.set(key, prev.then(async () => {
+                            const h = activeProviders.get(key);
+                            if (h) {
+                                try {
+                                    await h.stop();
+                                }
+                                catch { }
+                                activeProviders.delete(key);
                             }
-                            catch { }
-                            activeProvider = null;
-                        }
-                    });
+                        }));
+                    }
                 });
             }
         }

package/dist/provider.d.ts

@@ -16,6 +16,8 @@ export interface StartProviderOptions {
     cfg: any;
     deps: ProviderRuntimeDeps;
     onLog?: (msg: string) => void;
+    /** Plan 4b: opt into /ws/group (participant-scoped) instead of /ws/session. */
+    useGroupChannel: boolean;
 }
 export interface ProviderHandle {
     stop: () => Promise<void> | void;

package/dist/provider.js

@@ -17,6 +17,8 @@
 //   - dispatchReplyWithBufferedBlockDispatcher ← openclaw/plugin-sdk/reply-dispatch-runtime
 //   - runChannelInboundEvent                   ← openclaw/plugin-sdk/channel-inbound
 import { checkGuardrails, loadGuardrails } from "./guardrails.js";
+import { shouldWakeAgent, computeUsageTotal, sessionIdFromKey } from "./group-routing.js";
+import { onDiagnosticEvent } from "openclaw/plugin-sdk/diagnostic-runtime";
 const CHANNEL = "clawrent";
 /**
  * 从原始 ClawRent WS 帧提取对话文本。仅 dialogue.* 类型进入 agent;
@@ -49,6 +51,7 @@ export async function startProvider(opts) {
         ...(opts.wsUrl ? { wsUrl: opts.wsUrl } : {}),
         cursorStore: new FileCursorStore(opts.cursorPath),
         autoApprove: opts.autoApprove,
+        useGroupChannel: opts.useGroupChannel,
     });
     // Surface presence self-heal events (SDK EventEmitter). These replace the dead
     // onDisconnect/onError args previously passed to client.start() — ProviderCallbacks
@@ -57,6 +60,28 @@ export async function startProvider(opts) {
     client.on('agent:activated', () => log(`presence activated (online)`));
     client.on('agent:activation:failed', (_aid, err) => log(`presence activation FAILED (terminal): ${err?.message ?? err}`));
     client.on('agent:dead', (_aid, reason) => log(`presence DEAD — terminal close, will not reconnect: ${reason}`));
+    // Phase 3: pause/resume observability (ProviderClient 0.4.0 emits these).
+    // Pause = consumer paused this agent (4020 close, no reconnect); resume = consumer
+    // resumed → ProviderClient reconnects /ws/group. The agent simply goes idle while
+    // paused (no inbound messages arrive) — no extra plugin-side gating needed.
+    client.on('session:paused', (sid, reason) => log(`session PAUSED sid=${sid} (consumer paused this agent; will not reconnect until resumed): ${reason}`));
+    client.on('session:resumed', (sid) => log(`session RESUMED sid=${sid} — reconnecting /ws/group`));
+    // Plan 4b-2.3: capture per-session model token usage from OpenClaw diagnostics so
+    // outbound replies can carry payload.usage.totalTokens for per_token metering.
+    // Best-effort — if OpenClaw doesn't tag model.usage with a clawrent sessionKey the
+    // cache stays empty and totalTokens is omitted (backend skips → backward compatible).
+    const usageBySession = new Map();
+    const unsubDiagnostic = onDiagnosticEvent((evt) => {
+        if (evt.type !== 'model.usage')
+            return;
+        const sid = sessionIdFromKey(evt.sessionKey) ??
+            (evt.channel === CHANNEL ? evt.sessionId : undefined);
+        if (typeof sid !== 'string')
+            return;
+        const total = computeUsageTotal(evt.usage);
+        if (total > 0)
+            usageBySession.set(sid, total);
+    });
     await client.start({
         agentId: opts.agentId,
         onPendingApproval: async (session) => {
@@ -94,6 +119,12 @@ export async function startProvider(opts) {
                 log(`skip empty content session=${sessionId}`);
                 return;
             }
+            // Plan 4b-2.2: @-routing — only wake when this agent is addressed (spec §6.3).
+            // /ws/session mode (no mentions, no participantId) always wakes (unchanged).
+            if (!shouldWakeAgent(session?.participantId, message)) {
+                log(`skip not-@-ed session=${sessionId} (mentions do not include this agent)`);
+                return;
+            }
             // 护栏:危险指令直接拦截,不驱动 agent。
             const guard = checkGuardrails(content);
             if (guard.blocked) {
@@ -163,11 +194,17 @@ export async function startProvider(opts) {
                                                 const replyText = payload?.text ?? payload?.content ?? "";
                                                 if (!replyText.trim())
                                                     return;
+                                                // Plan 4b-2.3: attach captured per_token usage (if any) so the
+                                                // backend accumulates participant.totalTokens for this reply.
+                                                const capturedUsage = usageBySession.get(sessionId);
                                                 await client.send(sessionId, {
                                                     type: "dialogue.message",
-                                                    payload: { content: replyText },
+                                                    payload: {
+                                                        content: replyText,
+                                                        ...(capturedUsage ? { usage: { totalTokens: capturedUsage } } : {}),
+                                                    },
                                                 });
-                                                log(`replied session=${sessionId} (${replyText.length} chars)`);
+                                                log(`replied session=${sessionId} (${replyText.length} chars${capturedUsage ? `, ${capturedUsage} tokens` : ""})`);
                                             },
                                             // 模型跑失败时,把错误回发给租户(不静默),便于人工发现。
                                             onError: async (err) => {
@@ -200,6 +237,12 @@ export async function startProvider(opts) {
     log(`provider started (agentId=${opts.agentId ?? "auto"} autoApprove=${opts.autoApprove})`);
     return {
         stop: () => {
+            try {
+                unsubDiagnostic();
+            }
+            catch {
+                /* diagnostic unsubscribe best-effort */
+            }
             try {
                 client.stop();
             }

package/docs/openclaw-sdk-notes.md

@@ -18,7 +18,7 @@
 | `defineSetupPluginEntry` | 未强调 | 存在于 `channel-core`，供独立 setup-entry 使用 |
 | manifest `configSchema.required` | 示例多为可选 | 若把字段标 `required` 且 `plugins.entries.<id>.config` 未填，**整个 openclaw CLI 启动失败**（config validation 阻断全局）。应改为可选 + 运行时 warn |
 | `plugins install --link` | 开发期 link | 会尝试改写 `openclaw.json` 增加 `plugins.entries.<id>`；若写入导致 size-drop 过大，OpenClaw 拒绝写入并生成 `.rejected` 备份（安全机制，主文件不破坏） |
-| install 入口校验 | — | 报 `missing register/activate export` 与 `channelConfigs` 警告，即使使用 `defineChannelPluginEntry` 默认导出。install 校验与 defineChannelPluginEntry 约定存在偏差 |
+| install 入口校验 | — | 报 `missing register/activate export` 与 `channelConfigs` 警告，即使使用 `defineChannelPluginEntry` 默认导出。install 校验与 defineChannelPluginEntry 约定存在偏差（**2026.7.1 已修，见下方问题清单 #5**） |
 
 ---
 
@@ -41,6 +41,10 @@
 5. **`plugins install --link` 的入口校验与 `defineChannelPluginEntry` 不一致**：
    install 报 `missing register/activate export`，但 `defineChannelPluginEntry` 的
    返回值已含 `register`。建议统一 install 校验逻辑，或文档说明入口文件的导出约定。
+   **✅ 已修复（OpenClaw 2026.7.1）**：`resolvePluginModuleExport`（loader.ts:295）已
+   normalize default / module-wrapper 导出，接受 register/activate；PinkBo 在 2026.7.1-2
+   复测 `onStartup:true` + `defineChannelPluginEntry`（含纯 default-export 变体）干净加载、
+   不复现（openclaw/openclaw#111344 关闭为 "already implemented"）。
 6. **`channelConfigs` manifest 字段文档不足**：install 警告
    "channel plugin manifest declares clawrent without channelConfigs metadata"，
    但 manifest 已声明 `channelConfigs`。需明确该字段的精确期望结构。

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "clawrent",
   "name": "ClawRent Channel",
   "description": "OpenClaw channel plugin that turns ClawRent rental sessions into native OpenClaw conversations, so a local ClawRent provider agent can answer tenants autonomously with its own model and identity. / OpenClaw 频道插件：把 ClawRent 租赁会话桥接成 OpenClaw 原生对话，让本地 ClawRent provider 智能体用自有模型与身份自动应答租户。",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "channels": ["clawrent"],
   "activation": {
     "onStartup": false,
@@ -35,16 +35,6 @@
             "type": "string",
             "title": "ClawRent agent id"
           },
-          "pollIntervalMs": {
-            "type": "integer",
-            "title": "Poll interval (ms)",
-            "minimum": 0,
-            "maximum": 9007199254740991
-          },
-          "autoAnswer": {
-            "type": "boolean",
-            "title": "Auto-answer rental sessions"
-          },
           "autoApproveSessions": {
             "type": "boolean",
             "title": "Auto-approve incoming sessions"
@@ -53,14 +43,27 @@
             "type": "string",
             "title": "Path to guardrails markdown"
           },
-          "personaFiles": {
-            "type": "array",
-            "title": "Persona files to load into context",
-            "items": { "type": "string" }
-          },
-          "scope": {
+          "cursorPath": {
             "type": "string",
-            "title": "Workspace scope label for tenant isolation"
+            "title": "Message cursor storage path"
+          },
+          "useGroupChannel": {
+            "type": "boolean",
+            "title": "Use /ws/group participant-scoped channel (Plan 4b)",
+            "description": "true (default) = connect /ws/group (participant-scoped, @-routing, per_token usage). false = legacy /ws/session (fallback). Requires the ClawRent server to auto-provision the provider-agent participant (Plan 4b Part A) — else new sessions reject with 4013."
+          },
+          "agents": {
+            "type": "array",
+            "title": "Multiple provider agents (multi-agent mode)",
+            "description": "Serve multiple ClawRent provider agents from one gateway. Each entry starts an independent ProviderClient. Omit to serve a single agent via `token`.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "agentId": { "type": "string" },
+                "token": { "type": "string" }
+              },
+              "required": ["agentId", "token"]
+            }
           }
         }
       },
@@ -102,18 +105,14 @@
         "type": "string",
         "title": "ClawRent API base URL"
       },
+      "wsUrl": {
+        "type": "string",
+        "title": "ClawRent WebSocket URL"
+      },
       "agentId": {
         "type": "string",
         "title": "ClawRent agent id"
       },
-      "pollIntervalMs": {
-        "type": "integer",
-        "title": "Poll interval (ms)"
-      },
-      "autoAnswer": {
-        "type": "boolean",
-        "title": "Auto-answer rental sessions"
-      },
       "autoApproveSessions": {
         "type": "boolean",
         "title": "Auto-approve incoming sessions"
@@ -122,14 +121,25 @@
         "type": "string",
         "title": "Path to guardrails markdown"
       },
-      "personaFiles": {
-        "type": "array",
-        "items": { "type": "string" },
-        "title": "Persona files to load into context"
-      },
-      "scope": {
+      "cursorPath": {
         "type": "string",
-        "title": "Workspace scope label for tenant isolation"
+        "title": "Message cursor storage path"
+      },
+      "useGroupChannel": {
+        "type": "boolean",
+        "title": "Use /ws/group participant-scoped channel (Plan 4b)"
+      },
+      "agents": {
+        "type": "array",
+        "title": "Multiple provider agents (multi-agent mode)",
+        "items": {
+          "type": "object",
+          "properties": {
+            "agentId": { "type": "string" },
+            "token": { "type": "string" }
+          },
+          "required": ["agentId", "token"]
+        }
       }
     },
     "required": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawrent/openclaw-channel",
-  "version": "0.3.7",
+  "version": "0.5.0",
   "description": "OpenClaw channel plugin that turns ClawRent rental sessions into native OpenClaw conversations, so a local ClawRent provider agent can answer tenants autonomously with its own model and identity. / OpenClaw 频道插件：把 ClawRent 租赁会话桥接成 OpenClaw 原生对话，让本地 ClawRent provider 智能体用自有模型与身份自动应答租户。",
   "license": "ISC",
   "type": "module",
@@ -51,12 +51,13 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@clawrent/provider": "^0.2.0"
+    "@clawrent/provider": "^0.4.0"
   },
   "peerDependencies": {
     "openclaw": ">=2026.6.11"
@@ -69,6 +70,7 @@
   "devDependencies": {
     "openclaw": "2026.7.1",
     "@types/node": "^20",
-    "typescript": "*"
+    "typescript": "*",
+    "vitest": "^3.0.0"
   }
 }