# RemoteCLI

**Repository Path**: gityyge/remote-cli

## Basic Information

- **Project Name**: RemoteCLI
- **Description**: 远程命令行
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RemoteCLI - QQ官方机器人远程命令行

通过手机QQ向你的QQ机器人发送消息，远程控制电脑执行命令行操作。

## 工作原理

```
手机QQ ──► 腾讯QQ服务器 ──► WebSocket ──► Spring Boot (本项目)
                                │
                    REST API (发送消息回复)
                                │
                    ┌───────────┼───────────┐
               CommandDispatcher  ShellExecutor
                    │                  │
               ShortcutResolver   ProcessBuilder
                    │
               FileService (文件获取)
```

- 使用**腾讯QQ开放平台官方API**（无需额外登录QQ号）
- WebSocket 长连接实时接收消息事件
- REST API 发送消息回复
- Spring Boot 3.2.5 + Java 17

## 快速开始

### 1. 创建QQ机器人

浏览器打开 https://q.qq.com/qqbot/openclaw/login.html ，用你的QQ扫码登录，点击创建机器人。

创建成功后你会获得 **AppID** 和 **AppSecret**。

### 2. 配置

编辑 `src/main/resources/application.yml`:

```yaml
bot:
  app-id: "你的AppID"
  app-secret: "你的AppSecret"
  owner-openid: ""  # 留空则自动绑定第一个发消息的人

cli:
  work-dir: C:/Users/Administrator/Desktop
  allowed-paths:
    - C:/
    - D:/
  command-timeout: 600
  max-line-length: 500
```

### 3. 启动

```bash
mvn spring-boot:run
```

或在 IDEA 中直接运行 `RemoteCliApplication.main()`。

启动后控制台显示:
```
access_token获取成功，有效期7200秒
WebSocket连接成功
鉴权成功！session_id=xxx, 机器人已就绪
```

### 4. 使用

在手机QQ上向你的机器人发送消息：

```
cmd                    # 进入命令行模式
dir                    # 查看当前目录
cd D:\projects         # 切换目录
gradlew.bat assembleDebug   # 打包APK（实时输出）
获取 app-debug.apk     # 获取打包好的文件
exit                   # 退出命令行模式
```

### 快捷指令

| 指令 | 实际命令 |
|------|----------|
| `切换目录 桌面` | cd Desktop |
| `切换目录 下载` | cd Downloads |
| `切换目录 文档` | cd Documents |
| `切换目录 项目` | cd Desktop |
| `查看目录` | dir |
| `当前目录` | pwd |
| `返回上级` | cd .. |
| `系统信息` | systeminfo |
| `任务列表` | tasklist |
| `网络配置` | ipconfig /all |

## 安全说明

- 只有 `bot.owner-openid` 对应的QQ用户能控制机器人
- 留空则自动绑定第一个发消息的人
- `cli.allowed-paths` 限制可访问的目录
- 命令超时机制防止进程僵尸

## 配置说明

### bot 配置

| 参数 | 说明 |
|------|------|
| `bot.app-id` | QQ机器人AppID |
| `bot.app-secret` | QQ机器人AppSecret |
| `bot.owner-openid` | 主人OpenID（留空自动绑定） |

### cli 配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `cli.work-dir` | 当前目录 | 初始工作目录 |
| `cli.allowed-paths` | 空(不限制) | 允许cd的路径白名单 |
| `cli.command-timeout` | 600 | 命令超时(秒) |
| `cli.max-line-length` | 500 | 消息最大字符数 |

## 项目结构

```
src/main/java/net/yyge/remote/cli/
├── RemoteCliApplication.java      # Spring Boot启动类
├── config/
│   ├── BotProperties.java         # Bot配置(AppID/AppSecret)
│   └── CliProperties.java         # CLI配置
├── bot/
│   └── QqBot.java                 # QQ Bot WebSocket + REST API
├── command/
│   ├── CommandDispatcher.java     # 命令分发器
│   ├── CommandSession.java        # 会话状态
│   └── ShortcutResolver.java      # 快捷指令
├── shell/
│   └── ShellExecutor.java         # 命令执行器
└── file/
    └── FileService.java           # 文件服务
```

## QQ Bot API 接口说明

本项目对接的是腾讯QQ开放平台官方API：

| 接口 | 说明 |
|------|------|
| `POST https://bots.qq.com/app/getAppAccessToken` | 获取access_token |
| `GET https://api.sgroup.qq.com/gateway/bot` | 获取WebSocket网关 |
| `wss://api.sgroup.qq.com/websocket/` | WebSocket长连接 |
| `POST /v2/users/{openid}/messages` | 发送私聊消息 |
| `POST /v2/groups/{group_openid}/messages` | 发送群聊消息 |

参考文档: https://bot.qq.com/wiki