LiveAgent

Your Local-First AI Agent Desktop
多模型接入 · 本地工具执行 · MCP & Skills 生态 · 远程 Gateway

English | 简体中文

🌟 特别鸣谢

学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 获取最新版本。

系统要求

平台	要求
macOS	Intel(x64)与 Apple Silicon(aarch64)双架构
Windows	x64,需 WebView2 运行时(Windows 11 已内置)
Linux	x86_64,需 WebKitGTK 4.1(Ubuntu 22.04+ / Debian 12+ 等)

macOS 用户

从 Releases 下载对应芯片的 DMG,打开后将 LiveAgent 拖入「应用程序」:

Apple Silicon(M 系列):LiveAgent-<版本>-macOS-aarch64.dmg
Intel:LiveAgent-<版本>-macOS-x64.dmg

安装包已签名并通过 Apple 公证,首次启动无需在安全设置中手动放行。

Windows 用户

从 Releases 按需选择一种安装方式:

方式	文件	适合
安装向导	`LiveAgent-<版本>-Windows-x64-Setup.exe`	大多数用户
MSI 包	`LiveAgent-<版本>-Windows-x64.msi`	企业分发 / 静默安装
便携版	`LiveAgent-<版本>-Windows-x64-portable.zip`	免安装,解压即用

Linux 用户

从 Releases 按发行版选择:

格式	适用发行版	安装方式
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。

# 拉取镜像(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,请同步替换下方参数):

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 上启用升级:

# 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 · @openai/codex-sdk · claude-agent-sdk
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 开发环境
`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/
├── crates/
│   ├── 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!开发环境搭建请参考开发指南。

提交 PR 前,请确保以下检查全部通过(与 CI 门禁一致):

桌面客户端 · crates/agent-gui

类型检查与构建通过:pnpm build
代码规范检查通过:pnpm lint
前端单元测试通过:pnpm test:frontend(改动发布脚本时另跑 pnpm test:release)
Rust 后端检查通过:cargo check --manifest-path crates/agent-gui/src-tauri/Cargo.toml --tests(仓库根目录执行)

Gateway · crates/agent-gateway(如有改动)

Go 单元测试通过:go test ./...
WebUI 构建 / Lint / 测试通过:pnpm build && pnpm lint && pnpm test(在 web/ 目录执行)
Proto 变更后重新生成并提交产物:make proto

跨端一致性

GUI 与 WebUI 的镜像文件必须逐字节一致:node scripts/check-mirror.mjs
保持 diff 干净 (无行尾空白):git diff --check

👥 贡献者

感谢所有为 LiveAgent 做出贡献的朋友们！

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

LiveAgent

🌟 特别鸣谢

❤️ 赞助商

🤝 一起来开发吧！

为什么是 LiveAgent?

核心能力

🧠 多模型与对话

🔧 本地工具执行

🧩 MCP 与 Skills 生态

💾 记忆与自动化

🌐 远程 Gateway

下载与部署

系统要求

macOS 用户

Windows 用户

Linux 用户

需要远程访问? 部署 Gateway

从源码构建

FAQ

贡献

👥 贡献者

Star History

License

FilesExpand file tree

README.zh-CN.md

Latest commit

History

README.zh-CN.md

File metadata and controls

LiveAgent

🌟 特别鸣谢

❤️ 赞助商

🤝 一起来开发吧！

为什么是 LiveAgent?

核心能力

🧠 多模型与对话

🔧 本地工具执行

🧩 MCP 与 Skills 生态

💾 记忆与自动化

🌐 远程 Gateway

下载与部署

系统要求

macOS 用户

Windows 用户

Linux 用户

需要远程访问? 部署 Gateway

从源码构建

FAQ

贡献

👥 贡献者

Star History

License