> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluffbuzz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WeChat

FluffBuzz connects to WeChat through Tencent's external
`@tencent-weixin/fluffbuzz-weixin` channel plugin.

Status: external plugin. Direct chats and media are supported. Group chats are not
advertised by the current plugin capability metadata.

## Naming

* **WeChat** is the user-facing name in these docs.
* **Weixin** is the name used by Tencent's package and by the plugin id.
* `fluffbuzz-weixin` is the FluffBuzz channel id.
* `@tencent-weixin/fluffbuzz-weixin` is the npm package.

Use `fluffbuzz-weixin` in CLI commands and config paths.

## How it works

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

1. `fluffbuzz plugins install` installs `@tencent-weixin/fluffbuzz-weixin`.
2. The Gateway discovers the plugin manifest and loads the plugin entrypoint.
3. The plugin registers channel id `fluffbuzz-weixin`.
4. `fluffbuzz channels login --channel fluffbuzz-weixin` starts QR login.
5. The plugin stores account credentials under the FluffBuzz state directory.
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 FluffBuzz agent, and sent back through the plugin outbound path.

That separation matters: FluffBuzz core should stay 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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
npx -y @tencent-weixin/fluffbuzz-weixin-cli install
```

Manual install:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz plugins install "@tencent-weixin/fluffbuzz-weixin"
fluffbuzz config set plugins.entries.fluffbuzz-weixin.enabled true
```

Restart the Gateway after install:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz gateway restart
```

## Login

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz channels login --channel fluffbuzz-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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz config set session.dmScope per-account-channel-peer
```

## Access control

Direct messages use the normal FluffBuzz pairing and allowlist model for channel
plugins.

Approve new senders:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz pairing list fluffbuzz-weixin
fluffbuzz pairing approve fluffbuzz-weixin <CODE>
```

For the full access-control model, see [Pairing](/channels/pairing).

## Compatibility

The plugin checks the host FluffBuzz version at startup.

| Plugin line | FluffBuzz version       | npm tag  |
| ----------- | ----------------------- | -------- |
| `2.x`       | `>=2026.3.22`           | `latest` |
| `1.x`       | `>=2026.1.0 <2026.3.22` | `legacy` |

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz plugins install @tencent-weixin/fluffbuzz-weixin@legacy
```

## 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 FluffBuzz'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 FluffBuzz startup cleanup excludes the current process and its ancestors,
so a channel helper must not kill the Gateway that launched it. This fix is
generic; it is not a WeChat-specific path in core.

## Troubleshooting

Check install and status:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz plugins list
fluffbuzz channels status --probe
fluffbuzz --version
```

If the channel shows as installed but does not connect, confirm that the plugin is
enabled and restart:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz config set plugins.entries.fluffbuzz-weixin.enabled true
fluffbuzz gateway restart
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
npm view @tencent-weixin/fluffbuzz-weixin version
fluffbuzz plugins install "@tencent-weixin/fluffbuzz-weixin" --force
fluffbuzz gateway restart
```

Temporary disable:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz config set plugins.entries.fluffbuzz-weixin.enabled false
fluffbuzz gateway restart
```

## Related docs

* Channel overview: [Chat Channels](/channels)
* Pairing: [Pairing](/channels/pairing)
* Channel routing: [Channel Routing](/channels/channel-routing)
* Plugin architecture: [Plugin Architecture](/plugins/architecture)
* Channel plugin SDK: [Channel Plugin SDK](/plugins/sdk-channel-plugins)
* External package: [@tencent-weixin/fluffbuzz-weixin](https://www.npmjs.com/package/@tencent-weixin/fluffbuzz-weixin)