# 快速开始

本指南将帮助你在几分钟内完成 AQBot 的安装、配置和首次对话。

## 安装

前往 [下载页面](/zh/download) 获取最新安装包，选择与你系统匹配的版本。

### macOS

AQBot 提供两种架构的 `.dmg` 安装包：

- **Apple Silicon**（M1/M2/M3/M4）— `AQBot_x.x.x_aarch64.dmg`
- **Intel** — `AQBot_x.x.x_x64.dmg`

下载后双击 `.dmg` 文件，将 AQBot 拖入「应用程序」文件夹即可。

> **macOS 安全提示**
>
> AQBot 使用项目自签名的代码签名证书，而非 Apple Developer ID 证书，因此从浏览器下载后，macOS 仍可能提示 **"AQBot 已损坏，无法打开"** 或 **"无法打开 AQBot，因为无法验证开发者"**。
>
> 无需关闭整个系统的 Gatekeeper，只需放行 AQBot：
>
> 1. 在 Finder 中按住 Control 点击 `AQBot.app`，选择「打开」，然后再次点击「打开」。
> 2. 如果仍被拦截，前往「系统设置 → 隐私与安全性」，在「安全性」区域找到 AQBot 并点击「仍要打开」。
> 3. 再次启动 AQBot。
>
> Gatekeeper 放行与辅助功能授权是两项独立设置。使用划词工具栏时，还需根据应用内提示，在「系统设置 → 隐私与安全性 → 辅助功能」中启用 AQBot。

### Windows

- **x64** — `AQBot_x.x.x_x64-setup.exe`
- **ARM64** — `AQBot_x.x.x_arm64-setup.exe`

双击安装程序并按照向导完成安装。系统要求 Windows 10（1803）或更高版本。

### Linux

根据你的发行版和架构选择：

| 格式 | 架构 | 适用场景 |
|------|------|---------|
| `.deb` | amd64 / arm64 | Debian、Ubuntu 及其衍生版 |
| `.rpm` | x86_64 / aarch64 | Fedora、openSUSE 等 |
| `.AppImage` | x86_64 / aarch64 | 任意发行版，无需安装 |

`.deb` 安装示例：

```bash
sudo dpkg -i AQBot_x.x.x_amd64.deb
```

`.AppImage` 需要先赋予执行权限：

```bash
chmod +x AQBot_x.x.x_amd64.AppImage
./AQBot_x.x.x_amd64.AppImage
```

## 首次配置

安装完成后，按照以下步骤完成初始配置。

### 1. 进入设置

启动 AQBot 后，点击左侧边栏底部的齿轮图标进入 **设置** 页面。

### 2. 添加服务商

进入 **设置 → 服务商**，点击左下角的 **+** 按钮添加一个服务商。以 OpenAI 为例：

1. 输入服务商名称，如 `OpenAI`
2. 选择服务商类型为 **OpenAI**
3. 填入你的 **API Key**
4. **Base URL** 保持默认 `https://api.openai.com`，若使用第三方中转服务则填写其地址

> **获取 API Key**
>
> 前往 [OpenAI API Keys](https://platform.openai.com/api-keys) 页面创建密钥。其他服务商的密钥获取方式请参考各自官方文档。

### 3. 获取模型

服务商添加完成后，点击 **获取模型** 按钮，AQBot 会自动从 API 拉取可用模型列表。你也可以在模型 ID 输入框中手动添加模型。

### 4. 配置默认模型

进入 **设置 → 默认模型**，选择你最常用的模型作为默认助手模型和话题命名模型。新建对话时将自动使用默认模型。

## 开始第一次对话

### 新建对话

点击左侧边栏顶部的 **新建对话** 按钮，或使用快捷键 `Cmd/Ctrl+N`。

### 选择模型

在对话顶部的模型选择器中选取你想使用的模型。如果你已经设置了默认模型，会自动填充。

### 发送消息

在底部输入框中输入你的问题，按 `Enter` 发送。AQBot 使用流式输出，你会看到模型的回答逐字呈现。

> **关于 Thinking 块**
>
> 部分模型（如 Claude、DeepSeek R1）支持输出推理过程。当模型包含 thinking 块时，AQBot 会将其折叠显示，点击即可展开查看完整推理链。

## 核心概念

### 对话分支

AQBot 支持对话分支功能。当你在某条消息基础上重新生成或编辑提问时，系统会创建一个新的分支而非覆盖原内容。你可以随时在不同分支之间切换，对比不同的对话走向。

### 消息版本

每条消息可以拥有多个版本。重新生成助手回复时，新版本会自动添加到同一消息位置。通过消息旁的左右箭头可以在版本间快速切换。

### 上下文挂载

在对话中，你可以通过附件功能挂载额外的上下文信息：

- **文件** — 上传图片或文档作为对话上下文
- **搜索** — 关联本地知识库搜索结果
- **工具** — 启用 MCP 工具让模型调用外部能力
- **终端** — 切换到 Agent 模式后，模型可以在起始工作目录中执行非交互命令；该目录不是沙箱，每条执行类调用默认需要允许一次或拒绝

## 快捷键

AQBot 内置了一套常用快捷键，提升操作效率：

| 快捷键 | 功能 |
|-------|------|
| `CmdOrCtrl+Shift+A` | 显示/隐藏当前窗口 |
| `CmdOrCtrl+Shift+Z` | 显示/隐藏所有窗口 |
| `Cmd/Ctrl+N` | 新建对话 |
| `Cmd/Ctrl+,` | 打开设置 |
| `Cmd/Ctrl+F` | 搜索对话 |

> **自定义快捷键**
>
> 以上快捷键均可在 **设置 → 快捷键** 中自定义修改，包括全局快捷键和应用内快捷键。

## 桌面设置

在 **设置** 中可以调整各项桌面偏好：

### 外观

- **主题** — 支持深色、浅色和跟随系统三种模式
- **主题色** — 从 12 种预设色中选择，也支持自定义颜色
- **字体** — 可调整字体大小（12–20px）、字重和字体家族

### 语言

支持 简体中文、繁體中文、English、日本語、한국어、Français、Deutsch、Español、Русский、हिन्दी、العربية 共 11 种界面语言，在 **设置 → 通用** 中切换。

### 系统行为

- **系统托盘** — 关闭窗口后保持在系统托盘运行
- **开机自启** — 设置系统登录时自动启动 AQBot
- **窗口置顶** — 将 AQBot 窗口始终置于最前

### 代理配置

如果你需要通过代理访问 API，在 **设置 → 代理** 中配置：

- **代理类型** — 支持 HTTP 和 SOCKS5
- **代理地址** — 代理服务器的 IP 或域名
- **代理端口** — 默认为 7890

配置完成后可以点击 **测试** 按钮验证连通性，会显示延迟结果。

## 数据与备份

### 数据目录

AQBot 使用两个目录分别存储不同类型的数据：

| 目录 | 用途 |
|------|------|
| `~/.aqbot/` | 应用状态：数据库、加密密钥、向量数据库、SSL 证书 |
| `~/Documents/aqbot/` | 用户文件：图片、文档附件、备份 |

### 自动备份

在 **设置 → 备份** 中开启自动备份。支持三种备份目标：

- **本地** — 默认保存到 `~/Documents/aqbot/backups/`
- **WebDAV** — 同步到支持 WebDAV 的网盘（如坚果云）

可配置备份间隔（小时）和保留的最大备份数量。

### 手动备份与恢复

随时可以通过 **设置 → 备份** 手动触发完整备份。恢复时选择备份文件即可还原所有数据。

### 对话导出

在对话页面中，可以将当前对话导出为多种格式：

- **PNG** — 长图截图，适合分享
- **Markdown** — 结构化文本，方便二次编辑
- **纯文本** — 简洁格式
- **JSON** — 包含完整元数据，方便程序处理

## 下一步

基础配置完成后，你可以继续探索 AQBot 的进阶功能：

- [配置服务商](./providers) — 多服务商、多密钥、自定义端点
- [MCP 服务器](./mcp) — 连接外部工具扩展 AI 能力
- [API 网关](./gateway) — 将 AQBot 作为 API 代理服务器