Registry / messaging / koishi-plugin-adapter-wechat-robot

koishi-plugin-adapter-wechat-robot

library2.1.3jsnpmunverified

A Koishi plugin adapter for wechat-robot-client that enables WeChat bot integration with Koishi chatbot framework. Version 2.1.3 adds support for Webhook real-time push and MySQL polling message reception modes, with hybrid mode for maximum reliability. Unlike other WeChat adapters that rely solely on WebSocket or polling, this plugin provides a configurable mode selector, automatic reconnect with health checks every 30 seconds, and support for group/private messages, media forwarding, and @mention parsing. It requires Koishi ^4.0.0 as a peer dependency and optionally MySQL for polling mode. The plugin is actively maintained with a focus on production reliability.

messaging

npm install koishi-plugin-adapter-wechat-robot

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KOISHI-PLUGIN-ADAP

koishi-plugin-adapter-wechat-robot

messagingjavascriptv2.1.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import adapter from 'koishi-plugin-adapter-wechat-robot'

✗ const adapter = require('koishi-plugin-adapter-wechat-robot')

ESM/CJS hybrid – works with Koishi's plugin loader; manual require() may break

Schema

✓ import { Schema } from 'koishi'

✗ import { Schema } from 'koishi-plugin-adapter-wechat-robot'

Schema is exported by Koishi core, not the adapter plugin

WechatRobotClient

✓ import { WechatRobotClient } from 'koishi-plugin-adapter-wechat-robot'

✗ import { Client } from 'koishi-plugin-adapter-wechat-robot'

Internal class, not usually imported directly; use plugin configuration instead

Shows minimal Webhook mode setup for the Koishi adapter, including configuration and required client DB update.

// koishi.config.ts or .yaml import { defineConfig } from 'koishi' export default defineConfig({ plugins: { 'adapter-wechat-robot': { mode: 'webhook', endpoint: process.env.WECHAT_ROBOT_ENDPOINT ?? 'http://127.0.0.1:9000', webhookPath: '/wechat-robot/callback' } } }) // Then configure wechat-robot-client DB: // UPDATE system_settings SET webhook_url = 'http://<koishi-addr>:5140/wechat-robot/callback' WHERE id = 1;

Debug

Known issues

gotchaThe endpoint is the wechat-robot-client API address, not the Koishi server address

fix

Set endpoint to http://<client-host>:<client-port> (e.g., http://127.0.0.1:9000)

affects: >=1.0.0

breakingVersion 2.0.0 introduced mode selector (Schema.union), breaking existing configs without mode field

fix

Add mode: 'webhook' | 'polling' | 'mixed' to your plugin configuration

affects: >=2.0.0

deprecatedThe old single-mode configuration (pre-2.0) without explicit mode is deprecated and will be removed in v3

fix

Explicitly set mode field, e.g., mode: 'webhook'

affects: <3.0.0

gotchapollInterval: 0 does NOT disable polling; it means 0 seconds (effectively infinite loop). Use mixed: false or remove polling config to disable

fix

If you want to disable polling, remove all mysql* config fields or set mode: 'webhook' instead of 'mixed'

affects: >=2.1.0

gotchaIn Docker, MySQL host should be the container name (e.g., wechat-admin-mysql), not localhost or 127.0.0.1

fix

For Docker Compose, set mysqlHost to the MySQL service name defined in docker-compose.yml

affects: >=2.0.0

Errors

Common errors & fixes

Error: connect ECONNREFUSED 127.0.0.1:9000

wechat-robot-client is not running or endpoint is wrong

fix

Ensure wechat-robot-client is running and endpoint points to its API address (e.g., http://wechat-robot-client:9000)

Error: ER_ACCESS_DENIED_ERROR: Access denied for user 'robot_xxxx'@'...'

MySQL user credentials are incorrect or user lacks privileges

fix

Verify mysqlUser, mysqlPassword, and that the user has SELECT on the messages table in the specified mysqlDatabase

Error: Cannot find module 'koishi-plugin-adapter-wechat-robot'

Plugin is not installed or not auto-loaded by Koishi

fix

Run `yarn add koishi-plugin-adapter-wechat-robot` or install via Koishi plugin marketplace

Upgrade

Version history

2.1.3latest on npm

Audit

Dependencies

koishirequiredPeer dependency – the adapter requires Koishi framework v4 or higher to function

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/2212018862/koishi-plugin-adapter-wechat-robot ↗

packagekoishi-plugin-adapter-wechat-robot ↗

homepagehttps://github.com/2212018862/koishi-plugin-adapter-wechat-robot ↗