Apus connects to WeChat through Tencent's external @tencent-weixin/apus-weixin channel plugin.

Status: external plugin, maintained by the Tencent Weixin team. Direct chats and media are supported. Group chats are not advertised by the plugin capability metadata (it declares direct chats only).

Naming

Use apus-weixin in CLI commands and config paths.

How it works

The WeChat code does not live in the Apus core repo. Apus provides the generic channel plugin contract, and the external plugin provides the WeChat-specific runtime:

  1. apus plugins install installs @tencent-weixin/apus-weixin.
  2. The Gateway discovers the plugin manifest and loads the plugin entrypoint.
  3. The plugin registers channel id apus-weixin.
  4. apus channels login --channel apus-weixin starts QR login.
  5. The plugin stores account credentials under the Apus state directory (~/.apus by default).
  6. When the Gateway starts, the plugin starts its Weixin monitor for each configured account.
  7. Inbound WeChat messages are normalized through the channel contract, routed to the selected Apus agent, and sent back through the plugin outbound path.

That separation matters: Apus core stays channel-agnostic. WeChat login, Tencent iLink API calls, media upload/download, context tokens, and account monitoring are owned by the external plugin.

Install

Quick install:

npx -y @tencent-weixin/apus-weixin-cli install

Manual install:

apus plugins install "@tencent-weixin/apus-weixin"
apus plugins enable apus-weixin

The plugin commands apply changes to a running Gateway. Check the application result; start the Gateway if it is offline.

Login

Run QR login on the same machine that runs the Gateway:

apus channels login --channel apus-weixin

Scan the QR code with WeChat on your phone and confirm the login. The plugin saves the account token locally after a successful scan.

To add another WeChat account, run the same login command again. For multiple accounts, isolate direct-message sessions by account, channel, and sender:

apus config set session.dmScope per-account-channel-peer

Access control

Version 2.4.8 does not register an Apus pairing adapter or create pairing requests. The standard pairing list and approve commands cannot establish DM access for this version. QR login can still allow the user who scanned the code to chat with the bot.

This version reads a legacy account allowlist JSON file instead of Apus's SQLite pairing store. When that list is empty, it falls back to the QR scanner's saved user ID. If neither provides a user ID, its sender check admits any sender whose message reaches the plugin.

On current Apus, apus doctor --fix imports legacy approvals into SQLite and removes the source file. Previously approved secondary senders can therefore lose access in version 2.4.8. Revoking an approval in SQLite does not revoke access granted by the plugin's legacy file or scanner fallback.

Do not rely on standard pairing to manage or revoke DM access with version 2.4.8. If you need pairing enforcement, temporarily disable the plugin until a version with repaired pairing support is available.

For integrations that implement Apus's pairing API, see Pairing.

Compatibility

The package declares these Apus requirements:

Plugin version Declared Apus requirement npm tag
2.4.8 >=2026.5.12 latest
1.x >=2026.1.0 <2026.3.22 legacy

Version 2.4.8 declares >=2026.5.12, but its startup version guard still checks >=2026.3.22. Passing that guard alone does not satisfy the declared requirement.

If the plugin reports that your Apus version is too old, either update Apus or install the legacy plugin line:

apus plugins install @tencent-weixin/apus-weixin@legacy

Plugin 2.4.6 imports the retired apus/plugin-sdk/channel-runtime path and cannot load on Apus 2026.8.1. If startup reports that this subpath is not exported, update to plugin 2.4.8, which uses the available SDK path:

apus plugins update @tencent-weixin/apus-weixin@2.4.8

Sidecar process

The WeChat plugin can run helper work beside the Gateway while it monitors the Tencent iLink API. In issue #68451, that helper path exposed a bug in Apus's generic stale-Gateway cleanup: a child process could try to clean up the parent Gateway process, causing restart loops under process managers such as systemd.

Current Apus startup cleanup excludes the current process and its ancestors, so a channel helper cannot kill the Gateway that launched it. This fix is generic; it is not a WeChat-specific path in core.

Troubleshooting

Check install and status:

apus plugins list
apus channels status --probe
apus --version

If the channel shows as installed but does not connect, enable it and inspect the running plugin:

apus plugins enable apus-weixin
apus plugins inspect apus-weixin --runtime --json

If the Gateway restarts repeatedly after enabling WeChat, update both Apus and the plugin:

npm view @tencent-weixin/apus-weixin version
apus plugins install "@tencent-weixin/apus-weixin" --force
apus gateway restart

If startup reports that the installed plugin package requires compiled runtime output for TypeScript entry, the npm package was published without the compiled JavaScript runtime files Apus needs. Update/reinstall after the plugin publisher ships a fixed package, or temporarily disable/uninstall the plugin.

Temporary disable:

apus plugins disable apus-weixin

Related docs