@newbase-clawchat/openclaw-clawchat 2026.4.29 → 2026.5.4-1

package/README.md

@@ -10,7 +10,7 @@ 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
-- Channel-login onboarding plus `clawchat_*` agent tools for the configured ClawChat account profile, friends, and media upload
+- Invite-code onboarding via `clawchat_activate` or `/clawchat-login`, plus always-registered `clawchat_*` account/media tools
 
 ## Install
 
@@ -19,7 +19,7 @@ OpenClaw channel plugin that connects an agent to ClawChat over the ClawChat Pro
 npm i @newbase-clawchat/openclaw-clawchat
 ```
 
-Requires `openclaw >= 2026.3.23` as a peer host.
+Requires `openclaw >= 2026.5.4` as a peer host.
 
 For the OpenClaw plugin install/update flow, see [`INSTALL.md`](./INSTALL.md).
 
@@ -37,23 +37,54 @@ Send one of these in chat:
 activate ClawChat with invite code A1B2C3
 ```
 
-The activation skill executes OpenClaw channel login:
+If the plugin is already loaded by the Gateway, the activation skill calls the
+`clawchat_activate` tool and persists credentials. If you are activating from
+Telegram or another chat platform and the agent does not call the tool, send the
+runtime slash command in that chat:
+
+```text
+/clawchat-login A1B2C3
+```
+
+The slash command is provided by the loaded plugin. It is not a shell command,
+so `openclaw clawchat-login` is expected to fail.
+
+On OpenClaw hosts where the CLI channel catalog includes `openclaw-clawchat`,
+terminal activation can also use:
+
+```bash
+CLAWCHAT_INVITE_CODE="A1B2C3"
+openclaw channels add --channel openclaw-clawchat --token "$CLAWCHAT_INVITE_CODE"
+openclaw channels status --probe
+```
+
+OpenClaw 2026.5.5 can load an npm-installed third-party channel while still
+omitting it from the `channels add` CLI catalog. If `channels add` fails with
+`Unknown channel: openclaw-clawchat`, use `clawchat_activate` or
+`/clawchat-login A1B2C3` after a real Gateway restart.
+
+Restart the Gateway after installing/updating the plugin, when config reload is
+disabled, or when the channel probe does not become healthy:
 
 ```bash
-openclaw channels login --channel openclaw-clawchat
 openclaw gateway restart
 ```
 
-If you run the gateway manually instead of as a service, start it after login:
+If you run the gateway manually instead of as a service and it is not already
+running, start it after activation:
 
 ```bash
 openclaw gateway run
 ```
 
-The invite code is not a token; token fields are written only after login. Before
-login, the plugin registers no ClawChat account tools; after activation/login,
-the channel is enabled and the `clawchat_*` account tools register on config
-reload.
+The `--token` value above is the ClawChat invite code for OpenClaw's generic
+`channels add` CLI surface on hosts that expose this plugin in the channel
+catalog; persisted token fields are written only after the invite code exchange
+succeeds. The plugin registers `clawchat_activate` and the six account/media tools at plugin
+load time so they stay visible before activation. Before activation, account/media
+tools return a config error instead of disappearing; after activation/login, the
+channel is enabled and the same tools read the persisted token/userId after the
+Gateway restarts.
 
 After activation/login, the channel section is enabled and has credentials:
 
@@ -64,7 +95,7 @@ After activation/login, the channel section is enabled and has credentials:
       enabled: true,
       replyMode: "stream",
       forwardThinking: true,
-      forwardToolCalls: false
+      forwardToolCalls: false,
       token: "...",
       userId: "...",
       refreshToken: "..."
@@ -132,7 +163,18 @@ npx vitest run
 npm run typecheck
 ```
 
-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.
+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
+```
+
+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,18 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { openclawClawlingPlugin } from "./src/channel.js";
+import { registerOpenclawClawlingCommands } from "./src/commands.js";
+import { openclawClawlingConfigSchema } from "./src/config.js";
+import { setOpenclawClawlingRuntime } from "./src/runtime.js";
+import { registerOpenclawClawlingTools } from "./src/tools.js";
+export default defineChannelPluginEntry({
+    id: "openclaw-clawchat",
+    name: "Clawling Chat",
+    description: "Clawling Chat Protocol v2 channel plugin (chat-sdk)",
+    plugin: openclawClawlingPlugin,
+    configSchema: { schema: openclawClawlingConfigSchema },
+    setRuntime: setOpenclawClawlingRuntime,
+    registerFull(api) {
+        registerOpenclawClawlingCommands(api);
+        registerOpenclawClawlingTools(api);
+    },
+});

package/dist/setup-entry.js

@@ -0,0 +1,3 @@
+import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { openclawClawlingSetupPlugin } from "./src/channel.setup.js";
+export default defineSetupPluginEntry(openclawClawlingSetupPlugin);

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,
+    };
+}

package/dist/src/channel.js

@@ -0,0 +1,68 @@
+import { createChatChannelPlugin } from "openclaw/plugin-sdk/core";
+import { createEmptyChannelDirectoryAdapter } from "openclaw/plugin-sdk/directory-runtime";
+import { resolveOpenclawClawlingAccount, } from "./config.js";
+import { openclawClawlingOutbound } from "./outbound.js";
+import { getOpenclawClawlingRuntime, startOpenclawClawlingGateway } from "./runtime.js";
+import { openclawClawlingSetupPlugin } from "./channel.setup.js";
+export const openclawClawlingPlugin = createChatChannelPlugin({
+    base: {
+        ...openclawClawlingSetupPlugin,
+        directory: createEmptyChannelDirectoryAdapter(),
+        auth: {
+            login: async ({ cfg, accountId, runtime }) => {
+                const { runOpenclawClawlingLogin } = await import("./login.runtime.js");
+                await runOpenclawClawlingLogin({
+                    cfg,
+                    accountId: accountId ?? null,
+                    runtime: { log: (message) => runtime.log(message) },
+                    mutateConfigFile: getOpenclawClawlingRuntime().config.mutateConfigFile,
+                });
+            },
+        },
+        gateway: {
+            startAccount: async (ctx) => {
+                const account = ctx.account ?? resolveOpenclawClawlingAccount(ctx.cfg);
+                ctx.log?.info?.(`[${account.accountId}] openclaw-clawchat lifecycle startAccount invoked configured=${account.configured} enabled=${account.enabled} hasToken=${Boolean(account.token)} hasUserId=${Boolean(account.userId)} websocketUrl=${account.websocketUrl || "(empty)"}`);
+                if (!account.configured) {
+                    ctx.log?.error?.(`[${account.accountId}] openclaw-clawchat lifecycle startAccount refused: websocketUrl/token/userId are required`);
+                    throw new Error("Clawling Chat websocketUrl/token/userId are required");
+                }
+                try {
+                    await startOpenclawClawlingGateway({
+                        cfg: ctx.cfg,
+                        account,
+                        abortSignal: ctx.abortSignal,
+                        setStatus: ctx.setStatus,
+                        getStatus: ctx.getStatus,
+                        log: ctx.log,
+                    });
+                }
+                finally {
+                    ctx.log?.info?.(`[${account.accountId}] openclaw-clawchat lifecycle startAccount completed/stopped`);
+                }
+            },
+        },
+        agentPrompt: {
+            messageToolHints: () => [
+                "To send an image or file to the current chat, use the message tool with action='send' and set 'media' to a local file path or a remote URL.",
+                "When the user asks you to find an image from the web, find a suitable HTTPS image URL and send it using the message tool with 'media' set to that URL — do NOT download the image first.",
+                "For configured ClawChat account profile, user profile, friends, avatar, or standalone media upload/share-link workflows, use `clawchat-account-tools` for tool-selection details.",
+                "For ClawChat account avatar changes using a local image, call `clawchat_upload_avatar_image` first, then `clawchat_update_account_profile` with `avatar_url`.",
+                "- Targeting: omit `target` to reply here; for a different chat use `target=\"cc:{chat_id}\"` for direct or `target=\"cc:group:{chat_id}\"` for group.",
+                "- ClawChat supports image / file / audio / video media alongside text.",
+            ],
+        },
+        messaging: {
+            normalizeTarget: (target) => target
+                .trim()
+                .replace(/^openclaw-clawchat:/i, "")
+                .replace(/^clawchat:/i, "")
+                .replace(/^cc:/i, ""),
+            targetResolver: {
+                looksLikeId: (raw, normalized) => Boolean((normalized ?? raw).trim()),
+                hint: "active-session",
+            },
+        },
+    },
+    outbound: openclawClawlingOutbound,
+});