Hope Agent

跨端交接、越用越懂你的桌面 AI 助手，也能服务化常驻、跑在云上
会记忆 · 能成长 · 深度融合 · 在你所有的聊天里随叫随到

简体中文 · English

Hope Agent 想把 AI 助手做得更简单、更稳定，也更省维护。同一份会话能在你的设备和聊天之间随手交接，并在日复一日的使用里自己变好——跨会话记忆持续累积、空闲时自己整理、做过的事沉淀成可复用的技能。一个原生安装包，主流大模型 GUI 模板内置齐全，填完 API Key 就能开聊；桌面端还能在你授权后观察并控制本机电脑（暂时仅 macOS）；同时它也能以服务形态常驻 NAS / 自家服务器 / 云主机，在 IM 渠道里随叫随到。

目录

• 缘起
• 亮点
• 快速开始
  • 下载安装
  • 自托管（Docker）
  • 开发者
• 运行模式
• 生态一览
• 项目结构
• 文档
• 贡献
• 社区
• 致谢
• Star History
• License

缘起

我们希望 AI 助手能真正打开就能用——下载安装即用，不用先装运行时、学命令行，也不用为看不懂配置、服务半夜崩掉没人管而操心；同时它还应该走到哪都能接着用。Hope Agent 不只是桌面 GUI，它还能以 HTTP/WS 服务常驻，放在 NAS、自家服务器或云主机上 7×24 跑着，同时接入 IM 渠道、对接 IDE（ACP）；但我们相信最顺手的入口仍然是桌面，所以在桌面 GUI 和系统深度融合上投入了最多的精力，同时把性能、稳定性和交互细节一起打磨好。核心目标很朴素：降低使用和维护成本，让简单场景足够顺手，让长期运行也足够稳定。也希望它能陪着你长期用下去——同一份会话跨设备、跨入口接续，让工作随你切换平台而不中断，记忆和技能慢慢累积下来。

Hope Agent 早期曾受 openclaw 影响，感谢他们在本地 AI 助手方向上的先行工作——我们选择了不同的实现路径。

亮点

🎯 日常使用

🧠 记忆与学习

🛠 工作流 & 工具

🛡 安全与本地化

更多细节亮点请查看 CHANGELOG.md。

快速开始

下载安装

📦 各平台完整安装包列表：Releases

macOS

Homebrew（推荐）

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

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

手动安装（DMG）

到 Releases 下载 Hope.Agent_*.dmg，拖到「应用程序」即可。

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

copy

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

Apple Silicon 与 Intel Mac 均提供原生构建（arm64 / x64 DMG），Homebrew 与手动下载都会按你的硬件自动选对版本。

启动方式

• 桌面 GUI：Launchpad / 应用程序文件夹（点 Hope Agent 图标），或终端 open -a "Hope Agent" / hope-agent
• 后台服务（HTTP/WS daemon）：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 双击安装。Windows 端尚未完成充分测试，欢迎反馈问题。

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

当前仅 x64。

启动方式

• 桌面 GUI：Start 菜单点「Hope Agent」启动，或 PowerShell hope-agent
• 后台服务（HTTP/WS daemon）：hope-agent server start（PowerShell / cmd）
• 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://shiwenwen.github.io/hope-agent-linux-repo/pubkey.gpg | \
  sudo gpg --dearmor -o /usr/share/keyrings/hope-agent.gpg
echo "deb [signed-by=/usr/share/keyrings/hope-agent.gpg] https://shiwenwen.github.io/hope-agent-linux-repo/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://shiwenwen.github.io/hope-agent-linux-repo/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://shiwenwen.github.io/hope-agent-linux-repo/rpm/hope-agent.repo
sudo zypper install hope-agent

手动安装（AppImage / deb / rpm）

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

• AppImage：Hope.Agent_*.AppImage —— chmod +x 后直接运行
• Debian / Ubuntu：Hope.Agent_*.deb —— sudo dpkg -i Hope.Agent_*.deb
• Fedora / RHEL：Hope.Agent_*.rpm —— sudo rpm -i Hope.Agent_*.rpm

提供 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
• 后台服务（HTTP/WS daemon）：hope-agent server start
• ACP（IDE 集成）：hope-agent acp

首次启动 & 自动更新

1. 首次启动向导：选 Provider 模板 → 填 API Key / Codex OAuth 登录 → 开聊
2. 桌面应用内置 GitHub Releases 自动更新，应用内 设置 → 关于 检查更新并一键安装；或者直接在对话里说「升级」或「检查更新」
3. 通过 Homebrew / AUR / Scoop 装的版本同样走应用内置 updater；包管理器视角的版本号会保持初装时的，不影响功能

自托管（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。

开发者

git clone https://github.com/shiwenwen/hope-agent.git
cd hope-agent
pnpm install
pnpm tauri dev         # 桌面开发模式（前端 + Rust 热重载）

# 其他常用命令
pnpm typecheck         # 前端类型检查（tsc -b）
pnpm lint              # Lint
pnpm tauri build       # 打生产包

本地开发时如果想在浏览器里看“网页版”并实时刷新，运行 pnpm tauri dev 后打开 http://localhost:1420。这是 Vite dev server，和 Tauri 窗口共用前端热更新；http://localhost:8420 是内嵌 HTTP/WS 服务提供的静态 Web GUI（来自 dist/ / embedded bundle），用于模拟打包后的浏览器入口，不会跟随源码 HMR。若本地 Server 开了 API Key，1420 页面请求 8420 可能返回 401，开发时可先在设置里临时清空 Server API Key 后重启。

运行模式

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

生态一览

项目结构

Cargo Workspace 三 Crate 架构，核心业务逻辑全部在 ha-core：

crates/
  ha-core/       Rust 核心库（零 Tauri 依赖）— 所有业务逻辑在这里
  ha-server/     axum HTTP/WS 守护进程（薄壳）
src-tauri/       Tauri 桌面 Shell（薄壳）
src/             React 19 + TypeScript 前端
skills/          内置技能（随应用发行）

完整的模块拓扑、架构约定、编码规范见 AGENTS.md。

文档

详见 docs/。

贡献

主分支处于活跃开发阶段，欢迎 issue / PR。贡献前请先读一遍 AGENTS.md 的 "架构约定" 和 "编码规范" 两节。

常用命令：

pnpm tauri dev                    # 桌面开发
cargo check --workspace              # Rust 依赖 / 类型检查
cargo test -p ha-core -p ha-server   # 核心测试
node scripts/sync-i18n.mjs --check   # 检查翻译缺失

社区

• 🐛 Issues — Bug 报告、功能请求
• 💡 Discussions — 用法分享、想法讨论、提问答疑
• ⭐ 如果 Hope Agent 帮到了你，欢迎在 GitHub 上点个 Star
• 📮 路线图、正式文档站和更多社区渠道正在筹备中

致谢

• openclaw：在本地 AI 助手方向上的启发
• Ollama：本地大模型一键安装能力建立在 Ollama 的本地运行时与 OpenAI 兼容端点之上；Hope Agent 仅作 GUI 层包装，Qwen / Gemma 等模型由 Ollama 模型库分发
• ClawHub / SkillHub：为 Hope Agent 提供公开的 skill 搜索与发现来源
• Hermes Agent（间接溯源 obra/superpowers）：部分内置编程方法论 skill 改编自此（MIT），详见 THIRD_PARTY_NOTICES.md
• Tauri、axum、React、shadcn/ui、Streamdown、Radix UI 等开源基础设施
• 所有为这个项目做过反馈、测试、提交 issue 的朋友

Star History

License

MIT