LiveAgent安装与远程Gateway部署教程：macOS、Windows、Linux三平台

LiveAgent 安装与 Gateway：这篇覆盖什么

LiveAgent 是本地优先的开源 AI Agent 桌面客户端（MIT 协议，GitHub star 约 2000，2026-09 查询为 2018），AI 在本机读写文件、执行命令、管理定时任务，可选部署 Go 编写的 Gateway 后从浏览器远程控制本地 Agent。本文覆盖 macOS、Windows、Linux 三平台安装、桌面端模型配置、Gateway 的 Docker 部署与远程访问原理、常见故障排查，机制与命令均出自官方 README。技术栈为 Tauri 2 + React 19 + Rust + Go 1.25。

想先了解项目定位与能力全景，看是什么篇；安装部分从这里继续。

系统要求：先核对你的平台

三平台的坑集中在运行时依赖：Windows 要 WebView2，Linux 要 WebKitGTK 4.1，macOS 基本零障碍——下载前先核对这张表。

平台	架构	运行时依赖
macOS	Intel（x64）与 Apple Silicon（aarch64）双架构	无额外依赖
Windows	x64	WebView2 运行时（Windows 11 自带）
Linux	x86_64	WebKitGTK 4.1（Ubuntu 22.04+ / Debian 12+ 等）

从 GitHub Releases 下载安装

所有安装包由 GitHub Actions 自动构建、签名并发布到 GitHub Releases（官方 README），按平台和芯片选文件即可，不必去第三方下载站。

macOS

去 Releases 页面按芯片下载对应 DMG，打开后把 LiveAgent 拖进 Applications：

• Apple Silicon（M 系列）：LiveAgent-<version>-macOS-aarch64.dmg
• Intel：LiveAgent-<version>-macOS-x64.dmg

安装包已由 Apple 签名并公证，首次启动不需要手动放行安全设置（README）。

Windows

三种安装形态按场景选（README）：

形态	文件	适合谁
安装向导	LiveAgent-<version>-Windows-x64-Setup.exe	大多数用户
MSI 包	LiveAgent-<version>-Windows-x64.msi	企业分发、静默安装
便携版	LiveAgent-<version>-Windows-x64-portable.zip	免安装，解压即用

Linux

格式	适用发行版	安装方式
AppImage	任意发行版	chmod +x 后直接运行
DEB	Debian / Ubuntu 系	sudo dpkg -i 安装
RPM	Fedora / openSUSE 系	sudo rpm -i 安装

# Debian / Ubuntu 系
sudo dpkg -i LiveAgent-<version>-Linux-x86_64.deb
# Fedora / openSUSE 系
sudo rpm -i LiveAgent-<version>-Linux-x86_64.rpm

桌面端初始配置：把模型接进来

三种协议内置，填密钥即可用；第三方兼容服务走自定义 Base URL，这是中转与网关用户最常用的一条路。

多模型路由内置 Claude（Anthropic）、Codex（OpenAI）、Gemini 协议（官方 README），在设置里选协议、填密钥即可开始对话。如果你的密钥来自 API 中转站或企业统一网关，用自定义 Base URL 指向兼容端点——配置思路与 Claude Code 接中转的流程一致，一处密钥多处复用。

配置完可以顺手验证两件事：流式 Markdown 渲染是否正常（内置 KaTeX 数学、Mermaid 图表与 Monaco 代码预览），长对话历史是否稳定（Segment + Summary Checkpoint 双层持久化兜底）。两者都是 README 列明的对话层能力，出问题通常在密钥与网络，渲染层嫌疑最小。

Gateway 部署：浏览器远程控制本地 Agent

桌面端开箱即用、不依赖任何服务器（官方 README FAQ）；只有当你需要从浏览器远程控制这台机器上的 Agent 时，才值得部署 Gateway——一条 docker run 的事。

架构与断线恢复原理

Gateway 用 Go 编写，协议是 WebSocket + Protobuf，自带 WebUI；桌面端与 Gateway 之间走 WebSocket v2 双向流，浏览器经 Gateway 的 HTTP API 与 WebSocket 链路控制本地 Agent（README 架构图）。自协议 v2 起，WebUI、HTTP API、浏览器与桌面端的 WebSocket 全部收敛到单一 HTTP 端口，容器内默认监听 8080（README Nginx 说明）。

断线恢复机制值得单独讲：Gateway 维护一个有界的 seq（序列号）窗口，短暂断连重连后，按客户端上报的位点把窗口内的事件重放一遍，两端自动收敛；超出窗口的长断连，由桌面端的持久化兜底恢复（README）。工程上这是消息系统里「有界重放 + 持久化兜底」的标准组合——窗口有界，网关内存可控；持久化兜底，极端情况不丢会话。

Docker 部署与升级

镜像由 GitHub Actions 构建，多架构 amd64 / arm64（README）：

docker pull ghcr.io/stack-cairn/liveagent-gateway:latest

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

三个参数各有用途：-p 3000:8080 把宿主机 3000 端口映射到容器 8080；具名卷 liveagent-gateway-data 持久化 Gateway 数据库与独立签发的 Agent token，跨容器升级不丢（README）；LIVEAGENT_GATEWAY_TOKEN 是访问口令，务必换成自己的强随机值。

升级到最新版一条命令完成（README 给出的组合命令，改过端口或 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

反向代理要点

要绑自定义域名与 TLS 时用 Nginx 反代，四个关键点都来自 README 的参考配置：其一，WebSocket 升级发生在多条路径（/ws/v2、/ws/v2/agent、/ws/v2/terminal 及 /t/ 下的隧道），最简单正确的做法是整个 vhost 开启 upgrade；其二，Gateway 的同源校验会把浏览器 Origin 与 X-Forwarded-Proto 加 Host 比对，这两个头必须转发；其三，Gateway 每 15 秒 ping 一次所有 WebSocket 连接，proxy_read_timeout 300s 即够；其四，附件上传要求 client_max_body_size 留够，示例取 100m。配好后到桌面端 Settings → Remote 页，把 Gateway 地址填成 HTTPS URL 并用 443 端口（README）。

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    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;
    proxy_read_timeout 300s;
    proxy_send_timeout 300s;
    proxy_buffering off;
}

TunnelManager：把本地服务暴露到公网

TunnelManager 一键把本地服务暴露到公网（README），解决「服务在我机器上、外部够不着」的问题；用起来越方便，越要管好暴露面。

典型用途（工程建议，供参考）：给异地同事演示本机跑的 demo、接收第三方平台的 Webhook 回调、在外面用手机访问本地管理面板。Gateway 架构下隧道流量走 /t/ 路径，与前述 WebSocket 路径并列（README Nginx 说明）。

风险提示（工程建议，非官方要求）：公网暴露等于把内网端口交给互联网，动手前确认三件事——被暴露服务自身有认证、暴露范围与时长最小化、条件允许时套一层带鉴权的反向代理。架构侧 LiveAgent 有两道底：API key 只存桌面端本地；Gateway 是纯协议转发，不访问文件系统、不存任何凭证（官方 README FAQ）。

常见问题排查思路

三平台的故障集中在运行时依赖与 Gateway 连接两处，按顺序核对基本能定位。

• Windows 启动白屏或缺组件：检查 WebView2 运行时。Windows 11 自带（README），更早的系统需要先装一次微软官方提供的 WebView2 Runtime。
• Linux 无法启动：多半是 WebKitGTK 4.1 缺失，Ubuntu 22.04+ 与 Debian 12+ 的仓库里有对应运行库，装上再启动（README 系统要求）。
• 浏览器连不上 Gateway：依次核对 token 与 LIVEAGENT_GATEWAY_TOKEN 是否一致、端口映射与防火墙、反代是否转发了 Upgrade 与 X-Forwarded 头、同源校验是否通过（README 配置要求）。
• 短暂断网后会话丢吗：不丢。有界 seq 窗口重放短时断连，桌面端持久化兜底，重连后自动收敛（README FAQ）。

装完之后，扩展能力与自动化玩法见 MCP 与 Skills 实战。如果思路反过来——把 Agent 运行时从桌面挪到服务器常驻，那就是 AgentDock 的形态，两者按场景搭配。

常见问题

LiveAgent 必须部署 Gateway 吗？

不必须。桌面端完全独立可用，本地工具、MCP、Skills、记忆与定时任务都离线工作；只有需要从浏览器远程控制本地 Agent 时才部署 Gateway（官方 README FAQ）。不装 Gateway 不影响任何本地功能。

API 密钥会经过 Gateway 吗？

密钥不会离开桌面端：API key 只存在本地，Gateway 是纯协议转发，不访问文件系统、不存储任何凭证（官方 README FAQ）。Gateway 自托管在你自己的服务器上，链路两端的信任边界由你自己掌控。

LiveAgent 支持哪些操作系统？

macOS（Intel x64 与 Apple Silicon aarch64 双架构）、Windows x64（需 WebView2，Win11 自带）、Linux x86_64（需 WebKitGTK 4.1，Ubuntu 22.04+/Debian 12+），安装包由 GitHub Actions 构建签名并发布到 GitHub Releases（官方 README）。移动端没有原生客户端，远程场景走 Gateway 的浏览器 WebUI。