怎么跑起来
各平台最先卡在哪
装不上通常不是 agent 的问题,而是平台边界的问题。Windows 上第一处断裂是 git-bash 与原生程序之间的路径翻译;WSL 上是桌面端与后端的连接;macOS 我们没跑过,这一页就写「没跑过」,不猜。
三个平台,三处不同的第一失败点。没有一处是 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 路径。这些是假设,不是发现。
三个平台一样的那部分
有三步与平台无关,坏起来哪儿都一样:
- 状态目录存在:安装目录列出来是空的,后面全白搭,shell 再对也没用。
- 配置能解析:手改成了不符合预期的形状,会在加载时失败——表现常常是「agent 启动后立刻退出」。
- 凭据可读:凭据不可读不会在安装时报错,而是在第一次 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 未测,页面已明标