Wechaty Puppet Setup

There are two ways to connect Wechaty bots to agent-wechat:

Puppet mode — import @agent-wechat/wechaty-puppet directly and connect to the agent-wechat REST API
Gateway mode — connect via gRPC through a gateway container, using the standard wechaty-puppet-service (no agent-wechat dependency needed)

Both require a running agent-wechat server. You can self-host with Docker or use Managed Hosting.

Option 1: Puppet mode (direct)

Install

npm install @agent-wechat/wechaty-puppet wechaty wechaty-puppet

Prerequisites

Docker — on macOS, install Colima (brew install colima && colima start) or Docker Desktop
An agent-wechat server — self-hosted or via Managed Hosting:
Terminal window
```
npx @agent-wechat/cli up
```
Node.js >= 22

Usage

import { WechatyBuilder } from 'wechaty'
import PuppetAgentWeChat from '@agent-wechat/wechaty-puppet'

const bot = WechatyBuilder.build({
  puppet: new PuppetAgentWeChat({
    serverUrl: 'http://localhost:6174',  // optional, this is the default
    token: 'your-token',                 // optional, reads from ~/.config/agent-wechat/token
  })
})

bot.on('scan', (qrcode, status) => {
  console.log(`Scan QR Code: ${status}`)
  console.log(`https://wechaty.js.org/qrcode/${encodeURIComponent(qrcode)}`)
})

bot.on('login', user => console.log(`Logged in: ${user}`))

bot.on('message', async msg => {
  if (msg.text() === 'ding') {
    await msg.say('dong')
  }
})

await bot.start()

Configuration

Option	Type	Default	Description
`serverUrl`	string	`http://localhost:6174`	agent-wechat server URL
`token`	string	auto	Auth token. Falls back to `AGENT_WECHAT_TOKEN` env var, then `~/.config/agent-wechat/token`
`pollIntervalMs`	number	`2000`	Message polling interval (ms)

Option 2: Gateway mode (gRPC)

Gateway mode wraps the puppet in gRPC, so existing Wechaty bots can connect using the standard wechaty-puppet-service — no @agent-wechat/wechaty-puppet dependency needed. This is the recommended approach for Managed Hosting instances, where the gateway is already running.

Install

npm install wechaty wechaty-puppet-service

Usage

import { WechatyBuilder } from 'wechaty'
import { PuppetService } from 'wechaty-puppet-service'

const bot = WechatyBuilder.build({
  puppet: new PuppetService({
    endpoint: 'your-instance.agent-wx.app:8443',  // provided by managed hosting
    token: 'your-token',
    tls: {
      caCert: fs.readFileSync('/etc/ssl/cert.pem'),  // system CA certs
    },
  })
})

bot.on('login', user => console.log(`Logged in: ${user}`))

bot.on('message', async msg => {
  if (msg.text() === 'ding') {
    await msg.say('dong')
  }
})

await bot.start()

How it works

The connection flow is:

Your Wechaty bot → gRPC → Gateway container → REST API → Agent container

On managed hosting instances, the gateway endpoint and token are provided to you. The token may include an SNI prefix for TLS routing.

Supported features

Feature	Status	Notes
QR Login	Yes	Via WebSocket
Logout	Yes
Receive Text	Yes	Polling-based
Receive Image	Yes	Via media endpoint
Receive Voice	Yes	Via media endpoint
Receive Video	Yes	Via media endpoint
Receive Emoticon	Yes
Send Text	Yes
Send Image	Yes
Send File	Yes
Contact List	Yes	Full address book
Contact Alias	Read	From remark field
Room List	Partial	Recent group chats only
Room Topic	Read	From group name
Message Recall	No
Room Create	No
Friendships	No