openclaw-nim

v1.0.6

Published

2 months ago

OpenClaw NIM (NetEase IM) channel plugin

Downloads

342

0High
0Medium
0Low

netease-yunxin

openclaw nim netease yunxin im chatbot ai

OpenClaw NIM 插件

English | 中文

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

版本要求

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

功能特性

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

安装

安装 Node.js

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

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

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

方式二：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 — 实时流式数据使用说明

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

配置参考

顶层字段

| 字段 | 类型 | 默认值 | 说明 | | ----------------- | ------- | ------- | -------------------------------------------------------------- | | enabled | boolean | false | 启用/禁用 NIM 渠道 | | nimToken | string | — | 凭证：推荐 appKey\|accid\|token，兼容旧 appKey-accid-token | | antispamEnabled | boolean | true | 启用反垃圾邮件保护 |

`p2p` — 单聊（私聊）

| 字段 | 类型 | 默认值 | 说明 | | ----------- | ------ | -------- | -------------------------------------------------- | | policy | string | "open" | open · allowlist · disabled | | allowFrom | array | [] | 允许的发送者账号 ID（policy="allowlist" 时生效） |

策略行为：

| policy | allowFrom | 消息处理 | 好友申请自动同意 | | ----------- | ----------- | ---------------------------- | ------------------------ | | open | 任意 | 接受所有消息 | 自动同意所有 | | allowlist | 非空 | 仅接受列表中的发送者 | 仅自动同意列表中的发送者 | | allowlist | 空 | 等同于 disabled — 拒绝所有 | 不自动同意 | | disabled | 任意 | 拒绝所有消息 | 不自动同意 |

`team` — 群组

| 字段 | 类型 | 默认值 | 说明 | | ----------- | ------ | -------- | ------------------------------------------------------ | | policy | string | "open" | open · allowlist · disabled | | allowFrom | array | [] | 白名单条目 — 格式见下方（policy="allowlist" 时生效） |

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

team.allowFrom 条目格式：

| 格式 | 说明 | | ------------------------ | -------------------------------------- | | "teamId" | 该群任意发送者（高级群和超大群均匹配） | | "teamId\|accountId" | 该群中指定发送者（两种群类型均匹配） | | "1\|teamId" | 任意发送者，仅高级群 | | "2\|teamId" | 任意发送者，仅超大群 | | "1\|teamId\|accountId" | 指定发送者，仅高级群 | | "2\|teamId\|accountId" | 指定发送者，仅超大群 |

`qchat` — 圈组

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

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

qchat.allowFrom 条目格式：

| 格式 | 说明 | | ---------------------------------- | ------------------------------ | | "serverId" | 该服务器下所有频道、所有发送者 | | "serverId\|channelId" | 该服务器+频道下所有发送者 | | "serverId\|channelId\|accountId" | 该服务器+频道下指定发送者 | | "serverId\|\|accountId" | 该服务器下任意频道的指定发送者 |

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

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

`advanced` — 高级设置

| 字段 | 类型 | 默认值 | 说明 | | --------------------- | ------- | ------- | ------------------------------------ | | mediaMaxMb | number | 30 | 最大媒体文件大小（MB） | | textChunkLimit | number | 4000 | 每条消息最大字符数 | | debug | boolean | false | 启用 SDK 调试日志 | | weblbsUrl | string | — | LBS 地址（私有化部署） | | link_web | string | — | WebSocket/TCP 连接地址（私有化部署） | | nos_uploader | string | — | NOS 上传地址（私有化部署） | | nos_downloader_v2 | string | — | NOS 下载地址格式（私有化部署） | | nosSsl | boolean | — | NOS 下载是否启用 HTTPS（私有化部署） | | nos_accelerate | string | — | CDN 加速 URL 格式（私有化部署） | | nos_accelerate_host | string | — | CDN 加速命中域名（私有化部署） |

获取凭证

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

登录网易云信控制台
创建或选择应用
在应用设置中复制 AppKey
创建机器人账号（而非普通个人账号）并获取 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",
});

目标格式

| 格式 | 说明 | | -------------- | --------------- | | user123 | 纯账号 ID | | nim:user123 | 带 nim: 前缀 | | user:user123 | 带 user: 前缀 |

支持的消息类型

| 类型 | 接收 | 发送 | | ------ | ---- | ---- | | 文本 | ✅ | ✅ | | 图片 | ✅ | ✅ | | 文件 | ✅ | ✅ | | 音频 | ✅ | ✅ | | 视频 | ✅ | ✅ | | 位置 | ✅ | ❌ | | 自定义 | ✅ | ❌ |

开发

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

# 监听模式
npm run dev

许可证

MIT