wecom-ai-bot 0.1.0

Enterprise WeChat (WeCom) AI Bot Framework — Python-first, AI-native

WeComBot

企业微信 AI 智能客服机器人框架
Python 原生 · AI 驱动 · 开箱即用

快速开始 · Documentation · Examples · 赞助支持

---

和微信「龙虾」(OpenClaw) 有什么区别？

微信已开放 ClawBot 插件，允许 AI Agent 接入个人微信。但 WeComBot 解决的是完全不同的场景：

	微信龙虾 (ClawBot)	WeComBot
定位	个人 AI 助手	企业客服 / 商业场景
接入方式	微信个人聊天插件	企业微信官方客服 API
群聊支持	❌ 不支持	✅ 支持
多实例	❌ 只能连 1 个龙虾	✅ 多实例 + Redis 共享
数据归属	腾讯平台	自建服务器，数据完全自有
自定义程度	受限于 OpenClaw 生态	完全自由：任意模型、任意逻辑
客户管理	❌ 无	✅ 企微客户体系打通
适合谁	个人用户玩 AI	企业做智能客服、私域运营

简单说：龙虾是给个人玩的，WeComBot 是给企业赚钱用的。

为什么选 WeComBot？

	其他方案	WeComBot
企微支持	仅 Webhook 推送，或偏重个人微信	完整客服 API（kf API）全量封装
开发语言	TypeScript 优先（Wechaty）	Python 原生 — AI/ML 开发者首选
AI 能力	需自行集成	内置：多模型路由、对话记忆、插件系统
部署难度	配置复杂	Docker 一键部署
成本	SCRM SaaS 年费 ¥10,000+	免费开源

功能对比

功能	免费版	赞助版
企微客服 API 完整封装	✅	✅
消息加解密（AES-CBC）	✅	✅
Webhook 回调服务（FastAPI）	✅	✅
消息去重	✅	✅
单模型 LLM 接入	✅	✅
本地对话记忆	✅	✅
插件系统	✅	✅
Docker 部署	✅	✅
多模型智能路由（自动降本）		✅
Redis 共享记忆（多实例）		✅
RAG 知识库插件		✅
管理后台（用量、成本、日志）		✅
预配置 Docker 镜像（开箱即用）		✅
VIP 技术群 + 优先响应		✅

🚀 快速开始

1. 安装

pip install wecombot

2. 配置

cp config.example.yaml config.yaml
# 填入你的企业微信凭证

wecom:
  corp_id: "你的企业ID"
  secret: "你的应用Secret"
  kf_account: "你的客服账号"
  token: "你的回调Token"
  encoding_aes_key: "你的EncodingAESKey"

server:
  host: "0.0.0.0"
  port: 8000

3. 运行

from wecombot import WeComBot

bot = WeComBot("config.yaml")

@bot.on_text
async def handle(bot, msg):
    await bot.reply(msg, f"收到：{msg.content}")

bot.run()

搞定。 你的企微 AI 客服已上线。

10 行代码接入 AI 助手

from wecombot import WeComBot
from wecombot.ai import AIChatHandler
from wecombot.ai.providers import AnthropicProvider
from wecombot.memory import LocalMemory

bot = WeComBot("config.yaml")
provider = AnthropicProvider(api_key="sk-ant-xxx")
memory = LocalMemory("./history")
ai = AIChatHandler(provider=provider, memory=memory,
                   system_prompt="你是一个专业的客服助手。")

@bot.on_text
async def handle(bot, msg):
    reply = await ai.handle(msg.content, msg.external_userid)
    await bot.reply(msg, reply)

bot.run()

架构设计

┌─────────────────────────────────────────────┐
│                  WeComBot                    │
├──────────┬──────────┬───────────┬───────────┤
│  Webhook │  Client  │    AI     │  插件系统  │
│  回调服务 │  API客户端│  AI引擎   │  Plugins  │
├──────────┼──────────┼───────────┼───────────┤
│ FastAPI  │  httpx   │ 多模型路由 │ BasePlugin│
│ AES-CBC  │  自动重试 │ 对话记忆   │ 欢迎消息  │
│ 消息去重  │  Token   │ 智能降级   │ 网页搜索  │
│          │  缓存刷新 │  成本追踪  │ 自定义... │
└──────────┴──────────┴───────────┴───────────┘
        ↕                   ↕
  企微客服 API        Claude / GPT / DeepSeek
                      / 任意 OpenAI 兼容接口

支持的 AI 模型

模型服务	流式输出	用量追踪	接入方式
Anthropic (Claude)	✅	✅	AnthropicProvider(api_key="sk-ant-xxx")
OpenAI (GPT)	✅	✅	OpenAIProvider(api_key="sk-xxx")
DeepSeek	✅	✅	OpenAIProvider(api_key="xxx", base_url="https://api.deepseek.com/v1")
通义千问	✅	✅	OpenAIProvider(base_url="https://dashscope.aliyuncs.com/compatible-mode/v1")
本地模型 (Ollama, vLLM)	✅	✅	OpenAIProvider(base_url="http://localhost:11434/v1")
任意 OpenAI 兼容接口	✅	✅	OpenAIProvider(base_url="你的地址")

Docker 部署

# 快速启动
docker compose -f docker/docker-compose.yml up -d

# 启用 Redis（多实例共享记忆）
docker compose -f docker/docker-compose.yml --profile redis up -d

通过 cloudflared 暴露到公网：

cloudflared tunnel --url http://localhost:8000

插件系统

几分钟创建自定义插件：

from wecombot.plugins import BasePlugin

class WeatherPlugin(BasePlugin):
    name = "weather"
    description = "查询天气"

    async def can_handle(self, message):
        return "天气" in message.content

    async def handle(self, bot, message):
        city = message.content.replace("天气", "").strip()
        # 调用天气 API
        return f"{city}天气：25°C，晴"

# 注册插件
bot.register_plugin(WeatherPlugin())

内置插件：WelcomePlugin（新用户欢迎）、WebSearchPlugin（网页搜索）

企微后台配置指引

1. 登录企业微信管理后台
2. 进入 客服 → 创建客服账号
3. 记录 corp_id、secret、kf_account
4. 在 回调配置 中设置回调 URL，获取 token 和 encoding_aes_key
5. 填入 config.yaml，运行你的 Bot

详细文档：docs/getting-started.md

文档

• Getting Started — 企微配置、安装、第一个 Bot
• AI Integration — LLM 接入、多模型路由、对话记忆
• Plugin Development — 插件开发指南
• Deployment Guide — Docker 部署、隧道、生产配置

开发计划

• 企微客服 API 完整封装
• 消息加解密（AES-CBC）
• Webhook 回调服务 + 消息去重
• 多 LLM Provider 支持（Anthropic、OpenAI、兼容接口）
• 对话记忆（本地 + Redis）
• 多模型智能路由
• 插件系统 + 内置插件
• Docker 部署方案
• RAG 知识库插件
• 管理后台（Web UI）
• 企微应用消息支持
• 群聊支持
• 语音消息转文字
• 图片理解（多模态）
• 限流与配额管理

参与贡献

欢迎贡献！请参考 Contributing Guide。

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 编写测试
4. 确保所有测试通过 (pytest)
5. 提交 PR

所有 PR 在 48 小时内响应。

💰 赞助支持

WeComBot 完全免费开源。赞助支持项目持续开发，同时解锁高级功能和专属技术服务。

🔥 早鸟特惠（限前 50 名）

🎫 ¥9.9 早鸟赞助 限前 50 名 VIP 技术群 预配置 Docker 镜像 部署指导 赞助版全部功能

💎 ¥88 赞助版 早鸟结束后价格 VIP 技术群 预配置 Docker 镜像 部署指导 赞助版全部功能

🏢 ¥288 定制版 赞助版全部权益 1 对 1 部署支持 定制化需求开发 多账号解决方案

支付后请添加开发者微信（备注「WeComBot」）获取权益：

权益对比

权益	免费版	早鸟 ¥9.9 / 赞助 ¥88	定制版 ¥288
完整框架源码	✅	✅	✅
基础文档	✅	✅	✅
VIP 技术群		✅	✅
预配置 Docker 镜像		✅	✅
多模型路由 + Redis 记忆		✅	✅
部署指导		✅	✅
RAG 知识库插件		✅	✅
管理后台		✅	✅
优先 Issue 响应		✅	✅
1 对 1 部署支持			✅
定制化需求开发			✅
多账号解决方案			✅

⚖️ 法律声明

本项目完全合法合规：

• 仅使用企业微信官方开放 API，不涉及任何逆向工程、协议破解或非授权接口
• 不使用任何微信个人号协议（如 Pad/Hook/Web 协议）
• 不包含任何绕过平台安全策略的代码
• 遵守《企业微信用户账号使用规范》和《微信外部链接内容管理规范》

⚠️ 使用微信非官方协议（如 WeChatPadPro、itchat 等）存在法律风险，包括但不限于账号封禁、民事赔偿（已有判赔 500 万案例）甚至刑事责任。本项目与此类方案无关。

License

MIT — 随便用。

---

为企微开发者社区而建
_{觉得有用？给个 ⭐ 或 赞助支持}