PicoClaw 企业微信WeCom接入指南基于官方 WebSocket API 的零公网 IP 部署、流式回复与扫码绑定【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclawPicoClaw 将企业微信WeCom暴露为单一通道channels.wecom构建于 WeCom AI Bot 官方 WebSocket API 之上全程出站连接、无需任何公网回调地址。本文覆盖该通道的三种接入方式Web UI 扫码、CLI 扫码、手动配置、全部配置参数与环境变量并结合pkg/channels/wecom源码解析流式回复、turn 生命周期、路由持久化与消息去重等运行时机制帮助你完成部署并快速定位常见问题。设计要点为什么不需要回调 Webhook传统的企业微信自建应用接入需要企业配置回调 URL、申请token与encoding_aes_key并在服务端监听 HTTP 回调端口。PicoClaw 的 WeCom 通道彻底改变了这一模型它由客户端主动向 WeCom 的 WebSocket 端点wss://openws.work.weixin.qq.com发起出站连接消息推送与指令响应都在这条长连接上完成。这意味着无需暴露任何入站端口容器、内网主机、嵌入式设备均可直接部署不再需要token、encoding_aes_key、webhook_url、webhook_path等回调配置项该通道统一了旧的wecom、wecom_app、wecom_aibot三种分离形态收敛为一个channels.wecom配置模型。通道工厂在 pkg/channels/wecom/init.go 中通过channels.RegisterFactory以config.ChannelWeCom即wecom定义见 pkg/config/config_channel.go注册构造入口 NewChannel 会强制校验bot_id与secret非空websocket_url为空时回填默认端点。支持的功能根据 docs/channels/wecom/README.pt-br.md 与源码实现该通道支持私聊direct与群聊group双形态通过 WeCom AI Bot 协议进行流式回复streaming接收消息类型文本text、语音voice、图片image、文件file、视频video以及混合消息mixed发送消息类型文本以及image、file、voice、video四类媒体通过 Web UI 或 CLI 的 QR 扫码 onboarding共享的发送者白名单allow_from与reasoning_channel_id推理输出路由。快速开始三种接入方式方式一Web UI 扫码绑定推荐打开 Web UI进入Channels → WeCom点击 QR 绑定按钮用企业微信 App 扫码并在 App 内确认后凭据会被自动写入配置。上文的截图即为此流程。方式二CLI 扫码登录执行picoclaw auth wecom该命令的完整行为实现见 cmd/picoclaw/internal/auth/wecom.go向 WeCom 的 QR 生成端点work.weixin.qq.com/ai/qc/generatesource 标识为picoclaw请求二维码并以半角块字符渲染在终端同时打印一个QR Code Link——终端二维码难以扫描时可在浏览器中打开该链接指向work.weixin.qq.com/ai/qc/gen页面每3 秒轮询一次扫码状态wecomQRPollInterval等待用户在企业微信 App 中确认登录成功后将bot_id与secret写入channels.wecom并保存配置同时置enabled: true见 applyWeComAuthResult。默认超时为5 分钟wecomQRPollTimeout可用--timeout延长picoclaw auth wecom --timeout 10m注意仅扫码是不够的——必须在企业微信 App 内点击确认否则命令会一直轮询直到超时。状态机区分scanned已扫描终端提示 Confirm the login in WeCom与success已确认并返回凭据expired则直接报错要求重试。方式三手动配置如果已经持有 WeCom AI Bot 平台的bot_id与secret可直接编辑配置文件{ channel_list: { wecom: { enabled: true, type: wecom, bot_id: YOUR_BOT_ID, secret: YOUR_SECRET, websocket_url: wss://openws.work.weixin.qq.com, send_thinking_message: true, allow_from: [], reasoning_channel_id: } } }仓库中的 config/config.example.json 展示了同一通道在示例配置中的形态bot_id、secret、websocket_url、send_thinking_message位于settings子段外层保留enabled、allow_from、reasoning_channel_id等通用字段可作为字段归置的参考。配置参数详解完整参数表与 pkg/config/config.go 中WeComSettings结构体对应字段类型默认值说明enabledboolfalse启用 WeCom 通道bot_idstring—WeCom AI Bot 标识启用时必填secretstring—WeCom AI Bot 密钥以密文形式存储于.security.yml启用时必填websocket_urlstringwss://openws.work.weixin.qq.comWeCom WebSocket 端点send_thinking_messagebooltrue在流式回复开始前先发送一条Processing...消息allow_fromarray[]发送者白名单空数组表示允许所有发送者reasoning_channel_idstring可选将推理reasoning输出路由到另一个会话secret在配置层以SecureString类型承载见 WeComSettings由 PicoClaw 的安全模块加密后落盘到.security.yml配置文件本身不保留明文密钥。所有字段均可通过PICOCLAW_CHANNELS_WECOM_前缀的环境变量覆盖环境变量对应字段PICOCLAW_CHANNELS_WECOM_ENABLEDenabledPICOCLAW_CHANNELS_WECOM_BOT_IDbot_idPICOCLAW_CHANNELS_WECOM_SECRETsecretPICOCLAW_CHANNELS_WECOM_WEBSOCKET_URLwebsocket_urlPICOCLAW_CHANNELS_WECOM_SEND_THINKING_MESSAGEsend_thinking_messagePICOCLAW_CHANNELS_WECOM_ALLOW_FROMallow_fromPICOCLAW_CHANNELS_WECOM_REASONING_CHANNEL_IDreasoning_channel_id运行时机制源码级解析文档列出的运行时行为均可在 pkg/channels/wecom/wecom.go 中找到一一对应的实现1. 常驻 turn 与流式回复WeCom 的流式回复必须挂在一个活跃 turn上每条入站消息到达时dispatchIncoming 会构造一个wecomTurn{ReqID, ChatID, ChatType, StreamID}入队queueTurn并在send_thinking_message为真时立即推送Processing...开场块。回复流通过BeginStream获取 wecomStreamer其Update/Finalize分别发送未结束/结束的流式块。关键约束来自 常量定义单轮流式最长5 分 30 秒wecomStreamMaxDuration 5*time.Minute 30*time.Second超时后 turn 被消费validateActiveTurn拒绝继续推送流式块最小发送间隔500mswecomStreamMinIntervalUpdate中通过定时器节流连接超时 15s、指令应答超时 10s、心跳 30s 一次wecomCmdPing媒体下载/上传超时 30s。2. 流式不可用时的回退链Send的投递策略是一条清晰的降级链见 Send优先尝试当前活跃 turn 的流式回复 → 失败或 turn 已过期时查询reqIDStore中持久化的路由并走sendActivePush主动 pushmarkdown 消息→ 无路由时直接对msg.ChatID发起主动 push。媒体发送 SendMedia 同理先上传为临时素材再经由 turn 或主动 push 下发上传失败时回退为占位文本避免整条回复丢失。3. 路由持久化与 30 分钟过期req_id → chat的路由关联由 reqIDStore 维护默认持久化到~/.picoclaw/wecom/reqid-store.json不可用时退化为系统临时目录每条路由带ExpiresAtTTL 为30 分钟wecomRouteTTL即文档所述路由关联在 30 分钟不活跃后过期。load时与每次Get/Put都会先清理过期条目文件以0600权限写入。4. 消息去重recentMessageSet是一个容量为1000wecomRecentMessageMax的环形缓冲区加哈希集合Mark返回false即消息重复handleMessageCallback 直接丢弃实现文档所述最近 1000 个消息 ID 的环形缓冲去重。5. 媒体收发入站image/file/video/mixed消息经collectSingleMedia/collectMixedMedia下载携带 AES 密钥的远程素材到本地媒体存储再以mediaRefs交给 agent文本占位为[image]、[file]、[video]等mixed消息会合并其中的文本段并按索引分别落盘图片与文件出站本地文件先经uploadOutboundMedia上传为 WeCom 临时素材再作为媒体消息发送语音消息若平台已给出Voice.Content转写文本则直接作为文本内容处理。6. 断线重连connectLoop以指数退避1s 起步、翻倍、封顶 1 分钟驱动runConnection每次连接重建会清空全部 turns连接失败时记录 warning 并退避重试属于 runConnection 与 connectLoop 的职责。从旧版 WeCom 配置迁移旧配置到统一模型的迁移规则如下与文档一致旧配置迁移方式channels.wecombot webhook改用bot_idsecret的新channels.wecomchannels.wecom_app删除统一使用channels.wecomchannels.wecom_aibot将bot_id与secret移入channels.wecomtoken、encoding_aes_key、webhook_url、webhook_path不再使用删除corp_id、corp_secret、agent_id不再使用删除welcome_message、processing_message、max_steps不再属于 WeCom 通道配置删除故障排查QR 绑定超时无响应扫码后必须在企业微信 App 内确认登录仅扫码不会触发成功状态用更大的超时重试picoclaw auth wecom --timeout 10m终端二维码难以辨认时改用其下方打印的QR Code Link在浏览器中打开。QR 码过期QR 码有效期有限轮询返回expired状态。重新执行picoclaw auth wecom获取新码即可。WebSocket 连接失败核对bot_id与secret是否正确凭据错误会导致subscribe指令被 WeCom 拒绝或连接被断开日志中会出现 WeCom connection lost 警告确认主机可以出站访问wss://openws.work.weixin.qq.com——该模型是纯出站连接不需要任何入站端口。回复收不到检查allow_from是否把目标发送者挡在门外空数组才表示放行所有人检查channels.wecom.bot_id与channels.wecom.secret是否已正确设置且非空——两者是 NewChannel 的硬性前置条件缺失时通道根本无法启动。小结PicoClaw 的 WeCom 通道把企业微信接入压缩到了一个通道、两项凭据picoclaw auth wecom一次扫码即可拿到bot_idsecret此后所有消息都走一条出站 WebSocket。理解其 turn 队列、500ms 节流、5 分 30 秒流式上限、30 分钟路由 TTL 与 1000 条去重环这些边界条件后你就能准确预判为什么这条回复是流式的、那条是主动 push 的从而在生产环境里做更可靠的行为预期与排障。【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考