簡(jiǎn)介這份資源面向在Ubuntu 24.04上部署OpenClaw 3.2的開發(fā)者與運(yùn)維人員聚焦安裝過程中兩個(gè)高頻故障的排查與修復(fù)選擇千問大模型后登錄頁(yè)面卡死以及systemctl命令報(bào)“找不到介質(zhì)”導(dǎo)致服務(wù)無(wú)法啟動(dòng)。資源內(nèi)含可運(yùn)行源碼共3個(gè)文件以inscode工程配置、html頁(yè)面與gitignore忽略規(guī)則為主壓縮包約8KB體量輕便便于直接對(duì)照復(fù)現(xiàn)問題場(chǎng)景。作者同時(shí)整理了環(huán)境配置參考涵蓋Ubuntu、OpenClaw、npm與Node.js的版本信息并給出創(chuàng)建服務(wù)文件、補(bǔ)充安裝nvm、升級(jí)Node.js、重跑一鍵安裝腳本等排錯(cuò)思路幫助讀者快速定位依賴缺失與配置錯(cuò)誤。目前已有117人學(xué)習(xí)適合剛接觸OpenClaw部署、需要一份可運(yùn)行示例與故障對(duì)照清單的中級(jí)開發(fā)者參考。1. 在 Ubuntu 上裝 OpenClaw為什么你會(huì)在第三步就卡住很多人第一次在 Ubuntu 上裝 OpenClaw都會(huì)經(jīng)歷同一個(gè)劇本照著某篇教程敲完pip install終端刷出一屏紅字然后開始懷疑人生。OpenClaw 這類帶原生擴(kuò)展的 Python 工具坑幾乎從不在主程序本身而在依賴鏈、系統(tǒng)庫(kù)版本和 Python 環(huán)境這三者的交叉點(diǎn)上。你在 Ubuntu 22.04 上跑得好好的命令換到 24.04 可能直接報(bào)GLIBC版本不匹配用系統(tǒng)自帶的 Python 3.10 能過換成 conda 里的 3.12 又缺libGL。這篇筆記就是把這套安裝流程從「碰運(yùn)氣」變成「可復(fù)現(xiàn)」從環(huán)境準(zhǔn)備、依賴編譯、源碼運(yùn)行到排錯(cuò)一步步拆開講。適合兩類人剛接觸 OpenClaw 想在本機(jī)跑通的新手以及被依賴問題反復(fù)折磨、想搞清楚底層到底發(fā)生了什么的老手。2. 裝之前先把環(huán)境摸清楚Ubuntu 版本、Python 與編譯工具鏈2.1 為什么 Ubuntu 版本決定了你一半的安裝難度OpenClaw 的安裝難度和 Ubuntu 版本強(qiáng)相關(guān)核心原因是系統(tǒng)自帶的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 的某些原生擴(kuò)展在編譯時(shí)會(huì)對(duì) glibc 符號(hào)版本有要求如果你在 24.04 上編譯好的 wheel 拿到 20.04 上跑大概率報(bào)version GLIBC_2.34 not found。反過來(lái)在 20.04 上編譯的包在 24.04 上通常能跑因?yàn)楦甙姹?glibc 向后兼容。我一般建議如果你只是本地跑通驗(yàn)證功能用 Ubuntu 22.04 LTS它的 glibc 和 gcc 版本處于中間地帶絕大多數(shù)預(yù)編譯 wheel 都能直接用遇到需要源碼編譯的依賴也不容易翻車。如果你必須用 24.04那就要做好部分依賴需要手動(dòng)降級(jí)或從源碼編譯的心理準(zhǔn)備。先確認(rèn)你的系統(tǒng)信息# 查看 Ubuntu 版本和內(nèi)核 lsb_release -a uname -r # 查看 glibc 版本關(guān)鍵 ldd --version | head -1 # 查看 gcc 版本 gcc --version | head -1 # 查看系統(tǒng) Python 版本 python3 --version這幾條命令的輸出要記下來(lái)。后面遇到報(bào)錯(cuò)時(shí)第一件事就是對(duì)照這些版本號(hào)判斷是 glibc 不匹配、gcc 太老還是 Python 版本不對(duì)。2.2 Python 環(huán)境隔離別用系統(tǒng) Python 直接裝Ubuntu 系統(tǒng)自帶的 Python 是給系統(tǒng)工具用的直接往里裝包有兩個(gè)風(fēng)險(xiǎn)一是可能破壞系統(tǒng)依賴二是權(quán)限問題會(huì)讓你被迫用sudo pip而sudo pip裝出來(lái)的包路徑混亂后面排查問題極其痛苦。正確做法是用venv或conda建獨(dú)立環(huán)境。我習(xí)慣用venv輕量、不引入額外依賴# 安裝 venv 和開發(fā)工具如果還沒裝 sudo apt update sudo apt install -y python3-venv python3-dev build-essential # 創(chuàng)建獨(dú)立環(huán)境指定 Python 3.1022.04 自帶 python3 -m venv ~/openclaw-env # 激活環(huán)境 source ~/openclaw-env/bin/activate # 確認(rèn)當(dāng)前 python 指向 venv 里的版本 which python python --version激活后你的終端提示符前面會(huì)出現(xiàn)(openclaw-env)說(shuō)明環(huán)境隔離生效了。之后所有pip install都只影響這個(gè)環(huán)境不會(huì)污染系統(tǒng)。注意如果你用的是 conda創(chuàng)建環(huán)境時(shí)建議指定python3.10不要用 3.12。OpenClaw 的部分依賴在 3.12 上還沒有預(yù)編譯 wheel會(huì)觸發(fā)源碼編譯而源碼編譯又可能因?yàn)槿鄙傧到y(tǒng)庫(kù)而失敗平白多出一堆問題。2.3 補(bǔ)齊系統(tǒng)級(jí)依賴那些 pip 裝不上的庫(kù)Python 包管理只管 Python 層面的依賴但 OpenClaw 依賴的一些原生庫(kù)是通過apt安裝的。缺了它們pip install階段就會(huì)報(bào)fatal error: xxx.h: No such file or directory。常見需要提前裝好的系統(tǒng)庫(kù)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這些庫(kù)各自解決什么問題值得說(shuō)清楚系統(tǒng)庫(kù)作用缺失時(shí)的典型報(bào)錯(cuò)libgl1-mesa-glxOpenGL 渲染支持libGL.so.1: cannot open shared object filelibglib2.0-0GLib 基礎(chǔ)庫(kù)libgthread-2.0.so.0找不到libsm6 / libxext6X11 會(huì)話管理圖形相關(guān)模塊導(dǎo)入失敗libgomp1OpenMP 并行計(jì)算多線程相關(guān)擴(kuò)展編譯失敗libssl-devSSL/TLS 開發(fā)頭文件openssl/ssl.h找不到libffi-dev外部函數(shù)接口ffi.h找不到cffi 編譯失敗裝完這些再進(jìn) Python 環(huán)境裝 OpenClaw 的 Python 依賴成功率會(huì)高很多。3. 從源碼跑通 OpenClaw安裝步驟與依賴編譯3.1 獲取源碼與安裝依賴的正確順序假設(shè)你已經(jīng)拿到了 OpenClaw 的可運(yùn)行源碼包解壓后進(jìn)入項(xiàng)目根目錄。先別急著pip install -e .先看一眼項(xiàng)目結(jié)構(gòu)里有沒有requirements.txt、pyproject.toml或setup.py這決定了依賴怎么裝。# 進(jìn)入項(xiàng)目目錄假設(shè)解壓在 ~/openclaw-src cd ~/openclaw-src # 查看項(xiàng)目結(jié)構(gòu)確認(rèn)依賴聲明文件 ls -la cat requirements.txt 2/dev/null || echo 沒有 requirements.txt cat pyproject.toml 2/dev/null | head -30如果項(xiàng)目有requirements.txt先裝它再裝項(xiàng)目本身。順序很重要先裝依賴可以讓 pip 在解析依賴關(guān)系時(shí)更從容避免裝項(xiàng)目本體時(shí)因?yàn)槟硞€(gè)依賴版本沖突而回滾。# 確保在 venv 里 source ~/openclaw-env/bin/activate # 升級(jí) pip、setuptools、wheel 三件套 pip install --upgrade pip setuptools wheel # 先裝依賴 pip install -r requirements.txt # 再以開發(fā)模式安裝項(xiàng)目本體 pip install -e .pip install -e .里的-e是 editable 模式意思是「以可編輯方式安裝」項(xiàng)目目錄的改動(dòng)會(huì)直接生效不用重新安裝。這對(duì)調(diào)試源碼很有用。3.2 遇到源碼編譯時(shí)怎么判斷缺什么如果某個(gè)依賴沒有預(yù)編譯 wheelpip 會(huì)嘗試從源碼編譯。這時(shí)候終端會(huì)刷出大量編譯日志最后以error: command gcc failed或fatal error: xxx.h: No such file or directory結(jié)尾。判斷缺什么的方法看報(bào)錯(cuò)里提到的.h文件名然后反查它屬于哪個(gè)-dev包。比如Python.h找不到 → 缺python3-devopenssl/ssl.h找不到 → 缺libssl-devffi.h找不到 → 缺libffi-devlibxml/parser.h找不到 → 缺libxml2-dev用apt-file可以精確查找某個(gè)頭文件屬于哪個(gè)包# 安裝 apt-file sudo apt install -y apt-file sudo apt-file update # 查找頭文件屬于哪個(gè)包 apt-file search Python.h apt-file search openssl/ssl.h找到包名后sudo apt install裝上再重新pip install即可。3.3 驗(yàn)證安裝是否成功跑一個(gè)最小可運(yùn)行示例裝完之后別急著跑完整功能先用最小示例驗(yàn)證核心模塊能不能導(dǎo)入、能不能執(zhí)行。# test_openclaw_minimal.py # 最小驗(yàn)證腳本確認(rèn) OpenClaw 核心模塊可導(dǎo)入且能初始化 import sys def check_import(): 嘗試導(dǎo)入 OpenClaw 核心模塊 try: import openclaw print(f[OK] openclaw 導(dǎo)入成功版本: {getattr(openclaw, __version__, 未知)}) return True except ImportError as e: print(f[FAIL] openclaw 導(dǎo)入失敗: {e}) return False def check_core_module(): 檢查核心功能模塊是否可用 try: # 這里替換成 OpenClaw 實(shí)際的核心類或函數(shù) 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環(huán)境驗(yàn)證通過可以繼續(xù)跑完整功能。) else: print(\n環(huán)境有問題請(qǐng)根據(jù)上面的報(bào)錯(cuò)排查。) sys.exit(1)運(yùn)行python test_openclaw_minimal.py如果兩個(gè)檢查都通過說(shuō)明 Python 層面的安裝沒問題。如果導(dǎo)入成功但初始化失敗通常是運(yùn)行時(shí)依賴比如模型文件、配置文件缺失而不是安裝問題。注意有些 OpenClaw 版本在導(dǎo)入時(shí)會(huì)觸發(fā)原生庫(kù)加載如果報(bào)OSError: libxxx.so: cannot open shared object file說(shuō)明系統(tǒng)庫(kù)還是缺回到 2.3 節(jié)對(duì)照補(bǔ)裝。4. 避坑與排查安裝 OpenClaw 最常見的 5 個(gè)翻車現(xiàn)場(chǎng)4.1 坑一pip 裝到一半報(bào) GLIBC 版本不匹配現(xiàn)象pip install過程中某個(gè)依賴的 wheel 安裝時(shí)報(bào)version GLIBC_2.34 not found或類似符號(hào)版本錯(cuò)誤。原因你用的預(yù)編譯 wheel 是在更高版本 Ubuntu 上構(gòu)建的它鏈接了高版本 glibc 的符號(hào)而你的系統(tǒng) glibc 版本較低找不到這些符號(hào)。解決兩個(gè)方向。一是升級(jí) Ubuntu 到更高版本比如從 20.04 升到 22.04這是最省事的。二是不用預(yù)編譯 wheel強(qiáng)制從源碼編譯# 強(qiáng)制從源碼編譯某個(gè)包不走 wheel pip install --no-binary :all: 包名 # 或者只對(duì)特定包禁用 wheel pip install --no-binary 包名 包名源碼編譯會(huì)慢很多但編譯出來(lái)的二進(jìn)制鏈接的是你本機(jī)的 glibc不會(huì)出現(xiàn)版本不匹配。4.2 坑二conda 環(huán)境里缺 libGL 導(dǎo)致導(dǎo)入失敗現(xiàn)象在 conda 環(huán)境里import openclaw報(bào)ImportError: libGL.so.1: cannot open shared object file。原因conda 環(huán)境有自己的庫(kù)路徑系統(tǒng)apt裝的libGL不一定能被 conda 環(huán)境找到。conda 的庫(kù)搜索路徑和系統(tǒng)路徑是隔離的。解決在 conda 環(huán)境里也裝一份圖形庫(kù)# 在 conda 環(huán)境里安裝 libGL 相關(guān)庫(kù) conda install -c conda-forge libgl1-mesa-glx libglib # 或者設(shè)置 LD_LIBRARY_PATH 指向系統(tǒng)庫(kù) export LD_LIBRARY_PATH/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH第二種方法每次開終端都要設(shè)建議寫進(jìn)~/.bashrc或 conda 環(huán)境的激活腳本里。4.3 坑三sudo pip 裝出來(lái)的包普通用戶跑不起來(lái)現(xiàn)象用sudo pip install裝完普通用戶運(yùn)行時(shí)報(bào)ModuleNotFoundError或者權(quán)限錯(cuò)誤。原因sudo pip把包裝到了系統(tǒng) Python 的 site-packages 里而且文件屬主是 root。普通用戶的 Python 環(huán)境可能根本找不到這些包或者找到了但沒權(quán)限讀。解決永遠(yuǎn)不要在系統(tǒng) Python 上用sudo pip。用 venv 或 conda 建獨(dú)立環(huán)境所有安裝都在用戶權(quán)限下完成。如果已經(jīng)裝亂了清理方法# 查看 sudo pip 裝了什么謹(jǐn)慎操作 sudo pip list # 卸載誤裝的包 sudo pip uninstall 包名 # 然后回到 venv 重新裝 source ~/openclaw-env/bin/activate pip install -r requirements.txt4.4 坑四Python 3.12 下部分依賴沒有 wheel編譯又失敗現(xiàn)象在 Python 3.12 環(huán)境里pip install某個(gè)依賴時(shí)pip 說(shuō)找不到匹配的 wheel然后開始源碼編譯編譯到一半報(bào)錯(cuò)退出。原因Python 3.12 相對(duì)較新部分依賴的維護(hù)者還沒發(fā)布對(duì)應(yīng)的預(yù)編譯 wheel。源碼編譯又因?yàn)槿鄙傧到y(tǒng)庫(kù)或 C 擴(kuò)展兼容性問題而失敗。解決最直接的辦法是降 Python 版本到 3.10 或 3.11。這兩個(gè)版本生態(tài)最成熟絕大多數(shù)包都有 wheel。# 用 venv 指定 Python 3.10 重建環(huán)境 python3.10 -m venv ~/openclaw-env310 source ~/openclaw-env310/bin/activate pip install --upgrade pip setuptools wheel pip install -r requirements.txt如果必須用 3.12那就得逐個(gè)解決編譯問題成本高很多不推薦。4.5 坑五裝完了但運(yùn)行時(shí)報(bào)配置文件或模型文件缺失現(xiàn)象import openclaw成功但初始化某個(gè)功能時(shí)報(bào)FileNotFoundError或KeyError提示找不到配置文件、模型權(quán)重或字典文件。原因OpenClaw 的某些功能依賴外部數(shù)據(jù)文件這些文件可能沒有隨 pip 包一起安裝需要手動(dòng)下載或從源碼包里拷貝。解決先看報(bào)錯(cuò)里提到的文件路徑然后檢查源碼包里有沒有對(duì)應(yīng)的文件# 在源碼目錄里找報(bào)錯(cuò)提到的文件名 find ~/openclaw-src -name 報(bào)錯(cuò)里的文件名 # 如果找到了把它拷到報(bào)錯(cuò)提示的路徑 cp ~/openclaw-src/路徑/文件名 ~/報(bào)錯(cuò)提示的路徑/ # 或者設(shè)置環(huán)境變量指向文件所在目錄 export OPENCLAW_DATA_DIR~/openclaw-src/data具體環(huán)境變量名要看 OpenClaw 的文檔或源碼里的os.environ.get調(diào)用。沒有文檔的話直接在源碼里搜os.environ或getenv就能找到所有可配置的路徑。5. 讓安裝可復(fù)現(xiàn)鎖定版本與寫一份自己的安裝腳本5.1 用 pip freeze 鎖定依賴版本裝成功一次之后第一件事是把當(dāng)前環(huán)境的依賴版本凍結(jié)下來(lái)。否則下次換臺(tái)機(jī)器裝依賴自動(dòng)升級(jí)到新版本可能又出問題。# 在裝好的 venv 里執(zhí)行 pip freeze requirements-lock.txt # 查看凍結(jié)的版本 cat requirements-lock.txt | head -20requirements-lock.txt里記錄了每個(gè)包的確切版本號(hào)。下次安裝時(shí)用pip install -r requirements-lock.txt這樣裝出來(lái)的環(huán)境和這次完全一致不會(huì)因?yàn)橐蕾嚢姹酒贫嚒?.2 寫一個(gè)一鍵安裝腳本把踩過的坑固化進(jìn)去把前面所有步驟串成一個(gè)腳本下次重裝系統(tǒng)或換機(jī)器時(shí)直接跑省去重復(fù)排查。#!/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. 安裝系統(tǒng)依賴 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. 創(chuàng)建虛擬環(huán)境 if [ ! -d $VENV_DIR ]; then $PYTHON_VERSION -m venv $VENV_DIR fi source $VENV_DIR/bin/activate echo 3. 升級(jí)打包工具 pip install --upgrade pip setuptools wheel echo 4. 安裝項(xiàng)目依賴 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. 安裝項(xiàng)目本體 pip install -e . echo 6. 驗(yàn)證安裝 python -c import openclaw; print(OpenClaw 導(dǎo)入成功) echo 安裝完成 腳本里的set -e是關(guān)鍵任何一步失敗都會(huì)立即停止不會(huì)帶著錯(cuò)誤繼續(xù)往下跑。PYTHON_VERSION變量方便你根據(jù)系統(tǒng)實(shí)際情況改成python3.11或python3.9。5.3 驗(yàn)證腳本本身用最小示例做冒煙測(cè)試安裝腳本跑完后再跑一次 3.3 節(jié)的最小驗(yàn)證腳本確認(rèn)核心功能可用。這一步不能省因?yàn)閜ip install成功不代表運(yùn)行時(shí)沒問題。# 激活環(huán)境后跑冒煙測(cè)試 source ~/openclaw-env/bin/activate python test_openclaw_minimal.py如果冒煙測(cè)試通過再跑一個(gè)稍微完整一點(diǎn)的功能示例比如加載配置、初始化一個(gè)簡(jiǎn)單任務(wù)。這一步的目的是確認(rèn)「安裝」和「運(yùn)行」之間的鴻溝已經(jīng)填平。我自己的習(xí)慣是每裝一個(gè)新環(huán)境先跑最小導(dǎo)入測(cè)試再跑一個(gè)官方文檔里的 hello world 級(jí)別示例兩個(gè)都過了才認(rèn)為環(huán)境可用。這個(gè)習(xí)慣幫我省了很多「裝完了但跑不起來(lái)」的后悔藥時(shí)間。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取