OpenClaw 本地配置 QQ Bot 打通流程

本文档详细介绍了在Mac本地环境配置OpenClaw与QQ机器人对接的完整流程。

kishu_iOS&AI

669人浏览 · 2026-03-16 18:24:08

kishu_iOS&AI · 2026-03-16 18:24:08 发布

OpenClaw 本地配置 QQ Bot 打通流程

本文档用于在本地 Mac 环境把 OpenClaw + QQ Bot 打通，并完成：

QQ 机器人接入 OpenClaw
多账号配置（可选）
指定 QQ Bot 路由到指定 Agent
启动后可直接在 QQ 对话触发对应 Agent

1. 前置条件

确保以下条件已满足：

已安装 OpenClaw CLI
已有可用的 QQ 机器人 AppID 与 AppSecret
本机可访问 registry.npmjs.org、bots.qq.com、api.sgroup.qq.com

可先检查版本：

openclaw --version
node -v
npm -v

2. 安装 QQ Bot 插件

openclaw plugins install @tencent-connect/openclaw-qqbot@latest

安装后可确认插件已加载：

openclaw plugins list | rg -i qqbot

3.（可选）修复 npm TLS 证书问题

如果安装插件时报错 UNABLE_TO_GET_ISSUER_CERT_LOCALLY，执行：

mkdir -p ~/.certs
security find-certificate -a -p /System/Library/Keychains/SystemRootCertificates.keychain > ~/.certs/macos-root-certs.pem
security find-certificate -a -p /Library/Keychains/System.keychain > ~/.certs/macos-system-certs.pem
cat ~/.certs/macos-root-certs.pem ~/.certs/macos-system-certs.pem > ~/.certs/macos-all-certs.pem

npm config set cafile "$HOME/.certs/macos-all-certs.pem"
npm config set strict-ssl true

然后重试插件安装。

4. 把 QQ Token 存入 Keychain（推荐）

建议把凭据存 Keychain，不要把明文写到文档或脚本里。

4.1 概念澄清（重要）

AppID：QQ 开放平台里的机器人 ID（纯数字）
AppSecret：机器人密钥
token（OpenClaw 命令里）：AppID:AppSecret
accountId（例如 bot1）：OpenClaw 路由用的账号标识，不是密钥

也就是说：bot1 不是 token，本质是你在 --account 配置后用于路由匹配的账号 ID（插件会做小写规范化）。

QQ Token 格式：

AppID:AppSecret

示例（会覆盖同名项）：

security add-generic-password -a "$USER" -s "Key1" -w "APPID_1:APPSECRET_1" -U
security add-generic-password -a "$USER" -s "Key2" -w "APPID_2:APPSECRET_2" -U

验证能读到（只验证，不要泄漏到聊天记录）：

security find-generic-password -a "$USER" -s "Key1" -w

5. 配置 QQ Bot 账号到 OpenClaw

5.0 对应 QQ 开放平台截图

https://q.qq.com/qqbot/openclaw/

QQ 开放平台“OpenClaw 原生接入流程”里的 3 条命令，含义如下：

安装插件

openclaw plugins install @tencent-connect/openclaw-qqbot@latest

绑定当前 QQ 机器人（--token 就是 AppID:AppSecret）

openclaw channels add --channel qqbot --token "AppID:AppSecret"

重启 OpenClaw 服务

openclaw gateway restart

补充说明：

如果是多机器人，建议加 --account，例如 --account bot1
之后在 agents bind 使用的是 accountId（如 bot1），不是 token
截图里如果出现过完整 AppSecret，建议在 QQ 开放平台立即轮换（重置）AppSecret

5.1 单账号

openclaw channels add \
  --channel qqbot \
  --account bot1 \
  --token "$(security find-generic-password -a "$USER" -s "Key1" -w)"

5.2 多账号

openclaw channels add \
  --channel qqbot \
  --account bot1 \
  --token "$(security find-generic-password -a "$USER" -s "Key1" -w)"

openclaw channels add \
  --channel qqbot \
  --account bot2 \
  --token "$(security find-generic-password -a "$USER" -s "Key2" -w)"

查看已配置账号：

openclaw channels list --json | sed -n '/^{/,$p' | jq '.chat.qqbot'

注意：插件通常会把 accountId 规范成小写，例如 Bot1 -> bot1。

6. 创建 Agent 并绑定到指定 QQ Bot

6.1 创建 Agent

openclaw agents add qq_agent_bot \
  --non-interactive \
  --workspace ~/.openclaw/workspace-qq_agent_bot \
  --json

openclaw agents add qq_agent_edit_bot \
  --non-interactive \
  --workspace ~/.openclaw/workspace-qq_agent_edit_bot \
  --json

6.2 绑定路由（精准绑定到账号）

openclaw agents bind --agent qq_agent_bot --bind qqbot:bot1 --json
openclaw agents bind --agent qq_agent_edit_bot --bind qqbot:bot2 --json

查看绑定结果：

openclaw agents bindings --json | sed -n '/^\\[/,$p' | jq '.'

如果之前绑过泛路由（qqbot），建议移除，避免冲突：

openclaw agents unbind --agent qq_agent_bot --bind qqbot --json

7. 重启网关使配置生效

openclaw gateway restart

8. 验证是否真正打通

8.1 看配置层状态

openclaw channels status

期望看到类似：

QQ Bot bot1: enabled, configured
QQ Bot bot2: enabled, configured

8.2 看运行日志（最关键）

rg -n "qqbot:bot1|qqbot:bot2|READY|WebSocket connected|Access token obtained" \
  ~/.openclaw/logs/gateway.log -S | tail -n 80

出现以下日志即表示在线：

Access token obtained successfully
WebSocket connected
Dispatch event: t=READY 或 t=RESUMED

9. 日常运维命令

# 查看所有 agent
openclaw agents list

# 查看绑定关系
openclaw agents bindings

# 重启网关
openclaw gateway restart

# 查看网关日志
tail -f ~/.openclaw/logs/gateway.log

10. 常见问题排查

Q1：插件安装失败，报 TLS/证书错误

参考本文第 3 节设置 npm cafile
确保 ~/.certs/macos-all-certs.pem 不是空文件

Q2：`channels status` 提示很多 env var 缺失

这是当前 shell 未加载对应环境变量导致
若你依赖 ~/.zshrc + Keychain 注入，先执行 source ~/.zshrc

Q3：已连上 QQ，但消息没进目标 Agent

优先检查：

是否绑定成了错误的 accountId（大小写）
是否还保留了泛路由 qqbot 抢路由
openclaw agents bindings 是否存在精准规则 qqbot:<accountId>

Q4：多账号时默认路由不明确

显式给每个 QQ Bot 配 agent bind
避免只依赖默认路由

11. 最小可用流程（速记）

# 1) 安装插件
openclaw plugins install @tencent-connect/openclaw-qqbot@latest

# 2) 存 token 到 keychain（示例）
security add-generic-password -a "$USER" -s "Key1" -w "APPID_1:APPSECRET_1" -U

# 3) 配置频道账号
openclaw channels add --channel qqbot --account bot1 --token "$(security find-generic-password -a "$USER" -s "Key1" -w)"

# 4) 创建并绑定 agent
openclaw agents add qq_agent_bot --non-interactive --workspace ~/.openclaw/workspace-qq_agent_bot
openclaw agents bind --agent qq_agent_bot --bind qqbot:bot1

# 5) 重启并看日志
openclaw gateway restart
rg -n "qqbot:bot1|READY|WebSocket connected" ~/.openclaw/logs/gateway.log -S | tail -n 50