关注公众号
AI Agent DeepSeek Hermes 大模型

Ekko Studio 安装配置与报错排查

从装到用只花十分钟，卡在报错上花了三小时

Ekko Studio 安装配置与报错排查 封面图

先给结论：这个桌面端本身很好装，十分钟能用；真正耗时的是它挂掉之后——后端进程崩了，界面还开着，所有功能静默失效。

我把它完整走了一遍：下载、安装、配置、踩坑、修好。下面按时间顺序写，出错的地方都附上真实日志，能直接对着查。

一、它到底是什么

Ekko Studio 是 Hermes Agent 的桌面壳 + 本地运行时 + Web 控制台。仓库在 GitHub 上是 EKKOLearnAI/hermes-studio，桌面安装包的产品名叫 Ekko Studio，npm 包名却叫 hermes-web-ui——三个名字指同一件事，找文档的时候最容易在这里绕。

它跟你原来的 Agent 不是两套东西。配置和数据还留在原来的 Hermes 目录，Studio 只是接管了界面和运行环境：

位置存什么
%LOCALAPPDATA%\hermes你原有的 Hermes 配置、凭证池、技能、记忆
~/.hermes-web-uiStudio 自己的数据库、日志、会话、上传目录

所以装它不用重新配一遍模型。装完打开，你之前调好的 provider 和凭证池直接就在。

二、安装：Windows x64 桌面版

去 GitHub Releases 下载对应的 Windows x64 安装包，双击装完，路径默认落在 %LOCALAPPDATA%\Programs\Ekko Studio。我这边装完的时间戳是 09-16 10:19。

装完后它给你几个 wrapper 命令，避免和内置 CLI 冲突：

hermes-studio           # 打开桌面应用
hermes-studio cli ...   # 内置 Hermes Agent CLI
hermes-studio web ...   # 内置 hermes-web-ui 命令
hermes-studio-mcp api   # 跑指定的托管 MCP 工具集

两个和文档不一致的地方，提前说：README 写端口 8648，桌面版实际起在 127.0.0.1:8748；默认登录是 admin / 123456，进去第一件事就是改掉。

安装与初次配置

三、配置：装完自动做了三件事

一、往你的 Hermes 配置里注入四个 MCP 工具集。

config.yaml 里会多出 ekko-studio-api、ekko-studio-browser、ekko-studio-devices、ekko-studio-use 四个 server，全部指向 Ekko Studio.exe 以 node 模式启动。意思是你的 Agent 自己多出一组"操作控制台"的能力。不想让它自动注入，设 HERMES_WEB_UI_DISABLE_MCP_AUTOINJECT。

二、模型列表直接复用凭证池。

不用手填 key。它从 ~/.hermes/auth.json 发现模型，再向每个 provider 的 /v1/models 拉可用列表。我这边拉回来 21 个 provider。

三、Coding Agent 支持 scoped 模式。

每个编码对话可以单独绑一套 provider + 模型，和主界面的模型选择互不干扰。这是我觉得最实用的一个设计——主界面挂 A 模型聊天，编码窗口挂 B 模型干活，互不打架。

四、报错：DSH 装上，一聊天就报错

这是我遇到的第一个真坑。

现象：DeepSeek Harness 装完，在 Coding Agents 里新建对话，发什么都是这一句：

Error: DSH ACP: Internal error

先说一个实用的小发现：这个报错你如果按"DSN"去搜，什么都搜不到——DSN 是数据库连接的术语，搜出来全是 ODBC 和 DNS 的噪音。它的正确写法是 DSH（DeepSeek Harness）。我在这上面白花了不少时间，先记下来省得你也踩。

排查过程：翻日志发现每次 DSH 运行都在 2 秒内 run.failed，说明 ACP 握手阶段就挂了，根本没走到模型调用。顺着配置往下挖，两层原因：

第一层，代理 token 失效。 DSH 的 studio.patch.yml 里硬编码了 provider: ekko-studio，LLM 请求要走本机代理：

- id: llm-pi-ai
  config:
    providers:
      ekko-studio:
        apiKeyEnv: HERMES_DSH_API_KEY
        api: openai-responses
        baseURL: http://127.0.0.1:8748/api/codex-proxy/<base64-token>/v1

这个 token 一旦失效，上游直接返回：

{"error":{"type":"authentication_error","message":"Invalid Codex proxy token"}}

第二层，配置会被自动覆盖。 更麻烦的是，每次新建 DSH 对话，Studio 都会重新生成一遍 studio.patch.yml，你会看到 coding-agent/model/<profile>/<provider>/dsh/runs/<hash>/ 下面又多了一个新目录。你在界面上改的模型设置，会被这个新 patch 盖掉——于是就有了"我明明改了模型，怎么还报错"。

五、真正的坑：后端崩了，界面还开着

修完 DSH 的第二天上午，出事了。

现象：界面开着，看着一切正常，但所有功能静默失效——MCP 工具全部返回 fetch failed。

第一步查端口，一秒定位：

netstat -ano | grep 8748
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8748
# 输出 000，exit 7 —— 连接被拒，根本没进程在听

后端死了，但 Electron 窗口还活着。这就是最坑的地方：界面不报错，你只会觉得"功能莫名其妙不灵了"。

第二步，直接复现崩溃拿真实错误，别猜：

cd "$LOCALAPPDATA/Programs/Ekko Studio/resources/webui/dist/server"
node --check index.js

输出很明确：

SyntaxError: Invalid regular expression: Unmatched ')'

而且报错位置附近有乱码 [銆傦紒锛??.鈥——这是一段 UTF-8 的中文标点正则，被按 GBK 误解码了。对照文件时间才发现：index.js 在 09:08 被改写过，旁边留着一个 09-16 的 index.js.bak，两个文件 md5 不同，大小差了几百字节。也就是说，是一个补丁脚本动了后端文件，把中文正则改坏了，服务一启动就崩。

排错：后端进程崩了但窗口还开着

第三步，修复。 我最后的做法是重新安装桌面版。原因很实际：index.js 是单行压缩文件，diff 出来的 125 行差异完全不可读，手动改回去风险比重装高。重装后文件回到 09-16 10:19 的原始版本，8748 立刻恢复监听（新进程 12:37:57 起来）。

重装之后，DSH 也一起好了。 实测发一句"你好"，正常走通：provider ekko-studio、模型 agnes-2.5-flash、turn 正常 completed。回头看，这两个问题本来就是同一个根因——8748 上的后端没了，codex-proxy 自然也没了，DSH 的代理 token 当然失效。

六、总结

问题现象根因解决
端口对不上文档 8648，实际连不上桌面版起在 8748按 8748 访问
DSH 一聊天就报错DSH ACP: Internal errorstudio.patch.yml 走 codex-proxy，token 失效见下方三条路径
改了模型没用设置被覆盖新建对话会重新生成 patch 文件别改 patch，改 Studio 侧配置
功能静默全废MCP 工具全 fetch failed后端进程崩了，窗口还在查 8748 端口，必要时重装
后端崩的原因Unmatched ')'补丁脚本把中文正则按 GBK 改坏重装恢复原文件

DSH 那三条修复路径，从省事到治本：

顺序做法说明
1完全退出 Studio（含后台进程）再启动刷新代理 token，最快
2删掉 DSH 的 run 目录再重启~/.hermes-web-ui/coding-agent/.../dsh/runs/*
3直接重装桌面版治本，把后端文件还原成官方版本

三条经验，比上面任何表格都值钱：

  1. 界面活着 ≠ 服务活着。 这个架构下，Electron 壳和 Web UI 后端是两个独立进程，壳不会因为后端崩了就报错。以后遇到"功能莫名不灵"，第一件事就是 netstat 查端口。
  2. 别在自动生成的文件上下手改。 studio.patch.yml 这类文件由程序生成，改了会被覆盖，要去 Studio 侧的配置里改。
  3. 报错先搜对缩写。 DSN 和 DSH 差一个字母，搜索结果的噪音量差十倍。

谁适合装：同时用多个 Agent 需要一个统一入口的、要给 Agent 配多个渠道（Telegram / 微信 / 飞书 / 钉钉）的、想在画布上编排多步工作流还要留执行证据的。谁可以先不装：只用一个 CLI Agent、在终端里跑得很顺的。

这类桌面壳目前还是早期版本，踩坑正常。好在排查路径足够清楚——端口、进程、日志三样查下来，基本没有查不到的。

中国 AI 的位置：中美顶级模型差距约 2.7%（斯坦福 HAI 2026），论文和专利数量全球第一，工业机器人装机量是美国的 9 倍；差得最多的是投资，比例约 23:1。工具层的开源桌面包，恰恰是差距最小、迭代最快的一块。

如果觉得有帮助，点个「赞」和「在看」支持一下 👇

← 返回文章列表