Coze Agent接入微信：从验签回调到异步回复的桥接实战

简介：一套面向开发者的Coze Agent接入微信的可运行源码，旨在解决将智能助手接入个人微信、实现群聊与私聊自动回复的核心需求。源码包内共3个文件，涵盖1个inscode配置、1个html页面及1个gitignore配置文件，整体仅7KB，轻量易用。作者将创建Coze Bot、设置人设与回复逻辑、获取API令牌、搭建微信机器人服务的步骤沉淀为可直接运行的工程文件，并附有Docker与docker-compose部署思路，适合有一定Python或API基础、希望快速落地微信机器人的开发者。压缩包结构简洁，便于二次修改与复用。该资源目前已吸引138人学习浏览，尤其适合需要企业自动化回复、客户服务或个人助理场景的入门者参考。

1. Coze Agent接入微信：一句话讲清这件事和它的价值

Coze Agent接入微信，说白了就是把你搭好的Coze智能体挂到微信对话框里：用户在公众号或企业微信里发一条消息，微信回调到你的服务器，服务器把它转发给Coze API，等AI生成回复后再原路发回给用户。整个链路里最难的不是AI，而是桥本身——微信验签、5秒超时、消息格式、并发隔离，任何一个没处理好，Agent就一言不发。这里不聊大而全的Agent框架，只讲一个能跑起来的最小桥接服务怎么写，参数怎么设，以及那些让人排查到深夜的坑在哪。适合正在做公众号客服、企业知识库入口，或想给现有微信应用加一个AI助手的开发者。

2. 接入前设计：通道选型、会话隔离与消息长度策略

动手写代码前，先把三个设计问题定下来：走哪个微信通道、怎么区分不同用户、AI回复太长怎么办。这三个问题直接决定后面的代码结构和踩坑数量，值得花一章讲清楚。

2.1 微信通道选哪个：公众号、企业微信，还是个人号

微信生态里能接AI的通道不少，但适合做生产环境接入的其实只有两个。公众号有官方服务器回调，用户在对话框里发什么内容，微信会实时POST到你的服务器，这是最标准的接入姿势；企业微信的自建应用也提供类似回调，且消息可以直接指定给成员或部门，适合企业内部知识库问答。个人号没有官方接口，市面上那些自动化方案普遍依赖非官方hook或模拟登录，稳定性和账号风控风险都不可控，不建议把生产系统建在这上面。

通道	消息接入方式	适合场景	主要风险
公众号（订阅号/服务号）	官方服务器回调，接收文本/图片/事件	对外客服、公开知识库问答	需公网HTTPS地址，消息类型以文本为主
企业微信自建应用	官方回调，可指定成员/部门	企业内部文档问答、数据查询	配置链路较长，需要企业微信管理后台权限
个人微信	无官方接口，依赖非官方方案	不建议生产使用	稳定性与风控风险，随时可能失效

我一般建议个人开发者先用订阅号跑通验证。订阅号注册门槛低，服务器配置填URL和Token后就能收到消息；服务号有更完整的客服消息权限，适合后续做主动推送；企业微信则留给公司内部场景，因为它的消息天然带组织身份，省去公众号里维护openid和用户档案对应关系的麻烦。

开发阶段还有一件事要提前确认：公众号后台的「服务器配置」里填URL和Token时，微信会向你的URL发一次GET验签请求，只有验签通过才能保存成功。所以第一步不是写转发逻辑，而是先把验签跑通，这一点在第3章会给出完整代码。

2.2 会话隔离：用openid当Coze的user_id

Coze的API调用里通常有两个关键字段：bot_id和user_id。bot_id告诉Coze调哪个Agent，user_id告诉Coze“这是谁在说话”，多轮记忆、知识库个性化都基于这个维度。如果所有用户都传同一个user_id，Coze会把所有人的上下文混成一个人，A问的问题，B接着问时会共享上下文，回答自然就串了。

微信侧每个用户在同一个公众号下的openid是唯一的，这是天然的user_id。我建议把openid直接透传给Coze，并在自己的服务里用openid做key维护状态：

from collections import defaultdict # 以 openid 为 key 保存用户的会话状态 session_map = defaultdict(dict) def get_user_state(openid: str) -> dict: return session_map[openid] def save_user_state(openid: str, state: dict) -> None: session_map[openid] = state

逻辑说明：session_map是一个常驻内存的dict，每个openid对应一个独立的dict，里面放last_query、last_reply_time、pending_tasks等字段。Coze侧的历史会话记忆由user_id维度管理，所以这里只要保证openid透传一致，上下文就不会乱。生产环境如果有多台机器，要把session_map换成Redis，key设计为wechat:{appid}:{openid}，并设置过期时间，避免内存无限增长。

参数说明：openid本身是字母数字串，长度28位左右，直接作为Coze的user_id是安全的。注意别把unionid混进来——unionid在多个公众号/小程序间一致，但单场景下用openid就够，unionid还需要额外权限，没必要为第一版引入。

2.3 触发方式：避免把每一条消息都送进Coze

微信会把所有用户消息推给服务器。如果公众号同时有人工客服，或用户发的是“在吗”“你好”这类无意义消息，也会被转发给Coze，既浪费调用次数又让对话上下文变脏。常见做法是加触发前缀或维护白名单。

TRIGGER_PREFIX = "@bot" # 用户只有以 @bot 开头才会触发 ALLOWED_OPENIDS = {"oXXXX", "oYYYY"} # 测试期可只放自己的 openid def should_forward(openid: str, content: str) -> bool: if ALLOWED_OPENIDS and openid not in ALLOWED_OPENIDS: return False if TRIGGER_PREFIX and not content.startswith(TRIGGER_PREFIX): return False return True

逻辑说明：测试阶段开白名单，上线后如果只想让Coze回答特定问题，保留前缀触发；其余消息可以在公众号后台设置自动回复。把触发判断放在转发最前面，省下的不只是钱，还有Coze侧上下文被无关消息污染的问题。我在模拟项目X里吃过亏：没加前缀时，用户连续发“在吗”“还在吗”“人呢”，Coze把这几个问句当成多轮上下文，后面的正题回答质量明显变差。

参数说明：ALLOWED_OPENIDS为空集合时表示不限制；TRIGGER_PREFIX为空字符串时表示所有文本消息都触发。这两个开关建议暴露成环境变量，不要写死在代码里，方便灰度上线。

2.4 回复长度：微信不是让你发万字长文的

Coze一次可以生成上千字，但微信文本消息有长度上限，被动回复大约2048字节（不同账号类型有差异），超过会被截断或直接失败。而且被动回复只有5秒窗口，Coze生成太长内容也会拖慢整个链路。常见做法是做按字节截断与分段发送：

def split_reply(text: str, max_bytes: int = 1800) -> list[str]: # 优先按换行分段，避免截断在一句话中间 paragraphs = [p for p in text.split("\n") if p.strip()] chunks, cur = [], "" for para in paragraphs: if len(cur.encode("utf-8")) + len(para.encode("utf-8")) <= max_bytes: cur += para + "\n" else: if cur: chunks.append(cur.strip()) cur = para + "\n" if cur: chunks.append(cur.strip()) return chunks

逻辑说明：这个函数按段落切分，每段不超过1800字节而不是2048，因为还要给XML标签和CDATA留余量。注意这里用encode("utf-8")计算字节数，不能用len()——中文在UTF-8下是3字节，直接用len切会切出半个字符。

参数说明：max_bytes要留缓冲区，所以设1800；微信的显示区域里一条消息超过约600字就会折叠，如果想让用户体验好，我一般会把max_bytes设到500到800，把长回复拆成几条连续发，而不是一口气推一大段。

3. 可运行源码：从微信消息到Coze回复的桥接服务

这章给出整个桥接服务的核心代码。代码按“验签入口、消息接收、Coze调用、回复封装”四段拆开，每一段都能独立测试。

3.1 技术选型：为什么用FastAPI而不是Flask

这个链路里最核心的需求是“等待Coze时不阻塞其他请求”。Coze推理通常要2到8秒，微信服务器推送消息不是串行的，用户量一上来，多个请求会同时到达。如果框架是同步的，比如Flask多worker模式，一个请求在等Coze时占住一个worker，并发一高，其他消息全部排队，延迟会从5秒变成几十秒。

FastAPI配合async/await，可以在等待Coze返回时把控制权交出去处理别的请求。我第一版用Flask写，在并发测试时直接翻车，后来换成FastAPI，同样的逻辑代码量几乎没变。依赖只需要四个包，版本号建议用你当前环境的稳定版：

fastapi uvicorn python-dotenv httpx

FastAPI负责路由和请求解析，uvicorn是ASGI服务器，httpx用来异步调用Coze。不需要引额外的微信SDK，微信的验签和XML解析自己写也就几十行，引入一个不熟悉的SDK反而增加黑匣子。

3.2 微信回调验签：URL配置能保存的前提

微信后台保存「服务器配置」时，会往你的URL发GET请求，带上signature、timestamp、nonce、echostr四个参数。验签算法是：把开发者自己填的Token、timestamp、nonce三个值按字典序排序，拼接成一个字符串，做SHA1加密，与signature比对，相等就把echostr原样返回。

import hashlib from fastapi import FastAPI, Query from fastapi.responses import PlainTextResponse app = FastAPI() TOKEN = "your_token" # 与公众号后台填写的 Token 保持一致 def verify_signature(signature: str, timestamp: str, nonce: str) -> bool: tmp = "".join(sorted([TOKEN, timestamp, nonce])) return hashlib.sha1(tmp.encode("utf-8")).hexdigest() == signature @app.get("/wechat") async def wechat_get( signature: str = Query(""), timestamp: str = Query(""), nonce: str = Query(""), echostr: str = Query(""), ): if verify_signature(signature, timestamp, nonce): return PlainTextResponse(echostr) # 必须是裸字符串，不能带引号或换行 return PlainTextResponse("forbidden")

逻辑说明：这是微信回调的“握手”入口。FastAPI的Query参数会自动解析URL上的参数；PlainTextResponse保证返回体里没有多余引号和换行。很多人在这一步失败是因为直接返回了JSON字符串，或者开发框架统一给响应加了引号，微信比对不通过就提示保存失败。

参数说明：TOKEN是你自己在公众号后台填的任意字符串，不要和Coze的API Key混用。签名算法里sorted默认按字典序，三个值拼起来中间不加任何分隔符，这是微信的固定规则，不是你自己定的。

3.3 收到微信文本消息并转发给Coze

用户发给公众号的普通消息是POST请求，body是XML，字段包括ToUserName（公众号id）、FromUserName（用户的openid）、MsgType（text/image/event等）、Content（文本内容）。先解析XML，再按消息类型分发：

import xml.etree.ElementTree as ET from fastapi import Request, Response def parse_xml(xml_str: str) -> dict: root = ET.fromstring(xml_str) return {child.tag: child.text or "" for child in root} @app.post("/wechat") async def wechat_post(request: Request): xml_str = (await request.body()).decode("utf-8") data = parse_xml(xml_str) msg_type = data.get("MsgType") openid = data.get("FromUserName") # event 分支：关注/取关等事件，握手成功即可，不需要 AI 回复 if msg_type == "event": return PlainTextResponse("") content = data.get("Content", "").strip() if not content: return PlainTextResponse("") # 异步调 Coze，等待期间不阻塞其他请求 reply = await call_coze(openid, content) xml_resp = build_text_reply(openid, data.get("ToUserName"), reply) return Response(content=xml_resp, media_type="application/xml")

逻辑说明：事件消息（如用户关注公众号）也会POST过来，这类消息直接返回空字符串，否则用户每次关注都会触发一次Coze调用，额度消耗很快。文本消息才进Coze链路。parse_xml、build_text_reply、call_coze三个函数分别负责解析、拼XML、调外部API，职责拆开方便排查——哪一段出问题，日志就能定位。

注意ElementTree解析CDATA时，取到的text是去掉CDATA包裹后的原文，不会再带<![CDATA[符号。如果你自己用正则去解析XML，反而容易把这些符号带进Coze的输入，让AI回复一个带乱码的文本。

3.4 拼回复XML：这一步决定微信会不会显示

被动回复的XML格式是固定的，Content字段必须用CDATA包起来，否则消息里的特殊符号会破坏XML结构：

import time def build_text_reply(openid: str, appid: str, content: str) -> bytes: reply = ( "<xml>" f"<ToUserName><![CDATA[{openid}]]></ToUserName>" f"<FromUserName><![CDATA[{appid}]]></FromUserName>" f"<CreateTime>{int(time.time())}</CreateTime>" "<MsgType><![CDATA[text]]></MsgType>" f"<Content><![CDATA[{content}]]></Content>" "</xml>" ) return reply.encode("utf-8")

逻辑说明：这里是整条链路最容易出玄学问题的地方。ToUserName要填用户的openid，FromUserName填公众号的appid，别填反——我见过填反后消息偶尔能发出去、偶尔丢失的案例，因为微信侧校验不严格时能通过，校验严格时静默丢弃。CreateTime必须是秒级时间戳，不能用毫秒。Content里的换行符保留，但&、<、>这些字符即使包在CDATA里，也建议先做一次转义，微信的解析器在不同版本上行为不完全一致，双保险才不踩坑。

3.5 调Coze API：核心桥接函数

Coze的开放接口在不同环境下的URL不同，这里用占位符COZE_API_URL表示，实际值以你在Coze控制台的API凭据页面为准。核心参数是Authorization、bot_id、user_id、query、stream：

import httpx COZE_API_URL = "https://your-coze-endpoint/v1/chat" # 以控制台实际为准 COZE_TOKEN = "pat_XXXX" # 在 Coze 控制台创建的个人访问令牌 BOT_ID = "your_bot_id" # 发布 Agent 时生成的 Bot ID async def call_coze(openid: str, query: str) -> str: headers = { "Authorization": f"Bearer {COZE_TOKEN}", "Content-Type": "application/json", } payload = { "bot_id": BOT_ID, "user_id": openid, "query": query, "stream": False, } try: async with httpx.AsyncClient(timeout=10) as client: resp = await client.post(COZE_API_URL, headers=headers, json=payload) resp.raise_for_status() data = resp.json() # 返回结构以你的 Coze 接口版本为准，通常是 message/answer 字段 return data.get("message", data.get("answer", "抱歉，我暂时没有答案")) except httpx.TimeoutException: return "抱歉，我思考的时间太长了，请稍后再试" except Exception: return "服务暂时不可用，请稍后再试"

逻辑说明：payload里的user_id就是第2章说的会话隔离关键，直接传openid；stream=False是为了拿到完整回复再返回。第一版没必要开流式，微信不支持流式推送，你最终还是要等完整内容才能拼XML。timeout设为10秒，是因为微信侧有更短的超时限制，这个在下一段讲。特别注意：Authorization的token前缀是Bearer加空格，很多人把这里写成token xxx导致401，这是血泪经验。

参数说明：bot_id在Coze的Agent发布页或控制台能找到；COZE_TOKEN的权限只要“调用Agent”级别，不要用管理员全量Key，泄露范围更小。httpx.AsyncClient的timeout参数同时作用于连接和读取，适合这种外部API慢的场景。

4. 让Coze侧配合：工作流、参数映射与回复格式约定

桥接服务写完了，Coze侧如果没配好，微信里的体验依然很糟糕。这章讲Coze侧怎么配合，包括工作流形态、消息类型映射、回复格式约定。

4.1 在Coze里把Agent配置成适合API调用的形态

直接发布一个聊天Bot也能被API调用，但落地时有两个问题：一是Bot的自由对话回复格式不稳定，微信侧的解析逻辑很难写；二是Bot可以自行决定要不要查知识库、要不要用工具，这个黑匣子在调试时很难判断问题出在哪。

常见做法是给客服场景单独建一个「知识库问答」工作流：输入question，经过知识库检索，再由大模型生成，最后输出answer。这样的输出字段固定，桥接层只需要读answer字段；也方便在Coze侧查看日志，每个环节的耗时一目了然。

{ "answer": "关于报销流程，请先提交电子审批单，再由部门负责人审批。", "source": "员工手册_2024_v3", "confidence": 0.92 }

我在模拟项目X里用这个形态接的客服入口，好处是source字段可以直接透传给微信用户：“以上内容来自《员工手册_2024_v3》”，用户对AI回答的信任度提升非常明显。confidence过低时，桥接层可以兜底回复“这个我不太确定，建议转人工”，能在很早期过滤掉错误回答。

4.2 把微信消息类型映射到Coze的输入边界

微信推送的消息有text、image、voice、video、location等类型。Coze的query接口通常只接受文本。第一版只处理文本，其他类型统一回复提示，不要试图把图片转成base64发给Coze——微信的图片URL有临时性，且公众号图片消息的URL在外网环境受Host校验限制，Coze侧经常拉不到图。想支持coze文件上传的场景，需要另外搭建图片拉取和转存服务，这已经超出了最小可运行的范畴。

if msg_type == "image": return Response( content=build_text_reply( openid, data.get("ToUserName"), "当前版本只支持文字消息，请直接打字提问" ), media_type="application/xml", ) if msg_type == "voice": return Response( content=build_text_reply( openid, data.get("ToUserName"), "语音识别暂未开放，请用文字输入" ), media_type="application/xml", )

逻辑说明：先路由后转发，让Coze永远只收到文本，后续加能力时只需要在路由层加分支。微信的voice消息本身带Recognize字段（语音识别结果），但开通这个能力需要单独申请，识别质量不稳定，不建议第一版接。

参数说明：这些提示文案放在桥接服务里维护，不要放在Coze侧。原因是Coze侧每次修改要重新发布，而桥接服务的文案改完立刻生效，运营调整更灵活。

4.3 回复格式：让Coze输出纯文本而不是Markdown

Coze的默认输出往往带Markdown符号，比如加粗、标题、列表、行内代码。微信的文本消息不渲染Markdown，这些符号会原样暴露给用户，“你好”会显示成两个星号。这一步不用在代码里做正则清洗，更好的方案是直接在Coze的工作流提示词里约定输出格式。

在Coze工作流的「大模型」节点系统提示词里写清楚：

你是一个企业客服助手。请用纯文本回复，不要使用Markdown、不要使用Emoji、不要使用列表符号。需要分点时用数字1、2、3加句号。

如果Coze还是输出Markdown，桥接层加一个兜底清洗函数：

import re def clean_markdown(text: str) -> str: text = re.sub(r"#{1,6}\s*", "", text) # 标题 text = re.sub(r"\*\*([^*]+)\*\*", r"\1", text) # 加粗 text = re.sub(r"\*([^*]+)\*", r"\1", text) # 斜体 text = re.sub(r"`{1,3}[^`]*`{1,3}", "", text) # 行内代码/代码块 text = re.sub(r"!?\[([^\]]*)\]\(([^)]*)\)", r"\1", text) # 链接/图片 return text.strip()

逻辑说明：正则的顺序有讲究，先处理双星号再处理单星号，否则“加粗”会被单星号的正则切成“加粗”。这个函数是兜底，不要当成主方案——再好的正则也会误删内容，比如“价格数量”会被斜体规则变成“价格数量”。

参数说明：提示词里说“不要使用Emoji”很重要，微信文本消息的Emoji在部分机型上会显示成方框，而且Emoji占4字节，会把回复长度预算吃得更紧。

5. 接入微信最常见的5个坑：验签、5秒超时、串号与消息转义

这章写的是会吞掉你半个晚上的问题。每一条都是真实会遇到的，按“现象、原因、解决”拆开讲。

5.1 后台保存配置一直失败：验签入口被框架拦截

现象：公众号后台填好URL和Token，点保存，提示验证失败，但服务端日志里明明收到了GET请求。

原因：大部分情况下是响应格式不对。路由返回了JSON，echostr就带着引号被返回；或者URL填了带query参数的地址，CDN或网关把签名参数剥掉了。还有一种情况是局部变量没引用对TOKEN，导致SHA1算出来的结果永远不一致。

解决：先手动模拟微信验签请求，把GET URL直接粘到浏览器里访问：

curl "http://127.0.0.1:8000/wechat?signature=xxx&timestamp=1730000000&nonce=abc&echostr=hello"

如果返回的不是裸的hello而是带引号的"hello"，就是响应类型问题，改用PlainTextResponse。另外确认没有开启任何要求登录的中间层，否则GET请求被302重定向到登录页，微信拿到的是HTML而不是echostr。

5.2 消息已读不回：5秒被动回复超时

现象：用户在公众号里发消息，服务端日志显示Coze调用成功、回复XML也拼好了，但用户什么都没收到。

原因：微信的被动回复要求在5秒内响应。Coze推理动辄3到8秒，异步调用也没用——微信站在那里等你的HTTP响应，超时后它会重试一次，重试同样超时就丢弃。日志里你看不到错误，因为你的服务端没超时，只是微信那边先放弃了。

解决：改两段式应答。收到消息时立即返回空字符串，同时触发一个异步任务去调Coze，等Coze返回后通过客服消息接口主动下发给用户。客服消息有两个限制：用户必须在48小时内和公众号有交互（关注事件也算）；主动发送有频率限制。实现上是握手返回和AI回复解耦：

import asyncio @app.post("/wechat") async def wechat_post(request: Request): xml_str = (await request.body()).decode("utf-8") data = parse_xml(xml_str) openid = data.get("FromUserName") if data.get("MsgType") == "text": asyncio.create_task( handle_ai_reply(openid, data.get("Content", "")) ) return PlainTextResponse("") # 先握手，AI 回复稍后通过客服消息下发

逻辑说明：asyncio.create_task让AI调用在后台跑，HTTP响应立刻返回空串，微信认为服务正常。handle_ai_reply内部调Coze，拿到结果后调客服消息接口。这样5秒限制绕开了，但要给handle_ai_reply加异常兜底，AI失败时也要给用户发一条“暂时忙不过来”的客服消息，否则用户以为石沉大海。

5.3 回复串线：多人并发时用户B收到了用户A的答案

现象：A和B同时提问，A收到了B的答案。这是做微信AI接入最吓人的翻车现场，比AI答错更严重。

原因：代码里用了模块级变量存“上一条回复”或“当前处理的消息”，两个请求并发时互相覆盖。微信是并发推送的，不要假设请求串行到达。

解决：所有状态一律按openid隔离。上面3.3的代码里reply是call_coze的局部返回值，不落全局变量，就不会串。检查你的代码里有没有下面这种反模式：

# 反模式：全局变量保存回复内容 last_reply = "" async def handle(user, content): global last_reply last_reply = await call_coze(user, content) # 后续把 last_reply 发给某个 user —— 并发时这里就串了

如果你用的是Redis，key必须包含openid；如果只是单机内存，建议加一个openid粒度的异步锁，同一个用户的消息串行处理，不同用户之间并行。

5.4 回复内容带 & 或 < 时，消息直接消失

现象：Coze回复里出现“A&B方案”“价格<100元”这类内容，微信端消息是空的，或者只有前半句。

原因：被动回复XML里Content虽然用CDATA包裹，但如果内容本身带有]]>序列，会提前闭合CDATA；而客服消息接口那边虽然不需要XML转义，但微信的文本消息渲染端对控制字符的处理也不一致。

解决：拼XML前先做转义兜底，不要只依赖CDATA：

from xml.sax.saxutils import escape safe_content = escape(content, {"'": "'", '"': """}) # 然后再拼进 CDATA

逻辑说明：escape会把&转成&、<转成<，这些实体在CDATA里同样会被微信正确还原成原文。注意escape的默认quotelist不包含单双引号，建议手动补上。这就是3.4里build_text_reply建议无论CDATA还是转义都上的原因——玄学问题多半出在这里。

5.5 同一批消息被重复触发，Coze侧费用翻倍

现象：Coze控制台的调用量突然暴增，但真实用户并没怎么增加。

原因：微信对超时未响应的消息会重试，5秒超时一次、重试又一次，两段式应答如果没做消息去重，用户发一条消息，Coze可能被调2次甚至3次。另外，事件消息若没拦截，用户每次关注都产生一次调用。

解决：用MsgId做幂等去重，处理过的消息ID记在已处理集合里，几分钟后过期：

processed_ids = set() def is_duplicate(msg_id: str) -> bool: if msg_id in processed_ids: return True processed_ids.add(msg_id) return False

逻辑说明：MsgId是微信每条消息的唯一ID，在POST body的XML里能取到。集合只保留最近几分钟的ID即可，生产环境用Redis的SETEX设置600秒过期，自然清掉不会撑爆内存。这个去重要放在验签之后、任何AI调用之前，配合事件分支直接返回空串，费用飙升的坑基本就堵住了。

6. 上线前最后一圈：部署、自检清单与一个救命技巧

开发阶段代码跑在本机，微信服务器没法访问到127.0.0.1。想让微信回调到本地，常见做法是用内网穿透工具把本机端口映射成一个公网HTTPS地址，填到公众号后台；但这个地址在免费档通常不稳定，域名会变，只适合开发联调。正式环境还是建议把服务部署到云主机，微信的回调地址一旦变化就要去后台改，服务中断是小，用户感知到“AI助手失踪”才是麻烦。

上线前按这个清单过一遍，我每次部署都照着跑：

检查项	操作方法	通过标准
验签入口	浏览器访问GET URL带模板参数	返回裸echostr
文本链路	公众号后台发一条文本	5秒内收到握手，随后收到AI回复
图片消息	发一张图片	收到“仅支持文字”提示，不触发Coze
并发隔离	两个微信号同时提问	各自收到各自问题的答案
特殊字符	问一句“A&B哪个好”	回复完整，没有截断

最后说一个救过我多次的习惯：写一个小脚本，专门模拟微信验签和文本POST，每次改完桥接代码先跑它，再上公众号。不要总用真机发消息测，真机消息不可控，测一条就调一次Coze，既慢又费钱。我第一次上线时把TOKEN和API Key写反，用真机测了三轮都没发现，全被“已读不回”掩盖了，后来是跑脚本直接看请求体才定位到。从此这个脚本成了我所有微信接入项目的标配，省下的排查时间远超过写它的半小时。希望帮到你。

本文还有配套的精品资源，点击获取