怎么跑起来

各平台最先卡在哪

装不上通常不是 agent 的问题,而是平台边界的问题。Windows 上第一处断裂是 git-bash 与原生程序之间的路径翻译;WSL 上是桌面端与后端的连接;macOS 我们没跑过,这一页就写「没跑过」,不猜。

Windows 11git-bash (MSYS2)native binary cannot open /d/…WSL 2Ubuntu · Stoppeddesktop ⇄ backend link, not …macOSnot testedzsh PATH · arm64 build · bre…hypotheses, not findingsmeasured 2026-11-18 · Windows and WSL rows reproduced, macOS row is empty of findings
Source: this machine, 2026-11-18Dashed = not tested

三个平台,三处不同的第一失败点。没有一处是 agent 本身——agent 要么起来、要么不起来;起不来时,原因通常在下层:shell 怎么传路径、桌面端怎么找到后端、包管理器怎么解析二进制。

这一页记录 2026-11-18 我们实跑到的,以及 macOS 上我们没跑的。

这台机器当时的状态

项 版本 / 状态
Windows 11,shell 是 git-bash(MSYS2)
Node v22.17.0
Python 3.11.15
Git 2.56.0.windows.4
WSL Ubuntu,版本 2,状态 Stopped

这几个数字比看上去重要:一台没装 WSL 的 Windows,和一台 WSL2 已就绪的 Windows,是不同的安装环境;「他能跑我不行」的差异,多半就落在这张表上。

Windows:同一个 shell 把路径交给两个世界

这是第一处断裂,与 agent 无关。在 git-bash 里:

$ cd /d/谷歌项目/agenthardway && pwd
/d/谷歌项目/agenthardway
$ git -C /d/谷歌项目/agenthardway rev-parse --short HEAD
fatal: cannot change to '/d/谷歌项目/agenthardway': No such file or directory
$ git -C "D:/谷歌项目/agenthardway" rev-parse --short HEAD
d5ef80f

cd 能用,因为它是 bash 内置命令,bash 自己翻译 MSYS 路径。git 是原生 Windows 程序:它拿到的就是 /d/谷歌项目/... 这串字符,打不开,于是报「目录不存在」——尽管你就站在这个目录里。

能省一下午的规则:MSYS 路径(/d/...、/c/...)给 bash 内置命令;原生路径(D:/...)给所有为 Windows 编译的程序——git、node、python、docker、ffmpeg。如果一个工具对你 cd 得进去的路径说「不存在」,就是这个原因。

WSL:坏的是「连接」,不是「安装」

这台机器上 WSL2 装了、但没启动:

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

由此两件事:第一,发行版停着不是错误——第一条命令会把它拉起来,只是启动后的首个调用很慢。第二,如果你用桌面端接 WSL 后端,你要排查的是连接,不是 agent:桌面端得被指向后端、并且知道怎么鉴权。它坏的时候,app 里报连接错误,而后端日志一切正常——因为后端根本没被问到东西。

wsl --shutdown 之后的重连行为我们没测,所以不描述。

macOS:没测过,只说该查什么

这套环境里没有 Mac,所以没有表格行、没有报错原文、也不给结论。如果你在 macOS 上,先查三件事:你的 shell 是不是 zsh、PATH 是否与 app 继承的不同;你装的是不是 arm64 构建;你依赖的工具是否解析到 GUI 应用看不见的 Homebrew 路径。这些是假设,不是发现。

三个平台一样的那部分

有三步与平台无关,坏起来哪儿都一样:

  1. 状态目录存在:安装目录列出来是空的,后面全白搭,shell 再对也没用。
  2. 配置能解析:手改成了不符合预期的形状,会在加载时失败——表现常常是「agent 启动后立刻退出」。
  3. 凭据可读:凭据不可读不会在安装时报错,而是在第一次 API 调用时报错,因此最常被误判成网络问题。

怎么知道真的修好了

一条测试就能把两个世界分开,两边用的是同一条命令:

$ git -C /d/project rev-parse --short HEAD          # fatal: cannot change to ...   <- 预期
$ git -C "D:/project" rev-parse --short HEAD        # d5ef80f                       <- 修好了
  • 修好了的样子是:原生路径那条返回 SHA,POSIX 那条仍然失败。两个结果同时正确;如果哪天 /d/... 对 git 突然好用了,说明你动的是别的东西。
  • 没修好的样子是两条都失败:那是仓库不存在或路径写错,不是翻译问题。
  • bash 内建命令不受影响。 cd /d/project 能成,因为 cd 是 shell 自己的,不是原生程序。不想记这些的话就 cd /d/project && git rev-parse --short HEAD,用相对路径。

对 WSL 来说,同样的检查会得到不同的失败:发行版里根本没有 /d/...,挂载点是 /mnt/d/...。

怎么回滚

  • 这一页没有任何东西改动了系统。 改的是「路径怎么写」,所以「回滚」就是照老写法打一遍,没有文件要恢复。
  • 如果你导出过环境变量,从你事先存的那份恢复:echo "$PATH" > ~/path.before … export PATH="$(cat ~/path.before)"。这是全文唯一会活过本次会话的动作。
  • 如果你改过 WSL 挂载或 /etc/wsl.conf:wsl --shutdown 再重开,并且留着改之前的文件——automount 写错会让发行版看起来「空了」,而不是「坏了」。
  • 不要用 alias 给单条命令打补丁。 下一个原生工具会用同样的方式失败,你等于要再排一次障。

怎么判断自己坏在哪一层

一次只问一个问题,按这个顺序:

$ ls -1 "$LOCALAPPDATA/hermes" | wc -l      # 状态层:0 = 安装没完成
$ git -C "D:/谷歌项目/agenthardway" rev-parse --short HEAD   # 路径层:只有原生程序会失败
$ wsl.exe -l -v                             # 后端层:Stopped 正常,没有才不正常

如果第一条给出一个像样的数字、第二条失败,你遇到的是路径问题,不是安装问题——要改的是引号,不是重装。

最后核验:2026-11-18。Windows 与 WSL 两行是实测;macOS 一节故意没有发现,只有待查项。

常见问题

git-bash 里为什么 git 报 cannot change to /d/...?

bash 只会替自己的内置命令翻译 /d/ 这种路径(所以 cd 能进),原生 Windows 程序拿到的是原样的字符串,打不开目录。给 git、node、python 传 D:/... 这种形式。

Windows 上必须装 WSL 吗?

不必。agent 本身能在 Windows 原生跑。WSL 只在你需要桌面端接一个 Linux 后端、或者你的工具链假定 POSIX shell 时才相关。

macOS 支持吗?

我们没测过,所以不描述。这一页里与 macOS 相关的部分,写的是「该查什么」,不是「我们看到了什么」。

来源


本文最后一次核验:2026-11-18 · 在 Windows 11 + git-bash、以及 WSL2(Ubuntu,已装未启动)上实跑;macOS 未测,页面已明标