Tokens & Authentication

agent-wechat uses a simple token-based authentication to secure the REST API.

Where the token lives

Location	Description
~/.config/agent-wechat/token	File on your host machine. Auto-generated on first wx up.
/data/auth-token	Inside the container (read-only mount of the host file)
AGENT_WECHAT_TOKEN env var	Overrides the file-based token

How the token is used

The token serves two purposes:

1. API authentication — every API request must include it in the Authorization header:

   Authorization: Bearer <token>

2. Database encryption — the token is used to encrypt agent.db, the internal database that stores session state and metadata.

The CLI, OpenClaw plugin, and Wechaty puppet all read the token automatically from ~/.config/agent-wechat/token when connecting to localhost.

Caution

Changing or losing the token means agent.db can no longer be read. If you regenerate the token, the old database is effectively lost and a new one will be created.

Generating a token manually

mkdir -p ~/.config/agent-wechat
openssl rand -hex 32 > ~/.config/agent-wechat/token
chmod 600 ~/.config/agent-wechat/token

Regenerating the token

Using the CLI:

wx auth token --regenerate

Or manually:

openssl rand -hex 32 > ~/.config/agent-wechat/token

Then restart the container so it picks up the new token:

wx down && wx up
# or
docker compose restart agent-wechat

Remote access

When connecting to a remote agent-wechat server, you need the token value:

cat ~/.config/agent-wechat/token

Then set it in your client configuration:

• OpenClaw: "token": "<value>" in ~/.openclaw/openclaw.json
• Wechaty: token: '<value>' in the puppet constructor
• CLI: export AGENT_WECHAT_TOKEN=<value>