@mili-wang/umibot

v0.0.1

Published

4 days ago

0High
0Medium
0Low

mili-wang

简体中文 | English

Umi Bot — OpenClaw 渠道插件

让你的 AI 助手接入 Umi — 私聊、群聊、富媒体，一个插件全搞定。

扫描二维码加入群聊，一起交流

✨ 功能特性

| 功能 | 说明 | |------|------| | 🔒 多场景支持 | C2C 私聊、群聊 @消息、频道消息、频道私信 | | 🖼️ 富媒体消息 | 支持图片、语音、视频、文件的收发 | | 🎙️ 语音能力 (STT/TTS) | 语音转文字自动转录 & 文字转语音回复 | | ⏰ 定时推送 | 支持定时任务触发后主动推送消息 | | 🔗 URL 无限制 | 私聊可直接发送 URL | | ⌨️ 输入状态 | 实时显示"Bot 正在输入中…"状态 | | 🔄 热更新 | 支持 npm 方式安装和无缝热更新 | | 📝 Markdown | 完整支持 Markdown 格式消息 | | 🛠️ 原生命令 | 支持 OpenClaw 原生命令 |

📸 功能展示

说明： 本插件仅作为消息通道，负责在 Umi 和 OpenClaw 之间传递消息。图片理解、语音转录、AI 画图等能力取决于你配置的 AI 模型以及在 OpenClaw 中安装的 skill，而非插件本身提供。

你：（发送一段语音）"明天深圳天气怎么样"
UmiBot：明天（3月7日周六）深圳的天气预报 🌤️ ...

你：（发送《战争与和平》TXT 文件）
UmiBot：收到！你上传了列夫·托尔斯泰的《战争与和平》中文版文本。从内容来看，这是第一章的开头……你想让我做什么？

你：（发送一张图片）
UmiBot：哈哈，好可爱！这是Umi企鹅穿上小龙虾套装吗？🦞🐧 ...

你：画一只猫咪
UmiBot：给你画好了！🐱

你：用语音讲个笑话
UmiBot：（发送一条语音消息）

你：战争与和平的第一章截取一下发文件给我
UmiBot：（发送 .txt 文件）

你：发一个演示视频给我
UmiBot：（发送视频）

富媒体能力（图片、语音、视频、文件）的完整说明请参阅富媒体指南。

⭐ Star History

🚀 快速开始

第一步 — 在 Umi 开放平台创建机器人

前往 Umi 开放平台，用手机 Umi 扫描页面二维码即可注册/登录。若尚未注册，扫码后系统会自动完成注册并绑定你的 Umi 账号。

手机 Umi 扫码后选择同意，即完成注册，进入 Umi 机器人配置页。
点击创建机器人，即可直接新建一个 Umi 机器人。

在机器人页面中找到 AppID 和 AppSecret，分别点击右侧复制按钮，保存到记事本或备忘录中。AppSecret 不支持明文保存，离开页面后再查看会强制重置，请务必妥善保存。

详细图文教程请参阅官方指南。

⚠️ 机器人创建后会自动出现在你的 Umi 消息列表中，并发送第一条消息。但在完成下面的配置之前，发消息会提示"该机器人去火星了"，属于正常现象。

第二步 — 安装插件

# 通过 OpenClaw CLI 安装（推荐）
openclaw plugins install @mili-wang/umibot@latest

# 或从源码安装
git clone https://github.com/mili-wang/umibot.git && cd umibot
openclaw plugins install .

第三步 — 配置 OpenClaw

方式一：通过 Wizard 配置（推荐）

openclaw channels add --channel umibot --token "AppID:AppSecret"

方式二：编辑配置文件

编辑 ~/.openclaw/openclaw.json：

{
  "channels": {
    "umibot": {
      "enabled": true,
      "appId": "你的 AppID",
      "clientSecret": "你的 AppSecret"
    }
  }
}

第四步 — 启动与测试

openclaw gateway

打开 Umi，找到你的机器人，发条消息试试！

🤖 多账户配置（Multi-Bot）

支持在同一个 OpenClaw 实例下同时运行多个 Umi 机器人。

配置方式

编辑 ~/.openclaw/openclaw.json，在 channels.umibot 下增加 accounts 字段：

{
  "channels": {
    "umibot": {
      "enabled": true,
      "appId": "111111111",
      "clientSecret": "secret-of-bot-1",

      "accounts": {
        "bot2": {
          "enabled": true,
          "appId": "222222222",
          "clientSecret": "secret-of-bot-2"
        },
        "bot3": {
          "enabled": true,
          "appId": "333333333",
          "clientSecret": "secret-of-bot-3"
        }
      }
    }
  }
}

说明：

顶层的 appId / clientSecret 是默认账户（accountId = "default"）
accounts 下的每个 key（如 bot2、bot3）就是该账户的 accountId
每个账户都可以独立配置 enabled、name、allowFrom、systemPrompt 等字段
也可以不配顶层默认账户，只在 accounts 里配置所有机器人

通过 CLI 添加第二个机器人（如果框架支持 --account 参数）：

openclaw channels add --channel umibot --account bot2 --token "222222222:secret-of-bot-2"

向指定账户的用户发送消息

使用 openclaw message send 发消息时，需要通过 --account 参数指定使用哪个机器人发送：

# 使用默认机器人发送（不指定 --account 时自动使用 default）
openclaw message send --channel "umibot" \
  --target "umibot:c2c:OPENID" \
  --message "hello from default bot"

# 使用 bot2 发送
openclaw message send --channel "umibot" \
  --account bot2 \
  --target "umibot:c2c:OPENID" \
  --message "hello from bot2"

Target 格式支持：

| 格式 | 说明 | |------|------| | umibot:c2c:OPENID | 私聊 | | umibot:group:GROUP_OPENID | 群聊 | | umibot:channel:CHANNEL_ID | 频道 |

⚠️ 注意：每个机器人的用户 OpenID 是不同的。机器人 A 收到的用户 OpenID 不能用机器人 B 去发消息，否则会返回 500 错误。必须用对应机器人的 accountId 去给该机器人的用户发消息。

工作原理

启动 openclaw gateway 后，所有 enabled: true 的账户会同时启动 WebSocket 连接
每个账户独立维护 Token 缓存（基于 appId 隔离），互不干扰
接收消息时，日志会带上 [umibot:accountId] 前缀方便排查

🎙️ 语音能力配置（可选）

STT（语音转文字）— 自动转录用户发来的语音消息

STT 支持两级配置，按优先级查找：

| 优先级 | 配置路径 | 作用域 | |--------|----------|--------| | 1（最高） | channels.umibot.stt | 插件专属 | | 2（回退） | tools.media.audio.models[0] | 框架级 |

{
  "channels": {
    "umibot": {
      "stt": {
        "provider": "your-provider",
        "model": "your-stt-model"
      }
    }
  }
}

provider — 引用 models.providers 中的 key，自动继承 baseUrl 和 apiKey
设置 enabled: false 可禁用
配置后，用户发来的语音消息会自动转换（SILK→WAV）并转录为文字

TTS（文字转语音）— 机器人发送语音消息

| 优先级 | 配置路径 | 作用域 | |--------|----------|--------| | 1（最高） | channels.umibot.tts | 插件专属 | | 2（回退） | messages.tts | 框架级 |

{
  "channels": {
    "umibot": {
      "tts": {
        "provider": "your-provider",
        "model": "your-tts-model",
        "voice": "your-voice"
      }
    }
  }
}

provider — 引用 models.providers 中的 key，自动继承 baseUrl 和 apiKey
voice — 语音音色
设置 enabled: false 可禁用（默认：true）
配置后，AI 可使用 <umivoice> 标签生成并发送语音消息

🔄 升级

通过 OpenClaw / npm 升级（推荐）

仅适用于通过 openclaw plugins install 安装的场景

openclaw plugins upgrade @mili-wang/umibot@latest

通过 npx 升级

npx -y @mili-wang/umibot@latest upgrade

通过 upgrade-and-run.sh 一键升级

bash ./upgrade-and-run.sh

不传 --appid / --secret 参数时，脚本会自动读取 ~/.openclaw/openclaw.json 中已有的配置。

# 首次配置或需要覆盖时
bash ./upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET

| 选项 | 说明 | |------|------| | --appid <id> | Umi 机器人 AppID | | --secret <secret> | Umi 机器人 AppSecret | | --markdown <yes\|no> | 是否启用 Markdown 消息格式（默认: no） | | -h, --help | 显示帮助 |

也支持环境变量：UmiBOT_APPID、UmiBOT_SECRET、UmiBOT_TOKEN（AppID:Secret）。

通过 pull-latest.sh（Git 源码更新）

bash ./pull-latest.sh

bash ./pull-latest.sh --branch main            # 指定分支（默认 main）
bash ./pull-latest.sh --force                   # 跳过交互，强制更新
bash ./pull-latest.sh --repo <git-url>          # 使用其他仓库地址

从源码升级（手动）

git clone https://github.com/mili-wang/umibot.git && cd umibot
bash ./scripts/upgrade.sh
openclaw plugins install .
openclaw channels add --channel umibot --token "AppID:AppSecret"
openclaw gateway restart

📚 文档

富媒体指南 — 图片、语音、视频、文件
命令参考 — OpenClaw CLI 常用命令
更新日志 — 各版本变更记录（最新: 1.5.4）