FAQ

❓ FAQ

General

What is this?

wx-ai-bot is a one-command tool that turns your WeChat into an AI chatbot. Run npx wx-ai-bot, scan a QR code, and your bot is live.

Is this safe? Will my account get banned?

This uses WeChat's official iLink Bot API — a legitimate bot platform by Tencent. It's not a hook or hack. Zero ban risk.

Does this need a server?

No. Everything runs on your local machine. No server, no cloud, no third-party services.

What messages can the bot see?

Only messages that users send directly to the bot. It cannot monitor group chats or other conversations.

---

Setup

I can't scan the QR code in my terminal

Try making your terminal window wider, or use the URL fallback printed below the QR code.

"Session expired" keeps happening

WeChat tokens expire periodically. wx-ai-bot auto-reconnects up to 5 times. If it keeps failing, try npx wx-ai-bot --login.

How do I change AI provider?

Delete ~/.weixin-bot/config.json and run npx wx-ai-bot again, or pass --provider flag directly.

Can I use a proxy?

Yes, use --provider custom --base-url https://your-proxy.com/v1 --api-key xxx.

---

AI Providers

Which provider should I choose?

• Free: Ollama (local) or Gemini (free tier)
• Best quality: OpenAI GPT-4o or Claude
• Coding tasks: Codex or Claude Code
• Privacy: Ollama (everything stays local)

Codex/Claude Code says "CLI not found"

Install the CLI first:

npm i -g @openai/codex        # For Codex
npm i -g @anthropic-ai/claude-code  # For Claude Code

Can I use DeepSeek / Qwen / other models?

Yes! Use --provider custom with any OpenAI-compatible API endpoint.

---

Troubleshooting

Bot is running but not replying

1. Check if the AI provider is working (try a different provider with --echo first)
2. Check your API key is valid
3. Check the terminal for error messages

"Rate limited" message

Built-in protection: 3 second cooldown + 10 messages per minute per user. Wait a moment and try again.

How do I see logs?

All activity is printed to the terminal in real-time. Look for 📩 (received) and ✅ (replied) markers.