OpenClaw NIM 插件

English | 中文

OpenClaw 网易云信（NIM）渠道插件，支持 P2P 单聊、群组聊天及圈组（QChat）。

版本要求

⚠️ v1.0.0 破坏性变更

1. OpenClaw 版本要求：当前版本基于 OpenClaw 2026.4.5 进行开发。如遇到兼容性问题，请升级至 2026.4.5 及更新版本
2. 配置格式变更：channels.nim 从单对象改为数组格式（见下方示例）
3. 账号类型限制：仅支持机器人账号登录（不支持普通个人账号）
4. 凭证配置方式：推荐使用 nimToken 三合一配置（appKey|accid|token，兼容旧 appKey-accid-token）

功能特性

• 💬 P2P 单聊消息，支持可配置的访问策略
• 👥 群组聊天，支持群/发送者白名单
• 🔵 圈组（QChat）消息，支持统一白名单
• 🌊 流式输出支持（私聊和群组支持分块流式，圈组强制完整消息返回）
• 🔄 多实例支持（支持同时运行最多 3 个 NIM 实例，不同账号/AppKey）
• 📷 多媒体支持（图片、文件、音频、视频）
• 🔐 简化的 nimToken 认证（推荐 appKey|accid|token，兼容旧 appKey-accid-token）
• 🔄 自动重连处理
• 📝 长消息自动分片
• 🔒 私有化部署支持，可自定义服务器地址

安装

安装 Node.js

推荐版本：Node.js v24.x (>=24.0.0, <25.0.0)

方式一：官方安装包（推荐）

1. 访问 nodejs.org。
2. 下载 Node.js v24.x。
3. 运行安装包并按提示操作。

方式二：NVM（Node 版本管理器）

# 安装 nvm（如未安装）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 重启终端或执行：
source ~/.zshrc  # bash 用户使用 ~/.bashrc

# 安装 Node.js v24
nvm install 24
nvm use 24

方式三：Homebrew（macOS）

# 安装 Node.js v24
brew install node@24
brew link node@24

验证安装

node --version  # 应显示 v24.x.x

安装 OpenClaw

npm install -g openclaw@latest

注意： 如遇权限错误，请使用 sudo npm install -g openclaw@latest

安装插件

openclaw plugins install @nimsuite/openclaw-nim-channel

配置

注意：从 v1.0.0 开始，channels.nim 使用数组格式以支持多实例（最多 3 个）。每个实例可以有不同的凭证和策略。

快速配置（CLI）

# 注意：CLI 命令配置第一个实例（索引 0）
openclaw config set channels.nim.instances.0.nimToken "<appKey>|<accid>|<token>"
openclaw config set channels.nim.instances.0.enabled true

nimToken 格式：<appKey>|<accid>|<token>（用 | 分隔三个字段）— 推荐

示例：45c6af3c98409b18a84451215d0bdd6e|testbot001|a1b2c3d4e5f6

向后兼容：旧格式 <appKey>-<accid>-<token> 仍然可用

备选方式：使用独立的 appKey、account、token 字段（已弃用但仍支持）

私有化部署配置（CLI）

openclaw config set channels.nim.instances.0.advanced.weblbsUrl "https://your-lbs.example.com"
openclaw config set channels.nim.instances.0.advanced.link_web "weblink.netease.im:443"
openclaw config set channels.nim.instances.0.advanced.nos_uploader "https://your-nos-upload.example.com"
openclaw config set channels.nim.instances.0.advanced.nos_downloader_v2 "https://your-nos-download.example.com/{bucket}/{object}"
openclaw config set channels.nim.instances.0.advanced.nosSsl true
openclaw config set channels.nim.instances.0.advanced.nos_accelerate "https://your-cdn.example.com/{bucket}/{object}"
openclaw config set channels.nim.instances.0.advanced.nos_accelerate_host "your-cdn.example.com"

单实例配置

{
  "channels": {
    "nim": {
      "instances": [
        {
          "enabled": true,
          "nimToken": "<appKey>|<accid>|<token>",

          "p2p": {
            "policy": "open",
            "allowFrom": ["user_abc", "user_xyz"]
          },

          "team": {
            "policy": "open",
            "allowFrom": ["groupId_1", "groupId_2|user_abc", "1|groupId_3", "2|groupId_4", "1|groupId_5|user_xyz"]
          },

          "qchat": {
            "policy": "open",
            "allowFrom": [
              "serverId_1",
              "serverId_2|channelId_1",
              "serverId_2|channelId_2|user_abc",
              "serverId_3||user_xyz"
            ]
          },

          "advanced": {
            "mediaMaxMb": 30,
            "textChunkLimit": 4000,
            "debug": false,
            "weblbsUrl": "https://your-lbs.example.com",
            "link_web": "weblink.netease.im:443",
            "nos_uploader": "https://your-nos-upload.example.com",
            "nos_downloader_v2": "https://your-nos-download.example.com/{bucket}/{object}",
            "nosSsl": true,
            "nos_accelerate": "https://your-cdn.example.com/{bucket}/{object}",
            "nos_accelerate_host": "your-cdn.example.com"
          }
        }
      ]
    }
  }
}

多实例配置

同时运行最多 3 个 NIM 实例，使用不同账号或 AppKey：

{
  "channels": {
    "nim": {
      "instances": [
        {
          "enabled": true,
          "nimToken": "<appKey1>|<bot1>|<token1>",
          "p2p": { "policy": "open" },
          "team": { "policy": "allowlist", "allowFrom": ["team_abc"] },
          "qchat": { "policy": "disabled" }
        },
        {
          "enabled": true,
          "nimToken": "<appKey1>|<bot2>|<token2>",
          "p2p": { "policy": "allowlist", "allowFrom": ["user_vip"] },
          "team": { "policy": "disabled" },
          "qchat": { "policy": "open" }
        },
        {
          "enabled": false,
          "nimToken": "<appKey2>|<bot3>|<token3>",
          "p2p": { "policy": "open" }
        }
      ]
    }
  }
}

注意：最多 3 个实例（无论是否启用）。每个实例保持独立连接，可以有不同的策略。

流式输出配置

私聊和群组消息支持分块流式输出，实现实时响应传递。圈组消息使用完整消息传递（流式被强制禁用）。

要启用流式输出，配置 OpenClaw 的分块流式设置：

# config.yaml
agents:
  defaults:
    blockStreamingDefault: "on"
    blockStreamingBreak: "text_end"
    blockStreamingChunk:
      minChars: 150
      maxChars: 600

channels:
  nim:
    - enabled: true
      nimToken: "your-credentials"

流式输出详细配置，请参阅：

• BLOCK_STREAMING_CONFIG.md — 分块流式配置指南
• STREAMING_GUIDE.md — 实时流式数据使用说明

圈组特别说明：圈组消息强制禁用流式输出和文本分块，以避免消息碎片化，提升用户体验。圈组始终以完整消息形式传递。

配置参考

顶层字段

p2p — 单聊（私聊）

策略行为：

team — 群组

策略行为： 与 P2P 规则一致 — allowlist 且 allowFrom 为空时等同于 disabled。

team.allowFrom 条目格式：

qchat — 圈组

配置了 NIM 凭证后，圈组功能会自动启动。设置 policy: "disabled" 可完全关闭。

策略行为： 与 P2P 规则一致 — allowlist 且 allowFrom 为空时等同于 disabled。

qchat.allowFrom 条目格式：

allowFrom 列表（policy="allowlist" 时）还控制以下行为：

• 服务器订阅：自动订阅条目中提取的服务器 ID；policy="open" 时自动发现所有已加入的服务器。
• 服务器邀请自动同意：由 policy 控制：
  • open — 自动同意所有服务器邀请
  • allowlist — 仅自动同意 allowFrom 列表中服务器 ID 的邀请；空列表则拒绝所有
  • disabled — 不自动同意任何邀请

advanced — 高级设置

获取凭证

重要提示：仅支持机器人账号。普通个人账号无法使用此插件。

1. 登录网易云信控制台
2. 创建或选择应用
3. 在应用设置中复制 AppKey
4. 创建机器人账号（而非普通个人账号）并获取 Account ID 和 Token

启动机器人

openclaw onboard

使用

发送消息

import { sendMessageNim, sendImageNim, sendFileNim, sendAudioNim, sendVideoNim } from "@nimsuite/openclaw-nim-channel";

// 发送文本消息
await sendMessageNim({
  cfg: openclawConfig,
  to: "user123",
  text: "Hello from NIM bot!",
});

// 发送图片（支持：.jpg, .jpeg, .png, .gif, .webp, .bmp）
await sendImageNim({
  cfg: openclawConfig,
  to: "user123",
  imagePath: "/path/to/image.png",
});

// 发送视频（支持：.mp4, .mov, .avi, .mkv, .webm, .flv）
await sendVideoNim({
  cfg: openclawConfig,
  to: "user123",
  videoPath: "/path/to/video.mp4",
  duration: 60, // 时长（秒）
  width: 1920,
  height: 1080,
});

// 发送音频（支持：.mp3, .wav, .aac, .m4a, .ogg, .amr）
await sendAudioNim({
  cfg: openclawConfig,
  to: "user123",
  audioPath: "/path/to/audio.mp3",
  duration: 30, // 时长（秒）
});

// 发送文件（任意文件类型）
await sendFileNim({
  cfg: openclawConfig,
  to: "user123",
  filePath: "/path/to/document.pdf",
});

目标格式

支持的消息类型

开发

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

# 监听模式
npm run dev

许可证

MIT