OpenHands/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/usage/troubleshooting/windows.md

Windows 和 WSL 用户须知

OpenHands 仅支持通过 WSL 在 Windows 上运行。 请确保在 WSL 终端内运行所有命令。

故障排除

错误：在此 WSL 2 发行版中找不到 'docker'。

如果您使用的是 Docker Desktop，请确保在 WSL 内部调用任何 docker 命令之前启动它。 Docker 还需要启用 WSL 集成选项。

建议：不要以 root 用户身份运行

出于安全原因，非常建议不要以 root 用户身份运行 OpenHands，而是使用 UID 非零的用户身份运行。 此外，当以 root 身份运行时，不支持持久化沙箱，并且在启动 OpenHands 时可能会出现相应消息。

参考资料：

• 为什么以 root 登录是不好的
• 在 WSL 中设置默认用户 关于第二个参考资料的小提示：对于 Ubuntu 用户，该命令实际上可能是 "ubuntupreview" 而不是 "ubuntu"。

创建 openhands 用户失败

如果您在设置过程中遇到以下错误：

Exception: Failed to create openhands user in sandbox: 'useradd: UID 0 is not unique'

您可以通过运行以下命令解决：

export SANDBOX_USER_ID=1000

Poetry 安装

• 如果在构建过程中安装 Poetry 后仍然面临运行 Poetry 的问题，您可能需要将其二进制路径添加到您的环境变量：

export PATH="$HOME/.local/bin:$PATH"

• 如果 make build 停止并出现如下错误：

ModuleNotFoundError: no module named <module-name>

这可能是 Poetry 缓存的问题。 尝试运行以下两个命令：

rm -r ~/.cache/pypoetry
make build

NoneType 对象没有属性 'request'

如果您在执行 make run 时遇到与网络相关的问题，例如 NoneType object has no attribute 'request'，您可能需要配置您的 WSL2 网络设置。请按照以下步骤操作：

• 打开或创建位于 Windows 主机机器上的 C:\Users\%username%\.wslconfig 文件。
• 向 .wslconfig 文件添加以下配置：

[wsl2]
networkingMode=mirrored
localhostForwarding=true

• 保存 .wslconfig 文件。
• 通过退出所有正在运行的 WSL2 实例并在命令提示符或终端中执行 wsl --shutdown 命令，完全重启 WSL2。
• 重新启动 WSL 后，尝试再次执行 make run。 网络问题应该已经解决。