iOS：支持微信 8.0.70 版本。更新到最新版后需在后台关掉微信再重新打开，才能正常对接 Bot。
安卓：已支持！扫码提示更新微信，更新完重新扫码即可，可能有部分 Bug 建议自测（部分安卓首页看不到 Bot，需要搜索或者在功能页面显示）。
完全没用过终端？没关系，跟着下面一步步来：
去 nodejs.org 下载 LTS 版本（绿色按钮），双击安装，一路下一步就行。
怎么确认装好了？打开终端，输入：
node -v看到类似 v22.x.x 就说明装好了。
怎么打开终端？
- Mac：按
Command + 空格，输入"终端"，回车- Windows：按
Win + R，输入cmd，回车（或搜索"PowerShell"）- Linux：按
Ctrl + Alt + T
在终端里输入：
npx wx-ai-bot
npx是 Node.js 自带的工具，会自动下载并运行 wx-ai-bot，不需要你手动安装任何东西。
终端会显示菜单，输入数字选择：
AI 提供商：
1) OpenAI ← 最常用，需要 API key
2) Claude
3) Gemini ← Google 的，有免费额度
4) Ollama ← 本地运行，完全免费
...
9) Echo mode ← 测试用，不需要任何 key
新手建议：先选 9（回声模式）测试一下流程，确认能跑通再换成真正的 AI。
终端会显示一个二维码，用微信扫一扫扫它。
扫完在手机上确认，终端显示 ✅ 登录成功 就 OK 了。
现在用另一个微信号给你的 Bot 发消息试试！Bot 会自动回复。
按 Ctrl + C 可以随时停止。
| 问题 | 解决 |
|---|---|
npx 命令找不到 |
Node.js 没装好，重新装一遍 |
| 二维码扫不了 | 终端窗口拉宽一点，或者复制链接到浏览器打开 |
| 扫码后没反应 | iOS 需要微信 8.0.70+；安卓扫码后按提示更新微信 |
| Bot 收不到消息 | 要用另一个微信号给 Bot 发消息，不能自己给自己发 |
| API key 怎么获取 | OpenAI: platform.openai.com，Gemini: aistudio.google.com |
$ npx wx-ai-bot
🤖 wx-ai-bot — 一键微信 AI 机器人
首次使用？来设置你的 AI 后端。
AI 提供商：
1) OpenAI (GPT-4o, GPT-4o-mini 等)
2) Claude (Anthropic API)
3) Gemini (Google)
4) Ollama (本地运行，免费)
5) Codex (OpenAI 编程 Agent)
6) Claude Code (Anthropic 编程 Agent)
7) 自定义 (任何 OpenAI 兼容 API)
8) 回声模式 (不用 AI，原样返回消息)
选择提供商 [1-8]: 1
OpenAI API key: sk-xxx
📱 用微信扫码：
██████████████████████████████
██ ▄▄▄▄▄ █▀▄▀▄█▀█ ▄▄▄▄▄ ██
██ █ █ █▄▀▄ ▀██ █ █ ██
██ ▀▀▀▀▀ █ ▀ █▄▀█ ▀▀▀▀▀ ██
██████████████████████████████
✅ 登录成功！Bot ID: wx_bot_xxx
🤖 wx-ai-bot 已启动！
AI: openai (gpt-4o-mini)
按 Ctrl+C 停止。搞定。你的微信现在有 AI 了。
| 提供商 | 命令 | 说明 |
|---|---|---|
| OpenAI | --provider openai |
GPT-4o, GPT-4o-mini — 经典之选 |
| Claude | --provider claude |
Anthropic Claude — 长对话很强 |
| Gemini | --provider gemini |
Google Gemini — 有免费额度 |
| Ollama | --provider ollama |
本地运行 AI，完全免费 |
| Codex 🆕 | --provider codex |
OpenAI 编程 Agent — 能写真代码 |
| Claude Code 🆕 | --provider claude-code |
Anthropic 编程 Agent — 能读文件、跑命令 |
| OpenClaw 🆕 | --provider openclaw |
OpenClaw AI 网关 — 自动检测本地实例 |
| 自定义 | --provider custom |
任何 OpenAI 兼容 API（OpenRouter, Groq, vLLM...） |
| 回声 | --echo |
不用 AI，原样返回消息（测试用） |
这不只是聊天机器人 — 它们是编程 Agent。发一句"写个 Python 脚本..."，它们会在你的机器上真的写出代码。
# 你的微信变成 Codex 终端
npx wx-ai-bot --provider codex --api-key sk-xxx
# 或者 Claude Code 终端
npx wx-ai-bot --provider claude-code --api-key sk-ant-xxx我们认真对待安全。这不是玩具。
| 特性 | 说明 |
|---|---|
| 🔐 密钥加密 | API 密钥用 AES-256-CBC 加密后存盘 |
| 🔑 绑定机器 | 加密密钥由你机器的唯一指纹派生 |
| 📁 文件权限 | 配置目录 chmod 700，文件 chmod 600 |
| 🪵 日志脱敏 | API 密钥在所有输出中显示为 sk-abc...xyz |
| 🚦 限流防刷 | 每用户：3 秒冷却 + 每分钟最多 10 条 |
| 🧹 输入清洗 | 用户消息在日志中做了防注入处理 |
| 🐳 非 root Docker | 容器以非特权用户运行 |
Session 过期？没问题。wx-ai-bot 自动处理：
⚠️ Session 过期 (code: -14)
🔄 重连中 (1/5)，3 秒后...
📱 用微信扫码：
[二维码]
✅ 重连成功！
指数退避：3s → 5s → 10s → 20s → 30s，最多重试 5 次。
# 构建
docker build -t wx-ai-bot .
# 运行
docker run -it \
-v weixin-bot-data:/home/botuser/.weixin-bot \
-e OPENAI_API_KEY=sk-xxx \
wx-ai-botAlpine 镜像。非 root。零依赖。镜像 < 50MB。
用户可以在微信里给你的 Bot 发这些命令：
| 命令 | 功能 |
|---|---|
/clear |
清空对话历史 |
/help |
显示可用命令 |
/ping |
检查 Bot 是否在线 → 🏓 Pong! |
/status |
显示运行时间、消息数、AI 提供商 |
┌──────────────┐ ┌─────────────────────┐
│ 用户的 │ 发送消息 │ │
│ 微信 │ ──────────────────►│ iLink Bot API │
│ │ │ (腾讯官方) │
└──────────────┘ └──────────┬──────────┘
│
long-poll │
▼
┌─────────────────────┐
│ wx-ai-bot │
│ (你的电脑) │
└──────────┬──────────┘
│
API 调用 │
▼
┌─────────────────────┐
│ AI 提供商 │
│ OpenAI / Claude / │
│ Gemini / Ollama │
└──────────┬──────────┘
│
回复 │
▼
┌──────────────┐ ┌─────────────────────┐
│ 用户的 │ 收到回复 │ iLink Bot API │
│ 微信 │ ◄─────────────────│ (腾讯官方) │
└──────────────┘ └─────────────────────┘
- 官方 API — 使用微信 iLink Bot API，不是 hook
- 零封号风险 — 这是腾讯的正规 Bot 平台
- 隐私安全 — 所有数据在你本地处理，不经过第三方服务器
npx wx-ai-bot [选项]
选项：
--provider <name> openai | claude | gemini | ollama | codex | claude-code | openclaw | custom
--api-key <key> AI 提供商的 API 密钥
--base-url <url> 自定义 API 地址
--model <name> 模型名称（默认：按提供商自动选择）
--echo 回声模式（不用 AI）
--login 强制重新登录
-h, --help 显示帮助
-v, --version 显示版本
环境变量：
OPENAI_API_KEY OpenAI API 密钥
ANTHROPIC_API_KEY Claude API 密钥
GEMINI_API_KEY Gemini API 密钥| 项目 | 说明 |
|---|---|
| weixin-bot-sdk | 完整 SDK — 自定义机器人，支持媒体、TypeScript、事件驱动 |
| weixin-bot-sdk Wiki | 完整文档、教程、API 参考 |
- 使用微信官方 iLink Bot API，不是 hook/注入
- Bot 只能收到用户主动发给它的消息
- Bot 不能监听所有聊天或冒充个人号
- 需要 Node.js 18+
- 目前支持 iOS 微信 8.0.70 + 安卓（安卓扫码后按提示更新微信即可，可能有部分 Bug）
MIT © 2026
⭐ 觉得有用？给个 Star 吧！
基于微信官方 iLink Bot API。零依赖。零风险。