OpenClaw本地配置QQ Bot的使用流程

目录

• 1. 前置条件
• 2. 安装 QQ Bot 插件
• 3.（可选）修复 npm TLS 证书问题
• 4. 把 QQ Token 存入 Keychain（推荐）
• 4.1 概念澄清（重要）
• 5. 配置 QQ Bot 账号到 OpenClaw
• 5.0 对应 QQ 开放平台截图
• 5.1 单账号
• 5.2 多账号
• 6. 创建 Agent 并绑定到指定 QQ Bot
• 6.1 创建 Agent
• 6.2 绑定路由（精准绑定到账号）
• 7. 重启网关使配置生效
• 8. 验证是否真正打通
• 8.1 看配置层状态
• 8.2 看运行日志（最关键）
• 9. 日常运维命令
• 10. 常见问题排查
• Q1：插件安装失败，报 TLS/证书错误
• Q2：channels status提示很多 env var 缺失
• Q3：已连上 QQ，但消息没进目标 Agent
• Q4：多账号时默认路由不明确
• 11. 最小可用流程（速记）

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

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

确保以下条件已满足：

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

可先检查版本：

openclaw --version
node -v
npm -v

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

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

openclaw plugins list | rg -i qqbot

如果安装插件时报错 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

然后重试插件安装。

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

• 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

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

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

1. 安装插件

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

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

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

3. 重启 OpenClaw 服务

openclaw gateway restart

补充说明：

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

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

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。

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

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

openclaw gateway restart

openclaw channels status

期望看到类似：

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

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

# 查看所有 agent
openclaw agents list
# 查看绑定关系
openclaw agents bindings
# 重启网关
openclaw gateway restart
# 查看网关日志
tail -f ~/.openclaw/logs/gateway.log

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

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

优先检查：

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

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

# 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

到此这篇关于OpenClaw本地配置QQ Bot的使用流程的文章就介绍到这了,更多相关OpenClaw 本地配置 QQ Bot内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！