一个基于 icqq 协议的命令行 QQ 客户端，使用 React Ink 构建交互式终端 UI，支持消息收发、群管理、频道操作等丰富功能
凉菜
作者
@icqqjs/cli 是一个基于 icqq 协议库的命令行 QQ 客户端。它使用 React Ink 构建交互式终端 UI，让你无需打开图形界面，就能在终端中完成几乎所有 QQ 操作——从发送消息、管理好友群组，到频道交流、文件传输，一切尽在指尖。
作为开发者，终端是我们的主战场。在终端中操作 QQ 有着不可忽视的优势：
使用 npm 全局安装：
npm install -g @icqqjs/clinpm install -g @icqqjs/cliCLI 依赖 @icqqjs/icqq 协议库，首次使用需要安装。推荐使用一键安装命令：
# 自动配置 .npmrc + 安装 icqq
icqq setup# 自动配置 .npmrc + 安装 icqq
icqq setup如需手动安装，请先配置 npm scope 指向 GitHub Packages，然后安装 @icqqjs/icqq。
# 交互式登录，跟随向导完成配置
icqq login
# 快速重连（使用已保存的 token）
icqq login -r
# 指定账号快速重连
icqq login -q 12345 -r# 交互式登录，跟随向导完成配置
icqq login
# 快速重连（使用已保存的 token）
icqq login -r
# 指定账号快速重连
icqq login -q 12345 -r登录成功后，守护进程会在后台运行，保持你的 QQ 在线状态。
┌──────────────────────────────────────────────────────┐
│ icqq CLI │
│ ┌────────────┐ ┌────────────┐ ┌───────────────┐ │
│ │ Pastel │ │ React Ink │ │ IPC Client │ │
│ │ 文件路由 │─▸│ 终端 UI │ │ (ipc-client) │ │
│ └────────────┘ └────────────┘ └───────┬───────┘ │
└──────────────────────────────────────────┬───────────┘
│ Unix Socket
│ + Token 认证
┌──────────────────────────────────────────┴───────────┐
│ 守护进程 (Daemon) │
│ ┌────────────┐ ┌────────────┐ ┌───────────────┐ │
│ │ icqq │ │ IPC │ │ Webhook │ │
│ │ Client │◂─│ Server │─▸│ 推送 │ │
│ │ (QQ协议) │ │ (server) │ │ (HTTP POST) │ │
│ └─────┬──────┘ └────────────┘ └───────────────┘ │
└────────┼─────────────────────────────────────────────┘
│
▼
腾讯 QQ 服务器┌──────────────────────────────────────────────────────┐
│ icqq CLI │
│ ┌────────────┐ ┌────────────┐ ┌───────────────┐ │
│ │ Pastel │ │ React Ink │ │ IPC Client │ │
│ │ 文件路由 │─▸│ 终端 UI │ │ (ipc-client) │ │
│ └────────────┘ └────────────┘ └───────┬───────┘ │
└──────────────────────────────────────────┬───────────┘
│ Unix Socket
│ + Token 认证
┌──────────────────────────────────────────┴───────────┐
│ 守护进程 (Daemon) │
│ ┌────────────┐ ┌────────────┐ ┌───────────────┐ │
│ │ icqq │ │ IPC │ │ Webhook │ │
│ │ Client │◂─│ Server │─▸│ 推送 │ │
│ │ (QQ协议) │ │ (server) │ │ (HTTP POST) │ │
│ └─────┬──────┘ └────────────┘ └───────────────┘ │
└────────┼─────────────────────────────────────────────┘
│
▼
腾讯 QQ 服务器项目采用了优雅的分层架构：
src/commands/ 的目录结构就是命令结构，非常直观。React Ink 负责渲染终端 UI，带来类似 React 的组件化开发体验~/.icqq/<uin>/daemon.sock），首次连接需要 Token 认证，确保安全性# 给好友发消息
icqq friend send <qq> "你好！"
# 发送群消息
icqq group send <gid> "大家好！"
# 进入交互式聊天模式（好友/群）
icqq friend chat <qq>
icqq group chat <gid>
# 查看聊天记录
icqq friend chat history <qq>
icqq group chat history <gid># 给好友发消息
icqq friend send <qq> "你好！"
# 发送群消息
icqq group send <gid> "大家好！"
# 进入交互式聊天模式（好友/群）
icqq friend chat <qq>
icqq group chat <gid>
# 查看聊天记录
icqq friend chat history <qq>消息支持 CQ 码语法，可以发送富文本内容：
[face:id] 表情
[image:path] 图片
[at:uid] @某人
[at:all] @全体成员
[dice] 骰子
[rps] 猜拳[face:id] 表情
[image:path] 图片
[at:uid] @某人
[at:all] @全体成员
[dice] 骰子
[rps] 猜拳# 好友列表
icqq friend list
# 查看好友资料
icqq friend view <qq>
# 点赞、戳一戳
icqq friend like <qq>
icqq friend poke <qq>
# 好友分组管理
icqq friend class list
icqq friend class add <name>
# 文件传输
icqq friend send-file <qq> <file># 好友列表
icqq friend list
# 查看好友资料
icqq friend view <qq>
# 点赞、戳一戳
icqq friend like <qq>
icqq friend poke <qq>
# 好友分组管理
icqq friend class list
icqq friend class add <name>
# 文件传输
icqq friend send-file <qq> # 群列表和成员
icqq group list
icqq group member list <gid>
# 群管理操作
icqq group kick <gid> <qq> # 踢人
icqq group mute <gid> <qq> [duration] # 禁言
icqq group mute-all <gid> # 全体禁言
icqq group set admin <gid> <qq> # 设置管理员
icqq group set name <gid> <name> # 修改群名
# 群文件系统
icqq group fs list <gid> # 文件列表
icqq group fs upload <gid> <file> # 上传文件
icqq group fs mkdir <gid> <name> # 创建文件夹
# 群公告与签到
icqq group announce <gid> <content>
icqq group sign <gid># 群列表和成员
icqq group list
icqq group member list <gid>
# 群管理操作
icqq group kick <gid> <qq> # 踢人
icqq group mute <gid> <qq> [duration] # 禁言
icqq group mute-all <gid>
# 频道列表
icqq guild list
# 子频道消息
icqq guild channel send <guild_id> <channel_id> <message>
# 进入子频道聊天模式
icqq guild channel chat <guild_id> <channel_id># 频道列表
icqq guild list
# 子频道消息
icqq guild channel send <guild_id> <channel_id> <message>
# 进入子频道聊天模式
icqq guild channel chat <guild_id> <channel_id># 查看所有守护进程状态
icqq status
# 切换当前操作账号
icqq switch [uin]
# 也可以通过参数或环境变量指定
icqq -u 12345 profile
ICQQ_CURRENT_UIN=12345 icqq friend list
# 配置管理
icqq config get
icqq config set <key> <value># 查看所有守护进程状态
icqq status
# 切换当前操作账号
icqq switch [uin]
# 也可以通过参数或环境变量指定
icqq -u 12345 profile
ICQQ_CURRENT_UIN=12345 icqq friend list
# 配置管理
icqq config get
icqq config set <key> <value># 个人设置
icqq set nickname <name> # 修改昵称
icqq set avatar <file> # 修改头像
icqq set online-status <status> # 修改在线状态
# Webhook 配置
icqq webhook set <url> # 设置推送地址
icqq webhook off # 关闭推送
# 实用工具
icqq ocr <file> # 图片文字识别
icqq convert uid <qq> # QQ 号转 UID
icqq completion [shell] # 生成 Shell 自动补全# 个人设置
icqq set nickname <name> # 修改昵称
icqq set avatar <file> # 修改头像
icqq set online-status <status> # 修改在线状态
# Webhook 配置
icqq webhook set <url> # 设置推送地址
| 技术 | 用途 |
|---|---|
| TypeScript | 主开发语言，类型安全 |
| React Ink | 终端 UI 渲染框架 |
| Pastel | 文件系统路由，命令即目录 |
| Zod | 参数校验 |
| icqq | QQ 协议实现 |
| Unix Socket + IPC | CLI 与守护进程通信 |
| tsdown | 构建工具 |
| Vitest | 测试框架 |
项目要求 Node.js >= 22，采用 ESM 模块系统，使用 pnpm 作为包管理器。
在服务器上部署 icqq CLI，配合 Webhook 或脚本实现自动消息通知：
# 部署完成后发送通知
icqq group send <gid> "🚀 v2.0.0 部署完成！"
# 配合 Webhook 接收消息事件
icqq webhook set https://your-server.com/webhook# 部署完成后发送通知
icqq group send <gid> "🚀 v2.0.0 部署完成！"
# 配合 Webhook 接收消息事件
icqq webhook set https://your-server.com/webhook编写 Shell 脚本批量处理群管理任务：
#!/bin/bash
# 批量禁言违规用户
for qq in 111 222 333; do
icqq group mute <gid> $qq 3600
done#!/bin/bash
# 批量禁言违规用户
for qq in 111 222 333; do
icqq group mute <gid> $qq 3600
done开发 QQ 机器人时，通过 CLI 快速测试消息收发：
# 快速发送测试消息
icqq friend send <qq> "测试消息"
# 查看消息详情
icqq msg get <msgid># 快速发送测试消息
icqq friend send <qq> "测试消息"
# 查看消息详情
icqq msg get <msgid>对于终端重度用户来说，icqq CLI 就是你的日常 QQ 客户端：
# 进入群聊天模式，实时收发消息
icqq group chat <gid>
# 查看好友请求并处理
icqq requests
icqq request accept <flag># 进入群聊天模式，实时收发消息
icqq group chat <gid>
# 查看好友请求并处理
icqq requests
icqq request accept <flag>如果你想参与开发或了解源码：
# 克隆并安装
git clone https://github.com/icqqjs/cli.git
cd cli
pnpm install
# 构建
pnpm build
# 本地全局注册
npm link
# 运行测试
pnpm test# 克隆并安装
git clone https://github.com/icqqjs/cli.git
cd cli
pnpm install
# 构建
pnpm build
# 本地全局注册
npm link
# 运行测试
pnpm test项目使用 release-please 管理版本发布，推送代码后 GitHub Actions 会自动创建 Version PR，合并后自动发布。
icqqjs/cli 目前已发布到 v1.4.3 版本，处于活跃开发状态。近期更新亮点：
@icqqjs/cli 为终端用户和开发者提供了一个功能完备的命令行 QQ 客户端。它的特点包括：
无论你是想在服务器上收发 QQ 消息、自动化群管理任务，还是单纯享受在终端中使用 QQ 的极客体验，@icqqjs/cli 都值得一试！
本文介绍的 @icqqjs/cli 项目由 icqqjs 组织开发维护，采用 ISC 许可证。如果这个项目对你有帮助，欢迎给项目点个 Star ⭐
Conversation
使用 GitHub 账号登录即可发表评论
登录后即可发表评论