技术支持 wechatapi.net最近在把微信接到 OpenClaw想做一个真正能在微信里使用的 Agent 入口。这件事看起来好像只是收消息 - 调 OpenClaw - 发回去但实际做起来坑比想象中多得多。下面我把目前踩过的 7 个最典型的坑总结一下给后面要做类似事情的人少踩一些雷。坑 1回调打通不等于功能可用这是最容易误判的地方。很多人只要看到/wechat/callback能收到 POST消息能打印出来日志里有内容就以为这件事差不多完成了。实际上回调打通只代表入口层能接收到数据。而真正决定系统是否可用的是回调解析对不对群消息识别对不对自己发的消息有没有过滤session 是否合理并发模型会不会乱也就是说“能收到消息”和“这个系统能用”中间还隔着很多细节。坑 2微信群消息不能按私聊逻辑来理解这类接口里群消息最容易写错的地方是把“群 ID”和“真实发送人 ID”混在一起。我一开始也踩了这个坑后来才按回调结构拆清楚。正确判断群消息的逻辑类似这样is_groupfrom_user.endswith(chatroom)orto_user.endswith(chatroom)而真实发送人有时候还要从内容里拆ifis_groupandraw_contentand:\ninraw_content:possible_sender,possible_textraw_content.split(:\n,1)ifpossible_sender.startswith(wxid_):sender_wxidpossible_sender actual_textpossible_text.strip()如果这块一开始没处理好后面白名单判断会乱群上下文会乱机器人会把群 ID 当成人 IDsession 会错得很离谱坑 3不忽略自己发的消息机器人会自回环这件事看起来小但真的很致命。如果你不做这层判断机器人就会这样收到用户消息调 OpenClaw 得到回复发回微信又收到自己刚刚发出去的回复再把这条回复当成新消息送给 OpenClaw最后形成一个非常难排查的自回环。所以我后面强制加了这一步is_selfbool(wxidandfrom_userwxid)ifparsed.get(is_self):return{status:ignored_self}这一步不做后面一切都不稳。坑 4只要底层还是 CLI每条消息都会有冷启动成本我一开始的调用方式很直白cmd[self.bin,agent,--session-id,sid,--message,message.strip()]ressubprocess.run(cmd,capture_outputTrue,textTrue,stdinsubprocess.DEVNULL,timeoutself.chat_timeout)逻辑没问题但体感问题非常明显。因为它意味着每条消息都在做这些事情起一个新进程恢复 session加载 provider初始化环境请求模型退出这就是为什么很多时候OpenClaw 前端 10 秒左右能出结果接到微信里可能就拉到 20~30 秒甚至更久所以如果你也想做这种接入最好先接受一个事实微信这层可以优化但只要底层还是 OpenClaw CLI 单次调用延迟就很难像原生前端那样顺滑。坑 5session_id 不是随便拼就行我一开始为了看着直观session_id 设计成这种wechat:dm:wxid_xxx wechat:group:chatroom_xxx wechat:group:chatroom_xxx:user:wxid_yyy结果后面很快就踩到兼容性问题有些场景下会报Invalid session ID所以最后我把它收敛成更保守的格式只保留字母、数字、下划线、短横线defbuild_session_id(chat_id:str,sender_wxid:str,is_group:bool,config:dict)-str:defnorm(s:str)-str:returnre.sub(r[^a-zA-Z0-9_-],_,str(sor).strip())ifnotis_group:returnfwechat_dm_{norm(chat_id)}ifconfig[GROUP_SESSION_MODE]per_user:returnfwechat_group_{norm(chat_id)}_user_{norm(sender_wxid)}returnfwechat_group_{norm(chat_id)}这一步虽然小但能省掉很多奇怪的会话问题。坑 6不要一开始就接所有消息类型微信消息类型很多文本图片语音文件名片引用小程序系统通知撤回拍一拍如果你一上来就想全吃复杂度会直接爆炸。我后来很快就收敛到一个策略第一阶段只处理文本消息。代码里也直接限制ifmsg_type!1:logger.info( 暂时只处理文本消息已忽略 MsgType%s,msg_type)return{status:ignored_msg_type}这么做的好处很明显回路先跑稳日志更好看逻辑更容易定位后续再逐步放开图片、文件等能力坑 7如果没有并发设计群一热闹就堵住只用一个全局队列 一个 worker是很多 demo 项目的默认写法。但只要一进群聊场景它的问题就会立刻暴露所有会话都串行一个慢请求拖垮后面所有消息用户体感会非常差所以我后来改成了不同 session 可以并发同一个 session 固定路由到同一个 worker保证顺序的同时提升吞吐核心逻辑defshard_index_for_session(session_id:str,worker_count:int)-int:hint(hashlib.md5(session_id.encode(utf-8)).hexdigest(),16)returnh%worker_count然后worker_queues[shard_idx].put_nowait(task)这一步非常重要它本质上决定了这个系统是“玩具”还是“入口网关”。我后来做了哪些修正把这些坑踩完以后我后面做了几件真正有价值的改动1. 首次运行改成命令行初始化不让用户先打开配置文件手改。2. 自动生成带注释配置文件方便后面自己继续改参数。3. 加白名单私聊不是谁都能直接触发。4. 加群触发词避免群里所有消息都打进来。5. 默认关闭“正在处理中”不然体验很像机器人在刷屏。6. 失败提示收口不要把 OpenClaw 的底层报错直接吐给最终用户。我现在的判断把微信接到 OpenClaw绝对不是不值得做。但它真正难的地方从来不是“把接口接通”而是把这条链路做到像一个产品而不是一个脚本。如果你现在也在做类似事情我最想给的建议是不要一开始就追求“全功能”先把最小稳定闭环做出来。只要这个闭环稳定了后面的能力都可以继续叠加。最后我现在更愿意把这件事看成OpenClaw 负责能力层微信负责入口层网关负责把两者真正接起来而不是简单地理解成“消息转发脚本”。如果你也在做这一类方向欢迎交流。