@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/clawchat-metadata.ts

@@ -0,0 +1,429 @@
+import type {
+  AgentProfile,
+  ConversationDetails,
+  ConversationMetadataPatch,
+  Profile,
+} from "./api-types.ts";
+import {
+  readClawChatMemoryFile,
+  writeClawChatMetadata,
+  type ClawChatMemoryTargetType,
+} from "./clawchat-memory.ts";
+
+export interface MetadataWriteTarget {
+  targetType: ClawChatMemoryTargetType;
+  targetId: string;
+}
+
+export interface MetadataFailure extends MetadataWriteTarget {
+  error: string;
+}
+
+export interface MetadataPullResult {
+  ok: boolean;
+  writes: MetadataWriteTarget[];
+  failures: MetadataFailure[];
+  conversation?: ConversationDetails;
+}
+
+export interface MetadataPushResult extends MetadataPullResult {
+  metadata: Record<string, string>;
+}
+
+type MetadataApi = {
+  getConversation?: (conversationId: string) => Promise<{ conversation: ConversationDetails }>;
+  getUserInfo?: (userId: string) => Promise<Profile>;
+  getUserProfile?: (userId: string) => Promise<Profile>;
+  getAgentDetail?: (agentId: string) => Promise<{ agent: unknown }>;
+  getAgentProfile?: (agentId: string) => Promise<{ agent: unknown }>;
+  updateAgentBehavior?: (behavior: string) => Promise<{ agent: AgentProfile }>;
+  patchConversation?: (
+    conversationId: string,
+    patch: ConversationMetadataPatch,
+  ) => Promise<{ conversation: ConversationDetails }>;
+  updateMyProfile?: (patch: { nickname?: string; avatar_url?: string; bio?: string }) => Promise<Profile>;
+};
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" ? value as Record<string, unknown> : null;
+}
+
+function hasOwn(record: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+function stringField(record: Record<string, unknown>, key: string): string | undefined {
+  if (!hasOwn(record, key)) return undefined;
+  const value = record[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function addStringField(
+  metadata: Record<string, string>,
+  outputKey: string,
+  record: Record<string, unknown>,
+  inputKey = outputKey,
+): void {
+  const value = stringField(record, inputKey);
+  if (value !== undefined) metadata[outputKey] = value;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function ownerMetadataFromAgent(
+  agent: Record<string, unknown>,
+  params: { accountUserId?: string; accountOwnerUserId?: string },
+): Record<string, string> {
+  const metadata: Record<string, string> = {};
+  addStringField(metadata, "updated_at", agent);
+  const agentId = stringField(agent, "user_id") ?? params.accountUserId;
+  if (agentId !== undefined) metadata.agent_id = agentId;
+  const ownerId = stringField(agent, "owner_id") ?? params.accountOwnerUserId;
+  if (ownerId !== undefined) metadata.agent_owner_id = ownerId;
+  addStringField(metadata, "agent_nickname", agent, "nickname");
+  addStringField(metadata, "agent_avatar_url", agent, "avatar_url");
+  addStringField(metadata, "agent_bio", agent, "bio");
+  addStringField(metadata, "agent_behavior", agent, "behavior");
+  return metadata;
+}
+
+function addOwnerProfileMetadata(
+  metadata: Record<string, string>,
+  ownerProfile: Record<string, unknown>,
+): void {
+  addStringField(metadata, "agent_owner_nickname", ownerProfile, "nickname");
+  addStringField(metadata, "agent_owner_avatar_url", ownerProfile, "avatar_url");
+  addStringField(metadata, "agent_owner_bio", ownerProfile, "bio");
+}
+
+function userMetadataFromRecord(
+  record: Record<string, unknown>,
+  targetUserId: string,
+): Record<string, string> | null {
+  const metadata: Record<string, string> = {};
+  addStringField(metadata, "updated_at", record);
+  metadata.id = targetUserId;
+  addStringField(metadata, "nickname", record);
+  addStringField(metadata, "avatar_url", record);
+  addStringField(metadata, "bio", record);
+  addStringField(metadata, "profile_type", record, "type");
+  return metadata;
+}
+
+function userMetadataFromProfile(profile: Profile, userId: string): Record<string, string> {
+  const metadata = userMetadataFromRecord(profile as Profile & Record<string, unknown>, userId);
+  if (metadata === null) {
+    throw new Error("ClawChat user metadata response is missing id");
+  }
+  return metadata;
+}
+
+function participantUserMetadata(participant: Record<string, unknown>): { userId: string; metadata: Record<string, string> } | null {
+  const userRecord = asRecord(participant.user);
+  const source = userRecord ?? participant;
+  const userId = stringField(source, "id") ?? stringField(participant, "user_id");
+  if (!userId) return null;
+  const metadata = userMetadataFromRecord(source, userId);
+  return metadata ? { userId, metadata } : null;
+}
+
+function normalizeSkipUserIds(values: Iterable<string | null | undefined> | undefined): Set<string> {
+  const ids = new Set<string>();
+  for (const value of values ?? []) {
+    if (typeof value !== "string") continue;
+    const id = value.trim();
+    if (id) ids.add(id);
+  }
+  return ids;
+}
+
+function groupMetadataFromConversation(conversation: ConversationDetails, groupId: string): Record<string, string> {
+  const record = conversation as ConversationDetails & Record<string, unknown>;
+  const metadata: Record<string, string> = {};
+  addStringField(metadata, "updated_at", record);
+  metadata.group_id = groupId;
+  addStringField(metadata, "group_type", record, "type");
+  addStringField(metadata, "group_title", record, "title");
+  addStringField(metadata, "group_description", record, "description");
+  addStringField(metadata, "group_owner_id", record, "creator_id");
+  addStringField(metadata, "group_created_at", record, "created_at");
+  const participants = Array.isArray(conversation.participants) ? conversation.participants : [];
+  const participantIds: string[] = [];
+  const seen = new Set<string>();
+  for (const participant of participants) {
+    const participantRecord = participant as Record<string, unknown>;
+    const userRecord = asRecord(participantRecord.user);
+    const source = userRecord ?? participantRecord;
+    const userId = stringField(participantRecord, "id") ?? stringField(participantRecord, "user_id");
+    if (!userId || seen.has(userId)) continue;
+    seen.add(userId);
+    participantIds.push(userId);
+    if (!metadata.group_owner_id && stringField(participantRecord, "role") === "owner") {
+      metadata.group_owner_id = userId;
+    }
+    if (metadata.group_owner_id === userId) {
+      addStringField(metadata, "group_owner_nickname", source, "nickname");
+      addStringField(metadata, "group_owner_profile_type", source, "type");
+    }
+  }
+  if (participantIds.length > 0) metadata.participant_ids = participantIds.join(",");
+  return metadata;
+}
+
+function pickUpdatePatch<T extends Record<string, string>>(
+  patchInput: Record<string, unknown>,
+  keys: readonly (keyof T & string)[],
+): T {
+  const patch: Record<string, string> = {};
+  for (const key of keys) {
+    if (hasOwn(patchInput, key) && typeof patchInput[key] === "string") {
+      patch[key] = patchInput[key];
+    }
+  }
+  if (Object.keys(patch).length === 0) {
+    throw new Error("ClawChat metadata update must include at least one mutable field");
+  }
+  return patch as T;
+}
+
+export async function pullOwnerMetadata(params: {
+  memoryRoot: string;
+  agentId: string;
+  accountUserId?: string;
+  accountOwnerUserId?: string;
+  api: MetadataApi;
+}): Promise<MetadataPullResult> {
+  const getAgent = params.api.getAgentDetail ?? params.api.getAgentProfile;
+  if (!getAgent) throw new Error("ClawChat metadata pull requires getAgentDetail");
+  if (!params.agentId) throw new Error("ClawChat owner metadata pull requires agentId");
+  const data = await getAgent(params.agentId);
+  const metadata = ownerMetadataFromAgent(asRecord(data.agent) ?? {}, params);
+  const ownerId = metadata.agent_owner_id;
+  const getOwner = params.api.getUserProfile ?? params.api.getUserInfo;
+  if (ownerId && getOwner) {
+    addOwnerProfileMetadata(metadata, asRecord(await getOwner(ownerId)) ?? {});
+  }
+  await writeClawChatMetadata(params.memoryRoot, { targetType: "owner", targetId: "owner" }, metadata);
+  return { ok: true, writes: [{ targetType: "owner", targetId: "owner" }], failures: [] };
+}
+
+export async function pullUserMetadata(params: {
+  memoryRoot: string;
+  userId: string;
+  api: MetadataApi;
+}): Promise<MetadataPullResult> {
+  const getUser = params.api.getUserProfile ?? params.api.getUserInfo;
+  if (!getUser) throw new Error("ClawChat metadata pull requires getUserProfile");
+  const profile = await getUser(params.userId);
+  const metadata = userMetadataFromProfile(profile, params.userId);
+  await writeClawChatMetadata(params.memoryRoot, { targetType: "user", targetId: params.userId }, metadata);
+  return { ok: true, writes: [{ targetType: "user", targetId: params.userId }], failures: [] };
+}
+
+export async function pullGroupMetadata(params: {
+  memoryRoot: string;
+  groupId: string;
+  api: MetadataApi;
+  skipUserIds?: Iterable<string | null | undefined>;
+}): Promise<MetadataPullResult> {
+  if (!params.api.getConversation) throw new Error("ClawChat metadata pull requires getConversation");
+  const getUser = params.api.getUserProfile ?? params.api.getUserInfo;
+  const data = await params.api.getConversation(params.groupId);
+  const writes: MetadataWriteTarget[] = [];
+  const failures: MetadataFailure[] = [];
+  const conversationType = stringField(data.conversation as ConversationDetails & Record<string, unknown>, "type")
+    ?.trim()
+    .toLowerCase();
+  if (conversationType === "direct" || conversationType === "dm") {
+    return { ok: true, writes, failures, conversation: data.conversation };
+  }
+  const groupMetadata = groupMetadataFromConversation(data.conversation, params.groupId);
+  const skipUserIds = normalizeSkipUserIds(params.skipUserIds);
+  if (
+    groupMetadata.group_owner_id &&
+    !groupMetadata.group_owner_nickname &&
+    getUser &&
+    !skipUserIds.has(groupMetadata.group_owner_id)
+  ) {
+    try {
+      const ownerProfile = asRecord(await getUser(groupMetadata.group_owner_id)) ?? {};
+      addStringField(groupMetadata, "group_owner_nickname", ownerProfile, "nickname");
+      addStringField(groupMetadata, "group_owner_profile_type", ownerProfile, "type");
+    } catch (error) {
+      failures.push({ targetType: "user", targetId: groupMetadata.group_owner_id, error: errorMessage(error) });
+    }
+  }
+
+  await writeClawChatMetadata(
+    params.memoryRoot,
+    { targetType: "group", targetId: params.groupId },
+    groupMetadata,
+  );
+  writes.push({ targetType: "group", targetId: params.groupId });
+
+  const participants = Array.isArray(data.conversation.participants)
+    ? data.conversation.participants
+    : [];
+  for (const participant of participants) {
+    const mapped = participantUserMetadata(participant as Record<string, unknown>);
+    if (!mapped) continue;
+    if (skipUserIds.has(mapped.userId)) continue;
+    try {
+      const existing = await readClawChatMemoryFile(params.memoryRoot, {
+        targetType: "user",
+        targetId: mapped.userId,
+      });
+      if (existing.exists) continue;
+      if (!getUser) throw new Error("ClawChat participant metadata pull requires getUserProfile");
+      const profile = await getUser(mapped.userId);
+      const metadata = userMetadataFromProfile(profile, mapped.userId);
+      await writeClawChatMetadata(
+        params.memoryRoot,
+        { targetType: "user", targetId: mapped.userId },
+        metadata,
+      );
+      writes.push({ targetType: "user", targetId: mapped.userId });
+    } catch (error) {
+      failures.push({ targetType: "user", targetId: mapped.userId, error: errorMessage(error) });
+    }
+  }
+
+  return { ok: failures.length === 0, writes, failures, conversation: data.conversation };
+}
+
+export async function pushMetadata(params: {
+  memoryRoot: string;
+  targetType: ClawChatMemoryTargetType;
+  targetId: string;
+  fields: string[];
+  agentId?: string;
+  accountUserId: string;
+  api: MetadataApi;
+}): Promise<MetadataPushResult> {
+  const file = await readClawChatMemoryFile(params.memoryRoot, {
+    targetType: params.targetType,
+    targetId: params.targetId,
+  });
+  return await updateMetadata({
+    memoryRoot: params.memoryRoot,
+    targetType: params.targetType,
+    targetId: params.targetId,
+    agentId: params.agentId,
+    accountUserId: params.accountUserId,
+    patch: pickPushPatch(params.targetType, params.targetId, file.metadata, {
+      fields: params.fields,
+      agentId: params.agentId,
+      accountUserId: params.accountUserId,
+    }),
+    api: params.api,
+  });
+}
+
+function mutableFieldsForTarget(
+  targetType: ClawChatMemoryTargetType,
+  targetId: string,
+  params: { agentId?: string; accountUserId?: string },
+): readonly string[] {
+  if (targetType === "owner") {
+    if (targetId !== "owner") throw new Error("ClawChat owner metadata targetId must be owner");
+    if (!params.agentId) throw new Error("ClawChat owner metadata update requires agentId");
+    return ["agent_behavior"];
+  }
+  if (targetType === "user") {
+    if (!params.accountUserId) throw new Error("ClawChat user metadata update requires accountUserId");
+    if (targetId !== params.accountUserId) {
+      throw new Error("ClawChat user metadata update is allowed only for the connected user");
+    }
+    return ["nickname", "avatar_url", "bio"];
+  }
+  return ["group_title", "group_description"];
+}
+
+function pickPushPatch(
+  targetType: ClawChatMemoryTargetType,
+  targetId: string,
+  metadata: Record<string, string>,
+  params: { fields: string[]; agentId?: string; accountUserId?: string },
+): Record<string, string> {
+  if (!Array.isArray(params.fields) || params.fields.length === 0) {
+    throw new Error("fields are required for metadata push");
+  }
+  const allowed = mutableFieldsForTarget(targetType, targetId, params);
+  const patch: Record<string, string> = {};
+  for (const field of params.fields) {
+    if (typeof field !== "string" || field.length === 0) {
+      throw new Error("fields must contain non-empty strings");
+    }
+    if (!allowed.includes(field)) {
+      throw new Error(`fields contain non-pushable metadata field: ${field}`);
+    }
+    if (!hasOwn(metadata, field)) {
+      throw new Error(`missing_metadata_field: ${field}`);
+    }
+    patch[field] = metadata[field]!;
+  }
+  return patch;
+}
+
+export async function updateMetadata(params: {
+  memoryRoot: string;
+  targetType: ClawChatMemoryTargetType;
+  targetId: string;
+  agentId?: string;
+  accountUserId?: string;
+  patch: Record<string, unknown>;
+  api: MetadataApi;
+}): Promise<MetadataPushResult> {
+  if (params.targetType === "owner") {
+    if (!params.agentId) throw new Error("ClawChat owner metadata update requires agentId");
+    if (!params.api.updateAgentBehavior) {
+      throw new Error("ClawChat owner metadata update requires updateAgentBehavior");
+    }
+    const localPatch = pickUpdatePatch<Record<"agent_behavior", string>>(
+      params.patch,
+      ["agent_behavior"],
+    );
+    const response = await params.api.updateAgentBehavior(localPatch.agent_behavior);
+    const metadata = ownerMetadataFromAgent(response.agent as AgentProfile & Record<string, unknown>, {
+      accountUserId: params.accountUserId,
+    });
+    const ownerId = metadata.agent_owner_id;
+    const getOwner = params.api.getUserProfile ?? params.api.getUserInfo;
+    if (ownerId && getOwner) {
+      addOwnerProfileMetadata(metadata, asRecord(await getOwner(ownerId)) ?? {});
+    }
+    await writeClawChatMetadata(params.memoryRoot, { targetType: "owner", targetId: "owner" }, metadata);
+    return { ok: true, writes: [{ targetType: "owner", targetId: "owner" }], failures: [], metadata };
+  }
+
+  if (params.targetType === "user") {
+    if (!params.accountUserId) throw new Error("ClawChat user metadata update requires accountUserId");
+    if (params.targetId !== params.accountUserId) {
+      throw new Error("ClawChat user metadata update is allowed only for the connected user");
+    }
+    if (!params.api.updateMyProfile) throw new Error("ClawChat user metadata update requires updateMyProfile");
+    const patch = pickUpdatePatch<{ nickname?: string; avatar_url?: string; bio?: string } & Record<string, string>>(
+      params.patch,
+      ["nickname", "avatar_url", "bio"],
+    );
+    const profile = await params.api.updateMyProfile(patch);
+    const metadata = userMetadataFromProfile(profile, params.targetId);
+    await writeClawChatMetadata(params.memoryRoot, { targetType: "user", targetId: params.targetId }, metadata);
+    return { ok: true, writes: [{ targetType: "user", targetId: params.targetId }], failures: [], metadata };
+  }
+
+  if (!params.api.patchConversation) throw new Error("ClawChat group metadata update requires patchConversation");
+  const patch = pickUpdatePatch<ConversationMetadataPatch & Record<string, string>>(
+    params.patch,
+    ["group_title", "group_description"],
+  );
+  const response = await params.api.patchConversation(params.targetId, {
+    title: patch.group_title,
+    description: patch.group_description,
+  });
+  const metadata = groupMetadataFromConversation(response.conversation, params.targetId);
+  await writeClawChatMetadata(params.memoryRoot, { targetType: "group", targetId: params.targetId }, metadata);
+  return { ok: true, writes: [{ targetType: "group", targetId: params.targetId }], failures: [], metadata };
+}

package/src/client.test.ts

@@ -0,0 +1,169 @@
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
+import { describe, expect, it, vi } from "vitest";
+import { MockTransport } from "./mock-transport.ts";
+import { createOpenclawClawlingClient } from "./client.ts";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+
+function baseAccount(): ResolvedOpenclawClawlingAccount {
+  return {
+    accountId: DEFAULT_ACCOUNT_ID,
+    name: "clawchat-plugin-openclaw",
+    enabled: true,
+    configured: true,
+    websocketUrl: "ws://test",
+    baseUrl: "",
+    token: "t",
+    agentId: "",
+    userId: "agent-1",
+    ownerUserId: "owner-1",
+    groupMode: "all",
+    groupCommandMode: "owner",
+    groups: {},
+    forwardThinking: true,
+    forwardToolCalls: false,
+    richInteractions: false,
+    allowFrom: [],
+    reconnect: {
+      initialDelay: 1000,
+      maxDelay: 30000,
+      jitterRatio: 0.3,
+      maxRetries: Number.POSITIVE_INFINITY,
+    },
+    heartbeat: { interval: 25000, timeout: 10000 },
+    ack: { timeout: 10000, autoResendOnTimeout: false },
+  };
+}
+
+async function authenticate(transport: MockTransport) {
+  await Promise.resolve();
+  transport.emitInbound(
+    JSON.stringify({
+      version: "2",
+      event: "connect.challenge",
+      trace_id: "t-challenge",
+      emitted_at: Date.now(),
+      payload: { nonce: "nonce-1" },
+    }),
+  );
+  const connectFrame = transport.sent
+    .map((raw) => JSON.parse(raw))
+    .find((env) => env.event === "connect");
+  transport.emitInbound(
+    JSON.stringify({
+      version: "2",
+      event: "hello-ok",
+      trace_id: connectFrame.trace_id,
+      emitted_at: Date.now(),
+      payload: {},
+    }),
+  );
+}
+
+describe("clawchat-plugin-openclaw client", () => {
+  it("connects via MockTransport and completes hello handshake", async () => {
+    const transport = new MockTransport();
+    const client = createOpenclawClawlingClient(baseAccount(), { transport });
+    const p = client.connect();
+    await authenticate(transport);
+    await p;
+    expect(client.state).toBe("connected");
+    client.close();
+  });
+
+  it("sends msghub connect payload without signature fields", async () => {
+    const transport = new MockTransport();
+    const client = createOpenclawClawlingClient(baseAccount(), { transport });
+    const p = client.connect();
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    expect(connectFrame.payload).toMatchObject({
+      token: "t",
+      nonce: "nonce-1",
+    });
+    expect(connectFrame.payload).not.toHaveProperty("sign");
+    expect(connectFrame.payload).not.toHaveProperty("signature");
+    expect(connectFrame.payload).not.toHaveProperty("client_id");
+    expect(connectFrame.payload).not.toHaveProperty("client_version");
+
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await p;
+    client.close();
+  });
+
+  it("reports connect frames after the transport records them", async () => {
+    const transport = new MockTransport();
+    const onConnectFrameSent = vi.fn((env: { trace_id?: unknown }) => {
+      const sentConnect = transport.sent
+        .map((raw) => JSON.parse(raw))
+        .find((frame) => frame.event === "connect");
+      expect(sentConnect?.trace_id).toBe(env.trace_id);
+    });
+    const client = createOpenclawClawlingClient(baseAccount(), {
+      transport,
+      wsLifecycle: { onConnectFrameSent },
+    });
+
+    const connected = client.connect();
+    await authenticate(transport);
+    await connected;
+
+    expect(onConnectFrameSent).toHaveBeenCalledTimes(1);
+    client.close();
+  });
+
+  it("reports connect frames only after they are sent", async () => {
+    const transport = new MockTransport();
+    const onConnectFrameSent = vi.fn();
+    const originalSend = transport.send.bind(transport);
+    transport.send = vi.fn((wire: string) => {
+      const env = JSON.parse(wire);
+      if (env.event === "connect") throw new Error("send failed");
+      originalSend(wire);
+    });
+    const client = createOpenclawClawlingClient(baseAccount(), {
+      transport,
+      wsLifecycle: { onConnectFrameSent },
+    });
+
+    const connected = client.connect();
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+
+    await expect(connected).rejects.toThrow(/send failed/);
+    expect(onConnectFrameSent).not.toHaveBeenCalled();
+  });
+
+  it("creates a local production transport when no override is supplied", () => {
+    const client = createOpenclawClawlingClient(baseAccount());
+    expect(client.transportState).toBe("closed");
+  });
+});

package/src/client.ts

@@ -0,0 +1,56 @@
+import type { Envelope, Transport } from "./protocol-types.ts";
+import { createClawChatClient, type ClawlingChatClient } from "./ws-client.ts";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+
+export type { ChatType } from "./protocol-types.ts";
+
+export interface CreateClientOverrides {
+  /** Transport override — only intended for tests (e.g. MockTransport). */
+  transport?: Transport;
+  wsLifecycle?: {
+    onConnectFrameSent?: (env: {
+      trace_id?: unknown;
+      payload?: { device_id?: unknown };
+    }) => void;
+  };
+}
+
+export function createOpenclawClawlingClient(
+  account: ResolvedOpenclawClawlingAccount,
+  overrides: CreateClientOverrides = {},
+): ClawlingChatClient {
+  const client = createClawChatClient({
+    url: account.websocketUrl,
+    token: account.token,
+    deviceId: account.userId,
+    ...(overrides.transport ? { transport: overrides.transport } : {}),
+    reconnect: {
+      enabled: true,
+      initialDelay: account.reconnect.initialDelay,
+      maxDelay: account.reconnect.maxDelay,
+      jitterRatio: account.reconnect.jitterRatio,
+      maxRetries: account.reconnect.maxRetries,
+    },
+    heartbeat: {
+      enabled: true,
+      interval: account.heartbeat.interval,
+      timeout: account.heartbeat.timeout,
+    },
+    ack: {
+      timeout: account.ack.timeout,
+      autoResendOnTimeout: account.ack.autoResendOnTimeout,
+    },
+  });
+  if (overrides.wsLifecycle?.onConnectFrameSent) {
+    const sendRawEnvelope = client.sendRawEnvelope.bind(client);
+    client.sendRawEnvelope = (env: Envelope) => {
+      sendRawEnvelope(env);
+      if (env.event === "connect") {
+        overrides.wsLifecycle?.onConnectFrameSent?.(
+          env as { trace_id?: unknown; payload?: { device_id?: unknown } },
+        );
+      }
+    };
+  }
+  return client;
+}

package/src/commands.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it, vi } from "vitest";
+import { registerOpenclawClawlingCommands } from "./commands.ts";
+
+const loginRuntime = vi.hoisted(() => ({
+  runOpenclawClawlingLogin: vi.fn(),
+}));
+
+vi.mock("./login.runtime.ts", () => loginRuntime);
+
+describe("registerOpenclawClawlingCommands", () => {
+  it("registers a distinct slash activate command that passes the invite code to login", async () => {
+    loginRuntime.runOpenclawClawlingLogin.mockResolvedValue(undefined);
+    const commands: Array<{ name: string; acceptsArgs?: boolean; handler: (ctx: unknown) => Promise<{ text: string }> }> = [];
+    const api = {
+      registerCommand: (command: (typeof commands)[number]) => commands.push(command),
+      runtime: {
+        config: {
+          mutateConfigFile: vi.fn(),
+        },
+      },
+    } as never;
+
+    registerOpenclawClawlingCommands(api);
+
+    expect(commands.map((command) => command.name)).toEqual(["clawchat-activate"]);
+    expect(commands[0]?.acceptsArgs).toBe(true);
+
+    const result = await commands[0]!.handler({
+      args: "A1B2C3",
+      config: { channels: { "clawchat-plugin-openclaw": { websocketUrl: "wss://w" } } },
+    });
+
+    expect(loginRuntime.runOpenclawClawlingLogin).toHaveBeenCalledTimes(1);
+    const params = loginRuntime.runOpenclawClawlingLogin.mock.calls[0]?.[0];
+    expect(params.mutateConfigFile).toBe(api.runtime.config.mutateConfigFile);
+    await expect(params.readInviteCode()).resolves.toBe("A1B2C3");
+    expect(result.text).toMatch(/activated successfully/i);
+  });
+});