根据 AQBot 的官方仓库，这是一款本地优先、跨平台的桌面 AI 工作台，集成了多服务商对话、AI Agent、知识库和 API 网关等功能。以下是基于其文档整理的部署与使用教程。

🧭 核心功能与定位

AQBot 是一个功能强大的 AI 客户端，旨在成为你桌面上的 AI 统一入口。它的核心能力包括：

  • 多模型对话中心：支持 OpenAI、Claude、Gemini、DeepSeek、Qwen 等任意 OpenAI 兼容 API，可在一处切换、对比不同模型。
  • 双轨 AI Agent：
    • 对话 Agent：在普通对话中切换至 Agent 模式，让模型能读取/编辑文件、执行命令（权限可控）。
    • ACP Agent 工作台：通过 Agent Client Protocol (ACP) 连接 Codex、Claude Agent 等外部编程 Agent，在独立工作目录中运行。
  • 本地知识库与搜索：支持联网搜索（Tavily、Exa 等）和本地文档索引（基于 sqlite-vec），可将文件、搜索结果附加到对话上下文。
  • API 网关：可将 AQBot 作为本地网关，向其他工具（如 Claude Code）暴露 OpenAI、Claude 等格式的 API 接口。
  • 数据本地化：应用数据存储在 ~/.aqbot/，用户文件在 ~/Documents/aqbot/，API Key 使用 AES-256 本地加密。

📦 安装与初始设置

1. 系统要求与下载

  • 支持平台：
    • macOS：Apple Silicon (arm64) 和 Intel (x86_64)
    • Windows 10/11：x86_64 和 arm64
    • Linux：x86_64 和 arm64 (提供 AppImage/deb/rpm)
  • 获取安装包：从项目的 Releases 页面 下载适合你系统的安装包（如 .dmg、.exe、.AppImage）。

2. 安装与权限

  • 像安装普通桌面软件一样安装。
  • macOS 用户注意：由于应用使用自签名证书，首次打开可能会被系统拦截。解决方法：在 Finder 中按住 Control 键点击应用图标，选择“打开”，然后在弹出的对话框中再次确认打开。如仍被拦截，需前往“系统设置 → 隐私与安全性”中手动允许。

🚀 快速开始与核心功能使用

1. 配置 AI 服务商

  1. 启动 AQBot，进入设置或服务商管理界面。
  2. 点击“添加服务商”，选择提供商（如 OpenAI）或“自定义 OpenAI 兼容”。
  3. 填写 API Key、Base URL（如有需要）和模型名称。
  4. （可选）点击“同步模型”以获取模型列表，并进行分组和延迟测试。
  5. 快速导入：支持通过 aqbot:// 链接或 CC Switch 配置一键导入服务商。

2. 对话与模型使用

  • 新建对话：在主界面新建对话，在顶部选择已配置的服务商和模型。
  • 高级对话功能：支持流式回复、思考块显示、消息多版本、对话分支以及多模型并行回答（同时向多个模型提问并对比结果）。
  • 角色（System Prompt）：可将常用的系统提示词保存为“角色”，并一键应用到新对话中。也可从在线角色市场（prompts.chat 等来源）搜索安装。

3. 使用 AI Agent（两种方式）

  • 方式一：对话内 Agent：
    1. 在任意对话中，开启“Agent 模式”。
    2. 设置权限模式（“每次询问”、“自动接受编辑”或“完全访问”）。
    3. AQBot 会让模型在你的指定工作目录中执行命令、读写文件，并实时展示工具调用过程。
  • 方式二：ACP Agent 工作台（推荐用于编程任务）：
    1. 进入 ACP Agent 工作台。
    2. 从 ACP Registry 添加外部 Agent，如 Codex、Claude Agent、Gemini CLI 等（也可自定义命令）。
    3. 为 Agent 关联一个本地项目目录，开始独立会话。Agent 的所有操作（文件编辑、命令执行）都会在此目录内隔离进行。
    4. 支持工具调用审批、计划审核和会话恢复。

4. 扩展功能

  • 知识库：在“知识库”模块中，添加本地文档（PDF、TXT 等），AQBot 会为其建立向量索引。在对话中可引用知识库内容。
  • MCP 工具：配置 MCP (Model Context Protocol) 服务器，让模型能调用外部工具（如 @aqbot/fetch 网页抓取工具）。
  • API 网关：在“网关”模块中启用本地服务，可为其他 AI 工具（如 Claude Code）提供兼容的 API 端点，方便统一管理和监控用量。

⚙️ 高级配置与管理

  • 数据导入与备份：支持导入 ChatGPT、Cherry Studio 和 Kelivo 的导出数据，并通过本地目录、WebDAV 或 S3 进行备份与恢复。
  • 技能（Skills）管理：可管理 AQBot 及 Codex、Claude 等工具的技能目录，支持从 GitHub 或 skills.sh 市场安装技能组。
  • 桌面集成：支持系统托盘、窗口置顶、全局快捷键、开机自启和代理设置。

❓ 常见问题

  • macOS 提示“已损坏”或“无法验证开发者”：如前所述，这并非应用真的损坏。请在 Finder 中按住 Control 键点击应用，选择“打开”，并确认打开。对于划词工具栏等额外功能，还需在“系统设置 → 隐私与安全性 → 辅助功能”中授予权限。
  • API 连接失败：检查 API Key、Base URL 和网络代理设置。可在服务商配置页面使用“测试”功能验证连接。
  • ACP Agent 无法启动：确保已安装对应的外部 Agent CLI（如 Codex、Gemini CLI），并且其路径在系统 PATH 环境变量中。检查 ACP Agent 配置中的命令和参数是否正确。

总结

AQBot 提供了一个强大且统一的桌面 AI 工作台，其核心优势在于本地数据优先和集成了丰富的 AI 生态（多模型、双 Agent 模式、MCP、API 网关）。对于新手，建议从安装后配置一个 OpenAI 兼容服务商开始，体验其对话和角色功能。如果你是开发者或需要自动化任务，可以深入探索其 ACP Agent 工作台，它能让你在隔离环境中安全地运行编程 Agent。所有高级功能（知识库、网关、MCP）都可通过直观的界面进行配置，使得 AQBot 成为一个潜力巨大的个人 AI 控制中心。