给 Pi 开通 QQ 机器人：零依赖 Node 桥，让 Pi 随叫随到

适用：已有 Pi（本地或服务器均可），想通过 QQ 私聊直接指挥它干活。本方案经生产环境实测：零依赖 Node 桥、观察模式安全起步、指数退避防平台打标。

目录（点击跳转）

原理第 1 步 · 创建 QQ 机器人，拿凭据第 2 步 · 环境准备第 3 步 · 写桥脚本第 4 步 · 起桥，观察模式起步第 5 步 · 防平台打标验收清单常见问题与排错相关网址汇总

原理

写在前面

你在 QQ 发消息 → QQ 机器人平台 → WebSocket 推给桥程序
      → 桥 spawn「pi -p 你的消息」→ Pi 干活出结果
      → 桥把结果发回 QQ → 你在 QQ 里看到回复

桥是一段独立的 Node 脚本（不装任何第三方包，只有 Node 自带模块），Pi 以子进程方式被调用。每用户固定 session-id，上下文连续——同一用户连续问，Pi 记得前面聊过什么。

第 1 步：创建 QQ 机器人，拿凭据

步骤

打开 QQ 开放平台（q.qq.com/bot），用 QQ 扫码登录
创建应用 → 创建机器人，填写机器人名称、头像、简介
创建成功后在「开发设置」里拿到三样东西：

AppID
AppSecret
Token（机器人令牌，用于 WebSocket 鉴权）

第 2 步：环境准备

步骤

服务器或电脑上确认 Node ≥ 20：

node -v

不需要安装任何 npm 包——桥只依赖 Node 内置模块（ws 不是内置的，所以下面用平台官方的 WebSocket 接口路径，或直接引入一个 ws 包即可；若想保持零依赖，用 Node 22+ 内置的 WebSocket 全局对象）。

第 3 步：写桥脚本（核心代码）

步骤

// qq-bridge.mjs —— QQ 机器人 → Pi 的桥
import { spawn } from 'node:child_process';

const APP_ID = '你的AppID';
const TOKEN  = '你的Token';
const WS_URL = 'wss://api.sgroup.qq.com/websocket'; // 官方 WebSocket 网关

const sessions = {};  // openid -> pi session-id（上下文连续）

function runPi(openid, text, cb) {
  const sid = sessions[openid] ||= 'qq-' + openid.slice(-8);
  const child = spawn('pi', ['-p', text, '--session', sid], {
    stdio: ['ignore', 'pipe', 'pipe'],  // 关键：stdin 必须 ignore，否则 pi 等输入卡死
  });
  let out = '';
  child.stdout.on('data', d => out += d);
  child.on('close', () => cb(out.trim() || '（Pi 没有输出）'));
}

// 以下为 WebSocket 接入：鉴权、收消息、回消息
// （鉴权头 Authorization: Bot <AppID>.<Token>，事件类型 AT_MESSAGE_CREATE / DIRECT_MESSAGE_CREATE
//   回消息走开放平台 REST 接口，完整实现见 pi-qq-channel 技能包）

最容易踩的坑：spawn 默认把 stdin 连成管道，Pi 会一直等你敲回车 → 静默卡死。必须 stdio: ['ignore','pipe','pipe']，实测从"卡 3 分钟"变成"1.3 秒回复"。

第 4 步：起桥，观察模式起步

步骤

先把桥跑在观察模式：收到消息只打印、不回复，确认消息能进来
私聊你的机器人发一条消息，观察桥日志里是否出现消息事件
日志里能看到你的 openid——去开放平台后台把它加进可发送私信名单（后台"权限管理"放行），否则机器人不能主动/被动给你发私信

第 5 步：防平台打标（重要）

步骤

平台对机器人有风控，乱节奏的爆发式回复容易被打标限流。三个保命习惯：

指数退避：请求失败时等待时间翻倍重试（1s → 2s → 4s → …封顶），不狂撞
熔断：连续失败 N 次就停发一段时间，让平台冷静
串行队列：同一用户的消息排队处理，不并发；全局限频（如每秒 ≤ 1 条）

验收清单

完成

私聊机器人"你好"，收到 Pi 的回复
连续问两句带上下文的（"我叫小明""我叫什么？"），第二句答对——session 连续生效
机器人半夜没人理它时，不再主动发消息（观察模式/仅被动回复）

跑通这三步，你就有个 QQ 里随叫随到的 Pi 了——出门在外掏出手机就能指挥它干活。

常见问题与排错

排错

私聊机器人一直没回复：大概率是 openid 没放行——去开放平台后台「权限管理」把测试者的 openid 加进私信白名单，否则机器人不能给你发消息。
桥日志显示鉴权失败：检查 AppID / Token 是否复制完整（Token 在开发设置里单独查看，别和 AppSecret 混了）。
spawn 卡死、3 分钟没反应：就是教程第 3 步那个坑——子进程 stdin 必须 ignore，否则 pi 一直在等你敲回车。
被平台风控限流：先降到观察模式跑几天，确认消息量正常再放开回复；严格指数退避 + 熔断，别狂发。
两个用户聊天串上下文了：session-id 必须按 openid 隔离（代码里 'qq-' + openid.slice(-8) 就是干这个的），别用全局单 session。
WebSocket 频繁断线：加心跳重连（官方网关建议 30s 内 ping 一次），断线指数退避重连。