OpenClaw 安装环境检测指南

先检测，后安装，治未病

在运行 pip install 或执行任何安装脚本之前，请按照以下流程进行检查，流程图概括了核心步骤：

flowchart TD
    A[开始环境检测] --> B[基础环境检查<br>OS/Python/包管理器]
    B --> C{是否通过？}
    C -- 否 --> D[修复问题后重试]
    C -- 是 --> E[依赖项检查<br>PyTorch/CUDA/系统库]
    E --> F{是否通过？}
    F -- 否 --> D
    F -- 是 --> G[硬件与驱动检查<br>GPU/CUDA/cuDNN]
    G --> H{是否通过？}
    H -- 否 --> D
    H -- 是 --> I[🎉 环境准备就绪<br>开始安装OpenClaw]

第一阶段：基础系统环境检查

1. 操作系统确认

   • 推荐: Ubuntu 20.04/22.04 LTS, CentOS 7/8, Windows 10/11, macOS (注意：ARM架构的Mac可能有限制)。
   • 检查命令:
     • Linux: lsb_release -a 或 cat /etc/os-release
     • Windows: 系统信息或 winver
     • macOS: sw_vers

2. Python 版本

   • 要求: 通常为 Python 3.8 至 3.10（具体以项目README为准），Python 3.11+ 可能面临部分包不兼容。
   • 检查命令:

     python --version
     # 或
     python3 --version

   • 行动: 如果版本不符，使用 conda 或 pyenv 创建指定版本的虚拟环境。

3. 包管理器

   • pip: 确保是最新版本。

     python -m pip install --upgrade pip

   • conda (可选但推荐): 如果使用Anaconda/Miniconda管理环境。

     conda --version

4. 虚拟环境

   • 强烈建议 在隔离的虚拟环境中安装，避免污染系统Python。
   • 创建与激活:
     • venv (Python内置):

       python -m venv openclaw_env
       # Linux/macOS
       source openclaw_env/bin/activate
       # Windows
       openclaw_env\Scripts\activate

     • conda:

       conda create -n openclaw_env python=3.9
       conda activate openclaw_env

第二阶段：关键依赖项预检

在安装OpenClaw之前,手动检查并安装一些可能通过系统包管理器更易管理的依赖。

1. 系统级开发工具

   • Linux (Ubuntu/Debian):

     sudo apt-get update
     sudo apt-get install build-essential cmake git wget
     # 可能需要的额外库
     sudo apt-get install libgl1-mesa-glx libglib2.0-0 libsm6 libxrender1 libxext6

   • macOS:

     xcode-select --install # 安装命令行工具
     brew install cmake git wget

   • Windows: 确保已安装 Visual Studio Build Tools 和 CMake。

2. PyTorch 与 CUDA 兼容性 (重中之重)

   • 步骤:
     1. 确定CUDA版本 (如有NVIDIA GPU):

        nvidia-smi

        查看右上角显示的 CUDA Version，这是驱动支持的最高CUDA版本。

     2. 访问 PyTorch 官网，根据你的CUDA版本或“CPU”选择安装命令。
     3. 先单独安装PyTorch，验证成功后再安装OpenClaw。

        # 示例：CUDA 11.8
        pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
        # 示例：CPU版本
        pip3 install torch torchvision torchaudio

     4. 验证PyTorch及CUDA:

        python -c "import torch; print(f'PyTorch版本: {torch.__version__}'); print(f'CUDA可用: {torch.cuda.is_available()}'); if torch.cuda.is_available(): print(f'GPU设备: {torch.cuda.get_device_name(0)}')"

第三阶段：硬件与驱动专项检查 (针对GPU用户)

1. NVIDIA 驱动

   • 检查: nvidia-smi 应能正常输出，且驱动版本足够新。
   • 更新: 通过系统驱动管理器、NVIDIA官网或conda (conda install cuda -c nvidia) 更新。

2. CUDA Toolkit 与 cuDNN

   • PyTorch通常自带所需CUDA运行时库,但如果你需要从源码编译其他组件，可能需要完整CUDA Toolkit。
   • 检查CUDA编译器:

     nvcc --version

   • 检查cuDNN (较复杂，通常与CUDA捆绑): 确保与PyTorch要求的版本匹配。

第四阶段：安装OpenClaw并验证

1. 获取代码

   git clone https://github.com/作者/OpenClaw.git
   cd OpenClaw

2. 安装项目依赖

   • 仔细阅读 requirements.txt 或 setup.py。
   • 建议逐步安装,特别是大型包。

     pip install -r requirements.txt
     # 或者，如果使用开发模式
     pip install -e .

3. 运行基础测试/示例

   • 寻找项目中的 examples/ 或 tests/ 目录，运行一个最简单的脚本，确保核心功能无报错。

     python examples/minimal_demo.py

常见问题与排查清单

终极建议

• 逐行阅读 项目的 README.md 和 INSTALL.md，开发者通常会写明特定要求。
• 使用Docker：如果项目提供 Dockerfile 或推荐使用Docker，这是最能保证环境一致性的方式。

  docker build -t openclaw .
  docker run --gpus all -it openclaw

按照此指南系统性地检查,可以解决99%的环境问题，祝你顺利安装AI小龙虾OpenClaw！