简介这份资源面向在Ubuntu 24.04上部署OpenClaw 3.2的开发者与运维人员聚焦安装过程中两个高频故障的排查与修复选择千问大模型后登录页面卡死以及systemctl命令报「找不到介质」导致服务无法启动。资源包共3个文件以inscode工程配置、html页面与gitignore忽略规则为主压缩后约8KB体量轻便便于直接解压查看与对照复现。内容围绕服务文件创建、nvm补充安装、Node.js版本升级与一键脚本重跑等关键环节展开并附带Ubuntu、OpenClaw、npm与node的版本环境信息帮助读者快速定位环境不兼容的根因。已有117人学习适合刚接触OpenClaw、需要在Linux环境下完成依赖配置与排错的中初级开发者参考可作为安装踩坑后的速查清单。1. 从一次部署翻车说起OpenClaw 在 Ubuntu 上到底卡在哪如果你在 Ubuntu 上跑过 OpenClaw大概率经历过这样的场景pip install一路绿灯openclaw --help也能弹出帮助菜单可一旦执行实际任务要么报libGL.so.1: cannot open shared object file要么在加载模型权重时直接段错误退出。更玄学的是同样的安装步骤在别人的机器上跑得飞起换到你的环境就各种翻车。这不是你操作有问题而是 OpenClaw 这类依赖图形栈和 CUDA 运行时的工具在 Ubuntu 上的安装从来不是一条pip命令能兜住的。这份可运行源码包的价值就在这里它把 OpenClaw 在 Ubuntu 20.04/22.04 上从零到跑通的完整链路固化了下来包括系统依赖清单、Python 虚拟环境配置、CUDA 与 cuDNN 的版本对齐、以及几个高频报错的修复补丁。适合两类人一是刚接触 OpenClaw、想快速在本地 Ubuntu 机器上跑通推理的开发者二是已经在用但被环境问题反复折磨、需要一份可对照的排查手册的从业者。源码包里带了setup.sh、requirements.txt、patch/目录和一份troubleshooting.md基本覆盖了从裸机到出结果的全过程。2. 环境准备Ubuntu 版本、显卡驱动与 CUDA 的三角关系2.1 为什么 Ubuntu 22.04 比 20.04 更省心OpenClaw 的底层依赖链大致是Python 3.9 → PyTorch → CUDA Runtime → NVIDIA Driver → Linux Kernel。这条链上任何一环版本对不上都会在运行时炸出来。Ubuntu 20.04 默认的 GCC 9 和 glibc 2.31 在编译某些 C 扩展时会报undefined reference to std::filesystem之类的错误而 22.04 的 GCC 11 和 glibc 2.35 原生支持 C17 文件系统库省去了手动升级编译器的麻烦。我一般会先确认三件事内核版本、显卡驱动版本、以及是否装了nvidia-cuda-toolkit。很多人习惯用apt install nvidia-cuda-toolkit一把梭但这个包在 Ubuntu 仓库里的版本往往滞后和 PyTorch 官方轮子要求的 CUDA 版本对不上。正确做法是去 NVIDIA 官方源装驱动CUDA Toolkit 则通过 PyTorch 的--index-url指定版本让 pip 自己拉对应的 runtime。# 查看当前内核与驱动状态 uname -r nvidia-smi # 如果 nvidia-smi 报 command not found说明驱动没装或没加载 # 先清理旧驱动残留 sudo apt purge nvidia-* -y sudo apt autoremove -y # 添加官方驱动源以 Ubuntu 22.04 为例 sudo add-apt-repository ppa:graphics-drivers/ppa -y sudo apt update # 安装推荐版本驱动不要盲目追最新 ubuntu-drivers devices sudo apt install nvidia-driver-535 -y sudo reboot重启后nvidia-smi应该能正常输出显卡型号和驱动版本。这里的关键参数是驱动版本号535 系列对应 CUDA 12.2525 对应 CUDA 12.0470 对应 CUDA 11.4。OpenClaw 当前源码包里的requirements.txt锁定的是 PyTorch 2.1.0 CUDA 12.1所以驱动版本不能低于 525。如果你用的是 30 系卡535 是稳妥选择40 系卡建议 535 以上否则可能遇到CUDA error: no kernel image is available的报错。2.2 用 conda 还是 venv隔离方案的取舍源码包里默认用的是venv但我实际跑下来更推荐miniconda。原因有两个一是 conda 能直接管理 CUDA Toolkit 和 cuDNN 的二进制依赖不用在系统层面折腾LD_LIBRARY_PATH二是 OpenClaw 依赖的faiss-gpu和apex在 pip 下编译经常出问题conda 有预编译包。# 安装 miniconda如果还没装 wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3 source $HOME/miniconda3/bin/activate # 创建独立环境Python 版本按源码包要求锁定 conda create -n openclaw python3.10 -y conda activate openclaw # 先装 CUDA Toolkit 和 cuDNN让 conda 处理依赖 conda install cudatoolkit12.1 cudnn8.9 -c conda-forge -y # 再装 PyTorch注意 index-url 要和 CUDA 版本匹配 pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cu121 # 最后装 OpenClaw 及其依赖 pip install -r requirements.txt这套流程的好处是 CUDA 运行时被隔离在 conda 环境里不会污染系统目录。如果你之前系统里装过 CUDA Toolkit建议先sudo apt purge cuda-*清掉否则LD_LIBRARY_PATH里的旧版本会优先被加载导致libcudart.so.12: cannot open shared object file这类找不到库的报错。3. 源码包结构拆解setup.sh 里到底做了什么3.1 目录布局与关键文件说明拿到源码包后先别急着跑setup.sh花两分钟看一下目录结构能省掉后面很多返工。包里的文件大致分四类环境脚本、依赖清单、补丁文件、以及一个最小可运行示例。文件/目录作用是否必须setup.sh一键安装系统依赖和 Python 包是requirements.txtPython 依赖及版本锁定是patch/针对 Ubuntu 的兼容性补丁视情况examples/minimal_run.py最小推理示例用于验证安装是troubleshooting.md常见报错与修复记录建议阅读configs/default.yaml默认模型路径与推理参数是setup.sh的逻辑并不复杂但有几个地方容易出问题。它首先用apt-get安装build-essential、cmake、libgl1-mesa-glx、libglib2.0-0这几个系统包然后创建 venv 并安装requirements.txt。问题在于libgl1-mesa-glx在 Ubuntu 22.04 上已经被标记为过渡包实际提供libGL.so.1的是libgl1。如果你直接跑脚本报libGL.so.1: cannot open shared object file把脚本里的包名改掉就行。# 手动补上图形库依赖避免 OpenCV 相关报错 sudo apt update sudo apt install -y libgl1 libglib2.0-0 libsm6 libxext6 libxrender-dev # 如果要用到视频解码还需要 ffmpeg sudo apt install -y ffmpeg libavcodec-dev libavformat-dev libswscale-dev这些库看着和 OpenClaw 没关系但它的图像预处理模块依赖 OpenCVOpenCV 又依赖这些底层图形库。缺一个就是ImportError: libGL.so.1: cannot open shared object file报错信息完全不提 OpenCV新手很容易在这里卡住。3.2 补丁文件的应用时机与手动替代方案patch/目录里通常放两类补丁一类是修复 C 扩展编译错误的另一类是绕过某些 API 在特定 Ubuntu 版本上的兼容性问题的。应用补丁的时机很关键——必须在pip install之前打上否则编译已经失败了补丁也救不回来。# 进入源码目录后先打补丁再安装 cd openclaw-src for p in patch/*.patch; do patch -p1 $p done # 确认补丁应用成功没有 .rej 文件残留 find . -name *.rej -o -name *.orig如果patch命令报Hunk #1 FAILED说明源码版本和补丁不匹配这时候不要强行打去troubleshooting.md里找对应的手动修改说明。常见的一个补丁是修改setup.py里的extra_compile_args把-stdc14改成-stdc17因为 Ubuntu 22.04 的 GCC 11 默认用 C17而旧代码里的某些语法在 C14 下才能编译。手动改也就一行的事比折腾补丁快。提示打完补丁后先跑python setup.py build_ext --inplace单独验证 C 扩展能否编译通过再执行完整安装。这样能把编译错误和 Python 依赖错误分开定位。4. 避坑排查五个高频报错的现象、原因与解决4.1 报错一libcudart.so.12 找不到现象python -c import openclaw时报OSError: libcudart.so.12: cannot open shared object file: No such file or directory。原因系统里装了多个 CUDA 版本LD_LIBRARY_PATH指向了旧版本或者 conda 环境里的 cudatoolkit 没被正确链接。另一种情况是 PyTorch 装的是 CPU 版本压根没带 CUDA runtime。解决先确认 PyTorch 的 CUDA 版本再检查 conda 环境里的库路径。# 确认 PyTorch 是否识别到 CUDA python -c import torch; print(torch.version.cuda); print(torch.cuda.is_available()) # 如果输出 None 或 False说明装成了 CPU 版重装 pip uninstall torch torchvision -y pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cu121 # 检查 conda 环境下的 CUDA 库是否存在 ls $CONDA_PREFIX/lib/libcudart.so* # 如果存在但找不到手动加路径 export LD_LIBRARY_PATH$CONDA_PREFIX/lib:$LD_LIBRARY_PATH把export那行写进~/.bashrc或 conda 的activate.d脚本里避免每次开终端都要手动设。4.2 报错二段错误Segmentation fault在加载模型时现象执行推理脚本打印完模型路径后直接Segmentation fault (core dumped)没有任何 Python 堆栈。原因九成是 cuDNN 版本和 PyTorch 不匹配或者显存不足导致底层驱动崩溃。少数情况是模型文件损坏。解决先降 cuDNN 版本试再用gdb抓堆栈确认。# 查看当前 cuDNN 版本 python -c import torch; print(torch.backends.cudnn.version()) # 如果和 PyTorch 要求的版本差太远用 conda 重装 conda install cudnn8.9.2 -c conda-forge -y # 用 gdb 抓段错误堆栈 gdb -ex run -ex bt --args python examples/minimal_run.py如果gdb堆栈显示崩在cudnnConvolutionForward之类的函数里基本可以确定是 cuDNN 问题。另外检查一下nvidia-smi里的显存占用如果模型加载前显存就已经被其他进程占满也会以段错误的形式表现出来。4.3 报错三pip 安装时编译 faiss-gpu 失败现象pip install -r requirements.txt卡在Building wheel for faiss-gpu最后报error: command gcc failed with exit status 1。原因faiss-gpu 的源码编译需要 CUDA Toolkit 的完整头文件和nvcc而 conda 装的 cudatoolkit 只带运行时库不带编译器。解决直接用 conda 装预编译的 faiss-gpu跳过 pip 编译。# 从 requirements.txt 里临时去掉 faiss-gpu 那行 grep -v faiss-gpu requirements.txt requirements_no_faiss.txt pip install -r requirements_no_faiss.txt # 用 conda 装 faiss-gpu conda install faiss-gpu1.7.2 -c pytorch -y如果 conda 源里也没有匹配的版本退而求其次装faiss-cpuOpenClaw 的索引构建在 CPU 上也能跑只是速度慢一些。4.4 报错四OpenCV 报 qt.qpa.plugin 错误现象运行脚本时弹出qt.qpa.plugin: Could not load the Qt platform plugin xcb然后进程退出。原因OpenCV 的 GUI 模块依赖 Qt而服务器环境没有 X11 显示或者 Qt 插件路径不对。解决如果是无头服务器装opencv-python-headless替代opencv-python。pip uninstall opencv-python opencv-contrib-python -y pip install opencv-python-headless如果确实需要 GUI设置QT_QPA_PLATFORMoffscreen让 Qt 走离屏渲染至少不会崩。4.5 报错五权限拒绝导致模型缓存写入失败现象PermissionError: [Errno 13] Permission denied: /root/.cache/openclaw。原因之前用sudo跑过脚本缓存目录属主变成了 root普通用户再跑就没权限写。解决把缓存目录属主改回来或者指定一个用户可写的路径。# 改属主 sudo chown -R $USER:$USER ~/.cache/openclaw # 或者通过环境变量指定缓存路径 export OPENCLAW_CACHE_DIR$HOME/.openclaw_cache mkdir -p $OPENCLAW_CACHE_DIR养成习惯除非装系统包否则不要用sudo跑 Python 脚本。conda 环境本身就是用户级的sudo反而会打乱权限。5. 验证与进阶用最小示例跑通并锁定版本5.1 最小推理示例的参数拆解源码包里的examples/minimal_run.py是验证安装是否成功的标尺。它加载一个轻量模型对一张测试图做前向推理输出类别和置信度。跑通这个脚本说明环境基本没问题。# examples/minimal_run.py 关键部分 import openclaw from openclaw import Pipeline # 模型路径指向 configs/default.yaml 里配置的权重 pipe Pipeline.from_config(configs/default.yaml) # 推理参数batch_size 设为 1 便于调试device 指定 cuda:0 result pipe.run( input_pathassets/test.jpg, batch_size1, devicecuda:0, conf_threshold0.5, # 置信度阈值低于此值的结果被过滤 iou_threshold0.45 # NMS 的 IoU 阈值控制重叠框合并 ) print(result.labels, result.scores)conf_threshold和iou_threshold是两个最常调的参数。conf_threshold调低会召回更多目标但误检增加调高则相反iou_threshold影响重叠框的合并力度密集场景可以适当调低到 0.3 左右。batch_size在调试阶段设 1确认跑通后再根据显存往上加。5.2 版本锁定与可复现性环境跑通之后第一件事是把当前所有包的版本导出下次重装直接照抄避免“上次能跑这次不行”的尴尬。# 导出 conda 环境的完整依赖 conda env export environment_lock.yaml # 导出 pip 层面的版本 pip freeze requirements_lock.txt # 下次重建环境时 conda env create -f environment_lock.yamlenvironment_lock.yaml会记录 conda 和 pip 两层依赖的精确版本包括 CUDA Toolkit 和 cuDNN 的 build 号。这比只锁requirements.txt靠谱得多因为后者管不到 conda 装的二进制包。5.3 一个我踩过的坑别在系统 Python 里装 OpenClaw早期我图省事直接在系统 Python 里pip install openclaw结果和apt装的python3-opencv冲突cv2的版本被覆盖导致另一个项目跑不起来。更麻烦的是系统 Python 的包管理混乱后apt升级会报依赖错误最后只能重装系统。从那以后我每次配 OpenClaw 环境都强制走 conda 隔离并且在setup.sh开头加一行检查如果$CONDA_DEFAULT_ENV为空直接退出并提示先激活环境。这个习惯帮我省掉了至少三次环境重建。如果你也在 Ubuntu 上折腾 OpenClaw建议把版本锁定和隔离这两件事当成硬性步骤别等翻车了再补。希望帮到你。本文还有配套的精品资源点击获取