openclaw 连接微信手机端：TaoToken 统一 Key 打通插件安装与文件传输

1. 手机端微信接入 openclaw 到底卡在哪从扫码到文件传输的完整链路openclaw 连接微信手机端这件事本质上是在做一次「跨端桥接」手机微信负责扫码授权和消息收发服务端的 openclaw 负责跑模型和插件逻辑中间靠一个网关把两边串起来。听起来简单但真正动手时卡点往往集中在三个地方——微信版本不够导致插件入口不出现、服务端插件装完网关没重启、文件传输时路径和权限对不上。这篇就围绕 openclaw 在微信手机端的接入流程把插件安装和文件传输这两个高频环节拆开讲每一步都给可复制的命令和验证动作。先说清楚它适合谁如果你手上有一台能跑 Node 的服务器本地 Ubuntu、云主机都行手机微信版本在 8.0.70 以上想用 openclaw 把微信当成一个聊天入口来驱动模型或自动化任务那这套流程就是给你准备的。核心检索词就三个openclaw、微信手机端、插件安装与文件传输。整条链路里鉴权配置是最容易反复折腾的部分因为 openclaw 的插件、网关、模型调用各自可能要一套 Key。我的做法是用 TaoToken 的统一 Key/API 通道把模型鉴权收敛成一份配置后面插件和文件传输环节就不用再到处填 Key 了。先看整体链路心里有个图手机微信扫码授权→ 服务端网关openclaw-weixin-cli→ openclaw 主进程跑模型/插件→ 模型 APITaoToken 统一通道四个环节里手机端只负责「扫码 收发消息 传文件」服务端负责「装插件 起网关 调模型」。所以你在手机端看到的任何异常八成要回到服务端日志里找原因。这也是为什么下面每个步骤我都会配一条验证命令——不验证就等于没装。在开始之前确认两件事一是手机微信版本路径在「我 → 设置 → 关于微信」版本号必须大于 8.0.70低于这个版本插件入口不会出现二是服务端 Node 版本建议 18 以上用node -v看一眼。这两条不满足后面所有步骤都会在奇怪的地方失败。2. TaoToken 前置准备把模型鉴权收敛成一份统一 Key在装微信插件之前先把模型侧的鉴权搞定否则插件装完、扫码成功一发消息就报鉴权错误你还得回头重来。openclaw 调模型时需要 Base URL、API Key、Model ID 三件套如果每个插件、每个子进程都单独配维护起来很痛苦。TaoToken 的作用就是提供一个统一的 API 通道你只维护一份 Keyopenclaw 主进程和插件都指向它。先拿 Key。打开 TaoToken 控制台进入 API Keys 页面创建一个新 Key复制出来先存好。控制台地址是 https://taotoken.net/console API Keys 页面在 https://taotoken.net/api-keys 。创建时给它起个能认出来的名字比如openclaw-weixin方便以后区分。拿到 Key 之后你要确认 openclaw 的模型配置指向 TaoToken 的 API 地址。API 根地址是https://taotoken.net/api注意这里不要带任何查询参数就是干净的根路径。openclaw 的模型配置一般放在项目根目录的配置文件里不同版本可能是config.json、settings.json或环境变量。以 JSON 配置为例模型段大概长这样{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, modelId: claude-3-5-sonnet, timeout: 60000 } }三个字段对应关系要记牢baseUrl填 TaoToken 的 API 根地址apiKey填刚创建的 KeymodelId填你要用的模型 ID。Model ID 必须和 TaoToken 支持的模型名一致写错了会报model not found。如果你不确定用哪个模型可以先在模型对话页面试一下地址是 https://taotoken.net/chat 选一个能正常回复的模型把它的 ID 抄到配置里。如果你更习惯用环境变量也可以这样export OPENAI_BASE_URLhttps://taotoken.net/api export OPENAI_API_KEYsk-你的TaoToken密钥 export OPENCLAW_MODEL_IDclaude-3-5-sonnet环境变量的好处是插件子进程能自动继承不用每个插件单独配。坏处是重启终端就没了所以生产环境建议写进 systemd 的Environment或.env文件。配完之后先别急着装微信插件单独验证一下模型通道通不通。用 curl 打一发curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-3-5-sonnet, messages: [{role: user, content: ping}] }返回里能看到choices数组和一段回复内容就说明模型通道没问题。这一步过了后面微信插件调模型才有意义。如果这里就报 401先别往下走回去检查 Key 有没有复制全、有没有多余空格。3. 可复制配置服务端安装微信插件与网关参数模型通道验证通过后进入插件安装环节。openclaw 的微信插件通过 npm 包分发包名是tencent-weixin/openclaw-weixin-cli。安装命令在服务端执行npx -y tencent-weixin/openclaw-weixin-clilatest install这条命令会自动拉取最新版插件、写入 openclaw 的插件目录并在安装完成后重启网关。安装过程中终端会输出一段二维码或者提示你用手机扫描。这里有个细节二维码是网关生成的不是插件本身生成的所以如果网关没起来二维码不会出现。安装完成后先确认插件目录里有没有东西。默认路径一般在~/.openclaw/plugins/下ls -la ~/.openclaw/plugins/ | grep weixin能看到openclaw-weixin相关目录说明插件文件落地了。接着看网关状态ps aux | grep openclaw-gateway如果没看到进程手动起一下npx -y tencent-weixin/openclaw-weixin-clilatest gateway start网关起来后手机端操作打开微信进入「我 → 设置 → 插件」应该能看到 ClawBot 或 openclaw 相关的插件入口。点进去会显示连接状态和二维码。用手机扫描服务端终端或日志里输出的二维码完成授权绑定。如果你用的是 openclaw 的 TOML 配置部分版本支持插件段可以这样写[plugins.weixin] enabled true gateway_port 18789 auto_restart true model_base_url https://taotoken.net/api model_api_key sk-你的TaoToken密钥 model_id claude-3-5-sonnet注意gateway_port要和网关实际监听端口一致默认 18789如果你改过要同步。model_*三个字段就是前面 TaoToken 的三件套写在这里的好处是插件启动时直接读不用依赖环境变量。多人使用同一 openclaw 的场景配置上不用改但操作上要注意每个人在聊天窗口输入「启动微信扫描登录」会生成一个新的连接二维码用各自的手机扫各自的码就会绑定成不同的会话。网关会按会话隔离上下文所以 A 和 B 同时用不会串消息。这一点在团队共用一台服务器时很实用。配置写完后重启一次网关让配置生效npx -y tencent-weixin/openclaw-weixin-clilatest gateway restart重启后看日志确认没有报错tail -f ~/.openclaw/logs/gateway.log日志里出现gateway listening on 18789和weixin plugin loaded两行基本就稳了。4. 验证请求与文件传输从发消息到传文件的成功结果配置就绪后做一次端到端验证。手机微信里给绑定的 ClawBot 发一条消息比如「你好」服务端日志应该能看到请求进来、模型调用、回复返回三段记录。手机端收到回复说明消息链路通了。消息通了之后测文件传输。文件传输是 openclaw 微信插件里比较容易出问题的一环因为它涉及手机端上传、网关接收、服务端落盘三个步骤。先在手机端发一张图片或一个文档给 ClawBot然后在服务端看落盘目录ls -la ~/.openclaw/workspace/weixin/files/正常情况下能看到刚传的文件文件名可能带时间戳或哈希。如果目录是空的先看网关日志里有没有file received字样没有的话说明手机端上传没到网关检查微信版本和插件权限有file received但目录空说明落盘路径配置不对回去检查workspace配置。反向传输服务端发文件到手机需要 openclaw 主动调用发送接口。以图片为例在 openclaw 的会话里执行npx -y tencent-weixin/openclaw-weixin-clilatest send \ --to 会话ID \ --file /path/to/image.png \ --type image会话ID在网关日志里能查到每次扫码绑定会生成一个。发送成功后手机端会收到图片消息。如果报file too large检查插件配置里的max_file_size默认可能是 10MB大文件要调大。验证模型调用是否真的走了 TaoToken可以在网关日志里搜baseUrlgrep -i taotoken ~/.openclaw/logs/gateway.log能看到请求地址是https://taotoken.net/api/v1/chat/completions说明模型鉴权走的是统一通道没有走本地默认配置。这一步确认了整个链路才算真正闭环。多人场景再验一次让第二个人在聊天窗口输入「启动微信扫描登录」生成新二维码用第二台手机扫。扫完后两个人分别发消息看日志里是不是两个不同的会话 ID回复是否各自独立。如果串了检查网关的会话隔离配置通常是session_isolation true没开。5. 本篇常见错排查401、local proxy failed、reading choices 逐个拆实际跑下来报错集中在几个固定位置。下面按真实报错对照排查。401 Unauthorized模型调用返回 401九成是 Key 问题。先确认apiKey字段没有多余空格再确认 Key 没有过期或被删。用前面那条 curl 单独测一次curl 通但 openclaw 不通说明 openclaw 读的配置不是你改的那份检查是否有多个配置文件、环境变量是否覆盖了文件配置。TaoToken 的 Key 在控制台可以重新生成实在找不到原因就换一个 Key 重试。local proxy failed这个报错通常出现在网关启动阶段意思是本地代理端口起不来。原因一般是端口被占用。查一下lsof -i :18789有进程占用就杀掉或换端口。换端口后记得同步改插件配置里的gateway_port两边不一致会一直连不上。reading choices 报错类似cannot read property choices of undefined说明模型返回体里没有choices字段。常见原因是modelId写错或者 Base URL 少了/v1。TaoToken 的根地址是https://taotoken.net/api但 chat completions 的完整路径是/api/v1/chat/completionsopenclaw 一般会自动拼/v1如果你手动在baseUrl里写了/v1就会变成/v1/v1返回体自然不对。把baseUrl改回干净的根地址即可。OAuth 相关报错如果日志里出现 OAuth 字样通常是微信插件授权过期。重新在手机端进插件页面点重新授权或重新扫码。授权信息存在网关的会话文件里路径一般在~/.openclaw/workspace/weixin/session.json删掉这个文件再重新扫码也能强制刷新。文件传输失败分上传和下载两种。上传失败看网关日志有没有file received没有就是手机端问题下载失败看send命令的--to会话 ID 对不对会话 ID 错了会静默失败。另外检查落盘目录权限~/.openclaw/workspace/weixin/files/如果属主不对网关写不进去。排查时养成一个习惯先看网关日志再看 openclaw 主进程日志最后看模型侧返回。三层日志对应三个环节定位会快很多。6. 把统一 Key 用在长期编码与 Agent 场景微信手机端接入只是 openclaw 的一个入口真正让它有价值的是背后的模型能力和长期运行的 Agent 任务。如果你打算把 openclaw 当成日常编码助手或自动化 Agent 来用鉴权配置的稳定性就很重要——频繁换 Key、每个插件单独配维护成本会很高。用 TaoToken 的统一 Key 通道把 Base URL、Key、Model ID 三件套固定在一处插件、网关、主进程都读同一份配置换模型或换 Key 时只改一个地方。对于长期编码场景可以了解一下 Coding Plan地址是 https://taotoken.net/coding-plan 它面向的是持续性的代码生成和 Agent 调用配合 openclaw 的微信入口你可以在手机上发一条消息就让服务端的 Agent 跑一段任务结果再传回手机。接入文档在 https://taotoken.net/doc 里面有各语言的调用示例和参数说明配置遇到不确定的字段可以去查。回到 openclaw 本身微信手机端的插件安装和文件传输这两个环节跑通之后剩下的就是按你的实际需求扩展插件和任务。建议把网关做成开机自启避免服务器重启后微信入口失效npx -y tencent-weixin/openclaw-weixin-clilatest service install这条命令会注册系统服务重启后自动拉起网关。装完用systemctl status确认一下状态。文件传输目录也建议定期清理避免长期运行把磁盘占满可以加一条定时任务清理超过 7 天的文件。最后留一个实用技巧如果你在手机端发消息后迟迟没回复先别急着重装插件去服务端tail -f一下网关日志看请求有没有进来。请求进来了但没回复问题在模型通道请求没进来问题在微信授权或网关。按这个顺序排查比盲目重装快得多。