LiveAgent
Your Local-First AI Agent Desktop
多模型接入 · 本地工具执行 · MCP & Skills 生态 · 远程 Gateway
English | 简体中文
核心能力 •
下载与部署 •
FAQ •
文档
---
## 🌟 特别鸣谢
学AI，上L站！祝小破站越来越好～
---
## ❤️ 赞助商
 |
PackyCode 是一家稳定、高效、专业的API中转服务商，提供 Claude Code、Codex、Gemini，国模 等多种中转服务，老牌顶级中转，开发本软件用的绝大多数模型资源都是PackyCode提供，感谢老农！从 此处 注册并开始使用！ |
 |
Right Code 提供稳定的 Claude Code、Codex、Gemini，国模 等模型的中转服务。充值即可开票，企业、团队用户一对一对接。开发本软件用的另一部分模型资源都是RightCode提供，感谢RC站长，感谢小客服！ 从 此处 注册并开始使用！ |
 |
Cubence 是一家可靠高效的 API 中转服务商，提供 Claude Code、Codex、Gemini 等多种模型的中转服务，支持按量付费的计费方式。感谢 Cubence 对本项目的支持！从 此处 注册并开始使用！ |
---
## 🤝 一起来开发吧！
欢迎扫码进群，一起推进 LiveAgent 的开发！
（至于为什么是QQ群，感觉功能比微信群多一些～）
---
## 为什么是 LiveAgent?
LiveAgent 是一个 **本地优先** 的 AI Agent 桌面客户端。它将大语言模型的推理能力与本地系统工具深度整合,让 AI 能够真正操作你的文件系统、执行命令、管理定时任务,同时通过 Gateway 实现远程访问与协作。
- **真正动手的 Agent** — 不止于对话:读写文件、精确编辑、执行 Bash、托管长驻进程
- **生态完全开放** — MCP 协议桥接任意外部工具,Skills 技能包按需加载
- **本地与远程兼得** — 桌面端独立可用,部署 Gateway 后浏览器随处操控
---
## 核心能力
### 🧠 多模型与对话
- **多模型路由** — Claude(Anthropic)与 Codex(OpenAI)、Gemini 三协议,支持自定义 Base URL 接入第三方兼容服务
- **富文本渲染** — Markdown 流式渲染,内建 KaTeX 公式、Mermaid 图表与 Monaco 代码预览
- **历史压缩** — Segment + Summary Checkpoint 双层持久化,长对话不丢上下文
- **国际化** — 内建 i18n 多语言框架
### 🔧 本地工具执行
- **文件系统全能力** — `Read` / `Write` / `Edit` / `Delete` 精确读写,`Glob` / `Grep` 模式与正则搜索
- **Bash 与长驻进程** — 非交互式命令执行(cwd / timeout),`ManagedProcess` 托管 dev server 等常驻任务
- **Sub-Agent 委派** — 独立子代理并行执行,worktree 隔离,自动合并
- **隧道暴露** — `TunnelManager` 一键将本地服务暴露公网
### 🧩 MCP 与 Skills 生态
- **MCP 协议桥接** — Tauri 端原生桥接任意 stdio / http MCP Server,无限扩展工具能力
- **Skills 技能包** — 渐进式披露、按需加载,支持安装 / 创建 / 打包与 ClawHub 生态
### 💾 记忆与自动化
- **持久化记忆** — Markdown + SQLite FTS 全文检索,跨会话知识管理
- **定时任务** — bash / http / prompt 三种 Cron 任务类型,后台自动执行
### 🌐 远程 Gateway
- **浏览器随处访问** — Go 网关(WebSocket + Protobuf),WebUI 远程操控本地 Agent
- **断线可恢复** — 有界 seq window 补齐短时断线,桌面端持久化兜底
---
## 下载与部署
安装包由 GitHub Actions 自动构建、签名并发布,请前往 [**GitHub Releases**](https://github.com/Stack-Cairn/LiveAgent/releases/latest) 获取最新版本。
### 系统要求
| 平台 | 要求 |
|---|---|
| macOS | Intel(x64)与 Apple Silicon(aarch64)双架构 |
| Windows | x64,需 WebView2 运行时(Windows 11 已内置) |
| Linux | x86_64,需 WebKitGTK 4.1(Ubuntu 22.04+ / Debian 12+ 等) |
### macOS 用户
从 [Releases](https://github.com/Stack-Cairn/LiveAgent/releases/latest) 下载对应芯片的 DMG,打开后将 LiveAgent 拖入「应用程序」:
- Apple Silicon(M 系列):`LiveAgent-<版本>-macOS-aarch64.dmg`
- Intel:`LiveAgent-<版本>-macOS-x64.dmg`
> 安装包已签名并通过 Apple 公证,首次启动无需在安全设置中手动放行。
### Windows 用户
从 [Releases](https://github.com/Stack-Cairn/LiveAgent/releases/latest) 按需选择一种安装方式:
| 方式 | 文件 | 适合 |
|---|---|---|
| 安装向导 | `LiveAgent-<版本>-Windows-x64-Setup.exe` | 大多数用户 |
| MSI 包 | `LiveAgent-<版本>-Windows-x64.msi` | 企业分发 / 静默安装 |
| 便携版 | `LiveAgent-<版本>-Windows-x64-portable.zip` | 免安装,解压即用 |
### Linux 用户
从 [Releases](https://github.com/Stack-Cairn/LiveAgent/releases/latest) 按发行版选择:
| 格式 | 适用发行版 | 安装方式 |
|---|---|---|
| AppImage | 任意发行版 | `chmod +x` 后直接运行 |
| DEB | Debian / Ubuntu 系 | `sudo dpkg -i LiveAgent-<版本>-Linux-x86_64.deb` |
| RPM | Fedora / openSUSE 系 | `sudo rpm -i LiveAgent-<版本>-Linux-x86_64.rpm` |
### 需要远程访问? 部署 Gateway
桌面端开箱即用,不依赖任何服务端。只有想 **在浏览器里远程操控本地 Agent** 时,才需要部署 Gateway。
**注意：在部署并使用Nginx反向代理后，设置中Remote页面Gateway地址填写Https地址，端口号填写443。**
```bash
# 拉取镜像(GitHub Actions 自动构建,multi-arch: amd64 / arm64)
docker pull ghcr.io/stack-cairn/liveagent-gateway:latest
# 后台运行(HTTP/WebSocket → 宿主机 3000)
docker run -d \
--name liveagent-gateway \
--restart unless-stopped \
-p 3000:8080 \
-v liveagent-gateway-data:/var/lib/liveagent \
-e LIVEAGENT_GATEWAY_TOKEN=your-token \
ghcr.io/stack-cairn/liveagent-gateway:latest
```
命名卷用于持久化 Gateway 数据库和独立签发的 Agent Token，重建容器时不会丢失。
**一键升级到最新版** — 拉取新镜像 → 删除旧容器 → 以相同参数重建(若你修改过端口映射或 token,请同步替换下方参数):
```bash
docker pull ghcr.io/stack-cairn/liveagent-gateway:latest \
&& docker rm -f liveagent-gateway \
&& docker run -d \
--name liveagent-gateway \
--restart unless-stopped \
-p 3000:8080 \
-v liveagent-gateway-data:/var/lib/liveagent \
-e LIVEAGENT_GATEWAY_TOKEN=your-token \
ghcr.io/stack-cairn/liveagent-gateway:latest \
&& docker image prune -f
```
Nginx 反向代理配置 — 自建域名 / TLS 时参考
> 自 v2 协议起,WebUI、HTTP API 以及浏览器端和桌面端的 WebSocket 链路全部走同一个 HTTP 端口(默认 3000)。
>
> WebSocket 升级发生在多个路径上(`/ws/v2`、`/ws/v2/agent`、`/ws/v2/terminal`,以及 `/t/` 下的隧道),最省事且正确的做法是在整个 vhost 上启用升级:
```nginx
# WebUI SPA/静态资源/API + 全部 WebSocket 链路(浏览器端与桌面端)
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
# WebSocket 升级
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# 必须透传:Gateway 的同源校验会拿浏览器的 Origin 头
# 与 X-Forwarded-Proto + Host 做比对
proxy_set_header Host $host;
proxy_set_header Authorization $http_authorization;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# Gateway 每 15s 主动向每条 WebSocket 连接发 Ping,超时给足冗余即可
proxy_read_timeout 300s;
proxy_send_timeout 300s;
proxy_buffering off;
}
```
> 上游端口与上方 `docker run` 的宿主机映射对应:HTTP/WebSocket 3000(容器内 HTTP 实际监听 `PORT=8080`)。server 块需要 `listen 443 ssl;`,并把 `client_max_body_size` 调大到足够容纳附件上传(如 `100m`)。
### 从源码构建
展开下方「开发指南」查看完整 Make 命令。
架构总览 — 架构图与技术栈
```
┌──────────────────────────────────────────────────────────────┐
│ Browser WebUI │
│ React + Vite + WebSocket + Gateway API │
└────────────────────────────┬─────────────────────────────────┘
│ WebSocket / HTTP
┌────────────────────────────▼─────────────────────────────────┐
│ Agent Gateway │
│ Go · WebSocket · HTTP · Session Manager · Event Store │
│ (Railway / Docker / 自部署) │
└────────────────────────────┬─────────────────────────────────┘
│ WebSocket v2 (双向流)
┌────────────────────────────▼─────────────────────────────────┐
│ Agent GUI │
│ Tauri 2 · React 19 · Rust │
├──────────┬───────────┬───────────┬───────────┬───────────────┤
│ 模型协议 │ Agent运行时 │ 工具执行 │ Skills │ Memory/Cron │
│ pi-ai │ 多轮循环 │ FS/Bash/ │ 渐进披露 │ SQLite+MD │
│ + Codex │ + SubAgent │ MCP桥接 │ + Hub │ FTS索引 │
└──────────┴───────────┴───────────┴───────────┴───────────────┘
```
**技术栈**
| 组件 | 技术 |
|---|---|
| **Agent GUI** · 框架 | Tauri 2 + React 19 + TypeScript 6 |
| **Agent GUI** · 构建 | Vite 8 + pnpm |
| **Agent GUI** · 样式 | Tailwind CSS 4 + Radix UI |
| **Agent GUI** · 渲染 | streamdown + KaTeX + Mermaid + Monaco Editor |
| **Agent GUI** · 后端 | Rust + Tokio + SQLite (rusqlite) + WebSocket (tokio-tungstenite) |
| **Agent GUI** · LLM | @earendil-works/pi-ai · @earendil-works/pi-agent-core |
| **Gateway** · 语言 | Go 1.25 |
| **Gateway** · 协议 | WebSocket + Protobuf + HTTP |
| **Gateway** · Web UI | React + Vite + Tailwind CSS(嵌入式) |
| **Gateway** · 部署 | Docker multi-stage · Railway CI/CD |
开发指南 — 常用 Make 命令(完整列表见 make help)
| 命令 | 说明 |
|---|---|
| `make dev` | 启动 Tauri 开发环境并默认启用 Session Workbench（`DEV_SESSION_WORKBENCH=0` 可回退旧单会话布局） |
| `make build` | 构建桌面应用 |
| `make dev-gateway` | 启动 Gateway 开发服务 |
| `make dev-webui` | 启动 WebUI 开发服务 |
| `make gateway-build` | 构建 Gateway 二进制 |
| `make gateway-docker-build` | 构建 Docker 镜像 |
| `make gateway-docker-smoke` | 构建 + 健康检查 |
| `make desktop-build-macos-release` | macOS 签名发布构建 |
| `make build-linux` | Linux amd64 网关 |
| `make build-linux-arm` | Linux arm64 网关 |
| `make proto` | 重新生成 Protobuf 代码 |
| `make clean` | 清理构建产物 |
项目结构 — 目录树
```
LiveAgent/
├── package.json # pnpm workspace 命令
├── pnpm-lock.yaml # 统一前端依赖锁文件
├── crates/
│ ├── agent-ui/ # GUI/WebUI 共享 React 源码
│ │ └── src/ # 组件、领域模型、设置壳层
│ │
│ ├── agent-gui/ # 桌面客户端
│ │ ├── src/ # React 前端
│ │ │ ├── components/ # UI 组件
│ │ │ ├── lib/ # 核心逻辑 (chat, tools, skills, memory)
│ │ │ ├── pages/ # 页面 (Chat, Settings)
│ │ │ ├── i18n/ # 国际化
│ │ │ └── prompt/ # System Prompt 模板
│ │ └── src-tauri/ # Rust 后端 (Tauri)
│ │
│ └── agent-gateway/ # Go 网关服务
│ ├── cmd/gateway/ # 入口
│ ├── internal/ # 核心实现
│ ├── proto/v2/ # Protobuf 定义
│ └── web/ # 嵌入式 WebUI
│
├── docs/ # 项目文档
│ ├── architecture/ # 架构设计
│ ├── features/ # 功能说明
│ └── operations/ # 运维部署
│
├── scripts/release/ # 发布自动化
├── .github/workflows/ # CI/CD (CI + Desktop Release + Gateway Docker)
├── Dockerfile # Gateway 容器镜像
├── Makefile # 构建命令集
└── Cargo.toml # Rust workspace
```
---
## FAQ
API Key 会离开本机吗?
不会。秘钥仅保存在桌面端本地,Gateway 只做协议中继 — 不访问文件系统、不存储任何凭据。
必须部署 Gateway 吗?
不需要。桌面客户端可独立使用全部本地能力;只有需要从浏览器远程访问本地 Agent 时,才部署 Gateway。
支持哪些模型?
内置 Claude(Anthropic) 与 Codex(OpenAI)、Gemini 三协议,并支持自定义 Base URL 接入任何兼容的第三方服务。
长对话 / 断线后上下文会丢吗?
不会。桌面端以 Segment + Summary Checkpoint 持久化完整历史;Gateway 通过有界 seq window 补齐短时断线,重连后自动收敛。
---
## 贡献
欢迎提交 Issue 与 Pull Request!开发环境搭建请参考 [开发指南](docs/operations/development.md)。
提交 PR 前,请确保以下检查全部通过(与 CI 门禁一致):
先在仓库根目录执行一次 `pnpm install --frozen-lockfile` 安装前端依赖。
**桌面客户端**
1. 类型检查与构建通过:`pnpm build:gui`
2. 代码规范检查通过:`pnpm lint:ui && pnpm lint:gui`
3. 前端单元测试通过:`pnpm test:gui`(改动发布脚本时另跑 `pnpm --filter liveagent test:release`)
4. Rust 后端检查通过:`cargo check --manifest-path crates/agent-gui/src-tauri/Cargo.toml --tests`(仓库根目录执行)
**Gateway · `crates/agent-gateway`(如有改动)**
1. Go 单元测试通过:`go test ./...`
2. WebUI 构建 / Lint / 测试通过:`pnpm build:webui && pnpm lint:webui && pnpm test:webui`
3. Proto 变更后重新生成并提交产物:`make proto`
**共享 UI 边界**
- 共享源码不得直接依赖任一宿主:`pnpm check:ui-boundaries`
- 保持 diff 干净 (无行尾空白):`git diff --check`
---
## 👥 贡献者
感谢所有为 LiveAgent 做出贡献的朋友们！
---
## Star History
---
## License
MIT © StackCairn
