HugAgentOS

环境要求

• 一键安装需 Linux / macOS / WSL2，且已装 Python 3.11+、Node.js 20+、Git 和 curl
• Docker 方式需 Git、Docker 及 Compose v2
• 需要一个 OpenAI 兼容模型或本地模型
• 一键安装默认占用 127.0.0.1:3001，Docker 方式访问 localhost:3002

安装与启动步骤

1. 1确认环境依赖

   一键安装走 Linux / macOS / WSL2，先备好 Python 3.11+、Node.js 20+、Git 与 curl；此方式不需要 Docker、PostgreSQL、Redis。

2. 2一键安装并启动

   脚本会把源码拉到 ~/.hugagent/source，建独立 Python 环境、构建 Web 应用并引导首次设置，随后自动打开 127.0.0.1:3001。

   curl -fsSL https://raw.githubusercontent.com/ZJU-REAL/HugAgentOS/main/install.sh | bash

   复制

3. 3首次登录改密

   浏览器打开 http://127.0.0.1:3001，用初始账号 admin / 密码 admin 登录，并在首次登录时修改密码。

4. 4连接模型服务

   进入 Settings → System → Model services，配置一个 OpenAI 兼容或本地模型，否则智能体无法真正工作。

5. 5日常再次启动

   安装完成后，之后用安装目录里的可执行文件重新拉起服务，不需要再跑安装脚本。

   ~/.hugagent/venv/bin/hugagent

   复制

6. 6Docker Compose 部署

   需要 PostgreSQL、Redis、隔离沙箱和持久化卷时用这条路径：克隆仓库、复制环境文件、建数据目录并后台构建启动。

   git clone https://github.com/ZJU-REAL/HugAgentOS.git
   cd HugAgentOS
   cp .env.example .env
   mkdir -p data/storage
   docker compose up -d --build

   复制

7. 7打开 Docker 界面

   容器起来后访问 http://localhost:3002，同样在 Settings → System → Model services 里连接模型，再用 admin 登录改密。

关键配置

如何确认成功

浏览器能打开 http://127.0.0.1:3001（Docker 为 http://localhost:3002），并用 admin / admin 登录成功即正常。

常见问题

注意事项

• 一键安装默认只监听 127.0.0.1；确需远程访问可执行 hugagent serve --host 0.0.0.0 --port 3001 --no-browser，但请先设置强密码、防火墙与 HTTPS。
• 不要把服务直接暴露在不可信网络上。
• 社区仓库由上游主仓库按每次发布生成。