OpenClaw 接入 QQ 完全指南 - 打造你的私人 AI 助手

本文介绍了如何通过 @izhimu/qq 插件将 OpenClaw AI 框架接入 QQ 平台，实现私聊消息交互。主要内容包括：安装插件、配置 NapCat WebSocket 服务、设置 OpenClaw 连接参数，以及发送各类消息（文本、图片、回复等）的操作指南。文章还提供了实战案例，展示如何打造不同风格的 AI 助手，并详细说明了插件的高级功能如自动重连、心跳监测等。通过本指南，用户可以快速

栀暮

3607人浏览 · 2026-02-10 17:50:16

栀暮 · 2026-02-10 17:50:16 发布

OpenClaw 接入 QQ 完全指南 - 打造你的私人 AI 助手

本文将详细介绍如何使用 @izhimu/qq 插件将 OpenClaw 接入 QQ 平台，实现私聊消息、图片、回复等多种消息类型的完整支持。

一、项目简介

OpenClaw 是一个强大的 AI Agent 框架，支持多渠道消息接入。而 @izhimu/qq 插件则是 OpenClaw 的 QQ 通道扩展，通过 NapCat WebSocket API 连接 QQ，让你的 AI Agent 可以在 QQ 私聊中与用户互动。

🚀 项目地址

GitHub: izhimu/openclaw-channel-qq ⭐ 欢迎Star支持

NPM: @izhimu/qq

文档: OpenClaw 官方文档

核心特性

✅ 私聊支持 - 支持 QQ 私聊消息收发
✅ 丰富的消息类型 - 文本、图片、表情、语音、文件、回复
✅ 实时通信 - WebSocket 全双工连接，支持自动重连
✅ 心跳监测 - 内置健康检查和连接状态监控
✅ 交互式配置 - 提供向导式配置界面，零门槛上手

二、快速开始

前置准备

在开始之前，请确保你已经完成以下准备工作：

安装 OpenClaw (版本 >= 2026.2.1)
安装并配置 NapCat - 这是一个基于 NTQQ 的 QQ 机器人框架

💡 NapCat 安装指南

如果你还没有安装 NapCat，请参考官方文档进行安装：

📖 NapCat Shell 启动教程

📦 NapCat GitHub 仓库

NapCat 支持 Linux、Windows、macOS 等多个平台，选择适合你系统的安装方式即可。

2.1 安装插件

# 通过 OpenClaw CLI 安装
openclaw plugins install @izhimu/qq

2.2 配置 NapCat

如果你已经安装好了 NapCat，接下来需要配置 WebSocket 服务。

在这里插入图片描述

📌 NapCat 配置文件位置

NapCat 的配置文件通常位于：

Linux: ~/.config/NapCat/config/config.yml

Windows: %APPDATA%\NapCat\config\config.yml

具体位置请参考 NapCat 配置文档

在 NapCat 的 config.yml 中启用 WebSocket 服务：

ws:
  servers:
    - url: ws://0.0.0.0:3001
      token: ""  # 如需认证请设置
      enableHeart: true

2.3 配置 OpenClaw

你可以选择交互式配置或手动配置两种方式：

方式一：交互式配置（推荐）

openclaw onboard

按照提示输入 NapCat 的 WebSocket 地址和访问令牌即可。

方式二：手动配置

编辑 OpenClaw 配置文件，添加以下内容：

{
  "channels": {
    "qq": {
      "wsUrl": "ws://127.0.0.1:3001",
      "accessToken": "",
      "enabled": true
    }
  }
}

2.4 启动服务

# 启动 OpenClaw Gateway
openclaw gateway restart

三、配置详解

配置选项说明

属性	类型	必填	默认值	描述
`wsUrl`	`string`	是	-	NapCat WebSocket 地址
`accessToken`	`string`	否	`""`	访问令牌（如配置了认证）
`enabled`	`boolean`	否	`true`	是否启用该账号

完整配置示例

{
  "channels": {
    "qq": {
      "wsUrl": "ws://127.0.0.1:3001",
      "accessToken": "your-token-here",
      "enabled": true
    }
  },
  "agents": {
    "default": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-5-20250929"
    }
  }
}

四、使用指南

4.1 发送消息

发送私聊消息

openclaw message send "你好！" --to qq:private:123456789

带回复的消息

openclaw message send "回复你的消息" --to qq:private:123456789 --reply-to <message-id>

发送带图片的消息

openclaw message send "看这张图片" --to qq:private:123456789 --media https://example.com/image.jpg

4.2 检查状态

# 查看所有频道状态
openclaw channels

# 查看 QQ 频道日志
openclaw logs --channel qq

4.3 消息目标格式

私聊消息目标格式：qq:private:<QQ号>

示例：

qq:private:123456789

五、实战案例

💡 快速上手

学会了基本使用后，让我们通过实际案例来看看如何打造一个私聊 AI 助手！

案例：打造私聊 AI 助手

在这里插入图片描述

以下配置展示如何打造一个专业的私聊 AI 助手：

{
  "channels": {
    "qq": {
      "wsUrl": "ws://127.0.0.1:3001",
      "enabled": true
    }
  },
  "agents": {
    "assistant": {
      "provider": "openai",
      "model": "gpt-4o",
      "systemPrompt": "你是一个友好专业的 AI 助手，负责解答用户的问题。回答要简洁准确，语气友好。"
    }
  },
  "routing": {
    "qq:private:*": "assistant"
  }
}

配置说明：

systemPrompt: 定义助手的角色和性格
qq:private:*: 将所有 QQ 私聊消息路由到 assistant
你可以根据需求更换不同的 AI 模型（Claude、GPT-4 等）

不同风格的 AI 助手

你可以通过修改 systemPrompt 来打造不同风格的助手：

1. 技术助手

"systemPrompt": "你是一个专业的技术助手，擅长编程和技术咨询。回答要准确、专业，必要时提供代码示例。"

2. 学习助手

"systemPrompt": "你是一个耐心的学习助手，擅长解释复杂的概念。用简单易懂的语言解释问题，并鼓励学生提问。"

3. 创意助手

"systemPrompt": "你是一个富有创意的助手，擅长头脑风暴和创意写作。思维活跃，提供新颖独特的观点。"

六、高级功能

6.1 支持的消息类型

类型	入站	出站	说明
`text`	✓	✓	文本消息
`image`	✓	✓	图片
`face`	✓	-	QQ 表情
`reply`	✓	✓	消息回复
`record`	✓	✓	语音消息
`file`	✓	✓	文件
`json`	✓	-	JSON 富文本

6.2 自动重连机制

插件内置了指数退避的自动重连机制，当与 NapCat 的连接断开时，会自动尝试重连：

首次重连：1 秒后
后续重连：每次间隔翻倍，最长 60 秒
连接成功后：重置重连计时器

6.3 心跳监测

NapCat 会定期发送心跳包，插件会实时监控连接状态：

心跳间隔：默认 5 秒
超时检测：30 秒未收到心跳则判定连接异常
自动恢复：检测到异常后触发重连

七、架构设计

核心组件

openclaw-channel-qq/
├── src/
│   ├── channel.ts         # 主插件定义
│   ├── core/
│   │   ├── connection.ts  # WebSocket 连接管理器
│   │   └── dispatch.ts    # 事件分发器
│   ├── adapters/
│   │   └── message.ts     # NapCat ↔ OpenClaw 消息转换
│   ├── config.ts          # 配置解析
│   ├── onboarding.ts      # 交互式配置向导
│   └── types/
│       └── channel.ts     # TypeScript 类型定义

工作流程

用户消息 (QQ)
    ↓
NapCat (WebSocket API)
    ↓
openclaw-channel-qq (消息适配)
    ↓
OpenClaw Gateway
    ↓
AI Agent 处理
    ↓
OpenClaw Gateway
    ↓
openclaw-channel-qq (消息适配)
    ↓
NapCat (WebSocket API)
    ↓
回复消息 (QQ)

八、常见问题排查

8.1 连接问题

问题：无法连接到 NapCat

解决方案：

检查 NapCat 是否正常运行
```
curl http://localhost:3001/get_status
```
验证 WebSocket 配置
- 确认 wsUrl 与 NapCat 配置一致
- 检查访问令牌是否正确
防火墙设置
- 确保 WebSocket 端口未被防火墙拦截

8.2 消息发送失败

问题：消息无法发送

解决方案：

检查账号状态
```
openclaw channels
```
查看详细日志
```
openclaw logs --channel qq --verbose
```
验证消息格式
- 确保目标格式正确：qq:private:<QQ号>

8.3 常见问题速查表

问题	可能原因	解决方案
连接失败	NapCat 未启动	启动 NapCat 服务
认证失败	accessToken 错误	检查配置中的令牌
消息未收到	账号被禁用	检查 `enabled: true`
图片发送失败	URL 不可访问	确保图片 URL 可公网访问

九、相关资源

官方文档

项目地址

GitHub: izhimu/openclaw-channel-qq
NPM: @izhimu/qq

十、总结

@izhimu/qq 插件为 OpenClaw 提供了完整的 QQ 私聊接入能力，通过简单的配置即可实现：

📱 QQ 私聊消息收发
🖼️ 图片、文件、语音等多媒体支持
🔄 自动重连和心跳监测
🛠️ 交互式配置向导
🔧 完善的日志和错误处理

无论你是想打造个人 AI 助手，还是实现私聊智能客服，@izhimu/qq 都是一个值得尝试的选择。

快速命令参考

# 安装插件
openclaw plugins install @izhimu/qq

# 交互式配置
openclaw onboard

# 启动服务
openclaw gateway restart

# 查看状态
openclaw channels

# 发送消息
openclaw message send "消息内容" --to qq:private:123456789

# 查看日志
openclaw logs --channel qq

如有问题或建议，欢迎提交 Issue 或 PR！