请按照以下步骤逐一排查和解决

openclaw AI使用帮助 2026-04-09 3

基础检查（所有平台都适用）

确认文件完整性：
- 重新下载：网络中断可能导致文件下载不完整，请尝试从官方网站或可信的源码仓库（如GitHub） 重新下载一次。
- 检查文件格式：确认你下载的是否是正确的安装包。
  - Windows：通常是 .exe、.msi 或 .zip 文件。
  - macOS：通常是 .dmg 或 .pkg 文件。
  - Linux：可能是 .AppImage、.deb、.rpm 或源码压缩包。
- 校验哈希值：如果项目页面提供了SHA256或MD5校验码，使用工具校验你下载的文件是否匹配,以确保文件未被损坏。
以管理员/root权限运行：
- Windows：右键点击安装程序，选择 “以管理员身份运行”。
- macOS/Linux：在终端中使用 sudo 命令执行安装脚本。
关闭安全软件：

暂时禁用杀毒软件、Windows Defender（实时保护）或防火墙，有时它们会误报开源软件为威胁而阻止安装,安装完成后可以重新启用。

解压缩包：
- 如果下载的是 .zip 或 .7z 文件，你需要先解压，使用WinRAR、7-Zip或系统自带的解压工具,安装文件可能在解压后的文件夹里。
- 绿色版：有些开源软件是“便携版”（Portable），解压后直接运行主程序（如 .exe 文件）即可,无需传统安装。
安装运行库：
- 许多开源工具依赖微软的运行库，如 Visual C++ Redistributable。
- 前往微软官方下载并安装最新的 Visual C++ Redistributable for Visual Studio（根据系统选择x86或x64版本）。
- 也可能需要 .NET Framework 或 Java Runtime,请根据OpenClaw项目的要求安装。
兼容性模式：
- 右键点击安装程序 -> 属性 -> 兼容性选项卡。
- 尝试勾选“以兼容模式运行这个程序”，并选择一个较早的Windows版本（如Windows 8或7）。

允许来自不明开发者的应用：
- 前往 系统设置 > 隐私与安全性。
- 在“安全性”部分，如果看到一个提示说“已阻止使用……”，点击 “仍要打开”。
- 或者，首次运行时，在Finder中右键点击应用，选择“打开”,然后在弹出的对话框中确认。
检查是否为ARM架构原生应用：

如果软件是为Intel芯片编译的，而你的Mac是Apple Silicon（M1/M2/M3），可能需要通过Rosetta 2转译运行，可以尝试右键点击应用 -> 显示简介 -> 勾选“使用Rosetta打开”。

赋予执行权限：
- 如果下载的是二进制文件或脚本，在终端中进入文件所在目录，运行：
```
chmod +x 文件名
```
- 然后尝试运行：./文件名

安装依赖包：

对于Debian/Ubuntu：

sudo apt update
sudo apt install -f
# 如果项目提供了.deb包但安装失败，用上面命令修复依赖。
# 通常还需要安装通用依赖，
sudo apt install libgtk-3-0 libsdl2-2.0-0 libgl1

使用包管理器：

优先检查软件是否已存在于你的发行版仓库中：

sudo apt search openclaw    # Debian/Ubuntu
sudo dnf search openclaw    # Fedora
yay -Ss openclaw            # Arch Linux (AUR)

查看具体错误信息：
- Windows：安装失败时通常会弹出错误代码或描述，记下来,去搜索引擎或项目Issues页面搜索。
- 命令行/终端：尝试在命令提示符（Windows）或终端（macOS/Linux）中启动安装程序，这样可以看到详细的错误输出,便于诊断。
检查项目文档：
- 前往项目的 GitHub/GitLab页面、官方网站或Wiki，仔细阅读 README.md、INSTALL 或 BUILD 文件,里面通常有详细的平台安装说明和前提条件。
寻求社区帮助：
- 前往项目的 Issues页面（通常在GitHub上），用英文或中文（如果项目是国内的）搜索是否有其他人遇到相同问题。
- 如果找不到，可以发一个新Issue，务必提供以下信息：
  - 操作系统及版本（如Windows 11 23H2, Ubuntu 22.04）
  - 下载的OpenClaw具体版本号
  - 你尝试过的步骤
  - 完整的错误信息截图或文本