WeChat-AI

自托管微信角色扮演对话服务 · Self-hosted WeChat roleplay chatbot service

直连腾讯 iLink，数据存 远端 Redis，登录用 LINUX DO OAuth。 Connects directly to Tencent iLink, stores data in remote Redis, and authenticates via LINUX DO OAuth.

功能 Features · 架构 Architecture · 快速开始 Quick Start · 文档 Docs · 许可证 License

---

功能 Features

中文	English
LINUX DO OAuth 登录（用户 / 管理员）	LINUX DO OAuth login (user / admin)
用户中心：扫码添加/删除微信机器人、批准私聊用户、分配人设	User center: scan-QR add/remove WeChat bots, approve chat peers, assign personas
用户对话：绑定 LINUX DO 后微信内 @用户名 请求对话，对方 /同意 后双向中继	P2P chat: after binding, @username in WeChat to request a chat, peer replies /agree to relay messages both ways
管理后台：数据面板、Token 用量、用户与机器人、部署节点、表情包审核	Admin dashboard: stats, token usage, users & bots, deploy nodes, sticker moderation
表情包广场：投稿 / 我的库 / 公开需审核；恶意图过滤	Sticker square: submit / my library / public needs review; malicious-image filtering
回复文字与图片表情（主人表情库 → 模型引用 slug → iLink CDN 发图）	Text + image sticker replies (owner sticker library → model references slug → sent via iLink CDN)
输入状态指示（getconfig + sendtyping，回复送达即消失）	Typing indicator (getconfig + sendtyping, disappears when reply is delivered)
入站图片理解（VISION_ENABLED，默认关闭；caption 模式人设模型无需视觉）	Inbound image understanding (VISION_ENABLED, off by default; caption mode needs no vision-capable roleplay model)
入站语音转写（微信自带转写，默认开启）	Inbound voice transcription (WeChat built-in STT, on by default)
远端 Redis 存储（bot token 与表情包均在 Redis）	Remote Redis storage (bot tokens & stickers in Redis)
OpenAI 兼容 LLM + 按日 Token 统计	OpenAI-compatible LLM + daily token stats
用户自定义模型 + 联网搜索（经 HF 工具网关出站，主站不直连用户 API）	User custom models + web search (egress only via HF tools gateway)
Chatflow：可视化编排（/chatflow），人设可选 prompt / chatflow 模式	Chatflow: visual orchestration (/chatflow), personas support prompt / chatflow mode
多节点同构部署 + Cloudflare Worker 负载均衡	Multi-node homogeneous deployment + Cloudflare Worker LB
OTA 增量更新（文件差量 + 自动重启）	OTA incremental updates (file diff + auto restart)

架构 Architecture

微信用户 ──► 腾讯 iLink ──► 本系统多节点 (收消息 / 人设+记忆 / LLM / 回消息)
WeChat user ──► Tencent iLink ──► multi-node system (receive / persona+memory / LLM / reply)

浏览器 ──► 主域名 CF Worker LB ──► Node-1…N (同一镜像, 共享 Redis)
Browser ──► main domain CF Worker LB ──► Node-1…N (same image, shared Redis)

快速开始 Quick Start

本地开发 Local Development

pnpm install
cp .env.example .env
# 必填 Required: REDIS_URL（Upstash 用 rediss://）、LLM_API_KEY（平台）、LINUXDO_* 、LINUXDO_ADMIN_IDS
# 用户自定义 LLM / 联网搜索：部署 huggingface/wechat-ai-tools，配置 TOOLS_BASE_URL + TOOLS_API_KEY

pnpm db:seed
pnpm diag
pnpm dev

页面 / Pages：

路径 Path	说明 Description
/	功能落地页 + OG 分享图 Landing page
/app	用户中心 User center (LINUX DO login)
/docs	使用文档 Documentation
/admin	管理后台 Admin dashboard
/chatflow	Chatflow 编辑器 Chatflow editor

Docker 一键部署 One-Click Deploy

# 配置好 .env 后 After configuring .env
docker compose up -d --build

详见 / See docs/docker.md。

多节点 Multi-Node

每台服务器运行同一镜像，共享同一个 Upstash Redis，用户只访问主域名。Cloudflare Worker 负责健康检查与轮询分流，源站地址只写在 Worker 的 ORIGINS 中。详见 / See cloudflare-worker/README.md。

Each server runs the same image, shares one Upstash Redis; users only visit the main domain. A Cloudflare Worker handles health checks and round-robin, origin addresses live only in the Worker's ORIGINS.

文档 Docs

文档 Doc	内容 Content
docs/upstash-redis.md	Upstash Redis 配置 Redis setup
docs/oauth-linuxdo.md	LINUX DO OAuth 配置
docs/docker.md	Docker / 多节点部署 Multi-node deploy
docs/cloudflare.md	Cloudflare 缓存 Cache
cloudflare-worker/README.md	CF Worker 多源站 LB
docs/ai-gateway.md	AI 网关（主站 ↔ HF）AI gateway
docs/chatflow.md	Chatflow 编排
docs/admin-api.md	管理 API
docs/runbook.md	运维手册 Ops runbook
docs/e2e-checklist.md	真机验收清单 E2E checklist

仓库结构 Repository Structure

apps/api           # REST + iLink worker + Admin/App/Chatflow UI (public/*.html)
packages/ilink     # iLink HTTP 客户端 iLink HTTP client
packages/db        # Redis 仓储 / seed / 人设与模型连接 Redis repos / seed
packages/llm       # OpenAI 兼容 chat + tools 网关客户端
packages/core      # 会话、人设、记忆、路由、chatflow 引擎
huggingface/       # wechat-ai-tools：唯一外网 AI/搜索出口（可独立部署）
cloudflare-worker  # 主域名负载均衡 Cloudflare Worker LB
docs/              # runbook、E2E 清单、ADR
scripts/           # 构建 / 打包 / 验收脚本 build / pack / accept scripts

验收 Acceptance

pnpm accept          # 离线自动化门禁 offline automated gate

真机清单 / Real-device checklist：docs/e2e-checklist.md · 状态 / Status：docs/ACCEPTANCE.md

合规与风险 Compliance & Risk

• 使用腾讯 微信 ClawBot / iLink 能力，须遵守相关使用条款。 Using Tencent WeChat ClawBot / iLink capabilities requires compliance with the applicable terms.
• 个人 Bot 存在限流与处置风险；默认 白名单用户 才可对话。 Personal bots face rate-limit and takedown risks; by default only approved users can chat.
• 角色扮演内容会经 LLM API 出机；请自行评估隐私。 Roleplay content leaves the machine via LLM APIs; assess your own privacy posture.
• iLink 协议以实测为准，字段可能变更；适配层见 packages/ilink。 The iLink protocol is based on observed behavior and may change; the adapter lives in packages/ilink.

许可证 License

Apache-2.0 with Commons Clause

禁止商用与转卖：仅允许个人/非商业使用；不得以任何形式收取费用、提供付费托管/咨询服务，或将本代码用于商业产品转售。详见 LICENSE。

No commercial use / no resale: personal & non-commercial use only. You may not charge fees, offer paid hosting/support, or resell the code in commercial products. See LICENSE.