hope-agent

环境要求

• 已安装 Docker（能执行 docker run）
• 可访问 ghcr.io 拉取镜像，或使用官方镜像站下载安装包
• 宿主机空闲端口 8420（官方示例默认端口）
• 浏览器用于访问 Web GUI 完成首次向导

安装与启动步骤

1. 1启动容器

   用官方镜像在后台启动服务，映射端口 8420 并挂载数据卷 hope-data，数据持久化到 /data

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

   复制

2. 2打开 Web GUI

   容器跑起来后，在浏览器访问本机 8420 端口，即打开内嵌的 React Web 界面

3. 3完成首次向导

   按 Onboarding 向导演操作：选 Provider 模板，填 API Key，或用 Codex OAuth 登录，然后开聊

4. 4开放局域网访问

   若要手机或另一台电脑访问，先在设置→服务器里设置 API Key，再把监听地址改为 0.0.0.0:8420

5. 5重启并远程访问

   改完监听地址后重启服务，在其它设备浏览器访问 http://<运行 Hope Agent 的设备 IP>:8420

6. 6常驻与开机自启

   无 GUI 守护进程模式可用 server start 子命令启动，server install 可注册为 launchd / systemd 开机自启

关键配置

如何确认成功

浏览器打开 http://127.0.0.1:8420 能看到完整 Web GUI，并进入 Onboarding 向导配置 Provider 即为成功。

常见问题

注意事项

• 不要在没有鉴权的情况下把 8420 端口暴露到局域网或公网；公网使用请前置 HTTPS 反向代理。
• 配置、会话、记忆全部落在 ~/.hope-agent/ 下，Docker 场景请确保数据卷持久化。
• Docker compose、配合 Ollama 本地 LLM、反向代理与 TLS、升级流程见 docs/deployment/docker.md。
• 桌面端支持 macOS，Linux / Windows 为实验性；自动更新下载的安装包经内置公钥验签，手动下载的安装包不经这道验签。