快速摘要
AionUi 是一个基于 Electron 构建的本地开源 AI 协作桌面平台，它把 Claude Code、Gemini CLI、Codex、Qwen Code、Goose CLI 等散落在终端里的 AI 命令行工具，统一收进了一个图形化界面。 你不再需要在多个终端窗口之间反复切换，也不用忍受命令行对话无法保存、不能并行多会话的痛苦。它支持 macOS、Windows、Linux 三大平台，数据全部存在本地 SQLite 数据库里，不会上传到任何云端服务器。截至目前，该项目在 GitHub 已获得超过 12K Star。往下看，莫潇羽@无忆研习社将从底层原理到安装配置，再到实际使用场景，为你做一次事无巨细的拆解。
这篇文章要解决什么问题
如果你是一个正在使用 AI 编程工具的开发者，或者你已经开始接触 Gemini CLI、Claude Code 这类命令行 AI 助手，你很可能遇到过这些烦恼：每次打开终端敲完一轮对话，关掉窗口就什么都没了；想同时让两个不同的 AI 模型处理不同的任务，却只能来回切换；文件操作全靠手动在文件管理器和终端之间跳来跳去……
AionUi 就是为了解决这些问题而生的。但它到底是怎么做到的？它的技术架构长什么样？普通用户如何从零开始安装和配置？这些问题，网上大多数文章只是一笔带过。
莫潇羽（无忆研习社 www.wuyi.wiki 站长）在这篇文章里，会把 AionUi 从里到外翻个底朝天。不管你是资深开发者还是刚入门的新手，读完这篇文章，你都能清楚地知道这个工具值不值得用、怎么用、以及它背后的技术逻辑是什么。
一、AionUi 到底是什么
1.1 一句话定义
AionUi 是一个免费、开源、本地优先的 AI 协作桌面应用程序。它的核心功能是为各种命令行 AI 智能体（Agent）提供一个统一的图形化操作界面。
如果你用过 Anthropic 官方推出的 Cowork（一个配合 Claude Code 使用的桌面协作工具），那么可以这样理解：AionUi 做的事情和 Cowork 类似，但它不绑定任何一家 AI 厂商，不锁定任何一个操作系统，而且完全开源。
1.2 它解决了命令行 AI 工具的哪些痛点
目前主流的 AI 编程助手，很多都是以命令行工具（CLI）的形态存在的。比如 Google 的 Gemini CLI、Anthropic 的 Claude Code、OpenAI 的 Codex CLI、阿里巴巴的 Qwen Code 等等。这些工具本身非常强大，但它们在日常使用中有一些共同的短板：
- 对话无法持久保存。 你和 AI 在终端里聊了很长一段对话，关掉终端窗口后，这些对话记录就丢失了。下次打开，一切从零开始。
- 只能单会话运行。 同一时间你只能和一个 AI 工具进行一轮对话。如果你想同时让 Claude Code 帮你重构后端代码，又想让 Gemini CLI 帮你生成前端文档，你需要打开两个终端窗口手动管理。
- 文件操作不直观。 在纯终端环境里查看文件、预览图片、浏览 Excel 表格，体验相当原始。
- 只支持单一模型。 每个 CLI 工具通常只能调用自家的模型。你没办法在同一个工作流里灵活切换不同厂商的 AI。
AionUi 的做法是：在这些命令行工具的上面"盖一层楼"——一个统一的图形化界面。命令行工具继续在底层干活，AionUi 负责把它们的输入输出呈现在一个友好的可视化面板里，同时补齐对话保存、多会话并行、文件预览等能力。
1.3 项目基本信息一览
|
项目属性 |
详情 |
|
项目名称 |
AionUi |
|
开源地址 |
|
|
官方网站 |
|
|
开发语言 |
TypeScript（基于 Electron） |
|
支持平台 |
macOS、Windows、Linux（甚至可通过 Termux 在 Android 上运行 WebUI 模式） |
|
数据存储 |
本地 SQLite 数据库 |
|
协议许可 |
开源免费 |
|
GitHub Star |
12K+（截至文章发布时） |
莫潇羽@无忆研习社 提示：AionUi 本身是免费开源的，但它调用的底层 AI 模型（如 OpenAI、Claude 等）可能需要你自己准备对应的 API Key。不过 Gemini CLI 的基础使用是免费的，对于入门用户来说，安装好就能直接体验。
二、技术架构深度解析
理解一个开源项目，最重要的是搞清楚它的架构设计。很多同类文章只告诉你"这个工具很好用"，却不讲它为什么好用、怎么实现的。莫潇羽在这里带你从代码层面看清楚 AionUi 的内部结构。
2.1 整体架构：Electron + 多进程模型
AionUi 基于 Electron 框架构建。如果你不熟悉 Electron，可以简单理解为：它是一种用 Web 技术（HTML、CSS、JavaScript/TypeScript）来开发桌面应用的技术方案。VS Code、Slack、Discord 这些大家熟悉的桌面应用，都是用 Electron 构建的。
选择 Electron 的好处很明显——一套代码就能同时跑在 macOS、Windows 和 Linux 上，大幅降低了跨平台开发的成本。
AionUi 的架构大致可以分为以下几个核心层：
┌──────────────────────────────────────────────────────┐
│ AionUi 整体架构 │
├──────────────────────────────────────────────────────┤
│ 渲染层（Renderer） │
│ ├── 对话界面（Conversation Page） │
│ ├── 设置管理（Settings Page） │
│ ├── 定时任务（Cron Page） │
│ ├── 可复用组件库（Components） │
│ ├── React Hooks & Context（全局状态管理） │
│ └── 国际化（i18n，支持中英日韩等多语言） │
├──────────────────────────────────────────────────────┤
│ 主进程层（Main Process） │
│ ├── SQLite 数据库操作（Database） │
│ ├── IPC 通信桥（Bridge，连接渲染层与主进程） │
│ ├── MCP 协议服务（多智能体协议支持） │
│ └── 定时任务调度（Cron Services） │
├──────────────────────────────────────────────────────┤
│ WebServer 层（用于远程访问） │
│ ├── HTTP 路由（Routes） │
│ ├── WebSocket 实时通信 │
│ └── 认证模块（Auth） │
├──────────────────────────────────────────────────────┤
│ Worker 层（后台任务处理） │
├──────────────────────────────────────────────────────┤
│ Channels 层（Agent 通信系统） │
│ └── 通过 ACP 协议与外部 CLI 工具通信 │
└──────────────────────────────────────────────────────┘从这个结构图可以看出，AionUi 不是一个简单的"套壳聊天界面"。它有完整的数据库层、通信层、后台任务处理层，以及用于远程访问的 Web 服务器层。每一层各司其职，组合起来形成了一个功能相当完备的桌面 AI 工作站。
2.2 两种核心运行模式
AionUi 内部有两种运行模式，理解这两种模式的区别，是用好这个工具的关键。
第一种：Gemini CLI 模式（内置模式）
这是 AionUi 的默认模式。安装好之后，它自带了 Gemini CLI 的集成，你不需要额外安装任何命令行工具，开箱即用。在这个模式下，AionUi 的功能最完整：支持图像生成、定时任务、MCP 协议扩展等所有内置能力。
你可以把它理解为 AionUi 的"满血版"——所有功能都是原生集成的，体验最流畅。
第二种：Multi-Agent 模式（多智能体模式）
这个模式才是 AionUi 真正让人兴奋的地方。在这个模式下，你可以把 Claude Code、Codex、Qwen Code、Goose CLI、Auggie 等外部命令行 AI 工具，全部接入 AionUi 的界面中。
但这些外部工具需要你自己提前安装好。AionUi 通过一个叫做 ACP（Agent Client Protocol） 的协议来识别和管理这些外部工具。关于 ACP 协议，下面会详细讲。
两种模式的对比：
|
对比维度 |
Gemini CLI 模式 |
Multi-Agent 模式 |
|
是否需要额外安装工具 |
不需要，开箱即用 |
需要自行安装对应 CLI 工具 |
|
支持的功能范围 |
完整（图像生成、定时任务等） |
取决于外部工具本身的能力 |
|
能否使用 AionUi 内置 LLM 配置 |
可以 |
暂时不能直接使用 |
|
适合谁 |
新手、轻度用户 |
重度开发者、多模型玩家 |
2.3 ACP 协议：让不同的 AI 智能体"说同一种语言"
ACP 是 Agent Client Protocol（智能体客户端协议）的缩写。它是一个开放的通信标准，目的是让不同的代码编辑器或客户端应用能够和不同的 AI 编程智能体（Agent）进行标准化的通信。
这个协议不是 AionUi 自己发明的，它是一个行业层面的开放协议。除了 AionUi，JetBrains IDE、Zed 编辑器、Neovim 插件等也都支持 ACP。
在 AionUi 的语境下，ACP 的工作方式可以这样理解：
用户在 AionUi 界面输入指令
↓
AionUi 通过 ACP 协议
将指令转发给对应的 CLI 工具
（比如 Claude Code）
↓
CLI 工具执行任务并返回结果
↓
AionUi 接收结果
并在图形界面中展示AionUi 会自动扫描你的系统环境，检测已安装的 CLI 工具（比如检测 PATH 中是否存在 claude、gemini、codex 等命令）。一旦检测到，它就会在界面上显示对应的 Agent 选项，你可以在对话时自由切换。
如果你有自己开发的符合 ACP 协议规范的自定义 Agent，也可以手动配置接入。
2.4 MCP 协议支持：扩展 AI 的能力边界
除了 ACP，AionUi 还支持 MCP（Model Context Protocol，模型上下文协议）。这是 Anthropic 主导推动的另一个开放标准。如果说 ACP 解决的是"AI 智能体和客户端之间怎么通信"的问题，那 MCP 解决的是"AI 助手怎么安全地调用外部工具和数据源"的问题。
通过 MCP，你可以为 AionUi 中的 AI 助手挂载各种外部能力。比如让 AI 能够查询数据库、读取 API 数据、调用特定的业务逻辑等等。MCP 在 AionUi 中扮演了"能力插件"的角色。
AI 助手 ←→ MCP 协议层 ←→ 外部工具/服务
├── 数据库查询
├── API 调用
├── 文件系统操作
└── 自定义业务逻辑AionUi 提供了专门的 MCP 配置界面，你可以在设置中添加、管理和测试各个 MCP 服务的连接状态。
2.5 本地数据存储：SQLite 方案
AionUi 的所有数据——对话记录、文件操作日志、配置信息——都存储在本地的 SQLite 数据库中。不会有任何数据被上传到云端服务器。
这个设计决策背后有明确的考量：
- 数据主权。 你的对话内容、代码片段、项目信息完全由你自己掌控。对于处理涉密项目或企业内部代码的开发者来说，这一点尤为重要。
- 离线可用。 即使断网，你仍然可以回顾之前的对话记录，查看之前的任务结果。
- 零运维成本。 不需要搭建数据库服务器，不需要管理云端存储，SQLite 是一个单文件数据库，安装即可用。
三、完整安装与配置指南
接下来是实操环节。莫潇羽（无忆研习社）在这里给出三种安装方式的详细步骤，覆盖从"完全不懂命令行"的新手到"什么都想自己编译"的老手。
3.1 方式一：直接下载安装包（推荐新手使用）
这是最简单的方式。AionUi 为三大平台都提供了预编译好的安装包。
操作步骤：
- 打开 AionUi 的 GitHub Releases 页面：https://github.com/iOfficeAI/AionUi/releases
- 根据你的操作系统选择对应的安装包下载：
- macOS 用户：选择
.dmg文件（macOS 还支持通过 Homebrew 安装，命令为brew install aionui） - Windows 用户：选择
.exe安装程序 - Linux 用户：选择
.deb（Debian/Ubuntu 系列）或.AppImage（通用格式） - 下载完成后，像安装普通软件一样双击安装即可
- 安装完成后启动 AionUi，你会看到欢迎界面。默认进入的是 Gemini CLI 模式，开箱即用
3.2 方式二：从源码编译安装（适合开发者）
如果你想研究源码，或者需要做一些定制化修改，可以从源码编译。
前置要求：
- 已安装 Node.js（建议 18.x 或更高版本）
- 已安装 npm 或 yarn
- 已安装 Git
操作步骤：
# 1. 克隆仓库
git clone https://github.com/iOfficeAI/AionUi.git
# 2. 进入项目目录
cd AionUi
# 3. 安装依赖
npm install
# 4. 启动开发模式
npm start执行 npm start 后，AionUi 的桌面窗口会自动弹出。此时你进入的是开发模式，代码修改后会自动热更新。
如果你想打包成正式的安装包，可以运行：
# 打包为当前平台的安装程序
npm run build3.3 方式三：WebUI 模式（服务器/远程访问/Android 设备）
AionUi 不仅可以作为桌面应用运行，还提供了 WebUI 模式——通过命令行启动后，你可以在任何浏览器中访问它。这种模式特别适合以下场景：
- 在远程服务器上部署，通过浏览器随时随地访问
- 在 Android 手机上通过 Termux 运行
- 在局域网内让多台设备共享一个 AionUi 实例
基本启动命令：
# 本机访问
AionUi --webui
# 局域网内其他设备也能访问
AionUi --webui --remote启动后，默认的访问端口是 25808。在浏览器中打开 http://localhost:25808（或者局域网 IP 地址加端口）即可使用。
在 Linux 服务器上设置为开机自启（systemd）：
[Unit]
Description=AionUi WebUI Service
After=network.target
[Service]
Type=simple
User=YOUR_USERNAME
ExecStart=/opt/AionUi/aionui --webui --remote
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target# 启用并启动服务
sudo systemctl daemon-reload
sudo systemctl enable aionui-webui.service
sudo systemctl start aionui-webui.service
# 检查运行状态
sudo systemctl status aionui-webui.service在 Android 设备上运行（通过 Termux）：
这个方案来自社区贡献者 @Manamama 的教程，已经过实际验证。需要注意的是，Android 上不支持 Electron 桌面模式，只能运行 WebUI 模式。
# 1. 安装 Termux（请从 F-Droid 下载，Google Play 版本已过时）
# 2. 在 Termux 中安装 proot 环境
pkg update -y
pkg install proot-distro -y
proot-distro install ubuntu
proot-distro login ubuntu
# 3. 在 Ubuntu 环境中安装依赖
apt update
apt install -y wget libgtk-3-0 libnss3 libasound2 libgbm1 libxshmfence1 ca-certificates
# 4. 下载并安装 AionUi（ARM64 版本）
wget https://github.com/iOfficeAI/AionUi/releases/download/v1.7.0/AionUi_1.7.0_arm64.deb
apt install -y ./AionUi_*.deb
# 5. 启动 WebUI 模式（注意 --no-sandbox 参数是 Termux 环境必须的）
AionUi --no-sandbox --webui启动成功后，在手机浏览器中访问 http://localhost:25808 就能使用了。
莫潇羽@无忆研习社 温馨提示：Android 上运行 AionUi 大约需要 5GB 的存储空间，而且对设备性能有一定要求。如果你的手机比较老旧，体验可能不太流畅。
四、首次使用完全攻略
安装好之后，第一次打开 AionUi，你需要做一些基础配置。这一节莫潇羽带你从零走完整个流程。
4.1 初始界面和默认模式
第一次启动 AionUi，你会看到一个简洁的欢迎界面。默认情况下，AionUi 工作在 Gemini CLI 模式——这是它的内置 Agent，下载即可用，不需要你额外安装任何命令行工具。
如果你之前已经在系统中安装了 Gemini CLI 并且登录过 Google 账号，AionUi 会自动检测并关联，你可以直接开始对话。
4.2 配置 AI 模型（LLM 配置）
AionUi 支持对接多个 AI 模型平台。进入配置的路径是：设置（Settings） → LLM 设置。
目前支持的平台包括：
- Google Gemini：内置支持，免费额度可用
- OpenAI：需要 API Key
- Anthropic Claude：需要 API Key
- 阿里云 Qwen：需要 API Key
- OpenRouter：一个聚合了多家模型的 API 平台，支持 Key 配置
- Ollama：本地大模型运行框架（完全离线）
- LM Studio：另一个流行的本地模型运行工具
如果你要连接本地模型（比如通过 Ollama 运行的模型），在模型平台中选择 Custom，然后设置 API 地址为本地端口，例如 http://localhost:11434/v1，即可连接。
AionUi 还支持为同一个平台配置多个 API Key，系统会自动轮换使用，这在有请求频率限制的情况下非常实用。
4.3 创建你的第一个对话
配置好模型后，回到主界面：
- 点击 "新建对话" 按钮，创建一个新的会话
- 在输入框中用自然语言告诉 AI 你想做什么
- AI 会在对话面板中回复你
每个会话都有独立的上下文记忆——也就是说，你可以同时开多个对话窗口，处理不同的任务，它们之间互不干扰。
4.4 关联工作目录
AionUi 的一个重要功能是工作目录关联。当你把一个文件夹关联到某个对话会话时，AI 就能"看到"这个文件夹里的文件，并对它们进行操作。
操作方式：
- 在对话输入框旁边，点击 "+" 按钮
- 在下拉菜单中选择 "打开文件夹"
- 选择你想让 AI 操作的项目目录
关联成功后，界面右侧会出现一个 "工作区" 面板，展示目录树结构。你可以在这里快速浏览和选择文件，直接添加到对话中。
需要注意的是：一旦会话关联了某个工作目录，在这个会话的生命周期内就不能修改了。如果需要操作另一个目录，请新建一个会话。
4.5 文件预览功能
AionUi 内置了支持 9 种以上格式的文件预览面板，这是它相比纯命令行工具的一大优势。支持的格式包括：
- 文本文件（.txt、.md）
- 代码文件（各种编程语言）
- 图片文件
- PDF 文档
- Word 文档（.docx）
- Excel 表格（.xlsx）
- PPT 演示文稿（.pptx）
- HTML 页面（可实时预览）
- Markdown（实时渲染预览）
当 AI 生成或修改了一个文件时，你可以直接在 AionUi 的预览面板中查看效果，不需要再打开另一个应用程序。
五、Multi-Agent 模式配置详解
前面说到，Multi-Agent 模式是 AionUi 的核心卖点之一。这一节，莫潇羽（无忆研习社）手把手教你如何配置。
5.1 前提条件
在启用 Multi-Agent 模式之前，你需要先在自己的电脑上安装对应的 CLI 工具。AionUi 本身不会帮你安装这些工具——它只负责检测和调用。
以下是目前 AionUi 支持的主要外部 Agent
