Ekko Studio 安装教程：4 种形态一次跑通，升级避坑一次讲清-二趣网

Ekko Studio 安装教程：4 种形态一次跑通，升级避坑一次讲清

【免费下载链接】ekko-studioEkko Studio is a local-first AI workspace for multi-agent chat, coding, and visual workflows, available on desktop and the web.项目地址: https://gitcode.com/gh_mirrors/he/ekko-studio

Ekko Studio 是一款本地优先的多智能体 AI 工作台，集多智能体聊天、编码与可视化工作流于一体，桌面端与 Web 端都能跑。本文按桌面应用、npm 全局安装（hermes-web-ui / ekko-studio-web）、Docker Compose、源码开发四种安装形态，给出可直接执行的命令、端口与持久化路径。读完你能独立为任意一种场景完成安装、验证与升级。

先对号入座：按你的身份选安装路线

四种形态的差异不在功能，而在「谁来管理进程和数据」：

如果你在自己电脑上日常使用→ 走桌面应用。这是官方推荐给最终用户的形态，打包应用自带 Studio 服务器，还能单独管理一套 Hermes Runtime，你不需要关心端口和进程。
如果要在服务器或自己的机器上部署一个 Web 服务→ 走npm 全局安装，一条命令拉守护进程，默认端口 8648，升级也是一条命令。
如果要容器化自托管、或交给运维环境→ 走Docker Compose，预构建镜像里已集成 Hermes Agent Runtime，默认主机端口 6060。
如果要改代码、调试或贡献→ 走源码开发安装，前端 8649、后端 8647 分离，改动可实时看到。

⚡ 最快跑起来：桌面应用 4 步验证

从 Ekko Studio 的 Releases 页面下载与平台、架构匹配的安装包，安装并启动。
打开Agents页面，确认 Ekko 显示为Built in。
受管 Runtime（Managed Runtime，即由 Studio 下载并托管的 Hermes 运行环境）就绪后，在终端验证 shims（shim 是放进 PATH 里的小代理程序，让命令在终端里直接可用）：

ekko-studio -h ekko-studio web version

期望结果：第一条打印帮助，第二条打印版本号，都通过即桌面安装可用。

注意：桌面应用升级、下载 Runtime 包、ekko-studio cli update是三件事，装好后别把它们混用，详见文末升级专题。

分形态详解

桌面应用安装：下载、shims 与 Agents 页面核对

前置检查

确认操作系统与 CPU 架构，从 Releases 选对应安装包。
若之前装过非受管的 Hermes（例如python -m pip install hermes-agent），记住这个用户级 CLI 在 Studio 选源时优先于受管 Runtime。

操作步骤

下载、安装、启动应用。
打开 Agents：Ekko 应为 Built in；Hermes 状态只有三种——用户级 CLI、受管 Runtime、未安装。
Runtime 就绪后，终端里依次可用ekko-studio（打开应用）、ekko-studio web ...（内置 Web UI CLI）、ekko-studio cli ...（受管 Hermes CLI）。
需要 MCP 时执行ekko-studio-mcp [api|browser|use|plan]启动一个工具集，默认连http://127.0.0.1:8648；HERMES_WEB_UI_URL、HERMES_WEB_UI_HOME、HERMES_WEB_UI_TOKEN、HERMES_MCP_TOOLSET可分别改连接地址、状态目录、令牌与工具集类别（实现见 bin/ekko-studio-mcp.mjs）。

怎么确认装好了

看 Agents 页面即可：每次安装状态变化后都要刷新页面，确认 Hermes 落到预期状态。

常见卡点

终端里命令可用、Studio 识别不到：先重启 Studio，再排查 Studio 进程可见的 PATH 与 npm prefix，别急着重装（检测逻辑见 hermes-runtime.md）。
容器里不要使用 Desktop 的 Runtime 存储迁移功能，两者的管理职责不同。

hermes-web-ui npm 全局安装步骤

前置检查

node --version npm --version npm config get prefix

Node 需 23 及以上（package.json 的engines声明"node": ">=23.0.0"）；Windows 下确认全局 prefix 的 npm 目录在 PATH 中。

操作步骤

npm install -g ekko-studio ekko-studio-web version ekko-studio-web start --no-open ekko-studio-web status

期望：version输出版本号；start结束后status显示运行中，服务在http://localhost:8648，也可用--port指定别的端口。

说明：当前主 npm 包是ekko-studio、命令是ekko-studio-web；旧包hermes-web-ui及其命令仍受支持，发同一版本、跑同一份 bin/hermes-web-ui.mjs，所以旧命令hermes-web-ui start同样有效。

怎么确认装好了

两条同时满足才算成功：①version能输出版本号；②start后status显示运行中。CLI 启动时会每 500ms 轮询一次/health，最多等 30 秒，通过后打印✓ hermes-web-ui started并自动打开浏览器（--no-open关闭）。

常见卡点

端口被占：启动时检测到目标端口被占用，CLI 会先结束占用进程再拉起服务，这是预期行为。
健康检查 30 秒超时（打印 ⚠ 警告）：去看~/.hermes-web-ui下的server.log。
登录问题：ekko-studio-web reset-default-login可重建默认登录 admin / 123456；被 IP 锁住用clear-login-locks。
数据都落在HERMES_WEB_UI_HOME（默认~/.hermes-web-ui）：PID 文件server.pid、日志server.log、令牌.token、数据库hermes-web-ui.db。首次启动生成 32 字节随机令牌写入.token（权限 0600）并作为AUTH_TOKEN注入子进程；你自己设了AUTH_TOKEN则以你的为准。
server.log超过 3MB 会自动裁剪，只保留最后 2000 行。

Docker Compose 部署三步：镜像、挂载与验证

前置检查

Docker 与 Compose 可用；确认主机 6060 空闲（可用PORT环境变量改，完整变量表见 docs/docker.md）。

操作步骤

WEBUI_IMAGE=ekkoye8888/hermes-web-ui docker compose up -d docker compose ps docker compose logs -f hermes-webui

直接使用仓库根目录的 docker-compose.yml 即可。预构建镜像基于nousresearch/hermes-agent:latest，Hermes Agent Runtime 已集成在内，无需额外安装；HERMES_WEB_UI_MANAGED_GATEWAY=1会启用受管网关自动启动。

期望：ps中容器健康，浏览器打开http://localhost:6060可访问。

怎么确认装好了

docker compose exec hermes-webui hermes --version

输出版本号，说明容器内的 Hermes 可执行文件就位。

持久化路径

volumes: - ${HERMES_DATA_DIR:-./hermes_data}:/home/agent/.hermes - ${HERMES_DATA_DIR:-./hermes_data}/hermes-web-ui:/home/agent/.hermes-web-ui

宿主机./hermes_data下的两份数据映射到容器内两个独立目录：/home/agent/.hermes（Hermes 数据）与/home/agent/.hermes-web-ui（Studio 状态）。重建或升级容器时必须保留这两组挂载，否则数据丢失。容器内NPM_CONFIG_PREFIX指向 Studio 数据卷里的coding-agent/npm目录，让 Runtime 安装的 coding-agent CLI 持久化进已有数据卷（Dockerfile 中有相同配置）。

常见卡点

不要在容器内使用 Desktop 的 Runtime 迁移功能，Docker 环境的 Runtime 完全由镜像与 Compose 挂载托管。
鉴权令牌首次运行自动生成并打印在容器日志里；删掉令牌文件重启会生成新令牌。

源码开发环境搭建：从 clone 到 npm run dev

前置检查

Git、Node 23+、npm。

操作步骤

git clone https://gitcode.com/gh_mirrors/he/ekko-studio cd ekko-studio npm install npm run dev

npm run dev用concurrently并行起两个开发服务器：前端 Vite 跑在8649（设置HERMES_WEB_UI_BACKEND_PORT=8647），后端由 nodemon 跑在8647（脚本定义见 package.json）。

期望：浏览器打开http://localhost:8649，页面能正常从 8647 后端取到数据。

怎么确认装好了

先用最小相关测试验证检出状态（npm test全量跑，或vitest run只跑改动模块），通过后再执行npm run build——它会依次跑 OpenAPI 生成、vue-tsc -b类型检查、Vite 构建、服务端 TS 检查与build-server打包，全部通过才算可投产的构建。

常见卡点

已有检出先git status；工作区干净且分支策略允许才更新；lockfile 变了就重新npm install再构建。
绝不允许为了升级 Studio 而丢弃脏工作区，未提交的改动可能就是关键配置。

验证清单：逐项勾选确认装好

按你装的形态勾选对应项：

桌面：Agents 页面 Ekko 为 Built in，ekko-studio -h与ekko-studio web version均有输出
npm：version输出版本号，start后status显示运行中
npm：http://localhost:8648可访问且能登录
Docker：docker compose ps健康，http://localhost:6060可访问
Docker：docker compose exec hermes-webui hermes --version有版本输出
源码：http://localhost:8649（前端）与http://localhost:8647（后端）均有响应
安装状态变化后刷新过 Agents 页面，Hermes 落在「用户 CLI / 受管 Runtime / 未安装」之一
持久化目录可写：~/.hermes-web-ui（Studio 状态）、~/.hermes（Hermes 数据）或 Docker 的./hermes_data

🔁 升级专题：分清三条容易搞混的升级线

安装之后最容易犯的错，是把「升级」当成一件事。Ekko Studio 里其实是三条互不替代的升级线，对象、入口、前置条件都不同：

升级对象	入口	实际改变的东西	关键前置与边界
桌面应用本身	应用内Check for Updates	应用及其内置 Web UI 版本	更新器先查 Cloudflare feed，失败回退 GitHub latest-release feed；用户确认后才下载，随后提示重启
受管 Runtime 包	Agents 页 → Hermes → Version Management	Hermes Runtime 版本，存于`<HERMES_WEB_UI_HOME>/desktop-runtime`	新版本激活后旧版本仍保留；活动中的 Runtime 不能删，先切换到其他版本再删
Runtime 内的 Hermes Agent 源码	`ekko-studio cli update`（Runtime 0.19.1 及以上）	仅 Runtime 内部的 Agent 代码	必须先完全退出 Ekko Studio；不改桌面应用与 Web UI

hermes-web-ui 自升级（npm 形态）

ekko-studio-web update --no-open

upgrade是别名，旧命令hermes-web-ui update等效。CLI 依次做四件事：尽力npm cache clean --force（失败不中断）、全局安装最新版、定位更新后的全局 CLI 脚本、以之前的端口或指定端口重启服务。重启默认 15 秒优雅停机窗口（HERMES_WEB_UI_STOP_GRACE_MS/HERMES_WEB_UI_RESTART_GRACE_MS可调）；设置HERMES_AGENT_BRIDGE_STOP_ON_SHUTDOWN=0可让 Agent Bridge 跨重启保留（此时窗口缩短为默认 5 秒）。

Docker 镜像升级

WEBUI_IMAGE=ekkoye8888/hermes-web-ui docker compose pull WEBUI_IMAGE=ekkoye8888/hermes-web-ui docker compose up -d --force-recreate docker compose ps

拉取与启动必须使用同一个WEBUI_IMAGE值，否则会起一个旧镜像的容器。

Runtime 选源规则

Hermes 可能来自用户级 CLI 或受管 Runtime，且用户级 CLI 按设计优先。升级后先确认选中的是哪条来源（路径加版本）：终端里用hermes --version验证，macOS/Linux 用which -a hermes、Windows 用where hermes看全部候选。Studio 仍持有 Runtime 进程时不要跑ekko-studio cli update；做完后重新打开 Studio，核对 Hermes 版本与 Runtime 路径。

装完之后的三件事

只想用的话，装桌面应用、刷新 Agents 页面即可，以后每次「升级」前先对照上面三条升级线。服务器部署记得把ekko-studio-web status（或 Docker 的 6060 端口）纳入例行检查，并把~/.hermes-web-ui、~/.hermes（或./hermes_data）放进备份范围。已有源码检出时，养成先git status再动手的习惯。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析