1. 项目定位与用途
OpenClaw-Wechat 是 OpenClaw AI 助手框架的企业微信渠道插件，作为框架与企业微信之间的集成桥梁。其核心用途是提供两种标准接入方式：Agent 模式（自建应用回调）适用于需要主动推送、菜单交互的场景；Bot 模式（智能机器人长连接）适用于实时对话与流式输出场景。插件通过统一的配置与诊断体系，使开发者能快速将 OpenClaw 的 AI 能力部署到企业微信环境中，实现内部问答、客服助手、知识库检索等业务功能。
项目档案插件 / 扩展
OpenClaw-Wechat 企业微信插件：双模式接入与可靠投递，一键安装使用指南
OpenClaw-Wechat 是 OpenClaw 框架的企业微信渠道插件，支持 Agent 自建应用与 Bot 长连接双模式，提供消息可靠投递、流式输出和可视化配置。本文介绍项目定位、安装步骤、使用方式及技术特性，适用于企业微信 AI 助手集成场景。
AI 总结
OpenClaw-Wechat 是 OpenClaw AI 助手框架的企业微信渠道插件，支持 Agent 自建应用与 Bot 长连接双模式接入，提供可靠投递、流式输出与可视化配置，实现企业微信场景下的 AI 助手快速集成。
中文项目介绍
OpenClaw-Wechat 是 OpenClaw 框架的企业微信官方插件，旨在解决 AI 助手与企业微信系统的无缝对接问题。
项目通过提供两种核心接入模式——Agent 模式（基于自建应用 XML 回调）与 Bot 模式（基于智能机器人 JSON 长连接）——适应不同企业微信场景需求。其核心价值在于实现消息的可靠投递机制，包括失败自动重试、持久化补发、24小时窗口感知与配额管理，确保关键通知不丢失。
该插件适用于个人微信扫码进入企业微信对话、企业内部问答助手、多账户多业务线消息分流等场景。技术特性上支持流式输出（打字机效果）、群聊策略（@触发、关键词触发）、白名单控制、动态 Agent 分配以及文档知识库能力，并配套完整的 CLI 安装工具、交互式配置向导与诊断系统，大幅降低集成与运维成本。
详细信息与使用说明
2. 解决的问题
插件主要解决四大类问题：一是接入模式碎片化，通过双模式统一覆盖自建应用与智能机器人场景；二是消息可靠性不足，引入 Pending Reply 队列、自动重试、持久化补发与 24 小时窗口感知，确保最终回复可追踪、可重试；三是配置与运维复杂，提供 CLI 安装器、交互式向导、doctor 诊断与自检命令，降低使用门槛；四是高级能力缺失，原生支持流式输出、群聊策略（触发模式、白名单）、动态 Agent 路由与文档工具，满足企业级管控与体验需求。
3. 适用场景
主要适用以下场景：个人微信扫码后进入企业微信应用对话，实现跨平台沟通；企业内部员工问答助手，提供政策、流程查询；多账户多业务线消息分流，通过动态 Agent 或白名单实现隔离；企业微信群聊 AI 助手，支持 @触发、关键词触发与直接回复；需要严格白名单控制的内部服务，如高管助手、部门专用机器人；以及需要知识库文档检索能力的场景，通过 WeCom Doc 工具实现。
4. 安装方式
仓库中明确给出三种安装路径：首选官方安装命令 `npx -y @dingxiang-me/openclaw-wecom-cli install`，该命令会自动检测环境、生成配置并完成接入；其次使用交互式向导 `npm run wecom:quickstart -- --wizard`，逐步选择模式与策略并写入 openclaw.json；第三种为环境变量初始化路径，先配置 WECOM_* 系列环境变量，再执行 `openclaw channels add --channel wecom --use-env`。无论哪种方式，均需提前准备企业微信凭证（ CorpId、AgentId、Secret 或 BotId、BotSecret）。
5. 使用方式
配置完成后，日常使用包括：运行 `npm run wecom:quickstart -- --json` 生成推荐配置；使用 `npm run wecom:doctor -- --json` 验证接入状态与可靠投递配置；用户可通过内置命令进行会话管理，如 `/help` 查看帮助、`/status` 查看会话状态（含 24h 窗口与 Pending Reply）、`/clear` 清空会话、`/reset` 重置；Bot 模式下默认支持流式输出，Agent 模式支持主动发送与菜单；通过环境变量控制白名单（WECOM_ALLOW_FROM）、群聊触发（WECOM_GROUP_CHAT_*）、动态 Agent（WECOM_DYNAMIC_AGENT_*）等高级策略。
6. 补充说明与实现特点
插件具备以下实现特点：可靠投递链路采用多层级 fallback 策略（长连接/流式/响应 URL/Webhook/Agent 推送），并区分窗口过期、额度不足、传输失败等状态；流式输出管理器支持 UTF-8 字节截断、会话键规范化与媒体指令（MEDIA:/FILE:）自动隐藏；配置支持环境变量与 openclaw.json 双源，wizard 可交互式写入；诊断体系涵盖 selfcheck、doctor、probe 与 e2e 场景测试；代码结构清晰，Agent 与 Bot 处理链模块化，API 客户端统一封装企业微信接口。仓库中未明确给出性能基准测试数据与集群部署方案。
思维导图
OpenClaw-Wechat 架构
双模式接入
Agent 模式
Bot 长连接
Webhook 出站
可靠投递
Pending Reply 队列
自动重试与持久化
24h 窗口感知
配额与状态分类
流式输出
字节截断与清理
媒体指令隐藏
会话键管理
配置与诊断
CLI 安装器
交互式向导
doctor / selfcheck
e2e 测试
企业微信 API
API 客户端封装
媒体上传下载
加密响应处理
高级策略
群聊触发策略
白名单控制
动态 Agent 路由
WeCom Doc 工具
常见问题
OpenClaw-Wechat 支持哪些企业微信接入模式？
支持两种模式：Agent 模式（自建应用 XML 回调，适合主动发送与菜单交互）和 Bot 模式（智能机器人 JSON 长连接，适合实时对话与流式输出），此外还支持 Webhook 目标出站主动投递。
如何快速安装 OpenClaw-Wechat 插件？
推荐使用官方安装命令：`npx -y @dingxiang-me/openclaw-wecom-cli install`，该命令会自动完成配置检测、文件写入与接入验证。也可使用交互式向导 `npm run wecom:quickstart -- --wizard` 或环境变量初始化路径。
什么是可靠投递机制？它解决了什么问题？
可靠投递是 v2.2.0 引入的核心能力，通过 Pending Reply 队列、自动重试、持久化选项与 24 小时窗口感知，确保最终回复不丢失。它解决了企业微信回调超时、网络抖动导致的投递失败问题，并提供状态分类（窗口过期/额度不足/传输失败）便于诊断。
Bot 模式是否支持流式输出？如何配置？
Bot 模式原生支持流式输出（stream），可通过环境变量 `WECOM_STREAMING_ENABLED=true` 启用，并调整 `WECOM_STREAMING_MIN_CHARS` 与 `WECOM_STREAMING_MIN_INTERVAL_MS` 控制触发阈值与间隔。流式输出由 stream-manager 管理，支持文本截断与媒体指令隐藏。
如何控制群聊触发与私聊白名单？
通过环境变量配置：`WECOM_GROUP_CHAT_ENABLED` 开关群聊，`WECOM_GROUP_CHAT_TRIGGER_MODE` 设置触发模式（direct/mention），`WECOM_GROUP_CHAT_REQUIRE_MENTION` 控制是否必须 @机器人；私聊白名单通过 `WECOM_ALLOW_FROM` 设置用户列表，未授权用户将收到 `WECOM_ALLOW_FROM_REJECT_MESSAGE` 提示。这些策略可在 `/status` 与 selfcheck 中查看生效状态。