PicoClaw 企业微信WeCom渠道详解基于 WebSocket 出站连接的统一配置与流式回复实现【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclawPicoClaw 将企业微信整合为单一的channels.wecom渠道基于腾讯官方企业微信 AI Bot WebSocket API 实现原有的wecom、wecom_app、wecom_aibot三个独立渠道已合并为统一配置模型。本文完整覆盖该渠道的扫码绑定、手动配置、配置项与环境变量说明、运行时流式回复与媒体收发机制并结合开源仓库源码解释其连接管理、会话路由与消息去重的底层实现。读完后你可以在无需公网回调地址的设备如开发板、内网主机、容器上独立完成企业微信 AI Bot 的接入、配置与问题排查。本渠道无需公网 Webhook 回调地址。PicoClaw 主动向企业微信建立出站 WebSocket 连接因此不需要开放入站端口或配置反向代理。支持的功能单聊和群聊消息收发基于企业微信 AI Bot 协议的流式回复接收文本、语音、图片、文件、视频及混合消息发送文本及媒体消息image、file、voice、video通过 Web UI 或 CLI 扫码绑定发送者白名单和reasoning_channel_id路由从源码结构看上述能力对应pkg/channels/wecom/下的四个核心文件wecom.go连接与消息主逻辑、protocol.go协议命令与消息结构定义、media.go媒体下载/上传、reqid_store.go会话路由持久化。渠道通过 注册入口 以config.ChannelWeCom类型挂载到 PicoClaw 的渠道工厂体系。快速开始方式一Web UI 扫码绑定推荐打开 Web UI进入Channels → WeCom点击扫码绑定按钮。用企业微信扫码并在 App 内确认凭据自动保存。方式二CLI 扫码登录运行picoclaw auth wecom命令执行流程向企业微信请求二维码并在终端打印同时打印一个二维码链接终端二维码不清晰时可在浏览器中打开轮询确认状态——扫码后还需要在企业微信 App 内点击确认成功后将bot_id和secret写入channels.wecom并保存配置默认超时为5 分钟可通过--timeout延长picoclaw auth wecom --timeout 10m⚠️ 仅扫描二维码还不够——必须在企业微信 App 内点击确认否则命令会超时。从 CLI 实现cmd/picoclaw/internal/auth/wecom.go可以看到这条流程的具体参数| 常量 | 值 | 含义 | | ---- | -- | ---- | |wecomQRGenerateEndpoint|https://work.weixin.qq.com/ai/qc/generate| 请求生成二维码的接口 | |wecomQRQueryEndpoint|https://work.weixin.qq.com/ai/qc/query_result| 轮询扫码确认状态的接口 | |wecomQRPollInterval|3 * time.Second| 状态轮询间隔 | |wecomQRPollTimeout|5 * time.Minute| 默认确认等待时长即--timeout的默认值 |命令通过--timeout标志暴露等待时长命令定义确认成功后命令会加载配置、写入bot_id与secret并持久化保存与 Web UI 扫码绑定最终落到同一份channels.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: } } }构造渠道时会强制校验凭据NewChannel 在bot_id或secret为空时直接返回wecom bot_id and secret are required错误未显式指定websocket_url时自动回填默认值wss://openws.work.weixin.qq.com。配置项说明字段类型默认值说明enabledboolfalse启用企业微信渠道。bot_idstring—企业微信 AI Bot 标识符。启用时必填。secretstring—企业微信 AI Bot 密钥。加密存储于.security.yml。启用时必填。websocket_urlstringwss://openws.work.weixin.qq.com企业微信 WebSocket 端点。send_thinking_messagebooltrue在流式回复开始前发送处理中...提示消息。allow_fromarray[]发送者白名单。为空时允许所有人。reasoning_channel_idstring可选将推理/思考内容路由到指定会话 ID。对应源码中的配置结构体 WeComSettings 还包含一个streaming字段StreamingConfig用于控制是否启用流式回复通道allow_from与reasoning_channel_id则来自通用的渠道组配置WeComGroupConfig由基础渠道BaseChannel统一消费白名单过滤与推理内容路由。secret采用SecureString类型封装不在普通配置文件中明文保留而是加密写入.security.yml与 PicoClaw 的凭据加密机制一致。环境变量所有字段均可通过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这与源码中各字段的env标签BOT_ID、SECRET、WEBSOCKET_URL、SEND_THINKING_MESSAGE等相对应前缀PICOCLAW_CHANNELS_WECOM_由渠道名拼接生成适合在容器或 systemd 环境中以环境变量注入密钥而不落盘。运行时行为与源码实现连接管理与心跳渠道启动后在后台 goroutine 中运行连接循环connectLoop使用gorilla/websocket主动拨号到websocket_url连接超时15 秒wecomConnectTimeout。拨号成功后立即发送aibot_subscribe命令携带bot_id与secret完成订阅命令等待回执的超时为10 秒wecomCommandTimeout。心跳循环每30 秒wecomHeartbeatInterval发送一次ping命令心跳写失败会关闭连接。连接断开后按指数退避重连从 1 秒起步、逐次翻倍上限1 分钟。协议层面的所有命令名在 protocol.go 中集中定义aibot_subscribe订阅、ping心跳、aibot_msg_callback消息回调、aibot_event_callback事件回调、aibot_respond_msg应答/流式回复、aibot_send_msg主动推送、aibot_upload_media_init/chunk/finish分段上传媒体。所有帧共用wecomEnvelope信封结构cmdheaders.req_idbodyerrcode/errmsg发送方以req_id关联请求与回执并等待 ack。流式回复Turn 模型与降级策略运行时关键参数在 wecom.go 顶部常量区 中集中声明| 常量 | 值 | 对应行为 | | ---- | -- | -------- | |wecomStreamMaxDuration|5*time.Minute 30*time.Second| 流式回复最大持续时长5.5 分钟| |wecomStreamMinInterval|500 * time.Millisecond| 流式 chunk 最小发送间隔500ms| |wecomRouteTTL|30 * time.Minute| 会话路由30 分钟无活动后过期 | |wecomRecentMessageMax|1000| 消息去重环形缓冲区容量 | |wecomMediaTimeout|30 * time.Second| 媒体下载/上传 HTTP 超时 |具体工作方式为收到用户消息后渠道为该会话创建wecomTurn含ReqID、StreamID、创建时间并推入按会话维护的 Turn 队列SendThinkingMessage为true时会先发出 Processing... 开场 chunk见 dispatchIncoming。Agent 的流式输出通过wecomStreamer发送Update在相邻 chunk 之间强制保持500ms最小间隔UpdateFinalize以finishtrue收尾并消费该 Turn。每发一个 chunk 前都会校验 Turn 是否仍然活跃且未超过5.5 分钟validateActiveTurn超时会话将 Turn 消费掉并报错。流式不可用时无活跃 Turn、Turn 过期、配置关闭流式回复自动降级为主动推送优先从持久化的路由表取最近一次请求的chat_id/chat_type走aibot_send_msgSend。会话路由持久化30 分钟会话路由由 reqid_store.go 实现每条chat_id → (req_id, chat_type, 过期时间)的映射写入 JSON 文件默认路径为~/.picoclaw/wecom/reqid-store.json主目录不可用时退化为临时目录defaultReqIDStorePath。路由以30 分钟TTL 写入读写时都会惰性清理过期项。这意味着 PicoClaw 重启后30 分钟内的会话仍可继续以主动推送方式回复而不必依赖内存状态。媒体收发接收图片、文件、视频消息携带urlaeskey渠道先用带30 秒超时的 HTTP 客户端下载到本地媒体存储storeRemoteMedia再把本地引用mediaRefs与文本内容一起交给 AgentdispatchIncoming。混合消息mixed会逐项解析其中的text/image/file子项并分别落盘语音消息直接透传其转写文本内容。被引用的消息quote文本会在正文为空时兜底作为内容。发送媒体先经aibot_upload_media_init→aibot_upload_media_chunkbase64 分片→aibot_upload_media_finish三步上传为企业微信临时文件拿到media_id后作为image/file/voice/video媒体消息发出协议结构见 protocol.go。上传失败时降级为文本占位回复保证用户始终能收到反馈。去重所有入站消息 ID 经过recentMessageSet环形缓冲区过滤最多记录1000条消息 IDnewRecentMessageSet同一msgid的重复回调会被直接丢弃。从旧版企业微信配置迁移旧配置迁移方式channels.wecomWebhook 机器人改用channels.wecom填写bot_idsecret。channels.wecom_app删除改用channels.wecom。channels.wecom_aibot将bot_id和secret移至channels.wecom。token、encoding_aes_key、webhook_url、webhook_path已废弃从配置中删除。corp_id、corp_secret、agent_id已废弃从配置中删除。welcome_message、processing_message、max_steps已不属于企业微信渠道配置删除即可。常见问题扫码绑定超时扫码后必须在企业微信 App 内点击确认仅扫码不够。使用更长的超时重试picoclaw auth wecom --timeout 10m终端二维码不清晰时使用命令打印的二维码链接在浏览器中打开。二维码已过期二维码有效期有限重新运行picoclaw auth wecom获取新二维码。WebSocket 连接失败检查bot_id和secret是否正确。确认设备可以访问wss://openws.work.weixin.qq.com出站 WebSocket无需开放入站端口。连接失败时渠道会按 1 秒起步、上限 1 分钟的退避策略自动重连日志中会记录每次WeCom connection lost与当前 backoff 值。收不到回复检查allow_from是否屏蔽了发送者。确认channels.wecom.bot_id和channels.wecom.secret已填写且非空。若流式回复中断回复会自动降级为主动推送此时可用~/.picoclaw/wecom/reqid-store.json中是否存在该会话的路由TTL 30 分钟判断降级路径是否可用。相关文件索引文件作用docs/channels/wecom/README.zh.md本文依据的官方中文文档pkg/channels/wecom/wecom.go渠道主体连接循环、Turn/流式回复、消息分发pkg/channels/wecom/protocol.go企业微信 AI Bot WebSocket 协议命令与消息结构pkg/channels/wecom/reqid_store.go会话路由持久化存储30 分钟 TTLpkg/channels/wecom/media.go入站媒体下载与出站媒体分片上传pkg/config/config.goWeComSettings配置结构定义cmd/picoclaw/internal/auth/wecom.gopicoclaw auth wecom扫码绑定 CLI 实现如需了解 PicoClaw 其他渠道Telegram、Slack、QQ 等的接入方式可参考 渠道文档总览 与 配置指南。【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
PicoClaw 企业微信（WeCom）渠道详解：基于 WebSocket 出站连接的统一配置与流式回复实现
PicoClaw 企业微信WeCom渠道详解基于 WebSocket 出站连接的统一配置与流式回复实现【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclawPicoClaw 将企业微信整合为单一的channels.wecom渠道基于腾讯官方企业微信 AI Bot WebSocket API 实现原有的wecom、wecom_app、wecom_aibot三个独立渠道已合并为统一配置模型。本文完整覆盖该渠道的扫码绑定、手动配置、配置项与环境变量说明、运行时流式回复与媒体收发机制并结合开源仓库源码解释其连接管理、会话路由与消息去重的底层实现。读完后你可以在无需公网回调地址的设备如开发板、内网主机、容器上独立完成企业微信 AI Bot 的接入、配置与问题排查。本渠道无需公网 Webhook 回调地址。PicoClaw 主动向企业微信建立出站 WebSocket 连接因此不需要开放入站端口或配置反向代理。支持的功能单聊和群聊消息收发基于企业微信 AI Bot 协议的流式回复接收文本、语音、图片、文件、视频及混合消息发送文本及媒体消息image、file、voice、video通过 Web UI 或 CLI 扫码绑定发送者白名单和reasoning_channel_id路由从源码结构看上述能力对应pkg/channels/wecom/下的四个核心文件wecom.go连接与消息主逻辑、protocol.go协议命令与消息结构定义、media.go媒体下载/上传、reqid_store.go会话路由持久化。渠道通过 注册入口 以config.ChannelWeCom类型挂载到 PicoClaw 的渠道工厂体系。快速开始方式一Web UI 扫码绑定推荐打开 Web UI进入Channels → WeCom点击扫码绑定按钮。用企业微信扫码并在 App 内确认凭据自动保存。方式二CLI 扫码登录运行picoclaw auth wecom命令执行流程向企业微信请求二维码并在终端打印同时打印一个二维码链接终端二维码不清晰时可在浏览器中打开轮询确认状态——扫码后还需要在企业微信 App 内点击确认成功后将bot_id和secret写入channels.wecom并保存配置默认超时为5 分钟可通过--timeout延长picoclaw auth wecom --timeout 10m⚠️ 仅扫描二维码还不够——必须在企业微信 App 内点击确认否则命令会超时。从 CLI 实现cmd/picoclaw/internal/auth/wecom.go可以看到这条流程的具体参数| 常量 | 值 | 含义 | | ---- | -- | ---- | |wecomQRGenerateEndpoint|https://work.weixin.qq.com/ai/qc/generate| 请求生成二维码的接口 | |wecomQRQueryEndpoint|https://work.weixin.qq.com/ai/qc/query_result| 轮询扫码确认状态的接口 | |wecomQRPollInterval|3 * time.Second| 状态轮询间隔 | |wecomQRPollTimeout|5 * time.Minute| 默认确认等待时长即--timeout的默认值 |命令通过--timeout标志暴露等待时长命令定义确认成功后命令会加载配置、写入bot_id与secret并持久化保存与 Web UI 扫码绑定最终落到同一份channels.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: } } }构造渠道时会强制校验凭据NewChannel 在bot_id或secret为空时直接返回wecom bot_id and secret are required错误未显式指定websocket_url时自动回填默认值wss://openws.work.weixin.qq.com。配置项说明字段类型默认值说明enabledboolfalse启用企业微信渠道。bot_idstring—企业微信 AI Bot 标识符。启用时必填。secretstring—企业微信 AI Bot 密钥。加密存储于.security.yml。启用时必填。websocket_urlstringwss://openws.work.weixin.qq.com企业微信 WebSocket 端点。send_thinking_messagebooltrue在流式回复开始前发送处理中...提示消息。allow_fromarray[]发送者白名单。为空时允许所有人。reasoning_channel_idstring可选将推理/思考内容路由到指定会话 ID。对应源码中的配置结构体 WeComSettings 还包含一个streaming字段StreamingConfig用于控制是否启用流式回复通道allow_from与reasoning_channel_id则来自通用的渠道组配置WeComGroupConfig由基础渠道BaseChannel统一消费白名单过滤与推理内容路由。secret采用SecureString类型封装不在普通配置文件中明文保留而是加密写入.security.yml与 PicoClaw 的凭据加密机制一致。环境变量所有字段均可通过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这与源码中各字段的env标签BOT_ID、SECRET、WEBSOCKET_URL、SEND_THINKING_MESSAGE等相对应前缀PICOCLAW_CHANNELS_WECOM_由渠道名拼接生成适合在容器或 systemd 环境中以环境变量注入密钥而不落盘。运行时行为与源码实现连接管理与心跳渠道启动后在后台 goroutine 中运行连接循环connectLoop使用gorilla/websocket主动拨号到websocket_url连接超时15 秒wecomConnectTimeout。拨号成功后立即发送aibot_subscribe命令携带bot_id与secret完成订阅命令等待回执的超时为10 秒wecomCommandTimeout。心跳循环每30 秒wecomHeartbeatInterval发送一次ping命令心跳写失败会关闭连接。连接断开后按指数退避重连从 1 秒起步、逐次翻倍上限1 分钟。协议层面的所有命令名在 protocol.go 中集中定义aibot_subscribe订阅、ping心跳、aibot_msg_callback消息回调、aibot_event_callback事件回调、aibot_respond_msg应答/流式回复、aibot_send_msg主动推送、aibot_upload_media_init/chunk/finish分段上传媒体。所有帧共用wecomEnvelope信封结构cmdheaders.req_idbodyerrcode/errmsg发送方以req_id关联请求与回执并等待 ack。流式回复Turn 模型与降级策略运行时关键参数在 wecom.go 顶部常量区 中集中声明| 常量 | 值 | 对应行为 | | ---- | -- | -------- | |wecomStreamMaxDuration|5*time.Minute 30*time.Second| 流式回复最大持续时长5.5 分钟| |wecomStreamMinInterval|500 * time.Millisecond| 流式 chunk 最小发送间隔500ms| |wecomRouteTTL|30 * time.Minute| 会话路由30 分钟无活动后过期 | |wecomRecentMessageMax|1000| 消息去重环形缓冲区容量 | |wecomMediaTimeout|30 * time.Second| 媒体下载/上传 HTTP 超时 |具体工作方式为收到用户消息后渠道为该会话创建wecomTurn含ReqID、StreamID、创建时间并推入按会话维护的 Turn 队列SendThinkingMessage为true时会先发出 Processing... 开场 chunk见 dispatchIncoming。Agent 的流式输出通过wecomStreamer发送Update在相邻 chunk 之间强制保持500ms最小间隔UpdateFinalize以finishtrue收尾并消费该 Turn。每发一个 chunk 前都会校验 Turn 是否仍然活跃且未超过5.5 分钟validateActiveTurn超时会话将 Turn 消费掉并报错。流式不可用时无活跃 Turn、Turn 过期、配置关闭流式回复自动降级为主动推送优先从持久化的路由表取最近一次请求的chat_id/chat_type走aibot_send_msgSend。会话路由持久化30 分钟会话路由由 reqid_store.go 实现每条chat_id → (req_id, chat_type, 过期时间)的映射写入 JSON 文件默认路径为~/.picoclaw/wecom/reqid-store.json主目录不可用时退化为临时目录defaultReqIDStorePath。路由以30 分钟TTL 写入读写时都会惰性清理过期项。这意味着 PicoClaw 重启后30 分钟内的会话仍可继续以主动推送方式回复而不必依赖内存状态。媒体收发接收图片、文件、视频消息携带urlaeskey渠道先用带30 秒超时的 HTTP 客户端下载到本地媒体存储storeRemoteMedia再把本地引用mediaRefs与文本内容一起交给 AgentdispatchIncoming。混合消息mixed会逐项解析其中的text/image/file子项并分别落盘语音消息直接透传其转写文本内容。被引用的消息quote文本会在正文为空时兜底作为内容。发送媒体先经aibot_upload_media_init→aibot_upload_media_chunkbase64 分片→aibot_upload_media_finish三步上传为企业微信临时文件拿到media_id后作为image/file/voice/video媒体消息发出协议结构见 protocol.go。上传失败时降级为文本占位回复保证用户始终能收到反馈。去重所有入站消息 ID 经过recentMessageSet环形缓冲区过滤最多记录1000条消息 IDnewRecentMessageSet同一msgid的重复回调会被直接丢弃。从旧版企业微信配置迁移旧配置迁移方式channels.wecomWebhook 机器人改用channels.wecom填写bot_idsecret。channels.wecom_app删除改用channels.wecom。channels.wecom_aibot将bot_id和secret移至channels.wecom。token、encoding_aes_key、webhook_url、webhook_path已废弃从配置中删除。corp_id、corp_secret、agent_id已废弃从配置中删除。welcome_message、processing_message、max_steps已不属于企业微信渠道配置删除即可。常见问题扫码绑定超时扫码后必须在企业微信 App 内点击确认仅扫码不够。使用更长的超时重试picoclaw auth wecom --timeout 10m终端二维码不清晰时使用命令打印的二维码链接在浏览器中打开。二维码已过期二维码有效期有限重新运行picoclaw auth wecom获取新二维码。WebSocket 连接失败检查bot_id和secret是否正确。确认设备可以访问wss://openws.work.weixin.qq.com出站 WebSocket无需开放入站端口。连接失败时渠道会按 1 秒起步、上限 1 分钟的退避策略自动重连日志中会记录每次WeCom connection lost与当前 backoff 值。收不到回复检查allow_from是否屏蔽了发送者。确认channels.wecom.bot_id和channels.wecom.secret已填写且非空。若流式回复中断回复会自动降级为主动推送此时可用~/.picoclaw/wecom/reqid-store.json中是否存在该会话的路由TTL 30 分钟判断降级路径是否可用。相关文件索引文件作用docs/channels/wecom/README.zh.md本文依据的官方中文文档pkg/channels/wecom/wecom.go渠道主体连接循环、Turn/流式回复、消息分发pkg/channels/wecom/protocol.go企业微信 AI Bot WebSocket 协议命令与消息结构pkg/channels/wecom/reqid_store.go会话路由持久化存储30 分钟 TTLpkg/channels/wecom/media.go入站媒体下载与出站媒体分片上传pkg/config/config.goWeComSettings配置结构定义cmd/picoclaw/internal/auth/wecom.gopicoclaw auth wecom扫码绑定 CLI 实现如需了解 PicoClaw 其他渠道Telegram、Slack、QQ 等的接入方式可参考 渠道文档总览 与 配置指南。【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
