@newbase-clawchat/openclaw-clawchat 2026.4.24 → 2026.4.30

package/README.md

@@ -1,6 +1,6 @@
 # @newbase-clawchat/openclaw-clawchat
 
-OpenClaw channel plugin that connects an agent to ClawChat over the ClawChat Protocol v2, using [`@newbase-clawchat/sdk`](https://www.npmjs.com/package/@newbase-clawchat/sdk) for the WebSocket transport plus a small REST surface under `/v1/*` for profile / social / media operations.
+OpenClaw channel plugin that connects an agent to ClawChat over the ClawChat Protocol v2, using [`@newbase-clawchat/sdk`](https://www.npmjs.com/package/@newbase-clawchat/sdk) for the WebSocket transport plus a small REST surface for profile / social / media operations (`/v1/*` plus unversioned `/media/upload`).
 
 ## Features
 
@@ -10,31 +10,64 @@ OpenClaw channel plugin that connects an agent to ClawChat over the ClawChat Pro
 - Outbound text replies in `static` or `stream` mode, with a consolidated final `message.reply`
 - Typing indicators and filtered forwarding for thinking / tool-call content
 - Media fragments (image / file / audio / video) in either direction
-- `clawchat_*` agent tools for profile, friends, media upload, and self-activation
+- Invite-code onboarding via `clawchat_activate` or channel login, plus always-registered `clawchat_*` account/media tools
 
 ## Install
 
 ```bash
-# Via the OpenClaw CLI (recommended)
-openclaw channels setup --channel openclaw-clawchat --code INV-ABC123
-
-# Or add as a local extension
+# Add as an OpenClaw extension
 npm i @newbase-clawchat/openclaw-clawchat
 ```
 
-Requires `openclaw >= 2026.3.23` as a peer host.
+Requires `openclaw >= 2026.4.29` as a peer host.
+
+For the OpenClaw plugin install/update flow, see [`INSTALL.md`](./INSTALL.md).
+
+Example LLM prompt:
+
+```text
+Use https://raw.githubusercontent.com/clawling/openclaw-clawchat/refs/heads/main/INSTALL.md to install and activate the ClawChat plugin. The invite code is XXXXXX.
+```
 
 ## Quick start
 
+Send one of these in chat:
+
+```text
+activate ClawChat with invite code A1B2C3
+```
+
+If the plugin is already loaded by the Gateway, the activation skill calls the
+`clawchat_activate` tool and OpenClaw hot-reloads the updated `channels.*`
+credentials. If the tool is not available yet, use channel login as the CLI
+fallback:
+
 ```bash
-# One-shot: apply config + exchange invite code for an access token
-openclaw channels setup --channel openclaw-clawchat --code INV-ABC123
+openclaw channels login --channel openclaw-clawchat
+openclaw channels status --probe
+```
+
+Restart the Gateway after installing/updating the plugin, when config reload is
+disabled, or when the channel probe does not become healthy:
 
-# Run the gateway
+```bash
+openclaw gateway restart
+```
+
+If you run the gateway manually instead of as a service and it is not already
+running, start it after login:
+
+```bash
 openclaw gateway run
 ```
 
-Minimal `~/.openclaw/openclaw.json`:
+The invite code is not a token; token fields are written only after login. The
+plugin registers `clawchat_activate` and the six account/media tools at plugin
+load time so they stay visible before activation. Before login, account/media
+tools return a config error instead of disappearing; after activation/login, the
+channel is enabled and the same tools read the hot-reloaded token/userId.
+
+After activation/login, the channel section is enabled and has credentials:
 
 ```json5
 {
@@ -43,8 +76,10 @@ Minimal `~/.openclaw/openclaw.json`:
       enabled: true,
       replyMode: "stream",
       forwardThinking: true,
-      forwardToolCalls: false
-      // token / userId / refreshToken are written by the login flow.
+      forwardToolCalls: false,
+      token: "...",
+      userId: "...",
+      refreshToken: "..."
     }
   }
 }
@@ -55,10 +90,11 @@ Minimal `~/.openclaw/openclaw.json`:
 A minimal browser test harness is bundled under `tools/`:
 
 ```bash
-npm run test-ui
+node tools/standalone-webchat-server.mjs
+# Options: --host (default 127.0.0.1), --port (default 4318), --default-ws-url
 ```
 
-Then open the printed URL — it mounts `tools/standalone-webchat.html` against a local relay so you can exercise the plugin end to end without a full ClawChat backend.
+Then open the printed URL (default `http://127.0.0.1:4318`) to exercise the plugin end to end against a WebSocket relay.
 
 ## Layout
 
@@ -103,9 +139,23 @@ See [`docs/openclaw-clawchat.md`](./docs/openclaw-clawchat.md) for:
 ```bash
 # Tests
 npx vitest run
+
+# Typecheck
+npm run typecheck
+```
+
+Tests live next to the source they cover (`*.test.ts`). The development entrypoint stays in TypeScript for the OpenClaw extension loader, while npm installs use the compiled runtime entrypoint generated by `npm run build` / `prepack` under `dist/`.
+
+For OpenClaw host SDK/source lookup while developing this plugin, optionally
+clone OpenClaw into `tmp/openclaw`:
+
+```bash
+npm run dev:openclaw-source
+# equivalent: git clone --depth=1 https://github.com/openclaw/openclaw.git tmp/openclaw
 ```
 
-Tests live next to the source they cover (`*.test.ts`). The plugin is pure TypeScript and is consumed via the OpenClaw host's extension loader — no bundling step is required.
+This checkout is local-only. It is ignored by git and is not required to run the
+plugin tests or publish the package.
 
 ## License
 

package/dist/index.js

@@ -0,0 +1,27 @@
+import { openclawClawlingPlugin } from "./src/channel.js";
+import { registerOpenclawClawlingCommands } from "./src/commands.js";
+import { setOpenclawClawlingRuntime } from "./src/runtime.js";
+import { registerOpenclawClawlingTools } from "./src/tools.js";
+import { openclawClawlingConfigSchema } from "./src/config.js";
+export default {
+    id: "openclaw-clawchat",
+    name: "Clawling Chat",
+    description: "Clawling Chat Protocol v2 channel plugin (chat-sdk)",
+    configSchema: openclawClawlingConfigSchema,
+    register(api) {
+        setOpenclawClawlingRuntime(api.runtime);
+        api.registerChannel({ plugin: openclawClawlingPlugin });
+        registerOpenclawClawlingCommands(api);
+        registerOpenclawClawlingTools(api);
+    }
+};
+// export default defineChannelPluginEntry({
+//   id: "openclaw-clawchat",
+//   name: "Clawling Chat",
+//   description: "Clawling Chat Protocol v2 channel plugin (chat-sdk)",
+//   plugin: openclawClawlingPlugin,
+//   setRuntime: setOpenclawClawlingRuntime,
+//   registerFull(api) {
+//     registerOpenclawClawlingTools(api);
+//   },
+// });

package/dist/src/api-client.js

@@ -0,0 +1,156 @@
+import { ClawlingApiError, } from "./api-types.js";
+import { CHANNEL_ID } from "./config.js";
+export function createOpenclawClawlingApiClient(opts) {
+    if (!/^https?:\/\//i.test(opts.baseUrl)) {
+        throw new ClawlingApiError("validation", `openclaw-clawchat baseUrl must start with http:// or https:// (got "${opts.baseUrl}")`);
+    }
+    const baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    function url(path) {
+        return `${baseUrl}${path}`;
+    }
+    function authHeaders(extra = {}) {
+        // `X-Device-Id` is sent on every request so the server can correlate
+        // activity back to this plugin instance. Callers may override via
+        // `extra` (e.g. tests) but the default is the channel id.
+        return {
+            authorization: `Bearer ${opts.token}`,
+            "x-device-id": CHANNEL_ID,
+            ...extra,
+        };
+    }
+    async function readEnvelope(res, path) {
+        if (res.status === 401 || res.status === 403) {
+            throw new ClawlingApiError("auth", `unauthorized (status ${res.status})`, {
+                status: res.status,
+                path,
+            });
+        }
+        if (!res.ok) {
+            const snippet = await res.text().catch(() => "");
+            throw new ClawlingApiError("transport", `http ${res.status} ${snippet.slice(0, 200)}`, {
+                status: res.status,
+                path,
+            });
+        }
+        let parsed;
+        try {
+            parsed = await res.json();
+        }
+        catch (err) {
+            throw new ClawlingApiError("transport", `non-JSON response: ${err instanceof Error ? err.message : String(err)}`, { status: res.status, path });
+        }
+        // Unified envelope: `{ code: number, msg: string, data: T }`.
+        // `code === 0` means success; any other value is a business error whose
+        // `msg` is surfaced to callers and `code` is preserved on the error meta.
+        const env = parsed;
+        const code = typeof env.code === "number" ? env.code : Number.NaN;
+        const msg = typeof env.msg === "string"
+            ? env.msg
+            : typeof env.message === "string"
+                ? env.message
+                : "";
+        if (!Number.isFinite(code)) {
+            throw new ClawlingApiError("transport", "invalid envelope: missing numeric `code`", {
+                status: res.status,
+                path,
+            });
+        }
+        if (code !== 0) {
+            throw new ClawlingApiError("api", msg || `code=${code}`, {
+                code,
+                status: res.status,
+                path,
+            });
+        }
+        return env.data;
+    }
+    async function call(method, path, init) {
+        let res;
+        try {
+            const requestInit = {
+                method,
+                headers: authHeaders(init?.headers),
+            };
+            if (init?.body !== undefined) {
+                requestInit.body = init.body;
+            }
+            res = await fetchImpl(url(path), requestInit);
+        }
+        catch (err) {
+            throw new ClawlingApiError("transport", `fetch failed: ${err instanceof Error ? err.message : String(err)}`, { path });
+        }
+        return await readEnvelope(res, path);
+    }
+    // All JSON API endpoints live under `/v1/...`. Media upload is the one
+    // intentional exception — the upstream server mounts it at `/media/upload`
+    // without the version prefix.
+    return {
+        async getMyProfile() {
+            return await call("GET", "/v1/users/me");
+        },
+        async getUserInfo(userId) {
+            return await call("GET", `/v1/users/${encodeURIComponent(userId)}`);
+        },
+        async listFriends(params) {
+            const sp = new URLSearchParams();
+            if (typeof params.page === "number")
+                sp.set("page", String(params.page));
+            if (typeof params.pageSize === "number")
+                sp.set("pageSize", String(params.pageSize));
+            const q = sp.toString();
+            return await call("GET", q ? `/v1/friends?${q}` : "/v1/friends");
+        },
+        async updateMyProfile(patch) {
+            if (!opts.userId?.trim()) {
+                throw new ClawlingApiError("validation", "updateMyProfile: userId is required to target /v1/agents/{userId}");
+            }
+            return await call("PATCH", `/v1/users/me`, {
+                body: JSON.stringify(patch),
+                headers: { "content-type": "application/json" },
+            });
+        },
+        async agentsConnect({ code: inviteCode, platform, type }) {
+            if (!inviteCode?.trim()) {
+                throw new ClawlingApiError("validation", "agentsConnect: inviteCode is required");
+            }
+            if (!platform?.trim()) {
+                throw new ClawlingApiError("validation", "agentsConnect: platform is required");
+            }
+            if (!type?.trim()) {
+                throw new ClawlingApiError("validation", "agentsConnect: type is required");
+            }
+            return await call("POST", "/v1/agents/connect", {
+                // `X-Device-Id` is added globally via `authHeaders` on every request.
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    code: inviteCode.trim(),
+                    platform: platform.trim(),
+                    type: type.trim(),
+                }),
+            });
+        },
+        async uploadMedia(params) {
+            const blob = new Blob([new Uint8Array(params.buffer)], {
+                type: params.mime ?? "application/octet-stream",
+            });
+            const file = new File([blob], params.filename, {
+                type: params.mime ?? "application/octet-stream",
+            });
+            const fd = new FormData();
+            fd.set("file", file);
+            return await call("POST", "/media/upload", { body: fd });
+        },
+        async uploadAvatar(params) {
+            const blob = new Blob([new Uint8Array(params.buffer)], {
+                type: params.mime ?? "application/octet-stream",
+            });
+            const file = new File([blob], params.filename, {
+                type: params.mime ?? "application/octet-stream",
+            });
+            const fd = new FormData();
+            fd.set("file", file);
+            return await call("POST", "/v1/files/upload-url", { body: fd });
+        },
+    };
+}

package/dist/src/api-types.js

@@ -0,0 +1,17 @@
+/**
+ * Public-facing types for the Clawling Chat HTTP API.
+ *
+ * Field names mirror the upstream API (snake_case) so we don't lose
+ * fidelity on responses. Tool schemas accept camelCase externally and
+ * translate at the api-client boundary.
+ */
+export class ClawlingApiError extends Error {
+    kind;
+    meta;
+    constructor(kind, message, meta) {
+        super(message);
+        this.kind = kind;
+        this.meta = meta;
+        this.name = "ClawlingApiError";
+    }
+}

package/dist/src/buffered-stream.js

@@ -0,0 +1,177 @@
+import { emitStreamAdd, emitStreamCreated, emitStreamDone, emitStreamFailed, } from "./client.js";
+/**
+ * Merge two views of the same progressively-revealed text.
+ *
+ * The agent runner may give us either:
+ *   - full snapshots   ("Hel", "Hello", "Hello, world") where each item is
+ *     a superset of the previous; or
+ *   - overlapping slices ("hello ", "world hello ") that don't share a
+ *     prefix but share an overlap at the join.
+ *
+ * This helper returns a longest-sensible combined string. Ported from
+ * `clawling-channel/src/reply-dispatcher.ts`.
+ */
+export function mergeStreamingText(previousText, nextText) {
+    const currentSnapshot = typeof previousText === "string" ? previousText : "";
+    const incomingText = typeof nextText === "string" ? nextText : "";
+    if (!incomingText)
+        return currentSnapshot;
+    if (!currentSnapshot || incomingText === currentSnapshot)
+        return incomingText;
+    if (incomingText.startsWith(currentSnapshot))
+        return incomingText;
+    if (currentSnapshot.startsWith(incomingText))
+        return currentSnapshot;
+    if (incomingText.includes(currentSnapshot))
+        return incomingText;
+    if (currentSnapshot.includes(incomingText))
+        return currentSnapshot;
+    const maxOverlap = Math.min(currentSnapshot.length, incomingText.length);
+    for (let overlap = maxOverlap; overlap > 0; overlap -= 1) {
+        if (currentSnapshot.slice(-overlap) === incomingText.slice(0, overlap)) {
+            return `${currentSnapshot}${incomingText.slice(overlap)}`;
+        }
+    }
+    return `${currentSnapshot}${incomingText}`;
+}
+function resolveRouting(options) {
+    if (options.routing)
+        return options.routing;
+    if (options.to)
+        return { chatId: options.to.id, chatType: options.to.type };
+    throw new Error("openclaw-clawchat buffered stream requires routing");
+}
+/**
+ * Build a streaming session wrapper around message.created/add/done events.
+ *
+ * Usage pattern (matching clawling-channel):
+ *   const session = openBufferedStreamingSession({...});
+ *   await session.queueSnapshot("Hel");
+ *   await session.queueSnapshot("Hello");
+ *   await session.queueDelta(", world");
+ *   await session.done();
+ */
+export function openBufferedStreamingSession(options) {
+    const routing = resolveRouting(options);
+    const emitTyping = options.emitTyping !== false;
+    if (emitTyping)
+        options.client.typing(routing.chatId, true);
+    emitStreamCreated(options.client, {
+        messageId: options.messageId,
+        routing,
+    });
+    let bufferedSnapshot = "";
+    let flushedSnapshot = "";
+    let sequence = -1;
+    let flushTimer = null;
+    let pendingFlush = Promise.resolve();
+    let closed = false;
+    const clearTimer = () => {
+        if (flushTimer) {
+            clearTimeout(flushTimer);
+            flushTimer = null;
+        }
+    };
+    const performFlush = async () => {
+        clearTimer();
+        if (closed)
+            return;
+        if (bufferedSnapshot === flushedSnapshot)
+            return;
+        const snapshot = bufferedSnapshot;
+        const delta = snapshot.slice(flushedSnapshot.length);
+        if (!delta)
+            return;
+        sequence += 1;
+        emitStreamAdd(options.client, {
+            messageId: options.messageId,
+            routing,
+            sequence,
+            fullText: snapshot,
+            textDelta: delta,
+        });
+        flushedSnapshot = snapshot;
+    };
+    const flush = async () => {
+        pendingFlush = pendingFlush.then(performFlush);
+        await pendingFlush;
+    };
+    const scheduleFlush = () => {
+        if (flushTimer || closed)
+            return;
+        flushTimer = setTimeout(() => {
+            flushTimer = null;
+            void flush();
+        }, options.flushIntervalMs);
+    };
+    const queueSnapshot = async (snapshot) => {
+        if (closed || !snapshot)
+            return;
+        const base = bufferedSnapshot.length >= flushedSnapshot.length ? bufferedSnapshot : flushedSnapshot;
+        const merged = mergeStreamingText(base, snapshot);
+        if (merged === bufferedSnapshot)
+            return;
+        bufferedSnapshot = merged;
+        const deltaChars = Math.max(0, bufferedSnapshot.length - flushedSnapshot.length);
+        if (deltaChars >= options.minChunkChars || bufferedSnapshot.length >= options.maxBufferChars) {
+            await flush();
+        }
+        else {
+            scheduleFlush();
+        }
+    };
+    const queueDelta = async (delta) => {
+        if (closed || !delta)
+            return;
+        bufferedSnapshot = `${bufferedSnapshot}${delta}`;
+        const deltaChars = Math.max(0, bufferedSnapshot.length - flushedSnapshot.length);
+        if (deltaChars >= options.minChunkChars || bufferedSnapshot.length >= options.maxBufferChars) {
+            await flush();
+        }
+        else {
+            scheduleFlush();
+        }
+    };
+    const done = async () => {
+        if (closed)
+            return;
+        await flush();
+        closed = true;
+        clearTimer();
+        emitStreamDone(options.client, {
+            messageId: options.messageId,
+            routing,
+            finalSequence: Math.max(sequence, 0),
+            finalText: bufferedSnapshot,
+        });
+        if (emitTyping)
+            options.client.typing(routing.chatId, false);
+    };
+    const fail = async (reason) => {
+        if (closed)
+            return;
+        closed = true;
+        clearTimer();
+        emitStreamFailed(options.client, {
+            messageId: options.messageId,
+            routing,
+            sequence: Math.max(sequence, 0),
+            ...(reason !== undefined ? { reason } : {}),
+        });
+        if (emitTyping)
+            options.client.typing(routing.chatId, false);
+    };
+    return {
+        get currentText() {
+            return bufferedSnapshot;
+        },
+        get flushedText() {
+            return flushedSnapshot;
+        },
+        queueSnapshot,
+        queueDelta,
+        flush,
+        done,
+        fail,
+    };
+}