Ubuntu/Debian

我来为你整理一份详细的 AI小龙虾OpenClaw安装教程和避坑指南，OpenClaw是一个基于深度学习的机械臂抓取项目，安装过程涉及多个依赖，需要仔细操作。

📋 一、安装前准备

系统要求

• 推荐系统：Ubuntu 20.04/22.04（最佳兼容性）
• Windows可用但需要更多配置（建议WSL2）
• Python 3.8-3.10
• GPU支持：建议NVIDIA显卡（CUDA 11.3-12.1）

必要工具安装

sudo apt install -y git cmake build-essential python3-pip
sudo apt install -y libopencv-dev libeigen3-dev
# Windows
# 1. 安装Visual Studio 2019/2022（包含C++工具）
# 2. 安装CMake：https://cmake.org/download/
# 3. 安装Git：https://git-scm.com/

🚀 二、详细安装步骤

步骤1：克隆仓库

git clone https://github.com/OpenClaw/OpenClaw.git
cd OpenClaw
# 如果GitHub慢，可以使用国内镜像：
# git clone https://gitee.com/mirrors_openclaw/OpenClaw.git

步骤2：创建Python虚拟环境

# 使用conda（推荐）
conda create -n openclaw python=3.8
conda activate openclaw
# 或使用venv
python -m venv openclaw_env
source openclaw_env/bin/activate  # Linux
# Windows: openclaw_env\Scripts\activate

步骤3：安装PyTorch

# 查看CUDA版本
nvidia-smi
# 根据CUDA版本选择对应命令（以CUDA 11.8为例）
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
# CPU版本（无GPU时）
# pip3 install torch torchvision torchaudio

步骤4：安装核心依赖

pip install -r requirements.txt
# 如果requirements.txt不存在或安装失败，手动安装：
pip install numpy==1.21.0
pip install opencv-python==4.5.5.64
pip install scipy==1.7.3
pip install pybullet==3.2.5
pip install transforms3d
pip install trimesh
pip install pyyaml
pip install matplotlib

步骤5：编译安装（关键步骤）

# 创建build目录
mkdir build && cd build
# 配置（注意Python路径）
cmake .. -DPYTHON_EXECUTABLE=$(which python)
# 编译
make -j$(nproc)  # Linux
# Windows: 用VS打开生成的.sln文件编译
# 安装Python绑定
cd ../python
pip install -e .

⚠️ 三、常见坑点及解决方案

坑1：CMake找不到Python

CMake Error: Could NOT find PythonLibs

解决方案：

# 指定Python路径
cmake .. -DPYTHON_EXECUTABLE=/usr/bin/python3.8 \
         -DPYTHON_INCLUDE_DIR=/usr/include/python3.8 \
         -DPYTHON_LIBRARY=/usr/lib/x86_64-linux-gnu/libpython3.8.so

坑2：PyTorch与CUDA版本不匹配

RuntimeError: CUDA error: no kernel image is available for execution

解决方案：

1. 确认CUDA版本：nvidia-smi
2. 访问PyTorch官网获取正确安装命令：https://pytorch.org/get-started/locally/
3. 卸载重装：

   pip uninstall torch torchvision torchaudio
   # 重新安装对应版本

坑3：缺少动态库

ImportError: libxxxx.so.x: cannot open shared object file

解决方案：

# 查找缺失的库
ldd /path/to/your/library.so | grep not found
# 安装对应开发包
sudo apt install libgl1-mesa-glx libegl1-mesa libxrandr2
sudo apt install libxss1 libxcursor1 libxcomposite1 libasound2

坑4：权限问题

Permission denied: /dev/ttyUSB0

解决方案：

# 添加用户到dialout组（串口设备）
sudo usermod -a -G dialout $USER
# 重新登录生效

坑5：模型文件下载慢

解决方案：

1. 使用国内镜像源手动下载预训练模型
2. 修改代码中的下载链接为国内镜像
3. 在~/.bashrc添加：

   export HF_ENDPOINT=https://hf-mirror.com
   export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

🔧 四、验证安装

测试脚本

# test_installation.py
import torch
import cv2
import numpy as np
import openclaw  # 测试是否成功导入
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)}")
# 测试OpenCV
img = np.random.randint(0, 255, (100, 100, 3), dtype=np.uint8)
print(f"OpenCV版本: {cv2.__version__}")
print("✅ 所有依赖检查通过！")

运行示例

# 测试抓取演示
python examples/simple_grasp.py
# 如果没有硬件，测试仿真
python examples/simulation_test.py

📁 五、项目结构说明

OpenClaw/
├── core/           # 核心算法
├── models/         # 神经网络模型
├── utils/          # 工具函数
├── hardware/       # 硬件接口
├── sim/            # 仿真环境
├── configs/        # 配置文件
└── examples/       # 示例代码

💡 实用技巧

使用Docker简化安装

# 使用官方镜像
docker pull openclaw/openclaw:latest
docker run -it --gpus all openclaw/openclaw:latest

开发模式安装

# 可编辑模式安装，便于修改代码
pip install -e .

网络问题解决方案

# 使用国内pip源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
# Git克隆加速
git config --global url."https://ghproxy.com/https://github.com".insteadOf https://github.com

快速排错命令

# 查看所有Python包版本
pip list
# 检查CUDA环境
python -c "import torch; print(torch.cuda.is_available())"
# 验证编译
cd build && ctest -V

🆘 六、遇到问题怎么办

1. 查看Issues：先到GitHub Issues搜索类似问题
2. 检查日志：运行时有--verbose参数加详细日志
3. 版本回退：如果新版本有问题，尝试切换到稳定tag：

   git checkout v1.0.0  # 使用稳定版本

4. 寻求帮助：
   • GitHub Discussions
   • 项目Discord/Slack频道
   • 相关论文作者邮箱

📝 七、安装检查清单

• [ ] 系统满足要求（Ubuntu 20.04+）
• [ ] NVIDIA驱动和CUDA安装正确
• [ ] 虚拟环境创建并激活
• [ ] PyTorch与CUDA版本匹配
• [ ] 所有依赖包安装成功
• [ ] CMake编译无错误
• [ ] Python绑定安装成功
• [ ] 示例程序能正常运行

按照这个指南一步步操作,应该能顺利安装OpenClaw，如果遇到未涵盖的问题，建议查看项目的最新文档和Issues。