Hope Agent
shiwenwen/hope-agent
Assistente IA que sincroniza entre seus dispositivos e aprende com o tempo
Ver no GitHubAssistente de IA desktop multiplataforma que funciona nativamente em macOS, Linux e Windows, com capacidade de sincronização entre dispositivos e acúmulo de memória através de conversas. Pode ser implantado como serviço em NAS, servidores próprios ou nuvem, integrando-se a canais de IM e IDEs, com suporte a 44 templates de providers e 335 modelos pré-configurados.
Instalação
npx convez-ai shiwenwen/hope-agent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Assistência produtiva desktop com IA contextualizada
- Implantação de agente IA em servidor NAS ou nuvem como serviço 24/7
- Automação de tarefas com controle de desktop (macOS) e integração com IDE
Veredito

Projeto ambicioso em Rust com foco em estabilidade e UX nativa multiplataforma. Adota MCP como estratégia de integração, oferecendo flexibilidade, mas a maturidade da base de usuários e documentação em inglês requerem avaliação técnica prévia.
README
A tradução para o português deste README ainda está na fila.
Hope Agent 想把 AI 助手做得更简单、更稳定,也更省维护。同一份会话能在你的设备和聊天之间随手交接,并在日复一日的使用里自己变好——跨会话记忆持续累积、空闲时自己整理、做过的事沉淀成可复用的技能。一个原生安装包,主流大模型 GUI 模板内置齐全,填完 API Key 就能开聊;桌面端还能在你授权后观察并控制本机电脑(暂时仅 macOS);同时它也能以服务形态常驻 NAS / 自家服务器 / 云主机,在 IM 渠道里随叫随到。
目录
缘起
我们希望 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,拖到「应用程序」即可。
若启动时提示"已损坏"或"无法验证开发者",请在终端执行:
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
首次启动 & 自动更新
- 首次启动向导:选 Provider 模板 → 填 API Key / Codex OAuth 登录 → 开聊
- 桌面应用内置 GitHub Releases 自动更新,应用内 设置 → 关于 检查更新并一键安装;或者直接在对话里说「升级」或「检查更新」
- 通过 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 后重启。
运行模式
| 模式 | 启动方式 | 场景 |
|---|---|---|
| 桌面 GUI | 双击图标 / pnpm tauri dev | 功能最全的入口:完整 GUI 体验,并内嵌 HTTP/WS 服务,桌面在用的同时可对外提供接入 |
| Server + Web GUI(HTTP/WS) | 通过 server start 子命令;server install 可注册成 launchd / systemd 开机自启 | 无 GUI 守护进程,24 小时在线,IM 渠道 / Cron 不断线;前端 React UI 通过 rust-embed 内嵌进 server 二进制,浏览器打开 http://<server>:port 即得完整 Web GUI,手机 / 平板 / 任意电脑都能直连 |
| ACP(stdio) | 通过 acp 子命令 | IDE 直连,兼容 ACP 协议的编辑器把 Hope Agent 当 agent 后端调 |
三种模式共用同一套 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 的朋友