@newbase-clawchat/openclaw-clawchat 2026.4.15

package/README.md

@@ -0,0 +1,112 @@
+# @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.
+
+## Features
+
+- WebSocket transport with auto-reconnect (exponential backoff + jitter), heartbeat, and ack tracking
+- Invite-code onboarding — no raw credentials required
+- Inbound `message.send` / `message.reply` with reply context
+- 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
+
+## Install
+
+```bash
+# Via the OpenClaw CLI (recommended)
+openclaw channels setup --channel openclaw-clawchat --code INV-ABC123
+
+# Or add as a local extension
+npm i @newbase-clawchat/openclaw-clawchat
+```
+
+Requires `openclaw >= 2026.3.23` as a peer host.
+
+## Quick start
+
+```bash
+# One-shot: apply config + exchange invite code for an access token
+openclaw channels setup --channel openclaw-clawchat --code INV-ABC123
+
+# Run the gateway
+openclaw gateway run
+```
+
+Minimal `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  channels: {
+    "openclaw-clawchat": {
+      enabled: true,
+      replyMode: "stream",
+      forwardThinking: true,
+      forwardToolCalls: false
+      // token / userId / refreshToken are written by the login flow.
+    }
+  }
+}
+```
+
+## Standalone web chat (dev)
+
+A minimal browser test harness is bundled under `tools/`:
+
+```bash
+npm run test-ui
+```
+
+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.
+
+## Layout
+
+```
+src/
+  channel.ts          plugin adapter (setup, auth.login, gateway, agentPrompt)
+  runtime.ts          inbound dispatch + reply dispatcher
+  client.ts           chat-sdk WebSocket client wrapper
+  api-client.ts       REST client for /v1/* + /media/upload
+  inbound.ts          envelope → agent turn
+  outbound.ts         agent reply → envelope
+  streaming.ts        progressive reply emitter
+  buffered-stream.ts  chunk coalescing + flush policy
+  message-mapper.ts   fragment ↔ text/media mapping
+  login.runtime.ts    invite-code exchange flow
+  media-runtime.ts    media download/upload pipeline
+  reply-dispatcher.ts static vs stream routing
+  tools.ts            clawchat_* agent tools
+  protocol.ts         v2 envelope shapes
+  config.ts           defaults + typebox schema
+tools/
+  standalone-webchat-server.mjs
+  standalone-webchat.html
+docs/
+  openclaw-clawchat.md   full docs (protocol, diagrams, troubleshooting)
+```
+
+## Documentation
+
+See [`docs/openclaw-clawchat.md`](./docs/openclaw-clawchat.md) for:
+
+- Full configuration reference
+- Onboarding / activation details
+- REST endpoint table
+- Streaming frame shapes (`message.created` / `message.add` / `message.done` / `message.reply`)
+- End-to-end sequence diagram
+- Media pipeline (inbound download / outbound upload)
+- Troubleshooting
+
+## Development
+
+```bash
+# Tests
+npx vitest run
+```
+
+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.
+
+## License
+
+See the repository root.

package/index.ts

@@ -0,0 +1,19 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+import { openclawClawlingPlugin } from "./src/channel.ts";
+import { setOpenclawClawlingRuntime } from "./src/runtime.ts";
+import { registerOpenclawClawlingTools } from "./src/tools.ts";
+
+export { openclawClawlingPlugin } from "./src/channel.ts";
+export { setOpenclawClawlingRuntime } from "./src/runtime.ts";
+export { registerOpenclawClawlingTools } from "./src/tools.ts";
+
+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/openclaw.plugin.json

@@ -0,0 +1,52 @@
+{
+  "id": "openclaw-clawchat",
+  "channels": ["openclaw-clawchat"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": { "type": "boolean" },
+      "websocketUrl": { "type": "string" },
+      "baseUrl": { "type": "string" },
+      "token": { "type": "string" },
+      "userId": { "type": "string" },
+      "replyMode": { "type": "string", "enum": ["static", "stream"] },
+      "forwardThinking": { "type": "boolean" },
+      "forwardToolCalls": { "type": "boolean" },
+      "stream": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "flushIntervalMs": { "type": "integer", "minimum": 10 },
+          "minChunkChars": { "type": "integer", "minimum": 1 },
+          "maxBufferChars": { "type": "integer", "minimum": 1 }
+        }
+      },
+      "reconnect": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "initialDelay": { "type": "integer", "minimum": 100 },
+          "maxDelay": { "type": "integer", "minimum": 100 },
+          "jitterRatio": { "type": "number", "minimum": 0 }
+        }
+      },
+      "heartbeat": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "interval": { "type": "integer", "minimum": 1000 },
+          "timeout": { "type": "integer", "minimum": 1000 }
+        }
+      },
+      "ack": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "timeout": { "type": "integer", "minimum": 100 },
+          "autoResendOnTimeout": { "type": "boolean" }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@newbase-clawchat/openclaw-clawchat",
+  "version": "2026.4.15",
+  "description": "OpenClaw ClawChat channel plugin",
+  "files": [
+    "index.ts",
+    "src",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck",
+    "release": "npm run prepublishOnly && npm publish",
+    "test-ui": "node ./tools/standalone-webchat-server.mjs"
+  },
+  "dependencies": {
+    "@newbase-clawchat/sdk": "^0.1.0",
+    "@sinclair/typebox": "0.34.48"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "openclaw": "^2026.3.23",
+    "typescript": "^5.4.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.23"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "openclaw-clawchat",
+      "label": "Clawling Chat",
+      "selectionLabel": "Clawling Chat",
+      "docsPath": "/channels/openclaw-clawchat",
+      "docsLabel": "openclaw-clawchat",
+      "blurb":  "OpenClaw ClawChat channel plugin",
+      "order": 110
+    },
+    "install": {
+      "npmSpec": "@newbase-clawchat/openclaw-clawchat",
+      "localPath": "extensions/openclaw-clawchat",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.23"
+    }
+  }
+}

package/src/api-client.test.ts

@@ -0,0 +1,325 @@
+import { describe, expect, it, vi } from "vitest";
+import { createOpenclawClawlingApiClient } from "./api-client.ts";
+import { ClawlingApiError } from "./api-types.ts";
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+describe("openclaw-clawchat api-client", () => {
+  it("getMyProfile sends GET /me with bearer token and unwraps data", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { user_id: "u1", display_name: "Alice" },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+
+    const profile = await client.getMyProfile();
+
+    expect(fetchImpl).toHaveBeenCalledWith(
+      "https://api.example.com/v1/users/me",
+      expect.objectContaining({
+        method: "GET",
+        headers: expect.objectContaining({
+          authorization: "Bearer tk",
+          // Global X-Device-Id is sent on every request, not just connect.
+          "x-device-id": "openclaw-clawchat",
+        }),
+      }),
+    );
+    expect(profile).toEqual({ user_id: "u1", display_name: "Alice" });
+  });
+
+  it("getUserInfo url-encodes the userId", async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(
+        jsonResponse({ code: 0, message: "ok", data: { user_id: "u/2", display_name: "Bob" } }),
+      );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await client.getUserInfo("u/2");
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/users/u%2F2");
+  });
+
+  it("listFriends sends page + pageSize as query string", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { items: [], page: 2, pageSize: 50 },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await client.listFriends({ page: 2, pageSize: 50 });
+    expect(fetchImpl.mock.calls[0]![0]).toBe(
+      "https://api.example.com/v1/friends?page=2&pageSize=50",
+    );
+  });
+
+  it("updateMyProfile sends PATCH /me with JSON body", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { user_id: "u1", display_name: "Alice2" },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      userId: "agent-1",
+      fetchImpl,
+    });
+    await client.updateMyProfile({ display_name: "Alice2" });
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/agents/agent-1");
+    const init = fetchImpl.mock.calls[0]![1] as RequestInit;
+    expect(init.method).toBe("PATCH");
+    expect(JSON.parse(init.body as string)).toEqual({ display_name: "Alice2" });
+    expect((init.headers as Record<string, string>)["content-type"]).toBe("application/json");
+  });
+
+  it("updateMyProfile throws validation error when userId is not configured", async () => {
+    const fetchImpl = vi.fn();
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      // userId intentionally omitted
+      fetchImpl,
+    });
+    await expect(client.updateMyProfile({ display_name: "x" })).rejects.toMatchObject({
+      kind: "validation",
+    });
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it("uploadMedia POSTs multipart with field name 'file'", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { url: "https://cdn/x.png", size: 12, mime: "image/png" },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    const result = await client.uploadMedia({
+      buffer: Buffer.from("hi-bytes-12!"),
+      filename: "x.png",
+      mime: "image/png",
+    });
+    // uploadMedia intentionally targets `/media/upload` WITHOUT the `/v1`
+    // prefix — the upstream mount is unversioned.
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/media/upload");
+    const init = fetchImpl.mock.calls[0]![1] as RequestInit;
+    expect(init.method).toBe("POST");
+    expect(init.body).toBeInstanceOf(FormData);
+    const fd = init.body as FormData;
+    const file = fd.get("file") as File;
+    expect(file).toBeInstanceOf(File);
+    expect(file.name).toBe("x.png");
+    expect(file.type).toBe("image/png");
+    expect(result).toEqual({ url: "https://cdn/x.png", size: 12, mime: "image/png" });
+  });
+
+  it("uploadAvatar POSTs multipart to /v1/files/upload-url", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { url: "https://cdn/avatars/a.png", size: 99, mime: "image/png" },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    const result = await client.uploadAvatar({
+      buffer: Buffer.from("avatar-bytes-12"),
+      filename: "avatar.png",
+      mime: "image/png",
+    });
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/files/upload-url");
+    const init = fetchImpl.mock.calls[0]![1] as RequestInit;
+    expect(init.method).toBe("POST");
+    expect(init.body).toBeInstanceOf(FormData);
+    const fd = init.body as FormData;
+    const file = fd.get("file") as File;
+    expect(file).toBeInstanceOf(File);
+    expect(file.name).toBe("avatar.png");
+    expect(file.type).toBe("image/png");
+    // X-Device-Id is present on avatar uploads too.
+    expect((init.headers as Record<string, string>)["x-device-id"]).toBe("openclaw-clawchat");
+    expect(result).toEqual({ url: "https://cdn/avatars/a.png", size: 99, mime: "image/png" });
+  });
+
+  it("agentsConnect POSTs /agents/connect with { code, platform, type } body", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        msg: "ok",
+        data: {
+          agent: {
+            id: "ag-1",
+            owner_id: "owner-1",
+            user_id: "agent-1",
+            type: "bot",
+            nickname: "Bot",
+            avatar_url: "",
+            bio: "",
+            visibility: "public",
+            status: "active",
+            platform: "openclaw",
+            created_at: "2026-04-17T00:00:00Z",
+          },
+          access_token: "tk-access",
+          refresh_token: "tk-refresh",
+        },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    const result = await client.agentsConnect({
+      inviteCode: "INV-1",
+      platform: "openclaw",
+      type: "bot",
+    });
+    expect(fetchImpl).toHaveBeenCalledWith(
+      "https://api.example.com/v1/agents/connect",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          authorization: "Bearer tk",
+          "content-type": "application/json",
+          // Fixed device id — pins the issued credentials to this plugin.
+          "x-device-id": "openclaw-clawchat",
+        }),
+        body: JSON.stringify({ code: "INV-1", platform: "openclaw", type: "bot" }),
+      }),
+    );
+    expect(result.agent.user_id).toBe("agent-1");
+    expect(result.access_token).toBe("tk-access");
+    expect(result.refresh_token).toBe("tk-refresh");
+  });
+
+  it("agentsConnect rejects empty invite code / platform / type locally", async () => {
+    const fetchImpl = vi.fn();
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await expect(
+      client.agentsConnect({ inviteCode: "   ", platform: "openclaw", type: "bot" }),
+    ).rejects.toMatchObject({ kind: "validation" });
+    await expect(
+      client.agentsConnect({ inviteCode: "INV", platform: "", type: "bot" }),
+    ).rejects.toMatchObject({ kind: "validation" });
+    await expect(
+      client.agentsConnect({ inviteCode: "INV", platform: "openclaw", type: "" }),
+    ).rejects.toMatchObject({ kind: "validation" });
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it("throws ClawlingApiError(api) on code !== 0", async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(jsonResponse({ code: 4001, message: "user not found", data: null }));
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await expect(client.getUserInfo("missing")).rejects.toMatchObject({
+      kind: "api",
+      message: "user not found",
+      meta: expect.objectContaining({ code: 4001 }),
+    });
+  });
+
+  it("throws ClawlingApiError(auth) on 401", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(new Response("unauthorized", { status: 401 }));
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await expect(client.getMyProfile()).rejects.toMatchObject({
+      kind: "auth",
+      meta: expect.objectContaining({ status: 401 }),
+    });
+  });
+
+  it("throws ClawlingApiError(transport) on 500", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(new Response("internal error", { status: 500 }));
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await expect(client.getMyProfile()).rejects.toMatchObject({
+      kind: "transport",
+      meta: expect.objectContaining({ status: 500 }),
+    });
+  });
+
+  it("throws ClawlingApiError(transport) when fetch itself rejects", async () => {
+    const fetchImpl = vi.fn().mockRejectedValue(new Error("ENETDOWN"));
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await expect(client.getMyProfile()).rejects.toMatchObject({
+      kind: "transport",
+      message: expect.stringContaining("ENETDOWN"),
+    });
+  });
+
+  it("strips trailing slash from baseUrl", async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(
+        jsonResponse({ code: 0, message: "ok", data: { user_id: "u1", display_name: "A" } }),
+      );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com/",
+      token: "tk",
+      fetchImpl,
+    });
+    await client.getMyProfile();
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/users/me");
+  });
+
+  it("rejects baseUrl without http(s) scheme", () => {
+    expect(() =>
+      createOpenclawClawlingApiClient({
+        baseUrl: "ftp://wrong.example.com",
+        token: "tk",
+      }),
+    ).toThrow(ClawlingApiError);
+  });
+});