第一步，检查基本前提（最常见原因）

openclaw OpenClaw手册 2026-04-09 1

系统版本兼容性
- OpenClaw 主要面向 macOS 和 Linux。
- 如果你是 macOS 用户，请确认你的系统版本，某些版本（尤其是较新的 macOS Sonoma, Sequoia）可能需要更新版本的 OpenClaw 或特定的运行库。苹果 Silicon (M1/M2/M3) 芯片 的用户可能需要通过 Rosetta 2 运行，或者寻找原生 ARM 版本。
- 如果你是 Windows 用户，原生版本可能不稳定，建议使用 WSL2（Windows Subsystem for Linux）在 Linux 环境中运行，这是最可靠的方式。
应用来源与权限
- 首次运行时，macOS 可能会阻止未签名的应用。
  - 去 系统设置 -> 隐私与安全性 -> 在“安全性”部分，看是否有关于“OpenClaw”的拦截提示，点击“仍要打开”。
- 如果是从终端运行,请确保你进入了正确的目录，并对启动脚本有执行权限。
```
# 在OpenClaw所在目录下，给启动脚本添加执行权限
chmod +x OpenClaw-Pisces  # 或者具体的脚本名
```

第二步：检查并安装依赖（关键步骤）

OpenClaw 依赖于 Python 和一些第三方库，如果缺少依赖，启动后会立刻闪退。

确认 Python 版本
- 打开终端,输入 python3 --version，OpenClaw 通常需要 Python 3.8 或更高版本，如果版本太低，需要升级。
安装或更新 Python 依赖
- 在 OpenClaw 的应用目录或解压的文件夹里，通常会有一个 requirements.txt 文件。
- 打开终端,导航到 OpenClaw 的目录，然后运行以下命令来安装所有依赖：
```
# 如果你是直接下载的源码或可执行文件包
pip3 install -r requirements.txt
# 如果提示权限不足，可以加上 --user 标志
pip3 install --user -r requirements.txt
# 或者使用虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate  # Windows (如果支持)
pip install -r requirements.txt
```
- 特别注意 PyQt5 或 PySide6 这样的图形界面库是否成功安装，有时它们需要系统额外的图形开发包。
  - macOS: brew install pyqt@5
  - Ubuntu/Debian: sudo apt-get install python3-pyqt5

这是最重要的一步，闪退的原因会以错误信息的形式显示在终端里。

打开终端。
使用 cd 命令导航到 OpenClaw 所在的目录。
```
cd /path/to/your/OpenClaw-Pisces
```
尝试启动。
- 如果是可执行文件：
```
./OpenClaw-Pisces
```
- 如果是 Python 脚本：
```
python3 openclaw.py  # 或主脚本的名称
```
仔细阅读终端里输出的（通常是红色的）错误信息，这能直接定位问题。
- 示例1：ModuleNotFoundError: No module named 'xxx' -> 说明缺少 xxx 这个 Python 包，用 pip3 install xxx 安装即可。
- 示例2：与 libomp 或 Qt 相关错误 -> 可能是图形库问题，尝试重新安装或更新 PyQt5/PySide6。
- 示例3：[ERROR] Can‘t load ... model -> 可能是模型文件缺失或路径不对，检查 models 文件夹是否完整。

macOS (Apple Silicon M系列芯片):
- 尝试通过 Rosetta 2 运行，找到应用（或终端），右键点击 -> 显示简介 -> 勾选 使用 Rosetta 打开，然后再次运行。
- 如果从源码运行,确保所有原生依赖（如 numpy, grpcio）都安装了 ARM 版本。
Linux:
- 确保安装了系统级的图形和开发库,例如在 Ubuntu 上：
```
sudo apt-get install libgl1-mesa-glx libxcb-xinerama0
```
Windows:
- 强烈建议使用 WSL2 (Ubuntu)，在 WSL2 的 Ubuntu 环境中，按照 Linux 的步骤安装 Python 和依赖，再运行。