KOOK

KOOK（开黑啦）开发者平台官方机器人。WebSocket 网关 + HTTP 发送，支持文本 / 图片 / 视频 / 文件 / kmarkdown。国内可直连。

适配器类型："kook"　源码：src/adapter/kook/ 协议：KOOK 开发者平台官方机器人（WebSocket 网关 + HTTP 发送）。

说明

特点

• WebSocket 网关接收事件，国内可直连，无需公网回调
• 支持文本、KMarkdown、图片、视频、文件
• 支持频道消息和私聊消息
• 消息配额：单日 10,000 条/开发者账号

原理

• 接收：WebSocket 网关订阅事件，KOOK 推送消息/系统事件
• 发送：POST https://www.kookapp.cn/api/v3/message/create
• 图片需先通过 /api/v3/asset/create 上传获取 KOOK 资源 URL

前提

• KOOK 开发者中心创建应用，获取机器人 Token
• 连接模式选 WebSocket
• 机器人已加入目标服务器

安装

适配器安装

van adapter install kook

依赖库

npm install ws

配置

{
  "botId": "KOOK-Bot",
  "type": "kook",
  "token": "你的KOOK机器人Token",
  "reconnectDelay": 5000
}

配置项	必填	说明
token	✅	KOOK 开发者平台机器人 Token
reconnectDelay	可选	断线重连毫秒，默认 5000

接收事件

KOOK 事件	框架事件	说明
消息事件（文字/KMarkdown），channel_type=GROUP	group_message	频道消息，groupId=频道id
消息事件，channel_type=PERSON	private_message	私聊机器人
消息事件（图片/视频/文件）	同上	富媒体消息
系统事件（d.type=255）	notice	进服务器/被移出/角色变动等

事件对象字段：

{
  botId: "KOOK-Bot",
  selfId: "机器人用户id",
  userId: "author_id",
  groupId: "频道id",
  message: [{ type: "text", data: { text: "..." } }],
  postType: "group_message" | "private_message" | "notice",
  raw: { ...原始事件, sender, message_id, time, platform: "kook" }
}

API 调用

发送消息

// 频道消息
await bot.callApi("send_group_msg", { group_id: "频道id", message: "大家好" })

// 私聊消息
await bot.callApi("send_private_msg", { user_id: "用户id", message: "你好" })

// 自动判断
await bot.callApi("send_msg", { group_id: "...", user_id: "...", message: "..." })

消息段

• 文本 → text 段（以 KMarkdown type=9 发送，兼容纯文本与 markdown）
• markdown → { type: "markdown", data: { content: "..." } }，以 KMarkdown 发送
• 图片 → image 段（data.url 需为公网 url 或 base64://；KOOK 要求图片由机器人上传）
• @人 → at 段自动转换为 (met)用户id(met) 语法

常见问题

• 收不到消息：确认机器人已加入服务器、连接模式为 WebSocket，且机器人有对应频道权限。
• 发不出图片：KOOK 规定图片必须是机器人通过 /api/v3/asset/create 上传的资源，普通外链会被拒绝。
• 消息配额：单日 10,000 条/开发者账号。

相关项目

• KOOK 开发者中心：https://developer.kookapp.cn/
• WebSocket 协议：https://developer.kookapp.cn/doc/websocket