qqbot

配置并管理QQ官方机器人，支持身份认证、IP白名单设置、Webhook/WebSocket连接及OpenClaw AI集成。

Security Scan

The skill mostly matches its stated purpose (a QQ bot), but there are notable incoherences — a likely real AppSecret is included in the repo, required credentials are not declared, and multiple auxiliary publishing/automation scripts access user paths and browser tooling that are not strictly necessary for runtime bot operation.

Purpose & Capability

Name/description align with the included runtime code (qq_official_bot.py, daemon, AI handler). However, the package also contains many publishing/automation scripts (playwright/agent-browser) for pushing the skill to ClawHub which are unrelated to running the bot itself — they are plausible as author tooling but expand the repo footprint beyond the core purpose. More importantly, config.example.json contains a clientSecret-like value (looks like a real credential) which contradicts PUBLISH.md's claim that templates are 'desensitized'.

Instruction Scope

SKILL.md runtime instructions are focused on setting APP_ID/APP_SECRET, adding IP whitelist, copying files to ~/.openclaw/workspace and running the daemon and AI handler. That is coherent. But several included scripts (publish-*.js, publish-*.sh, publish-helper.sh) attempt to read files from ~/Desktop and interact with the local browser, and the install script copies files from the current directory into ~/.openclaw/workspace — these actions operate on user filesystem and browser state and are not declared in SKILL metadata. The SKILL.md does not warn about embedded credential values present in files (config.example.json).

Install Mechanism

There is no formal install spec (instruction-only in registry), which limits automatic execution. The repo includes an install.sh that installs Python packages with pip --user (requests, aiohttp, websockets) and copies scripts into ~/.openclaw/workspace. Node files depend on playwright (package.json) which when installed may download browsers — none of these are executed by the registry install step, but running the included scripts will perform local installs and may download browser binaries. No remote arbitrary download URLs or extract operations are present in the files themselves.

Credentials

Registry metadata declares no required env vars or primary credential, but the runtime clearly requires APP_ID and APP_SECRET (instructions tell the user to edit files or openclaw.json). The repo also includes config.example.json containing an AppId and a clientSecret-like string (bgmsz7FOX...). Embedding what looks like a real secret in the example is a red flag: either a leaked credential or a sloppy placeholder that could mislead users. The skill requests file-system locations under the user's home (~/Desktop, ~/.openclaw) and will read/write request/response files — acceptable for local integration but worth noting.

Persistence & Privilege

The skill spawns a background daemon (qq_bot_daemon.sh starts a nohup python process and writes pid/log files) and writes files to ~/.openclaw/workspace. always is false and disable-model-invocation is false (normal). The daemon and queue file usage are expected for a bot but mean the skill will run persistently if the user starts it; this is not inherently excessive but users should be aware it runs background processes and writes files under their home directory.

What to consider before installing

Summary of what to check before installing: - Treat the example credential as suspicious. config.example.json contains an AppID and a clientSecret-like string. Do NOT assume this is a safe placeholder — verify it is not a real/active secret. If you ever ran this code with that secret, rotate the secret in your QQ developer console immediately. - The skill does not declare required credentials in metadata. You will need to provide APP_ID and APP_SECRET yourself (either by editing qq_official_bot.py or openclaw.json). Prefer storing secrets in a secure config or environment variables rather than committing them to code. - The install.sh will pip-install dependencies into your user environment and copy scripts into ~/.openclaw/workspace. Review install.sh before running; consider running in an isolated environment (container or VM) if you are unsure. - The repo includes multiple publishing automation scripts (playwright/agent-browser). These scripts interact with your browser and ~/Desktop files (e.g., they try to upload ~/Desktop/qqbot-v1.0.0.zip). Do not run them unless you intend to perform publishing and you understand they will access your filesystem and potentially drive a browser. - Runtime behavior: the bot writes/reads files in ~/.openclaw/workspace/qq_queue to exchange messages with a local AI handler and runs as a background process if you start the daemon. That is expected, but be aware of persistent background processes and local files containing messages. - If you want to proceed: remove any embedded secrets from the repo, replace them with clear placeholders, set your own APP_ID/APP_SECRET, inspect and (if needed) simplify or remove the publishing scripts, and run install/start steps in an isolated environment until you're confident. If you want, I can point out the exact lines/files where the example secret appears and suggest a minimal checklist of commands to safely inspect or run this skill.

QQ 官方机器人配置指南

QQ 官方机器人 (QQ Bot) 完整配置教程，包含从创建机器人到接入 OpenClaw AI 的全过程，以及常见问题排查。

前置条件

• QQ 号（建议使用小号）
• 可访问公网 IP（家庭宽带需处理动态 IP）
• 服务器或本地机器
• OpenClaw 已安装

---

配置步骤

步骤 1: 创建 QQ 机器人

1. 访问 QQ 机器人平台
2. 点击「登录」，使用 QQ 扫码登录
3. 进入「开发者注册」页面，完成实名认证
4. 点击「创建机器人」，填写基本信息
5. 记录关键信息：
   • AppID (如: 102842119)
   • AppSecret (点击显示，只显示一次，务必保存！)

⚠️ 重要: AppSecret 只显示一次，立即保存！

---

步骤 2: 配置 IP 白名单

家庭宽带需要公网 IP，并配置到 QQ 开放平台。

获取公网 IP

curl https://api.ipify.org

配置白名单

1. 进入 QQ 机器人控制台
2. 选择你的机器人
3. 点击「开发设置」→「IP 白名单」
4. 添加获取到的公网 IP
5. 保存

⚠️ 注意: 家庭宽带 IP 会定期变化，需要及时更新白名单，否则会出现错误 11298。

---

步骤 3: 配置 OpenClaw

在 openclaw.json 中添加 QQ 频道配置：

{
  "channels": {
    "qq": {
      "enabled": true,
      "appId": "你的AppID",
      "appSecret": "你的AppSecret"
    }
  }
}

---

步骤 4: 部署 QQ Bot 程序

复制 qq_official_bot.py 到工作区：

cp qq_official_bot.py ~/.openclaw/workspace/

编辑配置文件：

APP_ID = "你的AppID"
APP_SECRET = "你的AppSecret"

---

步骤 5: 启动机器人

# 启动 QQ Bot
~/.openclaw/workspace/qq_bot_daemon.sh start

# 查看状态
~/.openclaw/workspace/qq_bot_daemon.sh status

# 查看日志
tail -f ~/.openclaw/workspace/qq_bot.log

---

常见问题与解决方案

问题 1: 错误 11298 - IP 不在白名单

现象:

获取 Token 失败: 11298
接口访问源IP不在白名单

原因:

• 当前 IP 未添加到 QQ 开放平台白名单
• 或 IP 已变更

解决方案:

1. 获取当前公网 IP: curl https://api.ipify.org
2. 登录 QQ 机器人控制台
3. 更新 IP 白名单
4. 重启 QQ Bot

长期方案:

• 使用云服务器（固定 IP）
• 或使用内网穿透服务

---

问题 2: 无法收到消息

现象:

• Bot 已连接 WebSocket
• 心跳正常
• 但没有收到任何消息事件

原因 1: Intents 权限未开启

解决方案:

1. 登录 QQ 机器人控制台
2. 进入「开发设置」→「权限设置」
3. 开启以下 Intents：
   • ✅ GUILDS (基础权限)
   • ✅ GROUP_AND_C2C_EVENT (私聊和群消息)
   • ✅ AT_MESSAGES (@消息)

原因 2: 事件订阅方式错误

解决方案: 确认选择了「使用长连接接收事件」(WebSocket 模式)，而不是 HTTP 回调。

原因 3: 机器人未添加好友/进群

解决方案:

• 私聊：添加机器人为 QQ 好友
• 群聊：将机器人邀请到群里

---

问题 3: ModuleNotFoundError

现象:

ModuleNotFoundError: No module named 'requests'
ModuleNotFoundError: No module named 'aiohttp'

解决方案:

pip3 install requests aiohttp websockets --user

---

问题 4: 鉴权成功但无法接收消息

现象:

✅ 鉴权成功!
Session ID: xxx
💓 心跳确认

但没有收到 C2C_MESSAGE_CREATE 或 AT_MESSAGE_CREATE 事件。

原因: Intents 值配置错误

解决方案: 使用正确的 Intents 组合：

INTENTS = (1 << 0) | (1 << 25) | (1 << 30)
# GUILDS | GROUP_AND_C2C_EVENT | AT_MESSAGES

---

问题 5: AI 回复超时

现象:

⏳ 等待 OpenClaw AI 回复...
抱歉，AI 响应超时

原因: AI 处理器未运行或响应太慢

解决方案:

1. 确保 AI 处理器脚本在运行
2. 检查请求文件是否生成
3. 手动创建回复文件测试

---

文件结构

~/.openclaw/workspace/
├── qq_official_bot.py      # QQ Bot 主程序
├── qq_bot_daemon.sh        # 启动管理脚本
├── qq_bot.log             # 运行日志
├── qq_queue/              # 消息队列目录
│   ├── ai_request_*.json  # AI 请求
│   └── ai_response_*.txt  # AI 回复
└── qq_ai_handler.sh       # AI 处理器

---

管理命令

# 启动
~/.openclaw/workspace/qq_bot_daemon.sh start

# 停止
~/.openclaw/workspace/qq_bot_daemon.sh stop

# 重启
~/.openclaw/workspace/qq_bot_daemon.sh restart

# 查看状态
~/.openclaw/workspace/qq_bot_daemon.sh status

# 查看日志
tail -f ~/.openclaw/workspace/qq_bot.log

---

调试技巧

1. 检查 WebSocket 连接

tail -f ~/.openclaw/workspace/qq_bot.log | grep -E "连接|心跳|收到"

2. 检查消息事件

tail -f ~/.openclaw/workspace/qq_bot.log | grep "收到事件"

3. 手动测试 AI 回复

# 创建测试请求
echo '{"request_id":"test","message":"你好"}' > ~/.openclaw/workspace/qq_queue/ai_request_test.json

# 创建回复
echo "你好！我是小皮" > ~/.openclaw/workspace/qq_queue/ai_response_test.txt

---

参考资料

• QQ 机器人平台文档
• QQ Bot API 文档
• Intents 说明

---

维护者: 小皮 🦊
版本: 1.0.0
更新时间: 2026-02-23