企业官网建设流程全解析

简介：这份资源面向在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 原生支持 C++17 文件系统库，省去了手动升级编译器的麻烦。

我一般会先确认三件事：内核版本、显卡驱动版本、以及是否装了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.2，525 对应 CUDA 12.0，470 对应 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 python=3.10 -y conda activate openclaw # 先装 CUDA Toolkit 和 cuDNN，让 conda 处理依赖 conda install cudatoolkit=12.1 cudnn=8.9 -c conda-forge -y # 再装 PyTorch，注意 index-url 要和 CUDA 版本匹配 pip install torch==2.1.0 torchvision==0.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的逻辑并不复杂，但有几个地方容易出问题。它首先用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 没关系，但它的图像预处理模块依赖 OpenCV，OpenCV 又依赖这些底层图形库。缺一个就是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，把-std=c++14改成-std=c++17，因为 Ubuntu 22.04 的 GCC 11 默认用 C++17，而旧代码里的某些语法在 C++14 下才能编译。手动改也就一行的事，比折腾补丁快。

提示：打完补丁后先跑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 torch==2.1.0 torchvision==0.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 cudnn=8.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-gpu=1.7.2 -c pytorch -y

如果 conda 源里也没有匹配的版本，退而求其次装faiss-cpu，OpenClaw 的索引构建在 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_PLATFORM=offscreen让 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_path="assets/test.jpg", batch_size=1, device="cuda:0", conf_threshold=0.5, # 置信度阈值，低于此值的结果被过滤 iou_threshold=0.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.yaml

environment_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，建议把版本锁定和隔离这两件事当成硬性步骤，别等翻车了再补。希望帮到你。

本文还有配套的精品资源，点击获取