1. 从零搭一个 QQ 群 AI 办公机器人到底卡在哪OpenClaw 做 QQ AI 办公机器人核心就两件事让 QQ 账号变成能收发消息的机器人再让机器人接上大模型和邮件能力。听起来简单真动手会发现坑集中在三处QQ 协议端怎么稳定登录、群聊消息怎么按关键词触发而不是每条都回、自定义域名邮件怎么通过验证并投递到任意邮箱。这篇就按这三条链路拆开写每一步都给可复制的配置和验证动作目标是一次跑通办公自动化闭环。适合谁看手里有一台能跑 Docker 的机器本地或云主机都行、想用 QQ 群做内部通知或客服入口、又不想自己从零写协议适配的开发者。前置知识只需要会敲几条命令、能看懂 YAML 和 JSON 结构。整条链路里QQ 协议端负责把群消息转成 WebSocket 事件OpenClaw 负责调度模型和技能TaoToken 负责把模型调用收敛成一个统一 Key 和 Base URL邮件则走自定义域名发信服务。四块拼起来就是一个能在群里被 唤醒、能按关键词响应、还能把结果发到指定邮箱的办公助手。我试过把这几块分开调最容易出问题的不是模型而是 QQ 协议端的登录态和插件配置。所以下面先讲协议端再讲 OpenClaw 接入最后讲邮件顺序别乱。2. TaoToken 前置统一 Key 与 API 通道怎么准备在写任何配置之前先把模型调用这条链路固定下来。OpenClaw 支持多种模型后端但如果你想让 QQ 机器人在群聊里稳定响应建议用一个统一的 API 通道避免每个模型单独配 Key、单独改 Base URL。TaoToken 在这里的角色就是提供统一的 Key 和 API 地址OpenClaw 侧只需要填一次 Base URL 和 Key后面换模型只改 Model ID。先到官网注册并拿到 Keyhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注册后在控制台创建 API Key复制出来备用。注意 Key 只在创建时完整显示一次丢了就重新建一个。拿到 Key 之后你需要记住两个地址Base URLhttps://taotoken.net/apiAPI Key控制台生成的那串这两个值后面会出现在 OpenClaw 的 auth.json 和插件配置里。如果你用的是 Claude Code 或 Codex 这类工具配置方式略有不同但核心都是 Base URL Key Model ID 三件套。Model ID 建议先用一个通用对话模型等链路跑通再换。注意Base URL 不要带末尾斜杠也不要自己拼 /v1按文档给的写法填。填错最常见的表现是 401 或连接超时。这一步做完你手里应该有三个东西一个 Key、一个 Base URL、一个准备用的 Model ID。后面所有配置都围绕这三个值展开。3. 可复制配置NapCat OpenClaw auth.json 全量片段这一节给全量可复制片段。先建项目目录再写 docker-compose.yml然后装 OpenClaw 插件最后写 auth.json。3.1 NapCat 协议端 docker-compose.yml在任意目录创建 napcat 文件夹和子目录mkdir -p napcat cd napcat mkdir -p config .config logs然后创建 docker-compose.yml内容如下services: napcat: image: mlikiowa/napcat-docker:latest container_name: napcat restart: unless-stopped environment: - NAPCAT_UID${NAPCAT_UID:-1000} - NAPCAT_GID${NAPCAT_GID:-1000} - MESSAGE_POST_FORMATstring - HTTP_ENABLEtrue - HTTP_HOST0.0.0.0 - HTTP_PORT3000 - WS_ENABLEtrue - WS_HOST0.0.0.0 - WS_PORT3001 ports: - 3000:3000 - 3001:3001 - 6099:6099 volumes: - ./config:/app/napcat/config - ./.config:/app/.config/QQ - ./logs:/app/napcat/logs stdin_open: true tty: true启动命令要带上当前用户 ID否则容器内权限和宿主机对不上NAPCAT_UID$(id -u) NAPCAT_GID$(id -g) docker-compose up -d启动后看日志拿登录二维码docker-compose logs -f用手机 QQ 扫码登录。登录成功后日志里会显示 WebUI 的 token也可以直接访问 http://127.0.0.1:6099/webui?token你的token 进管理页。进网络配置添加 WebSocket Server复制它的 token后面 OpenClaw 要用。3.2 OpenClaw 插件安装推荐用 openclaw_qq 插件因为它支持 requireMention 和 keywordTriggers群聊不会每条都回。安装命令cd ~/.openclaw/extensions git clone https://github.com/constansino/openclaw_qq.git qq cd ~/.openclaw/extensions/qq pnpm install 21 | tail -20装完重启网关pnpm openclaw gateway restart然后打开 http://127.0.0.1:18789/channels 粘贴刚才复制的 WebSocket token保存。过一会看到 yes 就是连上了。3.3 auth.json 与模型配置OpenClaw 的模型配置在用户目录下的 .openclaw 里。以 macOS 为例路径是 /Users/你的用户名/.openclaw/openclaw.json。找到 channels 下的 qq把 enable 改为 true。然后配置模型通道auth.json 片段如下{ baseUrl: https://taotoken.net/api, apiKey: 你的TaoToken Key, model: 你的Model ID }如果你用的是 Codex 风格的 auth.json结构类似关键是 baseUrl 和 apiKey 两个字段。填完重启pnpm openclaw gateway restart3.4 关键词触发配置openclaw_qq 的配置项里requireMention 默认 true也就是群里必须 机器人才触发。keywordTriggers 可以加关键词比如「小助手」「报销」「通知」。配置示例{ requireMention: true, keywordTriggers: [小助手, 报销, 通知], allowedGroups: [你的群号], rateLimitMs: 1000, maxMessageLength: 4000 }rateLimitMs 是发送限速默认 1000ms防风控用。maxMessageLength 默认 4000超长消息会分片。4. 验证请求群内 触发与邮件投递到指定域名配置写完必须验证不然你不知道是协议端没通还是模型没通。4.1 验证群内 触发在 QQ 群里 机器人发一句「小助手 你好」。预期结果是机器人回复。如果没回复先看 OpenClaw 网关日志再看 NapCat 日志里有没有收到消息事件。两个日志都正常但没回复多半是模型通道没通检查 auth.json 里的 baseUrl 和 apiKey。再测关键词触发不 机器人直接发「报销 帮我查一下流程」。如果 keywordTriggers 配了「报销」应该触发。没触发就检查关键词是否写对、群号是否在 allowedGroups 里。4.2 验证自定义域名邮件邮件这条链路用 resend 的发信技能。先装技能npx skills add resend/resend-skillssend-email -g -y默认只能发到注册邮箱要发任意邮箱必须加域名。到 resend 控制台添加你的域名然后按提示加 DNS 记录。以阿里云为例需要加这几条类型主机记录记录值优先级用途TXTresend._domainkeypMIGf...-DKIM 签名MXsendfeedback-smtp...10退信处理TXTsendvspf1 include...-SPF 验证TXT_dmarcvDMARC1; pnone;-DMARC 策略加完等验证从 Pending 变成 Verified 就通了。然后在群里 机器人发「发邮件到 xxx你的域名.com 主题测试 内容你好」检查目标邮箱是否收到。4.3 验证模型对话通道如果你想单独验证模型通道可以用模型对话页面直接测https://taotoken.net/api 。填同样的 Base URL 和 Key发一条消息看是否返回。返回正常说明通道没问题问题就在 OpenClaw 或 QQ 协议端。5. 本篇常见错排查401、local proxy failed、reading choices这一节列真实会遇到的报错和排查路径。401 Unauthorized最常见。原因三种Key 复制错、Base URL 写错、Key 被删。检查 auth.json 里的 apiKey 是否完整baseUrl 是否是 https://taotoken.net/api 。注意不要自己加 /v1。local proxy failedOpenClaw 网关连不上模型通道。先确认网络能通再确认 baseUrl 没写错。如果用了本地 ollama 模型但 ollama 没启动也会报这个。检查 agents.defaults.model.primary 指向的模型是否可用。reading choices 报错通常是模型返回结构不符合预期多半是 Model ID 填错或者用了不支持的模型。换一个通用对话模型再试。QQ 机器人回复 Connection error去 .openclaw/openclaw.json 找 channels.qq.enable 改为 true。如果还不行检查 agents.defaults.model.primary 是不是本地模型且没启动。群聊每条都回复说明用的是 izhimu/qq 插件它没有 requireMention 配置。换成 openclaw_qq 插件配 requireMention: true。/model 命令不生效izhimu/qq 不支持命令处理openclaw_qq 支持但仅管理员。检查 admins 列表是否包含你的 QQ 号。邮件发不出去先确认域名验证是否 Verified再确认 DNS 记录是否生效。DKIM 和 SPF 缺一个都可能被拒。验证码登录失败NapCat 部分场景不支持验证码改用扫码登录。登录后日志没显示离线就可以退出手机 QQ。6. 把这条链路用起来从群通知到邮件闭环链路跑通后实际办公场景可以这样用群里 机器人发「通知 明天下午三点开会」机器人调模型生成通知文案再通过邮件技能发到指定域名邮箱。整个过程不需要你手动复制粘贴。如果你要长期跑编码类或 Agent 类任务建议用 Coding Plan 把模型调用固定下来避免每次换模型都改配置。接入文档在 https://taotoken.net/api API Keys 在控制台生成。模型对话验证入口也在同一域名下。最后提醒一句QQ 协议端建议用小号避免主号被风控。群白名单和限速一定要配不然消息量大容易被限制。邮件域名验证一次通过后后续发信就稳定了。整条链路的关键不是某个单点配置而是四块协议端、OpenClaw、模型通道、邮件都通缺一个闭环就断。
1. 从零搭一个 QQ 群 AI 办公机器人到底卡在哪OpenClaw 做 QQ AI 办公机器人核心就两件事让 QQ 账号变成能收发消息的机器人再让机器人接上大模型和邮件能力。听起来简单真动手会发现坑集中在三处QQ 协议端怎么稳定登录、群聊消息怎么按关键词触发而不是每条都回、自定义域名邮件怎么通过验证并投递到任意邮箱。这篇就按这三条链路拆开写每一步都给可复制的配置和验证动作目标是一次跑通办公自动化闭环。适合谁看手里有一台能跑 Docker 的机器本地或云主机都行、想用 QQ 群做内部通知或客服入口、又不想自己从零写协议适配的开发者。前置知识只需要会敲几条命令、能看懂 YAML 和 JSON 结构。整条链路里QQ 协议端负责把群消息转成 WebSocket 事件OpenClaw 负责调度模型和技能TaoToken 负责把模型调用收敛成一个统一 Key 和 Base URL邮件则走自定义域名发信服务。四块拼起来就是一个能在群里被 唤醒、能按关键词响应、还能把结果发到指定邮箱的办公助手。我试过把这几块分开调最容易出问题的不是模型而是 QQ 协议端的登录态和插件配置。所以下面先讲协议端再讲 OpenClaw 接入最后讲邮件顺序别乱。2. TaoToken 前置统一 Key 与 API 通道怎么准备在写任何配置之前先把模型调用这条链路固定下来。OpenClaw 支持多种模型后端但如果你想让 QQ 机器人在群聊里稳定响应建议用一个统一的 API 通道避免每个模型单独配 Key、单独改 Base URL。TaoToken 在这里的角色就是提供统一的 Key 和 API 地址OpenClaw 侧只需要填一次 Base URL 和 Key后面换模型只改 Model ID。先到官网注册并拿到 Keyhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注册后在控制台创建 API Key复制出来备用。注意 Key 只在创建时完整显示一次丢了就重新建一个。拿到 Key 之后你需要记住两个地址Base URLhttps://taotoken.net/apiAPI Key控制台生成的那串这两个值后面会出现在 OpenClaw 的 auth.json 和插件配置里。如果你用的是 Claude Code 或 Codex 这类工具配置方式略有不同但核心都是 Base URL Key Model ID 三件套。Model ID 建议先用一个通用对话模型等链路跑通再换。注意Base URL 不要带末尾斜杠也不要自己拼 /v1按文档给的写法填。填错最常见的表现是 401 或连接超时。这一步做完你手里应该有三个东西一个 Key、一个 Base URL、一个准备用的 Model ID。后面所有配置都围绕这三个值展开。3. 可复制配置NapCat OpenClaw auth.json 全量片段这一节给全量可复制片段。先建项目目录再写 docker-compose.yml然后装 OpenClaw 插件最后写 auth.json。3.1 NapCat 协议端 docker-compose.yml在任意目录创建 napcat 文件夹和子目录mkdir -p napcat cd napcat mkdir -p config .config logs然后创建 docker-compose.yml内容如下services: napcat: image: mlikiowa/napcat-docker:latest container_name: napcat restart: unless-stopped environment: - NAPCAT_UID${NAPCAT_UID:-1000} - NAPCAT_GID${NAPCAT_GID:-1000} - MESSAGE_POST_FORMATstring - HTTP_ENABLEtrue - HTTP_HOST0.0.0.0 - HTTP_PORT3000 - WS_ENABLEtrue - WS_HOST0.0.0.0 - WS_PORT3001 ports: - 3000:3000 - 3001:3001 - 6099:6099 volumes: - ./config:/app/napcat/config - ./.config:/app/.config/QQ - ./logs:/app/napcat/logs stdin_open: true tty: true启动命令要带上当前用户 ID否则容器内权限和宿主机对不上NAPCAT_UID$(id -u) NAPCAT_GID$(id -g) docker-compose up -d启动后看日志拿登录二维码docker-compose logs -f用手机 QQ 扫码登录。登录成功后日志里会显示 WebUI 的 token也可以直接访问 http://127.0.0.1:6099/webui?token你的token 进管理页。进网络配置添加 WebSocket Server复制它的 token后面 OpenClaw 要用。3.2 OpenClaw 插件安装推荐用 openclaw_qq 插件因为它支持 requireMention 和 keywordTriggers群聊不会每条都回。安装命令cd ~/.openclaw/extensions git clone https://github.com/constansino/openclaw_qq.git qq cd ~/.openclaw/extensions/qq pnpm install 21 | tail -20装完重启网关pnpm openclaw gateway restart然后打开 http://127.0.0.1:18789/channels 粘贴刚才复制的 WebSocket token保存。过一会看到 yes 就是连上了。3.3 auth.json 与模型配置OpenClaw 的模型配置在用户目录下的 .openclaw 里。以 macOS 为例路径是 /Users/你的用户名/.openclaw/openclaw.json。找到 channels 下的 qq把 enable 改为 true。然后配置模型通道auth.json 片段如下{ baseUrl: https://taotoken.net/api, apiKey: 你的TaoToken Key, model: 你的Model ID }如果你用的是 Codex 风格的 auth.json结构类似关键是 baseUrl 和 apiKey 两个字段。填完重启pnpm openclaw gateway restart3.4 关键词触发配置openclaw_qq 的配置项里requireMention 默认 true也就是群里必须 机器人才触发。keywordTriggers 可以加关键词比如「小助手」「报销」「通知」。配置示例{ requireMention: true, keywordTriggers: [小助手, 报销, 通知], allowedGroups: [你的群号], rateLimitMs: 1000, maxMessageLength: 4000 }rateLimitMs 是发送限速默认 1000ms防风控用。maxMessageLength 默认 4000超长消息会分片。4. 验证请求群内 触发与邮件投递到指定域名配置写完必须验证不然你不知道是协议端没通还是模型没通。4.1 验证群内 触发在 QQ 群里 机器人发一句「小助手 你好」。预期结果是机器人回复。如果没回复先看 OpenClaw 网关日志再看 NapCat 日志里有没有收到消息事件。两个日志都正常但没回复多半是模型通道没通检查 auth.json 里的 baseUrl 和 apiKey。再测关键词触发不 机器人直接发「报销 帮我查一下流程」。如果 keywordTriggers 配了「报销」应该触发。没触发就检查关键词是否写对、群号是否在 allowedGroups 里。4.2 验证自定义域名邮件邮件这条链路用 resend 的发信技能。先装技能npx skills add resend/resend-skillssend-email -g -y默认只能发到注册邮箱要发任意邮箱必须加域名。到 resend 控制台添加你的域名然后按提示加 DNS 记录。以阿里云为例需要加这几条类型主机记录记录值优先级用途TXTresend._domainkeypMIGf...-DKIM 签名MXsendfeedback-smtp...10退信处理TXTsendvspf1 include...-SPF 验证TXT_dmarcvDMARC1; pnone;-DMARC 策略加完等验证从 Pending 变成 Verified 就通了。然后在群里 机器人发「发邮件到 xxx你的域名.com 主题测试 内容你好」检查目标邮箱是否收到。4.3 验证模型对话通道如果你想单独验证模型通道可以用模型对话页面直接测https://taotoken.net/api 。填同样的 Base URL 和 Key发一条消息看是否返回。返回正常说明通道没问题问题就在 OpenClaw 或 QQ 协议端。5. 本篇常见错排查401、local proxy failed、reading choices这一节列真实会遇到的报错和排查路径。401 Unauthorized最常见。原因三种Key 复制错、Base URL 写错、Key 被删。检查 auth.json 里的 apiKey 是否完整baseUrl 是否是 https://taotoken.net/api 。注意不要自己加 /v1。local proxy failedOpenClaw 网关连不上模型通道。先确认网络能通再确认 baseUrl 没写错。如果用了本地 ollama 模型但 ollama 没启动也会报这个。检查 agents.defaults.model.primary 指向的模型是否可用。reading choices 报错通常是模型返回结构不符合预期多半是 Model ID 填错或者用了不支持的模型。换一个通用对话模型再试。QQ 机器人回复 Connection error去 .openclaw/openclaw.json 找 channels.qq.enable 改为 true。如果还不行检查 agents.defaults.model.primary 是不是本地模型且没启动。群聊每条都回复说明用的是 izhimu/qq 插件它没有 requireMention 配置。换成 openclaw_qq 插件配 requireMention: true。/model 命令不生效izhimu/qq 不支持命令处理openclaw_qq 支持但仅管理员。检查 admins 列表是否包含你的 QQ 号。邮件发不出去先确认域名验证是否 Verified再确认 DNS 记录是否生效。DKIM 和 SPF 缺一个都可能被拒。验证码登录失败NapCat 部分场景不支持验证码改用扫码登录。登录后日志没显示离线就可以退出手机 QQ。6. 把这条链路用起来从群通知到邮件闭环链路跑通后实际办公场景可以这样用群里 机器人发「通知 明天下午三点开会」机器人调模型生成通知文案再通过邮件技能发到指定域名邮箱。整个过程不需要你手动复制粘贴。如果你要长期跑编码类或 Agent 类任务建议用 Coding Plan 把模型调用固定下来避免每次换模型都改配置。接入文档在 https://taotoken.net/api API Keys 在控制台生成。模型对话验证入口也在同一域名下。最后提醒一句QQ 协议端建议用小号避免主号被风控。群白名单和限速一定要配不然消息量大容易被限制。邮件域名验证一次通过后后续发信就稳定了。整条链路的关键不是某个单点配置而是四块协议端、OpenClaw、模型通道、邮件都通缺一个闭环就断。
