快速开始

下载安装

📦 各平台完整安装包列表：Releases 🌏 访问不了 GitHub？ 所有安装包同时镜像在 <https://repo.hopeagent.ai/download/latest/>（Cloudflare R2，与 apt / dnf 软件源同域名），下面每个手动安装入口都给了镜像直链。桌面应用的自动更新也优先走这个镜像，GitHub 作为兜底。历史版本按 https://repo.hopeagent.ai/download/v<版本>/ 长期保留。

macOS

Homebrew（推荐）

brew tap shiwenwen/hope-agent
brew install --cask hope-agent

已经手动装过 Hope Agent.app？在 brew install 后面加 --adopt（接管同版本现有应用，不重新下载）或 --force（强制重下覆盖）。

手动安装（DMG）

到 Releases 下载 Hope.Agent_*.dmg，拖到「应用程序」即可。镜像直链：Hope.Agent_aarch64.dmg。

若启动时提示"已损坏"或"无法验证开发者"，请在终端执行：

> sudo xattr -cr /Applications/Hope\ Agent.app
> sudo codesign --force --deep --sign - /Applications/Hope\ Agent.app
> 

常规发布提供 Apple Silicon（arm64）原生构建。Intel Mac（x64）安装包由独立构建流程按需提供，请先确认目标版本的 Release 资产确有 x64 DMG；缺失时 Homebrew 和下载页不能提供该版本的 Intel 安装包。

启动方式

• 桌面 GUI：Launchpad / 应用程序文件夹（点 Hope Agent 图标），或终端 open -a "Hope Agent" / hope-agent
• 浏览器 Web GUI：打开桌面应用后访问 <http://127.0.0.1:8420>；也可以运行 hope-agent server start，只启动服务、不打开桌面窗口
• ACP（IDE 集成）：hope-agent acp

Windows

Scoop（推荐）

scoop bucket add hope-agent https://github.com/shiwenwen/scoop-hope-agent
scoop install hope-agent

手动安装（installer）

到 Releases 下载 Hope.Agent_*-setup.exe 双击安装。镜像直链：Hope.Agent_x64-setup.exe。Windows 端尚未完成充分测试，欢迎反馈问题。

若启动时提示"由于找不到 MSVCP140_1.dll，无法继续执行代码"或类似缺失 VCRUNTIME140.dll / MSVCP140.dll，请安装 Microsoft Visual C++ 2015–2022 运行库（x64）后重启应用。

当前仅 x64。

启动方式

• 桌面 GUI：Start 菜单点「Hope Agent」启动，或 PowerShell hope-agent
• 浏览器 Web GUI：打开桌面应用后访问 <http://127.0.0.1:8420>；也可以在 PowerShell / cmd 运行 hope-agent server start，只启动服务、不打开桌面窗口
• ACP（IDE 集成）：hope-agent acp

Linux

Arch Linux / Manjaro（AUR）

yay -S hope-agent-bin   # 或 paru / 任意 AUR helper

预编译二进制版（沿用 GitHub Release 的 .deb），不从源码编译。

Debian / Ubuntu（apt）

curl -fsSL https://repo.hopeagent.ai/pubkey.gpg | \
  sudo gpg --dearmor -o /usr/share/keyrings/hope-agent.gpg
echo "deb [signed-by=/usr/share/keyrings/hope-agent.gpg] https://repo.hopeagent.ai/apt stable main" | \
  sudo tee /etc/apt/sources.list.d/hope-agent.list
sudo apt update
sudo apt install hope-agent

Fedora / RHEL / CentOS（dnf / yum）

sudo curl -fsSL https://repo.hopeagent.ai/rpm/hope-agent.repo \
  -o /etc/yum.repos.d/hope-agent.repo
sudo dnf install hope-agent     # 或 sudo yum install hope-agent

历史命令 sudo dnf config-manager --add-repo … 在 dnf5（Fedora 41+）已经废弃，用上面的 curl 写法对 dnf4 / dnf5 / yum / zypper 都兼容。

openSUSE 用户：

sudo zypper addrepo https://repo.hopeagent.ai/rpm/hope-agent.repo
sudo zypper install hope-agent

手动安装（AppImage / deb / rpm）

到 Releases 下载（包名含架构后缀，按你的机器选 _amd64 / _arm64 或 .x86_64 / .aarch64）：

• AppImage：Hope.Agent_*.AppImage —— chmod +x 后直接运行。镜像：amd64 · aarch64
• Debian / Ubuntu：Hope.Agent_*.deb —— sudo dpkg -i Hope.Agent_*.deb。镜像：amd64 · arm64
• Fedora / RHEL：Hope.Agent_*.rpm —— sudo rpm -i Hope.Agent_*.rpm。镜像：x86_64 · aarch64

提供 amd64 (x86_64) 与 arm64 (aarch64) 两种原生构建，覆盖普通 PC、树莓派 4/5、Apple Silicon 跑 Asahi Linux、Graviton / Ampere 云主机。apt 与 dnf 都会按 dpkg --print-architecture / $basearch 自动选对版本。

启动方式

• 桌面 GUI：应用菜单点「Hope Agent」启动，或终端 hope-agent
• 浏览器 Web GUI：打开桌面应用后访问 <http://127.0.0.1:8420>；也可以运行 hope-agent server start，只启动服务、不打开桌面窗口
• ACP（IDE 集成）：hope-agent acp

首次启动 & 自动更新

1. 首次启动向导：选 Provider 模板 → 填 API Key / Codex OAuth 登录 → 开聊
2. 桌面应用内置自动更新（优先读 repo.hopeagent.ai 镜像，GitHub Releases 兜底），应用内 设置 → 关于 检查更新并一键安装；或者直接在对话里说「升级」或「检查更新」。自动更新下载的安装包一律经内置公钥验签，镜像与 GitHub 走同一套校验（手动下载的安装包由系统安装，不经这道验签）
3. 通过 Homebrew / AUR / Scoop 装的版本同样走应用内置 updater；包管理器视角的版本号会保持初装时的，不影响功能

要从手机或另一台电脑访问，在「设置 → 服务器」中设置 API Key，并把监听地址改为 0.0.0.0:8420；重启后访问 http://<运行 Hope Agent 的设备 IP>:8420。不要在没有鉴权的情况下把端口暴露到局域网或公网；公网使用请前置 HTTPS 反向代理，详见 Docker 部署指南。

自托管（Docker）

把 Hope Agent 跑在家用 NAS / VPS / homelab 上、用浏览器访问 Web GUI 的场景：

docker run -d \
  --name hope-agent \
  -p 127.0.0.1:8420:8420 \
  -v hope-data:/data \
  ghcr.io/shiwenwen/hope-agent:latest

容器跑起来后浏览器打开 <http://127.0.0.1:8420>，按 Onboarding 向导配 Provider API Key。镜像覆盖 linux/amd64 + linux/arm64（含 Apple Silicon / 树莓派），随每次 Release Tag 自动构建。

要用 docker compose / 配合 Ollama 本地 LLM / 暴露到 LAN / 反向代理与 TLS / 升级流程，见 docs/deployment/docker.md。

运行模式

三种模式共用同一套 ha-core 核心逻辑；配置、会话、记忆全部落在 ~/.hope-agent/ 下。