怎么跑起来

把桌面端接到后端

桌面端不自己找后端,它只读一个文件:<code>connection.json</code>。真正起作用的只有两个字段——<code>mode</code> 和它指向的 <code>remote.url</code>;认证是第三个字段 <code>authMode</code>,它不是密码。本机这份文件是 mode local,却在 remote 块里停着一个没人用的地址——能用的状态,看着像配错了。最耗时间的故障根本不在这份文件里:<code>wsl.exe -l -v</code> 报 Ubuntu 是 Stopped,serve 端口上什么都没有。

要让桌面端跟 agent 说上话,必须有两个东西对得上:一个在某处监听的服务,和 Windows 这边一个小文件说「往哪发」。两边对不上时,你看到的现象像个配置错误,实际往往不是;而那个文件看着一切正常,它指向的东西却在睡觉。

连接文件到底决定了什么

桌面端不会主动发现后端。它读一个文件,这个文件有三层。mode 决定接线方式:local 表示后端在这台机器上,remote 表示后端在网络另一头。remote 是一个装着 url 与 authMode 的块,只有在接线方式需要它时才会被读。profiles 是叠在上面的按 profile 覆盖表。

这个顺序解释了那种「看着不对」的状态。下面是本机的文件,地址与 profile 名做了脱敏:

$ python -c "…只看结构…"
mode: <str, len=5>          # "local"
remote: dict
  url: <str, len=24>        # http://<脱敏>:8765
  authMode: <str, len=5>    # "oauth"
profiles: dict              # {}

mode 是 local,可 remote 块里明明还放着一个地址。什么都没坏——那个块是睡着的:mode: local 时桌面端根本不读它。于是有人改了地址、发现没变化,就断定文件被缓存了或者被忽略了。两个都不是,是选择这个块的那个字段写着 local。

三种接线,三种不同的故障

接线方式谁在监听错了会怎样
后端在本机serve 进程,绑回环地址进程死了就是连接被拒,文件完全正常
后端在 WSL 里发行版内的 serve,从 Windows 可达发行版停着:连接被拒,不需要改任何配置
后端在另一台主机serve 绑到可路由地址,且开了认证认证对不上或防火墙;文件是对的,请求依然失败

只有第三种需要密码。这一点很重要,因为大多数人是从第二种开始的,而那一种最不可能出问题的地方就是认证。

看着像配置错,其实是发行版停着

这是这篇文章的全部理由,而它只需要两条命令。先问 Windows 发行版是什么状态:

$ wsl.exe -l -v
  NAME      STATE           VERSION
* Ubuntu    Stopped         2

再从发行版内部问,那个端口上有什么在听:

$ wsl.exe -d Ubuntu -- bash -lc 'ss -tlnp | grep -E ":9119|:9911"'
9119/9911 无监听

什么都没有。没有监听,因为没有一个在跑的发行版去持有它。WSL 发行版在没人用的时候会停,里面的 agent 服务跟着一起停。从桌面端看,这跟端口写错、主机写错完全一样:连接被拒,文件看着没错。

修法是按顺序起身:先发行版,再服务;并且把服务当成需要验证的东西,而不是假设它起来了:

wsl.exe -d Ubuntu -- bash -lc 'ss -tlnp | grep 9119'
# 没有输出 = 还是没起;启动服务,再跑同一条命令

如果希望它活过启动它的那个终端,就得真正脱离会话。nohup 不是在所有环境下都够——仍然挂在这个会话上的进程会随会话一起死。起来之后看父进程号:父进程是 1,才算真的脱离:

ps -o pid,ppid,cmd -C hermes | head

secret 不是密码

第二个坑在服务端配置里,不在连接文件。服务一旦绑到可路由地址就会打开认证,并写出一个 basic_auth 段:

basic_auth:
  username: admin
  password_hash: scrypt…        # 密码的哈希,不是密码
  secret: …                     # 服务端内部签名密钥,不是凭据

三样不同的东西并排放着,其中两样的名字恰好都在引诱你复制错。桌面端需要的密码是生成那一刻显示一次的明文;password_hash 反推不回来,secret 也不是它。把 secret 填进连接文件,得到的认证失败读起来像「密码错了」——而密码无法找回,只能删掉这一段重启重新生成。

哪个字段选认证方式

authMode 选的是「怎么认证」,我们见过的两种取值都是合法的:

  • oauth——桌面端转发云网关的 token,文件里没有用户名也没有密码。看到这个值不是配错。
  • basic——桌面端把用户名和密码发给本地服务,要求服务端开了认证。

真正的错误是:因为某篇教程这么说,就把一份 oauth 的文件「修」成 basic。如果网关会话过期了,你会收到 token 相关的报错,而不是密码提示;该做的是重新登录,不是重写文件。

记忆面板读的是另一个文件

值得单独写,因为它能耗掉一个小时:记忆面板不是后端的视图。它读桌面机本地数据目录里的记忆文件,跟连接方式无关。后端在远程或在 WSL 里时,记忆有两份拷贝,面板显示本地那份——新装的 Windows 上那份是空的或旧的。面板空、后端能用,不是 bug,是两份存储没同步。

Profile:三个地方都得对上

一个命名 profile 要在三个地方选中,而它们不是一个开关:

  1. CLI 的粘性默认,由 profile 命令写入——只影响后续的 CLI 新会话。
  2. 桌面端自己的启动 profile 文件,启动时作为参数传给后端——它优先于粘性默认,而且只在启动时读一次。
  3. serve 进程本身,每次请求枚举 profile,不需要为切换重启。

本机这个启动文件不存在,所以不管 CLI 上次设成什么,桌面端都用默认 profile 起。会话起在了错的 profile 上,先看这个启动文件,别急着动别的地方。

怎么知道它真的有效

三条检查,可信度依次递增:

  1. 端口从 Windows 这边有应答:curl -s -o /dev/null -w '%{http_code}' http://localhost:9119/api/status 返回 200,而不是空响应。空响应说明监听根本不在。
  2. 状态返回里列出了你预期的 profile——服务端是枚举出来的,缺了哪个在这里能看见,而不是在界面上。
  3. 桌面端真的完成一次会话:有回复,并且记忆面板读到的内容跟你预期的那份一致。如果会话能用而面板是空的,那是两份拷贝的问题,不是连接问题。

只绿一条不算过:端口在听但认证路径坏,会挂在第 3 步;会话能用但面板空,挂在上一条最后半句。

怎么回滚

改之前先复制,因为这里没有 reset 键,而且那些值找不回来:

cp "$APPDATA/hermes/connection.json" "$APPDATA/hermes/connection.json.bak"

要撤销改动,恢复这份拷贝并重启桌面端——文件是启动时读的,正在跑的会话会一直用旧值直到重启。如果你是开了 basic 认证又丢了密码,就在服务端配置里删掉 basic_auth 段并重启:会生成新密码,旧密码期间的会话一起作废。后半句就是代价,值得在动手之前知道,而不是之后。

我们没验的部分

macOS 与 Linux 上的桌面端、装了不止一个 WSL 发行版的 Windows、以及后端在 NAT 后面的远程部署。上面的 dump 是一台机器的一种状态;命令是通用的,「连接被拒」这一串结论是我们重复遇到过的。

常见问题

桌面端从哪里读连接信息?

Windows 漫游目录下的一个 JSON 文件 connection.json。它有 mode 字段、可选的 remote 块(含 url 与 authMode),以及可选的 profiles 映射用于按 profile 覆盖。

authMode 就是密码吗?

不是。authMode 选的是认证方式:oauth 表示桌面端转发云网关的 token,basic 表示把用户名和密码发给本地服务。服务端配置里的 password_hash 也不是密码,那是它的 scrypt 哈希——明文只在生成那一刻存在。

后端明明有记忆,为什么桌面端的记忆面板是空的?

面板读的是桌面机本地那份记忆目录,不是通过连接读后端的。两台机器两份拷贝,没同步,面板显示的就是本地那份——新装的 Windows 上往往没有。

桌面端报 connection refused,是配置错了吗?

先看发行版状态。没在运行的 WSL 发行版不会有端口在听,wsl.exe -l -v 会显示 Stopped。这件事 connection.json 不会告诉你,配置也不需要改。

换 profile 需要重启后端吗?

serve 每次请求时枚举 profile,不需要为切换而重启。不热切的是桌面端会话:profile 是启动时传进去的,已经在跑的会话会一直用它启动时那个。

来源


本文最后一次核验:2026-11-18 · 下面的文件 dump、wsl.exe -l -v 输出与空的端口列表,都是 2026-11-18 在这台机器上读到的。地址与 profile 名做了脱敏,字段名与长度是原样。