---
title: "CLI"
weight: 21
---

# CLI 渠道

CLI 是 xbot 的默认渠道，一个功能完整的终端 UI（TUI），基于 [Bubble Tea](https://github.com/charmbracelet/bubbletea) 构建。

## 两种模式

### Standalone 模式（本地）

CLI 直接在本地运行 Agent，所有处理都在你的电脑上完成。

```bash
xbot-cli                # 启动交互式 TUI
xbot-cli "你的问题"      # 一次性问答
echo "问题" | xbot-cli   # 管道模式
```

### Remote 模式（远程）

CLI 通过 WebSocket 连接到 Server，Agent 运行在服务端。

```bash
# 使用安装器自动配置的连接
xbot-cli

# 手动指定 Server 地址
xbot-cli --server ws://your-server:8082
```

Remote 模式下，你的 CLI 和其他用户的 CLI / 飞书 / Web 共享同一个 Agent 实例。

## Setup 向导

首次运行会自动弹出配置向导。也可以随时输入 `/setup` 重新配置。

> ⚠️ **输入框操作技巧**：用方向键选中输入框 → 按 **Enter** 进入编辑模式 → 此时才能输入内容 → 再按 **Enter** 确认。直接打字是不会生效的。

## 常用命令

在 TUI 中输入以下斜杠命令：

| 命令 | 说明 |
|------|------|
| `/setup` | 重新运行配置向导 |
| `/settings` | 打开设置面板（沙箱模式、记忆模式等） |
| `/channel` | **频道配置面板** — 可视化配置 Web/飞书/QQ/NapCat 频道 |
| `/model` | 查看/切换当前 LLM 模型 |
| `/models` | 列出可用的模型 |
| `/new` | 开始新对话 |
| `/rewind` | 回退对话 |
| `/clear` | 清空对话和记忆 |

## 主题

CLI 支持 9 种配色方案，在 Setup 向导或 `/settings` 中切换：

`midnight` · `dracula` · `catppuccin` · `nord` · `gruvbox` · `tokyo` · `rose` · `rosepine` · `default`

## 键盘快捷键

### 主界面

| 快捷键 | 说明 |
|--------|------|
| `Enter` | 发送消息（或在输入框中进入/确认编辑） |
| `Ctrl+C` | 取消当前生成 |
| `Ctrl+D` | 退出 |
| `Ctrl+K` | 打开命令面板 |
| `Ctrl+P` | 快速切换订阅 |
| `Ctrl+T` | 打开会话面板 |
| `Ctrl+N` | 切换模型 (Next model) |
| `Ctrl+E` | 展开/折叠长消息 |
| `Ctrl+O` | 展开/折叠工具摘要 |
| `Ctrl+J` | 输入换行 |
| `↑` / `↓` | 浏览历史消息 |
| `Tab` | 补全斜杠命令 |
| `^` | 打开后台任务面板（有运行中任务时可用） |
| `/` | 开始输入斜杠命令 |

### 面板通用操作

| 快捷键 | 说明 |
|--------|------|
| `↑` / `↓` | 导航选项 |
| `Enter` | 选择/确认 |
| `Esc` | 关闭面板 / 返回上级面板 |
| `Ctrl+C` | 强制关闭面板 |
| `鼠标滚轮` | 滚动面板内容 |

### 设置面板（Settings）

| 快捷键 | 说明 |
|--------|------|
| `Enter` | 编辑选中项（开关 toggle / 下拉 combo / 文本输入） |
| `Ctrl+S` | 保存设置 |
| `Esc` | 关闭面板 |
| `Space` | 在 combo 下拉中切换到自定义输入 |

设置面板内可进入子面板（Runner 配置、危险区域），按 `Esc` 返回设置面板。

### 面板导航栈

面板支持 push/pop 导航。从面板 A 进入面板 B 后，按 `Esc` 会返回面板 A 而非直接关闭：

```
Settings → Runner 配置（Esc → 返回 Settings）
Settings → 危险区域（Esc → 返回 Settings）
```

## 鼠标操作

CLI 支持鼠标交互：

| 操作 | 说明 |
|------|------|
| **鼠标点击** | 点击选项、按钮、toggle 开关 |
| **鼠标滚轮** | 滚动面板内容或聊天历史 |
| **点击输入框** | 聚焦到文本输入区域 |

在 AskUser 面板中，鼠标滚轮会根据位置自动路由：
- 在上方聊天区域滚动 → 浏览历史消息
- 在下方问答区域滚动 → 滚动问答内容

## Agent 交互面板

当 Agent 需要用户输入时，会弹出 **AskUser 分屏面板**：

```
┌─ 聊天历史（可滚动）───────────────────────┐
│ ... 历史消息 ...                           │
├─ 问答面板 ──────────────────────────────┤
│ ❓ 请选择你需要的选项：                     │
│                                            │
│   ☑ 选项 A                                 │
│   ☐ 选项 B                                 │
│   ☐ 选项 C                                 │
│   ▸ Other: [自定义输入________]             │
│   ▸ [Submit]                               │
└────────────────────────────────────────────┘
```

### AskUser 操作

| 快捷键 | 说明 |
|--------|------|
| `↑` / `↓` | 在选项间移动光标 |
| `Space` | 勾选/取消 checkbox |
| `Enter` | 切换 checkbox / 提交（在 Submit 按钮上） |
| `←→` / `Tab` | 切换问题标签（多问题时） |
| `Ctrl+S` | 直接提交 |
| `Esc` | 取消 |
| `鼠标滚轮` | 滚动问答内容 |
| `Shift+↑↓` | 滚动上方聊天历史 |

标题栏始终显示当前可用的操作提示，底部显示滚动进度。光标到达选项边界时会自动滚动面板内容。

## 后台任务面板

当有后台任务运行时，按 `^`（caret 键）打开后台任务面板：

| 快捷键 | 说明 |
|--------|------|
| `↑↓` | 选择任务 |
| `Enter` | 查看任务日志 |
| `Del` | 终止任务 |
| `Esc` | 返回列表 / 关闭面板 |

## 会话面板（Ctrl+T）

管理多个对话会话：

| 快捷键 | 说明 |
|--------|------|
| `↑↓` | 选择会话 |
| `Enter` | 切换到该会话 / 查看消息预览 |
| `Del` | 删除会话（需确认） |
| `Esc` | 返回列表 / 关闭面板 |

## 进度显示

Agent 处理过程中，TUI 会实时显示：

- **思考状态**：推理/沉思中的动态指示
- **工具调用**：每个工具的执行状态和结果摘要
- **迭代进度**：当前迭代编号和已完成工具
- **流式输出**：逐字显示 Agent 回复

用 `Ctrl+O` 展开/折叠工具执行摘要，`Ctrl+E` 展开/折叠长消息。

## 底部提示栏

TUI 底部始终显示当前上下文最相关的快捷键提示，根据状态动态变化：
- **空闲态**：命令面板、补全、订阅切换等
- **处理中**：取消操作
- **面板内**：面板特有的操作提示（如设置面板的 Ctrl+S 保存）

底部 hint 栏可点击（鼠标支持），提供 `/session`、`Ctrl+K`、`Ctrl+N` 等快捷入口。

## AI-Native 配置能力

xbot 的 Agent 可以通过内置工具自行调整 TUI 配置和界面：

| 工具 | 能力 |
|------|------|
| `config` | AI 自助读写 xbot 配置（主题、布局、订阅等），运行时自动生效 |
| `tui_control` | AI 自助操作 TUI：切换/关闭会话、调整侧边栏宽度、切换主题、发送 slash 命令 |

典型场景：用户说「帮我把主题换成 dracula，侧边栏收窄一点」→ Agent 调用 `config set theme dracula` + `tui_control set_layout sidebar_width 25` → 界面即时变化。
