agent-wechatbot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent WeChatBot

A TypeScript CLI tool that enables AI agents and humans to send messages through WeChat Official Account API. Designed for customer engagement, template notifications, and CI/CD integrations using App ID + App Secret authentication.

一款TypeScript CLI工具，支持AI Agent和人类通过微信公众号API发送消息。基于App ID + App Secret认证，适用于客户互动、模板通知以及CI/CD集成场景。

Key Concepts

核心概念

Before diving in, a few things about WeChat Official Account API:

Send-only — The Official Account API delivers inbound messages via webhooks only. This CLI cannot list or read received messages.
Customer service messages — You can send free-form text, image, and news (article) messages to users who have interacted with your account within the last 48 hours.
Template messages — Pre-approved message templates can be sent at any time. Templates must be created and approved in the WeChat Official Account admin panel.
App ID — Your Official Account's unique application identifier. Found in the WeChat Official Account admin panel under Development > Basic Configuration.
App Secret — Your application's secret key, paired with the App ID. Found in the same location.
OpenID — Each follower has a unique OpenID scoped to your Official Account. Use
```
user list
```
to retrieve follower OpenIDs.
IP Whitelist — Your server IP must be added to the Official Account's IP whitelist, or API calls will fail with error
```
40164
```
.
Rate limits — WeChat enforces API call frequency limits. Customer service messages are limited per account per day.

开始使用前，先了解微信公众号API的几个关键点：

仅支持发送 —— 微信公众号API仅通过webhook接收消息，本CLI无法查看或读取收到的消息。
客服消息 —— 对于过去48小时内与公众号互动过的用户，你可以发送自由格式的文本、图片和图文（文章）消息。
模板消息 —— 预先审核通过的消息模板可随时发送。模板需在微信公众号后台创建并审核。
App ID —— 公众号的唯一应用标识，可在微信公众号后台「开发 > 基本配置」中找到。
App Secret —— 与App ID配对的应用密钥，同样在上述位置获取。
OpenID —— 每个粉丝对应一个针对当前公众号的唯一OpenID，可使用
```
user list
```
命令获取粉丝的OpenID。
IP白名单 —— 服务器IP必须添加到公众号的IP白名单中，否则API调用会返回错误
```
40164
```
。
调用限制 —— 微信对API调用频率有限制，客服消息有每日账号调用上限。

Quick Start

快速开始

bash

undefined

bash

undefined

Set your API credentials

设置API凭证

agent-wechatbot auth set your-app-id your-app-secret

Verify authentication

验证认证状态

agent-wechatbot auth status

Send a text message (recipient must have interacted within 48h)

发送文本消息（接收者需在48小时内有互动）

agent-wechatbot message send oXXXXXXXXXXXXXXX "Hello from the CLI!"

List available templates

查看可用模板

agent-wechatbot template list --pretty

List followers

查看粉丝列表

agent-wechatbot user list --pretty

undefined

agent-wechatbot user list --pretty

undefined

Authentication

认证

API Credential Setup

API凭证设置

agent-wechatbot uses App ID + App Secret pairs from the WeChat Official Account admin panel:

bash

undefined

agent-wechatbot使用微信公众号后台获取的App ID + App Secret配对：

bash

undefined

Set credentials (validates against WeChat API before saving)

设置凭证（保存前会验证微信API）

agent-wechatbot auth set your-app-id your-app-secret

Check auth status

检查认证状态

agent-wechatbot auth status

Clear stored credentials

清除已存储的凭证

agent-wechatbot auth clear

undefined

agent-wechatbot auth clear

undefined

Multi-Account Management

多账号管理

bash

undefined

bash

undefined

List stored accounts

查看已存储的账号

agent-wechatbot auth list

Switch active account

切换活跃账号

agent-wechatbot auth use <account-id>

Remove a stored account

删除已存储的账号

agent-wechatbot auth remove <account-id>

undefined

agent-wechatbot auth remove <account-id>

undefined

Memory

记忆功能

The agent maintains a

~/.config/agent-messenger/MEMORY.md

file as persistent memory across sessions. This is agent-managed, the CLI does not read or write this file. Use the

Read

and

Write

tools to manage your memory file.

Agent会在

~/.config/agent-messenger/MEMORY.md

文件中保存跨会话的持久化记忆。该文件由Agent管理，CLI不会直接读写，需使用

Read

和

Write

工具管理。

Reading Memory

读取记忆

At the start of every task, read

~/.config/agent-messenger/MEMORY.md

using the

Read

tool to load any previously discovered account IDs, template names, follower OpenIDs, and preferences.

If the file doesn't exist yet, that's fine. Proceed without it and create it when you first have useful information to store.
If the file can't be read (permissions, missing directory), proceed without memory. Don't error out.

在每个任务开始时，使用

Read

工具读取

~/.config/agent-messenger/MEMORY.md

，加载之前记录的账号ID、模板名称、粉丝OpenID和偏好设置。

如果文件不存在，无需处理，后续有有用信息时再创建即可。
如果无法读取文件（权限问题、目录缺失），跳过记忆功能继续执行，不要抛出错误。

Writing Memory

写入记忆

After discovering useful information, update

~/.config/agent-messenger/MEMORY.md

using the

Write

tool. Write triggers include:

After discovering account IDs and App IDs (from
```
auth list
```
,
```
auth status
```
, etc.)
After discovering template names and their parameters (from
```
template list
```
, etc.)
After discovering follower OpenIDs (from
```
user list
```
,
```
user get
```
, etc.)
After the user gives you an alias or preference ("call this the notifications account", "my main template is X")

When writing, include the complete file content. The

Write

tool overwrites the entire file.

发现有用信息后，使用

Write

工具更新

~/.config/agent-messenger/MEMORY.md

。触发写入的场景包括：

获取到账号ID和App ID后（来自
```
auth list
```
、
```
auth status
```
等命令）
获取到模板名称及其参数后（来自
```
template list
```
等命令）
获取到粉丝OpenID后（来自
```
user list
```
、
```
user get
```
等命令）
用户设置别名或偏好后（如"将这个账号称为通知账号"、"我的主要模板是X"）

写入时需包含完整的文件内容，

Write

工具会覆盖整个文件。

What to Store

存储内容

Account IDs (App IDs) with names
Template IDs with their required parameters
Frequently used follower OpenIDs with context
User-given aliases ("notifications account", "marketing account")
Any user preference expressed during interaction

带名称的账号ID（App ID）
带必填参数的模板ID
带上下文的常用粉丝OpenID
用户设置的别名（如"通知账号"、"营销账号"）
交互过程中用户表达的任何偏好

What NOT to Store

禁止存储内容

Never store App Secrets or any credentials. Never store full message content (just context). Never store personal user data.

切勿存储App Secret或任何凭证，切勿存储完整消息内容（仅保留上下文），切勿存储用户个人数据。

Handling Stale Data

处理过期数据

If a memorized template returns an error (template not found, account invalid), remove it from

MEMORY.md

. Don't blindly trust memorized data. Verify when something seems off. Prefer re-listing over using a memorized value that might be stale.

如果记忆中的模板返回错误（模板不存在、账号无效），请从

MEMORY.md

中删除该条目。不要盲目信任记忆数据，当出现异常时进行验证，优先重新查询而非使用可能过期的记忆值。

Format / Example

格式示例

markdown

undefined

markdown

undefined

Agent Messenger Memory

WeChat Accounts

```
wx1234567890
```
- Acme Notifications

```
wx1234567890
```
- Acme Notifications

Templates (Acme Notifications)

```
TM00001
```
- Order confirmation, params: [order_id, customer_name]
```
TM00002
```
- Shipping update, params: [tracking_number]

```
TM00001
```
- Order confirmation, params: [order_id, customer_name]
```
TM00002
```
- Shipping update, params: [tracking_number]

Frequent Recipients

```
oABCD1234
```
- Test user (internal QA)
```
oEFGH5678
```
- VIP customer

```
oABCD1234
```
- Test user (internal QA)
```
oEFGH5678
```
- VIP customer

Aliases

"notifications" ->
```
wx1234567890
```
(Acme Notifications)

"notifications" ->
```
wx1234567890
```
(Acme Notifications)

Notes

IP whitelist configured for 203.0.113.10
Customer service messages limited to 48h interaction window


> Memory lets you skip repeated `template list` calls. When you already know a template ID from a previous session, use it directly.

IP whitelist configured for 203.0.113.10
Customer service messages limited to 48h interaction window


> 记忆功能可避免重复调用`template list`命令。如果之前会话中已获取模板ID，可直接使用。

Commands

命令

Auth Commands

认证命令

bash

undefined

bash

undefined

Set account credentials (validates against API)

设置账号凭证（会通过API验证）

agent-wechatbot auth set <app-id> <app-secret>

Check auth status

检查认证状态

agent-wechatbot auth status agent-wechatbot auth status --account <account-id>

List stored accounts

查看已存储的账号

agent-wechatbot auth list

Switch active account

切换活跃账号

agent-wechatbot auth use <account-id>

Remove a stored account

删除已存储的账号

agent-wechatbot auth remove <account-id>

Clear all credentials

清除所有凭证

agent-wechatbot auth clear

undefined

agent-wechatbot auth clear

undefined

Whoami Command

Whoami命令

bash

undefined

bash

undefined

Show current authenticated bot

显示当前已认证的Bot

agent-wechatbot whoami agent-wechatbot whoami --pretty agent-wechatbot whoami --account <account-id>

undefined

agent-wechatbot whoami agent-wechatbot whoami --pretty agent-wechatbot whoami --account <account-id>

undefined

Message Commands

消息命令

bash

undefined

bash

undefined

Send a text message (customer service, within 48h window)

发送文本消息（客服消息，需在48小时互动窗口内）

agent-wechatbot message send <open-id> <text> agent-wechatbot message send oABCD1234 "Your order has shipped!"

Send an image message (customer service, within 48h window)

发送图片消息（客服消息，需在48小时互动窗口内）

agent-wechatbot message send-image <open-id> <media-id> agent-wechatbot message send-image oABCD1234 MEDIA_ID_HERE

Send a news/article message (customer service, within 48h window)

发送图文/文章消息（客服消息，需在48小时互动窗口内）

agent-wechatbot message send-news <open-id> --title "Title" --description "Desc" --url "https://..." --picurl "https://..."

undefined

agent-wechatbot message send-news <open-id> --title "Title" --description "Desc" --url "https://..." --picurl "https://..."

undefined

Template Commands

模板命令

bash

undefined

bash

undefined

List message templates

查看消息模板

agent-wechatbot template list

Send a template message

发送模板消息

agent-wechatbot template send <open-id> <template-id> agent-wechatbot template send oABCD1234 TM00001 --data '{"order_id":{"value":"ORD-9876"},"customer_name":{"value":"Alice"}}' --url "https://example.com/order/9876"

Delete a template

删除模板

agent-wechatbot template delete <template-id>

undefined

agent-wechatbot template delete <template-id>

undefined

User Commands

用户命令

bash

undefined

bash

undefined

List followers (paginated)

查看粉丝列表（分页）

agent-wechatbot user list agent-wechatbot user list --next-openid oLAST_OPENID

Get user info by OpenID

通过OpenID获取用户信息

agent-wechatbot user get <open-id> agent-wechatbot user get oABCD1234 --lang en

undefined

agent-wechatbot user get <open-id> agent-wechatbot user get oABCD1234 --lang en

undefined

Output Format

输出格式

JSON (Default)

JSON（默认）

All commands output JSON by default for AI consumption:

json

{
  "success": true,
  "app_id": "wx1234567890",
  "account_name": "wx1234567890"
}

所有命令默认输出JSON格式，方便AI处理：

json

{
  "success": true,
  "app_id": "wx1234567890",
  "account_name": "wx1234567890"
}

Pretty (Human-Readable)

格式化输出（人类可读）

Use

--pretty

flag for formatted output:

bash

agent-wechatbot template list --pretty

使用

--pretty

参数获取格式化输出：

bash

agent-wechatbot template list --pretty

Global Options

全局参数

Option	Description
`--pretty`	Human-readable output instead of JSON
`--account <id>`	Use a specific account for this command

参数	描述
`--pretty`	输出人类可读格式而非JSON
`--account <id>`	为当前命令指定特定账号

Common Patterns

常见使用场景

See

references/common-patterns.md

for additional workflows.

更多工作流请查看

references/common-patterns.md

。

Send a customer service message within 48h window

在48小时窗口内发送客服消息

Customer service messages can be sent to users who have interacted with your account within the last 48 hours:

bash

undefined

可向过去48小时内与公众号互动过的用户发送客服消息：

bash

undefined

Send a text reply

发送文本回复

agent-wechatbot message send oABCD1234 "Thanks for reaching out! We'll look into this right away."

Send a news article

发送图文文章

agent-wechatbot message send-news oABCD1234
--title "Your Order Update"
--description "Your order #12345 has been shipped"
--url "https://example.com/orders/12345"
--picurl "https://example.com/images/shipping.jpg"

undefined

undefined

Send a template notification (anytime)

发送模板通知（随时可发）

Template messages can be sent at any time, regardless of the 48h window:

bash

undefined

模板消息不受48小时窗口限制，可随时发送：

bash

undefined

List templates to find the right one

查看模板找到合适的模板

agent-wechatbot template list --pretty

Send a template message with data

发送带参数的模板消息

agent-wechatbot template send oABCD1234 TM00001
--data '{"order_id":{"value":"ORD-9876"},"status":{"value":"Shipped"}}'
--url "https://example.com/orders/9876"

undefined

agent-wechatbot template send oABCD1234 TM00001
--data '{"order_id":{"value":"ORD-9876"},"status":{"value":"Shipped"}}'
--url "https://example.com/orders/9876"

undefined

List and inspect followers

查看并检查粉丝信息

bash

undefined

bash

undefined

Get first page of followers

获取第一页粉丝列表

agent-wechatbot user list --pretty

Get next page

获取下一页粉丝列表

agent-wechatbot user list --next-openid oLAST_OPENID --pretty

Get details for a specific follower

获取特定粉丝的详细信息

agent-wechatbot user get oABCD1234 --pretty

undefined

agent-wechatbot user get oABCD1234 --pretty

undefined

CI/CD deployment notification

CI/CD部署通知

bash

agent-wechatbot template send oABCD1234 deployment_alert \
  --data '{"version":{"value":"v2.1.0"},"environment":{"value":"production"},"status":{"value":"success"}}'

bash

agent-wechatbot template send oABCD1234 deployment_alert \
  --data '{"version":{"value":"v2.1.0"},"environment":{"value":"production"},"status":{"value":"success"}}'

Templates

模板示例

See

templates/

directory for runnable examples:

```
post-message.sh
```
- Send a customer service message with error handling and retries
```
account-summary.sh
```
- Generate account, template, and follower summary
```
send-template.sh
```
- Send a template message with parameters

templates/

目录下有可运行的示例：

```
post-message.sh
```
- 带错误处理和重试机制的客服消息发送脚本
```
account-summary.sh
```
- 生成账号、模板和粉丝汇总信息
```
send-template.sh
```
- 发送带参数的模板消息

Error Handling

错误处理

All commands return consistent error format:

json

{
  "error": "No credentials. Run \"auth set <app-id> <app-secret>\" first."
}

Common errors:

No credentials

Account not found

Invalid credentials

WeChat API error (errcode: 40001)

IP not in whitelist (errcode: 40164)

Rate limit exceeded (errcode: 45009)

所有命令返回统一的错误格式：

json

{
  "error": "No credentials. Run \"auth set <app-id> <app-secret>\" first."
}

常见错误：

No credentials

、

Account not found

、

Invalid credentials

、

WeChat API error (errcode: 40001)

、

IP not in whitelist (errcode: 40164)

、

Rate limit exceeded (errcode: 45009)

。

Configuration

配置

Credentials stored in

~/.config/agent-messenger/wechatbot-credentials.json

(0600 permissions).

Config format:

json

{
  "current": { "account_id": "wx1234567890" },
  "accounts": {
    "wx1234567890": {
      "app_id": "wx1234567890",
      "app_secret": "...",
      "account_name": "wx1234567890"
    }
  }
}

凭证存储在

~/.config/agent-messenger/wechatbot-credentials.json

（权限为0600）。

配置格式：

json

{
  "current": { "account_id": "wx1234567890" },
  "accounts": {
    "wx1234567890": {
      "app_id": "wx1234567890",
      "app_secret": "...",
      "account_name": "wx1234567890"
    }
  }
}

Limitations

限制

Cannot list or read received messages — WeChat Official Account API delivers inbound messages via webhooks only. This CLI is send-only.
Customer service messages require 48h window — Free-form text, image, and news messages only work within 48 hours of the user's last interaction.
Template messages require pre-approval — Templates must be created and approved in the WeChat admin panel before use.
IP whitelist required — Your server's IP must be added to the Official Account's whitelist, or you'll get error
```
40164
```
.
Media IDs required for images — Images must be uploaded to WeChat's media platform first. The CLI accepts media IDs, not URLs.
No group chat support — Official Account API communicates with individual followers only.
No real-time events / WebSocket connection — Inbound messages require a separate webhook server.
No message editing or deletion
No voice or video calls
Access tokens expire — Tokens are valid for 7200 seconds. The CLI handles automatic refresh.

无法查看或读取收到的消息 —— 微信公众号API仅通过webhook接收消息，本CLI仅支持发送。
客服消息需在48小时窗口内发送 —— 自由格式的文本、图片和图文消息仅在用户最后互动的48小时内有效。
模板消息需预先审核 —— 模板需在微信后台创建并审核通过后才能使用。
需配置IP白名单 —— 服务器IP必须添加到公众号白名单，否则会返回错误
```
40164
```
。
图片需使用Media ID —— 图片需先上传到微信媒体平台，CLI仅接受Media ID，不支持URL。
不支持群聊 —— 公众号API仅支持与单个粉丝通信。
无实时事件/WebSocket连接 —— 接收消息需单独部署webhook服务器。
无法编辑或删除消息
不支持语音或视频通话
Access Token会过期 —— Token有效期为7200秒，CLI会自动处理刷新。

Troubleshooting

故障排查

agent-wechatbot: command not found

agent-wechatbot: command not found

agent-wechatbot
is NOT the npm package name. The npm package is

agent-messenger

If the package is installed globally, use

agent-wechatbot

directly:

bash

agent-wechatbot message send oABCD1234 "Hello"

If the package is NOT installed, run it directly with

npx -y

bash

npx -y agent-messenger wechatbot message send oABCD1234 "Hello"

Note: If the user prefers a different package runner (e.g.,
bunx
,
pnpx
,
pnpm dlx
), use that instead.

NEVER run
npx agent-wechatbot
,
bunx agent-wechatbot
, or
pnpm dlx agent-wechatbot
. It will fail or install a wrong package since

agent-wechatbot

is not the npm package name.

agent-wechatbot
并非npm包名称，npm包名称为

agent-messenger

。

如果已全局安装包，可直接使用

agent-wechatbot

：

bash

agent-wechatbot message send oABCD1234 "Hello"

如果未安装包，可使用

npx -y

直接运行：

bash

npx -y agent-messenger wechatbot message send oABCD1234 "Hello"

注意：如果用户偏好其他包运行工具（如
bunx
、
pnpx
、
pnpm dlx
），可替换使用。

切勿运行
npx agent-wechatbot
、
bunx agent-wechatbot
或
pnpm dlx agent-wechatbot
，由于

agent-wechatbot

不是npm包名称，这会导致运行失败或安装错误的包。

How to get API credentials

如何获取API凭证

Log in to the WeChat Official Account admin panel
Navigate to Development > Basic Configuration
Copy your App ID and App Secret (you may need to reset the secret if you don't have it saved)
Add your server's IP to the IP Whitelist

Run

agent-wechatbot auth set <app-id> <app-secret>

登录微信公众号后台
进入「开发 > 基本配置」
复制App ID和App Secret（如果未保存，可能需要重置密钥）
将服务器IP添加到IP白名单

运行

agent-wechatbot auth set <app-id> <app-secret>

IP whitelist errors (40164)

IP白名单错误（40164）

If you get error

, your server's IP is not in the Official Account's whitelist. Add it in the admin panel under Development > Basic Configuration > IP Whitelist.

如果返回错误

，说明服务器IP未添加到公众号白名单，需在后台「开发 > 基本配置 > IP白名单」中添加。

Token errors (40001, 42001)

Token错误（40001、42001）

These indicate an expired or invalid access token. The CLI handles automatic token refresh, but if you see persistent errors:

Verify your App Secret hasn't been reset in the admin panel

Re-run

agent-wechatbot auth set <app-id> <app-secret>

with the current credentials

这些错误表示Access Token过期或无效。CLI会自动处理Token刷新，但如果持续出现错误：

验证App Secret是否在后台被重置

使用当前凭证重新运行

agent-wechatbot auth set <app-id> <app-secret>

Rate limiting (45009)

调用频率限制（45009）

WeChat enforces API call frequency limits. If you hit error

, wait before retrying. For bulk operations, add delays between requests.

微信对API调用频率有限制，如果返回错误

，请等待后重试。批量操作时，请在请求之间添加延迟。

References

参考文档

Authentication Guide
Common Patterns

认证指南
常见使用场景