iCookCloud/wecom-inbox
iCookCloud/wecom-inbox has 66 GitHub stars and 0 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 17:25 UTC. Last push 2026-10-24.
实测星标增长
- 24小时
- 0
- 7天
- 更新延迟
- 15天
- 更新延迟
- 1个月
- 更新延迟
各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。
关于
Self-hosted inbox for WeCom bots and WeChat customer service: durable files, searchable records, and independent Agent integrations.
自托管README.zh-CN.md
原文WeCom Inbox
先留存原件,再选择处理方式。
一个可独立运行的企业微信业务收件箱:保存企业微信机器人及微信客服实际收到的消息和附件,查找来源、下载原件、导出资料,再交给普通程序、知识库或 Agent 处理。不需要 AI 账号,也不依赖某一种 Agent 框架。
English · 接口说明 · 部署与恢复 · 实施及验证状态
v0.1.0:首个公开开源版本。 本项目由社区独立维护,不属于腾讯官方产品。已有自动化回归、Linux/macOS 构建和企业微信机器人核心收件的真机记录。微信客服真实账号收发、断线重连及真人独立上手仍待验证,详见验证范围。未执行的检查保持待验证状态。

网页收件箱预览;全部为明确标注的合成测试样例,不含客户数据。
能做什么
- 企业微信机器人与微信客服统一收件;多个客服账号各自归档,按来源和发送人明确授权。
- 先持久记录消息,再下载附件;下载凭据临时加密保存,完成后清除。
- 一条消息的多个附件及引用文件分别保存,核对大小和 SHA-256;处理中断可恢复。
- 中英文网页收件箱,按内容、文件名、机器人、时间、发送人、类型和状态查找。
- JSON/CSV 导出,附件原件下载,分页 HTTP API。
- 多个处理程序各自订阅、重试和登记结果,互不覆盖处理状态。
- 可选择回复原会话;明确区分“已收件”“投递已确认”“业务处理完成”“发送结果不确定”。
- 只读导入旧 JSONL 资料,停机备份和恢复到新目录。
只保存平台实际推送给机器人的内容,不能据此读取任意个人微信、外部群或企业全量聊天。群聊需要按平台规则 @机器人。企业微信智能机器人经真机验证的限制:语音只提供转写文字、不含录音;合并聊天记录不推送内容;过期文件引用拿不到原件;单个附件上限 50 MB。详见验收记录。微信客服是另一套接口,其收件类型与限制见微信客服接入。
先选择你的使用方式
这是同一套软件的两种使用方式,不需要下载两个不同程序。 两种方式都不需要 AI 账号。
| 你现在的情况 | 使用方式 | 需要准备 |
|---|---|---|
| 希望用普通微信直接交资料 | 微信客服入口 | 企业微信接管的微信客服账号、授权自建应用、HTTPS 回调地址;不需要创建智能机器人 |
| 有自己能管理的企业微信智能机器人 | 已有机器人:直接接入 | Bot ID、长连接 Secret、允许测试的成员或群聊范围 |
| 目前没有可用机器人,先体验软件 | 无机器人:离线体验 | 无需企业微信凭据;使用明确标注的样例或符合格式的历史资料 |
| 目前没有可用机器人,希望接收真实企微消息 | 无机器人:从零创建 | 能登录企业微信并创建智能机器人;没有权限时由企业管理员协助 |
| 连企业微信都还没有开通 | 从零开通企业微信 | 手机、能正常使用的微信、可接收验证码的手机号、真实企业或组织信息 |
旧目录里存在机器人配置,不代表当前使用者拥有或可以操作它。实际接入以使用者确认的新配置为准。
用普通微信交资料:接入微信客服
用普通微信打开客服链接 → 发文字、图片、文件或语音 → 在同一个 WeCom Inbox 里查找原件 → 按需交给 Agent 处理并回复。 这是一对一客服入口,不用 @;不能读取你其他私聊或微信群。可以只开通微信客服,不创建企业微信智能机器人。
本版接入的是由企业微信接管、通过已授权自建应用调用 API 的微信客服。独立微信客服后台使用另一套接口,不能把独立版的密钥直接填进来;如已有独立版账号,先按官方后台指引确认使用方式,再继续配置。
1. 你本人先开通客服账号
- 没有企业微信时,先按下方从零开通企业微信创建组织,并确认自己能进入管理后台。
- 进入企业微信管理后台的 应用管理 → 微信客服,按实际页面开通,并创建专用测试客服账号,例如“资料收件箱”。
- 按后台提示,把这个客服账号设为通过 API 管理;在“可调用接口的应用”中授权一个启用的自建应用。需要接待人员时,把相应人员加入该应用的可见范围。
- 记录企业 ID(CorpID)、这个已授权自建应用的 Secret。不要使用智能机器人的 Secret;新企业也不能照旧教程默认使用微信客服系统应用 Secret。
- 按后台要求配置服务器可信 IP、域名和应用可见范围。账号主体、地区或认证状态可能影响可开通能力,以你的后台提示为准。
以上涉及企业账号、扫码与授权,需要账号管理员本人操作。密钥仅放进服务器私有配置,不发到公开聊天、Issue 或仓库。 官方依据:微信客服概述、读取消息及权限要求。
2. 部署人员取得客服账号 ID
先按下方安装步骤构建并初始化软件。在私有 config.toml 追加连接信息,暂时保持停用:
[[wechat_kf]]
id = "customer-service"
enabled = false
corp_id = "你的企业ID"
secret = "已授权自建应用的Secret"
token = "自行生成的3至32位英文字母或数字"
encoding_aes_key = "后台生成的43位EncodingAESKey"
在服务器执行:
./wecom-inbox kf-accounts -c /私有路径/config.toml --connection customer-service
命令通过官方接口列出账号名称与 open_kfid,不输出 Secret 或 access_token。选中测试账号后,在同一配置内追加:
[[wechat_kf.accounts]]
open_kfid = "刚取得的客服账号ID"
name = "微信资料收件箱"
receipt = false
allowed_customers = ["*"]
["*"] 明确允许所有联系这个客服账号的人向收件箱交资料;只做内部试用时,可改成已知测试客户的 external_userid 列表。修改后撤销的客户不会继续触发新的收件或回复;尚未下载的附件也会停止获取。已保存的历史记录按收件来源权限管理,不会被删除。
3. 配置可访问的 HTTPS 回调
把该连接的 enabled 改成 true,运行配置检查并启动服务:
./wecom-inbox check -c /私有路径/config.toml
./wecom-inbox serve -c /私有路径/config.toml
部署人员给服务配置 HTTPS 反向代理,然后在微信客服对应的 API 接收消息/事件配置中填写:
| 后台字段 | 填什么 |
|---|---|
| URL | https://你的回调域名/callbacks/wechat-kf/customer-service |
| Token | 与私有配置的 token 完全一致 |
| EncodingAESKey | 与私有配置的 encoding_aes_key 完全一致 |
最后由管理员保存,后台会验证回调 URL。不要把管理员访问令牌放进回调地址。无需把整个管理界面开放到公网;可以只代理回调路径,网页仍在受保护的内网或本机访问。部署示例
收到通知后,软件先保存通知,再异步拉取消息。每个客服账号独立保存游标,并周期性补拉,以降低漏掉回调的影响。第一次启用可能拉到该账号最近三天的消息,建议使用专用测试账号;停机超过平台保留期,不能保证补齐历史。
4. 取得普通微信的使用入口
可在官方后台复制这个客服账号的接入链接。也可执行:
./wecom-inbox kf-link -c /私有路径/config.toml \
--bot 'kf:你的企业ID:你的客服账号ID'
命令返回官方客服链接。在普通微信中打开该链接,进入客服会话,直接发送测试文字、图片、PDF 或语音,不用加机器人好友、不用 @。 在网页“连接与处理程序”中会显示类型“微信客服”,消息按这个客服来源归档。
“等待新消息”表示最近一次 API 拉取成功,不等于回调已通过公网验证,也不等于真实用户已经收发成功。
5. 需要回复或连接 Agent 时
只存资料无需配置 AI。需要处理程序读取资料时,沿用现有 API/Webhook,把消费者的 bots 范围填成:
bots = ["kf:你的企业ID:你的客服账号ID"]
allow_reply = true
也可在网页的资料详情中登记处理结果,勾选“同时回复原会话”。微信客服文本回复最多 2048 字节,超限会被拒绝,避免被平台静默截断。
- 官方要求客户主动发消息后 48 小时内最多回复 5 条,并受会话接待状态限制;客户继续发消息后,按平台规则重新取得回复机会。
receipt = false默认不逐条发归档回执,给实际业务回复保留额度。设为true后,“已归档”回执也占平台的回复额度。- 接口返回成功显示 “平台已受理”,不当作最终送达。如果随后收到平台发送失败事件,会更新为失败;断网导致结果不明时不自动重复发送。
- 不会主动把人工接待中的会话切走。人工接待人员的消息可以留档,但不会自动触发 Agent、归档回执或再次回复,避免循环。
官方依据:发送消息限制与失败事件。
6. 当前能力与验收清单
| 内容 | 当前处理方式 |
|---|---|
| 文字、图片、文件、语音、视频 | 保存消息,下载平台提供的原文件并校验;语音这里可取得录音,和智能机器人不同 |
| 合并聊天记录 | 展开平台提供的记录及附件,保留发送者与时间;有层数、条数及附件数量限制 |
| 链接、位置、小程序等结构化卡片 | 保存平台返回的字段;不自动访问卡片中的网页,也不承诺下载卡片缩略图 |
| 平台不提供详情或尚不支持的类型 | 显示归档失败并保留加密原始事件,不能伪报已完整保存 |
| 图片/语音、视频、文件上限 | 官方客服读取接口分别列出 2 MB、10 MB、20 MB;超限可能只返回文字提示,软件不能从提示恢复原件 |
| 真实普通微信收发 | 尚待账号联调验收;已完成加密回调、去重、断点续拉、附件和回复状态的自动化测试 |
真实验收时依次发送文字、图片、PDF、语音与合并聊天记录;逐个核对网页记录和下载原件,再登记一次回复并在普通微信里确认显示。重复通知、重启恢复和失败提示也需核对。
第零步:从零开通企业微信
企业微信(WeCom)是腾讯的客户端;WeCom Inbox 是本项目的收件工具。这一步先创建企业微信里的企业/组织账号,再创建给收件工具使用的机器人。 推荐用电脑打开官网,手机配合安装、扫码和身份验证。 不需要先懂服务器、编程或 AI。
1. 准备好这些东西
- 自己能够操作的手机,以及可正常登录的微信。
- 能接收验证码的常用手机号;如果页面提供国家/地区选项,按真实区号选择。
- 真实企业或组织的名称、行业和人员规模。
- 注册页面后续要求的管理员资料或身份验证,由本人按实际提示完成。
手机号地区、主体类型和账号状态可能影响后续验证。下面给出能核对的入口,不承诺所有地区或账号都会出现完全相同的验证页面。
2. 打开官方网站,安装企业微信
电脑打开 企业微信官网,网址认准 work.weixin.qq.com。
海外或英文环境可能显示 WeCom,是这里同一产品的名称。
- 手机上从官网的 下载 / Download 入口选择 iOS 或 Android,按页面指引安装。
- 电脑端可按自己的 Windows 或 macOS 系统下载安装。
- 安装后先保留手机端,后面的扫码或验证按页面要求使用微信或企业微信完成。
3. 进入注册页面,填写企业信息
在官网选择 立即注册 / Register Now。也可打开官方注册页。 本次查看的空白注册页首先展示以下三项:
| 页面字段 | 英文显示 | 怎么填写 |
|---|---|---|
| 企业 / 组织名称 | Company Name | 填写你实际使用的企业或组织名称;后续如要求核验主体,再按真实证件信息核对 |
| 行业类型 | Industry Type | 选择与你的实际业务最接近的类别 |
| 人员规模 | Company Size | 按实际人数选择对应档位 |

截图来自官方公开注册页,未填写身份资料、未提交注册;页面语言、布局及后续验证可能随账号和版本变化。
4. 按页面提示完成本人验证和注册
阅读页面协议,确认同意后由本人提交注册。如果随后要求管理员姓名、手机号、短信验证码或微信扫码, 填写真实信息,并使用你本人长期控制的微信或企业微信完成对应验证。验证码只填在官方页面。
如果要求实名认证、企业主体资料或认证费用,先查看该步骤的具体用途和要求;不要把网上其他账号的流程直接套用到自己的账号。 目前未核实所有地区和主体的认证条件,因此不把“完全免认证”或“全程必需付费”写成统一要求。
注册页还有“个人组建团队”入口;本指引未验证这种类型能否在你的账号中使用所需的智能机器人 API, 不能把创建个人团队成功直接当作机器人能力已经开通。用于实际业务时,按真实主体选择入口。
5. 确认企业微信已经开通
在手机企业微信中登录,并确认能看到刚创建的企业/组织名称。 再从官网 企业登录 / Login 进入管理后台,按页面提示扫码,确认登录的是同一个企业。
本项目需要能够创建或管理智能机器人的权限。如果仅有普通成员权限,需由该企业的管理员代建或授权。 做到这里,你只需要确认 企业已经创建、自己能进入正确的企业、能找到创建机器人的入口。
6. 接着创建测试机器人
开通企业微信后,继续下面的从零创建机器人:选择 API 模式、使用长连接,
名称可用 WeCom Inbox 测试助手,可见范围先限于测试人员。取得 Bot ID 和 Secret 后,由部署人员接入收件箱。
遇到问题时怎么继续
| 卡住的位置 | 下一步 |
|---|---|
| 手机号不可选、收不到验证码 | 核对真实区号和页面支持的地区,记录具体错误提示;不要把验证码发给部署人员 |
| 只看到“加入企业” | 回到官网注册入口,区分创建自己的组织与加入已有组织;不要加入来源不明的邀请 |
| 只看到个人团队入口 | 先确认该类型是否具备所需管理后台和智能机器人权限,不默认与企业主体等价 |
| 找不到智能机器人 | 按腾讯官方说明检查客户端版本,并核对当前企业及权限;管理员可查看管理后台入口 |
| 出现实名、主体认证或付费要求 | 保留提示文字和当前步骤,再核对是否是使用目标功能所必需 |
企业微信内的账号验证需要本人完成;软件部署、配置检查、收件与附件核对由部署人员处理。 上述创建机器人入口另参考腾讯官方指南。
安装程序(所有收件方式共用)
推荐:下载安装包,不用安装 Go
打开 v0.1.0 下载页,按运行软件的电脑或服务器选择:
| 运行环境 | 下载文件 |
|---|---|
| Linux x86-64 / amd64 服务器 | wecom-inbox-linux-amd64 |
| Linux ARM64 服务器 | wecom-inbox-linux-arm64 |
| Apple Silicon(M 系列)Mac | wecom-inbox-darwin-arm64 |
同时下载 SHA256SUMS 校验文件,核对下载文件的 SHA-256。把程序放在单独目录中,再在这个目录启动。下面以 Linux x64 为例;Mac 或 ARM 服务器请将文件名替换成自己下载的那个:
chmod +x ./wecom-inbox-linux-amd64
./wecom-inbox-linux-amd64 init
./wecom-inbox-linux-amd64 check
./wecom-inbox-linux-amd64 serve
浏览器打开 http://127.0.0.1:8787,用新生成的私有 config.toml 里的 admin_token 登录。初始化不会覆盖已有配置,初始页面是空收件箱,不会自动连接任何账号。
接着选择 普通微信使用微信客服、已有企业微信机器人 或 无账号离线体验。服务器常驻运行、HTTPS、备份恢复和可选安装器见部署说明。本版不提供 Windows 和 Intel Mac 安装包。
开发者:从源码构建
需要 Go 1.26.4 或更新版本:
git clone https://github.com/iCookCloud/wecom-inbox.git
cd wecom-inbox
make build
./wecom-inbox init
./wecom-inbox serve
文档其余示例使用源码构建后的名称 wecom-inbox。直接下载程序的使用者,把命令中的程序名替换成下载文件名即可;无需重复构建。离线样例位于源码仓库的 tests/fixtures/legacy/。
说明一:已有机器人,直接接入
1. 确认机器人类型和归属
打开你能管理的机器人详情,确认它是 API 模式的智能机器人,并选择 使用长连接。 需要能取得该机器人的 Bot ID 和 Secret。仅有群消息推送 Webhook 地址,不能直接填入本软件的长连接配置。
如果机器人正在连接其他网关,先安排好切换,或给 WeCom Inbox 单独创建一个测试机器人。 一个 Bot 不应同时交给两套网关连接;旧配置的本地备注也不一定等于企业微信里的显示名称。
2. 准备接入信息
| 信息 | 用途 | 由谁处理 |
|---|---|---|
| 企业微信里的机器人名称 | 方便找到真实聊天入口 | 使用者确认 |
| Bot ID | 标识要连接的机器人 | 使用者或企业管理员取得,部署人员配置 |
| Secret | 验证连接身份 | 写入服务器私有配置,不放进公开仓库、说明或截图 |
| 允许测试的成员 / 群聊 | 限定谁可以向收件箱交资料 | 使用者确定范围,部署人员核对平台 ID 并加入白名单 |
部署人员参照 config.example.toml,把以上信息加入私有 config.toml,设置 enabled = true;
需要收件回执时设置 receipt = true。保留初始化生成的随机管理员令牌,检查配置后启动服务。
有效配置会自动加载,随后在“连接与处理程序”里确认机器人状态为“已连接”。
3. 完成真实收发测试
- 在企业微信里打开这个机器人的单聊,发送
WeCom Inbox 测试。 - 再发送一张非敏感图片和一个小的 Excel、PDF 或 TXT 测试文件。
- 在网页收件箱里核对文字、发送人、时间和附件;下载附件并核对原件。
- 如需群聊接入,把机器人加入允许测试的群,再引用已发送的文件并 @机器人。
- 启用了回执时核对客户端回执;配置了外部处理程序时,再分别检查投递、处理结果和可选回复。
“已连接”只说明连接建立;以上收发、附件和客户端显示都通过,才算完成真实平台验收。
说明二:目前没有机器人
A. 先体验软件,不创建机器人
可以先使用空收件箱,或在独立资料目录中导入样例/符合格式的历史 JSONL。此时不需要 Bot ID、Secret,也不需要 AI 账号。
| 功能 | 无机器人时能否使用 |
|---|---|
| 打开网页收件箱 | 可以 |
| 查询、筛选、下载和导出已导入的资料 | 可以 |
| 通过 HTTP API 读取资料、登记处理结果 | 可以,仍需访问令牌 |
| 自动接收企业微信的新消息、图片和文件 | 不可以,需先创建并连接机器人 |
| 回复到企业微信会话 | 不可以 |
| 网页拖拽上传任意文件 | 当前版本未实现;离线导入入口是命令行 JSONL 导入 |
源码目录中可按以下步骤体验,数据放在源码目录外,避免混入现有收件箱或提交到 Git:
mkdir -p ../wecom-inbox-demo
./wecom-inbox init -c ../wecom-inbox-demo/config.toml
./wecom-inbox import -c ../wecom-inbox-demo/config.toml \
--file tests/fixtures/legacy/messages.jsonl \
--media-root tests/fixtures/legacy
样例均为合成测试数据,预期导入 4 条记录、其中 1 个附件故意缺失。导入命令会显示失败记录并返回退出码 1, 这不是企业微信连接故障。查看结果后,再单独运行:
./wecom-inbox serve -c ../wecom-inbox-demo/config.toml
打开 http://127.0.0.1:8787,使用这份演示配置里的 admin_token 登录。若已有服务占用此地址,
先把演示配置的 listen 改成另一个本机端口。离线导入不会自动触发 Webhook 或发送企微回复;
这套体验也不能替代真实平台验收。
B. 从零创建机器人,接收真实企业微信消息
- 准备企业微信账号与权限。 能登录企业微信,并能创建智能机器人;还没有开通时,先按 第零步:从零开通企业微信 操作。入口或权限不可用时,请企业管理员协助。
- 打开创建入口。 客户端可从“工作台 → 智能机器人 → 创建 → 手动创建”进入; 管理员也可从管理后台的“安全与管理 → 管理工具 → 智能机器人”进入。
- 选择 API 模式。 在创建页面底部选择“API 模式创建”,连接方式选择“使用长连接”。
- 填写机器人信息。 名称可以用
WeCom Inbox 测试助手,可见范围先限于参与测试的人。 - 取得并保存凭据。 记录 Bot ID,取得 Secret 后妥善保存,再完成机器人创建。
- 接入本软件。 按上面的“已有机器人”说明,由部署人员配置连接和成员/群聊白名单,然后做真实收发测试。
创建入口与长连接配置依据腾讯官方说明核对:企业微信智能机器人接入指南 与管理后台创建指引。这里只使用它们的机器人创建步骤; 使用 WeCom Inbox 不需要安装 CodeBuddy、OpenClaw 或购买它们的服务。
谁需要做什么
- 使用者 / 企业管理员:登录企业微信、创建或确认可用机器人、确定可见范围和测试成员、发送测试资料并查看客户端回复。
- 部署人员:安装 WeCom Inbox、把凭据放入私有配置、设置白名单、检查后台收件与文件完整性、配置需要的外部处理程序。
- GitHub 操作:与机器人创建分开。没有机器人也能查看代码和体验软件;真实收件验收尚未通过时,不宣称企微接入已经验收完成。
与现有系统互补
独立处理程序通过 HTTP API 或签名 Webhook 获取资料,通过结果接口登记处理情况。不同程序有不同令牌、Bot 范围和回复权限;不需要获得机器人 Secret。
仓库中的 Python 示例使用标准库验证附件哈希并登记结果,不调用模型。自研 Agent 可基于同一接口增加适配;本版不声称已经兼容尚未联调的专有协议。
数据与运维
data/ 保存数据库、原附件、恢复清单和临时下载凭据的加密密钥。附件和完成的消息不是静态加密资料,应保护主机磁盘和备份。默认只监听本机;远程访问应使用 HTTPS 反向代理并设置 public_url。
备份、导入等离线维护需要先停止服务。旧网关数据以只读方式导入,不自动搬移或删除原件;旧 Bot 管理命令仍由原工具维护。详细命令、限制和错误恢复见 部署说明。
许可证
MIT。保留代码来源和第三方许可声明,参见 LICENSE 与 THIRD_PARTY_NOTICES.md。