@clawrent/openclaw-channel 0.6.0 → 0.7.0

package/README.md

@@ -135,11 +135,11 @@ See [guardrails.example.md](guardrails.example.md) for a full example. Recommend
 
 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.
+3. Restart the Gateway → the plugin loads via **channel-triggered loading** (`onStartup:false`) → the gateway autostarts the account via `startAccount` → provider WS comes online → auto-accepts sessions. With `channels.clawrent` configured, the provider is **gateway-managed**: the health-monitor sees it as healthy (no false restarts) and it auto-recovers from terminal death / startup failure.
 
 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 上线 → 自动接单。
+3. 重启 Gateway → plugin 走 **channel 触发式加载**（`onStartup:false`）→ gateway 经 `startAccount` 自启账户 → provider WS 上线 → 自动接单。配了 `channels.clawrent` 后，provider 由 **gateway 托管**：health-monitor 判其健康（无误判 restart），且终态死亡 / 启动失败时自动恢复。
 
 > ⚠️ **Do NOT add `plugins.allow: ["clawrent"]`.** In testing, adding `allow` switches the load path to strict mode and actually *blocks* `registerFull` from executing (hit in 0.3.1). Staying in auto-load (no `allow`) is the config that works in 0.3.2.
 >
@@ -149,6 +149,10 @@ See [guardrails.example.md](guardrails.example.md) for a full example. Recommend
 >
 > ⚠️ **保持 `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)。
 
+> ℹ️ **(0.7.0) Startup `missing register/activate` — the real cause was `setupEntry`.** Through 0.6.0 the gateway could log `clawrent missing register/activate export` at startup. This was **not** the default-export loader bug noted just above (that one is fixed upstream) — it was `package.json`'s `openclaw.setupEntry` pointing at `dist/setup/setup.js`: in setup-only plans the loader loaded `setup.js` as the plugin entry and ran the full register/activate check on it, which the setup module legitimately lacks. 0.7.0 removes `setupEntry`; the setup `testConnection` still works via the channel's `setup` adapter. With this fix the plugin registers as a normal plugin at startup and the gateway-managed `startAccount` autostart works.
+>
+> ℹ️ **（0.7.0）启动报 `missing register/activate` —— 真因是 `setupEntry`。** 直到 0.6.0，gateway 启动时可能报 `clawrent missing register/activate export`。这**不是**上一条说的 default-export loader bug（那条上游已修）—— 而是 `package.json` 的 `openclaw.setupEntry` 指向 `dist/setup/setup.js`：setup-only plan 下 loader 把 `setup.js` 当 plugin 入口加载并跑完整 register/activate 校验，而 setup 模块本就没有这些导出。0.7.0 删除 `setupEntry`；setup 的 `testConnection` 仍经 channel 的 `setup` adapter 可用。修复后 plugin 启动时正常注册，gateway 托管的 `startAccount` 自启才得以工作。
+
 > ⚠️ **`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.
 >
 > ⚠️ **`channels status --deep` 在无 `plugins.allow` 模式下可能误报 `not-running` / `disabled`**（OpenClaw CLI 显示层 bug，非 plugin 问题）。实际是否运行以 gateway 日志 `[clawrent] provider started` + 平台 onlineStatus 为准，**不要依赖 status 显示**。
@@ -161,9 +165,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.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.)
+> 💡 **Gateway-managed provider lifecycle (≥ 0.7.0)**: since `@clawrent/openclaw-channel@0.7.0`, the plugin implements OpenClaw's `gateway.startAccount` / `stopAccount`, making `clawrent` a first-class gateway-managed account. While the `startAccount` task is alive the gateway marks the account `running:true` (no `setStatus` needed), so OpenClaw's per-channel health-monitor sees the channel as healthy and **no longer false-restarts it every ~10 min**. If the provider terminally dies (`agent:dead` / activation failure) or fails to start (e.g. a bad token → 401), `startAccount` exits and the gateway runs a **bounded auto-restart** (retries transient failures; gives up after N attempts on persistent config errors). The per-agent-id singleton still guarantees at most one ProviderClient per agent (no 4009 ping-pong). This requires the `channels.clawrent` block to be configured — without it the plugin falls back to legacy `registerFull` startup, which has no gateway health/restart integration. You do **not** need `gateway.channelHealthCheckMinutes: 0`. (Pre-0.7.0 the health-monitor restart was a silent no-op on this plugin: it could neither see real health nor recover a dead provider, and the only workaround was disabling the monitor.)
 >
-> 💡 **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 配置文档查准确的键名。）
+> 💡 **gateway 托管的 provider 生命周期（≥ 0.7.0）**：`@clawrent/openclaw-channel@0.7.0` 起实现 OpenClaw 的 `gateway.startAccount` / `stopAccount`，`clawrent` 成为 gateway 托管的一等账户。`startAccount` 任务存活期间 gateway 自动把账户记 `running:true`（无需 `setStatus`），OpenClaw 的 per-channel health-monitor 据此判健康，**不再每 ~10min 误判 restart**。provider 终态死亡（`agent:dead` / 激活失败）或启动失败（如坏 token → 401）时 `startAccount` 退出，gateway 走 **bounded auto-restart**（瞬态故障重试；持久配置错误给足次数后放弃）。per-agent-id 单例仍保证每 agent 至多一个 ProviderClient（无 4009 乒乓）。**需配置 `channels.clawrent` 块** —— 缺失则走 legacy `registerFull` 启动，无 gateway 健康/重启集成。**无需 `gateway.channelHealthCheckMinutes: 0`**。（0.7.0 之前 health-monitor restart 对本插件是静默 no-op：既看不到真实健康、也无法恢复死亡 provider，唯一 workaround 是关掉监控。）
 >
 > ⚠️ **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.
 >

package/dist/index.js

@@ -12,18 +12,18 @@ const CHANNEL_ID = "clawrent";
  * 模块级 provider 注册表:每个 agentId 一条串行化 chain + 一个 ProviderHandle,
  * 确保同一 agent 任何时刻只有一个 ProviderClient 连 /ws/agent(或 /ws/group)。
  *
- * 背景:若 registerFull 被调用多次(OpenClaw 双加载 / startup 与 channel 双触发 /
- * health-monitor restart 叠加),而每次都 `void startProvider(...)`,会叠加多个
- * ProviderClient 用同一 agentToken 连。后端 registerAgentClient 的语义是
+ * 背景:若同一 agent 的 startProvider 被并发调用多次(OpenClaw 双加载 / startup 与
+ * channel 双触发 / health-monitor restart 叠加),每次都 `void startProvider(...)` 会
+ * 叠加多个 ProviderClient 用同一 agentToken 连。后端 registerAgentClient 的语义是
  * 「新连接 4009 踢旧连接」,provider 侧 4009 走「非终态 → 无限重连」—— 两个实例互相
  * 踢、互相重连,形成稳态乒乓振荡(后端日志指纹:connected → ~350ms disconnected →
  * 2~3s connected 循环;provider 侧表现为 `presence reconnecting in 1000ms` 高频循环)。
  * 后果:presence 立不住 + reconnect 间隙漏接会话消息。
  *
  * 解法:按 agentId 分链(chain Map),每条链把该 agent 的 startProvider 串行化 ——
- * 先干净停掉该 agent 的上一个实例(若有),再起新实例。无论 registerFull 调几次,
- * 每个 agentId 任何时刻只有一个 ProviderClient 占着连接,4009 互踢消失。
- * 不同 agent 持不同 agentToken,彼此不会 4009 互踢(可安全共驻,spec §6.4)。
+ * 先干净停掉该 agent 的上一个实例(若有),再起新实例。无论谁发起启动(startAccount
+ * 或 legacy 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)。
@@ -47,142 +47,243 @@ const base = createChannelPluginBase({
         }),
     },
 });
-const plugin = createChatChannelPlugin({
-    base: base,
-});
+/** Resolve the plugin config object from the gateway runtime cfg. */
+function pluginConfigFromCfg(cfg) {
+    return cfg?.plugins?.entries?.[CHANNEL_ID]?.config ?? cfg?.plugins?.[CHANNEL_ID]?.config ?? {};
+}
+/** Read token from ~/.clawrent/config.json when not supplied inline. */
+function readFallbackToken(log) {
+    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);
+        return cr.token ?? cr.agentToken;
+    }
+    catch (e) {
+        log?.(`[clawrent] token fallback read failed: ${e?.message ?? e}`);
+        return undefined;
+    }
+}
+/**
+ * Resolve the agents to serve from plugin config. Returns null when no usable
+ * token is configured (channel should stay inactive).
+ *  - multi:  config.agents:[{agentId,token}] → one ProviderClient per agent
+ *  - single: config.token (+ optional config.agentId), ~/.clawrent/config.json fallback
+ */
+function resolveEntries(config, log) {
+    if (Array.isArray(config.agents) && config.agents.length > 0) {
+        const 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) {
+            log?.("[clawrent] agents array configured but has no valid entries; channel inactive");
+            return null;
+        }
+        return entries;
+    }
+    let token = config.token;
+    if (!token)
+        token = readFallbackToken(log);
+    if (!token) {
+        log?.("[clawrent] no token configured; channel inactive");
+        return null;
+    }
+    return [{ agentId: config.agentId, token }];
+}
+/**
+ * Start (or replace) one ProviderClient per resolved agent entry on its per-agentId
+ * chain. The chain guarantees ≤1 ProviderClient per agent at any instant (4009 guard).
+ * Handles are tracked in activeProviders.
+ */
+function serveAgents(opts) {
+    const entries = resolveEntries(opts.config, opts.onLog);
+    if (!entries)
+        return;
+    const multi = entries.length > 1;
+    const apiBaseUrl = opts.config.apiBaseUrl;
+    const wsUrl = opts.config.wsUrl;
+    const autoApprove = opts.config.autoApproveSessions ?? true;
+    const guardrailsFile = opts.config.guardrailsFile;
+    const useGroupChannel = opts.config.useGroupChannel ?? true;
+    const triagePrefilter = opts.config.triagePrefilter;
+    const triageTwoPhase = opts.config.triageTwoPhase;
+    const baseCursorPath = opts.config.cursorPath ?? path.join(homedir(), ".clawrent", "openclaw-provider-cursor.json");
+    for (const entry of entries) {
+        const agentKey = entry.agentId ?? "default";
+        const cursorPath = multi ? `${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: opts.cfg,
+            deps: opts.deps,
+            onLog: opts.onLog,
+            onTerminal: opts.onTerminal,
+            abortSignal: opts.abortSignal,
+            useGroupChannel,
+            triagePrefilter,
+            triageTwoPhase,
+        }).catch((e) => {
+            opts.onLog(`[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);
+            }
+            const handle = await start();
+            if (handle)
+                activeProviders.set(agentKey, handle);
+        }));
+    }
+}
+/**
+ * Stop every active provider, each on its own chain so we stop the final live
+ * instance. Returns a promise that resolves once all current chains settle.
+ */
+function stopAllAgents() {
+    const waits = [];
+    for (const key of Array.from(providerChains.keys())) {
+        const prev = providerChains.get(key) ?? Promise.resolve();
+        const next = prev.then(async () => {
+            const h = activeProviders.get(key);
+            if (h) {
+                try {
+                    await h.stop();
+                }
+                catch { }
+                activeProviders.delete(key);
+            }
+        });
+        providerChains.set(key, next);
+        waits.push(next.catch(() => { }));
+    }
+    return Promise.all(waits).then(() => { });
+}
+const pluginDeps = {
+    runChannelInboundEvent,
+    recordInboundSession: recordInboundSession,
+    dispatchReplyWithBufferedBlockDispatcher: dispatchReplyWithBufferedBlockDispatcher,
+};
+/**
+ * Gateway-account lifecycle adapter. When `channels.clawrent` is configured, the
+ * gateway autostarts the account at boot and on every health-monitor restart by
+ * calling startAccount; stopAccount is called on stop/restart. This is what makes
+ * the provider recover after a terminal death WITHOUT disabling health-monitor.
+ *
+ * Why no setStatus: the gateway sets `running:true` while the startAccount task is
+ * alive and `running:false` (setStoppedRuntime) when it exits. evaluateChannelHealth
+ * keys off `running`, so simply keeping this task alive while the provider is up is
+ * enough to be seen as healthy (no false-positive restart). When the provider
+ * terminally dies (onTerminal), we exit; the gateway then auto-restarts us with a
+ * bounded backoff (server-channels restartAttempts). We must NOT set
+ * `terminalDisconnect` or the gateway would skip the restart.
+ */
+const gatewayAdapter = {
+    async startAccount(ctx) {
+        const config = pluginConfigFromCfg(ctx.cfg);
+        const log = (m) => ctx.log?.info?.(m);
+        const entries = resolveEntries(config, log);
+        if (!entries) {
+            ctx.log?.warn?.("[clawrent] startAccount: no token configured; staying stopped");
+            return; // exit cleanly → gateway marks not-running (not an error)
+        }
+        if (ctx.abortSignal?.aborted)
+            return;
+        // Hold this task alive until a provider terminally dies or the account is
+        // aborted. On exit (finally), stop everything; the gateway then restarts us.
+        let release;
+        const exited = new Promise((resolve) => { release = resolve; });
+        let exitedOnce = false;
+        const exitOnce = (reason) => {
+            if (exitedOnce)
+                return;
+            exitedOnce = true;
+            ctx.log?.error?.(`[clawrent] exiting account for restart: ${String(reason)}`);
+            try {
+                release();
+            }
+            catch { }
+        };
+        if (ctx.abortSignal) {
+            ctx.abortSignal.addEventListener("abort", () => exitOnce("account aborted"), { once: true });
+        }
+        serveAgents({
+            config,
+            cfg: ctx.cfg,
+            deps: pluginDeps,
+            onLog: log,
+            onTerminal: (agentKey, reason) => exitOnce(`provider terminally dead (agent=${agentKey}): ${String(reason)}`),
+            abortSignal: ctx.abortSignal,
+        });
+        log("[clawrent] startAccount: provider(s) started; holding account alive");
+        try {
+            await exited;
+        }
+        finally {
+            log("[clawrent] startAccount: stopping provider(s) before exit");
+            await stopAllAgents();
+        }
+    },
+    async stopAccount(_ctx) {
+        // The gateway also aborts startAccount's abortSignal (which stops clients via
+        // startProvider); this explicit stop is the idempotent belt-and-suspenders path
+        // for flows that call stopAccount directly.
+        await stopAllAgents();
+    },
+};
+// Attach the gateway-account adapter. createChannelPluginBase/createChatChannelPlugin
+// don't expose a `gateway` option today, but ChannelPlugin carries it and the runtime
+// reads `plugin.gateway.startAccount/stopAccount`, so we attach it post-construction.
+const chatPlugin = createChatChannelPlugin({ base: base });
+const plugin = { ...chatPlugin, gateway: gatewayAdapter };
 const entry = defineChannelPluginEntry({
     id: CHANNEL_ID,
     name: "ClawRent",
     description: "ClawRent rental-session channel: turns ClawRent rental sessions into native OpenClaw conversations so a local provider agent can answer tenants autonomously with its own model and identity. Uses @clawrent/provider for push-based inbound (no CLI daemon).",
     plugin: plugin,
-    // 注意: 不在 entry 里注册 CLI command —— registerCliMetadata 阶段的 registerCommand
+    // 不在 entry 里注册 CLI command —— registerCliMetadata 阶段的 registerCommand
     // 要求 command.name 字段, 多余且易错; channel 插件无需自定义 command。
     registerFull(ctx) {
         try {
-            const config = ctx.config ?? {};
-            // 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;
-            // D3: triage switches (optional; prefilter defaults on at the provider, twoPhase off).
-            const triagePrefilter = config.triagePrefilter;
-            const triageTwoPhase = config.triageTwoPhase;
-            // --- 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}`);
-                    }
-                }
-                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;
-                }
-            }
-            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 autoApprove = config.autoApproveSessions ?? true;
-            const guardrailsFile = config.guardrailsFile;
-            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 ?? {};
-            // (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,
-                    triagePrefilter,
-                    triageTwoPhase,
-                }).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);
-                    }
-                    const handle = await start();
-                    if (handle)
-                        activeProviders.set(agentKey, handle);
-                }));
+            // Adaptive start: when `channels.clawrent` is configured, the gateway owns the
+            // account lifecycle (autostart + health-monitor restart via startAccount). Don't
+            // start the provider here — startAccount will. Otherwise (no channels.clawrent)
+            // fall back to starting from registerFull so the channel still works.
+            if (cfg?.channels?.[CHANNEL_ID]) {
+                ctx.logger?.info?.("[clawrent] channels.clawrent configured — gateway owns account lifecycle; provider starts via startAccount");
+                return;
             }
-            // shutdown 只注册一次(多次 registerFull 不叠加);停掉所有 active provider,每个走自己的 chain,
-            // 保证停的是最终存活的实例。
+            const config = ctx.config ?? pluginConfigFromCfg(cfg) ?? {};
+            ctx.logger?.info?.("[clawrent] no channels.clawrent — starting provider from registerFull (legacy)");
+            serveAgents({ config, cfg, deps: pluginDeps, onLog: (m) => ctx.logger?.info?.(m) });
+            // shutdown 只注册一次(多次 registerFull 不叠加);停掉所有 active provider。
             if (!shutdownRegistered) {
                 shutdownRegistered = true;
                 ctx.registerShutdown?.(() => {
-                    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);
-                            }
-                        }));
-                    }
+                    void stopAllAgents();
                 });
             }
         }

package/dist/provider.d.ts

@@ -21,6 +21,18 @@ export interface StartProviderOptions {
     /** D3: triage switches. prefilter default on; twoPhase default off. */
     triagePrefilter?: boolean;
     triageTwoPhase?: boolean;
+    /**
+     * Fired once when this provider terminally dies (ProviderClient emits
+     * `agent:dead` / `agent:activation:failed`). The gateway-account lifecycle
+     * (index.ts startAccount) uses this to exit the account task so the gateway
+     * auto-restarts it (bounded backoff). Optional — absent in legacy mode.
+     */
+    onTerminal?: (agentKey: string, reason: unknown) => void;
+    /**
+     * Account abort signal. When aborted (gateway stopping the account), stop the
+     * ProviderClient. Removed again in the returned handle's stop() for cleanliness.
+     */
+    abortSignal?: AbortSignal;
 }
 export interface ProviderHandle {
     stop: () => Promise<void> | void;

package/dist/provider.js

@@ -56,10 +56,40 @@ export async function startProvider(opts) {
     // Surface presence self-heal events (SDK EventEmitter). These replace the dead
     // onDisconnect/onError args previously passed to client.start() — ProviderCallbacks
     // never had those fields, so they were silently ignored.
+    const agentKey = opts.agentId ?? "default";
+    // Terminal death is fire-once: notifies the account lifecycle (onTerminal) so the
+    // gateway can auto-restart the account. Guarded so multiple terminal events don't
+    // re-fire.
+    let terminated = false;
+    const fireTerminal = (reason) => {
+        if (terminated)
+            return;
+        terminated = true;
+        opts.onTerminal?.(agentKey, reason);
+    };
     client.on('agent:reconnecting', (delay) => log(`presence reconnecting in ${delay}ms`));
     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}`));
+    client.on('agent:activation:failed', (_aid, err) => {
+        log(`presence activation FAILED (terminal): ${err?.message ?? err}`);
+        fireTerminal(err);
+    });
+    client.on('agent:dead', (_aid, reason) => {
+        log(`presence DEAD — terminal close, will not reconnect: ${reason}`);
+        fireTerminal(reason);
+    });
+    // Stop the client when the gateway aborts the account (stopChannel/restart).
+    const onAbort = () => {
+        try {
+            client.stop();
+        }
+        catch { /* best-effort */ }
+    };
+    if (opts.abortSignal) {
+        if (opts.abortSignal.aborted)
+            onAbort();
+        else
+            opts.abortSignal.addEventListener("abort", onAbort, { once: true });
+    }
     // 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
@@ -82,7 +112,13 @@ export async function startProvider(opts) {
         if (total > 0)
             usageBySession.set(sid, total);
     });
-    await client.start({
+    // client.start() resolves once the ProviderClient is set up. If initial setup
+    // throws (e.g. 401 auth, unreachable API), treat it as terminal so the account
+    // lifecycle (startAccount) exits and the gateway runs its bounded auto-restart
+    // (retries transient failures; gives up on persistent config errors). Without
+    // this, a setup failure would leave startAccount holding the task alive with no
+    // live provider and no recovery.
+    const startError = await client.start({
         agentId: opts.agentId,
         onPendingApproval: async (session) => {
             // 平台基线为 false(不自动批准);批准动作只在此端侧一道门发生。
@@ -268,7 +304,22 @@ export async function startProvider(opts) {
                 log(`runChannelInboundEvent failed session=${sessionId}: ${String(e)}`);
             }
         },
-    });
+    }).then(() => undefined, (e) => e);
+    if (startError !== undefined) {
+        log(`provider failed to start (terminal): ${String(startError)}`);
+        fireTerminal(startError);
+        return {
+            stop: () => {
+                if (opts.abortSignal)
+                    opts.abortSignal.removeEventListener("abort", onAbort);
+                // client.start() threw before setup completed (e.g. 401 auth, unreachable
+                // API). Do NOT call client.stop() here — the SDK has an internal pending
+                // firstActivation promise that stop() would reject with "Provider stopped",
+                // and that rejection is unhandled and crashes the host gateway. The client
+                // never finished starting, so there is nothing to stop.
+            },
+        };
+    }
     log(`provider started (agentId=${opts.agentId ?? "auto"} autoApprove=${opts.autoApprove})`);
     return {
         stop: () => {
@@ -278,6 +329,8 @@ export async function startProvider(opts) {
             catch {
                 /* diagnostic unsubscribe best-effort */
             }
+            if (opts.abortSignal)
+                opts.abortSignal.removeEventListener("abort", onAbort);
             try {
                 client.stop();
             }

package/dist/setup/setup.d.ts

@@ -7,7 +7,3 @@ export declare function testConnection(config: {
     token?: string;
     apiBaseUrl?: string;
 }): Promise<ClawRentConnectionResult>;
-declare const _default: {
-    testConnection: typeof testConnection;
-};
-export default _default;

package/dist/setup/setup.js

@@ -19,4 +19,3 @@ export async function testConnection(config) {
         return { ok: false, error: String(e?.message ?? e) };
     }
 }
-export default { testConnection };

package/docs/openclaw-sdk-notes.md

@@ -45,6 +45,20 @@
    normalize default / module-wrapper 导出，接受 register/activate；PinkBo 在 2026.7.1-2
    复测 `onStartup:true` + `defineChannelPluginEntry`（含纯 default-export 变体）干净加载、
    不复现（openclaw/openclaw#111344 关闭为 "already implemented"）。
+   **⚠️ 但 clawrent 直到 0.6.0 仍在启动报 `missing register/activate`——真因是 #7（setupEntry），不是本条。** 本条（default-export loader bug）与 clawrent 实际踩到的validation 失败是**两条不同的路径**，别混。
+7. **`openclaw.setupEntry` 被当 plugin 入口校验（2026-08-07 实测，0.7.0 已绕过）**：
+   `package.json` 的 `openclaw.setupEntry` / `runtimeSetupEntry` 指向 `./dist/setup/setup.js`
+   时，loader 在 setup-only / prefer-setup registration plan 下会把 setup.js 当作主入口加载
+   （`loader-svIpMF0d.js:1915` `loadEntry = loadSetupEntry && runtimeSetupEntry ? runtimeSetupEntry : runtimeCandidateEntry`），
+   再对它跑完整 plugin 的 register/activate 校验。而 setup.js 是 setup 接口（导出 `{testConnection}`），
+   合法地没有 register/activate → 误报 `clawrent missing register/activate export` → plugin
+   启动 validation 失败、不进注册 plugin 列表（只剩 channel 触发式加载的 registerFull 兜底，所以显得"非阻塞"）。
+   诊断法：`OPENCLAW_PLUGIN_LOAD_DEBUG=1` 起 gateway，看 `module shape: export:object keys=__esModule,default,testConnection`
+   （= setup.js 形态，非 index.js 的 entry）即铁证。`describePluginModuleExportShape`（loader:392）输出。
+   **plugin 侧修法**：删 `package.json` 的 `setupEntry`/`runtimeSetupEntry`（setup 向导 testConnection
+   由 `createChannelPluginBase({setup})` adapter 覆盖；setup-only 模式 fallback 加载 index.js，registerFull
+   只 full 模式起 provider、setup-only 不起，安全）。**建议回馈上游**：loader 不应对 setupEntry 跑完整
+   register/activate 校验（setup entry 是 `defineSetupPluginEntry`/setup 契约，非 plugin entry）。
 6. **`channelConfigs` manifest 字段文档不足**：install 警告
    "channel plugin manifest declares clawrent without channelConfigs metadata"，
    但 manifest 已声明 `channelConfigs`。需明确该字段的精确期望结构。

package/openclaw.plugin.json

@@ -2,11 +2,15 @@
   "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.6.0",
-  "channels": ["clawrent"],
+  "version": "0.7.0",
+  "channels": [
+    "clawrent"
+  ],
   "activation": {
     "onStartup": false,
-    "onChannels": ["clawrent"]
+    "onChannels": [
+      "clawrent"
+    ]
   },
   "channelConfigs": {
     "clawrent": {
@@ -69,10 +73,17 @@
             "items": {
               "type": "object",
               "properties": {
-                "agentId": { "type": "string" },
-                "token": { "type": "string" }
+                "agentId": {
+                  "type": "string"
+                },
+                "token": {
+                  "type": "string"
+                }
               },
-              "required": ["agentId", "token"]
+              "required": [
+                "agentId",
+                "token"
+              ]
             }
           }
         }
@@ -161,10 +172,17 @@
         "items": {
           "type": "object",
           "properties": {
-            "agentId": { "type": "string" },
-            "token": { "type": "string" }
+            "agentId": {
+              "type": "string"
+            },
+            "token": {
+              "type": "string"
+            }
           },
-          "required": ["agentId", "token"]
+          "required": [
+            "agentId",
+            "token"
+          ]
         }
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawrent/openclaw-channel",
-  "version": "0.6.0",
+  "version": "0.7.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",
@@ -33,8 +33,6 @@
     "runtimeExtensions": [
       "./dist/index.js"
     ],
-    "setupEntry": "./dist/setup/setup.js",
-    "runtimeSetupEntry": "./dist/setup/setup.js",
     "install": {
       "clawhubSpec": "clawhub:@clawrent/openclaw-channel",
       "defaultChoice": "clawhub",