@newbase-clawchat/openclaw-clawchat 2026.4.15

package/src/login.runtime.test.ts

@@ -0,0 +1,257 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { describe, expect, it, vi } from "vitest";
+import { ClawlingApiError } from "./api-types.ts";
+import { runOpenclawClawlingLogin } from "./login.runtime.ts";
+
+const CHANNEL_ID = "openclaw-clawchat";
+
+function buildCfg(
+  section: Record<string, unknown> = { baseUrl: "https://api.example.com" },
+): OpenClawConfig {
+  return {
+    channels: { [CHANNEL_ID]: section },
+  } as unknown as OpenClawConfig;
+}
+
+function makeApiClient(overrides: {
+  agentsConnect: ReturnType<typeof vi.fn>;
+}): ReturnType<typeof import("./api-client.ts").createOpenclawClawlingApiClient> {
+  return {
+    getMyProfile: vi.fn(),
+    getUserInfo: vi.fn(),
+    listFriends: vi.fn(),
+    updateMyProfile: vi.fn(),
+    uploadMedia: vi.fn(),
+    agentsConnect: overrides.agentsConnect,
+  } as never;
+}
+
+describe("runOpenclawClawlingLogin", () => {
+  it("works with no prior setup (baseUrl / websocketUrl default built-in)", async () => {
+    const cfg = buildCfg({}); // empty section — resolver provides defaults
+    const agentsConnect = vi.fn().mockResolvedValue({
+      agent: { user_id: "u" },
+      access_token: "t",
+      refresh_token: "r",
+    });
+    let capturedBaseUrl = "";
+    await runOpenclawClawlingLogin({
+      cfg,
+      runtime: { log: vi.fn() },
+      readInviteCode: async () => "INV",
+      apiClientFactory: (opts) => {
+        capturedBaseUrl = opts.baseUrl;
+        return makeApiClient({ agentsConnect });
+      },
+      persistConfig: vi.fn(),
+    });
+    // The api-client was constructed with a non-empty baseUrl sourced
+    // from the default, even though the cfg had none.
+    expect(capturedBaseUrl).toMatch(/^https?:\/\//);
+  });
+
+  it("errors if invite code is blank", async () => {
+    const cfg = buildCfg({ baseUrl: "https://api.example.com" });
+    await expect(
+      runOpenclawClawlingLogin({
+        cfg,
+        runtime: { log: vi.fn() },
+        readInviteCode: async () => "   ",
+      }),
+    ).rejects.toThrow(/invite code is required/);
+  });
+
+  it("calls agents/connect with the invite code and persists returned credentials", async () => {
+    const cfg = buildCfg({
+      baseUrl: "https://api.example.com",
+      websocketUrl: "wss://ws.example.com/v2/client",
+    });
+    const agentsConnect = vi.fn().mockResolvedValue({
+      agent: {
+        id: "ag-1",
+        owner_id: "owner-1",
+        user_id: "agent-123",
+        type: "bot",
+        nickname: "Bot",
+        avatar_url: "",
+        bio: "",
+        visibility: "public",
+        status: "active",
+        platform: "clawchat",
+        created_at: "2026-04-17T00:00:00Z",
+      },
+      access_token: "access-tok",
+      refresh_token: "refresh-tok",
+    });
+    const persistConfig = vi.fn();
+    const log = vi.fn();
+
+    await runOpenclawClawlingLogin({
+      cfg,
+      runtime: { log },
+      readInviteCode: async () => "INV-ABC",
+      apiClientFactory: () => makeApiClient({ agentsConnect }),
+      persistConfig,
+    });
+
+    expect(agentsConnect).toHaveBeenCalledWith({
+      inviteCode: "INV-ABC",
+      platform: "openclaw",
+      type: "clawbot",
+    });
+    expect(persistConfig).toHaveBeenCalledTimes(1);
+    const savedCfg = persistConfig.mock.calls[0]![0] as OpenClawConfig;
+    const section = (savedCfg.channels as Record<string, Record<string, unknown>>)[CHANNEL_ID]!;
+    expect(section.token).toBe("access-tok");
+    expect(section.refreshToken).toBe("refresh-tok");
+    expect(section.userId).toBe("agent-123");
+    // Existing baseUrl and websocketUrl are preserved — agents/connect
+    // does not return them.
+    expect(section.baseUrl).toBe("https://api.example.com");
+    expect(section.websocketUrl).toBe("wss://ws.example.com/v2/client");
+    expect(log).toHaveBeenCalledWith(expect.stringContaining("login succeeded"));
+  });
+
+  it("surfaces agents/connect API errors with the kind and message", async () => {
+    const cfg = buildCfg({ baseUrl: "https://api.example.com" });
+    const agentsConnect = vi.fn().mockRejectedValue(
+      new ClawlingApiError("api", "invite code expired", { code: 4002 }),
+    );
+    await expect(
+      runOpenclawClawlingLogin({
+        cfg,
+        runtime: { log: vi.fn() },
+        readInviteCode: async () => "expired",
+        apiClientFactory: () => makeApiClient({ agentsConnect }),
+        persistConfig: vi.fn(),
+      }),
+    ).rejects.toThrow(/agents\/connect failed \(api\): invite code expired/);
+  });
+
+  it("rejects responses that omit required fields", async () => {
+    const cfg = buildCfg({ baseUrl: "https://api.example.com" });
+    const agentsConnect = vi.fn().mockResolvedValue({
+      agent: { user_id: "" },
+      access_token: "t",
+      refresh_token: "r",
+    });
+    await expect(
+      runOpenclawClawlingLogin({
+        cfg,
+        runtime: { log: vi.fn() },
+        readInviteCode: async () => "ok",
+        apiClientFactory: () => makeApiClient({ agentsConnect }),
+        persistConfig: vi.fn(),
+      }),
+    ).rejects.toThrow(/missing required fields/);
+  });
+
+  it("persists the config automatically after receiving the token (no further prompts)", async () => {
+    const cfg = buildCfg({
+      baseUrl: "https://api.example.com",
+      websocketUrl: "wss://ws.example.com",
+    });
+    const agentsConnect = vi.fn().mockResolvedValue({
+      agent: { user_id: "agent-9", nickname: "Nine" },
+      access_token: "ACC-0123456789",
+      refresh_token: "REF-xyz",
+    });
+    const persistCalls: OpenClawConfig[] = [];
+    const logMessages: string[] = [];
+    await runOpenclawClawlingLogin({
+      cfg,
+      runtime: { log: (m) => logMessages.push(m) },
+      readInviteCode: async () => "INV-AUTO",
+      apiClientFactory: () => makeApiClient({ agentsConnect }),
+      persistConfig: (next) => {
+        persistCalls.push(next);
+      },
+    });
+    // persistConfig is invoked exactly once with the merged credentials.
+    expect(persistCalls).toHaveLength(1);
+    const section = (persistCalls[0]!.channels as Record<string, Record<string, unknown>>)[CHANNEL_ID]!;
+    expect(section.token).toBe("ACC-0123456789");
+    expect(section.userId).toBe("agent-9");
+    expect(section.refreshToken).toBe("REF-xyz");
+    // Existing URL fields are preserved.
+    expect(section.baseUrl).toBe("https://api.example.com");
+    expect(section.websocketUrl).toBe("wss://ws.example.com");
+    // Operator-visible log confirms the automatic config write.
+    expect(logMessages.some((m) => /Updating config/.test(m))).toBe(true);
+    expect(logMessages.some((m) => /Config file updated/.test(m))).toBe(true);
+    // Token in logs is redacted.
+    expect(logMessages.every((m) => !m.includes("ACC-0123456789"))).toBe(true);
+  });
+
+  it("login logs don't leak the /agents/connect endpoint path or base URL", async () => {
+    const cfg = buildCfg({ baseUrl: "https://api.example.com" });
+    const agentsConnect = vi.fn().mockResolvedValue({
+      agent: { user_id: "u" },
+      access_token: "t",
+      refresh_token: "r",
+    });
+    const logMessages: string[] = [];
+    await runOpenclawClawlingLogin({
+      cfg,
+      runtime: { log: (m) => logMessages.push(m) },
+      readInviteCode: async () => "INV",
+      apiClientFactory: () => makeApiClient({ agentsConnect }),
+      persistConfig: vi.fn(),
+    });
+    expect(logMessages.every((m) => !m.includes("/agents/connect"))).toBe(true);
+    expect(logMessages.every((m) => !m.includes(cfg.channels!["openclaw-clawchat"].baseUrl))).toBe(
+      true,
+    );
+  });
+
+  it("trims the invite code before sending", async () => {
+    const cfg = buildCfg({ baseUrl: "https://api.example.com" });
+    const agentsConnect = vi.fn().mockResolvedValue({
+      agent: { user_id: "u" },
+      access_token: "t",
+      refresh_token: "r",
+    });
+    await runOpenclawClawlingLogin({
+      cfg,
+      runtime: { log: vi.fn() },
+      readInviteCode: async () => "  INV-TRIM  ",
+      apiClientFactory: () => makeApiClient({ agentsConnect }),
+      persistConfig: vi.fn(),
+    });
+    expect(agentsConnect).toHaveBeenCalledWith({
+      inviteCode: "INV-TRIM",
+      platform: "openclaw",
+      type: "clawbot",
+    });
+  });
+});
+
+describe("runOpenclawClawlingLogin (non-interactive via readInviteCode)", () => {
+  it("performs a full login when called with a fixed readInviteCode (programmatic path)", async () => {
+    const cfg = buildCfg({ baseUrl: "https://api.example.com" });
+    const agentsConnect = vi.fn().mockResolvedValue({
+      agent: { user_id: "agent-7", nickname: "Seven" },
+      access_token: "acc-non-interactive",
+      refresh_token: "ref-ni",
+    });
+    const persistConfig = vi.fn();
+    await runOpenclawClawlingLogin({
+      cfg,
+      runtime: { log: () => {} },
+      readInviteCode: async () => "INV-PROGRAMMATIC",
+      apiClientFactory: () => makeApiClient({ agentsConnect }),
+      persistConfig,
+    });
+    expect(agentsConnect).toHaveBeenCalledWith({
+      inviteCode: "INV-PROGRAMMATIC",
+      platform: "openclaw",
+      type: "clawbot",
+    });
+    expect(persistConfig).toHaveBeenCalledTimes(1);
+    const section = (persistConfig.mock.calls[0]![0] as OpenClawConfig).channels!
+      ["openclaw-clawchat"] as Record<string, unknown>;
+    expect(section.token).toBe("acc-non-interactive");
+    expect(section.userId).toBe("agent-7");
+    expect(section.refreshToken).toBe("ref-ni");
+  });
+});

package/src/login.runtime.ts

@@ -0,0 +1,153 @@
+import { createInterface, type Interface as ReadlineInterface } from "node:readline/promises";
+import { writeConfigFile } from "openclaw/plugin-sdk/config-runtime";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { createOpenclawClawlingApiClient } from "./api-client.ts";
+import { ClawlingApiError } from "./api-types.ts";
+import { CHANNEL_ID, resolveOpenclawClawlingAccount } from "./config.ts";
+
+/**
+ * Platform tag sent to `/v1/agents/connect`. Identifies the host of this
+ * agent runtime — openclaw's bundled clawchat channel.
+ */
+export const AGENTS_CONNECT_PLATFORM = "openclaw" as const;
+/**
+ * Agent type tag sent to `/v1/agents/connect`. The clawchat channel is
+ * always a bot; humans don't log in through this flow.
+ */
+export const AGENTS_CONNECT_TYPE = "clawbot" as const;
+
+export interface LoginParams {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+  runtime: { log: (message: string) => void };
+  /**
+   * Override for the invite-code prompt — used by tests. Defaults to
+   * stdin via `node:readline/promises`.
+   */
+  readInviteCode?: () => Promise<string>;
+  /** Override for the HTTP client — used by tests. */
+  apiClientFactory?: typeof createOpenclawClawlingApiClient;
+  /** Override for config persistence — used by tests. */
+  persistConfig?: (cfg: OpenClawConfig) => Promise<void> | void;
+}
+
+/**
+ * Prompt the operator for an invite code.
+ *
+ * The prompt text is emitted via `runtime.log` so it flows through the
+ * same openclaw logging pipeline every other channel plugin uses (no
+ * clack frame, no raw-mode takeover, no TTY detection). Input is read
+ * from stdin with `node:readline` — Enter-to-submit is plain language in
+ * the prompt so any upstream LLM / orchestrator reading the log stream
+ * knows a newline is expected, and the behavior is identical under a
+ * TTY, piped stdin, or a test harness.
+ */
+async function promptInviteCodeFromStdin(runtime: {
+  log: (message: string) => void;
+}): Promise<string> {
+  runtime.log("Please enter your ClawChat invite code (press Enter to submit):");
+  let rl: ReadlineInterface | undefined;
+  try {
+    rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question("> ");
+    return answer.trim();
+  } finally {
+    rl?.close();
+  }
+}
+
+/**
+ * Run the `openclaw channels login --channel openclaw-clawchat` flow:
+ *   1. Read the existing channel section; require `baseUrl` to be set so we
+ *      know which server to hit.
+ *   2. Prompt the user for an invite code on stdin.
+ *   3. POST it to `${baseUrl}/v1/agents/connect`.
+ *   4. Write the returned `websocket_url` / `token` / `user_id` back into
+ *      the config so subsequent `openclaw gateway run` picks them up.
+ *
+ * Errors surface with clear messages (missing baseUrl, empty invite,
+ * server-side rejection) so the caller can relay them to the operator.
+ */
+export async function runOpenclawClawlingLogin(params: LoginParams): Promise<void> {
+  const { cfg, runtime } = params;
+
+  // `resolveOpenclawClawlingAccount` falls back to the built-in
+  // `DEFAULT_BASE_URL` / `DEFAULT_WEBSOCKET_URL` when the operator has not
+  // overridden them, so login works without a prior `openclaw channels setup --channel openclaw-clawchat`.
+  const account = resolveOpenclawClawlingAccount(cfg);
+
+  const inviteCode = (
+    await (params.readInviteCode ?? (() => promptInviteCodeFromStdin(runtime)))()
+  ).trim();
+  if (!inviteCode) {
+    throw new Error("Login aborted: invite code is required.");
+  }
+
+  const apiClient = (params.apiClientFactory ?? createOpenclawClawlingApiClient)({
+    baseUrl: account.baseUrl,
+    // Pre-login we may not have a token yet. Send the current one (or empty)
+    // — the server should accept an unauthenticated invite-code exchange.
+    token: account.token || "",
+  });
+
+  runtime.log("Verifying invite code …");
+  let result;
+  try {
+    result = await apiClient.agentsConnect({
+      inviteCode,
+      platform: AGENTS_CONNECT_PLATFORM,
+      type: AGENTS_CONNECT_TYPE,
+    });
+  } catch (err) {
+    if (err instanceof ClawlingApiError) {
+      throw new Error(`agents/connect failed (${err.kind}): ${err.message}`);
+    }
+    throw err;
+  }
+
+  if (!result?.access_token || !result?.agent?.user_id) {
+    throw new Error(
+      `agents/connect response missing required fields (access_token / agent.user_id): ${JSON.stringify(result)}`,
+    );
+  }
+
+  // Merge credentials into cfg.channels.openclaw-clawchat and persist
+  // immediately so a subsequent `openclaw gateway run` picks them up
+  // without any manual edit. `baseUrl` / `websocketUrl` stay untouched —
+  // the built-in defaults (or operator overrides) remain authoritative
+  // because `/v1/agents/connect` doesn't return them.
+  const channels = (cfg.channels ?? {}) as Record<string, unknown>;
+  const existing = (channels[CHANNEL_ID] ?? {}) as Record<string, unknown>;
+  const nextSection: Record<string, unknown> = {
+    ...existing,
+    token: result.access_token,
+    userId: result.agent.user_id,
+  };
+  if (result.refresh_token) {
+    nextSection.refreshToken = result.refresh_token;
+  }
+  const nextCfg: OpenClawConfig = {
+    ...cfg,
+    channels: { ...channels, [CHANNEL_ID]: nextSection },
+  };
+
+  const tokenPreview = redactToken(result.access_token);
+  runtime.log(
+    `Updating config: channels.${CHANNEL_ID}.token=${tokenPreview} userId=${result.agent.user_id}${
+      result.refresh_token ? " refreshToken=***" : ""
+    } …`,
+  );
+  await (params.persistConfig ?? writeConfigFile)(nextCfg);
+  runtime.log(`Config file updated.`);
+
+  runtime.log(
+    `openclaw-clawchat login succeeded (user_id=${result.agent.user_id}, nickname=${result.agent.nickname || "-"}).`,
+  );
+}
+
+/** Shortens a token for display logs without revealing the full secret. */
+function redactToken(token: string): string {
+  if (!token) return "(empty)";
+  if (token.length <= 8) return "***";
+  return `${token.slice(0, 4)}…${token.slice(-4)}`;
+}

package/src/manifest.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import pluginManifest from "../openclaw.plugin.json" with { type: "json" };
+import packageJson from "../package.json" with { type: "json" };
+
+interface PackageJsonWithOpenclaw {
+  name: string;
+  openclaw: {
+    channel: { id: string };
+    install: { npmSpec: string };
+  };
+}
+
+describe("openclaw-clawchat manifest", () => {
+  it("keeps plugin id / channel id / package name aligned", () => {
+    expect(pluginManifest.id).toBe("openclaw-clawchat");
+    expect(pluginManifest.channels).toContain("openclaw-clawchat");
+    expect(packageJson.name).toBe("openclaw-clawchat");
+    const pkg = packageJson as PackageJsonWithOpenclaw;
+    expect(pkg.openclaw.channel.id).toBe("openclaw-clawchat");
+    expect(pkg.openclaw.install.npmSpec).toBe("openclaw-clawchat");
+  });
+});

package/src/media-runtime.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  inferMediaKindFromMime,
+  fetchInboundMedia,
+  uploadOutboundMedia,
+  type MediaItem,
+} from "./media-runtime.ts";
+
+// loadWebMedia is imported directly in media-runtime.ts (not via runtime.channel.media)
+// because the channel runtime only exposes fetchRemoteMedia/saveMediaBuffer.
+const loadWebMediaMock = vi.hoisted(() => vi.fn());
+vi.mock("openclaw/plugin-sdk/web-media", () => ({
+  loadWebMedia: loadWebMediaMock,
+}));
+
+describe("inferMediaKindFromMime", () => {
+  it("maps image/* to image", () => {
+    expect(inferMediaKindFromMime("image/png")).toBe("image");
+    expect(inferMediaKindFromMime("image/jpeg")).toBe("image");
+  });
+  it("maps audio/* to audio", () => {
+    expect(inferMediaKindFromMime("audio/mpeg")).toBe("audio");
+  });
+  it("maps video/* to video", () => {
+    expect(inferMediaKindFromMime("video/mp4")).toBe("video");
+  });
+  it("maps anything else to file", () => {
+    expect(inferMediaKindFromMime("application/pdf")).toBe("file");
+    expect(inferMediaKindFromMime("text/plain")).toBe("file");
+  });
+  it("maps undefined / empty to file", () => {
+    expect(inferMediaKindFromMime(undefined)).toBe("file");
+    expect(inferMediaKindFromMime("")).toBe("file");
+  });
+});
+
+describe("fetchInboundMedia", () => {
+  function buildRuntime() {
+    const fetchRemoteMedia = vi.fn().mockImplementation(async ({ url }: { url: string }) => ({
+      buffer: Buffer.from(`bytes-of-${url}`),
+      contentType: "image/png",
+      fileName: "x.png",
+    }));
+    const saveMediaBuffer = vi
+      .fn()
+      .mockImplementation(
+        async (_buf: Buffer, _ct?: string, _sub?: string, _max?: number, name?: string) => ({
+          path: `/cache/${name ?? "auto"}`,
+          contentType: "image/png",
+        }),
+      );
+    const runtime = {
+      channel: {
+        media: { fetchRemoteMedia, saveMediaBuffer },
+      },
+    } as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
+    return { runtime, fetchRemoteMedia, saveMediaBuffer };
+  }
+
+  it("fetches each item and returns local paths", async () => {
+    const { runtime } = buildRuntime();
+    const items: MediaItem[] = [
+      { kind: "image", url: "https://cdn/a.png", mime: "image/png" },
+      { kind: "image", url: "https://cdn/b.png", mime: "image/png" },
+    ];
+    const paths = await fetchInboundMedia(items, { runtime, maxBytes: 1000 });
+    expect(paths).toEqual(["/cache/x.png", "/cache/x.png"]);
+  });
+
+  it("drops a single item that fails, keeps others", async () => {
+    const { runtime, fetchRemoteMedia } = buildRuntime();
+    fetchRemoteMedia.mockImplementationOnce(async () => {
+      throw new Error("network");
+    });
+    const items: MediaItem[] = [
+      { kind: "image", url: "https://cdn/bad.png" },
+      { kind: "image", url: "https://cdn/good.png" },
+    ];
+    const log = { info: vi.fn(), error: vi.fn() };
+    const paths = await fetchInboundMedia(items, { runtime, log });
+    expect(paths).toHaveLength(1);
+    expect(log.info).toHaveBeenCalled();
+  });
+
+  it("returns empty array for empty input", async () => {
+    const { runtime } = buildRuntime();
+    expect(await fetchInboundMedia([], { runtime })).toEqual([]);
+  });
+});
+
+describe("uploadOutboundMedia", () => {
+  function buildApiClient() {
+    return {
+      uploadMedia: vi.fn().mockResolvedValue({
+        url: "https://cdn/uploaded.png",
+        size: 12,
+        mime: "image/png",
+      }),
+    } as unknown as ReturnType<typeof import("./api-client.ts").createOpenclawClawlingApiClient>;
+  }
+
+  function setupLoadWebMedia() {
+    loadWebMediaMock.mockResolvedValue({
+      buffer: Buffer.from("loaded-bytes"),
+      contentType: "image/png",
+      fileName: "img.png",
+    });
+    return loadWebMediaMock;
+  }
+
+  it("loads each url and uploads", async () => {
+    const loadWebMedia = setupLoadWebMedia();
+    const apiClient = buildApiClient();
+    // runtime is unused for uploadOutboundMedia (loadWebMedia is a direct import)
+    const runtime = {} as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
+    const fragments = await uploadOutboundMedia(["https://cdn/in.png", "https://cdn/in2.png"], {
+      apiClient,
+      runtime,
+    });
+    expect(loadWebMedia).toHaveBeenCalledTimes(2);
+    expect(fragments).toEqual([
+      {
+        kind: "image",
+        url: "https://cdn/uploaded.png",
+        mime: "image/png",
+        size: 12,
+        name: "img.png",
+      },
+      {
+        kind: "image",
+        url: "https://cdn/uploaded.png",
+        mime: "image/png",
+        size: 12,
+        name: "img.png",
+      },
+    ]);
+  });
+
+  it("drops a single failed upload, returns the rest", async () => {
+    setupLoadWebMedia();
+    const apiClient = buildApiClient();
+    (apiClient.uploadMedia as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error("boom"));
+    const log = { info: vi.fn(), error: vi.fn() };
+    const runtime = {} as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
+    const fragments = await uploadOutboundMedia(["https://cdn/a.png", "https://cdn/b.png"], {
+      apiClient,
+      runtime,
+      log,
+    });
+    expect(fragments).toHaveLength(1);
+    expect(log.error).toHaveBeenCalled();
+  });
+
+  it("returns empty array for empty input", async () => {
+    const apiClient = buildApiClient();
+    const runtime = {} as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
+    expect(await uploadOutboundMedia([], { apiClient, runtime })).toEqual([]);
+  });
+});