@open-ic/openchat_openclaw 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# openchat-openclaw
+
+An [OpenClaw](https://openclaw.ai) plugin that adds [OpenChat](https://oc.app) as a channel. Users interact with the AI agent by sending a `/prompt` command to a bot in OpenChat.
+
+## Prerequisites
+
+- OpenClaw gateway running and accessible from the internet (OpenChat needs to reach your `/bot_definition` and `/execute_command` endpoints)
+- `openssl` on your PATH (for key generation)
+- Node 22+
+
+## Installation
+
+```sh
+openclaw plugin install @open-ic/openchat_openclaw
+```
+
+## Setup
+
+### 1. Generate a bot identity
+
+```sh
+npx --package @open-ic/openchat_openclaw generate-key
+```
+
+This generates a secp256k1 private key, writes it to `~/.openclaw/openchat-bot.pem` (mode 600), and prints the corresponding Internet Computer principal. Save the principal — you'll need it when registering the bot on OpenChat.
+
+### 2. Supply required environment variables
+
+The plugin requires two env vars that must be set before starting the gateway. Add them to `~/.openclaw/.env` (or export them in your shell):
+
+```sh
+# OpenChat's ES256 public key — used to verify JWTs on incoming bot commands.
+# Obtain from: https://oc.app/api
+OC_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
+
+# User index canister ID — provided by OpenChat for your deployment.
+OC_USER_INDEX_CANISTER="<canister-id>"
+```
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `OC_PUBLIC_KEY` | Yes | — | OpenChat's ES256 public key for JWT verification |
+| `OC_USER_INDEX_CANISTER` | Yes | — | OpenChat user index canister ID |
+| `OC_PRIVATE_KEY` | See below | — | Bot private key PEM (alternative to config) |
+| `OC_IC_HOST` | No | `https://icp-api.io` | Internet Computer host (override for local replicas) |
+| `OC_STORAGE_INDEX_CANISTER` | No | `nbpzs-kqaaa-aaaar-qaaua-cai` | Storage index canister ID |
+
+### 3. Configure the private key
+
+The bot private key (from step 1) can be supplied in three ways, in priority order:
+
+**Option A — Key file (recommended):**
+
+The `generate-key` script writes the PEM to `~/.openclaw/openchat-bot.pem` and prints the exact command to run:
+
+```sh
+openclaw config set channels.openchat.privateKeyFile ~/.openclaw/openchat-bot.pem
+```
+
+**Option B — Env var:**
+
+```sh
+# In ~/.openclaw/.env or your shell:
+OC_PRIVATE_KEY="-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----"
+```
+
+**Option C — Inline config (not recommended for production):**
+
+```sh
+openclaw config set channels.openchat.privateKey "-----BEGIN EC PRIVATE KEY-----\n..."
+```
+
+### 4. Start the gateway
+
+```sh
+openclaw gateway run
+```
+
+### 5. Register the bot on OpenChat
+
+Once the gateway is running and reachable from the internet, go to [oc.app](https://oc.app), navigate to **Settings → Bots → Register bot**, and provide:
+
+- **Endpoint URL**: `https://<your-gateway-host>/openchat`
+- **Principal**: the value printed in step 1
+
+OpenChat will call `GET /openchat/bot_definition` to verify your endpoint is reachable before completing registration, and `POST /openchat/execute_command` each time a user sends `/prompt`.

package/index.ts

@@ -0,0 +1,73 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { handleBotDefinition } from "./src/bot-definition.js";
+import { openChatPlugin, type ResolvedOpenChatAccount } from "./src/channel.js";
+import { makeExecuteCommandHandler } from "./src/execute-command.js";
+import { setOpenChatRuntime } from "./src/runtime.js";
+
+// Active per-account context, keyed by accountId.
+// Populated by gateway.startAccount, removed on abort.
+const activeAccounts = new Map<string, { cfg: OpenClawConfig; account: ResolvedOpenChatAccount }>();
+
+const plugin = {
+  id: "openchat",
+  name: "OpenChat",
+  description: "OpenChat channel plugin — AI agent via a /prompt bot command",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setOpenChatRuntime(api.runtime);
+
+    // Register the channel, with a gateway that tracks active accounts.
+    api.registerChannel({
+      plugin: {
+        ...openChatPlugin,
+        gateway: {
+          startAccount: async (ctx) => {
+            activeAccounts.set(ctx.accountId, {
+              cfg: ctx.cfg,
+              account: ctx.account as ResolvedOpenChatAccount,
+            });
+            ctx.abortSignal.addEventListener("abort", () => {
+              activeAccounts.delete(ctx.accountId);
+            });
+          },
+        },
+      },
+    });
+
+    const executeCommandHandler = async (
+      req: import("node:http").IncomingMessage,
+      res: import("node:http").ServerResponse,
+    ) => {
+      // Use the first active account (single-account use case).
+      // For multi-account support, the JWT scope could be used to pick the right one.
+      const entry = activeAccounts.values().next().value;
+      if (!entry) {
+        res.statusCode = 503;
+        res.end(JSON.stringify({ error: "OpenChat channel not started" }));
+        return;
+      }
+      const handler = makeExecuteCommandHandler(entry.cfg, entry.account);
+      await handler(req, res);
+    };
+
+    // GET /bot_definition and POST /execute_command at root — OpenChat bot registration
+    // only accepts an origin URL, so it expects these paths at the root.
+    // We also register the /openchat/* prefixed variants for clarity.
+    for (const prefix of ["", "/openchat"]) {
+      api.registerHttpRoute({
+        path: `${prefix}/bot_definition`,
+        handler: (req, res) => {
+          handleBotDefinition(req, res);
+        },
+      });
+      api.registerHttpRoute({
+        path: `${prefix}/execute_command`,
+        handler: executeCommandHandler,
+      });
+    }
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "openchat",
+  "name": "OpenChat",
+  "description": "OpenChat channel plugin — AI agent via a /prompt bot command",
+  "channels": ["openchat"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+    "name": "@open-ic/openchat_openclaw",
+    "version": "0.1.0",
+    "description": "OpenClaw OpenChat channel plugin",
+    "type": "module",
+    "scripts": {
+        "generate-key": "tsx scripts/generate-key.ts"
+    },
+    "dependencies": {
+        "@open-ic/openchat-botclient-ts": "^1.0.64"
+    },
+    "devDependencies": {
+        "openclaw": "latest",
+        "tsx": "latest"
+    },
+    "openclaw": {
+        "extensions": [
+            "./index.ts"
+        ]
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/scripts/generate-key.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env -S node --import tsx
+/**
+ * Generates a secp256k1 private key, writes it to ~/.openclaw/openchat-bot.pem,
+ * and prints the corresponding Internet Computer principal — everything needed
+ * to register an OpenChat bot before the gateway is running.
+ *
+ * Usage:
+ *   npx --package @open-ic/openchat_openclaw generate-key
+ *
+ * Output:
+ *   ~/.openclaw/openchat-bot.pem  → configure with: openclaw config set channels.openchat.privateKeyFile ~/.openclaw/openchat-bot.pem
+ *   Principal                     → use when registering the bot on OpenChat
+ */
+import { execSync } from "node:child_process";
+import { mkdirSync, writeFileSync, chmodSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { BotClientFactory } from "@open-ic/openchat-botclient-ts";
+
+// Generate a secp256k1 key in traditional EC format (BEGIN EC PRIVATE KEY),
+// which is what the @dfinity/identity-secp256k1 SDK expects.
+const pem = execSync(
+  "openssl ecparam -name secp256k1 -genkey -noout | openssl ec -outform PEM 2>/dev/null",
+)
+  .toString()
+  .trim();
+
+// Write the PEM to ~/.openclaw/openchat-bot.pem (mode 600 — private key).
+const pemDir = join(homedir(), ".openclaw");
+const pemPath = join(pemDir, "openchat-bot.pem");
+mkdirSync(pemDir, { recursive: true });
+if (existsSync(pemPath)) {
+  console.error(`Error: ${pemPath} already exists. Remove it first if you want to regenerate.`);
+  process.exit(1);
+}
+writeFileSync(pemPath, pem + "\n", { encoding: "utf8" });
+chmodSync(pemPath, 0o600);
+
+// BotClientFactory logs "Principal: <text>" to console as a side effect of createAgent.
+// We use a dummy public key and canister ID since we only need the identity to be created.
+console.log("=== OpenChat Bot Identity ===\n");
+console.log("Deriving principal from key (you will see it printed below)...\n");
+
+new BotClientFactory({
+  openchatPublicKey: "dummy",
+  icHost: "https://icp-api.io",
+  identityPrivateKey: pem,
+  openStorageCanisterId: "aaaaa-aa",
+});
+
+console.log(`\nPrivate key saved to: ${pemPath}`);
+console.log("\nConfigure OpenClaw to use it:");
+console.log(`  openclaw config set channels.openchat.privateKeyFile ${pemPath}`);
+console.log("\nEndpoint to register with OpenChat: https://<your-gateway-host>/openchat");

package/src/bot-definition.ts

@@ -0,0 +1,57 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { Permissions } from "@open-ic/openchat-botclient-ts";
+
+const emptyPermissions = { chat: [], community: [], message: [] };
+
+const BOT_DEFINITION = {
+  description:
+    "An AI agent powered by OpenClaw. Send it a /prompt and it will reply using your configured AI model.",
+  // No autonomous_config — this bot only responds to explicit /prompt commands,
+  // so it doesn't need to subscribe to all chat messages.
+  commands: [
+    {
+      name: "prompt",
+      default_role: "Participant",
+      description: "Send a message to the AI agent",
+      // Allow use in direct messages (the primary use case)
+      direct_messages: true,
+      permissions: Permissions.encodePermissions({
+        ...emptyPermissions,
+        message: ["Text"],
+      }),
+      params: [
+        {
+          name: "prompt",
+          required: true,
+          description: "Your message to the AI agent",
+          placeholder: "Ask me anything...",
+          param_type: {
+            StringParam: {
+              min_length: 1,
+              max_length: 5000,
+              choices: [],
+              multi_line: true,
+            },
+          },
+        },
+      ],
+    },
+  ],
+};
+
+export function handleBotDefinition(req: IncomingMessage, res: ServerResponse): boolean {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+  if (req.method === "OPTIONS") {
+    res.statusCode = 204;
+    res.end();
+    return true;
+  }
+
+  res.setHeader("Content-Type", "application/json");
+  res.statusCode = 200;
+  res.end(JSON.stringify(BOT_DEFINITION));
+  return true;
+}

package/src/channel.ts

@@ -0,0 +1,112 @@
+import { readFileSync } from "node:fs";
+import { type ChannelPlugin, DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import { openChatOnboardingAdapter } from "./onboarding.js";
+
+/**
+ * Resolves the bot private key PEM using this priority order:
+ *   1. OC_PRIVATE_KEY env var
+ *   2. privateKeyFile path in config (reads the file)
+ *   3. privateKey raw value in config (newlines may be escaped as \n)
+ *
+ * Returns undefined if none are set.
+ */
+export function resolvePrivateKey(config: OpenChatAccountConfig): string | undefined {
+  if (process.env.OC_PRIVATE_KEY) {
+    return process.env.OC_PRIVATE_KEY.replace(/\\n/g, "\n");
+  }
+  if (config.privateKeyFile) {
+    try {
+      return readFileSync(config.privateKeyFile, "utf8").trim();
+    } catch (err) {
+      throw new Error(
+        `[openchat] Could not read privateKeyFile "${config.privateKeyFile}": ${String(err)}`,
+      );
+    }
+  }
+  if (config.privateKey) {
+    return config.privateKey.replace(/\\n/g, "\n");
+  }
+  return undefined;
+}
+
+const meta = {
+  id: "openchat",
+  label: "OpenChat",
+  selectionLabel: "OpenChat (Bot)",
+  docsPath: "/channels/openchat",
+  blurb: "Talk to the AI agent directly inside OpenChat via a bot.",
+  systemImage: "bubble.left.and.bubble.right.fill",
+};
+
+export interface OpenChatAccountConfig {
+  /** Path to the PEM file on disk. Takes priority over privateKey. */
+  privateKeyFile?: string;
+  /** Raw PEM string (with \n escaped as \\n). Use privateKeyFile instead when possible. */
+  privateKey?: string;
+  enabled?: boolean;
+}
+
+export interface ResolvedOpenChatAccount {
+  accountId: string;
+  name: string;
+  enabled: boolean;
+  config: OpenChatAccountConfig;
+  /** Resolved PEM: env var > key file > raw config value. */
+  privateKey?: string;
+}
+
+export const openChatPlugin: ChannelPlugin<ResolvedOpenChatAccount> = {
+  id: "openchat",
+  meta,
+  onboarding: openChatOnboardingAdapter,
+  capabilities: {
+    // Direct chat only — user installs the bot and talks to it 1:1
+    chatTypes: ["direct"],
+    media: false,
+  },
+  config: {
+    listAccountIds: (cfg) => {
+      const base = cfg.channels?.openchat as
+        | (OpenChatAccountConfig & {
+            accounts?: Record<string, OpenChatAccountConfig>;
+          })
+        | undefined;
+      if (process.env.OC_PRIVATE_KEY || base?.privateKeyFile || base?.privateKey) {
+        return [DEFAULT_ACCOUNT_ID];
+      }
+      const accountKeys = Object.keys(base?.accounts ?? {});
+      return accountKeys.length ? accountKeys : [DEFAULT_ACCOUNT_ID];
+    },
+    resolveAccount: (cfg, accountId) => {
+      const id = accountId || DEFAULT_ACCOUNT_ID;
+      const base = cfg.channels?.openchat as
+        | (OpenChatAccountConfig & {
+            accounts?: Record<string, OpenChatAccountConfig>;
+          })
+        | undefined;
+      const account = base?.accounts?.[id];
+
+      const config: OpenChatAccountConfig = {
+        privateKeyFile: (account?.privateKeyFile || base?.privateKeyFile) as string | undefined,
+        privateKey: (account?.privateKey || base?.privateKey) as string | undefined,
+        enabled: (account?.enabled ?? base?.enabled ?? true) as boolean,
+      };
+
+      return {
+        accountId: id,
+        name: id,
+        enabled: config.enabled ?? true,
+        config,
+        privateKey: resolvePrivateKey(config),
+      };
+    },
+    defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+    isConfigured: (account) => Boolean(account.privateKey?.trim()),
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.privateKey?.trim()),
+    }),
+  },
+};

package/src/execute-command.ts

@@ -0,0 +1,175 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { ResolvedOpenChatAccount } from "./channel.js";
+import { getFactory } from "./factory.js";
+import { getOpenChatRuntime } from "./runtime.js";
+
+export function success(msg?: import("@open-ic/openchat-botclient-ts").Message) {
+  return {
+    message: msg?.toResponse(),
+  };
+}
+
+/**
+ * Handles POST /openchat/execute_command.
+ *
+ * OpenChat sends a signed JWT in the x-oc-jwt header. The JWT contains
+ * the command name, arguments, and scope (which chat/user sent this).
+ * We verify it via the SDK, dispatch to the agent pipeline, then send
+ * the reply back via BotClient.sendMessage().
+ */
+export function makeExecuteCommandHandler(cfg: OpenClawConfig, account: ResolvedOpenChatAccount) {
+  return async function handleExecuteCommand(
+    req: IncomingMessage,
+    res: ServerResponse,
+  ): Promise<boolean> {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, x-oc-jwt");
+
+    if (req.method === "OPTIONS") {
+      res.statusCode = 204;
+      res.end();
+      return true;
+    }
+
+    if (req.method !== "POST") {
+      res.statusCode = 405;
+      res.end("Method Not Allowed");
+      return true;
+    }
+
+    const jwt = req.headers["x-oc-jwt"] as string | undefined;
+    if (!jwt) {
+      res.statusCode = 400;
+      res.end(JSON.stringify({ error: "Missing x-oc-jwt header" }));
+      return true;
+    }
+
+    if (!account.privateKey) {
+      res.statusCode = 500;
+      res.end(
+        JSON.stringify({
+          error: "OpenChat bot not configured (missing privateKey)",
+        }),
+      );
+      return true;
+    }
+
+    let client;
+    try {
+      const factory = getFactory(account.privateKey);
+      client = factory.createClientFromCommandJwt(jwt);
+    } catch (err) {
+      res.statusCode = 400;
+      res.end(JSON.stringify({ error: `Invalid JWT: ${String(err)}` }));
+      return true;
+    }
+
+    if (client.commandName !== "prompt") {
+      res.statusCode = 400;
+      res.end(
+        JSON.stringify({
+          error: `Unknown command: ${client.commandName}`,
+        }),
+      );
+      return true;
+    }
+
+    const promptText = client.stringArg("prompt");
+    if (!promptText?.trim()) {
+      res.statusCode = 400;
+      res.end(JSON.stringify({ error: "prompt argument is required" }));
+      return true;
+    }
+
+    const placeholder = (await client.createTextMessage("Thinking ...")).setFinalised(false);
+
+    // Respond immediately so OpenChat shows a placeholder while we process.
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify(success(placeholder)));
+
+    // Dispatch to the agent pipeline asynchronously.
+    const core = getOpenChatRuntime();
+    const log = core.logging.getChildLogger({ channel: "openchat" });
+    const senderId = String(client.initiator ?? "unknown");
+    const messageId = String(Date.now());
+
+    const route = core.channel.routing.resolveAgentRoute({
+      cfg,
+      channel: "openchat",
+      accountId: account.accountId,
+      peer: { kind: "direct", id: senderId },
+    });
+
+    const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
+    const storePath = core.channel.session.resolveStorePath(cfg.session?.store, {
+      agentId: route.agentId,
+    });
+    const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+      storePath,
+      sessionKey: route.sessionKey,
+    });
+
+    const body = core.channel.reply.formatAgentEnvelope({
+      channel: "OpenChat",
+      from: senderId,
+      timestamp: Date.now(),
+      previousTimestamp,
+      envelope: envelopeOptions,
+      body: promptText,
+    });
+
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+      Body: body,
+      BodyForAgent: promptText,
+      RawBody: promptText,
+      CommandBody: promptText,
+      From: `openchat:${senderId}`,
+      To: `openchat:${account.accountId}`,
+      SessionKey: route.sessionKey,
+      AccountId: route.accountId,
+      ChatType: "direct",
+      ConversationLabel: senderId,
+      SenderId: senderId,
+      Provider: "openchat",
+      Surface: "openchat",
+      MessageSid: messageId,
+      MessageSidFull: messageId,
+    });
+
+    // OpenChat command/response model: one command → one reply message.
+    // All messages created by a command BotClient share the same messageId, so we
+    // must call sendMessage exactly once. Accumulate all delivered text segments
+    // and send a single finalised message after dispatch completes.
+    const replyParts: string[] = [];
+    await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+      ctx: ctxPayload,
+      cfg,
+      dispatcherOptions: {
+        deliver: async (payload) => {
+          if (payload.text) {
+            replyParts.push(payload.text);
+          }
+        },
+        onError: (err) => {
+          log.error(`[openchat] dispatch error: ${String(err)}`);
+        },
+      },
+    });
+    const replyText = replyParts.join("\n\n").trim();
+    if (replyText) {
+      try {
+        const msg = await client.createTextMessage(replyText);
+        msg.setBlockLevelMarkdown(true);
+        msg.setFinalised(true);
+        await client.sendMessage(msg);
+      } catch (err) {
+        log.error(`[openchat] failed to send reply: ${String(err)}`);
+      }
+    }
+
+    return true;
+  };
+}

package/src/factory.ts

@@ -0,0 +1,40 @@
+import { BotClientFactory } from "@open-ic/openchat-botclient-ts";
+
+// Production OpenChat / Internet Computer constants.
+// Override via environment variables for testing against a local replica.
+const OC_IC_HOST = process.env.OC_IC_HOST ?? "https://icp-api.io";
+const OC_PUBLIC_KEY = process.env.OC_PUBLIC_KEY ?? "";
+const OC_USER_INDEX_CANISTER = process.env.OC_USER_INDEX_CANISTER ?? "";
+const OC_STORAGE_INDEX_CANISTER =
+  process.env.OC_STORAGE_INDEX_CANISTER ?? "nbpzs-kqaaa-aaaar-qaaua-cai";
+
+let cached: { factory: BotClientFactory; privateKey: string } | null = null;
+
+/**
+ * Returns a BotClientFactory for the given private key, reusing the cached
+ * instance when the key hasn't changed.
+ */
+export function getFactory(privateKey: string): BotClientFactory {
+  if (cached?.privateKey === privateKey) {
+    return cached.factory;
+  }
+
+  if (!OC_PUBLIC_KEY) {
+    throw new Error(
+      "OC_PUBLIC_KEY environment variable is required. " +
+        "Set it to OpenChat's ES256 public key for JWT verification.",
+    );
+  }
+
+  // Both keys may have literal \n in env vars — unescape them.
+  const factory = new BotClientFactory({
+    openchatPublicKey: OC_PUBLIC_KEY.replace(/\\n/g, "\n"),
+    icHost: OC_IC_HOST,
+    identityPrivateKey: privateKey,
+    openStorageCanisterId: OC_STORAGE_INDEX_CANISTER,
+    userIndexCanisterId: OC_USER_INDEX_CANISTER,
+  });
+
+  cached = { factory, privateKey };
+  return factory;
+}

package/src/onboarding.ts

@@ -0,0 +1,59 @@
+import type { ChannelOnboardingAdapter, OpenClawConfig } from "openclaw/plugin-sdk";
+
+type OcConfig = { privateKeyFile?: string; privateKey?: string };
+
+function setEnabled(cfg: OpenClawConfig, enabled: boolean): OpenClawConfig {
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      openchat: { ...cfg.channels?.openchat, enabled },
+    },
+  };
+}
+
+function isConfigured(cfg: OpenClawConfig): boolean {
+  const oc = cfg.channels?.openchat as OcConfig | undefined;
+  return Boolean(
+    process.env.OC_PRIVATE_KEY || oc?.privateKeyFile?.trim() || oc?.privateKey?.trim(),
+  );
+}
+
+export const openChatOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel: "openchat",
+  getStatus: async ({ cfg }) => {
+    const configured = isConfigured(cfg);
+    return {
+      channel: "openchat",
+      configured,
+      statusLines: [configured ? "OpenChat: Configured" : "OpenChat: Not configured"],
+      quickstartScore: configured ? 1 : 0,
+    };
+  },
+  configure: async ({ cfg, prompter }) => {
+    const oc = cfg.channels?.openchat as OcConfig | undefined;
+
+    // Prefer file path — avoids PEM newline escaping issues in YAML.
+    // Users can also set OC_PRIVATE_KEY env var to skip this entirely.
+    const privateKeyFile = await prompter.text({
+      message:
+        "Path to your OpenChat bot PEM key file (e.g. ~/.openclaw/openchat-bot.pem)\n" +
+        "  Leave blank to use the OC_PRIVATE_KEY env var instead.",
+      initialValue: oc?.privateKeyFile ?? "",
+    });
+
+    const next: OpenClawConfig = {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        openchat: {
+          ...cfg.channels?.openchat,
+          enabled: true,
+          privateKeyFile: String(privateKeyFile ?? "").trim() || undefined,
+        },
+      },
+    };
+    return { cfg: next, accountId: "default" };
+  },
+  disable: (cfg) => setEnabled(cfg, false),
+};

package/src/runtime.ts

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