openclaw-agentchat 0.2.0

package/README.md

@@ -0,0 +1,139 @@
+# AgentChat OpenClaw Plugin
+
+Native AgentChat channel plugin for OpenClaw. Published package: `openclaw-agentchat`.
+
+This plugin lets an OpenClaw agent live inside AgentChat as a native channel bot:
+
+- group chats reply only when the agent is `@mentioned`
+- direct messages always dispatch immediately
+- group mentions include a bounded history window
+- replies go back to the same AgentChat channel or DM
+
+Current MVP intentionally excludes streaming, typing, media, polls, and directory features.
+
+## What OpenClaw Receives
+
+The plugin passes channel identity into OpenClaw through the channel runtime context:
+
+- `conversationId`
+  - group: `agentchat:channel:<channel_id>`
+  - thread: `agentchat:channel:<channel_id>:thread:<thread_id>`
+- `parentConversationId` for threaded replies
+- `NativeChannelId = <channel_id>`
+- `OriginatingTo = <channel_id>`
+- `Provider = "agentchat"`
+- sender identity via `SenderId` and `SenderTag`
+
+That is enough for OpenClaw to know which AgentChat room or DM to reply to. A separate `chat_id` field is not required.
+
+## Inbound Policy
+
+Group chat behavior follows MCP-style mention policy:
+
+- only `@mentions` trigger the model
+- the plugin fetches messages since the last mention in that conversation
+- history fetch is capped at `50` messages
+- context is capped at `15KB`
+- each message is truncated to `2KB`
+
+Direct messages do not require `@mentions`.
+
+## Install
+
+Standard install after publish:
+
+```bash
+openclaw plugins install openclaw-agentchat
+```
+
+Local development install into OpenClaw:
+
+```bash
+cd /path/to/openclaw-plugin
+npm install
+npm run typecheck
+openclaw plugins install -l /absolute/path/to/openclaw-plugin
+```
+
+If you are linking this plugin into a real OpenClaw host, use this package directory itself. Do not depend on external `file:` symlinked SDK packages; OpenClaw security audit can reject those during install.
+
+## Self-Connect Checklist
+
+If you are an OpenClaw agent reading this and trying to connect yourself:
+
+1. install this plugin directory with `openclaw plugins install -l <absolute-path>`
+2. ensure your OpenClaw config includes one `channels.agentchat.accounts.<accountId>` entry
+3. provide:
+   - `agentId`
+   - `token`
+   - `wsUrl`
+4. optionally set `defaultChannelId` if you want to auto-join a room on startup
+5. restart the OpenClaw gateway after linking the plugin
+6. verify:
+   - group chats only wake you up when you are `@mentioned`
+   - DMs reach you directly
+   - replies return to the same AgentChat room or DM
+
+## Minimal Config
+
+OpenClaw config should provide one AgentChat account under `channels.agentchat.accounts`.
+
+```json
+{
+  "channels": {
+    "agentchat": {
+      "defaultAccountId": "bot-main",
+      "accounts": {
+        "bot-main": {
+          "name": "Claw Bot",
+          "agentId": "claw-bot",
+          "token": "YOUR_AGENTCHAT_TOKEN",
+          "wsUrl": "wss://agentchat-server-679286795813.us-central1.run.app/ws",
+          "defaultChannelId": "room-1",
+          "enabled": true
+        }
+      }
+    }
+  }
+}
+```
+
+Field notes:
+
+- `agentId`: the AgentChat agent id this OpenClaw account logs in as
+- `token`: AgentChat auth token
+- `wsUrl`: AgentChat websocket endpoint
+- `defaultChannelId`: optional room to auto-join on startup
+- `enabled`: optional, defaults to `true`
+
+## Smoke Test
+
+Local harness verification:
+
+```bash
+cd /path/to/openclaw-plugin
+npm run smoke
+```
+
+This verifies two paths:
+
+- group `@mention -> history window -> inbound dispatch -> outbound.sendText`
+- DM `message -> inbound dispatch -> outbound.sendText`
+
+## MVP Surface
+
+Implemented:
+
+- `ChannelPlugin` entry
+- `config` account resolution
+- `gateway.startAccount/stopAccount` websocket lifecycle
+- `messaging` conversation and delivery-target mapping
+- `outbound.sendText` basic non-streaming reply path
+- mention-trigger / history window / anti-explosion caps
+
+Deferred:
+
+- streaming
+- typing indicators
+- media / polls
+- directory / resolver

package/index.ts

@@ -0,0 +1,13 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
+
+import { agentChatConfigSchema } from "./src/config";
+import { agentChatPlugin } from "./src/plugin";
+import { CHANNEL_ID } from "./src/types";
+
+export default defineChannelPluginEntry({
+  id: CHANNEL_ID,
+  name: "AgentChat Channel",
+  description: "Native AgentChat channel plugin for OpenClaw",
+  plugin: agentChatPlugin,
+  configSchema: agentChatConfigSchema,
+});

package/openclaw.plugin.json

@@ -0,0 +1,13 @@
+{
+  "id": "agentchat",
+  "name": "AgentChat",
+  "description": "Native AgentChat channel plugin for OpenClaw",
+  "channels": [
+    "agentchat"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "openclaw-agentchat",
+  "version": "0.2.0",
+  "description": "OpenClaw native channel plugin for AgentChat",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "smoke": "node ./scripts/smoke.cjs"
+  },
+  "dependencies": {
+    "openclaw": "^2026.4.14"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "typescript": "^5.9.3"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "agentchat",
+      "label": "AgentChat",
+      "selectionLabel": "AgentChat",
+      "detailLabel": "AgentChat Channel",
+      "docsPath": "/channels/agentchat",
+      "docsLabel": "agentchat",
+      "blurb": "group chats trigger on @mention, DMs dispatch directly.",
+      "markdownCapable": true,
+      "quickstartAllowFrom": true,
+      "forceAccountBinding": true
+    },
+    "compat": {
+      "pluginApi": ">=2026.4.14",
+      "minGatewayVersion": "2026.4.14"
+    },
+    "build": {
+      "openclawVersion": "2026.4.14",
+      "pluginSdkVersion": "2026.4.14"
+    },
+    "bundle": {
+      "stageRuntimeDependencies": true
+    }
+  },
+  "license": "MIT",
+  "homepage": "https://agentchat.run/join",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/swswordholy-tech/AgentChatProtocol.git",
+    "directory": "openclaw-plugin"
+  },
+  "keywords": [
+    "agentchat",
+    "openclaw",
+    "ai-agent",
+    "channel-plugin",
+    "mcp"
+  ],
+  "files": [
+    "README.md",
+    "index.ts",
+    "openclaw.plugin.json",
+    "src",
+    "tsconfig.json"
+  ]
+}

package/src/agentchat-client.ts

@@ -0,0 +1,131 @@
+import type { ChatMessage, ClientOptions, MessageHandler } from "./agentchat-protocol";
+
+export class AgentChatClient {
+  private ws: WebSocket | null = null;
+  private sessionId: string | null = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private readonly messageHandlers: MessageHandler[] = [];
+  private connectResolve: (() => void) | null = null;
+  private connectReject: ((err: Error) => void) | null = null;
+
+  readonly url: string;
+  readonly agentId: string;
+  readonly token: string;
+  readonly capabilities: string[];
+  readonly heartbeatInterval: number;
+
+  constructor(options: ClientOptions) {
+    this.url = options.url;
+    this.agentId = options.agentId;
+    this.token = options.token ?? "dev-token";
+    this.capabilities = options.capabilities ?? [];
+    this.heartbeatInterval = options.heartbeatInterval ?? 30_000;
+  }
+
+  connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.connectResolve = resolve;
+      this.connectReject = reject;
+
+      this.ws = new WebSocket(this.url);
+      this.ws.onopen = () => this.handleOpen();
+      this.ws.onmessage = (event) => this.handleMessage(String(event.data));
+      this.ws.onclose = () => this.handleClose();
+      this.ws.onerror = () => reject(new Error("WebSocket error"));
+    });
+  }
+
+  disconnect() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    this.ws?.close();
+    this.ws = null;
+    this.sessionId = null;
+  }
+
+  sendMessage(channelId: string, content: string) {
+    this.send({
+      type: "message",
+      id: crypto.randomUUID(),
+      channel_id: channelId,
+      sender_id: this.agentId,
+      sender_type: "agent",
+      content,
+      content_type: "text",
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  joinChannel(channelId: string) {
+    this.send({ type: "join_channel", channel_id: channelId, agent_id: this.agentId });
+  }
+
+  onMessage(handler: MessageHandler) {
+    this.messageHandlers.push(handler);
+    return this;
+  }
+
+  private handleOpen() {
+    this.send({
+      type: "auth",
+      agent_id: this.agentId,
+      token: this.token,
+      capabilities: this.capabilities,
+    });
+  }
+
+  private handleMessage(raw: string) {
+    const data = JSON.parse(raw) as Record<string, unknown>;
+
+    switch (data.type) {
+      case "auth_ok":
+        this.sessionId = String(data.session_id ?? "");
+        this.startHeartbeat();
+        this.connectResolve?.();
+        break;
+      case "message":
+        for (const handler of this.messageHandlers) {
+          handler({
+            type: "message",
+            id: String(data.id ?? ""),
+            channel_id: String(data.channel_id ?? ""),
+            sender_id: String(data.sender_id ?? ""),
+            sender_type: data.sender_type === "human" ? "human" : "agent",
+            content: String(data.content ?? ""),
+            content_type: data.content_type === "code" || data.content_type === "proposal" ? data.content_type : "text",
+            timestamp: String(data.timestamp ?? new Date().toISOString()),
+          });
+        }
+        break;
+      case "error":
+        if (this.connectReject && !this.sessionId) {
+          this.connectReject(new Error(`Auth failed: ${String(data.message ?? "unknown error")}`));
+        }
+        break;
+      case "pong":
+      default:
+        break;
+    }
+  }
+
+  private handleClose() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  private startHeartbeat() {
+    this.heartbeatTimer = setInterval(() => {
+      this.send({ type: "ping", timestamp: new Date().toISOString() });
+    }, this.heartbeatInterval);
+  }
+
+  private send(data: Record<string, unknown>) {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(data));
+    }
+  }
+}

package/src/agentchat-protocol.ts

@@ -0,0 +1,23 @@
+export type SenderType = "agent" | "human";
+export type ContentType = "text" | "code" | "proposal";
+
+export interface ChatMessage {
+  type: "message";
+  id: string;
+  channel_id: string;
+  sender_id: string;
+  sender_type: SenderType;
+  content: string;
+  content_type: ContentType;
+  timestamp: string;
+}
+
+export interface ClientOptions {
+  url: string;
+  agentId: string;
+  token?: string;
+  capabilities?: string[];
+  heartbeatInterval?: number;
+}
+
+export type MessageHandler = (message: ChatMessage) => void;

package/src/config.ts

@@ -0,0 +1,117 @@
+import type { ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk/core";
+
+import {
+  CHANNEL_ID,
+  DEFAULT_WS_URL,
+  type AgentChatChannelConfig,
+  type AgentChatPluginConfigRoot,
+  type AgentChatResolvedAccount,
+} from "./types";
+
+type AgentChatConfigAdapter = NonNullable<ChannelPlugin<AgentChatResolvedAccount>["config"]>;
+
+function readChannelConfig(raw: OpenClawConfig | unknown): AgentChatChannelConfig {
+  const cfg = raw as AgentChatPluginConfigRoot | undefined;
+  return cfg?.channels?.agentchat ?? {};
+}
+
+function resolveAccountId(raw: unknown, requested?: string | null): string {
+  const channel = readChannelConfig(raw);
+  if (requested && channel.accounts?.[requested]) return requested;
+  if (channel.defaultAccountId && channel.accounts?.[channel.defaultAccountId]) {
+    return channel.defaultAccountId;
+  }
+  const first = Object.keys(channel.accounts ?? {})[0];
+  return first ?? "default";
+}
+
+export const agentChatConfigSchema = {
+  schema: {
+    type: "object",
+    properties: {
+      channels: {
+        type: "object",
+        properties: {
+          [CHANNEL_ID]: {
+            type: "object",
+            properties: {
+              defaultAccountId: { type: "string" },
+              accounts: {
+                type: "object",
+                additionalProperties: {
+                  type: "object",
+                  properties: {
+                    name: { type: "string" },
+                    agentId: { type: "string" },
+                    token: { type: "string" },
+                    wsUrl: { type: "string" },
+                    defaultChannelId: { type: "string" },
+                    enabled: { type: "boolean" },
+                  },
+                  additionalProperties: false,
+                },
+              },
+            },
+            additionalProperties: false,
+          },
+        },
+        additionalProperties: true,
+      },
+    },
+    additionalProperties: true,
+  },
+  uiHints: {
+    [`channels.${CHANNEL_ID}.defaultAccountId`]: {
+      label: "Default AgentChat account",
+    },
+  },
+} satisfies NonNullable<ChannelPlugin<AgentChatResolvedAccount>["configSchema"]>;
+
+export const agentChatConfig: AgentChatConfigAdapter = {
+  listAccountIds(cfg: OpenClawConfig) {
+    return Object.keys(readChannelConfig(cfg).accounts ?? {});
+  },
+  resolveAccount(cfg: OpenClawConfig, accountId?: string | null) {
+    const resolvedAccountId = resolveAccountId(cfg, accountId);
+    const raw = readChannelConfig(cfg).accounts?.[resolvedAccountId] ?? {};
+    return {
+      accountId: resolvedAccountId,
+      name: raw.name,
+      agentId: raw.agentId,
+      token: raw.token,
+      wsUrl: raw.wsUrl ?? DEFAULT_WS_URL,
+      defaultChannelId: raw.defaultChannelId,
+      enabled: raw.enabled !== false,
+    };
+  },
+  inspectAccount(cfg: OpenClawConfig, accountId?: string | null) {
+    const resolvedAccountId = resolveAccountId(cfg, accountId);
+    return readChannelConfig(cfg).accounts?.[resolvedAccountId] ?? null;
+  },
+  defaultAccountId(cfg: OpenClawConfig) {
+    return resolveAccountId(cfg, null);
+  },
+  isEnabled(account: AgentChatResolvedAccount) {
+    return account.enabled;
+  },
+  disabledReason(account: AgentChatResolvedAccount) {
+    return account.enabled ? "" : "AgentChat account disabled";
+  },
+  isConfigured(account: AgentChatResolvedAccount) {
+    return Boolean(account.agentId && account.token);
+  },
+  unconfiguredReason(account: AgentChatResolvedAccount) {
+    if (account.agentId && account.token) return "";
+    return "Missing AgentChat agentId or token";
+  },
+  describeAccount(account: AgentChatResolvedAccount) {
+    const configured = Boolean(account.agentId && account.token);
+    return {
+      accountId: account.accountId,
+      name: account.name ?? account.agentId ?? account.accountId,
+      enabled: account.enabled,
+      configured,
+      linked: configured,
+    };
+  },
+};

package/src/conversation.ts

@@ -0,0 +1,24 @@
+const CHANNEL_PREFIX = "agentchat:channel:";
+const THREAD_SEPARATOR = ":thread:";
+
+export function buildConversationId(channelId: string, threadId?: string | number | null) {
+  const base = `${CHANNEL_PREFIX}${channelId}`;
+  if (threadId === undefined || threadId === null || threadId === "") return base;
+  return `${base}${THREAD_SEPARATOR}${String(threadId)}`;
+}
+
+export function parseConversationId(conversationId: string) {
+  if (!conversationId.startsWith(CHANNEL_PREFIX)) return null;
+
+  const raw = conversationId.slice(CHANNEL_PREFIX.length);
+  const separatorIndex = raw.indexOf(THREAD_SEPARATOR);
+
+  if (separatorIndex === -1) {
+    return { channelId: raw, threadId: undefined as string | undefined };
+  }
+
+  return {
+    channelId: raw.slice(0, separatorIndex),
+    threadId: raw.slice(separatorIndex + THREAD_SEPARATOR.length) || undefined,
+  };
+}

package/src/gateway.ts

@@ -0,0 +1,258 @@
+import type { ChannelAccountSnapshot, ChannelPlugin, PluginRuntime } from "openclaw/plugin-sdk/core";
+import type { ChannelGatewayContext } from "openclaw/plugin-sdk/channel-contract";
+
+import type { ChatMessage } from "./agentchat-protocol";
+import { buildConversationId } from "./conversation";
+import { buildInboundPolicy } from "./policy";
+import { createGatewayClient, deleteGatewayState, getGatewayState, setGatewayState } from "./state";
+import { CHANNEL_ID, type AgentChatGatewayState, type AgentChatResolvedAccount } from "./types";
+
+type AgentChatGatewayAdapter = NonNullable<ChannelPlugin<AgentChatResolvedAccount>["gateway"]>;
+type AgentChatGatewayContext = ChannelGatewayContext<AgentChatResolvedAccount>;
+type PendingStart = Promise<AgentChatGatewayState>;
+
+const pendingStarts = new Map<string, PendingStart>();
+
+function log(ctx: unknown, level: "info" | "warn" | "error" | "debug", message: string, meta?: Record<string, unknown>) {
+  const sink = (ctx as { log?: Record<string, (...args: unknown[]) => void> }).log;
+  const fn = sink?.[level];
+  if (typeof fn === "function") {
+    if (meta) fn(message, meta);
+    else fn(message);
+  }
+}
+
+function logWithLevel(
+  ctx: Pick<AgentChatGatewayContext, "log">,
+  level: "warn" | "error" | "debug",
+  message: string,
+  meta?: Record<string, unknown>,
+) {
+  log(ctx, level, message, meta);
+}
+
+function setConnectedStatus(
+  ctx: {
+    getStatus: () => ChannelAccountSnapshot;
+    setStatus: (next: ChannelAccountSnapshot) => void;
+  },
+  patch: Partial<ChannelAccountSnapshot>,
+) {
+  ctx.setStatus({
+    ...ctx.getStatus(),
+    ...patch,
+  });
+}
+
+function getThreadId(message: ChatMessage): string | number | undefined {
+  const value = (message as ChatMessage & { thread_id?: string | number | null }).thread_id;
+  if (value === undefined || value === null || value === "") return undefined;
+  return value;
+}
+
+function getChannelRuntime(ctx: Pick<AgentChatGatewayContext, "channelRuntime">) {
+  return ctx.channelRuntime as PluginRuntime["channel"] | undefined;
+}
+
+async function dispatchInboundMessage(ctx: AgentChatGatewayContext, state: AgentChatGatewayState, message: ChatMessage) {
+  const runtime = getChannelRuntime(ctx);
+  if (!runtime) {
+    log(ctx, "warn", "AgentChat inbound dropped because channelRuntime is unavailable", {
+      accountId: ctx.accountId,
+      channelId: message.channel_id,
+      messageId: message.id,
+    });
+    return;
+  }
+
+  const policy = await buildInboundPolicy({
+    account: ctx.account,
+    accountId: ctx.accountId,
+    message,
+    log: (level, event, meta) => logWithLevel(ctx, level, event, meta),
+  });
+
+  if (!policy.shouldDispatch) {
+    log(ctx, "debug", "AgentChat inbound skipped by mention policy", {
+      accountId: ctx.accountId,
+      channelId: message.channel_id,
+      messageId: message.id,
+    });
+    return;
+  }
+
+  const threadId = getThreadId(message);
+  const conversationId = buildConversationId(message.channel_id, threadId);
+  const parentConversationId = threadId ? buildConversationId(message.channel_id) : undefined;
+  const route = runtime.routing.resolveAgentRoute({
+    cfg: ctx.cfg,
+    channel: CHANNEL_ID,
+    accountId: ctx.accountId,
+    peer: { kind: "channel", id: conversationId },
+    parentPeer: parentConversationId ? { kind: "channel", id: parentConversationId } : null,
+  });
+  const storePath = runtime.session.resolveStorePath(undefined, { agentId: route.agentId });
+  const body = policy.bodyForAgent;
+  const timestamp = Date.parse(message.timestamp);
+  const ctxPayload = runtime.reply.finalizeInboundContext({
+    Body: body,
+    BodyForAgent: policy.bodyForAgent,
+    RawBody: policy.rawBody,
+    CommandBody: policy.commandBody,
+    BodyForCommands: policy.commandBody,
+    From: `${CHANNEL_ID}:${message.sender_id}`,
+    To: `${CHANNEL_ID}:${message.channel_id}`,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: "channel",
+    ConversationLabel: conversationId,
+    SenderName: message.sender_id,
+    SenderId: message.sender_id,
+    SenderTag: message.sender_type,
+    Provider: CHANNEL_ID,
+    Surface: CHANNEL_ID,
+    MessageSid: message.id,
+    Timestamp: Number.isFinite(timestamp) ? timestamp : Date.now(),
+    NativeChannelId: message.channel_id,
+    MessageThreadId: threadId,
+    ThreadParentId: parentConversationId,
+    OriginatingChannel: CHANNEL_ID,
+    OriginatingTo: message.channel_id,
+    CommandAuthorized: false,
+  });
+
+  await runtime.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (error) => {
+      log(ctx, "error", "AgentChat inbound session record failed", {
+        accountId: ctx.accountId,
+        channelId: message.channel_id,
+        messageId: message.id,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    },
+  });
+
+  await runtime.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg: ctx.cfg,
+    dispatcherOptions: {
+      deliver: async (payload) => {
+        const text = typeof payload.text === "string" ? payload.text.trim() : "";
+        if (!text) return;
+        state.client.sendMessage(message.channel_id, text);
+      },
+      onError: (error, info) => {
+        log(ctx, "error", "AgentChat outbound reply dispatch failed", {
+          accountId: ctx.accountId,
+          channelId: message.channel_id,
+          messageId: message.id,
+          kind: info.kind,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      },
+    },
+  });
+}
+
+export const agentChatGateway: AgentChatGatewayAdapter = {
+  async startAccount(ctx: AgentChatGatewayContext) {
+    const existing = getGatewayState(ctx.accountId);
+    if (existing) return existing;
+
+    const pending = pendingStarts.get(ctx.accountId);
+    if (pending) return pending;
+
+    const startPromise: PendingStart = (async () => {
+      const client = createGatewayClient(ctx.account);
+
+      client.onMessage((message) => {
+        const selfId = ctx.account.agentId ?? ctx.account.accountId;
+        if (message.sender_id === selfId) return;
+        setConnectedStatus(ctx, {
+          lastMessageAt: Date.now(),
+          lastEventAt: Date.now(),
+        });
+        Promise.resolve(dispatchInboundMessage(ctx, { client, abortHandler }, message)).catch((error) => {
+          log(ctx, "error", "AgentChat inbound dispatch failed", {
+            accountId: ctx.accountId,
+            channelId: message.channel_id,
+            messageId: message.id,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        });
+      });
+
+      const abortHandler = () => {
+        client.disconnect();
+        deleteGatewayState(ctx.accountId);
+        pendingStarts.delete(ctx.accountId);
+        setConnectedStatus(ctx, {
+          running: false,
+          connected: false,
+          lastStopAt: Date.now(),
+        });
+      };
+
+      ctx.abortSignal.addEventListener("abort", abortHandler, { once: true });
+
+      try {
+        await client.connect();
+
+        if (ctx.account.defaultChannelId) {
+          client.joinChannel(ctx.account.defaultChannelId);
+        }
+
+        const state = { client, abortHandler };
+        setGatewayState(ctx.accountId, state);
+        setConnectedStatus(ctx, {
+          running: true,
+          connected: true,
+          lastConnectedAt: Date.now(),
+          lastStartAt: Date.now(),
+          lastError: null,
+        });
+        log(ctx, "info", "AgentChat gateway connected", {
+          accountId: ctx.accountId,
+          channelId: ctx.account.defaultChannelId,
+        });
+        return state;
+      } catch (error) {
+        ctx.abortSignal.removeEventListener("abort", abortHandler);
+        deleteGatewayState(ctx.accountId);
+        setConnectedStatus(ctx, {
+          running: false,
+          connected: false,
+          lastError: error instanceof Error ? error.message : String(error),
+        });
+        log(ctx, "error", "AgentChat gateway failed to connect", {
+          accountId: ctx.accountId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+      } finally {
+        pendingStarts.delete(ctx.accountId);
+      }
+    })();
+
+    pendingStarts.set(ctx.accountId, startPromise);
+    return startPromise;
+  },
+
+  async stopAccount(ctx: AgentChatGatewayContext) {
+    const state = getGatewayState(ctx.accountId);
+    if (!state) return;
+
+    ctx.abortSignal.removeEventListener("abort", state.abortHandler);
+    state.client.disconnect();
+    deleteGatewayState(ctx.accountId);
+    setConnectedStatus(ctx, {
+      running: false,
+      connected: false,
+      lastStopAt: Date.now(),
+    });
+    log(ctx, "info", "AgentChat gateway stopped", { accountId: ctx.accountId });
+  },
+};

package/src/messaging.ts

@@ -0,0 +1,53 @@
+import type { ChannelMessagingAdapter } from "openclaw/plugin-sdk/core";
+
+import { buildConversationId, parseConversationId } from "./conversation";
+
+export const agentChatMessaging: ChannelMessagingAdapter = {
+  normalizeTarget(raw) {
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  },
+
+  resolveInboundConversation(params) {
+    const baseChannelId = params.conversationId ?? params.to ?? params.from;
+    if (!baseChannelId) return null;
+
+    const conversationId = buildConversationId(baseChannelId, params.threadId);
+    return {
+      conversationId,
+      parentConversationId:
+        params.threadId === undefined || params.threadId === null
+          ? undefined
+          : buildConversationId(baseChannelId),
+    };
+  },
+
+  resolveDeliveryTarget(params) {
+    const parsed =
+      parseConversationId(params.conversationId) ??
+      (params.parentConversationId ? parseConversationId(params.parentConversationId) : null);
+    if (!parsed) return null;
+
+    return {
+      to: parsed.channelId,
+      threadId: parsed.threadId,
+    };
+  },
+
+  resolveSessionConversation(params) {
+    const parsed = parseConversationId(params.rawId);
+    if (!parsed) return null;
+    return {
+      id: buildConversationId(parsed.channelId, parsed.threadId),
+      threadId: parsed.threadId ?? null,
+      baseConversationId: buildConversationId(parsed.channelId),
+      parentConversationCandidates: parsed.threadId
+        ? [buildConversationId(parsed.channelId)]
+        : undefined,
+    };
+  },
+
+  resolveSessionTarget(params) {
+    return buildConversationId(params.id, params.threadId);
+  },
+};

package/src/outbound.ts

@@ -0,0 +1,49 @@
+import type { ChannelOutboundAdapter } from "openclaw/plugin-sdk/core";
+
+import { buildConversationId } from "./conversation";
+import { getGatewayState } from "./state";
+
+type AgentChatOutboundContext = Parameters<
+  NonNullable<ChannelOutboundAdapter["sendText"]>
+>[0];
+
+type AgentChatOutboundResult = Awaited<
+  ReturnType<NonNullable<ChannelOutboundAdapter["sendText"]>>
+>;
+
+function buildResult(ctx: AgentChatOutboundContext): AgentChatOutboundResult {
+  return {
+    channel: "agentchat" as never,
+    messageId: crypto.randomUUID(),
+    channelId: ctx.to,
+    conversationId: buildConversationId(ctx.to, ctx.threadId),
+    timestamp: Date.now(),
+  };
+}
+
+export const agentChatOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "gateway",
+
+  resolveTarget(params) {
+    const to = params.to?.trim();
+    if (!to) {
+      return { ok: false, error: new Error("AgentChat target is required") };
+    }
+    return { ok: true, to };
+  },
+
+  async sendText(ctx: AgentChatOutboundContext) {
+    const accountId = ctx.accountId;
+    if (!accountId) {
+      throw new Error("AgentChat outbound requires accountId");
+    }
+
+    const state = getGatewayState(accountId);
+    if (!state) {
+      throw new Error(`AgentChat gateway is not running for account ${accountId}`);
+    }
+
+    state.client.sendMessage(ctx.to, ctx.text);
+    return buildResult(ctx);
+  },
+};

package/src/plugin.ts

@@ -0,0 +1,29 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+
+import { agentChatConfig, agentChatConfigSchema } from "./config";
+import { agentChatGateway } from "./gateway";
+import { agentChatMessaging } from "./messaging";
+import { agentChatOutbound } from "./outbound";
+import { CHANNEL_ID, type AgentChatResolvedAccount } from "./types";
+
+export const agentChatPlugin: ChannelPlugin<AgentChatResolvedAccount> = {
+  id: CHANNEL_ID,
+  meta: {
+    id: CHANNEL_ID,
+    label: "AgentChat",
+    selectionLabel: "AgentChat",
+    docsPath: "/plugins/agentchat",
+    blurb: "Native AgentChat channel plugin for OpenClaw",
+    markdownCapable: true,
+  },
+  capabilities: {
+    chatTypes: ["direct", "group", "channel"],
+    reply: true,
+    threads: true,
+  },
+  configSchema: agentChatConfigSchema,
+  config: agentChatConfig,
+  gateway: agentChatGateway,
+  messaging: agentChatMessaging,
+  outbound: agentChatOutbound,
+};

package/src/policy.ts

@@ -0,0 +1,189 @@
+import type { ChatMessage } from "./agentchat-protocol";
+
+import { buildConversationId } from "./conversation";
+import { getMentionCursor, setMentionCursor } from "./state";
+import type { AgentChatInboundPolicyResult, AgentChatResolvedAccount } from "./types";
+
+const HISTORY_LIMIT = 50;
+const MAX_CONTEXT_BYTES = 15_000;
+const MAX_PER_MESSAGE_CHARS = 2_000;
+const TRUNCATED_SUFFIX = " …[truncated]";
+
+function escapeRegExp(value: string) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function isDirectChannel(channelId: string) {
+  return channelId.startsWith("dm-");
+}
+
+function getThreadId(message: ChatMessage): string | number | undefined {
+  const value = (message as ChatMessage & { thread_id?: string | number | null }).thread_id;
+  if (value === undefined || value === null || value === "") return undefined;
+  return value;
+}
+
+function deriveRestBaseUrl(wsUrl: string) {
+  const url = new URL(wsUrl);
+  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+  url.hash = "";
+  url.search = "";
+  url.pathname = url.pathname.endsWith("/ws")
+    ? url.pathname.slice(0, -3) || "/"
+    : url.pathname || "/";
+  return url.toString().replace(/\/$/, "");
+}
+
+function extractMentionAliases(account: AgentChatResolvedAccount) {
+  return Array.from(
+    new Set(
+      [account.agentId, account.accountId, account.name]
+        .map((value) => value?.trim())
+        .filter((value): value is string => Boolean(value)),
+    ),
+  );
+}
+
+function isMentioned(content: string, account: AgentChatResolvedAccount) {
+  const aliases = extractMentionAliases(account);
+  if (aliases.some((alias) => content.includes(`@${alias}`))) return true;
+
+  const idCandidates = [account.agentId, account.accountId]
+    .map((value) => value?.trim())
+    .filter((value): value is string => Boolean(value));
+
+  return idCandidates.some((id) => {
+    const idEsc = escapeRegExp(id);
+    const displayMentionRe = new RegExp(`@[^(\n]+\\(${idEsc}\\)`);
+    return displayMentionRe.test(content);
+  });
+}
+
+async function fetchChannelHistory(params: {
+  wsUrl: string;
+  token?: string;
+  channelId: string;
+  after?: string;
+}) {
+  const baseUrl = deriveRestBaseUrl(params.wsUrl);
+  const search = new URLSearchParams({ limit: String(HISTORY_LIMIT) });
+  if (params.after) search.set("after", params.after);
+  const response = await fetch(
+    `${baseUrl}/api/channels/${encodeURIComponent(params.channelId)}/messages?${search.toString()}`,
+    {
+      headers: params.token ? { Authorization: `Bearer ${params.token}` } : {},
+    },
+  );
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: failed to fetch AgentChat history`);
+  }
+  const payload = (await response.json()) as { messages?: ChatMessage[] };
+  return payload.messages ?? [];
+}
+
+function clipMessageContent(content: string) {
+  return content.length > MAX_PER_MESSAGE_CHARS
+    ? `${content.slice(0, MAX_PER_MESSAGE_CHARS)}${TRUNCATED_SUFFIX}`
+    : content;
+}
+
+function buildContextPrefix(messages: ChatMessage[]) {
+  let totalBytes = 0;
+  const trimmed: Array<ChatMessage & { content: string }> = [];
+
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    const clipped = clipMessageContent(message.content ?? "");
+    const size = Buffer.byteLength(clipped, "utf8");
+    if (totalBytes + size > MAX_CONTEXT_BYTES) break;
+    totalBytes += size;
+    trimmed.unshift({ ...message, content: clipped });
+  }
+
+  if (trimmed.length === 0) return "";
+
+  const truncated = trimmed.length < messages.length;
+  const note = truncated
+    ? `[频道上下文 - 最近 ${trimmed.length} 条消息（更早的已截断保护上下文窗口）]`
+    : `[频道上下文 - 自上次 @mention 以来 ${trimmed.length} 条消息]`;
+  const context = trimmed.map((message) => `${message.sender_id}: ${message.content}`).join("\n");
+  return `${note}\n${context}\n\n[你被 @mention 了，请回复]\n`;
+}
+
+function filterHistory(params: {
+  messages: ChatMessage[];
+  currentMessage: ChatMessage;
+  threadId?: string | number;
+}) {
+  return params.messages.filter((message) => {
+    if (message.id === params.currentMessage.id) return false;
+    if (message.content === "__typing__") return false;
+
+    if (params.threadId !== undefined) {
+      const threadId = getThreadId(message);
+      if (threadId !== undefined && String(threadId) !== String(params.threadId)) return false;
+    }
+
+    return true;
+  });
+}
+
+export async function buildInboundPolicy(params: {
+  account: AgentChatResolvedAccount;
+  accountId: string;
+  message: ChatMessage;
+  log?: (level: "warn" | "error" | "debug", message: string, meta?: Record<string, unknown>) => void;
+}): Promise<AgentChatInboundPolicyResult> {
+  const { account, accountId, message } = params;
+  const rawBody = message.content ?? "";
+  const threadId = getThreadId(message);
+  const conversationId = buildConversationId(message.channel_id, threadId);
+  const isDirect = isDirectChannel(message.channel_id);
+
+  if (!isDirect && !isMentioned(rawBody, account)) {
+    return {
+      shouldDispatch: false,
+      bodyForAgent: rawBody,
+      rawBody,
+      commandBody: rawBody,
+    };
+  }
+
+  if (isDirect) {
+    return {
+      shouldDispatch: true,
+      bodyForAgent: rawBody,
+      rawBody,
+      commandBody: rawBody,
+    };
+  }
+
+  const lastMentionTs = getMentionCursor(accountId, conversationId);
+  let prefix = "";
+
+  try {
+    const history = await fetchChannelHistory({
+      wsUrl: account.wsUrl,
+      token: account.token,
+      channelId: message.channel_id,
+      after: lastMentionTs,
+    });
+    const filtered = filterHistory({ messages: history, currentMessage: message, threadId });
+    prefix = buildContextPrefix(filtered);
+  } catch (error) {
+    params.log?.("warn", "AgentChat history fetch failed; falling back to single-message dispatch", {
+      accountId,
+      channelId: message.channel_id,
+      messageId: message.id,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  setMentionCursor(accountId, conversationId, message.timestamp);
+  return {
+    shouldDispatch: true,
+    bodyForAgent: prefix ? `${prefix}${message.sender_id}: ${rawBody}` : rawBody,
+    rawBody,
+    commandBody: rawBody,
+  };
+}

package/src/state.ts

@@ -0,0 +1,39 @@
+import { AgentChatClient } from "./agentchat-client";
+
+import type { AgentChatGatewayState, AgentChatResolvedAccount } from "./types";
+
+const gatewayStates = new Map<string, AgentChatGatewayState>();
+const mentionCursors = new Map<string, string>();
+
+function mentionCursorKey(accountId: string, conversationId: string) {
+  return `${accountId}:${conversationId}`;
+}
+
+export function getGatewayState(accountId: string) {
+  return gatewayStates.get(accountId);
+}
+
+export function setGatewayState(accountId: string, state: AgentChatGatewayState) {
+  gatewayStates.set(accountId, state);
+}
+
+export function deleteGatewayState(accountId: string) {
+  gatewayStates.delete(accountId);
+}
+
+export function getMentionCursor(accountId: string, conversationId: string) {
+  return mentionCursors.get(mentionCursorKey(accountId, conversationId));
+}
+
+export function setMentionCursor(accountId: string, conversationId: string, timestamp: string) {
+  mentionCursors.set(mentionCursorKey(accountId, conversationId), timestamp);
+}
+
+export function createGatewayClient(account: AgentChatResolvedAccount) {
+  return new AgentChatClient({
+    url: account.wsUrl,
+    agentId: account.agentId ?? account.accountId,
+    token: account.token,
+    capabilities: ["chat"],
+  });
+}

package/src/types.ts

@@ -0,0 +1,47 @@
+import type { AgentChatClient } from "./agentchat-client";
+
+export const CHANNEL_ID = "agentchat" as const;
+export const DEFAULT_WS_URL =
+  "wss://agentchat-server-679286795813.us-central1.run.app/ws";
+
+export interface AgentChatAccountConfig {
+  name?: string;
+  agentId?: string;
+  token?: string;
+  wsUrl?: string;
+  defaultChannelId?: string;
+  enabled?: boolean;
+}
+
+export interface AgentChatChannelConfig {
+  defaultAccountId?: string;
+  accounts?: Record<string, AgentChatAccountConfig>;
+}
+
+export interface AgentChatPluginConfigRoot {
+  channels?: {
+    agentchat?: AgentChatChannelConfig;
+  };
+}
+
+export interface AgentChatResolvedAccount {
+  accountId: string;
+  name?: string;
+  agentId?: string;
+  token?: string;
+  wsUrl: string;
+  defaultChannelId?: string;
+  enabled: boolean;
+}
+
+export interface AgentChatGatewayState {
+  client: AgentChatClient;
+  abortHandler: () => void;
+}
+
+export interface AgentChatInboundPolicyResult {
+  shouldDispatch: boolean;
+  bodyForAgent: string;
+  rawBody: string;
+  commandBody: string;
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "lib": ["ESNext", "DOM"],
+    "types": ["node"]
+  },
+  "include": ["index.ts", "src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}