寒水微痕搞微信接入 OpenClaw，其实比我预想中简单。我上个月把一个旧笔记本翻出来，装上 OpenClaw，把微信通道一开，扫码登录之后，往文件传输助手发了一句“帮我整理今天的待办”，十几秒后消息弹回来，那一刻确实有点上头。社区里管这个微信通道模块叫“小龙虾”，名字很接地气，实际作用就是在 OpenClaw 这个本地 AI 助手机架和微信之间搭一座桥，让微信消息能进到 agent 里，agent 的回复也能从微信发出来。
这篇教程就围绕“从 0 到 1 接入微信”这条主线展开，适合有三五分钟命令行经验、想在自己电脑或云服务器上跑一个微信 AI 助手的读者。整个过程不需要写代码，不需要懂深度学习，会复制命令、会看报错日志就行。文章会把原理、配置、实操、排坑一次讲完，尽量少说废话。
1. 接入前，先搞懂“小龙虾”到底在链路的哪一环
1.1 OpenClaw 是个什么东西
OpenClaw 本质上是一个开源的个人 AI 助手运行时。你可以把它理解成一个“大脑壳”：它负责接收消息、调用大模型、执行技能、管理记忆，最后把结果返回给用户。它不绑定某一家云厂商，也不绑死某一个模型，你可以接 OpenAI 兼容接口、DeepSeek、通义、本地 Ollama，甚至接 NVIDIA NIM 这类企业级推理服务。
我第一次接触 OpenClaw 时，觉得它像是一个“没有身体的机器人操作系统”。它本身不解决“消息从哪里来”的问题，也不解决“消息往哪里去”的问题，它只解决“消息进来之后该怎么处理”的问题。那消息通道从哪来？这就是通道（Channel）模块做的事。OpenClaw 官方和社区生态里提供了很多通道适配，比如命令行、网页控制台、Telegram、Slack，还有我们今天要说的微信。
1.2 微信和 OpenClaw 之间为什么需要“通道”
微信是一个相对封闭的 IM 系统，没有开放的个人号聊天 API。想让自己控制的微信号收发消息，只能通过客户端协议适配的方式来做。OpenClaw 里的微信通道，就是社区开发者基于微信客户端协议实现的适配层，它能够监听微信收到的消息，把文本消息转发给 OpenClaw 核心，再把 core 生成的回复发回对端。
“小龙虾”这个昵称，我印象里是社区里某个版本的微信通道项目自带的中文代号，后来大家叫着叫着就成了通用叫法。它实际做的事情不复杂，但很关键。你可以把 OpenClaw 核心比作一个人的大脑，把微信通道比作眼睛、耳朵和嘴。没有通道，大脑再聪明也没法通过微信跟你对话。
整个链路大致是这样：微信好友发来消息 -> 小龙虾通道捕获消息 -> 转成 OpenClaw 的标准化消息格式 -> Agent 收到后决定要不要调用技能、要不要查记忆 -> 调用模型生成回复 -> 通道把回复发回微信。这个链路里每一步都有日志，排查问题基本靠日志就够了。
1.3 方案选型：为什么用 OpenClaw 而不是自建机器人
在接微信 AI 助手这件事上，有两条常见路线：一条是自己写协议客户端，另一条是直接用开源的机器人框架。自己写的好处是可控，坏处是工作量大，而且微信协议本身变动频繁，今天能跑明天可能就挂。开源机器人框架虽然省事，但往往只解决“收发消息”这一层，没有模型调度、技能执行、长期记忆这些能力。
OpenClaw 刚好卡在中间：通道部分由社区持续维护，核心部分提供了完整的 Agent 能力。你可以只把它当成一个“消息转发 + 模型调用”服务来用，也可以逐步加技能、加知识库、加定时任务。对个人用户来说，这个投入产出比是最划算的。
还有一个考量是数据隐私。用 OpenClaw 接微信，聊天记录和上下文是存在你自己机器上的，模型调用可以选本地模型或国内 API，敏感信息不用经过第三方 IM 机器人平台。这也是我最终选它的原因。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备：装好运行时，避免一半的坑
2.1 前置依赖清单
在正式安装 OpenClaw 之前，先把环境检查一遍。很多教程让你直接跑安装命令，结果报错一堆，大部分都是因为 Node.js 没装好或者版本不对。
OpenClaw 基于 Node.js 构建，所以第一步是装 Node.js。建议装 LTS 版本，不要装最新的奇数版本，至少是 Node.js 18 以上，20 更稳。安装完成后打开终端，分别执行：
bash复制node -v
npm -v
这两个命令能输出版本号，说明 Node 环境没问题。如果提示“node 不是内部或外部命令”，那说明安装时没把 Node 加到 PATH，或者安装根本没成功，重装一次，勾选自动加入 PATH 的选项就行。
除了 Node.js，还需要 Git。Windows 用户如果打算拉取一些社区扩展包，Git 是少不了的。Linux 服务器一般自带或可以用包管理器一键装，Windows 装 Git 时用默认选项一路下一步即可。
提示：如果你用的是 Windows，建议全程用 PowerShell 或 Windows Terminal 执行命令，不要用 cmd。OpenClaw 的一些提示符交互在 PowerShell 下显示更正常，复制粘贴也不容易出乱码。
2.2 用一条命令完成 OpenClaw 安装
环境没问题之后，安装 OpenClaw 本身其实只要一条命令。OpenClaw 提供了全局 CLI 工具，安装后可以直接在终端里使用 openclaw 命令：
bash复制npm install -g @openclaw/cli
安装过程中如果遇到权限报错，Linux/macOS 用户可以在命令前面加 sudo，Windows 用户一般不会遇到权限问题。装完执行：
bash复制openclaw --version
能看到版本号，说明 CLI 安装成功。社区里也有一键部署工具，把 Node、CLI、常用依赖打包处理了，但我个人还是比较推荐手动装一遍，这样出了问题你知道去哪查。
注意：安装过程如果特别慢，可以临时把 npm 源切到国内镜像，用
npm config set registry https://registry.npmmirror.com再重试。装完可以切回来，不影响使用。
2.3 初始化项目目录与配置文件
OpenClaw 装好后，需要初始化一个工作目录，后续的配置、日志、会话数据都会放在这里。我习惯在 home 目录下建一个 openclaw 文件夹：
bash复制mkdir openclaw && cd openclaw
openclaw init
初始化过程中，CLI 会问你几个问题，比如默认模型、工作目录名、是否开启自动更新。这里不用太纠结，后面都可以改。初始化完成后，当前目录下会生成一个 openclaw.config.json 文件，这就是整个助手的核心配置。
打开这个配置文件，你会看到几个关键字段：modelProviders 是模型供应商配置，channels 是通道配置，skills 是技能列表，memory 是记忆服务的配置。刚安装完的时候，channels 可能是空的，需要手动添加微信通道。这些字段我后面会逐个演示怎么填。
另外一个容易被忽略的目录是 ~/.openclaw，它存放的是运行时的全局状态，包括登录会话、日志缓存、临时文件。如果之后遇到“删不掉这个目录”的报错，基本就是有进程还在占用它，后面排查章节会专门讲。
3. 接上模型：没有大脑的助手只会复读
3.1 模型供应商怎么选
OpenClaw 本身不含模型，它需要接一个模型服务才能完成对话。模型就是助手的大脑，没有模型配置，你给小龙虾发消息，它只会返回错误或者直接不回复。
选模型供应商，主要看三个维度：响应速度、调用成本、数据是否敏感。如果你只是自己玩，国内可以直接选 DeepSeek，原因很简单：API 便宜、中文效果好、OpenAI 兼容格式，OpenClaw 配置起来几乎没有障碍。如果你在意数据完全不出本机，那就装 Ollama 跑本地模型，比如 Qwen 系列或 Llama 系列，缺点是速度慢，普通笔记本跑 7B 模型都费劲，建议至少有一块 6GB 显存的显卡再考虑。
企业用户如果正好有 NVIDIA NIM 环境，OpenClaw 也支持把 NIM 的推理端点配进来。NIM 的好处是推理服务可以内网部署，数据链路短，但配置的时候 baseURL 和模型名要严格按 NIM 提供的格式填，一个小数点错了都会识别失败。
3.2 配置 DeepSeek 的实操示例
我实测下来最顺手的是 DeepSeek。先到 DeepSeek 开放平台申请一个 API Key，然后编辑 openclaw.config.json 里的 modelProviders 部分。
下面是一个可以直接用的配置片段：
json复制{
"modelProviders": {
"deepseek": {
"baseURL": "https://api.deepseek.com",
"apiKey": "sk-你的key粘到这里",
"models": ["deepseek-chat", "deepseek-reasoner"]
}
},
"defaultModel": "deepseek/deepseek-chat"
}
这里有个非常容易踩的坑：模型名必须写成 deepseek-chat，不能把 provider 名写进去。如果你在配置里写成了 "defaultModel": "deepseek/deepseek"，启动日志会报 unknown model: deepseek，一眼看上去像模型服务挂了，其实只是名字没写对。
填完配置后，重启 OpenClaw 让配置生效。怎么确认模型配置成功？最简单的办法是在终端里直接跑一个对话测试命令，OpenClaw 提供了 CLI 对话模式：
bash复制openclaw chat
然后输入“你好”，如果模型返回了非空内容，说明模型链路通了。这一步能省下后面大量联调时间。
3.3 顺便聊聊本地模型接入（Ollama / NVIDIA NIM）
如果你不想用云 API，可以把模型切到本地。Ollama 是最省事的本地模型运行工具，下载安装后，先拉一个模型：
bash复制ollama pull qwen2.5:7b
然后在 OpenClaw 配置里加一个 provider，baseURL 填 http://localhost:11434，模型名填 qwen2.5:7b。注意本地模型的响应速度取决于你的机器配置，我用一台 2020 年的笔记本跑 7B 模型，单轮回复要等半分钟以上，体验一般，但至少数据不出本机。
NIM 的配置思路类似，只是地址换成了 NIM 服务的 endpoint，而且通常需要额外的鉴权头。OpenClaw 的模型供应商是插件化的，每种 provider 支持的特性略有差异，配置时以官方文档为准。但核心逻辑都一样：baseURL 指导到哪，apiKey 验证你是谁，model 告诉它用哪个模型。
4. 微信扫码接入：真正“从 0 到 1”的关键一跳
4.1 添加微信通道
模型通了，接下来才是重头戏：把微信通道加上。OpenClaw 的通道管理也是通过 CLI 完成的。在项目目录下执行：
bash复制openclaw channels add wechat
执行完，配置文件里的 channels 部分会多出一个 wechat 条目。如果你用的版本较新，可能还需要单独安装微信通道依赖包，CLI 会提示你执行安装命令，照做就行。
这里要特别强调一个事：一定不要在主微信号上测试。微信协议适配的账号有被限制的风险，这是平台规则决定的，任何第三方接入方式都规避不了。我建议专门准备一个不常用的微信号，先登录几天养一养，不要一注册完就接机器人，否则大概率被风控。
4.2 扫码登录与 session 保存
通道加好之后，启动微信通道，CLI 会输出一个二维码。运行命令一般是：
bash复制openclaw channels start wechat
启动后观察终端输出，会出现一个二维码的 ASCII 字符画，或者一个二维码图片的本地链接。用手机微信扫码，手机上确认登录，终端会提示“login success”。如果二维码显示不完整，可以调整终端窗口宽度，或者用终端里给的本机链接在浏览器里打开，二维码会清晰很多。
登录成功后，OpenClaw 会把登录状态保存成一个 session 文件，一般放在项目目录的 data 或 ~/.openclaw 下。这个文件就是微信登录凭证，之后重启 OpenClaw 不需要重新扫码，除非 session 过期或者微信主动踢下线。
有一点需要注意：微信手机端如果和这个机器人账号同时登录，手机上会显示“Windows微信已登录”之类提示。这是正常的，不要点“退出其他设备”，否则 session 就失效了。
4.3 白名单与安全配置
微信通道接入后，默认情况下，任何给你这个微信号发消息的人，都能触发 AI 回复。如果微信号被拉进某个群，群里有人 @ 这个号，也可能触发。这既是便利也是风险，一定要配置白名单。
OpenClaw 的微信通道支持配置两个列表：allowFriends 和 allowGroups，分别表示允许触发 AI 的好友和群聊。配置方式是在 openclaw.config.json 的 wechat 通道配置下加字段：
json复制{
"channels": {
"wechat": {
"enabled": true,
"allowFriends": ["你自己", "一个测试好友"],
"allowGroups": ["测试群"]
}
}
}
注意这里填的是微信昵称，不是微信 ID。如果你想要更严格的控制，可以设置只允许文件传输助手触发，这样最安全：因为文件传输助手只有你自己能访问，别人不可能给你这个号发消息。实际调试阶段，我强烈建议只开文件传输助手这一个入口，确认稳定后再放开其他好友和群。
提示：配置改动后需要重启 OpenClaw 进程才能生效。有些版本的通道配置支持热加载，但实测偶尔会不生效，所以配置完选择“重启大法”最稳妥。
5. 端到端实测：在微信聊天框里叫醒小龙虾
5.1 启动 OpenClaw 并确认各组件状态
配置完成后，先把整个服务完整启动起来。我的习惯是开两个终端窗口：一个跑 OpenClaw 主进程，一个看日志。主进程启动命令：
bash复制openclaw serve
如果一切正常，终端里会依次看到模型 provider 加载成功、微信通道初始化成功、监听端口就绪这类日志。如果某个组件失败，先别继续，停下把报错信息看清楚。
在这个阶段，有一个经典问题会出现：浏览器控制台打不开，日志里提示 control UI did not start。这通常只是网页控制面板没起来，不影响微信通道本身。如果你需要控制面板，可以手动访问日志里给出的 localhost 地址；如果不需要，完全忽略它。
5.2 用文件传输助手做最小化验证
启动成功后，微信扫码登录。等终端输出“login success”，然后打开手机微信，找到文件传输助手，发一句：“你是我的 AI 助手，现在在线吗？”
正常情况下，过几秒到十几秒，你会收到回复。这个时间取决于你配置的模型：本地模型慢一些，云 API 快一些。如果文件传输助手里回复过来了，说明整条链路已经通了：微信消息 -> 小龙虾通道 -> OpenClaw Agent -> 模型 -> 回发微信。
如果发出去没有反应，立刻去终端看日志。最常出现的情况是消息没有进入 Agent，日志里根本没有收到消息的记录，那问题就出在通道登录状态上，重新扫码一般能解决。如果日志显示 Agent 收到了，但回复失败，那问题基本在 API Key、额度、模型名这三个地方。
5.3 进阶：让小龙虾调用技能和记忆
文件传输助手只测试通过还不够，你肯定想让小龙虾做更多事。比如我给它加了一个“待办清单”技能，在微信里发“记录待办：明天上午十点开会”，它就会调用技能把这条写进本地文件，下次问“我最近有什么待办”，它能检索出来。
OpenClaw 的技能就是一组自定义工具。写一个技能，本质上是做一个带有描述和入参定义的函数，然后丢进 skills 目录。比如一个最简单的技能目录结构是：
text复制skills/todo/
SKILL.md
run.js
SKILL.md 里描述这个技能是干什么的、参数是什么，Agent 看到描述才知道什么时候该调用它。run.js 里实现具体逻辑，比如追加一行到 todos.md。
记忆功能我把它理解成助手的长期工作记忆。默认情况下模型对话是无状态的，每次调用都是全新上下文。OpenClaw 的 active memory 会把重要的历史信息存进本地向量库，之后 Agent 在回答问题时可以主动检索这些记忆。这意味着你昨天告诉它的偏好，今天再问它，它还“记得”。配置记忆服务会稍微复杂一点，需要启动一个本地向量库服务，但值得研究，尤其是你想让助手越来越懂你的时候。
6. 常见问题速查：我从日志里捞出来的 4 个大坑
6.1 unknown model: deepseek
这个报错我在这段时间的交流群里看到不下十次。现象是安装完 OpenClaw 后，配置了 DeepSeek 的 Key，一启动就提示 agent failed before reply: unknown model: deepseek。
原因很简单：默认模型写错了。你配置的模型名是 deepseek，但 DeepSeek API 认可的模型名是 deepseek-chat 或 deepseek-reasoner。改成正确的模型名，重启服务就好。这不是网络问题，也不是 Key 问题，根因就是字符串不匹配。
6.2 oneclaw node runtime not found
Windows 安装 OpenClaw 时，有时会提示 node runtime not found，但明明已经装了 Node。这个问题的根因通常是 CLI 找不到 node 的安装路径。解决办法是先确认 node 命令在 PowerShell 里能正常执行，然后检查环境变量里的 PATH 是否包含 Node.js 的安装目录。如果 PATH 没问题，把当前终端关掉重新打开一个，让环境变量重新加载。实在不行，重装 Node.js，安装时务必勾选“Add to PATH”。
6.3 failed to remove ~/.openclaw: error: ebusy: resource busy or locked, unlink
这个报错出现在 Windows 上删除 .openclaw 目录时，中文意思是“资源忙或锁定，无法删除”。最常见的原因是后台还有 OpenClaw 相关进程在运行，占用了目录里的文件。解决办法是打开任务管理器，找到所有 node.exe 或 openclaw 相关进程，全部结束，再重新执行删除命令。如果还是删不掉，用 PowerShell 执行 Remove-Item -Recurse -Force ~/.openclaw 强删一次。
这个坑是我在升级版本时遇到的。新版本下载失败后残留了临时文件，导致目录半损坏，进程还在运行，删目录也没权限。先杀进程再强删，一气呵成。
6.4 control UI did not start
openclaw control UI did not start 不一定是真错误，只是网页控制面板没起来。控制面板一般是一个本地 Web 服务，用于可视化查看状态和配置，它没启动不影响微信通道收发消息。如果你需要控制面板，检查日志里打印的实际端口，手动在浏览器打开 http://localhost:端口。如果页面打不开，看看防火墙是不是拦截了 127.0.0.1 的回环地址，或者换一个端口再试。
6.5 微信扫码后没有反应或账号被限制
扫码登录后终端一直不输出 success，或者在手机上确认登录后又掉线，多半是网络或账号风控问题。第一次扫码之前，先确认手机和电脑在同一网络环境，不要用流量扫码。如果账号是刚注册的，建议先在手机上正常使用几天，加几个好友，发几条消息，再考虑接入机器人。我已经见过太多次新号当天扫码当天被限制的情况，这不是 OpenClaw 能解决的问题，尽量从账号层面规避。
真遇到账号被限制，应该先停止一切自动化脚本，然后按微信客户端里的提示完成自助解封流程，等几天再重新尝试。
写在最后的经验
我实际操作中最大的体会是：微信接入 OpenClaw，最花时间的部分不是安装配置，而是“调稳”。第一次跑通可能只要半小时，但让它稳定跑一个月不出问题，需要你在通道白名单、账号使用习惯、模型调用频率上做一些取舍。我的建议很简单：一开始只让文件传输助手触发，别急着接群聊；模型用便宜的云 API，别一上来就折腾本地大模型；每次改配置后重启一次，用文件传输助手做回归测试。这样运转起来的 OpenClaw，才会真的像一个踏实能干的小龙虾，安安静静趴在后台，随叫随到。