WinClaw Docs

本章节收录了 WinClaw 使用过程中常见的错误情况及其解决方法。

服务启动失败

启动 WinClaw 后，如果浏览器中出现如下页面，说明后台引擎服务未能正常启动：

服务启动失败诊断页面

页面会列出几种可能原因：

页面列出的只是可能的原因。要知道实际出了什么问题，需要查看引擎日志：

打开文件管理器，导航到以下路径，用文本编辑器打开 app.log：

C:\Users\<用户名>\.auto-coder-rag\logs\app.log

将 <用户名> 替换为你的 Windows 用户名，例如 C:\Users\Alice\.auto-coder-rag\logs\app.log

日志文件会记录引擎启动过程中的详细错误信息，可以看到具体是哪一步失败了。

Windows 路径长度限制（首要排查项）

Windows 10 默认限制路径最大长度为 260 个字符。WinClaw 在解压安装包时，部分内置文件的路径较长，超出限制后会导致解压失败或文件不完整，进而引起服务启动失败。

解决方法：以管理员权限打开命令提示符，执行以下命令启用长路径支持：

第一步：以管理员身份打开命令提示符

点击开始菜单，在搜索框中输入"命令提示符"，右键点击搜索结果，选择**"以管理员身份运行"**：

在开始菜单搜索命令提示符并以管理员身份运行

第二步：执行注册表命令

在打开的管理员命令提示符窗口中，输入以下命令并按回车：

reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f

看到 The operation completed successfully. 提示即表示成功：

执行命令成功，提示 The operation completed successfully

执行成功后，重新安装 WinClaw 即可。

端口 9199 被占用

日志中出现类似 Address already in use 或 port 9199 字样时，说明有其他程序占用了该端口。

打开任务管理器，找到占用端口的进程并结束它，然后重新启动 WinClaw。或者在命令行中执行：

netstat -ano | findstr :9199

找到对应的 PID 后，在任务管理器中结束该进程。

防火墙或安全软件拦截

如果日志中出现连接被拒绝相关的错误，请暂时关闭防火墙或安全软件后重试。若确认是安全软件导致的，将 WinClaw 添加到白名单即可。

服务包安装不完整

如果日志提示找不到某个模块或文件，尝试重新安装 WinClaw：先完整卸载，清理残留文件后重新下载安装最新版本。

Python 环境问题

WinClaw 依赖内置的 Python 环境，通常无需用户手动安装。如果日志中出现 Python 相关错误，请确认安装包是否完整下载（未被杀毒软件拦截或下载中断）。

将 app.log 的内容发送给官方支持，可以更快定位问题：