微信命令行工具 - 基于 WeChat iLink Bot API 实现的独立命令行工具,支持扫码注册、长轮询接收消息和发送文本消息。
- 扫码注册 - 微信扫码绑定,获得 bot 账号
- 交互模式 - 同时收发消息,类似聊天界面
- 消息监听 - 后台长轮询接收消息
- 发送消息 - 发送文本消息
- 凭证持久化 - 自动保存账号,无需重复注册
cd weixin-cli
npm install
npm run build# 1. 首次使用 - 注册(扫码)
npm start login
# 2. 日常使用 - 交互模式
npm start chat同时监听和发送消息,类似聊天界面。
npm start chat交互命令:
| 命令 | 说明 |
|---|---|
<消息> |
发送消息给当前联系人 |
/to <用户ID> |
设置接收者 |
/list |
列出最近联系人 |
/quit 或 /q |
退出 |
示例:
npm start chat
╔════════════════════════════════════════════════════════════╗
║ WeChat CLI - Interactive Chat Mode ║
╚════════════════════════════════════════════════════════════╝
Bot ID: abc123def456@im.bot
Current recipient: xyz789uvw012@im.wechat
> 你好
[Sent to xyz789uvw012@im.wechat]
>
[12:30:00 PM] xyz789uvw012@im.wechat: 收到了
> /q
Goodbye!
注意:这个命令实际上是"注册"而非"登录"。
npm start login行为:
- 无账号 → 显示二维码,扫码注册
- 有账号且有效 → 显示账号信息,提示可用
- 有账号但过期 → 提示过期,重新注册
首次注册流程:
WeChat CLI Register
==================
No account found. Starting registration...
[二维码显示在终端]
请用微信扫描二维码
Scanning... (等待扫码)
Confirmed! (扫码成功)
Bot ID: abc123def456@im.bot
User ID: xyz789uvw012@im.wechat
Account saved to ~/.weixin-cli/account.json
单独监听消息,按 Ctrl+C 退出(可能需要等几秒)。
npm start listen💡 推荐使用
chat命令,可以同时收发消息,Ctrl+C 立即退出。
# 发送给最后一个联系人
npm start send "你好"
# 发送给指定用户
npm start send xyz789uvw012@im.wechat "你好"npm start status输出:
Bot ID: abc123def456@im.bot
User ID: xyz789uvw012@im.wechat
Base URL: https://ilinkai.weixin.qq.com
Login Time: 3/30/2026, 11:57:01 AM
删除保存的账号文件,不会删除服务器端的 bot。
npm start logout| 文件 | 说明 |
|---|---|
~/.weixin-cli/account.json |
账号凭证(botId, botToken, baseUrl 等) |
~/.weixin-cli/recent-senders.json |
最近联系人列表 |
A: 不需要。只需首次注册,之后凭证会保存。日常直接用 chat 即可。
A: 可能会。长期不用(比如几个月)可能过期,需要重新 login。
A: 检查以下几点:
- 确认
chat或listen收到过对方消息(需要获取 context_token) - 确认接收者 ID 正确(用
/list查看) - 查看 bot 是否被对方限制
A:
chat模式:按一次即可,或输入/qlisten模式:可能需要等几秒(等待网络请求超时)
| 命令 | 服务器端 | 本地 |
|---|---|---|
login |
创建/验证 bot 账号 | 保存凭证到文件 |
logout |
无操作 | 删除凭证文件 |
logout 只是"忘记本地凭证",服务器上的 bot 仍然存在。
本工具基于微信 iLink Bot API 实现,使用固定基础 URL:
https://ilinkai.weixin.qq.com
API 端点: GET /ilink/bot/get_bot_qrcode
请求示例:
curl "https://ilinkai.weixin.qq.com/ilink/bot/get_bot_qrcode?bot_type=3" \
-H "iLink-App-Id: bot" \
-H "iLink-App-ClientVersion: 65536"响应:
{
"qrcode": "xxx",
"qrcode_img_content": "https://xxx.weixin.qq.com/qrcode/xxx"
}使用方式:
- 调用此接口获取二维码
- 显示在终端或让用户用浏览器打开
qrcode_img_content - 用户用微信扫码
API 端点: GET /ilink/bot/get_qrcode_status
请求示例:
curl "https://ilinkai.weixin.qq.com/ilink/bot/get_qrcode_status?qrcode=xxx" \
-H "iLink-App-Id: bot" \
-H "iLink-App-ClientVersion: 65536"响应(轮询状态变化):
// 状态1:等待扫码
{ "status": "wait" }
// 状态2:已扫码,等待确认
{ "status": "scaned" }
// 状态3:确认成功,返回凭证
{
"status": "confirmed",
"bot_token": "abc123def456@im.bot:0123456789abcdef0123456789abcdef",
"ilink_bot_id": "abc123def456@im.bot",
"ilink_user_id": "xyz789uvw012@im.wechat",
"baseurl": "https://ilinkai.weixin.qq.com"
}使用方式:
- 长轮询此接口(35秒超时)
- 每秒检查一次,直到
status变为confirmed - 保存返回的凭证到本地
API 端点: POST /ilink/bot/getupdates
请求示例:
curl -X POST "https://ilinkai.weixin.qq.com/ilink/bot/getupdates" \
-H "Content-Type: application/json" \
-H "AuthorizationType: ilink_bot_token" \
-H "Authorization: Bearer abc123def456@im.bot:0123456789abcdef0123456789abcdef" \
-H "iLink-App-Id: bot" \
-H "iLink-App-ClientVersion: 65536" \
-d '{
"get_updates_buf": "",
"base_info": { "channel_version": "1.0.0" }
}'响应:
{
"ret": 0,
"msgs": [
{
"message_id": 1234567890,
"from_user_id": "xyz789uvw012@im.wechat",
"to_user_id": "abc123def456@im.bot",
"create_time_ms": 1711756800000,
"item_list": [
{
"type": 1,
"msg_id": "1234567890",
"text_item": { "text": "你好" }
}
],
"context_token": "xxx"
}
],
"get_updates_buf": "base64_encoded_buffer"
}使用方式:
- 首次请求
get_updates_buf为空字符串"" - 保存响应中的
get_updates_buf - 下次请求带上这个 buf(用于增量同步)
- 无消息时会阻塞 30 秒,有消息立即返回
- 收到消息后保存
context_token,用于回复
错误处理:
// 会话超时(需要重新注册)
{ "ret": -1, "errcode": -14, "errmsg": "session timeout" }API 端点: POST /ilink/bot/sendmessage
请求示例:
curl -X POST "https://ilinkai.weixin.qq.com/ilink/bot/sendmessage" \
-H "Content-Type: application/json" \
-H "AuthorizationType: ilink_bot_token" \
-H "Authorization: Bearer abc123def456@im.bot:0123456789abcdef0123456789abcdef" \
-H "iLink-App-Id: bot" \
-H "iLink-App-ClientVersion: 65536" \
-d '{
"msg": {
"message_id": 1711756800000,
"from_user_id": "",
"to_user_id": "xyz789uvw012@im.wechat",
"client_id": "cli_1711756800000_abc123",
"create_time_ms": 1711756800000,
"message_type": 2,
"message_state": 2,
"item_list": [
{
"type": 1,
"msg_id": "1711756800000",
"text_item": { "text": "你好" }
}
],
"context_token": "xxx"
},
"base_info": { "channel_version": "1.0.0" }
}'响应:
{
"ret": 0
}关键字段说明:
| 字段 | 说明 |
|---|---|
message_id |
消息 ID(时间戳) |
client_id |
客户端生成的唯一 ID |
to_user_id |
接收者用户 ID(从收到的消息中获取) |
message_type |
2 = BOT 消息 |
message_state |
2 = 完成状态 |
context_token |
从该用户收到的消息中获取(重要!) |
注意: context_token 必须从收到的消息中获取并发回,否则消息可能无法送达。
基于微信 iLink Bot API:
| 端点 | 用途 |
|---|---|
ilink/bot/get_bot_qrcode |
获取注册二维码 |
ilink/bot/get_qrcode_status |
轮询扫码状态 |
ilink/bot/getupdates |
长轮询获取消息(30s 超时) |
ilink/bot/sendmessage |
发送消息 |
Content-Type: application/json
AuthorizationType: ilink_bot_token
Authorization: Bearer <botToken>
iLink-App-Id: bot
iLink-App-ClientVersion: <版本号>
X-WECHAT-UIN: <随机base64>
weixin-cli/
├── package.json
├── tsconfig.json
├── src/
│ ├── api.ts # HTTP API 封装
│ ├── auth.ts # 扫码注册逻辑
│ ├── storage.ts # 凭证持久化
│ ├── cli.ts # 命令行入口
│ ├── monitor.ts # 消息监听(listen 命令)
│ └── interactive.ts # 交互模式(chat 命令)
├── dist/ # 编译输出
└── README.md
# 开发模式(自动重新编译)
npm run dev
# 类型检查
npx tsc --noEmitMIT