OpenClaw + NapCat：QQ 机器人 AI 接入实战

难度：入门 | 时长：25 分钟 | 收获：用 NapCat 把 QQ 接入 OpenClaw，获得 45 个 AI 工具控制能力

---

目标读者

你已经在用 OpenClaw，感受过它通过 Telegram、Discord 或其他平台替你处理任务的体验。现在你想更进一步——让 AI 直接接管 QQ：用自然语言在群里发公告、查成员、禁言、点赞，在私聊里操控机器人行为。

NapCat 是一个基于 QQ（通过 OneBot 11 协议）的桥梁，而 @hyl_aa/napcat 是把它接入 OpenClaw 的官方 channel 插件。装好之后，你的 QQ 机器人就变成了一个 AI Agent，45 个工具直接可用。

本文适合：

• 已部署 OpenClaw，想增加 QQ 作为交互入口
• 想让 AI 在 QQ 群里执行管理操作（禁言、踢人、发公告等）
• 有过 OneBot 或 QQ 机器人开发经验，想快速接入 OpenClaw

---

核心依赖与环境

GitHub 仓库：https://github.com/Aliang1337/openclaw-napcat

---

完整项目结构

@hyl_aa/napcat 插件安装后，目录结构如下：

napcat/
├── index.ts                    # 插件入口
├── openclaw.plugin.json        # 插件元数据
├── package.json
└── src/
    ├── channel.ts              # Channel 插件与 Dock 定义（消息收发核心）
    ├── tools.ts                # 45 个 AI Agent 工具注册
    ├── api.ts                  # OneBot 11 HTTP API 客户端
    ├── monitor.ts              # WebSocket 消息监听 + STT 语音处理
    ├── accounts.ts             # 多账号解析
    ├── config-schema.ts        # 配置 JSON Schema + UI 提示
    ├── probe.ts                # 连接探测 / 健康检查
    ├── runtime.ts              # 运行时上下文
    ├── send.ts                 # 消息发送
    └── types.ts                # TypeScript 类型定义

---

手把手步骤

Step 1：安装 NapCat 并完成 QQ 账号登录

这一步跟 OpenClaw 完全无关，是 NapCat 自己的安装流程。我们先把这个跑通。

去 NapCat 官方仓库 找到对应 QQ 客户端版本的 release 下载包，按文档说明完成安装。关键要求只有一个：账号必须成功登录，机器人要在线。

---

Step 2：配置 NapCat 开启 HTTP API + 反向 WebSocket

NapCat 启动后，需要开启两个通道：

HTTP API（插件主动发送消息用，默认端口 3000）：

{
  "httpApi": {
    "enable": true,
    "port": 3000
  }
}

反向 WebSocket（接收 QQ 消息，推给 OpenClaw）：

{
  "reverseWs": {
    "enable": true,
    "urls": ["ws://127.0.0.1:18800"]
  }
}

18800 是 OpenClaw 分配给 NapCat channel 的默认 WS 端口，插件会在启动时监听这个端口。如果配置了多账号，端口会依次递增（18800、18801、18802……），对应 channelId 分别为 napcat、napcat_1、napcat_2。

修改配置后重启 NapCat 使其生效。

---

Step 3：安装 @hyl_aa/napcat 插件

两种方式：

方式一：从 npm 安装（推荐）

openclaw plugins install @hyl_aa/napcat

方式二：手动克隆

cd ~/.openclaw/extensions
git clone https://github.com/Aliang1337/openclaw-napcat.git napcat
cd napcat && npm install --omit=dev

安装完成后重启 OpenClaw：

openclaw gateway restart

---

Step 4：在 OpenClaw 配置 NapCat channel

用 openclaw config edit 打开配置文件，添加 channels.napcat 配置块：

{
  "channels": {
    "napcat": {
      "httpApi": "http://127.0.0.1:3000",
      "accessToken": "你的token",
      "selfId": "123456789",
      "dmPolicy": "allowlist",
      "allowFrom": ["好友QQ号"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["群号"]
    }
  }
}

逐个字段说明：

---

Step 5：配置 dmPolicy / groupPolicy 访问策略

这两个字段控制谁可以和 AI 交互，是最重要的安全配置：

dmPolicy（私聊策略）：

groupPolicy（群聊策略）：

allowFrom / groupAllowFrom：

• allowFrom：私聊白名单，填入允许私聊的 QQ 号（格式为字符串数字）
• groupAllowFrom：群聊白名单，填入允许触发 AI 的群号；留空则使用 allowFrom 的值

最常见的配置——只让特定群和特定好友用 AI：

{
  "channels": {
    "napcat": {
      "dmPolicy": "allowlist",
      "allowFrom": ["10001", "10002"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["987654321"]
    }
  }
}

---

Step 6：将 tools.profile 设为 "full"

这是最容易踩的坑。OpenClaw 默认的 tools.profile 是 "coding"，这个 profile 会过滤掉大部分 qq_* 工具，导致 AI 说"我没有这个能力"。

在配置里加上：

{
  "tools": {
    "profile": "full"
  }
}

"full" profile 会把所有 channel 提供的工具（包括全部 45 个 qq_* 工具）暴露给 AI 模型。

---

Step 7：重启 OpenClaw 并验证连接

openclaw gateway restart
openclaw gateway status

检查日志里有没有 NapCat channel 的连接成功信息。如果看到类似 "napcat connected" 或 "reverse ws connected" 的字样，说明 NapCat 和 OpenClaw 之间的 WebSocket 通道已经建立。

你也可以让机器人给你发一条测试消息——在 NapCat 的 HTTP API 接口正常的情况下，OpenClaw 可以主动推送消息到 QQ：

# 手动测试：让 AI 给你发一条消息
# 在 QQ 私聊里直接发："你好"
# AI 应该回复

如果私聊没有反应，跳到「常见问题排查」Step 1 先排查。

---

Step 8：在 QQ 里调用 AI 工具

连接验证正常之后，你就可以在 QQ 里用自然语言驱动 AI 操作了。以下是一些典型场景：

发消息和公告：

"在群里发一条公告：明天晚上8点开会"
"发群公告：本周末活动取消"

AI 会调用 qq_send_group_notice，前提是机器人有群主/管理员权限。

群成员管理：

"把 @某人 禁言10分钟"
"把那个人踢出群"
"把张三设为群管理员"

对应的工具分别是 qq_mute_group_member、qq_kick_group_member、qq_set_group_admin。

查询类操作：

"查看群成员列表"
"看看这个群最近30条聊天记录"
"查一下 @某人 的资料"

AI 会调用 qq_get_group_member_list、qq_get_group_msg_history、qq_get_user_info。

精华消息和文件：

"把这条消息设为精华"
"看看群文件里有什么"

给消息点赞、戳一戳：

"给 3870871935 点赞"
"戳一下 @某人"

---

常见问题排查

1. WebSocket 连接失败

表现：OpenClaw 日志里没有 "napcat connected"，机器人没有响应消息。

排查步骤：

# 1. 检查 NapCat 是否正常运行
curl http://127.0.0.1:3000/get_version_info
# 正常返回版本信息，说明 NapCat HTTP API 可达

# 2. 检查反向 WS 端口是否被占用
netstat -an | grep 18800
# 如果有其他进程占用了这个端口，NapCat 连不上

# 3. 确认 NapCat 配置中的 WS 地址是否正确
# 必须和 OpenClaw 分配的端口一致，默认是 ws://127.0.0.1:18800

确保 NapCat 配置里的 reverseWs.urls 指向的端口和 OpenClaw 监听的一致。

---

2. accessToken 鉴权失败

表现：HTTP 请求返回 401，或者日志里有 "unauthorized" 错误。

检查 NapCat 端的 token 配置和 OpenClaw 端的 accessToken 字段是否一致。如果 NapCat 没有开启 token 验证，OpenClaw 端也留空 accessToken 字段。

// NapCat 端（如果有 token）
"accessToken": "my-secret-token"

// OpenClaw 端必须保持一致
"accessToken": "my-secret-token"

---

3. @机器人 无法识别

表现：在群里发了 "@机器人 你好" 但 AI 没有响应。

排查顺序：

1. 确认 selfId 配置的是机器人自己的 QQ 号，且完全正确
2. 确认 groupPolicy 不是 disabled，且群号在 groupAllowFrom 列表里（如果是 allowlist 模式）
3. 确认 @ 的格式是 "@机器人昵称"（不是 @"机器人" 或者其他变体）
4. 检查 OpenClaw 的 prompt 里是否正确配置了 @hyl_aa/napcat 的 channel 接入

---

4. 工具被 profile 过滤（qq_* 全部不可用）

表现：AI 回复"我不具备这个能力"，但配置看起来没问题。

这是最常见的坑。默认 tools.profile: "coding" 会过滤掉绝大多数 channel 工具。

{
  "tools": {
    "profile": "full"
  }
}

改完之后重启 OpenClaw，然后重新在 QQ 里触发一次。

---

5. 多账号端口冲突

表现：配置了第二个 NapCat 账号，但第二个机器人收不到消息。

NapCat 多账号时，HTTP API 端口和反向 WS 端口都需要递增：

// 第一个账号
{
  "httpApi": { "port": 3000 },
  "reverseWs": { "urls": ["ws://127.0.0.1:18800"] }
}

// 第二个账号
{
  "httpApi": { "port": 3001 },
  "reverseWs": { "urls": ["ws://127.0.0.1:18801"] }
}

OpenClaw 端也需要配置多账号映射：

{
  "channels": {
    "napcat": {
      "defaultAccount": "bot1",
      "accounts": {
        "bot1": {
          "name": "主号",
          "httpApi": "http://127.0.0.1:3000",
          "selfId": "111111111",
          "accessToken": "token1"
        },
        "bot2": {
          "name": "小号",
          "httpApi": "http://127.0.0.1:3001",
          "selfId": "222222222"
        }
      }
    }
  }
}

---

6. dmPolicy / groupPolicy 策略导致消息无响应

表现：私聊或群里完全没有反应，AI 似乎没有收到消息。

最常见的原因是策略配置过于严格：

• dmPolicy: "allowlist" 但 allowFrom 是空数组 → 没有任何人能触发私聊
• groupPolicy: "allowlist" 但 groupAllowFrom 是空数组 → 没有任何群能触发

临时放宽策略来确认是不是这个问题：

{
  "channels": {
    "napcat": {
      "dmPolicy": "open",
      "groupPolicy": "open"
    }
  }
}

如果改成 open 之后能正常响应，说明问题出在白名单配置上，再回来精确填 allowFrom 和 groupAllowFrom。

---

扩展阅读 / 进阶方向

1. 多账号配置与协作

OpenClaw 支持同时运行多个 NapCat 机器人账号，每个账号有独立的配置。在 accounts 块里定义后，可以用 /clawspec worker <account-id> 之类的方式在账号间切换（如果配合 ClawSpec 使用）。多账号适合：一个账号当客服，一个账号当管理 bot，互不干扰。

2. 语音消息 STT 配置

如果希望 AI 能处理语音消息，在 OpenClaw 配置里开启音频 STT：

{
  "tools": {
    "media": {
      "audio": {
        "enabled": true
      }
    }
  }
}

开启后，QQ 里的语音消息会自动转录为文字，再发送给 AI 模型处理。对应的 NapCat 需要在消息事件里正确上报语音文件的下载链接。

3. 自定义 AI 回复前缀

通过 responsePrefix 可以给 AI 的每条回复加上统一前缀：

{
  "channels": {
    "napcat": {
      "responsePrefix": "[AI]"
    }
  }
}

AI 的回复会变成 "[AI] 你好！有什么可以帮你的？"，方便群友区分 AI 回复和普通群员消息。

4. 与其他 OpenClaw channel 共存

OpenClaw 可以同时接入多个 channel（NapCat + Telegram + Discord 等）。每个 channel 是独立的，AI 的工具集由 tools.profile: "full" 统一暴露，跨 channel 的行为保持一致。你可以在 Telegram 上开始一个任务，切到 QQ 查看进度——只要你用同一套 OpenSpec/ClawSpec 工作流管理。

5. 权限控制与安全加固

dmPolicy 和 groupPolicy 只是基础访问控制。在生产环境里，建议：

• 私聊用 allowlist 模式，只加可信用户
• 群聊中对于高危操作（禁言、踢人、发公告），可以让 AI 在执行前要求群主确认
• 定期检查 NapCat 的登录状态，确保机器人账号没有掉线或被风控

6. 接入其他 OneBot 11 兼容客户端

NapCat 不是唯一的选择。任何实现了 OneBot 11 标准的 QQ 客户端（如 Lagrange、LLOneBot）都可以用同样的方式接入 OpenClaw，只需要把 httpApi 和 reverseWs 地址改成对应客户端的配置即可。