简介这份资源面向在Ubuntu 24.04上部署OpenClaw 3.2的开发者与运维人员聚焦安装过程中两个高频故障的排查与修复选择千问大模型后登录页面卡死以及systemctl命令报“找不到介质”导致服务无法启动。资源内含可运行源码共3个文件以inscode工程配置、html页面与gitignore忽略规则为主压缩包约8KB体量轻便便于直接对照复现问题场景。作者同时整理了环境配置参考涵盖Ubuntu、OpenClaw、npm与Node.js的版本信息并给出创建服务文件、补充安装nvm、升级Node.js、重跑一键安装脚本等排错思路帮助读者快速定位依赖缺失与配置错误。目前已有117人学习适合刚接触OpenClaw部署、需要一份可运行示例与故障对照清单的中级开发者参考。1. 在 Ubuntu 上装 OpenClaw为什么你会在第三步就卡住很多人第一次在 Ubuntu 上装 OpenClaw都会经历同一个剧本照着某篇教程敲完pip install终端刷出一屏红字然后开始怀疑人生。OpenClaw 这类带原生扩展的 Python 工具坑几乎从不在主程序本身而在依赖链、系统库版本和 Python 环境这三者的交叉点上。你在 Ubuntu 22.04 上跑得好好的命令换到 24.04 可能直接报GLIBC版本不匹配用系统自带的 Python 3.10 能过换成 conda 里的 3.12 又缺libGL。这篇笔记就是把这套安装流程从「碰运气」变成「可复现」从环境准备、依赖编译、源码运行到排错一步步拆开讲。适合两类人刚接触 OpenClaw 想在本机跑通的新手以及被依赖问题反复折磨、想搞清楚底层到底发生了什么的老手。2. 装之前先把环境摸清楚Ubuntu 版本、Python 与编译工具链2.1 为什么 Ubuntu 版本决定了你一半的安装难度OpenClaw 的安装难度和 Ubuntu 版本强相关核心原因是系统自带的glibc和gcc版本不同。Ubuntu 20.04 自带 glibc 2.31、gcc 9Ubuntu 22.04 是 glibc 2.35、gcc 11Ubuntu 24.04 则是 glibc 2.39、gcc 13。OpenClaw 的某些原生扩展在编译时会对 glibc 符号版本有要求如果你在 24.04 上编译好的 wheel 拿到 20.04 上跑大概率报version GLIBC_2.34 not found。反过来在 20.04 上编译的包在 24.04 上通常能跑因为高版本 glibc 向后兼容。我一般建议如果你只是本地跑通验证功能用 Ubuntu 22.04 LTS它的 glibc 和 gcc 版本处于中间地带绝大多数预编译 wheel 都能直接用遇到需要源码编译的依赖也不容易翻车。如果你必须用 24.04那就要做好部分依赖需要手动降级或从源码编译的心理准备。先确认你的系统信息# 查看 Ubuntu 版本和内核 lsb_release -a uname -r # 查看 glibc 版本关键 ldd --version | head -1 # 查看 gcc 版本 gcc --version | head -1 # 查看系统 Python 版本 python3 --version这几条命令的输出要记下来。后面遇到报错时第一件事就是对照这些版本号判断是 glibc 不匹配、gcc 太老还是 Python 版本不对。2.2 Python 环境隔离别用系统 Python 直接装Ubuntu 系统自带的 Python 是给系统工具用的直接往里装包有两个风险一是可能破坏系统依赖二是权限问题会让你被迫用sudo pip而sudo pip装出来的包路径混乱后面排查问题极其痛苦。正确做法是用venv或conda建独立环境。我习惯用venv轻量、不引入额外依赖# 安装 venv 和开发工具如果还没装 sudo apt update sudo apt install -y python3-venv python3-dev build-essential # 创建独立环境指定 Python 3.1022.04 自带 python3 -m venv ~/openclaw-env # 激活环境 source ~/openclaw-env/bin/activate # 确认当前 python 指向 venv 里的版本 which python python --version激活后你的终端提示符前面会出现(openclaw-env)说明环境隔离生效了。之后所有pip install都只影响这个环境不会污染系统。注意如果你用的是 conda创建环境时建议指定python3.10不要用 3.12。OpenClaw 的部分依赖在 3.12 上还没有预编译 wheel会触发源码编译而源码编译又可能因为缺少系统库而失败平白多出一堆问题。2.3 补齐系统级依赖那些 pip 装不上的库Python 包管理只管 Python 层面的依赖但 OpenClaw 依赖的一些原生库是通过apt安装的。缺了它们pip install阶段就会报fatal error: xxx.h: No such file or directory。常见需要提前装好的系统库sudo apt install -y \ libgl1-mesa-glx \ libglib2.0-0 \ libsm6 \ libxext6 \ libxrender-dev \ libgomp1 \ libssl-dev \ libffi-dev \ libxml2-dev \ libxslt1-dev \ zlib1g-dev这些库各自解决什么问题值得说清楚系统库作用缺失时的典型报错libgl1-mesa-glxOpenGL 渲染支持libGL.so.1: cannot open shared object filelibglib2.0-0GLib 基础库libgthread-2.0.so.0找不到libsm6 / libxext6X11 会话管理图形相关模块导入失败libgomp1OpenMP 并行计算多线程相关扩展编译失败libssl-devSSL/TLS 开发头文件openssl/ssl.h找不到libffi-dev外部函数接口ffi.h找不到cffi 编译失败装完这些再进 Python 环境装 OpenClaw 的 Python 依赖成功率会高很多。3. 从源码跑通 OpenClaw安装步骤与依赖编译3.1 获取源码与安装依赖的正确顺序假设你已经拿到了 OpenClaw 的可运行源码包解压后进入项目根目录。先别急着pip install -e .先看一眼项目结构里有没有requirements.txt、pyproject.toml或setup.py这决定了依赖怎么装。# 进入项目目录假设解压在 ~/openclaw-src cd ~/openclaw-src # 查看项目结构确认依赖声明文件 ls -la cat requirements.txt 2/dev/null || echo 没有 requirements.txt cat pyproject.toml 2/dev/null | head -30如果项目有requirements.txt先装它再装项目本身。顺序很重要先装依赖可以让 pip 在解析依赖关系时更从容避免装项目本体时因为某个依赖版本冲突而回滚。# 确保在 venv 里 source ~/openclaw-env/bin/activate # 升级 pip、setuptools、wheel 三件套 pip install --upgrade pip setuptools wheel # 先装依赖 pip install -r requirements.txt # 再以开发模式安装项目本体 pip install -e .pip install -e .里的-e是 editable 模式意思是「以可编辑方式安装」项目目录的改动会直接生效不用重新安装。这对调试源码很有用。3.2 遇到源码编译时怎么判断缺什么如果某个依赖没有预编译 wheelpip 会尝试从源码编译。这时候终端会刷出大量编译日志最后以error: command gcc failed或fatal error: xxx.h: No such file or directory结尾。判断缺什么的方法看报错里提到的.h文件名然后反查它属于哪个-dev包。比如Python.h找不到 → 缺python3-devopenssl/ssl.h找不到 → 缺libssl-devffi.h找不到 → 缺libffi-devlibxml/parser.h找不到 → 缺libxml2-dev用apt-file可以精确查找某个头文件属于哪个包# 安装 apt-file sudo apt install -y apt-file sudo apt-file update # 查找头文件属于哪个包 apt-file search Python.h apt-file search openssl/ssl.h找到包名后sudo apt install装上再重新pip install即可。3.3 验证安装是否成功跑一个最小可运行示例装完之后别急着跑完整功能先用最小示例验证核心模块能不能导入、能不能执行。# test_openclaw_minimal.py # 最小验证脚本确认 OpenClaw 核心模块可导入且能初始化 import sys def check_import(): 尝试导入 OpenClaw 核心模块 try: import openclaw print(f[OK] openclaw 导入成功版本: {getattr(openclaw, __version__, 未知)}) return True except ImportError as e: print(f[FAIL] openclaw 导入失败: {e}) return False def check_core_module(): 检查核心功能模块是否可用 try: # 这里替换成 OpenClaw 实际的核心类或函数 from openclaw import core print([OK] core 模块可用) return True except Exception as e: print(f[FAIL] core 模块异常: {e}) return False if __name__ __main__: ok1 check_import() ok2 check_core_module() if ok1 and ok2: print(\n环境验证通过可以继续跑完整功能。) else: print(\n环境有问题请根据上面的报错排查。) sys.exit(1)运行python test_openclaw_minimal.py如果两个检查都通过说明 Python 层面的安装没问题。如果导入成功但初始化失败通常是运行时依赖比如模型文件、配置文件缺失而不是安装问题。注意有些 OpenClaw 版本在导入时会触发原生库加载如果报OSError: libxxx.so: cannot open shared object file说明系统库还是缺回到 2.3 节对照补装。4. 避坑与排查安装 OpenClaw 最常见的 5 个翻车现场4.1 坑一pip 装到一半报 GLIBC 版本不匹配现象pip install过程中某个依赖的 wheel 安装时报version GLIBC_2.34 not found或类似符号版本错误。原因你用的预编译 wheel 是在更高版本 Ubuntu 上构建的它链接了高版本 glibc 的符号而你的系统 glibc 版本较低找不到这些符号。解决两个方向。一是升级 Ubuntu 到更高版本比如从 20.04 升到 22.04这是最省事的。二是不用预编译 wheel强制从源码编译# 强制从源码编译某个包不走 wheel pip install --no-binary :all: 包名 # 或者只对特定包禁用 wheel pip install --no-binary 包名 包名源码编译会慢很多但编译出来的二进制链接的是你本机的 glibc不会出现版本不匹配。4.2 坑二conda 环境里缺 libGL 导致导入失败现象在 conda 环境里import openclaw报ImportError: libGL.so.1: cannot open shared object file。原因conda 环境有自己的库路径系统apt装的libGL不一定能被 conda 环境找到。conda 的库搜索路径和系统路径是隔离的。解决在 conda 环境里也装一份图形库# 在 conda 环境里安装 libGL 相关库 conda install -c conda-forge libgl1-mesa-glx libglib # 或者设置 LD_LIBRARY_PATH 指向系统库 export LD_LIBRARY_PATH/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH第二种方法每次开终端都要设建议写进~/.bashrc或 conda 环境的激活脚本里。4.3 坑三sudo pip 装出来的包普通用户跑不起来现象用sudo pip install装完普通用户运行时报ModuleNotFoundError或者权限错误。原因sudo pip把包装到了系统 Python 的 site-packages 里而且文件属主是 root。普通用户的 Python 环境可能根本找不到这些包或者找到了但没权限读。解决永远不要在系统 Python 上用sudo pip。用 venv 或 conda 建独立环境所有安装都在用户权限下完成。如果已经装乱了清理方法# 查看 sudo pip 装了什么谨慎操作 sudo pip list # 卸载误装的包 sudo pip uninstall 包名 # 然后回到 venv 重新装 source ~/openclaw-env/bin/activate pip install -r requirements.txt4.4 坑四Python 3.12 下部分依赖没有 wheel编译又失败现象在 Python 3.12 环境里pip install某个依赖时pip 说找不到匹配的 wheel然后开始源码编译编译到一半报错退出。原因Python 3.12 相对较新部分依赖的维护者还没发布对应的预编译 wheel。源码编译又因为缺少系统库或 C 扩展兼容性问题而失败。解决最直接的办法是降 Python 版本到 3.10 或 3.11。这两个版本生态最成熟绝大多数包都有 wheel。# 用 venv 指定 Python 3.10 重建环境 python3.10 -m venv ~/openclaw-env310 source ~/openclaw-env310/bin/activate pip install --upgrade pip setuptools wheel pip install -r requirements.txt如果必须用 3.12那就得逐个解决编译问题成本高很多不推荐。4.5 坑五装完了但运行时报配置文件或模型文件缺失现象import openclaw成功但初始化某个功能时报FileNotFoundError或KeyError提示找不到配置文件、模型权重或字典文件。原因OpenClaw 的某些功能依赖外部数据文件这些文件可能没有随 pip 包一起安装需要手动下载或从源码包里拷贝。解决先看报错里提到的文件路径然后检查源码包里有没有对应的文件# 在源码目录里找报错提到的文件名 find ~/openclaw-src -name 报错里的文件名 # 如果找到了把它拷到报错提示的路径 cp ~/openclaw-src/路径/文件名 ~/报错提示的路径/ # 或者设置环境变量指向文件所在目录 export OPENCLAW_DATA_DIR~/openclaw-src/data具体环境变量名要看 OpenClaw 的文档或源码里的os.environ.get调用。没有文档的话直接在源码里搜os.environ或getenv就能找到所有可配置的路径。5. 让安装可复现锁定版本与写一份自己的安装脚本5.1 用 pip freeze 锁定依赖版本装成功一次之后第一件事是把当前环境的依赖版本冻结下来。否则下次换台机器装依赖自动升级到新版本可能又出问题。# 在装好的 venv 里执行 pip freeze requirements-lock.txt # 查看冻结的版本 cat requirements-lock.txt | head -20requirements-lock.txt里记录了每个包的确切版本号。下次安装时用pip install -r requirements-lock.txt这样装出来的环境和这次完全一致不会因为依赖版本漂移而翻车。5.2 写一个一键安装脚本把踩过的坑固化进去把前面所有步骤串成一个脚本下次重装系统或换机器时直接跑省去重复排查。#!/bin/bash # install_openclaw.sh # Ubuntu 下 OpenClaw 一键安装脚本基于 venv set -e # 任何一步失败就退出 PROJECT_DIR$HOME/openclaw-src VENV_DIR$HOME/openclaw-env PYTHON_VERSIONpython3.10 echo 1. 安装系统依赖 sudo apt update sudo apt install -y \ python3-venv python3-dev build-essential \ libgl1-mesa-glx libglib2.0-0 libsm6 libxext6 \ libxrender-dev libgomp1 libssl-dev libffi-dev \ libxml2-dev libxslt1-dev zlib1g-dev echo 2. 创建虚拟环境 if [ ! -d $VENV_DIR ]; then $PYTHON_VERSION -m venv $VENV_DIR fi source $VENV_DIR/bin/activate echo 3. 升级打包工具 pip install --upgrade pip setuptools wheel echo 4. 安装项目依赖 cd $PROJECT_DIR if [ -f requirements-lock.txt ]; then pip install -r requirements-lock.txt elif [ -f requirements.txt ]; then pip install -r requirements.txt fi echo 5. 安装项目本体 pip install -e . echo 6. 验证安装 python -c import openclaw; print(OpenClaw 导入成功) echo 安装完成 脚本里的set -e是关键任何一步失败都会立即停止不会带着错误继续往下跑。PYTHON_VERSION变量方便你根据系统实际情况改成python3.11或python3.9。5.3 验证脚本本身用最小示例做冒烟测试安装脚本跑完后再跑一次 3.3 节的最小验证脚本确认核心功能可用。这一步不能省因为pip install成功不代表运行时没问题。# 激活环境后跑冒烟测试 source ~/openclaw-env/bin/activate python test_openclaw_minimal.py如果冒烟测试通过再跑一个稍微完整一点的功能示例比如加载配置、初始化一个简单任务。这一步的目的是确认「安装」和「运行」之间的鸿沟已经填平。我自己的习惯是每装一个新环境先跑最小导入测试再跑一个官方文档里的 hello world 级别示例两个都过了才认为环境可用。这个习惯帮我省了很多「装完了但跑不起来」的后悔药时间。希望帮到你。本文还有配套的精品资源点击获取 Ubuntu 下 OpenClaw 安装避坑指南：从环境准备到源码运行
简介这份资源面向在Ubuntu 24.04上部署OpenClaw 3.2的开发者与运维人员聚焦安装过程中两个高频故障的排查与修复选择千问大模型后登录页面卡死以及systemctl命令报“找不到介质”导致服务无法启动。资源内含可运行源码共3个文件以inscode工程配置、html页面与gitignore忽略规则为主压缩包约8KB体量轻便便于直接对照复现问题场景。作者同时整理了环境配置参考涵盖Ubuntu、OpenClaw、npm与Node.js的版本信息并给出创建服务文件、补充安装nvm、升级Node.js、重跑一键安装脚本等排错思路帮助读者快速定位依赖缺失与配置错误。目前已有117人学习适合刚接触OpenClaw部署、需要一份可运行示例与故障对照清单的中级开发者参考。1. 在 Ubuntu 上装 OpenClaw为什么你会在第三步就卡住很多人第一次在 Ubuntu 上装 OpenClaw都会经历同一个剧本照着某篇教程敲完pip install终端刷出一屏红字然后开始怀疑人生。OpenClaw 这类带原生扩展的 Python 工具坑几乎从不在主程序本身而在依赖链、系统库版本和 Python 环境这三者的交叉点上。你在 Ubuntu 22.04 上跑得好好的命令换到 24.04 可能直接报GLIBC版本不匹配用系统自带的 Python 3.10 能过换成 conda 里的 3.12 又缺libGL。这篇笔记就是把这套安装流程从「碰运气」变成「可复现」从环境准备、依赖编译、源码运行到排错一步步拆开讲。适合两类人刚接触 OpenClaw 想在本机跑通的新手以及被依赖问题反复折磨、想搞清楚底层到底发生了什么的老手。2. 装之前先把环境摸清楚Ubuntu 版本、Python 与编译工具链2.1 为什么 Ubuntu 版本决定了你一半的安装难度OpenClaw 的安装难度和 Ubuntu 版本强相关核心原因是系统自带的glibc和gcc版本不同。Ubuntu 20.04 自带 glibc 2.31、gcc 9Ubuntu 22.04 是 glibc 2.35、gcc 11Ubuntu 24.04 则是 glibc 2.39、gcc 13。OpenClaw 的某些原生扩展在编译时会对 glibc 符号版本有要求如果你在 24.04 上编译好的 wheel 拿到 20.04 上跑大概率报version GLIBC_2.34 not found。反过来在 20.04 上编译的包在 24.04 上通常能跑因为高版本 glibc 向后兼容。我一般建议如果你只是本地跑通验证功能用 Ubuntu 22.04 LTS它的 glibc 和 gcc 版本处于中间地带绝大多数预编译 wheel 都能直接用遇到需要源码编译的依赖也不容易翻车。如果你必须用 24.04那就要做好部分依赖需要手动降级或从源码编译的心理准备。先确认你的系统信息# 查看 Ubuntu 版本和内核 lsb_release -a uname -r # 查看 glibc 版本关键 ldd --version | head -1 # 查看 gcc 版本 gcc --version | head -1 # 查看系统 Python 版本 python3 --version这几条命令的输出要记下来。后面遇到报错时第一件事就是对照这些版本号判断是 glibc 不匹配、gcc 太老还是 Python 版本不对。2.2 Python 环境隔离别用系统 Python 直接装Ubuntu 系统自带的 Python 是给系统工具用的直接往里装包有两个风险一是可能破坏系统依赖二是权限问题会让你被迫用sudo pip而sudo pip装出来的包路径混乱后面排查问题极其痛苦。正确做法是用venv或conda建独立环境。我习惯用venv轻量、不引入额外依赖# 安装 venv 和开发工具如果还没装 sudo apt update sudo apt install -y python3-venv python3-dev build-essential # 创建独立环境指定 Python 3.1022.04 自带 python3 -m venv ~/openclaw-env # 激活环境 source ~/openclaw-env/bin/activate # 确认当前 python 指向 venv 里的版本 which python python --version激活后你的终端提示符前面会出现(openclaw-env)说明环境隔离生效了。之后所有pip install都只影响这个环境不会污染系统。注意如果你用的是 conda创建环境时建议指定python3.10不要用 3.12。OpenClaw 的部分依赖在 3.12 上还没有预编译 wheel会触发源码编译而源码编译又可能因为缺少系统库而失败平白多出一堆问题。2.3 补齐系统级依赖那些 pip 装不上的库Python 包管理只管 Python 层面的依赖但 OpenClaw 依赖的一些原生库是通过apt安装的。缺了它们pip install阶段就会报fatal error: xxx.h: No such file or directory。常见需要提前装好的系统库sudo apt install -y \ libgl1-mesa-glx \ libglib2.0-0 \ libsm6 \ libxext6 \ libxrender-dev \ libgomp1 \ libssl-dev \ libffi-dev \ libxml2-dev \ libxslt1-dev \ zlib1g-dev这些库各自解决什么问题值得说清楚系统库作用缺失时的典型报错libgl1-mesa-glxOpenGL 渲染支持libGL.so.1: cannot open shared object filelibglib2.0-0GLib 基础库libgthread-2.0.so.0找不到libsm6 / libxext6X11 会话管理图形相关模块导入失败libgomp1OpenMP 并行计算多线程相关扩展编译失败libssl-devSSL/TLS 开发头文件openssl/ssl.h找不到libffi-dev外部函数接口ffi.h找不到cffi 编译失败装完这些再进 Python 环境装 OpenClaw 的 Python 依赖成功率会高很多。3. 从源码跑通 OpenClaw安装步骤与依赖编译3.1 获取源码与安装依赖的正确顺序假设你已经拿到了 OpenClaw 的可运行源码包解压后进入项目根目录。先别急着pip install -e .先看一眼项目结构里有没有requirements.txt、pyproject.toml或setup.py这决定了依赖怎么装。# 进入项目目录假设解压在 ~/openclaw-src cd ~/openclaw-src # 查看项目结构确认依赖声明文件 ls -la cat requirements.txt 2/dev/null || echo 没有 requirements.txt cat pyproject.toml 2/dev/null | head -30如果项目有requirements.txt先装它再装项目本身。顺序很重要先装依赖可以让 pip 在解析依赖关系时更从容避免装项目本体时因为某个依赖版本冲突而回滚。# 确保在 venv 里 source ~/openclaw-env/bin/activate # 升级 pip、setuptools、wheel 三件套 pip install --upgrade pip setuptools wheel # 先装依赖 pip install -r requirements.txt # 再以开发模式安装项目本体 pip install -e .pip install -e .里的-e是 editable 模式意思是「以可编辑方式安装」项目目录的改动会直接生效不用重新安装。这对调试源码很有用。3.2 遇到源码编译时怎么判断缺什么如果某个依赖没有预编译 wheelpip 会尝试从源码编译。这时候终端会刷出大量编译日志最后以error: command gcc failed或fatal error: xxx.h: No such file or directory结尾。判断缺什么的方法看报错里提到的.h文件名然后反查它属于哪个-dev包。比如Python.h找不到 → 缺python3-devopenssl/ssl.h找不到 → 缺libssl-devffi.h找不到 → 缺libffi-devlibxml/parser.h找不到 → 缺libxml2-dev用apt-file可以精确查找某个头文件属于哪个包# 安装 apt-file sudo apt install -y apt-file sudo apt-file update # 查找头文件属于哪个包 apt-file search Python.h apt-file search openssl/ssl.h找到包名后sudo apt install装上再重新pip install即可。3.3 验证安装是否成功跑一个最小可运行示例装完之后别急着跑完整功能先用最小示例验证核心模块能不能导入、能不能执行。# test_openclaw_minimal.py # 最小验证脚本确认 OpenClaw 核心模块可导入且能初始化 import sys def check_import(): 尝试导入 OpenClaw 核心模块 try: import openclaw print(f[OK] openclaw 导入成功版本: {getattr(openclaw, __version__, 未知)}) return True except ImportError as e: print(f[FAIL] openclaw 导入失败: {e}) return False def check_core_module(): 检查核心功能模块是否可用 try: # 这里替换成 OpenClaw 实际的核心类或函数 from openclaw import core print([OK] core 模块可用) return True except Exception as e: print(f[FAIL] core 模块异常: {e}) return False if __name__ __main__: ok1 check_import() ok2 check_core_module() if ok1 and ok2: print(\n环境验证通过可以继续跑完整功能。) else: print(\n环境有问题请根据上面的报错排查。) sys.exit(1)运行python test_openclaw_minimal.py如果两个检查都通过说明 Python 层面的安装没问题。如果导入成功但初始化失败通常是运行时依赖比如模型文件、配置文件缺失而不是安装问题。注意有些 OpenClaw 版本在导入时会触发原生库加载如果报OSError: libxxx.so: cannot open shared object file说明系统库还是缺回到 2.3 节对照补装。4. 避坑与排查安装 OpenClaw 最常见的 5 个翻车现场4.1 坑一pip 装到一半报 GLIBC 版本不匹配现象pip install过程中某个依赖的 wheel 安装时报version GLIBC_2.34 not found或类似符号版本错误。原因你用的预编译 wheel 是在更高版本 Ubuntu 上构建的它链接了高版本 glibc 的符号而你的系统 glibc 版本较低找不到这些符号。解决两个方向。一是升级 Ubuntu 到更高版本比如从 20.04 升到 22.04这是最省事的。二是不用预编译 wheel强制从源码编译# 强制从源码编译某个包不走 wheel pip install --no-binary :all: 包名 # 或者只对特定包禁用 wheel pip install --no-binary 包名 包名源码编译会慢很多但编译出来的二进制链接的是你本机的 glibc不会出现版本不匹配。4.2 坑二conda 环境里缺 libGL 导致导入失败现象在 conda 环境里import openclaw报ImportError: libGL.so.1: cannot open shared object file。原因conda 环境有自己的库路径系统apt装的libGL不一定能被 conda 环境找到。conda 的库搜索路径和系统路径是隔离的。解决在 conda 环境里也装一份图形库# 在 conda 环境里安装 libGL 相关库 conda install -c conda-forge libgl1-mesa-glx libglib # 或者设置 LD_LIBRARY_PATH 指向系统库 export LD_LIBRARY_PATH/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH第二种方法每次开终端都要设建议写进~/.bashrc或 conda 环境的激活脚本里。4.3 坑三sudo pip 装出来的包普通用户跑不起来现象用sudo pip install装完普通用户运行时报ModuleNotFoundError或者权限错误。原因sudo pip把包装到了系统 Python 的 site-packages 里而且文件属主是 root。普通用户的 Python 环境可能根本找不到这些包或者找到了但没权限读。解决永远不要在系统 Python 上用sudo pip。用 venv 或 conda 建独立环境所有安装都在用户权限下完成。如果已经装乱了清理方法# 查看 sudo pip 装了什么谨慎操作 sudo pip list # 卸载误装的包 sudo pip uninstall 包名 # 然后回到 venv 重新装 source ~/openclaw-env/bin/activate pip install -r requirements.txt4.4 坑四Python 3.12 下部分依赖没有 wheel编译又失败现象在 Python 3.12 环境里pip install某个依赖时pip 说找不到匹配的 wheel然后开始源码编译编译到一半报错退出。原因Python 3.12 相对较新部分依赖的维护者还没发布对应的预编译 wheel。源码编译又因为缺少系统库或 C 扩展兼容性问题而失败。解决最直接的办法是降 Python 版本到 3.10 或 3.11。这两个版本生态最成熟绝大多数包都有 wheel。# 用 venv 指定 Python 3.10 重建环境 python3.10 -m venv ~/openclaw-env310 source ~/openclaw-env310/bin/activate pip install --upgrade pip setuptools wheel pip install -r requirements.txt如果必须用 3.12那就得逐个解决编译问题成本高很多不推荐。4.5 坑五装完了但运行时报配置文件或模型文件缺失现象import openclaw成功但初始化某个功能时报FileNotFoundError或KeyError提示找不到配置文件、模型权重或字典文件。原因OpenClaw 的某些功能依赖外部数据文件这些文件可能没有随 pip 包一起安装需要手动下载或从源码包里拷贝。解决先看报错里提到的文件路径然后检查源码包里有没有对应的文件# 在源码目录里找报错提到的文件名 find ~/openclaw-src -name 报错里的文件名 # 如果找到了把它拷到报错提示的路径 cp ~/openclaw-src/路径/文件名 ~/报错提示的路径/ # 或者设置环境变量指向文件所在目录 export OPENCLAW_DATA_DIR~/openclaw-src/data具体环境变量名要看 OpenClaw 的文档或源码里的os.environ.get调用。没有文档的话直接在源码里搜os.environ或getenv就能找到所有可配置的路径。5. 让安装可复现锁定版本与写一份自己的安装脚本5.1 用 pip freeze 锁定依赖版本装成功一次之后第一件事是把当前环境的依赖版本冻结下来。否则下次换台机器装依赖自动升级到新版本可能又出问题。# 在装好的 venv 里执行 pip freeze requirements-lock.txt # 查看冻结的版本 cat requirements-lock.txt | head -20requirements-lock.txt里记录了每个包的确切版本号。下次安装时用pip install -r requirements-lock.txt这样装出来的环境和这次完全一致不会因为依赖版本漂移而翻车。5.2 写一个一键安装脚本把踩过的坑固化进去把前面所有步骤串成一个脚本下次重装系统或换机器时直接跑省去重复排查。#!/bin/bash # install_openclaw.sh # Ubuntu 下 OpenClaw 一键安装脚本基于 venv set -e # 任何一步失败就退出 PROJECT_DIR$HOME/openclaw-src VENV_DIR$HOME/openclaw-env PYTHON_VERSIONpython3.10 echo 1. 安装系统依赖 sudo apt update sudo apt install -y \ python3-venv python3-dev build-essential \ libgl1-mesa-glx libglib2.0-0 libsm6 libxext6 \ libxrender-dev libgomp1 libssl-dev libffi-dev \ libxml2-dev libxslt1-dev zlib1g-dev echo 2. 创建虚拟环境 if [ ! -d $VENV_DIR ]; then $PYTHON_VERSION -m venv $VENV_DIR fi source $VENV_DIR/bin/activate echo 3. 升级打包工具 pip install --upgrade pip setuptools wheel echo 4. 安装项目依赖 cd $PROJECT_DIR if [ -f requirements-lock.txt ]; then pip install -r requirements-lock.txt elif [ -f requirements.txt ]; then pip install -r requirements.txt fi echo 5. 安装项目本体 pip install -e . echo 6. 验证安装 python -c import openclaw; print(OpenClaw 导入成功) echo 安装完成 脚本里的set -e是关键任何一步失败都会立即停止不会带着错误继续往下跑。PYTHON_VERSION变量方便你根据系统实际情况改成python3.11或python3.9。5.3 验证脚本本身用最小示例做冒烟测试安装脚本跑完后再跑一次 3.3 节的最小验证脚本确认核心功能可用。这一步不能省因为pip install成功不代表运行时没问题。# 激活环境后跑冒烟测试 source ~/openclaw-env/bin/activate python test_openclaw_minimal.py如果冒烟测试通过再跑一个稍微完整一点的功能示例比如加载配置、初始化一个简单任务。这一步的目的是确认「安装」和「运行」之间的鸿沟已经填平。我自己的习惯是每装一个新环境先跑最小导入测试再跑一个官方文档里的 hello world 级别示例两个都过了才认为环境可用。这个习惯帮我省了很多「装完了但跑不起来」的后悔药时间。希望帮到你。本文还有配套的精品资源点击获取