Run it
Where each platform fails first
Installs fail at the platform boundary, not in the agent. On Windows the first break is path translation between git-bash and native binaries; on WSL it is the desktop-to-backend link; on macOS we have not run it, and this page says so instead of guessing.
Three platforms, three different first failures. None of them is the agent itself — the agent starts or it does not, and when it does not, the reason is usually the layer underneath: how the shell passes paths, how the desktop app finds a backend, how a package manager resolves a binary.
This page records what we ran on 2026-11-18 and, for macOS, what we did not.
What the machine actually had
| Item | Version / state |
|---|---|
| Windows | 11, git-bash (MSYS2) as the shell |
| Node | v22.17.0 |
| Python | 3.11.15 |
| Git | 2.56.0.windows.4 |
| WSL | Ubuntu, version 2, state Stopped |
Those numbers matter more than they look: a Windows install with no WSL is a different install from one with WSL2 already provisioned, and most “it works for them but not me” reports differ on exactly this table.
Windows: the shell hands paths to two different worlds
This is the first failure and it has nothing to do with the agent. In 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 works because it is a bash builtin — bash translates the MSYS path itself. git is a native Windows binary: it receives /d/work/... verbatim and cannot open it, so it reports the directory as missing even though you are standing in it.
The rule that saves an afternoon: MSYS paths (/d/..., /c/...) for bash builtins; native paths (D:/...) for anything compiled for Windows — git, node, python, docker, ffmpeg. If a tool says “no such file” about a path you can cd into, this is the reason.
WSL: the failure is the link, not the install
On this machine WSL2 is present and stopped:
$ wsl.exe -l -v
NAME STATE VERSION
* Ubuntu Stopped 2
Two things follow. First, a stopped distro is not an error — the first command into it starts it, and the first call after a boot is slow because of that. Second, if you run the desktop app against a WSL backend, the thing you debug is the connection, not the agent: the app has to be pointed at the backend and told how to authenticate. When it fails, you get a connection error in the app, while the backend logs look perfectly healthy — because the backend was never asked anything.
We have not measured the reconnect behaviour after a wsl --shutdown, so we do not describe it.
macOS: not tested, and here is what we would check
We do not have a Mac in this setup, so there is no table row, no error text and no claim. If you are on macOS, the three things worth checking first are: whether your shell is zsh with a different PATH than the one the app inherits, whether the binary you installed is the arm64 build, and whether any tool you rely on resolves to a Homebrew path that a GUI-launched app cannot see. Those are hypotheses, not findings.
The part that is the same on every platform
Three steps are platform-independent and fail the same way everywhere:
- The state directory exists. If a listing of the install directory is empty, nothing downstream will work, no matter how the shell behaves.
- The config parses. A config file edited into an unexpected shape fails at load, which usually looks like “the agent starts and immediately exits”.
- Credentials are readable. An unreadable credentials file fails at the first API call, not at install — which is why it gets misdiagnosed as a network problem.
How you know it worked
A single test separates the two worlds, and it is the same command on both sides:
$ git -C /d/project rev-parse --short HEAD # fatal: cannot change to ... <- expected
$ git -C "D:/project" rev-parse --short HEAD # d5ef80f <- the fix
- You are fixed when the native-path form returns a SHA and the POSIX form still fails. Both outcomes are correct at the same time; a setup where
/d/...suddenly works forgitwould mean you changed something else. - You are not fixed when both fail: that is a missing repo or a bad path, not a translation problem.
- Bash builtins are unaffected.
cd /d/projectworks becausecdis the shell, not a native binary. Usecdthen a relative path if you would rather not think about it:cd /d/project && git rev-parse --short HEAD.
For WSL, the equivalent check is that the same path fails differently inside the distro — /d/... does not exist there at all; the mount is /mnt/d/....
How to undo it
- Nothing here changes the system. The fix is how you type a path, so “undo” is typing it the old way. There is no file to restore.
- If you exported something, restore it from the copy you took first:
echo "$PATH" > ~/path.before…export PATH="$(cat ~/path.before)". This is the only step in this article that can outlive the session. - If you changed a WSL mount or
/etc/wsl.conf,wsl --shutdownthen reopen; and keep the previous file — a badautomountline makes the distro look empty, not broken. - Do not “fix” it with an alias for one command. The next native tool will fail the same way and you will debug it twice.
How to know which layer you are in
Ask one question at a time, in this order:
$ ls -1 "$LOCALAPPDATA/hermes" | wc -l # state layer: 0 means install never completed
$ git -C "D:/谷歌项目/agenthardway" rev-parse --short HEAD # path layer: fails only for native tools
$ wsl.exe -l -v # backend layer: Stopped is fine, missing is not
If the first command returns a plausible number and the second fails, you have a path problem, not an install problem — and the fix is quoting, not reinstalling.
Last checked: 2026-11-18. Windows and WSL rows are measured; the macOS section is deliberately empty of findings.
Related
Questions people actually ask
Why does git fail with "cannot change to /d/..." in git-bash?
Bash translates /d/ to D:\ for its own builtins (cd works), but native Windows binaries receive the argument unchanged and cannot open it. Pass D:/... to git, node or python.
Do I need WSL to run the agent on Windows?
No. The agent runs natively on Windows. WSL matters when you want the desktop app to talk to a Linux backend, or when your tooling assumes a POSIX shell.
Is macOS supported?
We have not tested it, so we do not describe it. Everything on this page about macOS is what to check, not what we observed.
Sources
Last checked: 2026-11-18 · Windows 11 + git-bash 与 WSL2(Ubuntu, 已安装未启动) 上实跑;macOS 未测,页面已标注