@hyl_aa/openclaw-napcat 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 HylAa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# openclaw-napcat
+
+[English](./README_EN.md) | 中文
+
+OpenClaw 的 QQ 消息通道插件，基于 [NapCat](https://github.com/NapNeko/NapCatQQ) 的 OneBot 11 反向 WebSocket 协议。
+
+让 AI 助手通过自然语言完全控制 QQ 交互 —— 点赞、戳一戳、禁言、踢人、查看用户资料、管理群组等。
+
+## 功能特性
+
+- **17 个 AI Agent 工具** —— AI 通过自然语言指令执行 QQ 操作
+- **语音转文字 (STT)** —— 自动将语音消息转录为文字后发送给 AI
+- **@提及识别** —— 自动识别消息中的 `@QQ号` 并映射到用户 ID
+- **群管理** —— 完整的管理工具集：禁言、踢人、设置管理员、改群名、发公告
+- **多账号支持** —— 支持配置多个 NapCat 机器人账号
+
+## Agent 工具列表
+
+| 工具 | 功能 | 仅群主 |
+|------|------|:------:|
+| `qq_like_user` | 给用户点赞 | |
+| `qq_get_user_info` | 获取用户资料（昵称、年龄、签名等） | |
+| `qq_get_group_info` | 获取群信息（群名、成员数） | |
+| `qq_get_group_member_info` | 获取群内某成员的详细信息 | |
+| `qq_get_friend_list` | 获取机器人好友列表 | |
+| `qq_get_group_list` | 获取机器人群列表 | |
+| `qq_get_group_member_list` | 获取群全部成员列表 | |
+| `qq_get_group_honor_info` | 获取群荣誉信息（龙王等） | |
+| `qq_poke` | 戳一戳 | |
+| `qq_mute_group_member` | 禁言群成员 | Yes |
+| `qq_kick_group_member` | 踢出群成员 | Yes |
+| `qq_recall_message` | 撤回消息 | Yes |
+| `qq_set_group_card` | 设置群名片 | Yes |
+| `qq_set_group_admin` | 设置/取消群管理员 | Yes |
+| `qq_set_group_name` | 修改群名称 | Yes |
+| `qq_set_group_whole_ban` | 全员禁言开关 | Yes |
+| `qq_send_group_notice` | 发送群公告 | Yes |
+
+## 前置要求
+
+- 已安装并运行 [OpenClaw](https://github.com/openclaw/openclaw)
+- 已运行 [NapCat](https://github.com/NapNeko/NapCatQQ) 并开启 HTTP API
+- Node.js 22+
+
+## 安装
+
+```bash
+openclaw install extensions/napcat
+```
+
+或者手动克隆到 OpenClaw 扩展目录：
+
+```bash
+cd ~/.openclaw/extensions
+git clone https://github.com/HylAa/openclaw-napcat.git napcat
+cd napcat && npm install --omit=dev
+```
+
+## 配置
+
+在 OpenClaw 配置中添加（`openclaw config edit`）：
+
+```json
+{
+  "channels": {
+    "napcat": {
+      "httpApi": "http://127.0.0.1:3000",
+      "accessToken": "你的token",
+      "selfId": "123456789",
+      "dmPolicy": "allowlist",
+      "allowFrom": ["好友QQ号"],
+      "groupPolicy": "allowlist",
+      "groupAllowFrom": ["群号"]
+    }
+  }
+}
+```
+
+### 配置字段说明
+
+| 字段 | 说明 |
+|------|------|
+| `httpApi` | NapCat OneBot 11 HTTP API 地址 |
+| `accessToken` | API 鉴权 token（可选） |
+| `selfId` | 机器人自身 QQ 号（用于 @机器人检测） |
+| `dmPolicy` | 私聊策略：`allowlist` / `pairing` / `open` / `disabled` |
+| `allowFrom` | 允许私聊的 QQ 号列表 |
+| `groupPolicy` | 群聊策略：`allowlist` / `open` / `disabled` |
+| `groupAllowFrom` | 允许在群聊中触发的 QQ 号列表 |
+
+**重要：** 需要在 OpenClaw 配置中将 `tools.profile` 设置为 `"full"`，否则 `qq_*` 工具会被默认的 `"coding"` profile 过滤掉。
+
+## 使用示例
+
+配置完成后，直接在 QQ 中与 AI 对话即可：
+
+- "帮我给 3870871935 点赞" —— AI 调用 `qq_like_user`
+- "帮我分析 @某人 的签名" —— AI 从 @提及中提取 QQ 号，调用 `qq_get_user_info`
+- "查看群成员列表" —— AI 调用 `qq_get_group_member_list`
+- "把 @某人 禁言10分钟" —— AI 调用 `qq_mute_group_member`（仅群主）
+- "发个群公告：明天开会" —— AI 调用 `qq_send_group_notice`（仅群主）
+
+## 语音消息
+
+启用语音 STT 后（`tools.media.audio.enabled: true`），语音消息会自动转录为文字再发送给 AI 模型。
+
+## 项目结构
+
+```
+.
+├── index.ts                 # 插件入口
+├── package.json
+├── openclaw.plugin.json     # 插件元数据
+└── src/
+    ├── accounts.ts          # 多账号解析
+    ├── api.ts               # OneBot 11 HTTP API 客户端
+    ├── channel.ts           # Channel 插件与 Dock 定义
+    ├── config-schema.ts     # 配置 JSON Schema + UI 提示
+    ├── monitor.ts           # WebSocket 消息监听 + STT
+    ├── probe.ts             # 连接探测 / 健康检查
+    ├── runtime.ts           # 运行时上下文
+    ├── send.ts              # 消息发送
+    ├── tools.ts             # 17 个 AI Agent 工具
+    └── types.ts             # TypeScript 类型定义
+```
+
+## 许可证
+
+MIT

package/README_EN.md

@@ -0,0 +1,129 @@
+# openclaw-napcat
+
+English | [中文](./README.md)
+
+OpenClaw extension for QQ messaging via [NapCat](https://github.com/NapNeko/NapCatQQ) (OneBot 11 reverse WebSocket).
+
+Let your AI assistant fully control QQ interactions through natural language -- like, poke, mute, kick, query user profiles, manage groups, and more.
+
+## Features
+
+- **17 AI Agent Tools** -- AI can execute QQ actions via natural language commands
+- **Voice-to-Text (STT)** -- Auto-transcribes voice messages before sending to AI
+- **@Mention Resolution** -- Recognizes `@QQNumber` in messages and maps to user IDs
+- **Group Management** -- Full admin toolkit: mute, kick, set admin, rename group, announcements
+- **Multi-Account** -- Supports multiple NapCat bot accounts
+
+## Agent Tools
+
+| Tool | Description | Owner Only |
+|------|-------------|:----------:|
+| `qq_like_user` | Give a user thumbs-up (like) | |
+| `qq_get_user_info` | Get user profile (nickname, age, signature, etc.) | |
+| `qq_get_group_info` | Get group info (name, member count) | |
+| `qq_get_group_member_info` | Get a member's info within a group | |
+| `qq_get_friend_list` | Get bot's friend list | |
+| `qq_get_group_list` | Get bot's group list | |
+| `qq_get_group_member_list` | Get all members of a group | |
+| `qq_get_group_honor_info` | Get group honor/achievements (Dragon King, etc.) | |
+| `qq_poke` | Send a poke/nudge to a user | |
+| `qq_mute_group_member` | Mute a member for specified duration | Yes |
+| `qq_kick_group_member` | Kick a member from a group | Yes |
+| `qq_recall_message` | Recall (delete) a sent message | Yes |
+| `qq_set_group_card` | Set member's display name in group | Yes |
+| `qq_set_group_admin` | Set/unset group admin | Yes |
+| `qq_set_group_name` | Change group name | Yes |
+| `qq_set_group_whole_ban` | Toggle whole-group mute | Yes |
+| `qq_send_group_notice` | Send group announcement | Yes |
+
+## Prerequisites
+
+- [OpenClaw](https://github.com/openclaw/openclaw) installed and running
+- [NapCat](https://github.com/NapNeko/NapCatQQ) running with HTTP API enabled
+- Node.js 22+
+
+## Installation
+
+```bash
+openclaw install extensions/napcat
+```
+
+Or clone this repo into your OpenClaw extensions directory:
+
+```bash
+cd ~/.openclaw/extensions
+git clone https://github.com/HylAa/openclaw-napcat.git napcat
+cd napcat && npm install --omit=dev
+```
+
+## Configuration
+
+Add to your OpenClaw config (`openclaw config edit`):
+
+```json
+{
+  "channels": {
+    "napcat": {
+      "httpApi": "http://127.0.0.1:3000",
+      "accessToken": "your-token-here",
+      "selfId": "123456789",
+      "dmPolicy": "allowlist",
+      "allowFrom": ["friend_qq_number"],
+      "groupPolicy": "allowlist",
+      "groupAllowFrom": ["group_number"]
+    }
+  }
+}
+```
+
+### Config Fields
+
+| Field | Description |
+|-------|-------------|
+| `httpApi` | NapCat OneBot 11 HTTP API address |
+| `accessToken` | API auth token (optional) |
+| `selfId` | Bot's own QQ number (for @mention detection) |
+| `dmPolicy` | DM policy: `allowlist` / `pairing` / `open` / `disabled` |
+| `allowFrom` | Allowed QQ numbers for DM |
+| `groupPolicy` | Group policy: `allowlist` / `open` / `disabled` |
+| `groupAllowFrom` | Allowed QQ numbers in groups |
+
+**Important:** Set `tools.profile` to `"full"` in your OpenClaw config, otherwise `qq_*` tools will be filtered out by the default `"coding"` profile.
+
+## Usage Examples
+
+Once configured, just talk to your AI in QQ:
+
+- "Help me like user 3870871935" -- AI calls `qq_like_user`
+- "Analyze @someone's signature" -- AI extracts QQ number from @mention, calls `qq_get_user_info`
+- "Show group member list" -- AI calls `qq_get_group_member_list`
+- "Mute @someone for 10 minutes" -- AI calls `qq_mute_group_member` (owner only)
+- "Post a group announcement: meeting tomorrow" -- AI calls `qq_send_group_notice` (owner only)
+
+## Voice Messages
+
+When voice STT is enabled (`tools.media.audio.enabled: true`), voice messages are automatically transcribed to text before being sent to the AI model.
+
+## Project Structure
+
+```
+.
+├── index.ts                 # Plugin entry point
+├── package.json
+├── openclaw.plugin.json     # Plugin metadata
+└── src/
+    ├── accounts.ts          # Multi-account resolution
+    ├── api.ts               # OneBot 11 HTTP API client
+    ├── channel.ts           # Channel plugin & dock definition
+    ├── config-schema.ts     # Config JSON Schema + UI hints
+    ├── monitor.ts           # WebSocket message monitor + STT
+    ├── probe.ts             # Connection probe / health check
+    ├── runtime.ts           # Runtime context
+    ├── send.ts              # Outbound message sending
+    ├── tools.ts             # 17 AI agent tools
+    └── types.ts             # TypeScript type definitions
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { napCatDock, napCatPlugin } from "./src/channel.js";
+import { setNapCatRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "napcat",
+  name: "QQ (NapCat)",
+  description: "QQ channel plugin via NapCat (OneBot 11 reverse WebSocket)",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setNapCatRuntime(api.runtime);
+    api.registerChannel({ plugin: napCatPlugin, dock: napCatDock });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "napcat",
+  "channels": ["napcat"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@hyl_aa/openclaw-napcat",
+  "version": "0.1.0",
+  "description": "OpenClaw QQ channel plugin via NapCat (OneBot 11)",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HylAa/openclaw-napcat.git"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "qq",
+    "napcat",
+    "onebot",
+    "chatbot"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "napcat",
+      "label": "QQ (NapCat)",
+      "selectionLabel": "QQ via NapCat (OneBot 11)",
+      "docsPath": "/channels/napcat",
+      "docsLabel": "napcat",
+      "blurb": "QQ messaging via NapCat OneBot 11 reverse WebSocket.",
+      "aliases": [
+        "qq",
+        "onebot"
+      ],
+      "order": 90,
+      "quickstartAllowFrom": true
+    },
+    "install": {
+      "npmSpec": "@hyl_aa/openclaw-napcat",
+      "localPath": "extensions/napcat",
+      "defaultChoice": "npm"
+    }
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,101 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  normalizeResolvedSecretInputString,
+} from "openclaw/plugin-sdk";
+import type { NapCatAccountConfig, NapCatConfig, ResolvedNapCatAccount } from "./types.js";
+
+function getNapCatSection(cfg: OpenClawConfig): NapCatConfig | undefined {
+  return (cfg as Record<string, unknown>).channels?.napcat as NapCatConfig | undefined;
+}
+
+function mergeNapCatAccountConfig(
+  cfg: OpenClawConfig,
+  accountId: string,
+): NapCatAccountConfig {
+  const section = getNapCatSection(cfg);
+  if (!section) return {};
+
+  const base: NapCatAccountConfig = {
+    name: section.name,
+    enabled: section.enabled,
+    httpApi: section.httpApi,
+    accessToken: section.accessToken,
+    selfId: section.selfId,
+    dmPolicy: section.dmPolicy,
+    allowFrom: section.allowFrom,
+    groupPolicy: section.groupPolicy,
+    groupAllowFrom: section.groupAllowFrom,
+    mediaMaxMb: section.mediaMaxMb,
+    responsePrefix: section.responsePrefix,
+  };
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return base;
+  }
+
+  const accountConfig = section.accounts?.[accountId];
+  if (!accountConfig) return base;
+
+  // Account-level overrides base-level
+  return {
+    ...base,
+    ...Object.fromEntries(
+      Object.entries(accountConfig).filter(([, v]) => v !== undefined),
+    ),
+  };
+}
+
+export function resolveNapCatAccount(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): ResolvedNapCatAccount {
+  const accountId = normalizeAccountId(params.accountId);
+  const config = mergeNapCatAccountConfig(params.cfg, accountId);
+  const section = getNapCatSection(params.cfg);
+
+  const baseEnabled = section?.enabled !== false;
+  const accountEnabled = config.enabled !== false;
+  const enabled = baseEnabled && accountEnabled;
+
+  const httpApi = (config.httpApi ?? "").trim();
+  const accessToken = normalizeResolvedSecretInputString(config.accessToken) ?? "";
+  const selfId = String(config.selfId ?? "").trim();
+
+  return {
+    accountId,
+    name: config.name?.trim(),
+    enabled,
+    httpApi,
+    accessToken,
+    selfId,
+    config,
+  };
+}
+
+export function listNapCatAccountIds(cfg: OpenClawConfig): string[] {
+  const section = getNapCatSection(cfg);
+  if (!section) return [];
+
+  const ids = new Set<string>();
+  // Base config counts as default account
+  if (section.httpApi || section.accessToken || section.selfId) {
+    ids.add(DEFAULT_ACCOUNT_ID);
+  }
+  if (section.accounts) {
+    for (const id of Object.keys(section.accounts)) {
+      ids.add(normalizeAccountId(id));
+    }
+  }
+  if (ids.size === 0) ids.add(DEFAULT_ACCOUNT_ID);
+  return [...ids];
+}
+
+export function resolveDefaultNapCatAccountId(cfg: OpenClawConfig): string {
+  const section = getNapCatSection(cfg);
+  if (section?.defaultAccount) {
+    return normalizeAccountId(section.defaultAccount);
+  }
+  return DEFAULT_ACCOUNT_ID;
+}

package/src/api.ts

@@ -0,0 +1,134 @@
+import type {
+  OneBotApiResponse,
+  OneBotLoginInfo,
+  OneBotSegment,
+  OneBotSendMsgResult,
+} from "./types.js";
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export class OneBotApiError extends Error {
+  constructor(
+    public readonly retcode: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "OneBotApiError";
+  }
+}
+
+/**
+ * Call OneBot 11 HTTP API.
+ * NapCat exposes HTTP endpoints at `{baseUrl}/{action}`.
+ */
+export async function callOneBotApi<T>(
+  baseUrl: string,
+  action: string,
+  params: Record<string, unknown> = {},
+  options?: { accessToken?: string; timeoutMs?: number },
+): Promise<OneBotApiResponse<T>> {
+  const url = `${baseUrl.replace(/\/+$/, "")}/${action}`;
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (options?.accessToken) {
+    headers["Authorization"] = `Bearer ${options.accessToken}`;
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(
+    () => controller.abort(),
+    options?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  );
+
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(params),
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      throw new OneBotApiError(res.status, `HTTP ${res.status}: ${res.statusText}`);
+    }
+
+    const data = (await res.json()) as OneBotApiResponse<T>;
+    if (data.retcode !== 0) {
+      throw new OneBotApiError(
+        data.retcode,
+        `OneBot API error: retcode=${data.retcode} status=${data.status}`,
+      );
+    }
+
+    return data;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/** Get bot login info (QQ number + nickname). */
+export async function getLoginInfo(
+  baseUrl: string,
+  accessToken?: string,
+): Promise<OneBotLoginInfo> {
+  const resp = await callOneBotApi<OneBotLoginInfo>(baseUrl, "get_login_info", {}, { accessToken });
+  return resp.data;
+}
+
+/** Send a private message. */
+export async function sendPrivateMsg(
+  baseUrl: string,
+  userId: number,
+  message: OneBotSegment[],
+  accessToken?: string,
+): Promise<OneBotSendMsgResult> {
+  const resp = await callOneBotApi<OneBotSendMsgResult>(
+    baseUrl,
+    "send_private_msg",
+    { user_id: userId, message },
+    { accessToken },
+  );
+  return resp.data;
+}
+
+/** Send a group message. */
+export async function sendGroupMsg(
+  baseUrl: string,
+  groupId: number,
+  message: OneBotSegment[],
+  accessToken?: string,
+): Promise<OneBotSendMsgResult> {
+  const resp = await callOneBotApi<OneBotSendMsgResult>(
+    baseUrl,
+    "send_group_msg",
+    { group_id: groupId, message },
+    { accessToken },
+  );
+  return resp.data;
+}
+
+/** Build a text message segment. */
+export function textSegment(text: string): OneBotSegment {
+  return { type: "text", data: { text } };
+}
+
+/** Build an image message segment. */
+export function imageSegment(fileUrl: string): OneBotSegment {
+  return { type: "image", data: { file: fileUrl } };
+}
+
+/** Build an @mention segment. */
+export function atSegment(qq: string | number): OneBotSegment {
+  return { type: "at", data: { qq: String(qq) } };
+}
+
+/** Build a reply (quote) segment referencing an earlier message. */
+export function replySegment(messageId: number | string): OneBotSegment {
+  return { type: "reply", data: { id: String(messageId) } };
+}
+
+/** Build a voice/record message segment. */
+export function recordSegment(fileUrl: string): OneBotSegment {
+  return { type: "record", data: { file: fileUrl } };
+}