1. 先把场景说清楚OpenClaw 本地跑 QQ Bot 到底在解决什么OpenClaw 是一个可以在本地运行的 Agent 网关它把不同聊天渠道QQ、Telegram、Discord 等的消息统一收进来再按路由规则分发给对应的 Agent 处理。QQ Bot 则是腾讯 QQ 开放平台提供的机器人能力通过 AppID AppSecret 拿到访问凭据后就能让机器人接收和回复 QQ 消息。把这两者接在一起你就能在本地用一条config.toml骨架 几条 CLI 命令让 QQ 里发来的消息自动触发你配置好的 Agent。这套流程适合谁适合已经装好 OpenClaw CLI、手里有 QQ 机器人凭据、想在自己电脑上完成联调而不依赖云端托管的开发者。整条链路的核心是三件事插件装好、凭据配对、路由绑准。任何一环出问题表现都是“QQ 里发消息没反应”或者“日志里看不到 READY”。我试过在 Mac 上从零走一遍最容易卡住的不是命令本身而是 token 格式写错、accountId 大小写不一致、以及泛路由和精准路由打架。下面按可复制的顺序拆开讲每一步都给出命令和预期结果。2. TaoToken 统一 Key 前置为什么本地 Bot 也要接统一通道OpenClaw 的 Agent 在收到 QQ 消息后需要调用大模型来生成回复。如果你每个 Agent 都单独配一套模型 Key多账号场景下管理会非常乱。TaoToken 的作用就是提供一个统一的 API 通道你只需要在 OpenClaw 里配置一次 base_url 和 Key所有 Agent 都走同一个入口。具体来说TaoToken 兼容 OpenAI 风格的接口OpenClaw 的模型配置里把base_url指向https://taotoken.net/api再把 API Key 填进去即可。这样 QQ Bot 收到的消息经过 Agent 处理时模型调用就走 TaoToken 通道不用在每个 Agent 的 workspace 里重复写 Key。你需要先拿到一个可用的 Key。登录 TaoToken 控制台在 API Keys 页面创建一个新 Key复制保存。注意这个 Key 只在创建时完整显示一次后面只能看到前缀。如果你还没注册可以先从官网入口进去了解整体能力再决定用哪种套餐。提示Key 不要写进config.toml的明文字段后提交到 Git。本地调试可以用环境变量注入或者用系统 Keychain 存。拿到 Key 之后OpenClaw 的模型配置通常长这样放在config.toml的模型段里[models.default] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model gpt-4o-mini这里的${TAOTOKEN_API_KEY}是环境变量引用写法OpenClaw 启动时会从当前 shell 读取。你可以在~/.zshrc里加一行export TAOTOKEN_API_KEY你的Key然后source ~/.zshrc生效。这样配置文件和 Key 就解耦了换 Key 不用改 toml。3. config.toml 骨架QQ Bot 频道与 Agent 路由的完整写法OpenClaw 的config.toml一般位于~/.openclaw/config.toml。下面是一个最小可用的骨架包含模型通道、QQ Bot 频道、Agent 定义和路由绑定四部分。你可以直接复制后按自己的 AppID/AppSecret 替换。# ~/.openclaw/config.toml [gateway] log_level info log_file ~/.openclaw/logs/gateway.log [models.default] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model gpt-4o-mini [channels.qqbot] enabled true accounts [bot1] [channels.qqbot.accounts.bot1] app_id 你的AppID app_secret ${QQBOT_BOT1_SECRET} [agents.qq_agent_bot] workspace ~/.openclaw/workspace-qq_agent_bot model default [agents.qq_agent_edit_bot] workspace ~/.openclaw/workspace-qq_agent_edit_bot model default [routing] qqbot:bot1 qq_agent_bot qqbot:bot2 qq_agent_edit_bot几个关键点解释一下。[channels.qqbot]段声明启用 QQ Bot 频道accounts列出所有账号标识。每个账号在[channels.qqbot.accounts.xxx]下配app_id和app_secret。app_secret同样建议用环境变量引用不要写明文。[routing]段是路由核心格式是渠道:账号ID Agent名。注意账号 ID 会被插件规范成小写所以bot1不要写成Bot1否则路由匹配不上。如果你之前用 CLI 的agents bind命令绑过config.toml里的 routing 和 CLI 绑定会合并冲突时以精准路由优先。注意config.toml修改后必须重启网关才生效直接改文件不会热加载。如果你更习惯用 CLI 管理也可以不写[routing]段改用openclaw agents bind命令。两种方式等价但建议二选一避免两边都配导致排查困难。4. 从安装到验证可复制的打通步骤4.1 安装 QQ Bot 插件先确认 OpenClaw CLI 可用openclaw --version node -v npm -v然后安装腾讯官方插件openclaw plugins install tencent-connect/openclaw-qqbotlatest安装后确认插件已加载openclaw plugins list | rg -i qqbot如果这一步报UNABLE_TO_GET_ISSUER_CERT_LOCALLY是 npm 的 TLS 证书链问题。在 Mac 上可以导出系统根证书并让 npm 使用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然后重试插件安装。确认~/.certs/macos-all-certs.pem不是空文件否则说明证书导出失败。4.2 把 QQ 凭据存入 Keychain不要把 AppSecret 明文写在脚本或文档里。Mac 上用 Keychain 存security add-generic-password -a $USER -s Key1 -w APPID_1:APPSECRET_1 -U验证能读到只验证别把输出贴到聊天记录security find-generic-password -a $USER -s Key1 -w这里要澄清一个容易混的概念AppID 是 QQ 开放平台里的机器人 ID纯数字AppSecret 是机器人密钥而accountId比如bot1是 OpenClaw 内部路由用的账号标识不是密钥。token 的格式是AppID:AppSecret中间用冒号连接。4.3 配置频道账号单账号openclaw channels add \ --channel qqbot \ --account bot1 \ --token $(security find-generic-password -a $USER -s Key1 -w)多账号就重复执行换--account和 Keychain 条目名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.qqbot4.4 创建 Agent 并绑定路由创建两个 Agentopenclaw 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 --json4.5 重启网关并验证openclaw gateway restart看配置层状态openclaw channels status期望看到类似QQ Bot bot1: 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: tREADY这三类日志说明 QQ Bot 已经在线。这时候在 QQ 里给机器人发一条消息Agent 应该能收到并回复。5. 本篇常见错排查Q1插件安装失败报 TLS/证书错误。回到 4.1 节设置 npm cafile确认证书文件非空。如果公司网络有自签证书需要把公司根证书也追加进去。Q2channels status提示很多 env var 缺失。这是当前 shell 没加载环境变量。如果你依赖~/.zshrc注入先执行source ~/.zshrc再重启网关。Q3QQ 已连上但消息没进目标 Agent。优先检查三件事绑定用的 accountId 大小写是否一致插件会规范成小写是否还保留泛路由qqbot抢路由openclaw agents bindings里是否存在精准规则qqbot:accountId。Q4多账号时默认路由不明确。显式给每个 QQ Bot 配 agent bind不要只依赖默认路由。config.toml的[routing]段和 CLI 绑定二选一别两边都写。Q5模型调用报 401 或超时。检查TAOTOKEN_API_KEY是否在当前 shell 可见base_url是否写成https://taotoken.net/api注意不要多加路径。如果 Key 刚创建确认没有多余空格。6. 日常运维与下一步日常最常用的几条命令openclaw agents list openclaw agents bindings openclaw gateway restart tail -f ~/.openclaw/logs/gateway.log如果你要长期跑编码类 Agent建议把模型通道固定到 TaoToken 的 Coding Plan这样多 Agent 共享额度不用每个 workspace 单独配 Key。接入文档里有完整的参数说明遇到路由或鉴权问题可以先翻文档对照。验证模型是否通的时候可以直接在模型对话页面发一条测试消息确认 Key 和 base_url 没问题再回到 OpenClaw 排查频道层。这样能把“模型不通”和“QQ 频道不通”两类问题分开省很多时间。最后提醒一句QQ 开放平台截图里如果出现过完整 AppSecret建议立即在平台轮换重置然后重新执行channels add更新 Keychain 里的值。本地联调阶段多改几次没关系但别让旧密钥留在任何日志或文档里。