openclaw-nim 0.0.1

package/README.md

@@ -0,0 +1,202 @@
+# OpenClaw NIM Plugin
+
+A [OpenClaw](https://openclaw.ai/) channel plugin for NetEase IM (网易云信).
+
+## Features
+
+- 📱 Private chat (P2P) message support
+- 📷 Media support (images, files, audio, video)
+- 🔐 AppKey + Token authentication
+- 🔄 Automatic reconnection handling
+- 📝 Message chunking for long responses
+
+## Installation
+
+### Install Node.js
+
+#### Option 1: Official Installer (Recommended)
+
+1. Visit [nodejs.org](https://nodejs.org/).
+2. Download the **LTS** version (e.g., v20.x.x).
+3. Run the installer and follow the prompts.
+
+#### Option 2: NVM (Node Version Manager)
+
+NVM allows you to install and manage multiple Node.js versions:
+
+```bash
+# Install nvm (if not already installed)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+
+# Restart terminal or run:
+source ~/.zshrc  # or ~/.bashrc for bash
+
+# Install Node.js LTS
+nvm install --lts
+
+# Use the installed version
+nvm use --lts
+```
+
+#### Option 3: Homebrew (macOS)
+
+If you have Homebrew installed:
+
+```bash
+brew install node
+```
+
+#### Verify Installation
+
+```bash
+node --version
+# Should show v20.x.x or higher
+```
+
+### Install OpenClaw
+
+Open Terminal
+
+Press `Cmd + Space`, type `Terminal`, and hit Enter.
+
+Install CLI
+
+```bash
+npm install -g openclaw@latest
+```
+
+> **Note:** If you see permission errors, use `sudo`:
+>
+> ```bash
+> sudo npm install -g openclaw@latest
+> ```
+
+### Installation Plugin
+
+```bash
+openclaw plugins install openclaw-nim
+```
+
+## Configuration
+
+```bash
+openclaw config set channels.nim.appKey "your-app-key"
+openclaw config set channels.nim.account "your-bot-account-id"
+openclaw config set channels.nim.token "your-auth-token"
+openclaw config set channels.nim.enabled true     
+```
+
+Or add the following to your OpenClaw configuration (`openclaw.yaml` or `openclaw.json`):
+
+```yaml
+channels:
+  nim:
+    enabled: true
+    appKey: "your-app-key"
+    account: "your-bot-account-id"
+    token: "your-auth-token"
+    dmPolicy: "open"  # or "allowlist"
+    allowFrom:        # Required if dmPolicy is "allowlist"
+      - "allowed-user-1"
+      - "allowed-user-2"
+    mediaMaxMb: 30    # Max media file size in MB
+    textChunkLimit: 4000  # Max characters per message
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable/disable the NIM channel |
+| `appKey` | string | - | NIM application AppKey (required) |
+| `account` | string | - | Bot account ID (required) |
+| `token` | string | - | Authentication token (required) |
+| `dmPolicy` | string | `"open"` | DM access policy: `"open"` or `"allowlist"` |
+| `allowFrom` | array | `[]` | List of allowed sender IDs (when using allowlist) |
+| `mediaMaxMb` | number | `30` | Maximum media file size in MB |
+| `textChunkLimit` | number | `4000` | Maximum characters per message chunk |
+| `lbsUrl` | string | - | Custom LBS server URL (for private deployment) |
+| `linkUrl` | string | - | Custom Link server URL (for private deployment) |
+| `debug` | boolean | `false` | Enable SDK debug logging |
+
+## Start the Bot
+
+```bash
+openclaw onboard
+```
+
+## Getting Credentials
+
+1. Log in to the [NetEase IM Console](https://app.netease.im/)
+2. Create or select an application
+3. Copy the **AppKey** from the application settings
+4. Create a bot account and obtain its **Account ID** and **Token**
+
+## Usage
+
+### Sending Messages
+
+```typescript
+import { sendMessageNim, sendImageNim } from "openclaw-nim";
+
+// Send text message
+await sendMessageNim({
+  cfg: openclawConfig,
+  to: "user123",
+  text: "Hello from NIM bot!",
+});
+
+// Send image
+await sendImageNim({
+  cfg: openclawConfig,
+  to: "user123",
+  imagePath: "/path/to/image.png",
+});
+```
+
+### Target Formats
+
+The plugin accepts various target formats:
+
+- `user123` - Plain account ID
+- `nim:user123` - Prefixed with `nim:`
+- `user:user123` - Prefixed with `user:`
+
+## Supported Message Types
+
+| Type | Receive | Send |
+|------|---------|------|
+| Text | ✅ | ✅ |
+| Image | ✅ | ✅ |
+| File | ✅ | ✅ |
+| Audio | ✅ | ✅ |
+| Video | ✅ | ✅ |
+| Location | ✅ | ❌ |
+| Custom | ✅ | ❌ |
+
+## Limitations
+
+- **Private chat only**: Group chat support is not implemented in this version
+- **No message editing**: NIM does not support editing sent messages
+- **No reactions**: Message reactions are not supported
+- **No threads**: Thread/reply functionality is not supported
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode
+npm run dev
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,64 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
+import { nimPlugin } from "./src/channel.js";
+import { setNimRuntime } from "./src/runtime.js";
+
+// Export monitor functions
+export { monitorNimProvider, stopNimMonitor, isNimMonitorRunning } from "./src/monitor.js";
+
+// Export send functions
+export { sendMessageNim, editMessageNim, getMessageNim, sendLongMessageNim } from "./src/send.js";
+
+// Export outbound functions
+export { 
+  nimOutboundConfig, 
+  sendNimOutboundText, 
+  sendNimOutboundMedia, 
+  resolveNimOutboundTarget,
+  nimOutbound,
+  type NimOutboundResult,
+} from "./src/outbound.js";
+
+// Export media functions
+export { sendImageNim, sendFileNim, sendAudioNim, sendVideoNim, downloadNimMedia } from "./src/media.js";
+
+// Export probe function
+export { probeNim, probeNimWithConnect } from "./src/probe.js";
+
+// Export channel plugin
+export { nimPlugin } from "./src/channel.js";
+
+// Export types
+export type {
+  NimConfig,
+  NimMessageContext,
+  NimSendResult,
+  NimProbeResult,
+  NimMediaInfo,
+  NimMessageEvent,
+  NimMessageType,
+  NimDmPolicy,
+  ResolvedNimAccount,
+} from "./src/types.js";
+
+// Export utility functions
+export { normalizeNimTarget, looksLikeNimId, formatNimTarget } from "./src/targets.js";
+export { resolveNimCredentials, resolveNimAccount, isNimDmAllowed } from "./src/accounts.js";
+
+/**
+ * OpenClaw NIM Plugin
+ *
+ * A Clawdbot channel plugin for NetEase IM (NIM).
+ */
+const plugin = {
+  id: "openclaw-nim",
+  name: "NIM",
+  description: "NetEase IM (网易云信) channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: ClawdbotPluginApi) {
+    setNimRuntime(api.runtime);
+    api.registerChannel({ plugin: nimPlugin });
+  },
+};
+
+export default plugin;

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "openclaw-nim",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "OpenClaw NIM (NetEase IM) channel plugin",
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src",
+    "openclaw.plugin.json"
+  ],
+  "keywords": [
+    "openclaw",
+    "nim",
+    "netease",
+    "yunxin",
+    "im",
+    "chatbot",
+    "ai"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "nim",
+      "label": "NIM",
+      "selectionLabel": "NetEase IM (网易云信)",
+      "docsPath": "/channels/nim",
+      "docsLabel": "nim",
+      "blurb": "网易云信 IM 即时通讯。",
+      "aliases": [
+        "netease",
+        "yunxin"
+      ],
+      "order": 80
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "node-nim": "^10.9.72",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "openclaw": "2026.1.29",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.29"
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,115 @@
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import type { NimConfig, ResolvedNimAccount, NimDmPolicy } from "./types.js";
+
+/**
+ * Default account ID for NIM (single account mode).
+ */
+export const DEFAULT_NIM_ACCOUNT_ID = "default";
+
+/**
+ * Coerce a value to string.
+ * Handles cases where YAML parses numeric values (e.g., account: 123456) as numbers.
+ */
+function coerceToString(value: unknown): string {
+  if (typeof value === "number") {
+    return String(value);
+  }
+  return String(value ?? "");
+}
+
+/**
+ * Resolve NIM credentials from configuration.
+ * Returns null if required credentials are missing.
+ * Automatically converts numeric values to strings (YAML may parse them as numbers).
+ */
+export function resolveNimCredentials(
+  cfg: NimConfig | undefined,
+): { appKey: string; account: string; token: string } | null {
+  if (!cfg?.appKey || !cfg?.account || !cfg?.token) {
+    return null;
+  }
+  return {
+    appKey: coerceToString(cfg.appKey),
+    account: coerceToString(cfg.account),
+    token: coerceToString(cfg.token),
+  };
+}
+
+/**
+ * Resolve NIM account information from Clawdbot configuration.
+ */
+export function resolveNimAccount(params: {
+  cfg: ClawdbotConfig;
+}): ResolvedNimAccount | null {
+  const { cfg } = params;
+  const nimCfg = cfg.channels?.nim as NimConfig | undefined;
+  const creds = resolveNimCredentials(nimCfg);
+
+  if (!creds) {
+    return null;
+  }
+
+  return {
+    id: DEFAULT_NIM_ACCOUNT_ID,
+    appKey: creds.appKey,
+    account: creds.account,
+    token: creds.token,
+    enabled: nimCfg?.enabled ?? false,
+    dmPolicy: (nimCfg?.dmPolicy as NimDmPolicy) ?? "open",
+    allowFrom: nimCfg?.allowFrom ?? [],
+  };
+}
+
+/**
+ * Check if a sender is in the allowlist.
+ */
+export function resolveNimAllowlistMatch(params: {
+  allowFrom: Array<string | number>;
+  senderId: string;
+}): { allowed: boolean; matchedEntry?: string | number } {
+  const { allowFrom, senderId } = params;
+
+  if (!allowFrom || allowFrom.length === 0) {
+    return { allowed: false };
+  }
+
+  const normalizedSenderId = senderId.toLowerCase();
+
+  for (const entry of allowFrom) {
+    const normalizedEntry = String(entry).toLowerCase();
+    if (normalizedEntry === normalizedSenderId) {
+      return { allowed: true, matchedEntry: entry };
+    }
+  }
+
+  return { allowed: false };
+}
+
+/**
+ * Check if DM is allowed based on policy and sender.
+ */
+export function isNimDmAllowed(params: {
+  dmPolicy: "open" | "pairing" | "allowlist";
+  allowFrom: Array<string | number>;
+  senderId: string;
+}): boolean {
+  const { dmPolicy, allowFrom, senderId } = params;
+
+  if (dmPolicy === "open") {
+    return true;
+  }
+
+  if (dmPolicy === "allowlist") {
+    const match = resolveNimAllowlistMatch({ allowFrom, senderId });
+    return match.allowed;
+  }
+
+  // "pairing" mode - could implement pairing logic here
+  if (dmPolicy === "pairing") {
+    // For now, treat pairing as allowlist
+    const match = resolveNimAllowlistMatch({ allowFrom, senderId });
+    return match.allowed;
+  }
+
+  return false;
+}

package/src/bot.ts

@@ -0,0 +1,240 @@
+import type { ClawdbotConfig, RuntimeEnv } from "clawdbot/plugin-sdk";
+import type { NimConfig, NimMessageContext, NimMessageEvent, NimMessageType, NimSessionType } from "./types.js";
+import { isNimDmAllowed } from "./accounts.js";
+import { getNimRuntime } from "./runtime.js";
+import { downloadNimMedia, buildNimMediaPayload, inferMediaPlaceholder } from "./media.js";
+import { createNimReplyDispatcher } from "./reply-dispatcher.js";
+
+/**
+ * Map node-nim message type number to typed enum.
+ * node-nim msg_type: 0=text, 1=image, 2=audio, 3=video, 4=geo, 5=notification, 6=file, 10=tip, 100=custom
+ */
+function mapMessageType(msgType: number): NimMessageType {
+  switch (msgType) {
+    case 0:
+      return "text";
+    case 1:
+      return "image";
+    case 2:
+      return "audio";
+    case 3:
+      return "video";
+    case 4:
+      return "geo";
+    case 5:
+      return "notification";
+    case 6:
+      return "file";
+    case 10:
+      return "tip";
+    case 100:
+      return "custom";
+    default:
+      return "unknown";
+  }
+}
+
+/**
+ * Get session type name from number.
+ * node-nim session_type: 0=p2p, 1=team
+ */
+function getSessionTypeName(sessionType: number): "p2p" | "team" | "unknown" {
+  switch (sessionType) {
+    case 0:
+      return "p2p";
+    case 1:
+      return "team";
+    default:
+      return "unknown";
+  }
+}
+
+/**
+ * Extract text content from a NIM message.
+ */
+function extractMessageContent(message: NimMessageEvent): string {
+  if (message.type === "text" && message.text) {
+    return message.text;
+  }
+
+  if (message.type === "geo" && message.attach) {
+    const geo = message.attach;
+    return `[位置] ${geo.title ?? ""} (${geo.lat}, ${geo.lng})`;
+  }
+
+  if (message.type === "custom" && message.ext) {
+    try {
+      const parsed = message.ext;
+      return (parsed as any).text || (parsed as any).content || JSON.stringify(parsed);
+    } catch {
+      return String(message.ext);
+    }
+  }
+
+  // For media messages, return a placeholder
+  if (["image", "file", "audio", "video"].includes(message.type)) {
+    return inferMediaPlaceholder(message.type);
+  }
+
+  return message.text || "";
+}
+
+/**
+ * Parse a NIM message event into a message context.
+ */
+export function parseNimMessageEvent(message: NimMessageEvent): NimMessageContext {
+  const isDirectMessage = message.sessionType === "p2p";
+  const sessionId = isDirectMessage 
+    ? `p2p-${message.from}` 
+    : `team-${message.to}`;
+
+  return {
+    id: message.clientMsgId,
+    sessionId,
+    sessionType: message.sessionType,
+    senderId: message.from,
+    type: message.type,
+    text: extractMessageContent(message),
+    timestamp: message.time,
+    isDm: isDirectMessage,
+    rawEvent: message,
+  };
+}
+
+/**
+ * Handle an incoming NIM message.
+ */
+export async function handleNimMessage(params: {
+  cfg: ClawdbotConfig;
+  message: NimMessageEvent;
+  runtime?: RuntimeEnv;
+}): Promise<void> {
+  const { cfg, message, runtime } = params;
+  const nimCfg = cfg.channels?.nim as NimConfig | undefined;
+  const log = runtime?.log ?? console.log;
+  const error = runtime?.error ?? console.error;
+
+  // Only process P2P messages (DM only for now)
+  if (message.sessionType !== "p2p") {
+    log(`nim: ignoring non-P2P message from session type: ${message.sessionType}`);
+    return;
+  }
+
+  const ctx = parseNimMessageEvent(message);
+
+  log(`nim: received message from ${ctx.senderId} (type: ${ctx.type})`);
+
+  // Check DM policy
+  const dmPolicy = nimCfg?.dmPolicy ?? "open";
+  const allowFrom = nimCfg?.allowFrom ?? [];
+
+  const allowed = isNimDmAllowed({
+    dmPolicy,
+    allowFrom,
+    senderId: ctx.senderId,
+  });
+
+  if (!allowed) {
+    log(`nim: sender ${ctx.senderId} not allowed by DM policy`);
+    return;
+  }
+
+  try {
+    const core = getNimRuntime();
+
+    const nimFrom = `nim:${ctx.senderId}`;
+    const nimTo = `user:${ctx.senderId}`;
+
+    const route = core.channel.routing.resolveAgentRoute({
+      cfg,
+      channel: "nim",
+      peer: {
+        kind: "dm",
+        id: ctx.senderId,
+      },
+    });
+
+    const preview = ctx.text.replace(/\s+/g, " ").slice(0, 160);
+    const inboundLabel = `NIM DM from ${ctx.senderId}`;
+
+    core.system.enqueueSystemEvent(`${inboundLabel}: ${preview}`, {
+      sessionKey: route.sessionKey,
+      contextKey: `nim:message:${ctx.sessionId}:${ctx.id}`,
+    });
+
+    // Handle media if present
+    const mediaMaxBytes = (nimCfg?.mediaMaxMb ?? 30) * 1024 * 1024;
+    const mediaList = [];
+
+    if (["image", "file", "audio", "video"].includes(ctx.type)) {
+      const attachUrl = message.attach?.url;
+      if (attachUrl) {
+        const mediaInfo = await downloadNimMedia({
+          cfg,
+          url: attachUrl,
+          filename: message.attach?.name,
+          maxBytes: mediaMaxBytes,
+          log,
+        });
+        if (mediaInfo) {
+          mediaList.push(mediaInfo);
+        }
+      }
+    }
+
+    const mediaPayload = buildNimMediaPayload(mediaList);
+
+    const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
+
+    const body = core.channel.reply.formatAgentEnvelope({
+      channel: "NIM",
+      from: ctx.senderId,
+      timestamp: new Date(ctx.timestamp),
+      envelope: envelopeOptions,
+      body: ctx.text,
+    });
+
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+      Body: body,
+      RawBody: ctx.text,
+      CommandBody: ctx.text,
+      From: nimFrom,
+      To: nimTo,
+      SessionKey: route.sessionKey,
+      AccountId: route.accountId,
+      ChatType: "direct",
+      SenderName: ctx.senderId,
+      SenderId: ctx.senderId,
+      Provider: "nim" as const,
+      Surface: "nim" as const,
+      MessageSid: ctx.id,
+      Timestamp: ctx.timestamp,
+      CommandAuthorized: true,
+      OriginatingChannel: "nim" as const,
+      OriginatingTo: nimTo,
+      ...mediaPayload,
+    });
+
+    const { dispatcher, replyOptions, markDispatchIdle } = createNimReplyDispatcher({
+      cfg,
+      agentId: route.agentId,
+      runtime: runtime as RuntimeEnv,
+      senderId: ctx.senderId,
+    });
+
+    log(`nim: dispatching to agent (session=${route.sessionKey})`);
+
+    const { queuedFinal, counts } = await core.channel.reply.dispatchReplyFromConfig({
+      ctx: ctxPayload,
+      cfg,
+      dispatcher,
+      replyOptions,
+    });
+
+    markDispatchIdle();
+
+    log(`nim: dispatch complete (queuedFinal=${queuedFinal}, replies=${counts.final})`);
+  } catch (err) {
+    error(`nim: failed to dispatch message: ${String(err)}`);
+  }
+}