wechaty-puppet-gateway

Generic gRPC gateway for Wechaty puppets. Run any Wechaty puppet as a remote service.

Architecture

┌─────────────────────────────────────┐     ┌─────────────────────────────────────┐
│      Machine A (Gateway)            │     │      Machine B (Your App)           │
│                                     │     │                                     │
│  ┌─────────────────────────────┐    │     │    ┌─────────────────────────┐      │
│  │ Real Puppet                 │    │     │    │   Your Wechaty App      │      │
│  │ (@wechatferry/puppet, etc.) │    │     │    │   (moltbot, etc.)       │      │
│  └─────────────┬───────────────┘    │     │    └───────────┬─────────────┘      │
│                │                    │     │                │                    │
│                ▼                    │     │                ▼                    │
│  ┌─────────────────────────────┐    │     │    ┌─────────────────────────┐      │
│  │  wechaty-puppet-gateway     │◀───┼─────┼────│ @juzi/wechaty-puppet-   │      │
│  │  (this package)             │    │     │    │ service (client)        │      │
│  │  gRPC server on :8788       │    │     │    │ endpoint: machineA:8788 │      │
│  └─────────────────────────────┘    │     │    └─────────────────────────┘      │
│                                     │     │                                     │
└─────────────────────────────────────┘     └─────────────────────────────────────┘

Quick Start

# Run with any puppet (auto-installs if missing)
npx wechaty-puppet-gateway --puppet @wechatferry/puppet

# Or with a config file
npx wechaty-puppet-gateway --config ./config.json

Installation

npm install -g wechaty-puppet-gateway

# Or run directly with npx (recommended)
npx wechaty-puppet-gateway --puppet <puppet-name>

Usage

CLI Options

Usage: wechaty-gateway [options]

Options:
  -p, --puppet <name>    Puppet package name (e.g., @wechatferry/puppet)
  -c, --config <path>    Path to config file (JSON)
  --port <port>          gRPC server port (default: 8788)
  --host <host>          gRPC server host (default: 0.0.0.0)
  -t, --token <token>    Authentication token (auto-generated if not set)
  --no-tls               Disable TLS (for local development)
  --no-auto-install      Disable auto-install of missing puppet
  -h, --help             Display help

Config File

Create a JSON config file:

{
  "puppet": "@wechatferry/puppet",
  "puppetOptions": {
    "// any puppet-specific options": "go here"
  },
  "port": 8788,
  "host": "0.0.0.0",
  "token": "insecure_my-secret-token",
  "tls": false
}

Environment Variables

WECHATY_GATEWAY_PUPPET=@wechatferry/puppet
WECHATY_GATEWAY_PORT=8788
WECHATY_GATEWAY_HOST=0.0.0.0
WECHATY_GATEWAY_TOKEN=insecure_my-token
WECHATY_GATEWAY_NO_TLS=true

Priority: CLI args > Environment variables > Config file > Defaults

Connecting from Your App

In your Wechaty app (e.g., moltbot-wechaty), configure the puppet service client:

# config.yaml
channels:
  wechaty:
    puppet: "@juzi/wechaty-puppet-service"
    puppetOptions:
      endpoint: "gateway-server:8788"
      token: "insecure_my-secret-token"
      tls:
        disable: true

Or programmatically:

import { WechatyBuilder } from 'wechaty'

const bot = WechatyBuilder.build({
  puppet: '@juzi/wechaty-puppet-service',
  puppetOptions: {
    endpoint: 'gateway-server:8788',
    token: 'insecure_my-secret-token',
    tls: { disable: true },
  },
})

await bot.start()

Examples

WeChatFerry (PC Hook)

npx wechaty-puppet-gateway \
  --puppet @wechatferry/puppet \
  --port 8788 \
  --token insecure_wcferry-dev

PadLocal

npx wechaty-puppet-gateway \
  --config padlocal.config.json

{
  "puppet": "wechaty-puppet-padlocal",
  "puppetOptions": {
    "token": "YOUR_PADLOCAL_TOKEN"
  },
  "port": 8788,
  "token": "insecure_padlocal-gw"
}

Mock (for testing)

npx wechaty-puppet-gateway \
  --puppet @juzi/wechaty-puppet-mock \
  --port 8788

Token Format

Tokens should be prefixed with an SNI identifier for TLS. For local/insecure usage:

insecure_<your-identifier>

For production with TLS, use a proper UUID:

yourservice_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Auto-Install

By default, the gateway will automatically install missing puppet packages. This happens when:

1. You run npx wechaty-puppet-gateway --puppet @wechatferry/puppet
2. The package @wechatferry/puppet is not found
3. Gateway prompts and installs it via npm/yarn/pnpm

Disable with --no-auto-install.

License

Apache-2.0