Skip to content
项目

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 构建和企业微信机器人核心收件的真机记录。微信客服真实账号收发、断线重连及真人独立上手仍待验证,详见验证范围。未执行的检查保持待验证状态。

WeCom Inbox

网页收件箱预览;全部为明确标注的合成测试样例,不含客户数据。

能做什么

  • 企业微信机器人与微信客服统一收件;多个客服账号各自归档,按来源和发送人明确授权。
  • 先持久记录消息,再下载附件;下载凭据临时加密保存,完成后清除。
  • 一条消息的多个附件及引用文件分别保存,核对大小和 SHA-256;处理中断可恢复。
  • 中英文网页收件箱,按内容、文件名、机器人、时间、发送人、类型和状态查找。
  • JSON/CSV 导出,附件原件下载,分页 HTTP API。
  • 多个处理程序各自订阅、重试和登记结果,互不覆盖处理状态。
  • 可选择回复原会话;明确区分“已收件”“投递已确认”“业务处理完成”“发送结果不确定”。
  • 只读导入旧 JSONL 资料,停机备份和恢复到新目录。

只保存平台实际推送给机器人的内容,不能据此读取任意个人微信、外部群或企业全量聊天。群聊需要按平台规则 @机器人。企业微信智能机器人经真机验证的限制:语音只提供转写文字、不含录音;合并聊天记录不推送内容;过期文件引用拿不到原件;单个附件上限 50 MB。详见验收记录。微信客服是另一套接口,其收件类型与限制见微信客服接入。

先选择你的使用方式

这是同一套软件的两种使用方式,不需要下载两个不同程序。 两种方式都不需要 AI 账号。

你现在的情况 使用方式 需要准备
希望用普通微信直接交资料 微信客服入口 企业微信接管的微信客服账号、授权自建应用、HTTPS 回调地址;不需要创建智能机器人
有自己能管理的企业微信智能机器人 已有机器人:直接接入 Bot ID、长连接 Secret、允许测试的成员或群聊范围
目前没有可用机器人,先体验软件 无机器人:离线体验 无需企业微信凭据;使用明确标注的样例或符合格式的历史资料
目前没有可用机器人,希望接收真实企微消息 无机器人:从零创建 能登录企业微信并创建智能机器人;没有权限时由企业管理员协助
连企业微信都还没有开通 从零开通企业微信 手机、能正常使用的微信、可接收验证码的手机号、真实企业或组织信息

旧目录里存在机器人配置,不代表当前使用者拥有或可以操作它。实际接入以使用者确认的新配置为准。

用普通微信交资料:接入微信客服

用普通微信打开客服链接 → 发文字、图片、文件或语音 → 在同一个 WeCom Inbox 里查找原件 → 按需交给 Agent 处理并回复。 这是一对一客服入口,不用 @;不能读取你其他私聊或微信群。可以只开通微信客服,不创建企业微信智能机器人。

本版接入的是由企业微信接管、通过已授权自建应用调用 API 的微信客服。独立微信客服后台使用另一套接口,不能把独立版的密钥直接填进来;如已有独立版账号,先按官方后台指引确认使用方式,再继续配置。

1. 你本人先开通客服账号

  1. 没有企业微信时,先按下方从零开通企业微信创建组织,并确认自己能进入管理后台。
  2. 进入企业微信管理后台的 应用管理 → 微信客服,按实际页面开通,并创建专用测试客服账号,例如“资料收件箱”。
  3. 按后台提示,把这个客服账号设为通过 API 管理;在“可调用接口的应用”中授权一个启用的自建应用。需要接待人员时,把相应人员加入该应用的可见范围。
  4. 记录企业 ID(CorpID)、这个已授权自建应用的 Secret。不要使用智能机器人的 Secret;新企业也不能照旧教程默认使用微信客服系统应用 Secret。
  5. 按后台要求配置服务器可信 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. 完成真实收发测试

  1. 在企业微信里打开这个机器人的单聊,发送 WeCom Inbox 测试。
  2. 再发送一张非敏感图片和一个小的 Excel、PDF 或 TXT 测试文件。
  3. 在网页收件箱里核对文字、发送人、时间和附件;下载附件并核对原件。
  4. 如需群聊接入,把机器人加入允许测试的群,再引用已发送的文件并 @机器人。
  5. 启用了回执时核对客户端回执;配置了外部处理程序时,再分别检查投递、处理结果和可选回复。

“已连接”只说明连接建立;以上收发、附件和客户端显示都通过,才算完成真实平台验收。

说明二:目前没有机器人

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. 从零创建机器人,接收真实企业微信消息

  1. 准备企业微信账号与权限。 能登录企业微信,并能创建智能机器人;还没有开通时,先按 第零步:从零开通企业微信 操作。入口或权限不可用时,请企业管理员协助。
  2. 打开创建入口。 客户端可从“工作台 → 智能机器人 → 创建 → 手动创建”进入; 管理员也可从管理后台的“安全与管理 → 管理工具 → 智能机器人”进入。
  3. 选择 API 模式。 在创建页面底部选择“API 模式创建”,连接方式选择“使用长连接”。
  4. 填写机器人信息。 名称可以用 WeCom Inbox 测试助手,可见范围先限于参与测试的人。
  5. 取得并保存凭据。 记录 Bot ID,取得 Secret 后妥善保存,再完成机器人创建。
  6. 接入本软件。 按上面的“已有机器人”说明,由部署人员配置连接和成员/群聊白名单,然后做真实收发测试。

创建入口与长连接配置依据腾讯官方说明核对:企业微信智能机器人接入指南 与管理后台创建指引。这里只使用它们的机器人创建步骤; 使用 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。