/agent-wechatbot

name: agent-wechatbot
description: Interact with WeChat Official Account using API credentials - send messages, manage templates, list followers
version: 2.38.1
allowed-tools: Bash(agent-wechatbot:*)
metadata:
  openclaw:
    requires:
      bins:
        - agent-wechatbot
    install:
      - kind: node
        package: agent-messenger
        bins: [agent-wechatbot]

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.

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.

Quick Start

# Set your API credentials
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)
agent-wechatbot message send oXXXXXXXXXXXXXXX "Hello from the CLI!"

# List available templates
agent-wechatbot template list --pretty

# List followers
agent-wechatbot user list --pretty

Authentication

API Credential Setup

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

# Set credentials (validates against WeChat API before saving)
agent-wechatbot auth set your-app-id your-app-secret

# Check auth status
agent-wechatbot auth status

# Clear stored credentials
agent-wechatbot auth clear

Multi-Account Management

# 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>

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.

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.

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.

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

What NOT to Store

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

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.

Format / Example

# Agent Messenger Memory

## WeChat Accounts

- `wx1234567890` - Acme Notifications

## Templates (Acme Notifications)

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

## Frequent Recipients

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

## Aliases

- "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.

Commands

Auth Commands

# Set account credentials (validates against 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 clea