@clawrent/openclaw-channel 0.2.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 ClawRent
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @clawrent/openclaw-channel
+
+OpenClaw **channel plugin** that turns ClawRent rental sessions into native
+OpenClaw conversations, so a local **ClawRent provider agent** can answer rental
+requests autonomously using its own model and identity.
+
+> 官方维护的通用 ClawRent 频道模板。由 ClawRent 官方基于 PinkBo 移交的原型接手开发
+> （接管记录见 [CLAWRENT_HANDOFF.md](CLAWRENT_HANDOFF.md) 的 R1–R5 需求清单）。
+
+## 它做什么
+
+把一个 ClawRent 租赁会话桥接成一个 OpenClaw 原生对话频道：
+
+- 用 `@clawrent/provider` 的 `ProviderClient` **WS push 接收**租户消息（无需 CLI daemon / 轮询）。
+- 危险指令走护栏拦截，不驱动 agent。
+- 驱动 OpenClaw agent 跑一个 inbound turn，把模型回复**回发**到 ClawRent 会话。
+- 在 `onPendingApproval` 端侧门执行批准策略（护栏最高优先级：危险类永远转人工）。
+
+## 数据流
+
+```
+ClawRent WS 推送
+  → ProviderClient.onMessage(session, message)        [@clawrent/provider]
+  → extractDialogue()        取 payload.content / type
+  → checkGuardrails()        护栏判定（危险 → 拦截，不驱动 agent）
+  → runChannelInboundEvent({ channel:"clawrent", raw, adapter })   [openclaw/plugin-sdk]
+       adapter.resolveTurn → { ctxPayload, recordInboundSession, runDispatch }
+         runDispatch → dispatchReplyWithBufferedBlockDispatcher（跑 agent）
+           → providerClient.send(sessionId, { type, payload:{content} })   // 回发 ClawRent
+```
+
+## 目录结构
+
+```
+openclaw-channel/
+├─ openclaw.plugin.json   # 插件 manifest（严格 schema，含 channelConfigs.clawrent.schema）
+├─ package.json           # openclaw 扩展入口声明
+├─ tsconfig.json          # tsc 配置（moduleResolution: Bundler，靠 node_modules 解析）
+├─ src/
+│  ├─ index.ts            # 频道入口：defineChannelPluginEntry + createChatChannelPlugin + startProvider
+│  ├─ provider.ts         # ProviderClient 驱动无人值守 provider：onPendingApproval 批准策略 + onMessage 对话路由
+│  ├─ guardrails.ts       # 护栏判定（内置最小示例 + guardrailsFile 外置追加）
+│  └─ setup/setup.ts      # 配置 setup 入口（testConnection：token 校验）
+├─ docs/
+│  └─ openclaw-sdk-notes.md   # OpenClaw SDK 踩坑笔记（文档 vs 实际，开发必读）
+└─ CLAWRENT_HANDOFF.md    # 移交说明 + R1–R5 需求清单
+```
+
+## 构建 / 校验
+
+```bash
+npm install        # 拉 openclaw（SDK 类型）+ @clawrent/provider
+npm run build      # tsc -p tsconfig.json → dist/
+npm run typecheck  # 不产物的类型校验
+```
+
+`npm install` 后 `openclaw` 进本地 `node_modules`，`moduleResolution: "Bundler"` 经其
+`exports` 白名单解析 `openclaw/plugin-sdk/*`，**不依赖全局安装的 openclaw 路径**。
+
+## 配置
+
+`plugins.entries.clawrent.config` 字段：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `token` | 否* | ClawRent agent token。缺失时回退读 `~/.clawrent/config.json` 的 `token`/`agentToken`，避免密钥写入 openclaw.json |
+| `apiBaseUrl` | 否 | ClawRent API 地址，默认 `https://clawrent.cloud` |
+| `wsUrl` | 否 | ClawRent WebSocket 地址 |
+| `agentId` | 否 | ClawRent agent id（UUID），留空由 token 自动解析 |
+| `autoApproveSessions` | 否 | 端侧代理批准开关。`true`（默认）= 非危险会话按护栏自动接单，危险类仍转人工；`false` = 全部转人工 |
+| `guardrailsFile` | 否 | 外置护栏策略文件（每行 `/regex/ \|\| 原因`，`#` 注释），规则追加在内置护栏之后 |
+| `cursorPath` | 否 | 消息游标存储路径，默认 `~/.clawrent/openclaw-provider-cursor.json` |
+
+\* token 必须在 config 或 `~/.clawrent/config.json` 二者之一中存在，否则频道不激活（仅 warn）。
+
+### openclaw.json 示例
+
+```json
+"plugins": {
+  "entries": {
+    "clawrent": {
+      "enabled": true,
+      "config": {
+        "apiBaseUrl": "https://clawrent.cloud",
+        "agentId": "019f35a8-...",
+        "autoApproveSessions": true,
+        "guardrailsFile": "/path/to/clawrent-guardrails.md"
+      }
+    }
+  }
+}
+```
+
+## 启用
+
+1. `openclaw plugins install --link <本目录>`，或手动把本目录加入 `openclaw.json` 的 `plugins.load.paths`。
+2. 按上方示例填 `plugins.entries.clawrent.config`（token 可放 `~/.clawrent/config.json`）。
+3. 重启 Gateway。
+
+> manifest 的 `configSchema.required` 保持空数组：channel plugin 的 required 字段缺失会让
+> `openclaw` CLI 整体启动失败（config validation 阻断全局）。字段改为可选 + 运行时 warn。
+
+## 设计要点
+
+- **WS push inbound**：经 `@clawrent/provider` 的 `ProviderClient` 接收推送，不轮询、无需 CLI daemon。
+- **护栏原生**：`guardrails.ts` 内置最小安全示例（拦结构化 `instruction.*`），完整策略由
+  `guardrailsFile` 外置追加——plugin 不绑任何一家 provider 的私货，可作通用频道模板。
+- **身份一致**：平台答案即本地 provider agent（同 token / persona），成长通过 workspace 文件自然同步。
+- **端侧批准门**：`onPendingApproval` 是唯一批准闸门；护栏最高优先级（危险永远转人工），
+  其余跟随 `autoApproveSessions`。详见移交文档 §2.2 关于「平台 autoApprove 状态 SDK 不暴露」的已知限制。
+
+## Typing indicator（v0.2.0+）
+
+provider agent 驱动回复时，向 consumer 发送 `dialogue.typing` 控制信号，consumer 侧显示
+「provider 正在输入」，填补 provider 生成回复前的 UX 空窗。
+
+- **依赖** `@clawrent/provider@^0.1.1`（`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 心跳足以保活，回复到达后自然替换。
+
+## 更多
+
+- [docs/openclaw-sdk-notes.md](docs/openclaw-sdk-notes.md) — OpenClaw Channel Plugin SDK 实测事实表 + 待提交官方的问题清单（开发/升级必读）。
+- [CLAWRENT_HANDOFF.md](CLAWRENT_HANDOFF.md) — 移交说明 + R1–R5 需求清单（approval 结构化策略 / 护栏平台下发 / autoApprove 语义文档化 等）。

package/dist/guardrails.d.ts

@@ -0,0 +1,14 @@
+export interface GuardrailResult {
+    blocked: boolean;
+    reason?: string;
+}
+export declare function loadGuardrails(path?: string): string;
+/**
+ * 解析外置护栏文件(每行: `/regex/ || 原因`,`#` 开头为注释)。
+ * 规则作为内置 BLOCK_PATTERNS 的**追加**(不覆盖),实现策略外置、可扩展。
+ */
+export declare function parseGuardrailRules(content: string): {
+    re: RegExp;
+    reason: string;
+}[];
+export declare function checkGuardrails(text: string, fileContent?: string): GuardrailResult;

package/dist/guardrails.js

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+// 内置最小安全示例:仅拦截 ClawRent 结构化危险指令(instruction.exec/read_file/write_file)。
+// 注意:完整护栏策略**不应写死在 plugin 里**——应由需求方通过 `guardrailsFile`
+// (外置,每行 `/regex/ || 原因`) 或平台下发的 approval 策略提供。本 plugin 只做
+// “读策略 + 判定”的通用壳,不绑定任何一家 provider 的私货。
+const BLOCK_PATTERNS = [
+    // ClawRent 消息类型层面的危险指令(结构化 instruction.* 一律拦)
+    { re: /instruction\.(exec|read_file|write_file)/i, reason: "拒绝结构化危险指令(exec/文件读写)" },
+];
+export function loadGuardrails(path) {
+    if (!path)
+        return "";
+    try {
+        return fs.readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * 解析外置护栏文件(每行: `/regex/ || 原因`,`#` 开头为注释)。
+ * 规则作为内置 BLOCK_PATTERNS 的**追加**(不覆盖),实现策略外置、可扩展。
+ */
+export function parseGuardrailRules(content) {
+    const out = [];
+    for (const raw of content.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const idx = line.indexOf("||");
+        if (idx < 0)
+            continue;
+        const pattern = line.slice(0, idx).trim();
+        const reason = line.slice(idx + 2).trim() || "命中外部护栏规则";
+        try {
+            out.push({ re: new RegExp(pattern, "i"), reason });
+        }
+        catch { /* 忽略非法正则 */ }
+    }
+    return out;
+}
+export function checkGuardrails(text, fileContent) {
+    // 内置规则始终生效(fallback);外置文件规则追加在其后。
+    const rules = [...BLOCK_PATTERNS, ...(fileContent ? parseGuardrailRules(fileContent) : [])];
+    for (const p of rules) {
+        if (p.re.test(text)) {
+            return {
+                blocked: true,
+                reason: `命中护栏拦截规则：${p.reason}。需人工介入，provider 不会自动执行。`,
+            };
+        }
+    }
+    return { blocked: false };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
+declare const entry: ReturnType<typeof defineChannelPluginEntry>;
+export default entry;

package/dist/index.js

@@ -0,0 +1,104 @@
+import { defineChannelPluginEntry, createChatChannelPlugin, createChannelPluginBase, } from "openclaw/plugin-sdk/channel-core";
+import { runChannelInboundEvent } from "openclaw/plugin-sdk/channel-inbound";
+import { recordInboundSession } from "openclaw/plugin-sdk/conversation-runtime";
+import { dispatchReplyWithBufferedBlockDispatcher } from "openclaw/plugin-sdk/reply-dispatch-runtime";
+import path from "node:path";
+import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
+import { startProvider } from "./provider.js";
+import { testConnection } from "./setup/setup.js";
+const CHANNEL_ID = "clawrent";
+// Minimal setup adapter required by createChannelPluginBase.
+const setupAdapter = {
+    async testConnection(cfg) {
+        return testConnection({ token: cfg?.token, apiBaseUrl: cfg?.apiBaseUrl });
+    },
+};
+const base = createChannelPluginBase({
+    id: CHANNEL_ID,
+    setup: setupAdapter,
+    config: {
+        listAccountIds: () => ["clawrent-provider"],
+        resolveAccount: (_cfg, accountId) => ({
+            accountId: accountId ?? "clawrent-provider",
+        }),
+    },
+});
+const plugin = createChatChannelPlugin({
+    base: base,
+});
+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
+    // 要求 command.name 字段, 多余且易错; channel 插件无需自定义 command。
+    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;
+                }
+                catch (e) {
+                    ctx.logger?.warn?.(`[clawrent] token fallback read failed: ${e?.message ?? e}`);
+                }
+            }
+            if (!token) {
+                ctx.logger?.warn?.("[clawrent] no token configured; channel inactive");
+                return;
+            }
+            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 runtime = ctx.runtime;
+            const cfg = typeof runtime?.config?.current === "function"
+                ? runtime.config.current()
+                : runtime?.cfg ?? {};
+            let handle = null;
+            void 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}`),
+            })
+                .then((h) => {
+                handle = h;
+            })
+                .catch((e) => ctx.logger?.error?.(`[clawrent] startProvider failed: ${String(e)}`));
+            ctx.registerShutdown?.(() => {
+                if (handle)
+                    void handle.stop();
+            });
+        }
+        catch (e) {
+            ctx.logger?.error?.(`[clawrent] registerFull threw: ${e?.stack ?? e}`);
+        }
+    },
+});
+export default entry;

package/dist/provider.d.ts

@@ -0,0 +1,23 @@
+export interface ProviderRuntimeDeps {
+    runChannelInboundEvent: (params: any) => Promise<any>;
+    recordInboundSession: (params: any) => Promise<void>;
+    dispatchReplyWithBufferedBlockDispatcher: (params: any) => Promise<any>;
+}
+export interface StartProviderOptions {
+    agentToken: string;
+    apiBaseUrl?: string;
+    wsUrl?: string;
+    cursorPath: string;
+    agentId?: string;
+    autoApprove: boolean;
+    guardrailsFile?: string;
+    channelId: string;
+    accountId: string;
+    cfg: any;
+    deps: ProviderRuntimeDeps;
+    onLog?: (msg: string) => void;
+}
+export interface ProviderHandle {
+    stop: () => Promise<void> | void;
+}
+export declare function startProvider(opts: StartProviderOptions): Promise<ProviderHandle>;

package/dist/provider.js

@@ -0,0 +1,210 @@
+// provider.ts — 用 @clawrent/provider 的 ProviderClient 驱动无人值守 provider。
+//
+// 数据流(已由 probe-inbound.mjs 实测钉死 kernel 契约):
+//
+//   ClawRent WS 推送 → ProviderClient.onMessage(session, message)
+//     → 解析 message(取 payload.content / type)
+//     → 护栏判定(危险指令直接拦截,不驱动 agent)
+//     → runChannelInboundEvent({ channel:"clawrent", raw, adapter })
+//          adapter.ingest      → NormalizedTurnInput
+//          adapter.resolveTurn → { ...base, ctxPayload, recordInboundSession, runDispatch }
+//            runDispatch → dispatchReplyWithBufferedBlockDispatcher(跑 agent)
+//              → dispatcherOptions.deliver(payload)  // payload.text = 模型答案
+//                → providerClient.send(sessionId, { type, payload:{content} })  // 回发 ClawRent
+//
+// 依赖来源(已钉死):
+//   - recordInboundSession                    ← openclaw/plugin-sdk/conversation-runtime
+//   - dispatchReplyWithBufferedBlockDispatcher ← openclaw/plugin-sdk/reply-dispatch-runtime
+//   - runChannelInboundEvent                   ← openclaw/plugin-sdk/channel-inbound
+import { checkGuardrails, loadGuardrails } from "./guardrails.js";
+const CHANNEL = "clawrent";
+/**
+ * 从原始 ClawRent WS 帧提取对话文本。仅 dialogue.* 类型进入 agent;
+ * 其余(instruction.* / result.* / task_update 等)按护栏与业务规则处理。
+ */
+function extractDialogue(message) {
+    const type = String(message?.type ?? message?.messageType ?? "");
+    const content = message?.payload?.content ??
+        message?.content ??
+        "";
+    return { type, content: String(content ?? "") };
+}
+export async function startProvider(opts) {
+    const log = (m) => (opts.onLog ? opts.onLog(m) : console.log(`[clawrent:provider] ${m}`));
+    // 动态 import,避免插件在未安装 @clawrent/provider 时整体加载失败。
+    let ProviderClient;
+    let FileCursorStore;
+    try {
+        const mod = await import("@clawrent/provider");
+        ProviderClient = mod.ProviderClient;
+        FileCursorStore = mod.FileCursorStore;
+    }
+    catch (e) {
+        log(`@clawrent/provider not available: ${String(e)}; provider inactive`);
+        return { stop: () => { } };
+    }
+    const client = new ProviderClient({
+        agentToken: opts.agentToken,
+        ...(opts.apiBaseUrl ? { apiUrl: opts.apiBaseUrl } : {}),
+        ...(opts.wsUrl ? { wsUrl: opts.wsUrl } : {}),
+        cursorStore: new FileCursorStore(opts.cursorPath),
+        autoApprove: opts.autoApprove,
+    });
+    await client.start({
+        agentId: opts.agentId,
+        onPendingApproval: async (session) => {
+            // 平台基线为 false(不自动批准);批准动作只在此端侧一道门发生。
+            // 护栏最高优先级:危险类永远转人工,无视 autoApprove 开关。
+            const task = String(session?.taskDescription ?? session?.task ?? "");
+            const fileContent = loadGuardrails(opts.guardrailsFile);
+            const res = checkGuardrails(task, fileContent);
+            if (res.blocked) {
+                log(`[clawrent] blocked pending session=${session?.sessionId}: ${res.reason}`);
+                return false; // 危险 → 转人工
+            }
+            // 非危险:跟随端侧代理开关(默认 true = 按护栏自动接单;false = 全转人工)。
+            log(`pending approval (non-dangerous) session=${session?.sessionId} autoApprove=${opts.autoApprove}`);
+            return opts.autoApprove;
+        },
+        onSessionNew: (session) => {
+            log(`session new: ${session?.sessionId}`);
+        },
+        onSessionEnded: (session, reason) => {
+            log(`session ended: ${session?.sessionId} reason=${reason ?? ""}`);
+        },
+        onDisconnect: (info) => {
+            log(`disconnected: ${info?.reason ?? JSON.stringify(info)}`);
+        },
+        onError: (err) => {
+            log(`provider error: ${err?.message ?? JSON.stringify(err)}`);
+        },
+        onMessage: async (session, message) => {
+            const sessionId = session?.sessionId;
+            const rawType = String(message?.type ?? message?.messageType ?? "?");
+            log(`onMessage RAW session=${sessionId} type=${rawType}`);
+            const { type, content } = extractDialogue(message);
+            log(`onMessage session=${sessionId} type=${type} len=${content.length}`);
+            // 只处理对话类;其它类型不驱动 agent。
+            if (!type.startsWith("dialogue")) {
+                log(`skip non-dialogue message type=${type} session=${sessionId}`);
+                return;
+            }
+            if (!content.trim()) {
+                log(`skip empty content session=${sessionId}`);
+                return;
+            }
+            // 护栏:危险指令直接拦截,不驱动 agent。
+            const guard = checkGuardrails(content);
+            if (guard.blocked) {
+                log(`guardrail blocked session=${sessionId}: ${guard.reason}`);
+                await client
+                    .send(sessionId, {
+                    type: "dialogue.message",
+                    payload: { content: `⚠️ ${guard.reason}` },
+                })
+                    .catch((e) => log(`send block notice failed: ${String(e)}`));
+                return;
+            }
+            // 驱动 OpenClaw agent 跑一个 inbound turn。
+            const routeSessionKey = `${CHANNEL}:${sessionId}`;
+            // Windows 文件名不允许冒号, storePath 需做安全转义。
+            const storePath = routeSessionKey.replace(/[:]/g, "_");
+            const consumerId = session?.consumerUserId ?? "consumer";
+            const ctxPayload = {
+                From: `${CHANNEL}:${consumerId}`,
+                Body: content,
+                RawBody: content,
+                BodyForAgent: content,
+                channel: CHANNEL,
+                SessionKey: routeSessionKey,
+            };
+            const raw = { sessionId, consumerId, content, message };
+            try {
+                await opts.deps.runChannelInboundEvent({
+                    channel: CHANNEL,
+                    accountId: opts.accountId,
+                    raw,
+                    log: (ev) => {
+                        if (ev?.event === "error") {
+                            log(`turn ${ev.stage} error: ${ev?.error?.message ?? ev?.error}`);
+                        }
+                    },
+                    adapter: {
+                        ingest: (r) => ({
+                            id: `${r.sessionId}:${r.message?.id ?? Date.now()}`,
+                            timestamp: Date.now(),
+                            rawText: r.content,
+                            textForAgent: r.content,
+                            textForCommands: r.content,
+                            raw: r,
+                        }),
+                        resolveTurn: () => ({
+                            channel: CHANNEL,
+                            accountId: opts.accountId,
+                            routeSessionKey,
+                            storePath,
+                            ctxPayload,
+                            recordInboundSession: opts.deps.recordInboundSession,
+                            record: { createIfMissing: true, updateLastRoute: true },
+                            runDispatch: async () => {
+                                // 通知 consumer:provider 正在生成回复(dialogue.typing 控制信号,后端短路
+                                // 转发、不持久化/不计 metering)。WS-only:sendTyping 在 WS 非 OPEN 时静默
+                                // 返回 false,不影响下方 client.send 的 WS+REST fallback 主路。
+                                client.sendTyping(sessionId);
+                                // 长生成期间持续心跳;SDK 内置 500ms/session 防抖,800ms 间隔保证每次真发。
+                                const typingTimer = setInterval(() => client.sendTyping(sessionId), 800);
+                                try {
+                                    return await opts.deps.dispatchReplyWithBufferedBlockDispatcher({
+                                        ctx: ctxPayload,
+                                        cfg: opts.cfg,
+                                        dispatcherOptions: {
+                                            deliver: async (payload) => {
+                                                const replyText = payload?.text ?? payload?.content ?? "";
+                                                if (!replyText.trim())
+                                                    return;
+                                                await client.send(sessionId, {
+                                                    type: "dialogue.message",
+                                                    payload: { content: replyText },
+                                                });
+                                                log(`replied session=${sessionId} (${replyText.length} chars)`);
+                                            },
+                                            // 模型跑失败时,把错误回发给租户(不静默),便于人工发现。
+                                            onError: async (err) => {
+                                                const msg = err?.message ?? String(err);
+                                                log(`dispatch error session=${sessionId}: ${msg}`);
+                                                await client
+                                                    .send(sessionId, {
+                                                    type: "dialogue.message",
+                                                    payload: { content: `⚠️ provider 生成回复时出错,需人工介入:${msg}` },
+                                                })
+                                                    .catch((e) => log(`send error notice failed: ${String(e)}`));
+                                            },
+                                        },
+                                    });
+                                }
+                                finally {
+                                    clearInterval(typingTimer);
+                                }
+                            },
+                        }),
+                    },
+                });
+                log(`runChannelInboundEvent done session=${sessionId}`);
+            }
+            catch (e) {
+                log(`runChannelInboundEvent failed session=${sessionId}: ${String(e)}`);
+            }
+        },
+    });
+    log(`provider started (agentId=${opts.agentId ?? "auto"} autoApprove=${opts.autoApprove})`);
+    return {
+        stop: () => {
+            try {
+                client.stop();
+            }
+            catch (e) {
+                log(`stop error: ${String(e)}`);
+            }
+        },
+    };
+}

package/dist/setup/setup.d.ts

@@ -0,0 +1,13 @@
+export interface ClawRentConnectionResult {
+    ok: boolean;
+    detail?: string;
+    error?: string;
+}
+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

@@ -0,0 +1,22 @@
+export async function testConnection(config) {
+    const token = config.token;
+    const apiBaseUrl = config.apiBaseUrl ?? "https://clawrent.cloud";
+    if (!token)
+        return { ok: false, error: "missing token" };
+    try {
+        const mod = await import("@clawrent/provider");
+        const ApiClient = mod.ApiClient;
+        const client = new ApiClient({
+            token,
+            apiUrl: apiBaseUrl,
+            wsUrl: apiBaseUrl.replace(/^http/, "ws"),
+        });
+        const res = await client.getSessions({ role: "provider", status: "active" });
+        const count = (res?.data ?? res ?? []).length ?? 0;
+        return { ok: true, detail: `connected; ${count} active session(s)` };
+    }
+    catch (e) {
+        return { ok: false, error: String(e?.message ?? e) };
+    }
+}
+export default { testConnection };

package/docs/openclaw-sdk-notes.md

@@ -0,0 +1,51 @@
+# OpenClaw Channel Plugin SDK 踩坑笔记
+
+> **来源**:PinkBo 在 2026.6.11 前后基于 `openclaw@2026.6.11` 实测整理,随 plugin 移交。
+> 这些是**第一手踩坑记录**(文档说法 vs dist 实际实现),开发/升级 openclaw 时必读。
+> 由 ClawRent 官方接管后持续维护——openclaw 升级后请复核每条是否仍成立,过时的标注并更新。
+
+---
+
+## 1. 已确认的 OpenClaw Channel Plugin SDK 事实（2026.6.11）
+
+| 项 | 文档说法 | 实际实现（dist 验证） |
+|----|----------|----------------------|
+| 入口导出 | `defineChannelPluginEntry({ registerFull, registerCliMetadata })` | ✅ 正确，但**必须传 `plugin` 字段**（ChannelPlugin 实例），仅 registerFull 不够 |
+| `createChatChannelPlugin` 参数 | 文档示例简洁 | 实际为 `{ base, outbound?, security?, pairing?, threading? }`；`base` 由 `createChannelPluginBase({ id, setup, config })` 构造；`id/name/kind/accountId` 不在顶层 |
+| `ChannelOutboundAdapter.send` | 文档写 `send({ text })` | 实际是 `sendText(ctx)`，`ctx: ChannelOutboundContext`（从 `ctx.text` / `ctx.route` / `ctx.target` 取数据） |
+| `defineChannelMessageAdapter` / `createMessageReceiptFromOutboundResults` | 文档放 `channel-core` | 实际在 `openclaw/plugin-sdk/channel-message` |
+| `definePluginSetup` / `defineSetupSteps`（setup SDK） | 文档 `openclaw/plugin-sdk/setup` 有 | **不存在**；`setup` 模块只有底层 `ChannelSetupAdapter` 原语。已改用轻量 `testConnection()` 模块 |
+| `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 约定存在偏差 |
+
+---
+
+## 2. 待提交官方的问题清单（SDK / 文档偏差）
+
+> 这些是文档与实现不符、值得回馈给 OpenClaw 官方的点。若已回馈/修复，请标注。
+
+1. **`definePluginSetup` / `defineSetupSteps` 未实现**：`docs/plugins/sdk-entrypoints.md`
+   描述了该 API，但 `openclaw/plugin-sdk/setup` 未导出。建议要么实现，要么更正文档。
+2. **`createChatChannelPlugin` 文档与签名不符**：文档示例缺少 `base` 包装层，
+   新手易写成 `{ id, name, kind, accountId, outbound }` 导致类型错误。建议文档给出
+   `createChannelPluginBase` + `createChatChannelPlugin` 的完整最小示例。
+3. **outbound `send` 签名文档化缺失**：`ChannelOutboundAdapter.sendText(ctx)`
+   的 `ChannelOutboundContext` 结构未在文档示例中出现，只有简化的 `send({ text })`。
+   建议补充真实 ctx 形状（如何取 route/sessionId）。
+4. **manifest `required` 字段阻断全局 CLI**：channel plugin 的 config required 字段
+   缺失会让 `openclaw` 任何子命令都因 config validation 失败而无法启动。建议：
+   - 文档明确警告；或
+   - OpenClaw 对"未启用插件"跳过 required 校验。
+5. **`plugins install --link` 的入口校验与 `defineChannelPluginEntry` 不一致**：
+   install 报 `missing register/activate export`，但 `defineChannelPluginEntry` 的
+   返回值已含 `register`。建议统一 install 校验逻辑，或文档说明入口文件的导出约定。
+6. **`channelConfigs` manifest 字段文档不足**：install 警告
+   "channel plugin manifest declares clawrent without channelConfigs metadata"，
+   但 manifest 已声明 `channelConfigs`。需明确该字段的精确期望结构。
+   （PinkBo 已通过给 `channelConfigs.clawrent` 补 `schema` 修复了加载告警。）
+
+---
+
+*整理：PinkBo（2026-6.11 实测）· 接管维护：ClawRent 官方*

package/openclaw.plugin.json

@@ -0,0 +1,137 @@
+{
+  "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 rental requests autonomously using its own model and identity.",
+  "version": "0.2.0",
+  "channels": ["clawrent"],
+  "activation": {
+    "onStartup": false,
+    "onChannels": ["clawrent"]
+  },
+  "channelConfigs": {
+    "clawrent": {
+      "label": "ClawRent Provider",
+      "description": "Connection and behavior settings for the ClawRent rental-session channel.",
+      "schema": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "token": {
+            "type": "string",
+            "title": "ClawRent agent token"
+          },
+          "apiBaseUrl": {
+            "type": "string",
+            "title": "ClawRent API base URL",
+            "format": "uri"
+          },
+          "wsUrl": {
+            "type": "string",
+            "title": "ClawRent WebSocket URL",
+            "format": "uri"
+          },
+          "agentId": {
+            "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"
+          },
+          "guardrailsFile": {
+            "type": "string",
+            "title": "Path to guardrails markdown"
+          },
+          "personaFiles": {
+            "type": "array",
+            "title": "Persona files to load into context",
+            "items": { "type": "string" }
+          },
+          "scope": {
+            "type": "string",
+            "title": "Workspace scope label for tenant isolation"
+          }
+        }
+      },
+      "uiHints": {
+        "token": {
+          "label": "ClawRent Agent Token",
+          "help": "Token from clawrent serve / provider dashboard. Stored in openclaw.json.",
+          "sensitive": true,
+          "placeholder": "agt_clawrent_..."
+        },
+        "apiBaseUrl": {
+          "label": "API Base URL",
+          "placeholder": "https://clawrent.cloud"
+        },
+        "agentId": {
+          "label": "Agent ID",
+          "help": "ClawRent agent id (UUID). Leave empty to auto-resolve from token."
+        },
+        "autoApproveSessions": {
+          "label": "Auto-approve sessions (end-side)",
+          "help": "端侧代理批准开关。true(默认)= 非危险会话按护栏自动接单+应答,危险类仍转人工;false = 全部转人工/等平台。平台 dashboard 的 autoApprove 应设 false,批准动作只发生在端侧这道门。"
+        },
+        "guardrailsFile": {
+          "label": "Guardrails file",
+          "help": "外置护栏策略文件(每行 `/regex/ || 原因`,# 开头为注释)。规则追加在内置护栏之后,实现策略外置。"
+        }
+      }
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "token": {
+        "type": "string",
+        "title": "ClawRent agent token"
+      },
+      "apiBaseUrl": {
+        "type": "string",
+        "title": "ClawRent API base 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"
+      },
+      "guardrailsFile": {
+        "type": "string",
+        "title": "Path to guardrails markdown"
+      },
+      "personaFiles": {
+        "type": "array",
+        "items": { "type": "string" },
+        "title": "Persona files to load into context"
+      },
+      "scope": {
+        "type": "string",
+        "title": "Workspace scope label for tenant isolation"
+      }
+    },
+    "required": []
+  }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@clawrent/openclaw-channel",
+  "version": "0.2.0",
+  "description": "OpenClaw channel plugin that turns ClawRent rental sessions into native OpenClaw conversations, so a local ClawRent provider agent can answer tenants autonomously.",
+  "license": "ISC",
+  "type": "module",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md",
+    "docs"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "clawrent",
+    "channel",
+    "rental",
+    "provider",
+    "ai-agent"
+  ],
+  "homepage": "https://clawrent.cloud",
+  "author": "ClawRent",
+  "publishConfig": {
+    "access": "public"
+  },
+  "openclaw": {
+    "extensions": ["./dist/index.js"],
+    "runtimeExtensions": ["./dist/index.js"],
+    "setupEntry": "./dist/setup/setup.js",
+    "runtimeSetupEntry": "./dist/setup/setup.js",
+    "install": {
+      "clawhubSpec": "clawhub:@clawrent/openclaw-channel",
+      "defaultChoice": "clawhub",
+      "minHostVersion": ">=2026.6.11"
+    },
+    "compat": { "pluginApi": ">=2026.6.11" },
+    "build": { "openclawVersion": "2026.6.11" },
+    "release": { "publishToClawHub": true }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@clawrent/provider": "^0.1.1"
+  },
+  "devDependencies": {
+    "openclaw": "2026.6.11",
+    "@types/node": "^20",
+    "typescript": "*"
+  }
+}