WeChat-AI: a self-hosted roleplay bot that connects to Tencent iLink

What WeChat-AI actually is, and who it is built for

WeChat-AI is a self-hosted service that gives a personal WeChat account a persona, memory and an LLM behind it. The README describes it as a self-hosted WeChat roleplay chatbot service, and the repository is a pnpm workspace with five packages: apps/api, packages/ilink, packages/db, packages/llm and packages/core. The audience is narrow. You need a server, a remote Redis instance, a LINUX DO account for OAuth, and an OpenAI-compatible model endpoint. In exchange you get a bot that lives inside WeChat rather than in a separate chat app, which is the whole point: the people talking to it never install anything.

The feature list is longer than a toy project's. There is a user centre where you scan a QR code to attach or remove a WeChat bot, approve private-chat peers and assign personas. There is a peer-to-peer mode where a bound user types @username inside WeChat to request a conversation and the other side replies /agree, after which messages relay both ways. There is an admin dashboard with token usage, deploy nodes and sticker moderation, and a sticker square where submissions go public only after review. None of this is unusual on its own. What is unusual is that all of it is wired to WeChat through iLink rather than through a documented official bot API.

The iLink adapter is the risky half of the architecture

The data flow in the README is one line: WeChat user to Tencent iLink to a multi-node system that receives, applies persona and memory, calls an LLM, and replies. On the browser side, the main domain sits behind a Cloudflare Worker load balancer that forwards to Node-1 through Node-N, all running the same image and sharing one Redis. Origin addresses live only in the Worker's ORIGINS list, which is a sensible choice: nodes are never exposed directly.

The part worth pausing on is packages/ilink. The compliance section states plainly that the iLink protocol is based on observed behaviour and may change, and that the adapter lives in that package. That is an honest admission and also the largest operational risk in the project. Everything above the adapter, personas, memory, Chatflow, stickers, is ordinary application code you can reason about. The adapter is a moving target. If Tencent changes a field, the failure will show up as a bot that stops replying, not as a type error, because the shape of the response is not under your control. The README also notes that personal bots face rate-limit and takedown risks, and that only approved users can chat by default. Treat the whitelist as a requirement, not a setting.

Storage is remote Redis, and the README says bot tokens and stickers both live there. The .env.example shows an Upstash example with a rediss:// URL and a note that concurrent commands are merged into one round trip, with REDIS_AUTO_PIPELINE=true enabled by default because the Redis is remote. That default is correct for the deployment the project targets and wrong for a local Redis, where the extra batching buys nothing. There is also an L1 cache layer over Redis with per-key TTLs such as REDIS_L1_SESSION_MS and REDIS_L1_SQUARE_MS, and the comments are explicit that a new sticker or persona published on another node can take up to that TTL to appear in the square. Ten seconds is fine. Sixty seconds for the default persona is the kind of delay that makes you think your edit did not save.

Installing WeChat-AI locally and getting a first reply

The local path is a pnpm workspace, so Node 20 or newer and pnpm are the prerequisites. The README gives these steps, and the comment next to them names the variables you cannot skip: REDIS_URL, LLM_API_KEY, the LINUXDO_* values, and LINUXDO_ADMIN_IDS. Note that the Upstash form of REDIS_URL uses rediss://, not redis://.

pnpm install
cp .env.example .env
# Required: REDIS_URL (rediss:// for Upstash), LLM_API_KEY, LINUXDO_*, LINUXDO_ADMIN_IDS
pnpm db:seed
pnpm diag
pnpm dev

pnpm db:seed runs the seed script in packages/db, and pnpm diag runs the diagnostic in apps/api. Run diag before dev: it is the cheapest way to find a variable you left as the placeholder value, and the .env.example ships several placeholders, including a REDIS_URL pointing at YOUR_ENDPOINT.upstash.io and a WECHAT_AI_TOKEN set to change-me-long-random. The dev server then serves the pages listed in the README: / for the landing page, /app for the user centre behind LINUX DO login, /docs, /admin and /chatflow. Your first real action is signing in at /app and scanning a QR code to attach a bot, because nothing replies until a bot is attached and a peer is approved.

For a container instead of a local process, the compose file documents a wrapper rather than a bare compose call:

pnpm docker:up

The comment in docker-compose.yml is unusually direct about why: a plain docker compose up -d --build will not bump the version and will not pack, whereas pnpm docker:up bumps, runs the local OTA pack and then brings the stack up. The container forces WECHAT_AI_HOST to 0.0.0.0 and listens on 8787, exposed as ${WECHAT_AI_PORT:-8787}:8787. If you want the separate tools gateway for user-supplied models and web search, the compose file gives it its own profile, and the main site points at it with TOOLS_BASE_URL and TOOLS_API_KEY:

docker compose --profile tools up -d --build

The README's stated reason for that split is that egress for user custom models and web search goes only through the HF tools gateway, so the main site never calls a user's API directly. That is a deliberate boundary, and it means the tools service is not optional if you plan to let users bring their own model.

Where WeChat-AI is the wrong tool

The licence is the first disqualifier. The repository is Apache-2.0 with Commons Clause, and the README spells out the consequence in both languages: personal and non-commercial use only, no charging fees, no paid hosting or support, no reselling the code in a commercial product. If your plan involves billing anyone for access to this bot, or running it as a feature of something you sell, the licence is not a formality you can work around. That is a product decision, not a legal opinion, and if the boundary matters to you, read LICENSE rather than this article.

The second disqualifier is scale and support expectations. The multi-node setup assumes one shared Upstash Redis and a Cloudflare Worker doing health checks and round-robin, with each machine running the same image and a unique WORKER_ID. The compose file notes that it defaults to a single replica and that multi-machine deployment means running the image per server yourself. There is no documented autoscaling story, no queue, and no isolation between users beyond the approved-peer whitelist. If you need per-tenant data separation, this is not that system.

The third is the reason people usually look for a WeChat bot in the first place: a stable, documented messaging API. WeChat-AI does not provide one. It rides on iLink and WeChat's own ClawBot capability, and the README says using those capabilities requires compliance with the applicable terms. A team that needs a guaranteed message delivery contract, delivery receipts or a support SLA should be looking at a platform with a published API and a commercial agreement, not at an adapter that is honest about being built from observed behaviour. Also note the default for inbound image understanding: VISION_ENABLED is off by default, and the README explains that in caption mode the roleplay model does not need vision. If you expect the bot to look at pictures out of the box, it will not.

Chatflow versus a plain persona prompt

The feature that separates WeChat-AI from a thin LLM wrapper is Chatflow, a visual editor at /chatflow where personas can run in either prompt mode or chatflow mode. In prompt mode you write a system prompt and the model handles the rest. In chatflow mode you arrange the conversation as a graph. The README does not document the node types in the excerpt available here, so the practical difference in expressiveness is something you have to read in docs/chatflow.md rather than infer from the feature table.

The comparison that matters is not against another WeChat bot but against building this yourself. A minimal alternative is a small script that polls a WeChat automation library, appends messages to a list, and calls an OpenAI-compatible endpoint. That script is maybe a hundred lines, and for a single user with one persona it will work. What it will not have is the parts that make this a service: LINUX DO OAuth so users log in without you handing out tokens, a per-user bot registry with leases (the compose file's 30 second stop_grace_period exists specifically to let a node release bot leases before SIGKILL), per-day token accounting, sticker storage and moderation, and a Chatflow engine for personas that need more than one model call. The trade is real in both directions. You accept a much larger surface area, a Redis dependency and a reverse-engineered protocol adapter in exchange for not rebuilding the multi-user plumbing. If you only ever want one bot for yourself, the plumbing is the cost and the benefit is mostly the sticker pipeline.

Maintenance, upgrades and what the OTA path assumes

The last push to master was on 2026-09-16, and the most recent release is v0.12.0 from 2026-08-13. The repository is not archived. That is recent enough that the project is being worked on, but the release cadence is the thing to watch rather than the commit date: one tagged release between mid-August and mid-September suggests changes land on master and get tagged in batches.

Upgrades have two paths and they are not equivalent. The documented one is the wrapper, pnpm docker:up, which bumps the version, runs a local OTA pack and brings compose up. The channel publish path is through /admin, where you upload files.json, and the Dockerfile comment notes that this needs no CLI cookie. The README describes OTA as file diff plus automatic restart, which means an update can restart the process under you. The compose file's stop_grace_period of 30 seconds is there so a graceful shutdown can release bot leases first; if you shorten it, expect a window where a bot is still leased to a node that is gone. A plain docker compose up -d --build bypasses both the version bump and the pack, which is exactly the kind of thing that leaves two nodes running different code against one Redis.

Cost is dominated by two line items the project does not hide: remote Redis and LLM tokens. The README advertises per-day token statistics, so you can see the second one. The first is a function of how much you store in Redis, and since bot tokens and stickers live there, it grows with the sticker library. The L1 cache settings exist to cut round trips to a remote Redis, which is a cost optimisation as much as a latency one. On licensing, the Commons Clause is the operative constraint and it is broader than the Apache-2.0 header suggests, so treat the two as one licence and read LICENSE directly.

Editorial conclusion

Adopt WeChat-AI if you run a small, invite-only roleplay bot for yourself and friends, you already have an Upstash Redis URL and an OpenAI-compatible key, and you accept that the iLink adapter in packages/ilink is reverse-engineered and may break without notice. Do not adopt it if you want to sell hosting, run it as a commercial product, or need a documented, versioned WeChat API contract, because the licence forbids commercial use and the README itself says the iLink protocol is based on observed behaviour. Before deploying, run pnpm diag after pnpm db:seed and confirm every required variable resolves, then read docs/e2e-checklist.md and walk the real-device checks, since pnpm accept is only the offline gate.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. SMNETSTUDIO/WeChat-AI on GitHub