From 5e9d577fcafcc2a1871fd94c3a6f58ce165fc080 Mon Sep 17 00:00:00 2001 From: dd3xp Date: Wed, 8 Jul 2026 00:47:24 -0400 Subject: [PATCH] docs: mention Windows Defender loopback issue --- docs/installation.md | 6 ++++++ docs/installation_zh.md | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/docs/installation.md b/docs/installation.md index dab72278..f372b0e3 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -160,6 +160,12 @@ type ga If it resolves to something unexpected, do not rely on the shortcut. Run GA from the install directory with `python launch.pyw` or `python frontends/tuiapp_v2.py`. +#### Windows Defender blocks local loopback + +The desktop app talks to its local bridge over `127.0.0.1` / `localhost`. On some Windows machines, Windows Defender Firewall may block this loopback connection, making the desktop app look like it cannot start or cannot connect to the service. + +If this happens, allow `GenericAgent.exe` and the bundled `python.exe` through Windows Defender Firewall, then restart the desktop app. + #### Windows TUI rendering issues TUI rendering on Windows depends on terminal, font, and `textual` version. diff --git a/docs/installation_zh.md b/docs/installation_zh.md index c124cc7b..485d2688 100644 --- a/docs/installation_zh.md +++ b/docs/installation_zh.md @@ -160,6 +160,12 @@ type ga 如果解析到意料之外的位置，就不要依赖这个快捷命令。请进入安装目录运行 `python launch.pyw` 或 `python frontends/tuiapp_v2.py`。 +#### Windows Defender 拦截本机回环网络 + +桌面端会通过 `127.0.0.1` / `localhost` 连接本机 bridge 服务。部分 Windows 机器上，Windows Defender 防火墙可能会拦截这个本机回环连接，导致桌面端看起来无法启动，或一直连不上服务。 + +如果遇到这种情况，请在 Windows Defender 防火墙中允许 `GenericAgent.exe` 和随包的 `python.exe` 通过，然后重启桌面端。 + #### Windows 上 TUI 显示异常 TUI 在 Windows 上依赖终端、字体和 `textual` 版本。