⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v1.2.0

onebot-ops

lstm-kirigaya@lstm-kirigaya⭐ 144 stars· last commit 6mo ago· 8 open issues

OneBot (QQ/Lagrange) 渠道运维与使用规范。消息收发通过 Channel outbound 与 deliver 完成,不依赖 Agent 工具。

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 144 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

openclaw-onebot

OpenClaw 的 OneBot v11 协议(QQ/Lagrange.Core、go-cqhttp 等)渠道插件。

npm version GitHub stars License: MIT Node.js TypeScript OpenClaw


安装

openclaw plugins install @kirigaya/openclaw-onebot
openclaw onebot setup

教程

让 QQ 接入 openclaw!让你的助手掌管千人大群

功能

  • ✅ 私聊:所有消息 AI 都会回复
  • ✅ 触发:支持 @触发 和基于关键字的触发
  • ✅ 自动获取上下文
  • ✅ 自定义新成员入群欢迎触发器
  • ✅ 自动合并转发长消息:超过阈值可渲染为图片发送或者合并发送
  • ✅ 支持文件,图像读取/发送
  • ✅ 支持黑白名单系统

安装 onebot 服务端

你需要安装 onebot 服务端,QQ 目前比较常用的是 onebot 服务端是 NapCat,可以查看 官网 了解安装方法

连接类型

类型说明
forward-websocket插件主动连接 OneBot(go-cqhttp、Lagrange.Core 正向 WS/WSS)
backward-websocket插件作为服务端,OneBot 连接过来

💡 提示:支持 ws:// 和 wss://(WebSocket Secure)协议,可填写完整 URL 如 wss://ws-napcatqq.example.com

环境变量

可替代配置文件,适用于 Lagrange 等:

变量说明
ONEBOT_WS_TYPEforward-websocket / backward-websocket
ONEBOT_WS_HOST主机地址
ONEBOT_WS_PORT端口
ONEBOT_WS_ACCESS_TOKEN访问令牌

使用

  1. 安装并配置
  2. 重启 Gateway:openclaw gateway restart
  3. 在 QQ 私聊或群聊中发消息(群聊需 @ 机器人,或配置关键字触发)

关键字触发回复

除了 @ 机器人外,还可以配置关键字检测,当群消息中包含指定关键字时自动触发回复(无需 @)。

{
  "channels": {
    "onebot": {
      "keywordTriggers": {
        "enabled": true,
        "keywords": ["AI", "助手", "帮我问"],
        "caseSensitive": false
      }
    }
  }
}
配置项说明
enabled是否启用关键字触发
keywords关键字列表,包含任一关键字即触发
caseSensitive是否区分大小写

长消息处理与 OG 图片渲染

当单次回复超过长消息阈值(默认 300 字)时,可选用三种模式(openclaw onebot setup 中配置):

模式说明
normal准流式分段发送:边生成边聚合,按时间窗口或长度阈值增量发送
og_image将 Markdown 转为 HTML 再生成图片发送(需安装 satori 和 sharp)
forward合并转发(发给自己后打包转发)

normal 模式默认会开启块流式接收,并在插件侧做短时间聚合,默认规则:

  • normalModeFlushIntervalMs: 1200
  • normalModeFlushChars: 160

也就是回复不会逐 token 刷屏,而是大约每 1.2 秒或累计到 160 字左右就发送一段。可在 openclaw.json 中手动调整:

{
  "channels": {
    "onebot": {
      "longMessageMode": "normal",
      "normalModeFlushIntervalMs": 1200,
      "normalModeFlushChars": 160
    }
  }
}

选择 生成图片发送(og_image) 时,会额外询问渲染主题:

选项说明
default无额外样式,默认白底黑字
dust内置主题:暖色、旧纸质感
custom自定义:在 ogImageRenderThemePath 中填写 CSS 文件绝对路径

配置项(枚举 + 可选路径):

  • ogImageRenderTheme:"default" | "dust" | "custom"
  • ogImageRenderThemePath:当为 custom 时必填,CSS 文件绝对路径

示例(openclaw.json):

{
  "channels": {
    "onebot": {
      "longMessageMode": "og_image",
      "longMessageThreshold": 300,
      "ogImageRenderTheme": "dust"
    }
  }
}

自定义主题示例:

{
  "channels": {
    "onebot": {
      "longMessageMode": "og_image",
      "ogImageRenderTheme": "custom",
      "ogImageRenderThemePath": "C:/path/to/your-theme.css"
    }
  }
}

主动发送消息

通过 openclaw message send CLI(无需 Agent 工具):

# 发送文本
openclaw message send --channel onebot --target user:123456789 --message "你好"

# 发送图片
openclaw message send --channel onebot --target group:987654321 --media "file:///path/to/image.png"

--target 格式:user:QQ号 或 group:群号。回复场景由 deliver 自动投递,Agent 输出 text/mediaUrl 即会送达。

新成员入群欢迎(自定义图片)

当有新成员加入群时,可根据其 ID 信息生成欢迎图片并发送。详见 receive.md。

  1. 在 openclaw.json 中配置:
{
  "channels": {
    "onebot": {
      "groupIncrease": {
        "enabled": true,
        "command": "npx tsx src/openclaw/trigger/welcome.ts",
        "cwd": "C:/path/to/Tiphareth"
      }
    }
  }
}
  1. command 在 cwd 下用系统 shell 执行,环境变量传入 GROUP_ID、GROUP_NAME、USER_ID、USER_NAME、AVATAR_URL。命令可调用 openclaw message send 自行发送,或向 stdout 输出 JSON 行供 handler 发送。

  2. 测试:npm run test:group-increase-handler(DRY_RUN 模式,仅生成图片)

回复白名单

默认为空回复所有人的消息。如果设置的话,那么机器人就只会回复设置的数组里的用户的消息。

{
  "channels": {
    "onebot": {
      "whitelistUserIds": [1193466151]
    }
  }
}

黑名单

在群里有时候有些人需要被屏蔽,不管他怎么 @ 还是怎么,都屏蔽他的消息不触发。

{
  "channels": {
    "onebot": {
      "blacklistUserIds": [123456789]
    }
  }
}

注意:白名单优先级高于黑名单。如果同时设置了白名单和黑名单,只有白名单内的用户才能触发,且黑名单内的白名单用户也会被屏蔽。

新人入群触发器

如果有人入群之后,可以通过这个来实现触发器。

{
  "channels": {
    "onebot": {
      "groupIncrease": {
        "enabled": true,
        "command": "npx tsx welcome.ts",
        "cwd": "/path/to/triggers"
      }
    }
  }
}

实现的脚本必须支持这三个参数:

--userId ${userId} --username ${username} --groupId ${groupId}

测试

测试连接

项目内提供测试脚本(需 .env 或环境变量):

cd openclaw-onebot
npm run test:connect

测试 OG 图片渲染效果

用于预览「Markdown 转图片」在不同主题下的渲染效果(需安装 satori 和 sharp):

cd openclaw-onebot
# 无额外样式
npm run test:render-og-image -- default
# 内置 dust 主题
npm run test:render-og-image -- dust
# 自定义 CSS 文件(绝对路径)
npm run test:render-og-image -- "C:/path/to/your-theme.css"

生成图片保存在 test/output-render-<主题>.png,可直接打开查看。

参考

联系

[email protected]

要是我不回你,可以选择进我的QQ群。782833642

License

MIT © LSTM-Kirigaya

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/onebot-ops/SKILL.md2.9 KBupstream ↗
    ---
    name: onebot-ops
    description: OneBot (QQ/Lagrange) 渠道运维与使用规范。消息收发通过 Channel outbound 与 deliver 完成,不依赖 Agent 工具。
    ---
    
    # OneBot 运维/使用规范
    
    OneBot v11 协议渠道,支持 QQ/Lagrange.Core/go-cqhttp。消息收发均通过 Channel 的 outbound 与 deliver 完成,**不依赖 Agent 工具**。
    
    ## 快速判断
    
    | 场景 | 说明 |
    |------|------|
    | **接收消息** | 私聊全回复,群聊默认仅 @ 回复,详见 [receive.md](receive.md) |
    | **message 工具 target** | 群聊必须用 `ctx.To`(格式 `group:群号`),勿用 SenderId |
    | **发送消息** | 使用 `openclaw message send` CLI,详见 [send.md](send.md) |
    | **配置** | 运行 `openclaw onebot setup` 或编辑 `openclaw.json`,详见 [config.md](config.md) |
    
    ## 插件安装
    
    ```bash
    openclaw plugins install @openclaw/onebot
    ```
    
    本地开发时:
    
    ```bash
    openclaw plugins install ./openclaw-onebot
    ```
    
    ## 前置条件
    
    - Gateway 已启动:`openclaw gateway`
    - OneBot 实现(Lagrange.Core / go-cqhttp)已运行并暴露 WebSocket
    - 在 `openclaw.json` 中配置 `channels.onebot` 或通过 `ONEBOT_WS_*` 环境变量
    
    ## OneBot 协议能力
    
    对应 Lagrange.onebot `context.ts` 的 API:
    
    | 能力 | 说明 |
    |------|------|
    | **send_private_msg** | 发送私聊消息 |
    | **send_group_msg** | 发送群消息 |
    | **send_msg** | 按 message_type 发送 |
    | **图片消息** | message 为 `[{ type: "image", data: { file } }]` |
    | **delete_msg** | 撤回消息 |
    | **get_msg** | 获取单条消息 |
    | **get_group_msg_history** | 获取群历史(Lagrange.Core 扩展),支持 reverse_order 分页 |
    | **upload_group_file** | 上传群文件 |
    | **upload_private_file** | 上传私聊文件 |
    | **set_msg_emoji_like** | 表情回应(Lagrange/QQ NT 扩展) |
    
    ## Agent 工具与 CLI
    
    插件提供群历史、按名字搜 QQ 等能力,既注册为 **Agent 工具**(供 Cron/脚本/AI 调用),也提供等价的 **CLI 命令**,便于 AI 与人工按文档调用。
    
    **详细说明与所有命令用法见:[agent-tools.md](agent-tools.md)**
    
    ### 常用 CLI 一览
    
    | 命令 | 说明 |
    |------|------|
    | `openclaw onebot setup` | 交互式配置 OneBot 连接 |
    | `openclaw onebot get-group-msg-history --group-id <群号> [--hours N]` | 获取群历史(单页或最近 N 小时内,从旧到新) |
    | `openclaw onebot search-group-member --group-id <群号> --name <名字>` | 按名字模糊搜群友 QQ 号 |
    | `openclaw onebot upload-file --target group:<群号> --file <路径> --name <文件名>` | 上传文件到群/私聊 |
    | `openclaw message send --channel onebot --target group:xxx --message "hi"` | 发送文本/图片 |
    | `openclaw gateway status` | 查看 Gateway 状态 |
    | `openclaw logs --follow` | 查看日志 |
    
    AI 或脚本需要「获取群历史、查群友 QQ」时,应使用上述 CLI 或查阅 [agent-tools.md](agent-tools.md) 中的完整参数说明。
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/lstm-kirigaya-openclaw-onebot-skills-onebot-ops.md

// REPO STATS

144 stars
8 open issues
Last commit: 6mo ago