@coffeexdev/xmtp 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 coffeebot-agent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @coffeexdev/xmtp
+
+XMTP channel plugin for [OpenClaw](https://github.com/open-claw/openclaw) — adds E2E encrypted wallet-to-wallet messaging via the [XMTP protocol](https://xmtp.org/).
+
+## Features
+
+- **Direct Messages** — Wallet-to-wallet E2E encrypted DMs over XMTP
+- **Pairing Flow** — Policy-aware consent with pairing codes for new senders
+- **Reply Threading** — Native XMTP reply threading support (reference IDs)
+- **DM Policies** — Configurable policies: `open`, `pairing`, `allowlist`, `disabled`
+- **Allowlist** — Restrict access to specific Ethereum addresses
+- **Activity Tracking** — Inbound/outbound message activity recording
+- **Markdown Tables** — Automatic markdown table conversion for XMTP clients
+
+## Installation
+
+```bash
+openclaw plugins install @coffeexdev/xmtp
+```
+
+Or install manually via npm:
+
+```bash
+npm install @coffeexdev/xmtp
+```
+
+## Configuration
+
+Add XMTP channel configuration to your OpenClaw config (`openclaw.yaml` or equivalent):
+
+```yaml
+channels:
+  xmtp:
+    # Required: XMTP wallet private key (0x-prefixed hex)
+    walletKey: "0x..."
+    # Or use a file:
+    # walletKeyFile: "/path/to/wallet-key"
+
+    # Required: Database encryption key (hex string)
+    dbEncryptionKey: "0x..."
+    # Or use a file:
+    # dbEncryptionKeyFile: "/path/to/db-encryption-key"
+
+    # XMTP network environment (default: production)
+    env: production # or: dev, local
+
+    # DM policy (default: pairing)
+    dmPolicy: pairing # or: open, allowlist, disabled
+
+    # Allowlist of Ethereum addresses (used with allowlist/pairing policies)
+    allowFrom:
+      - "0x1234567890abcdef1234567890abcdef12345678"
+
+    # Custom database path (optional)
+    # dbPath: "~/.openclaw/state/channels/xmtp/production"
+```
+
+### Environment Variables
+
+As an alternative to config file values, you can set:
+
+- `XMTP_WALLET_KEY` — Wallet private key
+- `XMTP_DB_ENCRYPTION_KEY` — Database encryption key
+
+## DM Policies
+
+| Policy      | Behavior                                                                            |
+| ----------- | ----------------------------------------------------------------------------------- |
+| `open`      | Accept DMs from anyone                                                              |
+| `pairing`   | New senders receive a pairing code; approve via `openclaw pair approve xmtp <code>` |
+| `allowlist` | Only accept DMs from addresses in `allowFrom` or approved via pairing               |
+| `disabled`  | Drop all inbound DMs                                                                |
+
+## Links
+
+- [XMTP Documentation](https://docs.xmtp.org/)
+- [XMTP Agent SDK](https://github.com/nicobianchetti/xmtp-agent-sdk)
+- [OpenClaw](https://github.com/open-claw/openclaw)
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { xmtpPlugin } from "./src/channel.js";
+import { setXmtpRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "xmtp",
+  name: "XMTP",
+  description: "XMTP E2E encrypted messaging channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setXmtpRuntime(api.runtime);
+    api.registerChannel({ plugin: xmtpPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,12 @@
+{
+  "id": "xmtp",
+  "channels": ["xmtp"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  },
+  "install": {
+    "npmSpec": "@coffeexdev/xmtp"
+  }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@coffeexdev/xmtp",
+  "version": "0.0.2",
+  "description": "OpenClaw XMTP channel plugin for E2E encrypted wallet-to-wallet messaging",
+  "keywords": [
+    "channel",
+    "e2e",
+    "encrypted",
+    "ethereum",
+    "messaging",
+    "openclaw",
+    "plugin",
+    "wallet",
+    "xmtp"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/coffeexcoin/openclaw-xmtp.git"
+  },
+  "files": [
+    "index.ts",
+    "src/*.ts",
+    "!src/*.test.ts",
+    "openclaw.plugin.json"
+  ],
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "format": "oxfmt --write",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint",
+    "check": "npm run format:check && npm run lint",
+    "prepare": "git rev-parse --is-inside-work-tree >/dev/null 2>&1 && git config core.hooksPath git-hooks || exit 0"
+  },
+  "dependencies": {
+    "@xmtp/agent-sdk": "^2.2.0",
+    "viem": "^2.23.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "openclaw": "latest",
+    "oxfmt": "0.32.0",
+    "oxlint": "^1.47.0",
+    "vitest": "^3.1.1"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.2.15"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "xmtp",
+      "label": "XMTP",
+      "selectionLabel": "XMTP (E2E Encrypted DMs)",
+      "docsPath": "/channels/xmtp",
+      "docsLabel": "xmtp",
+      "blurb": "E2E encrypted messaging via XMTP protocol; wallet-to-wallet.",
+      "order": 101,
+      "quickstartAllowFrom": true
+    },
+    "install": {
+      "npmSpec": "@coffeexdev/xmtp",
+      "localPath": "extensions/xmtp",
+      "defaultChoice": "npm"
+    }
+  }
+}

package/src/channel.ts

@@ -0,0 +1,520 @@
+import {
+  buildChannelConfigSchema,
+  collectStatusIssuesFromLastError,
+  createDefaultChannelRuntimeState,
+  createReplyPrefixOptions,
+  DEFAULT_ACCOUNT_ID,
+  formatAllowlistMatchMeta,
+  formatPairingApproveHint,
+  PAIRING_APPROVED_MESSAGE,
+  resolveAllowlistMatchSimple,
+  resolveControlCommandGate,
+  type ChannelPlugin,
+  type OpenClawConfig,
+  type ReplyPayload,
+} from "openclaw/plugin-sdk";
+import { XmtpConfigSchema } from "./config-schema.js";
+import { getXmtpRuntime } from "./runtime.js";
+import {
+  listXmtpAccountIds,
+  resolveDefaultXmtpAccountId,
+  resolveXmtpAccount,
+  type ResolvedXmtpAccount,
+} from "./types.js";
+import { normalizeEthAddress, startXmtpBus, type XmtpBusHandle } from "./xmtp-bus.js";
+
+const activeBuses = new Map<string, XmtpBusHandle>();
+
+function normalizeAllowEntry(entry: string): string {
+  const trimmed = entry.trim();
+  if (!trimmed) {
+    return "";
+  }
+  if (trimmed === "*") {
+    return "*";
+  }
+  try {
+    return normalizeEthAddress(trimmed);
+  } catch {
+    return trimmed.toLowerCase();
+  }
+}
+
+function normalizeAllowEntries(entries: Array<string | number>): string[] {
+  return entries
+    .map((entry) => normalizeAllowEntry(String(entry)))
+    .filter((entry) => entry.length > 0);
+}
+
+function previewText(text: string, limit = 200): string {
+  return text.slice(0, limit).replace(/\n/g, "\\n");
+}
+
+export const xmtpPlugin: ChannelPlugin<ResolvedXmtpAccount> = {
+  id: "xmtp",
+  meta: {
+    id: "xmtp",
+    label: "XMTP",
+    selectionLabel: "XMTP",
+    docsPath: "/channels/xmtp",
+    docsLabel: "xmtp",
+    blurb: "E2E encrypted messaging via XMTP (wallet-to-wallet)",
+    order: 101,
+  },
+  capabilities: {
+    chatTypes: ["direct"],
+    media: false,
+    reply: true,
+  },
+  reload: { configPrefixes: ["channels.xmtp"] },
+  configSchema: buildChannelConfigSchema(XmtpConfigSchema),
+
+  config: {
+    listAccountIds: (cfg) => listXmtpAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveXmtpAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultXmtpAccountId(cfg),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      credentialSource: account.walletKeySource,
+      secretSource: account.dbEncryptionKeySource,
+      dmPolicy: account.config.dmPolicy,
+      allowFrom: account.config.allowFrom,
+      dbPath: account.config.dbPath ?? null,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      resolveXmtpAccount({ cfg, accountId }).config.allowFrom ?? [],
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => {
+          if (entry === "*") return "*";
+          try {
+            return normalizeEthAddress(entry);
+          } catch {
+            return entry;
+          }
+        })
+        .filter(Boolean),
+  },
+
+  pairing: {
+    idLabel: "ethAddress",
+    normalizeAllowEntry: (entry) => {
+      try {
+        return normalizeEthAddress(entry);
+      } catch {
+        return entry;
+      }
+    },
+    notifyApproval: async ({ id, cfg }) => {
+      const effectiveAccountId = resolveDefaultXmtpAccountId(cfg);
+      const bus = activeBuses.get(effectiveAccountId);
+      if (!bus) {
+        throw new Error(`XMTP bus not running for account ${effectiveAccountId}`);
+      }
+      await bus.sendText(id, PAIRING_APPROVED_MESSAGE);
+      getXmtpRuntime().channel.activity.record({
+        channel: "xmtp",
+        accountId: effectiveAccountId,
+        direction: "outbound",
+      });
+    },
+  },
+
+  security: {
+    resolveDmPolicy: ({ account }) => ({
+      policy: account.config.dmPolicy ?? "pairing",
+      allowFrom: account.config.allowFrom ?? [],
+      policyPath: "channels.xmtp.dmPolicy",
+      allowFromPath: "channels.xmtp.allowFrom",
+      approveHint: formatPairingApproveHint("xmtp"),
+      normalizeEntry: (raw) => {
+        try {
+          return normalizeEthAddress(raw.trim());
+        } catch {
+          return raw.trim();
+        }
+      },
+    }),
+  },
+
+  messaging: {
+    normalizeTarget: (target) => {
+      const cleaned = target.trim().toLowerCase();
+      try {
+        return normalizeEthAddress(cleaned);
+      } catch {
+        return cleaned;
+      }
+    },
+    targetResolver: {
+      looksLikeId: (input) => {
+        const trimmed = input.trim();
+        return /^0x[0-9a-fA-F]{40}$/.test(trimmed);
+      },
+      hint: "<0x... Ethereum address>",
+    },
+  },
+
+  outbound: {
+    deliveryMode: "direct",
+    textChunkLimit: 4000,
+    sendText: async ({ to, text, accountId, replyToId }) => {
+      const core = getXmtpRuntime();
+      const aid = accountId ?? DEFAULT_ACCOUNT_ID;
+      const bus = activeBuses.get(aid);
+      if (!bus) {
+        throw new Error(`XMTP bus not running for account ${aid}`);
+      }
+      const tableMode = core.channel.text.resolveMarkdownTableMode({
+        cfg: core.config.loadConfig(),
+        channel: "xmtp",
+        accountId: aid,
+      });
+      const message = core.channel.text.convertMarkdownTables(text ?? "", tableMode);
+      const replyTarget = typeof replyToId === "string" ? replyToId.trim() : "";
+      if (replyTarget) {
+        await bus.sendReply(to, message, replyTarget);
+      } else {
+        await bus.sendText(to, message);
+      }
+      core.channel.activity.record({
+        channel: "xmtp",
+        accountId: aid,
+        direction: "outbound",
+      });
+      core.logging
+        .getChildLogger?.({ channel: "xmtp", accountId: aid })
+        ?.debug?.(
+          `xmtp outbound: to=${to} len=${message.length} preview="${previewText(message, 160)}"`,
+        );
+      return {
+        channel: "xmtp" as const,
+        to,
+        messageId: `xmtp-${Date.now()}`,
+      };
+    },
+  },
+
+  status: {
+    defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID),
+    collectStatusIssues: (accounts) => collectStatusIssuesFromLastError("xmtp", accounts),
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      credentialSource: snapshot.credentialSource ?? "none",
+      secretSource: snapshot.secretSource ?? "none",
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+    }),
+    buildAccountSnapshot: ({ account, runtime }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      credentialSource: account.walletKeySource,
+      secretSource: account.dbEncryptionKeySource,
+      dmPolicy: account.config.dmPolicy,
+      allowFrom: account.config.allowFrom,
+      dbPath: account.config.dbPath ?? null,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+  },
+
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      ctx.setStatus({
+        accountId: account.accountId,
+        credentialSource: account.walletKeySource,
+        secretSource: account.dbEncryptionKeySource,
+        dmPolicy: account.config.dmPolicy,
+        allowFrom: account.config.allowFrom,
+        dbPath: account.config.dbPath ?? null,
+      });
+      ctx.log?.info(
+        `[${account.accountId}] starting XMTP provider (address: ${account.address}, env: ${account.env})`,
+      );
+
+      if (!account.configured) {
+        throw new Error("XMTP walletKey and dbEncryptionKey not configured");
+      }
+
+      const runtime = getXmtpRuntime();
+
+      const bus = await startXmtpBus({
+        accountId: account.accountId,
+        walletKey: account.walletKey,
+        dbEncryptionKey: account.dbEncryptionKey,
+        env: account.env,
+        dbPath: account.config.dbPath,
+        shouldConsentDm: (senderAddress: string) => {
+          const cfg = runtime.config.loadConfig() as OpenClawConfig;
+          const freshAccount = resolveXmtpAccount({
+            cfg,
+            accountId: account.accountId,
+          });
+          const policy = freshAccount.config.dmPolicy ?? "pairing";
+          if (policy === "disabled") return false;
+          if (policy === "open" || policy === "pairing") return true;
+          // allowlist: only consent if sender is in the effective allowlist
+          const configuredAllow = normalizeAllowEntries(freshAccount.config.allowFrom ?? []);
+          return configuredAllow.includes(senderAddress) || configuredAllow.includes("*");
+        },
+        onMessage: async ({
+          senderAddress,
+          senderInboxId,
+          conversationId,
+          text,
+          messageId,
+          replyContext,
+        }) => {
+          const cfg = runtime.config.loadConfig() as OpenClawConfig;
+
+          const rawBody = text.trim();
+          if (!rawBody) {
+            return;
+          }
+
+          runtime.channel.activity.record({
+            channel: "xmtp",
+            accountId: account.accountId,
+            direction: "inbound",
+          });
+
+          const freshAccount = resolveXmtpAccount({
+            cfg,
+            accountId: account.accountId,
+          });
+          const dmPolicy = freshAccount.config.dmPolicy ?? "pairing";
+          const configuredAllowFrom = normalizeAllowEntries(freshAccount.config.allowFrom ?? []);
+          const storeAllowFrom = normalizeAllowEntries(
+            await runtime.channel.pairing
+              .readAllowFromStore("xmtp", process.env, account.accountId)
+              .catch((error) => {
+                ctx.log?.warn?.(
+                  `[${account.accountId}] Failed to read pairing store: ${String(error)}`,
+                );
+                return [];
+              }),
+          );
+          const effectiveAllowFrom = [...configuredAllowFrom, ...storeAllowFrom];
+          const allowMatch = resolveAllowlistMatchSimple({
+            allowFrom: effectiveAllowFrom,
+            senderId: senderAddress,
+          });
+          const allowMatchMeta = formatAllowlistMatchMeta(allowMatch);
+
+          if (dmPolicy === "disabled") {
+            ctx.log?.debug?.(`[${account.accountId}] blocked xmtp DM ${senderAddress} (disabled)`);
+            return;
+          }
+
+          if (dmPolicy !== "open" && !allowMatch.allowed) {
+            if (dmPolicy === "pairing") {
+              try {
+                const { code, created } = await runtime.channel.pairing.upsertPairingRequest({
+                  channel: "xmtp",
+                  id: senderAddress,
+                  accountId: account.accountId,
+                  meta: {
+                    inboxId: senderInboxId,
+                  },
+                });
+                if (created) {
+                  ctx.log?.info?.(
+                    `[${account.accountId}] xmtp pairing request from ${senderAddress} (${allowMatchMeta})`,
+                  );
+                  const reply = runtime.channel.pairing.buildPairingReply({
+                    channel: "xmtp",
+                    idLine: `Your XMTP address: ${senderAddress}`,
+                    code,
+                  });
+                  await bus.sendText(conversationId, reply);
+                  runtime.channel.activity.record({
+                    channel: "xmtp",
+                    accountId: account.accountId,
+                    direction: "outbound",
+                  });
+                  ctx.log?.debug?.(
+                    `[${account.accountId}] xmtp pairing reply to=${conversationId} len=${reply.length}`,
+                  );
+                }
+              } catch (err) {
+                ctx.log?.error?.(
+                  `[${account.accountId}] xmtp pairing reply failed for ${senderAddress}: ${String(err)}`,
+                );
+              }
+            } else {
+              ctx.log?.debug?.(
+                `[${account.accountId}] blocked unauthorized xmtp sender ${senderAddress} (dmPolicy=${dmPolicy}, ${allowMatchMeta})`,
+              );
+            }
+            return;
+          }
+
+          const allowTextCommands = runtime.channel.commands.shouldHandleTextCommands({
+            cfg,
+            surface: "xmtp",
+          });
+          const hasControlCommand = runtime.channel.commands.isControlCommandMessage(rawBody, cfg);
+          const commandGate = resolveControlCommandGate({
+            useAccessGroups: cfg.commands?.useAccessGroups !== false,
+            authorizers: [
+              {
+                configured: effectiveAllowFrom.length > 0,
+                allowed: allowMatch.allowed,
+              },
+            ],
+            allowTextCommands,
+            hasControlCommand,
+          });
+
+          if (commandGate.shouldBlock) {
+            ctx.log?.debug?.(
+              `[${account.accountId}] blocked xmtp control command from ${senderAddress} (${allowMatchMeta})`,
+            );
+            return;
+          }
+
+          const route = runtime.channel.routing.resolveAgentRoute({
+            cfg,
+            channel: "xmtp",
+            accountId: account.accountId,
+            peer: { kind: "direct", id: senderAddress },
+          });
+
+          const envelopeOptions = runtime.channel.reply.resolveEnvelopeFormatOptions(cfg);
+          const body = runtime.channel.reply.formatAgentEnvelope({
+            channel: "XMTP",
+            from: senderAddress,
+            envelope: envelopeOptions,
+            body: rawBody,
+          });
+
+          const ctxPayload = runtime.channel.reply.finalizeInboundContext({
+            Body: body,
+            BodyForAgent: rawBody,
+            RawBody: rawBody,
+            CommandBody: rawBody,
+            From: `xmtp:${senderAddress}`,
+            To: `xmtp:${account.address}`,
+            SessionKey: route.sessionKey,
+            AccountId: route.accountId,
+            ChatType: "direct" as const,
+            ConversationLabel: senderAddress,
+            SenderName: senderAddress,
+            SenderId: senderAddress,
+            Provider: "xmtp",
+            Surface: "xmtp",
+            MessageSid: messageId,
+            MessageSidFull: messageId,
+            ReplyToId: replyContext?.referenceId,
+            ReplyToIdFull: replyContext?.referenceId,
+            ReplyToBody: replyContext?.referencedText,
+            OriginatingChannel: "xmtp",
+            OriginatingTo: `xmtp:${account.address}`,
+            CommandAuthorized: commandGate.commandAuthorized,
+          });
+
+          ctx.log?.debug?.(
+            `[${account.accountId}] xmtp inbound: sender=${senderAddress} sid=${messageId} len=${rawBody.length} ${allowMatchMeta} preview="${previewText(rawBody)}"`,
+          );
+
+          const storePath = runtime.channel.session.resolveStorePath(cfg.session?.store, {
+            agentId: route.agentId,
+          });
+          await runtime.channel.session.recordInboundSession({
+            storePath,
+            sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+            ctx: ctxPayload,
+            onRecordError: (err) => {
+              ctx.log?.error?.(`[${account.accountId}] session record failed: ${String(err)}`);
+            },
+          });
+
+          const tableMode = runtime.channel.text.resolveMarkdownTableMode({
+            cfg,
+            channel: "xmtp",
+            accountId: account.accountId,
+          });
+
+          const { onModelSelected, ...prefixOptions } = createReplyPrefixOptions({
+            cfg,
+            agentId: route.agentId,
+            channel: "xmtp",
+            accountId: account.accountId,
+          });
+
+          await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+            ctx: ctxPayload,
+            cfg,
+            dispatcherOptions: {
+              ...prefixOptions,
+              deliver: async (payload: ReplyPayload) => {
+                const message = runtime.channel.text.convertMarkdownTables(
+                  payload.text ?? "",
+                  tableMode,
+                );
+                if (message) {
+                  const replyTarget =
+                    typeof payload.replyToId === "string" ? payload.replyToId.trim() : "";
+                  if (replyTarget) {
+                    await bus.sendReply(conversationId, message, replyTarget);
+                  } else {
+                    await bus.sendText(conversationId, message);
+                  }
+                  runtime.channel.activity.record({
+                    channel: "xmtp",
+                    accountId: account.accountId,
+                    direction: "outbound",
+                  });
+                  ctx.log?.debug?.(
+                    `[${account.accountId}] xmtp outbound: to=${conversationId} len=${message.length} preview="${previewText(message, 160)}"`,
+                  );
+                }
+              },
+              onError: (err, info) => {
+                ctx.log?.error?.(
+                  `[${account.accountId}] xmtp ${info.kind} reply failed: ${String(err)}`,
+                );
+              },
+            },
+            replyOptions: {
+              onModelSelected,
+            },
+          });
+        },
+        onError: (error, context) => {
+          ctx.log?.error?.(`[${account.accountId}] XMTP error (${context}): ${error.message}`);
+        },
+        onConnect: () => {
+          ctx.log?.info?.(`[${account.accountId}] XMTP agent connected (env: ${account.env})`);
+        },
+      });
+
+      activeBuses.set(account.accountId, bus);
+
+      ctx.log?.info(`[${account.accountId}] XMTP provider started (address: ${bus.getAddress()})`);
+
+      return {
+        stop: async () => {
+          await bus.close();
+          activeBuses.delete(account.accountId);
+          ctx.log?.info(`[${account.accountId}] XMTP provider stopped`);
+        },
+      };
+    },
+  },
+};

package/src/config-schema.ts

@@ -0,0 +1,23 @@
+import { MarkdownConfigSchema, buildChannelConfigSchema } from "openclaw/plugin-sdk";
+import { z } from "zod";
+
+export const XmtpConfigSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  markdown: MarkdownConfigSchema,
+
+  walletKey: z.string().optional(),
+  walletKeyFile: z.string().optional(),
+  dbEncryptionKey: z.string().optional(),
+  dbEncryptionKeyFile: z.string().optional(),
+
+  env: z.enum(["local", "dev", "production"]).optional(),
+  dbPath: z.string().optional(),
+
+  dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
+  allowFrom: z.array(z.string()).optional(),
+});
+
+export type XmtpConfig = z.infer<typeof XmtpConfigSchema>;
+
+export const xmtpChannelConfigSchema = buildChannelConfigSchema(XmtpConfigSchema);

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setXmtpRuntime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+export function getXmtpRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("XMTP runtime not initialized");
+  }
+  return runtime;
+}

package/src/types.ts

@@ -0,0 +1,180 @@
+import { readFileSync } from "node:fs";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { privateKeyToAccount } from "viem/accounts";
+
+export interface XmtpAccountConfig {
+  enabled?: boolean;
+  name?: string;
+  walletKey?: string;
+  walletKeyFile?: string;
+  dbEncryptionKey?: string;
+  dbEncryptionKeyFile?: string;
+  env?: "local" | "dev" | "production";
+  dbPath?: string;
+  dmPolicy?: "pairing" | "allowlist" | "open" | "disabled";
+  allowFrom?: string[];
+}
+
+export type XmtpSecretSource = "env" | "secretFile" | "config" | "none";
+
+export interface ResolvedXmtpAccount {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  configured: boolean;
+  walletKey: string;
+  walletKeySource: XmtpSecretSource;
+  dbEncryptionKey: string;
+  dbEncryptionKeySource: XmtpSecretSource;
+  address: string;
+  env: "local" | "dev" | "production";
+  config: XmtpAccountConfig;
+}
+
+const DEFAULT_ACCOUNT_ID = "default";
+const DEFAULT_ENV = "production" as const;
+
+function deriveAddressFromKey(walletKey: string): string {
+  try {
+    const account = privateKeyToAccount(walletKey as `0x${string}`);
+    return account.address.toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+export function listXmtpAccountIds(cfg: OpenClawConfig): string[] {
+  const xmtpCfg = (cfg.channels as Record<string, unknown> | undefined)?.xmtp as
+    | XmtpAccountConfig
+    | undefined;
+
+  const hasConfig =
+    Boolean(xmtpCfg?.walletKey?.trim()) ||
+    Boolean(xmtpCfg?.walletKeyFile?.trim()) ||
+    Boolean(xmtpCfg?.dbEncryptionKey?.trim()) ||
+    Boolean(xmtpCfg?.dbEncryptionKeyFile?.trim());
+  const hasEnv =
+    Boolean(process.env.XMTP_WALLET_KEY?.trim()) ||
+    Boolean(process.env.XMTP_DB_ENCRYPTION_KEY?.trim());
+
+  if (hasConfig || hasEnv) {
+    return [DEFAULT_ACCOUNT_ID];
+  }
+
+  return [];
+}
+
+export function resolveDefaultXmtpAccountId(cfg: OpenClawConfig): string {
+  const ids = listXmtpAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) {
+    return DEFAULT_ACCOUNT_ID;
+  }
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+export function resolveXmtpAccount(opts: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): ResolvedXmtpAccount {
+  const accountId = opts.accountId ?? DEFAULT_ACCOUNT_ID;
+  const xmtpCfg = (opts.cfg.channels as Record<string, unknown> | undefined)?.xmtp as
+    | XmtpAccountConfig
+    | undefined;
+
+  const baseEnabled = xmtpCfg?.enabled !== false;
+  const walletKeyResolution = resolveWalletKey(accountId, xmtpCfg);
+  const dbEncryptionKeyResolution = resolveDbEncryptionKey(accountId, xmtpCfg);
+  const configured = Boolean(walletKeyResolution.secret && dbEncryptionKeyResolution.secret);
+
+  let address = "";
+  if (configured) {
+    address = deriveAddressFromKey(walletKeyResolution.secret);
+  }
+
+  return {
+    accountId,
+    name: xmtpCfg?.name?.trim() || undefined,
+    enabled: baseEnabled,
+    configured,
+    walletKey: walletKeyResolution.secret,
+    walletKeySource: walletKeyResolution.source,
+    dbEncryptionKey: dbEncryptionKeyResolution.secret,
+    dbEncryptionKeySource: dbEncryptionKeyResolution.source,
+    address,
+    env: xmtpCfg?.env ?? DEFAULT_ENV,
+    config: {
+      enabled: xmtpCfg?.enabled,
+      name: xmtpCfg?.name,
+      walletKey: xmtpCfg?.walletKey,
+      walletKeyFile: xmtpCfg?.walletKeyFile,
+      dbEncryptionKey: xmtpCfg?.dbEncryptionKey,
+      dbEncryptionKeyFile: xmtpCfg?.dbEncryptionKeyFile,
+      env: xmtpCfg?.env,
+      dbPath: xmtpCfg?.dbPath,
+      dmPolicy: xmtpCfg?.dmPolicy,
+      allowFrom: xmtpCfg?.allowFrom,
+    },
+  };
+}
+
+function resolveWalletKey(
+  accountId: string,
+  cfg?: XmtpAccountConfig,
+): { secret: string; source: XmtpSecretSource } {
+  const walletKeyFile = cfg?.walletKeyFile?.trim();
+  if (walletKeyFile) {
+    try {
+      const secret = readFileSync(walletKeyFile, "utf-8").trim();
+      if (secret) {
+        return { secret, source: "secretFile" };
+      }
+    } catch {
+      return { secret: "", source: "none" };
+    }
+  }
+
+  const configKey = cfg?.walletKey?.trim();
+  if (configKey) {
+    return { secret: configKey, source: "config" };
+  }
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    const envKey = process.env.XMTP_WALLET_KEY?.trim();
+    if (envKey) {
+      return { secret: envKey, source: "env" };
+    }
+  }
+
+  return { secret: "", source: "none" };
+}
+
+function resolveDbEncryptionKey(
+  accountId: string,
+  cfg?: XmtpAccountConfig,
+): { secret: string; source: XmtpSecretSource } {
+  const secretFile = cfg?.dbEncryptionKeyFile?.trim();
+  if (secretFile) {
+    try {
+      const secret = readFileSync(secretFile, "utf-8").trim();
+      if (secret) {
+        return { secret, source: "secretFile" };
+      }
+    } catch {
+      return { secret: "", source: "none" };
+    }
+  }
+
+  const configKey = cfg?.dbEncryptionKey?.trim();
+  if (configKey) {
+    return { secret: configKey, source: "config" };
+  }
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    const envKey = process.env.XMTP_DB_ENCRYPTION_KEY?.trim();
+    if (envKey) {
+      return { secret: envKey, source: "env" };
+    }
+  }
+
+  return { secret: "", source: "none" };
+}

package/src/xmtp-bus.ts

@@ -0,0 +1,319 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Agent, createSigner, createUser } from "@xmtp/agent-sdk";
+import { getXmtpRuntime } from "./runtime.js";
+
+export type XmtpReplyContext = {
+  referenceId: string;
+  referencedText?: string;
+};
+
+export interface XmtpBusOptions {
+  accountId?: string;
+  walletKey: string;
+  dbEncryptionKey: string;
+  env: "local" | "dev" | "production";
+  dbPath?: string;
+  // Default to auto-consenting DMs so pairing flows can proceed.
+  shouldConsentDm: (senderAddress: string) => boolean;
+  onMessage: (params: {
+    senderAddress: string;
+    senderInboxId: string;
+    conversationId: string;
+    isDm: boolean;
+    text: string;
+    messageId: string;
+    replyContext?: XmtpReplyContext;
+  }) => Promise<void>;
+  onError?: (error: Error, context: string) => void;
+  onConnect?: () => void;
+}
+
+export interface XmtpBusHandle {
+  sendText(target: string, text: string): Promise<void>;
+  sendReply(target: string, text: string, referenceMessageId: string): Promise<void>;
+  getAddress(): string;
+  close(): Promise<void>;
+}
+
+type XmtpConversationHandle = {
+  sendText: (text: string) => Promise<unknown>;
+  sendReply?: (reply: unknown) => Promise<unknown>;
+};
+
+type XmtpAgentHandle = Awaited<ReturnType<typeof Agent.create>>;
+
+type XmtpInboundMessageContext = {
+  getSenderAddress: () => Promise<string | null>;
+  message: {
+    senderInboxId: string;
+    content: unknown;
+    id: string;
+  };
+  conversation: {
+    id: string;
+  };
+  isDm: () => boolean;
+};
+
+function looksLikeEthAddress(value: string): boolean {
+  return /^0x[0-9a-fA-F]{40}$/.test(value.trim());
+}
+
+async function resolveConversationForTarget(
+  agent: XmtpAgentHandle,
+  target: string,
+): Promise<XmtpConversationHandle> {
+  const trimmedTarget = target.trim();
+  if (!trimmedTarget) {
+    throw new Error("Target is required");
+  }
+
+  if (looksLikeEthAddress(trimmedTarget)) {
+    const normalizedAddress = normalizeEthAddress(trimmedTarget);
+    const agentWithAddressDm = agent as XmtpAgentHandle & {
+      createDmWithAddress?: (address: string) => Promise<XmtpConversationHandle | null>;
+    };
+    if (typeof agentWithAddressDm.createDmWithAddress === "function") {
+      const dmConversation = await agentWithAddressDm.createDmWithAddress(normalizedAddress);
+      if (dmConversation) {
+        return dmConversation;
+      }
+      throw new Error(`Conversation not found for address: ${normalizedAddress}`);
+    }
+
+    const conversationsWithAddressDm = agent.client.conversations as {
+      createDmWithAddress?: (address: string) => Promise<XmtpConversationHandle | null>;
+    };
+    if (typeof conversationsWithAddressDm.createDmWithAddress === "function") {
+      const dmConversation =
+        await conversationsWithAddressDm.createDmWithAddress(normalizedAddress);
+      if (dmConversation) {
+        return dmConversation;
+      }
+      throw new Error(`Conversation not found for address: ${normalizedAddress}`);
+    }
+
+    throw new Error("XMTP SDK does not support address-based DM creation");
+  }
+
+  const conversation = await agent.client.conversations.getConversationById(trimmedTarget);
+  if (!conversation) {
+    throw new Error(`Conversation not found: ${trimmedTarget}`);
+  }
+  return conversation as XmtpConversationHandle;
+}
+
+function resolveDbDirectory(env: string, configDbPath?: string): string {
+  if (configDbPath) {
+    const resolved = configDbPath.replace(/^~/, os.homedir());
+    fs.mkdirSync(resolved, { recursive: true, mode: 0o700 });
+    return resolved;
+  }
+
+  const runtime = getXmtpRuntime();
+  const stateDir = runtime.state.resolveStateDir(process.env, os.homedir);
+  const dbDir = path.join(stateDir, "channels", "xmtp", env);
+  fs.mkdirSync(dbDir, { recursive: true, mode: 0o700 });
+  return dbDir;
+}
+
+function extractTextFromMessageContent(content: unknown): string | undefined {
+  if (typeof content === "string") {
+    return content;
+  }
+  if (content && typeof content === "object") {
+    const nestedContent = (content as { content?: unknown }).content;
+    if (typeof nestedContent === "string") {
+      return nestedContent;
+    }
+  }
+  return undefined;
+}
+
+function extractReplyContext(content: unknown): XmtpReplyContext | undefined {
+  if (!content || typeof content !== "object") {
+    return undefined;
+  }
+
+  const referenceIdRaw = (content as { referenceId?: unknown }).referenceId;
+  if (typeof referenceIdRaw !== "string" || !referenceIdRaw.trim()) {
+    return undefined;
+  }
+
+  const inReplyTo = (content as { inReplyTo?: unknown }).inReplyTo;
+  const referencedText = extractTextFromMessageContent(inReplyTo);
+
+  return {
+    referenceId: referenceIdRaw,
+    ...(referencedText ? { referencedText } : {}),
+  };
+}
+
+export async function startXmtpBus(options: XmtpBusOptions): Promise<XmtpBusHandle> {
+  const {
+    walletKey,
+    dbEncryptionKey,
+    env,
+    dbPath: configDbPath,
+    shouldConsentDm = () => true,
+    onMessage,
+    onError,
+    onConnect,
+  } = options;
+
+  const dbDir = resolveDbDirectory(env, configDbPath);
+  const user = createUser(walletKey as `0x${string}`);
+  const signer = createSigner(user);
+
+  const normalizedEncryptionKey = dbEncryptionKey.startsWith("0x")
+    ? dbEncryptionKey
+    : `0x${dbEncryptionKey}`;
+
+  const agent = await Agent.create(signer, {
+    env,
+    dbEncryptionKey: normalizedEncryptionKey as `0x${string}`,
+    dbPath: (inboxId: string) => path.join(dbDir, `xmtp-${inboxId}.db3`),
+  });
+
+  const agentAddress = agent.address ?? user.account.address.toLowerCase();
+
+  agent.on("conversation", async (ctx) => {
+    try {
+      if (ctx.isDm()) {
+        const senderAddress = await (
+          ctx as { getSenderAddress?: () => Promise<string | null> }
+        ).getSenderAddress?.();
+        type ConsentState = Parameters<NonNullable<typeof ctx.conversation.updateConsentState>>[0];
+        const conversation = ctx.conversation as unknown as {
+          updateConsentState: (state: ConsentState) => void;
+        };
+        if (!senderAddress) {
+          conversation.updateConsentState("allowed" as unknown as ConsentState);
+          return;
+        }
+        if (shouldConsentDm(senderAddress.toLowerCase())) {
+          conversation.updateConsentState("allowed" as unknown as ConsentState);
+        }
+      }
+    } catch (err) {
+      onError?.(err as Error, "auto-consent conversation");
+    }
+  });
+
+  agent.on("text", async (ctx) => {
+    try {
+      const typedCtx = ctx as XmtpInboundMessageContext;
+      const senderAddressRaw = await typedCtx.getSenderAddress();
+      if (!senderAddressRaw) {
+        throw new Error("XMTP message missing sender address");
+      }
+      const senderAddress = senderAddressRaw.toLowerCase();
+      const senderInboxId = typedCtx.message.senderInboxId;
+      const conversationId = typedCtx.conversation.id;
+      const isDm = typedCtx.isDm();
+      const text = typedCtx.message.content as string;
+      const messageId = typedCtx.message.id;
+
+      if (!isDm) return;
+
+      await onMessage({
+        senderAddress,
+        senderInboxId,
+        conversationId,
+        isDm,
+        text,
+        messageId,
+      });
+    } catch (err) {
+      onError?.(err as Error, "handle text message");
+    }
+  });
+
+  (
+    agent as {
+      on: (event: string, handler: (ctx: unknown) => Promise<void>) => void;
+    }
+  ).on("reply", async (ctx) => {
+    try {
+      const typedCtx = ctx as XmtpInboundMessageContext;
+      const senderAddressRaw = await typedCtx.getSenderAddress();
+      if (!senderAddressRaw) {
+        throw new Error("XMTP message missing sender address");
+      }
+      const senderAddress = senderAddressRaw.toLowerCase();
+      const senderInboxId = typedCtx.message.senderInboxId;
+      const conversationId = typedCtx.conversation.id;
+      const isDm = typedCtx.isDm();
+      const messageId = typedCtx.message.id;
+      const replyContent = typedCtx.message.content;
+      const text = extractTextFromMessageContent(replyContent);
+
+      if (!isDm) return;
+      if (!text?.trim()) {
+        return;
+      }
+
+      await onMessage({
+        senderAddress,
+        senderInboxId,
+        conversationId,
+        isDm,
+        text,
+        messageId,
+        replyContext: extractReplyContext(replyContent),
+      });
+    } catch (err) {
+      onError?.(err as Error, "handle reply message");
+    }
+  });
+
+  agent.on("unhandledError", (error) => {
+    onError?.(error, "unhandled agent error");
+  });
+
+  await agent.start();
+  onConnect?.();
+
+  return {
+    async sendText(target: string, text: string): Promise<void> {
+      const conversation = await resolveConversationForTarget(agent, target);
+      await conversation.sendText(text);
+    },
+
+    async sendReply(target: string, text: string, referenceMessageId: string): Promise<void> {
+      const trimmedReferenceMessageId = referenceMessageId.trim();
+      if (!trimmedReferenceMessageId) {
+        throw new Error("referenceMessageId is required");
+      }
+
+      const conversation = await resolveConversationForTarget(agent, target);
+      if (typeof conversation.sendReply === "function") {
+        await conversation.sendReply({
+          content: text,
+          referenceId: trimmedReferenceMessageId,
+        });
+        return;
+      }
+
+      await conversation.sendText(text);
+    },
+
+    getAddress(): string {
+      return agentAddress;
+    },
+
+    async close(): Promise<void> {
+      await agent.stop();
+    },
+  };
+}
+
+export function normalizeEthAddress(input: string): string {
+  const trimmed = input.trim().toLowerCase();
+  if (!/^0x[0-9a-f]{40}$/.test(trimmed)) {
+    throw new Error("Invalid Ethereum address: must be 0x-prefixed 40 hex chars");
+  }
+  return trimmed;
+}