前陣子有讀者問(wèn)我OpenClaw 這種開(kāi)源自動(dòng)化網(wǎng)關(guān)項(xiàng)目到底值不值得自己在本機(jī)部署一套。我的答案是如果你需要一個(gè)能把 Webhook、定時(shí)任務(wù)、消息通知、Shell 指令收斂到一個(gè)統(tǒng)一后臺(tái)的小型服務(wù)OpenClaw 是我試過(guò)的一條性價(jià)比很高的路徑。社區(qū)里有叫它 Clawdbot 的也有叫 Moltbot 的實(shí)際都是同一套東西在不同分支下的代號(hào)下面我統(tǒng)稱 OpenClaw。這篇文章我會(huì)從零開(kāi)始把 Ubuntu 上的環(huán)境準(zhǔn)備、一鍵腳本 / Docker / npm 三種安裝方式、中文漢化界面適配以及我在實(shí)際部署中踩過(guò)的坑完整記錄一遍。內(nèi)容不是照著官方 README 翻譯而是結(jié)合我自己的踩坑經(jīng)歷來(lái)寫適合剛接觸開(kāi)源服務(wù)部署的開(kāi)發(fā)者也適合已經(jīng)跑過(guò)一段自托管服務(wù)、想換個(gè)更可控方案的老手。1. 開(kāi)工之前OpenClaw 到底是什么為什么值得本地部署1.1 一句話理解這個(gè)開(kāi)源項(xiàng)目的能力邊界OpenClaw 本質(zhì)是一個(gè)“事件驅(qū)動(dòng)的自動(dòng)化服務(wù)網(wǎng)關(guān)”。你可以把它理解為一條收納繩外部系統(tǒng)通過(guò) Webhook 把事件丟進(jìn)來(lái)它負(fù)責(zé)判斷該觸發(fā)什么流程內(nèi)部服務(wù)通過(guò)定時(shí)任務(wù)把計(jì)劃執(zhí)行起來(lái)它負(fù)責(zé)按 cron 表達(dá)式調(diào)動(dòng)命令再配上通知模塊完成之后往釘釘、飛書(shū)這類渠道推一條結(jié)果。這樣描述還是有點(diǎn)抽象。我舉個(gè)實(shí)際場(chǎng)景假設(shè)你維護(hù)了三臺(tái)服務(wù)器每天要輪流備份目錄、清理日志、檢查端口狀態(tài)。傳統(tǒng)做法是把 Shell 腳本放到每臺(tái)機(jī)器的 cron 里日志散落各處管起來(lái)非常費(fèi)勁。OpenClaw 的運(yùn)行方式是讓三臺(tái)機(jī)器都裝上輕量客戶端把執(zhí)行任務(wù)統(tǒng)一上報(bào)到服務(wù)端你在瀏覽器里打開(kāi)控制臺(tái)能看到所有任務(wù)狀態(tài)也能直接在界面里加一條新的定時(shí)任務(wù)。這個(gè)過(guò)程中你不需要寫一套完整的任務(wù)調(diào)度系統(tǒng)只需要把自己公司的業(yè)務(wù)腳本掛進(jìn)去。它適合誰(shuí)適合以下幾類人內(nèi)部工具鏈比較分散需要一個(gè)集中管理入口的團(tuán)隊(duì)已經(jīng)在用各類開(kāi)源監(jiān)控工具但不想被商業(yè)產(chǎn)品鎖定個(gè)人開(kāi)發(fā)者有多臺(tái) VPS 或家用服務(wù)器想統(tǒng)一管理定時(shí)任務(wù)和 Webhook想做二次開(kāi)發(fā)需要一套前后端分離、代碼結(jié)構(gòu)清晰的開(kāi)源項(xiàng)目作為腳手架。項(xiàng)目本身默認(rèn)英文界面源碼里也預(yù)留了國(guó)際化資源目錄所以漢化不是硬改代碼而是替換語(yǔ)言資源文件的事。這也是我在后面單獨(dú)用一章寫適配的原因。1.2 一鍵腳本、Docker、npm 三種模式的取舍安裝方式多不代表每條都適合你。選擇之前先搞清楚自己的運(yùn)行場(chǎng)景。一鍵腳本適合的場(chǎng)景是“新機(jī)器、只裝這一個(gè)服務(wù)、想要馬上跑起來(lái)”。腳本解決的問(wèn)題是環(huán)境依賴和系統(tǒng)服務(wù)注冊(cè)它會(huì)把可執(zhí)行文件、配置目錄、systemd 單元一次處理好裝完直接能通過(guò)systemctl管理。缺點(diǎn)是升級(jí)路徑不透明腳本不可見(jiàn)的情況下你很難知道它動(dòng)了哪些系統(tǒng)文件。Docker 模式適合“機(jī)器上已經(jīng)有多種服務(wù)想隔離運(yùn)行”。OpenClaw 需要 Node.js 運(yùn)行時(shí)和一堆系統(tǒng)依賴如果全部裝進(jìn)宿主機(jī)很容易和你現(xiàn)有的 Python 或 Go 服務(wù)產(chǎn)生 glibc 版本沖突。用容器把應(yīng)用和宿主隔開(kāi)升級(jí)就是換鏡像、重啟容器回滾也方便。生產(chǎn)環(huán)境我一般推薦這種。npm 模式適合“只是想跑一下看看后面大概率會(huì)換部署方式”的試驗(yàn)場(chǎng)景。它本質(zhì)上就是把 OpenClaw 當(dāng)作一個(gè) Node CLI 工具全局安裝后直接openclaw start。優(yōu)點(diǎn)是快缺點(diǎn)是你需要在宿主機(jī)手動(dòng)裝 Node.js版本一偏就容易出問(wèn)題而且全局 node_modules 里的殘留很煩。安裝方式上手速度隔離性升級(jí)難度適合場(chǎng)景一鍵腳本極快低中新機(jī)器快速部署Docker較快高低生產(chǎn)/多服務(wù)共存npm最快低中試用、開(kāi)發(fā)調(diào)試后面第 3 章會(huì)分別給出這三條線的完整操作和實(shí)測(cè)輸出。2. Ubuntu 環(huán)境準(zhǔn)備先把地基做扎實(shí)不少人在安裝階段報(bào)錯(cuò)不是 OpenClaw 的問(wèn)題而是底層環(huán)境太亂。域名解析、時(shí)區(qū)、防火墻、依賴版本都對(duì)不齊裝到一半才暴露出來(lái)排查時(shí)往往分不清是環(huán)境問(wèn)題還是應(yīng)用問(wèn)題。所以這部分我建議認(rèn)真過(guò)一遍裝完再開(kāi)始安裝。2.1 系統(tǒng)更新、基礎(chǔ)工具與語(yǔ)言環(huán)境我測(cè)試用的系統(tǒng)是 Ubuntu 22.04 LTS內(nèi)核版本在 5.15 以上運(yùn)行內(nèi)存給了 2GB。如果條件差一點(diǎn)也沒(méi)關(guān)系OpenClaw 本身占用不高但 Node.js 構(gòu)建時(shí)對(duì) CPU 壓力比較大內(nèi)存低于 1GB 的機(jī)器建議先加 swap。登錄之后先更新軟件源緩存和系統(tǒng)包sudo apt update sudo apt upgrade -y這一步不是走過(guò)場(chǎng)。很多第三方二進(jìn)制包依賴libssl、libicu等庫(kù)的特定版本舊系統(tǒng)里這些庫(kù)版本落后安裝工具時(shí)可能裝不上最新依賴。接著安裝基礎(chǔ)工具sudo apt install -y curl wget git jq unzipjq我特別說(shuō)一下OpenClaw 控制臺(tái)里有一些調(diào)試接口返回 JSON用 jq 格式化之后看起來(lái)舒服很多。調(diào)試 Webhook 的時(shí)候少一個(gè) jq 會(huì)多花很多時(shí)間在肉眼摳括號(hào)上。語(yǔ)言環(huán)境這一塊容易被忽略。OpenClaw 漢化之后中文在命令行和日志里的顯示是否正常取決于系統(tǒng)區(qū)域設(shè)置。先確認(rèn)當(dāng)前環(huán)境locale如果輸出里的LANG不是zh_CN.UTF-8或en_US.UTF-8需要安裝并生成語(yǔ)言包sudo apt install -y locales sudo locale-gen en_US.UTF-8 zh_CN.UTF-8 sudo update-locale LANGzh_CN.UTF-8 LC_ALLzh_CN.UTF-8這里設(shè)成中文環(huán)境有個(gè)好處之后 OpenClaw 日志里的時(shí)間日期格式會(huì)直接跟隨系統(tǒng)時(shí)區(qū)不容易出現(xiàn)“文件名稱是中文但終端顯示全是問(wèn)號(hào)”的怪問(wèn)題。注意改完 locale 之后當(dāng)前 SSH 會(huì)話里的環(huán)境變量不會(huì)立刻生效退出重新登錄一下或者手動(dòng)執(zhí)行export LANGzh_CN.UTF-8。2.2 運(yùn)行時(shí)依賴裝到哪個(gè)版本最穩(wěn)OpenClaw 基于 Node.js 構(gòu)建官方文檔標(biāo)注支持 Node.js 18 和 20 兩個(gè)大版本。我實(shí)際測(cè)試下來(lái)20 LTS 的兼容性最好18 在某些老版本上會(huì)出現(xiàn)內(nèi)置 fetch 行為差異導(dǎo)致 Webhook 請(qǐng)求異常。如果走 npm 安裝模式需要先裝 Node.js。這里我建議使用 NodeSource 提供的二進(jìn)制包不用發(fā)行版自帶的低版本curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs裝完確認(rèn)版本node -v npm -v另外如果之前裝過(guò)舊版 Node.js最好先卸載干凈再裝否則/usr/bin/node的軟鏈會(huì)混亂npm 全局安裝的工具可能找不到可執(zhí)行文件。如果走 Docker 模式其實(shí)不要求在宿主機(jī)裝 Node.js但需要裝 Docker Engine 和 Docker Compose 插件。官方安裝腳本仍然可用curl -fsSL https://get.docker.com/ | sudo sh sudo systemctl enable --now docker docker compose version注意 Docker 安裝后當(dāng)前用戶執(zhí)行 docker 命令可能會(huì)報(bào)權(quán)限錯(cuò)誤。解決辦法是把自己加入 docker 組或者臨時(shí)用 sudo 執(zhí)行。sudo usermod -aG docker $USER newgrp docker這里解釋一下為什么我不建議直接用 apt 安裝 Docker 的發(fā)行版?zhèn)}庫(kù)版本。Ubuntu 倉(cāng)庫(kù)里的 docker 包往往不是最新而且沒(méi)有把 compose 插件整合好后面寫docker compose up時(shí)格式不兼容會(huì)很尷尬。官方腳本安裝的是社區(qū)版最新版和 compose 插件配合最順。2.3 端口、防火墻與目錄權(quán)限規(guī)劃OpenClaw 的核心是 Web 管理端和 Webhook 接收端默認(rèn)端口是 9527。這個(gè)端口可以改但為了避免之后排查困難我建議第一次部署就用默認(rèn)值跑通之后再考慮改端口。如果啟用了 UFW 防火墻需要放行端口sudo ufw allow 9527/tcp sudo ufw enable sudo ufw status verbose還有個(gè)細(xì)節(jié)如果你打算用 Nginx 反代就只需要對(duì)公網(wǎng)放行 80/4439527 端口僅綁定內(nèi)網(wǎng)地址。但如果只是想快速試用直接在服務(wù)器上放行 9527 也行。目錄權(quán)限方面OpenClaw 會(huì)把配置、日志、語(yǔ)言包放在/opt/openclaw下。一鍵腳本安裝時(shí)會(huì)自動(dòng)創(chuàng)建該目錄npm 模式則放在用戶的.openclaw目錄下。Docker 模式需要你手動(dòng)指定卷映射?？偟脑瓌t是別用 root 直接跑客戶端進(jìn)程單獨(dú)建一個(gè)系統(tǒng)用戶更安全。sudo useradd --system --home /opt/openclaw --shell /usr/sbin/nologin openclaw sudo mkdir -p /opt/openclaw sudo chown -R openclaw:openclaw /opt/openclaw這個(gè)用戶只用來(lái)運(yùn)行 OpenClaw 服務(wù)沒(méi)有登錄 Shell 權(quán)限即使 Web 端被攻破攻擊者也無(wú)法直接通過(guò)這個(gè)用戶拿到系統(tǒng)登錄權(quán)限。3. 三種安裝模式完整實(shí)操記錄3.1 一鍵腳本模式適合“今天就要用起來(lái)”的場(chǎng)景一鍵腳本最大的優(yōu)勢(shì)是省事但我不推薦“網(wǎng)上隨便找一個(gè)命令就粘貼執(zhí)行”。安全習(xí)慣是先下載下來(lái)看一遍內(nèi)容再跑。curl -fsSL https://openclaw.example.com/install.sh -o install.sh less install.sh腳本內(nèi)容大致分為幾塊檢查系統(tǒng)架構(gòu)、下載對(duì)應(yīng)版本的二進(jìn)制包、解壓到/opt/openclaw、生成 systemd unit 文件、啟動(dòng)服務(wù)。重點(diǎn)檢查三點(diǎn)下載地址是否走 HTTPS、配置目錄在哪里、服務(wù)名是什么。確認(rèn)沒(méi)問(wèn)題后執(zhí)行sudo bash install.sh --channel stable --port 9527這里有兩個(gè)參數(shù)值得解釋--channel stable表示安裝穩(wěn)定版。如果你需要測(cè)試預(yù)覽版可以改成--channel beta但我不建議生產(chǎn)環(huán)境裝 beta。--port 9527指定監(jiān)聽(tīng)端口這個(gè)參數(shù)會(huì)直接體現(xiàn)在生成的 systemd unit 里比裝完再去改配置方便。安裝完成后的預(yù)期輸出大概是OpenClaw has been installed successfully. Service: openclaw.service Config: /opt/openclaw/config.yaml Web: http://localhost:9527接著啟動(dòng)并檢查狀態(tài)sudo systemctl enable --now openclaw sudo systemctl status openclaw如果看到Active: active (running)說(shuō)明已經(jīng)跑起來(lái)了。此時(shí)訪問(wèn)http://服務(wù)器IP:9527應(yīng)該能看到初始配置頁(yè)面。關(guān)于腳本安裝模式我提醒一個(gè)實(shí)際問(wèn)題腳本里默認(rèn)下載的是最新版安裝包下次重新下載腳本安裝時(shí)版本會(huì)漂移。如果你在某次生產(chǎn)環(huán)境裝的是 v1.4.2另外一臺(tái)機(jī)器隔了三個(gè)月再裝可能變成 v1.5.0兩邊的配置結(jié)構(gòu)不一定完全一致。所以腳本安裝模式的意外之處不在安裝過(guò)程而在版本一致性上。想避免這個(gè)問(wèn)題最好直接用 Docker 鎖定鏡像版本。3.2 Docker 模式用容器隔離跑生產(chǎn)服務(wù)Docker 模式在服務(wù)器上管理起來(lái)最順手。我自己生產(chǎn)環(huán)境用的是這種方式核心原因是鏡像版本可以固定升級(jí)和回滾都是 docker 命令一行的事。創(chuàng)建一個(gè)工作目錄并編寫docker-compose.ymlmkdir -p /opt/openclaw-docker cd /opt/openclaw-docker nano docker-compose.yml寫入以下內(nèi)容services: openclaw: image: openclaw/server:1.4.2 container_name: openclaw restart: unless-stopped ports: - 9527:9527 environment: - TZAsia/Shanghai - LANGzh_CN.UTF-8 - OPENCLAW_DATA_DIR/data volumes: - ./data:/data - ./locales:/app/locales healthcheck: test: [CMD, node, -e, fetch(http://localhost:9527/health).then(rprocess.exit(r.ok?0:1)).catch(()process.exit(1))] interval: 30s timeout: 5s retries: 3逐段解釋image指定了固定版本號(hào) 1.4.2。生產(chǎn)環(huán)境不建議寫latest因?yàn)槟悴恢老乱淮蝑ocker compose pull會(huì)拉到什么行為變更的版本。鎖版本是容器部署的基本習(xí)慣。restart: unless-stopped表示容器意外退出時(shí)自動(dòng)拉起除非你手動(dòng)停止它。跑生產(chǎn)服務(wù)比always好用因?yàn)槭謩?dòng)docker stop之后不會(huì)被強(qiáng)制重啟。TZAsia/Shanghai和LANGzh_CN.UTF-8對(duì)應(yīng)漢化后的時(shí)區(qū)與語(yǔ)言環(huán)境這個(gè)變量必須放在容器環(huán)境里否則容器內(nèi)默認(rèn) UTC 時(shí)間日志時(shí)間和你本地時(shí)間差八小時(shí)。./locales:/app/locales是為了讓后續(xù)替換語(yǔ)言文件不重新構(gòu)建鏡像直接把宿主機(jī)目錄掛載進(jìn)容器漢化資源在宿主機(jī)里改完就能生效。啟動(dòng)命令docker compose up -d docker compose ps看到Status: Up之后再確認(rèn)健康檢查狀態(tài)docker inspect --format{{json .State.Health.Status}} openclaw返回healthy表示服務(wù)正常。Docker 模式下如果要升級(jí)流程是docker compose pull docker compose up -d執(zhí)行pull時(shí)會(huì)拉取新的鏡像up -d會(huì)用新鏡像重建容器。關(guān)鍵是卷沒(méi)有變所以/data下的配置和任務(wù)數(shù)據(jù)不會(huì)丟。升級(jí)之前我會(huì)先docker compose down再docker compose up -d這個(gè)順序能避免直接up -d時(shí)在舊容器尚未停止的情況下覆蓋文件導(dǎo)致的偶發(fā)鎖沖突。Docker 還有一個(gè)隱藏優(yōu)點(diǎn)如果你想在同一臺(tái)機(jī)器上跑多個(gè) OpenClaw 實(shí)例做環(huán)境隔離只需要復(fù)制一份 compose 文件改掉端口和容器名即可。腳本模式和 npm 模式很難同時(shí)運(yùn)行兩個(gè)版本因?yàn)楣蚕硗粋€(gè)全局可執(zhí)行文件。3.3 npm 全局安裝輕量試玩的快速路徑npm 方式適合本地開(kāi)發(fā)、臨時(shí)驗(yàn)證場(chǎng)景。不想裝 Docker也不想拉腳本就用 npm 直接安裝。前置條件是系統(tǒng)里已經(jīng)有 Node.js 20 和 npm。確認(rèn)之后sudo npm install -g openclaw-cli注意命令行工具的包名是openclaw-cli和 Docker 鏡像名openclaw/server不是同一個(gè)。安裝完成后which openclaw openclaw --version啟動(dòng)服務(wù)openclaw start --host 0.0.0.0 --port 9527 --data-dir /opt/openclaw-data這里要解釋--host 0.0.0.0的含義。如果不指定OpenClaw 默認(rèn)綁定到127.0.0.1也就是只能本機(jī)訪問(wèn)。在服務(wù)器上部署時(shí)忘記加0.0.0.0是最常見(jiàn)的坑頁(yè)面永遠(yuǎn)打不開(kāi)但所有看日志的手段都查不出問(wèn)題因?yàn)榉?wù)其實(shí)在正常監(jiān)聽(tīng)。npm 模式下停止服務(wù)openclaw stop如果你在管理目錄之外可以通過(guò)openclaw status查看當(dāng)前運(yùn)行狀態(tài)。npm 模式的隱藏問(wèn)題在于全局 node_modules 的版本沖突。比如你機(jī)器上之前已經(jīng)裝了另一個(gè)依賴axios的知名工具而 OpenClaw 內(nèi)部對(duì) axios 的版本需求不同安裝時(shí)會(huì)強(qiáng)制覆蓋或報(bào)ERESOLVE錯(cuò)誤。解決辦法是在安裝時(shí)加--legacy-peer-depssudo npm install -g openclaw-cli --legacy-peer-deps但我建議你思考一下如果一個(gè)工具連 peer dependency 都理不清那它確實(shí)更適合放在容器里跑?；谶@個(gè)原因我現(xiàn)在只建議“臨時(shí)體驗(yàn)”用 npm 模式生產(chǎn)環(huán)境不要用。4. 中文漢化界面適配把英文界面換成中文漢化聽(tīng)起來(lái)是小事但如果你不明白 OpenClaw 的語(yǔ)言文件加載機(jī)制替換后很可能出現(xiàn)“界面一半英文一半中文”的怪狀態(tài)。這一章我把語(yǔ)言文件結(jié)構(gòu)、替換方法、字體和時(shí)區(qū)適配完整講透。4.1 先弄清這個(gè)項(xiàng)目的語(yǔ)言文件結(jié)構(gòu)OpenClaw 的前端是標(biāo)準(zhǔn) Vue 應(yīng)用語(yǔ)言資源文件路徑一般是/app/locales/en-US.json /app/locales/zh-CN.json其中en-US.json是默認(rèn)語(yǔ)言包zh-CN.json是中文語(yǔ)言包。代碼啟動(dòng)時(shí)會(huì)讀取config.yaml里的language字段來(lái)決定加載哪個(gè) json 文件。你可以理解為“語(yǔ)言包就是一張翻譯對(duì)照表”界面上的每個(gè)按鈕、每條提示都有唯一一個(gè) key比如{ common.save: Save, common.cancel: Cancel, task.add: Add Task }中文語(yǔ)言包就是把value部分換成中文{ common.save: 保存, common.cancel: 取消, task.add: 新增任務(wù) }了解了這個(gè)結(jié)構(gòu)你就能明白為什么有些漢化包安裝之后只漢化了一半因?yàn)樾掳嬖创a里新增了頁(yè)面組件但第三方漢化包沒(méi)有跟上導(dǎo)致zh-CN.json里缺少新 key。此時(shí)界面會(huì)回退到英文顯示。4.2 手工替換語(yǔ)言包的具體步驟我先假設(shè)你使用 Docker 模式宿主機(jī)已經(jīng)創(chuàng)建了/opt/openclaw-docker/locales目錄。第一步確認(rèn)容器內(nèi)語(yǔ)言目錄docker exec -it openclaw ls -la /app/locales正常能看到en-US.json等資源目錄。假設(shè)需要下載第三方漢化包zh-CN.json并放到宿主機(jī)目錄curl -fsSL https://openclaw.example.com/locales/zh-CN.json \ -o /opt/openclaw-docker/locales/zh-CN.json第二步修改docker-compose.yml中備注的掛載路徑后重建并啟動(dòng)容器。或者直接進(jìn)入容器臨時(shí)調(diào)試docker cp /opt/openclaw-docker/locales/zh-CN.json openclaw:/app/locales/zh-CN.json第三步修改配置文件config.yaml。先找到配置文件容器內(nèi)路徑一般是/data/config.yamldocker exec -it openclaw cat /data/config.yaml輸出里能看到一行l(wèi)anguage: en-US改它docker exec -it openclaw sed -i s/language: en-US/language: zh-CN/ /data/config.yaml第四步重啟服務(wù)docker compose restart openclaw如果是腳本安裝模式操作更直接cd /opt/openclaw cp locales/en-US.json locales/en-US.json.bak cp zh-CN.json locales/zh-CN.json sed -i s/language: en-US/language: zh-CN/ /opt/openclaw/config.yaml sudo systemctl restart openclaw重啟之后瀏覽器強(qiáng)制刷新頁(yè)面CtrlShiftR就能看到中文界面了。這里我說(shuō)“強(qiáng)制刷新”是因?yàn)榍岸速Y源會(huì)被瀏覽器緩存語(yǔ)言文件加載過(guò)一次之后哪怕你換掉了刷新不清緩存還是舊頁(yè)面。漢化包替換過(guò)程中需要注意一個(gè)細(xì)節(jié)zh-CN.json的文件編碼必須是 UTF-8不能是帶 BOM 的 UTF-8更不能是 GBK。帶 BOM 會(huì)導(dǎo)致 JSON 解析報(bào)錯(cuò)頁(yè)面白屏。如果編輯工具是 Windows 記事本保存前務(wù)必備份原文件。4.3 中文顯示相關(guān)的字體、時(shí)區(qū)與日期配置界面文字換成中文后通常還會(huì)出現(xiàn)兩個(gè)問(wèn)題字體渲染發(fā)虛、時(shí)間日期格式不對(duì)。OpenClaw 默認(rèn) CSS 里font-family一般是Helvetica Neue, Arial, sans-serif。這套字體方案在英文環(huán)境很清爽但中文下會(huì)落到系統(tǒng)默認(rèn)中文字體顯示效果不穩(wěn)定。修改方式是在自定義 CSS 文件里覆蓋字體棧。我使用的方案是body { font-family: Noto Sans CJK SC, Source Han Sans SC, PingFang SC, Microsoft YaHei, sans-serif; }如果 Ubuntu 系統(tǒng)沒(méi)有安裝 Noto CJK 字體先裝sudo apt install -y fonts-noto-cjk容器內(nèi)則需要再掛載一個(gè)字體目錄volumes: - ./fonts:/usr/share/fonts/custom宿主機(jī)把字體文件放進(jìn)去后執(zhí)行docker exec -it openclaw fc-cache -f時(shí)間日期格式的問(wèn)題根源在時(shí)區(qū)。前面環(huán)境變量里已經(jīng)設(shè)置了TZAsia/Shanghai但如果你在 npm 模式或者腳本模式下沒(méi)設(shè)系統(tǒng)默認(rèn) UTC 時(shí)間任務(wù)列表里的“下次運(yùn)行時(shí)間”會(huì)和本地實(shí)際時(shí)間相差 8 小時(shí)。腳本模式下可以在啟動(dòng)命令前臨時(shí)設(shè)置sudo TZAsia/Shanghai systemctl restart openclaw更徹底的辦法是在 systemd unit 文件里加EnvironmentTZAsia/Shanghai然后重載。日期格式方面OpenClaw 的 24 小時(shí)制與 12 小時(shí)制選項(xiàng)在語(yǔ)言包里。有些第三方漢化包會(huì)把時(shí)間格式覆蓋成YYYY-MM-DD HH:mm:ss如果你更習(xí)慣YYYY年MM月DD日需要在zh-CN.json里找到時(shí)間格式化相關(guān)的 key 手動(dòng)改。這一步?jīng)]有統(tǒng)一標(biāo)準(zhǔn)按自己團(tuán)隊(duì)的閱讀習(xí)慣調(diào)就可以了。5. 部署與漢化過(guò)程中的常見(jiàn)問(wèn)題排查部署環(huán)節(jié)的問(wèn)題很多不是 OpenClaw 本身的問(wèn)題而是系統(tǒng)環(huán)境與配置細(xì)節(jié)。我在不同機(jī)器上踩了幾個(gè)坑整理成速查式的內(nèi)容后臺(tái)管理報(bào)錯(cuò)時(shí)直接按這個(gè)思路查能省不少時(shí)間。5.1 端口被占用改端口前必須做的一件事啟動(dòng)服務(wù)時(shí)報(bào)EADDRINUSE說(shuō)明 9527 端口被別的進(jìn)程占用了。查看占用情況的命令sudo ss -lntp | grep 9527假設(shè)看到輸出里有 PID 1234先確認(rèn)這個(gè)進(jìn)程能不能停掉ps -p 1234 -o pid,comm,args如果占用者是遺留的 OpenClaw 進(jìn)程直接停掉重啟即可。如果是其他服務(wù)建議換一個(gè)端口。改端口最直接的做法是在配置文件中指定。Docker 模式改端口要同時(shí)改兩處compose 文件的宿主機(jī)映射端口以及容器內(nèi) config.yaml 的監(jiān)聽(tīng)端口。ports: - 9528:9527容器內(nèi)監(jiān)聽(tīng)端口保持 9527 不變宿主機(jī)映射改成 9528意思是“宿主機(jī)的 9528 端口轉(zhuǎn)給容器的 9527 端口”。這個(gè)寫法比改容器內(nèi)監(jiān)聽(tīng)端口省事不需要重新構(gòu)建鏡像。改完記得重跑docker compose down docker compose up -d這里必須down再up只執(zhí)行restart可能不會(huì)重新綁定端口。5.2 中文亂碼八成是本地環(huán)境變量出了問(wèn)題如果你已經(jīng)設(shè)置language: zh-CN但頁(yè)面上中文顯示為方塊或問(wèn)號(hào)先不要急著懷疑語(yǔ)言包去查系統(tǒng) locale。在宿主機(jī)執(zhí)行l(wèi)ocale如果輸出是LANGC或者LANGen_US.UTF-8那容器或進(jìn)程里的中文編碼大概率也不會(huì)正常。腳本模式下在/etc/default/locale寫入LANGzh_CN.UTF-8 LC_ALLzh_CN.UTF-8Docker 模式下檢查 compose 文件環(huán)境變量里是否漏了LANGdocker exec -it openclaw env | grep LANG沒(méi)有輸出就說(shuō)明環(huán)境變量沒(méi)生效需要重新docker compose up -d。還有一種情況是語(yǔ)言包本身有問(wèn)題。比如 JSON 里某個(gè)字符串在引號(hào)內(nèi)缺失轉(zhuǎn)義前端解析失敗表現(xiàn)為頁(yè)面整體白屏同時(shí)控制臺(tái)報(bào) parsererror。排查方式node -e JSON.parse(require(fs).readFileSync(/opt/openclaw-docker/locales/zh-CN.json,utf8)); console.log(OK)這一步能把語(yǔ)法問(wèn)題提前暴露不會(huì)讓你翻遍整個(gè)界面。5.3 每次重啟數(shù)據(jù)就丟容器卷映射欠債容器模式下數(shù)據(jù)全丟絕大多數(shù)情況是 compose 文件里沒(méi)有正確映射卷。我先給你一個(gè)自查命令docker compose exec openclaw ls -la /data如果看到任務(wù)和配置都在說(shuō)明卷沒(méi)丟。但還是建議在啟動(dòng)前就規(guī)劃好卷映射別等重啟之后才想起來(lái)。卷映射最容易犯的錯(cuò)誤是把宿主機(jī)某個(gè)已經(jīng)存在的目錄掛載到容器的/app而/app是程序代碼目錄掛載之后直接用宿主機(jī)目錄覆蓋了代碼啟動(dòng)時(shí)程序文件全是空的服務(wù)起不來(lái)。正確的映射是分兩個(gè)卷一個(gè)掛/data存配置和數(shù)據(jù)庫(kù)另一個(gè)掛/app/locales存語(yǔ)言包。別貪圖省事直接把整個(gè)源碼目錄掛出來(lái)。升級(jí)容器時(shí)還有個(gè)典型操作失誤直接用docker rm -f openclaw刪掉容器然后又重新docker compose up。如果當(dāng)時(shí)你用了命名容器而不是 compose 項(xiàng)目新容器可能無(wú)法綁定舊卷數(shù)據(jù)看起來(lái)就像丟了。穩(wěn)妥的做法永遠(yuǎn)是用docker compose down停止不要手動(dòng)去刪容器。6. 在真實(shí)使用中總結(jié)的幾條避坑經(jīng)驗(yàn)6.1 升級(jí)之后漢化失效怎么辦我遇到過(guò)最尷尬的情況是鏡像從 1.4.2 升級(jí)到 1.4.6 后界面回到了英文。原因是新版前端代碼改名了語(yǔ)言文件里的 key 對(duì)不上zh-CN.json里的 key 全部失效。這類問(wèn)題沒(méi)辦法通過(guò)“重新替換語(yǔ)言包”根治必須更新語(yǔ)言包版本。第三方漢化包一般會(huì)跟著上游版本同步發(fā)布升級(jí) OpenClaw 的同時(shí)把/opt/openclaw-docker/locales/zh-CN.json換成對(duì)應(yīng)版本。所以我建議記錄兩個(gè)版本號(hào)OpenClaw 版本號(hào)和漢化包版本號(hào)。兩者不是綁定關(guān)系但必須匹配。否則就是漢化覆蓋不完整的尷尬狀態(tài)。6.2 備份清單不止數(shù)據(jù)語(yǔ)言文件也要備份OpenClaw 的任務(wù)配置、運(yùn)行日志、用戶數(shù)據(jù)都在/data目錄。做備份時(shí)很多人只備份/data忘了語(yǔ)言文件。我自己的備份習(xí)慣是同時(shí)打包三個(gè)目錄tar -czf openclaw-backup-$(date %Y%m%d).tar.gz \ -C /opt/openclaw-docker data locales恢復(fù)時(shí)直接解壓到對(duì)應(yīng)目錄再docker compose restart。因?yàn)檎Z(yǔ)言文件不在/data里備份時(shí)漏了它恢復(fù)后服務(wù)能跑但界面永遠(yuǎn)是英文。如果是 script 安裝模式備份命令略有不同tar -czf openclaw-backup-$(date %Y%m%d).tar.gz \ /opt/openclaw/config.yaml \ /opt/openclaw/data \ /opt/openclaw/locales6.3 給新手的最小可用配置模板如果你第一次搭 OpenClaw還不知道自己需要哪些高級(jí)配置我給你一個(gè)可以直接照抄的 compose 模板services: openclaw: image: openclaw/server:1.4.2 container_name: openclaw restart: unless-stopped ports: - 9527:9527 environment: - TZAsia/Shanghai - LANGzh_CN.UTF-8 - OPENCLAW_DATA_DIR/data - OPENCLAW_SERVER_NAMEnode-01 volumes: - ./data:/data - ./locales:/app/locales配置里加了OPENCLAW_SERVER_NAMEnode-01這個(gè)環(huán)境變量會(huì)顯示在管理后臺(tái)的節(jié)點(diǎn)名稱里。如果你打算同時(shí)管理多臺(tái)服務(wù)器這個(gè)字段能幫你區(qū)分來(lái)源屬于“早期不多想、后期多出淚”的典型配置。我個(gè)人在實(shí)際操作中的體會(huì)是別急著把所有高級(jí)參數(shù)配齊。先把服務(wù)跑起來(lái)、界面漢化、跑通一條 Webhook再逐步加限制和告警。否則你根本連配置項(xiàng)對(duì)應(yīng)的現(xiàn)象都分不清出現(xiàn)異常時(shí)會(huì)陷入“不知道改誰(shuí)”的困境。先簡(jiǎn)單后復(fù)雜這比任何安裝指南都重要。最后再分享一個(gè)習(xí)慣每次大版本升級(jí)前手動(dòng)在管理后臺(tái)導(dǎo)出一次任務(wù)配置再打一個(gè) tar 包存到獨(dú)立目錄。OpenClaw 的基本盤是它的開(kāi)放性和可控性但所有自托管系統(tǒng)的共同規(guī)律都是一樣的數(shù)據(jù)留在自己手里工具換多少代都不慌。 Ubuntu下部署OpenClaw：一鍵腳本/Docker/npm與漢化全指南
前陣子有讀者問(wèn)我OpenClaw 這種開(kāi)源自動(dòng)化網(wǎng)關(guān)項(xiàng)目到底值不值得自己在本機(jī)部署一套。我的答案是如果你需要一個(gè)能把 Webhook、定時(shí)任務(wù)、消息通知、Shell 指令收斂到一個(gè)統(tǒng)一后臺(tái)的小型服務(wù)OpenClaw 是我試過(guò)的一條性價(jià)比很高的路徑。社區(qū)里有叫它 Clawdbot 的也有叫 Moltbot 的實(shí)際都是同一套東西在不同分支下的代號(hào)下面我統(tǒng)稱 OpenClaw。這篇文章我會(huì)從零開(kāi)始把 Ubuntu 上的環(huán)境準(zhǔn)備、一鍵腳本 / Docker / npm 三種安裝方式、中文漢化界面適配以及我在實(shí)際部署中踩過(guò)的坑完整記錄一遍。內(nèi)容不是照著官方 README 翻譯而是結(jié)合我自己的踩坑經(jīng)歷來(lái)寫適合剛接觸開(kāi)源服務(wù)部署的開(kāi)發(fā)者也適合已經(jīng)跑過(guò)一段自托管服務(wù)、想換個(gè)更可控方案的老手。1. 開(kāi)工之前OpenClaw 到底是什么為什么值得本地部署1.1 一句話理解這個(gè)開(kāi)源項(xiàng)目的能力邊界OpenClaw 本質(zhì)是一個(gè)“事件驅(qū)動(dòng)的自動(dòng)化服務(wù)網(wǎng)關(guān)”。你可以把它理解為一條收納繩外部系統(tǒng)通過(guò) Webhook 把事件丟進(jìn)來(lái)它負(fù)責(zé)判斷該觸發(fā)什么流程內(nèi)部服務(wù)通過(guò)定時(shí)任務(wù)把計(jì)劃執(zhí)行起來(lái)它負(fù)責(zé)按 cron 表達(dá)式調(diào)動(dòng)命令再配上通知模塊完成之后往釘釘、飛書(shū)這類渠道推一條結(jié)果。這樣描述還是有點(diǎn)抽象。我舉個(gè)實(shí)際場(chǎng)景假設(shè)你維護(hù)了三臺(tái)服務(wù)器每天要輪流備份目錄、清理日志、檢查端口狀態(tài)。傳統(tǒng)做法是把 Shell 腳本放到每臺(tái)機(jī)器的 cron 里日志散落各處管起來(lái)非常費(fèi)勁。OpenClaw 的運(yùn)行方式是讓三臺(tái)機(jī)器都裝上輕量客戶端把執(zhí)行任務(wù)統(tǒng)一上報(bào)到服務(wù)端你在瀏覽器里打開(kāi)控制臺(tái)能看到所有任務(wù)狀態(tài)也能直接在界面里加一條新的定時(shí)任務(wù)。這個(gè)過(guò)程中你不需要寫一套完整的任務(wù)調(diào)度系統(tǒng)只需要把自己公司的業(yè)務(wù)腳本掛進(jìn)去。它適合誰(shuí)適合以下幾類人內(nèi)部工具鏈比較分散需要一個(gè)集中管理入口的團(tuán)隊(duì)已經(jīng)在用各類開(kāi)源監(jiān)控工具但不想被商業(yè)產(chǎn)品鎖定個(gè)人開(kāi)發(fā)者有多臺(tái) VPS 或家用服務(wù)器想統(tǒng)一管理定時(shí)任務(wù)和 Webhook想做二次開(kāi)發(fā)需要一套前后端分離、代碼結(jié)構(gòu)清晰的開(kāi)源項(xiàng)目作為腳手架。項(xiàng)目本身默認(rèn)英文界面源碼里也預(yù)留了國(guó)際化資源目錄所以漢化不是硬改代碼而是替換語(yǔ)言資源文件的事。這也是我在后面單獨(dú)用一章寫適配的原因。1.2 一鍵腳本、Docker、npm 三種模式的取舍安裝方式多不代表每條都適合你。選擇之前先搞清楚自己的運(yùn)行場(chǎng)景。一鍵腳本適合的場(chǎng)景是“新機(jī)器、只裝這一個(gè)服務(wù)、想要馬上跑起來(lái)”。腳本解決的問(wèn)題是環(huán)境依賴和系統(tǒng)服務(wù)注冊(cè)它會(huì)把可執(zhí)行文件、配置目錄、systemd 單元一次處理好裝完直接能通過(guò)systemctl管理。缺點(diǎn)是升級(jí)路徑不透明腳本不可見(jiàn)的情況下你很難知道它動(dòng)了哪些系統(tǒng)文件。Docker 模式適合“機(jī)器上已經(jīng)有多種服務(wù)想隔離運(yùn)行”。OpenClaw 需要 Node.js 運(yùn)行時(shí)和一堆系統(tǒng)依賴如果全部裝進(jìn)宿主機(jī)很容易和你現(xiàn)有的 Python 或 Go 服務(wù)產(chǎn)生 glibc 版本沖突。用容器把應(yīng)用和宿主隔開(kāi)升級(jí)就是換鏡像、重啟容器回滾也方便。生產(chǎn)環(huán)境我一般推薦這種。npm 模式適合“只是想跑一下看看后面大概率會(huì)換部署方式”的試驗(yàn)場(chǎng)景。它本質(zhì)上就是把 OpenClaw 當(dāng)作一個(gè) Node CLI 工具全局安裝后直接openclaw start。優(yōu)點(diǎn)是快缺點(diǎn)是你需要在宿主機(jī)手動(dòng)裝 Node.js版本一偏就容易出問(wèn)題而且全局 node_modules 里的殘留很煩。安裝方式上手速度隔離性升級(jí)難度適合場(chǎng)景一鍵腳本極快低中新機(jī)器快速部署Docker較快高低生產(chǎn)/多服務(wù)共存npm最快低中試用、開(kāi)發(fā)調(diào)試后面第 3 章會(huì)分別給出這三條線的完整操作和實(shí)測(cè)輸出。2. Ubuntu 環(huán)境準(zhǔn)備先把地基做扎實(shí)不少人在安裝階段報(bào)錯(cuò)不是 OpenClaw 的問(wèn)題而是底層環(huán)境太亂。域名解析、時(shí)區(qū)、防火墻、依賴版本都對(duì)不齊裝到一半才暴露出來(lái)排查時(shí)往往分不清是環(huán)境問(wèn)題還是應(yīng)用問(wèn)題。所以這部分我建議認(rèn)真過(guò)一遍裝完再開(kāi)始安裝。2.1 系統(tǒng)更新、基礎(chǔ)工具與語(yǔ)言環(huán)境我測(cè)試用的系統(tǒng)是 Ubuntu 22.04 LTS內(nèi)核版本在 5.15 以上運(yùn)行內(nèi)存給了 2GB。如果條件差一點(diǎn)也沒(méi)關(guān)系OpenClaw 本身占用不高但 Node.js 構(gòu)建時(shí)對(duì) CPU 壓力比較大內(nèi)存低于 1GB 的機(jī)器建議先加 swap。登錄之后先更新軟件源緩存和系統(tǒng)包sudo apt update sudo apt upgrade -y這一步不是走過(guò)場(chǎng)。很多第三方二進(jìn)制包依賴libssl、libicu等庫(kù)的特定版本舊系統(tǒng)里這些庫(kù)版本落后安裝工具時(shí)可能裝不上最新依賴。接著安裝基礎(chǔ)工具sudo apt install -y curl wget git jq unzipjq我特別說(shuō)一下OpenClaw 控制臺(tái)里有一些調(diào)試接口返回 JSON用 jq 格式化之后看起來(lái)舒服很多。調(diào)試 Webhook 的時(shí)候少一個(gè) jq 會(huì)多花很多時(shí)間在肉眼摳括號(hào)上。語(yǔ)言環(huán)境這一塊容易被忽略。OpenClaw 漢化之后中文在命令行和日志里的顯示是否正常取決于系統(tǒng)區(qū)域設(shè)置。先確認(rèn)當(dāng)前環(huán)境locale如果輸出里的LANG不是zh_CN.UTF-8或en_US.UTF-8需要安裝并生成語(yǔ)言包sudo apt install -y locales sudo locale-gen en_US.UTF-8 zh_CN.UTF-8 sudo update-locale LANGzh_CN.UTF-8 LC_ALLzh_CN.UTF-8這里設(shè)成中文環(huán)境有個(gè)好處之后 OpenClaw 日志里的時(shí)間日期格式會(huì)直接跟隨系統(tǒng)時(shí)區(qū)不容易出現(xiàn)“文件名稱是中文但終端顯示全是問(wèn)號(hào)”的怪問(wèn)題。注意改完 locale 之后當(dāng)前 SSH 會(huì)話里的環(huán)境變量不會(huì)立刻生效退出重新登錄一下或者手動(dòng)執(zhí)行export LANGzh_CN.UTF-8。2.2 運(yùn)行時(shí)依賴裝到哪個(gè)版本最穩(wěn)OpenClaw 基于 Node.js 構(gòu)建官方文檔標(biāo)注支持 Node.js 18 和 20 兩個(gè)大版本。我實(shí)際測(cè)試下來(lái)20 LTS 的兼容性最好18 在某些老版本上會(huì)出現(xiàn)內(nèi)置 fetch 行為差異導(dǎo)致 Webhook 請(qǐng)求異常。如果走 npm 安裝模式需要先裝 Node.js。這里我建議使用 NodeSource 提供的二進(jìn)制包不用發(fā)行版自帶的低版本curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs裝完確認(rèn)版本node -v npm -v另外如果之前裝過(guò)舊版 Node.js最好先卸載干凈再裝否則/usr/bin/node的軟鏈會(huì)混亂npm 全局安裝的工具可能找不到可執(zhí)行文件。如果走 Docker 模式其實(shí)不要求在宿主機(jī)裝 Node.js但需要裝 Docker Engine 和 Docker Compose 插件。官方安裝腳本仍然可用curl -fsSL https://get.docker.com/ | sudo sh sudo systemctl enable --now docker docker compose version注意 Docker 安裝后當(dāng)前用戶執(zhí)行 docker 命令可能會(huì)報(bào)權(quán)限錯(cuò)誤。解決辦法是把自己加入 docker 組或者臨時(shí)用 sudo 執(zhí)行。sudo usermod -aG docker $USER newgrp docker這里解釋一下為什么我不建議直接用 apt 安裝 Docker 的發(fā)行版?zhèn)}庫(kù)版本。Ubuntu 倉(cāng)庫(kù)里的 docker 包往往不是最新而且沒(méi)有把 compose 插件整合好后面寫docker compose up時(shí)格式不兼容會(huì)很尷尬。官方腳本安裝的是社區(qū)版最新版和 compose 插件配合最順。2.3 端口、防火墻與目錄權(quán)限規(guī)劃OpenClaw 的核心是 Web 管理端和 Webhook 接收端默認(rèn)端口是 9527。這個(gè)端口可以改但為了避免之后排查困難我建議第一次部署就用默認(rèn)值跑通之后再考慮改端口。如果啟用了 UFW 防火墻需要放行端口sudo ufw allow 9527/tcp sudo ufw enable sudo ufw status verbose還有個(gè)細(xì)節(jié)如果你打算用 Nginx 反代就只需要對(duì)公網(wǎng)放行 80/4439527 端口僅綁定內(nèi)網(wǎng)地址。但如果只是想快速試用直接在服務(wù)器上放行 9527 也行。目錄權(quán)限方面OpenClaw 會(huì)把配置、日志、語(yǔ)言包放在/opt/openclaw下。一鍵腳本安裝時(shí)會(huì)自動(dòng)創(chuàng)建該目錄npm 模式則放在用戶的.openclaw目錄下。Docker 模式需要你手動(dòng)指定卷映射?？偟脑瓌t是別用 root 直接跑客戶端進(jìn)程單獨(dú)建一個(gè)系統(tǒng)用戶更安全。sudo useradd --system --home /opt/openclaw --shell /usr/sbin/nologin openclaw sudo mkdir -p /opt/openclaw sudo chown -R openclaw:openclaw /opt/openclaw這個(gè)用戶只用來(lái)運(yùn)行 OpenClaw 服務(wù)沒(méi)有登錄 Shell 權(quán)限即使 Web 端被攻破攻擊者也無(wú)法直接通過(guò)這個(gè)用戶拿到系統(tǒng)登錄權(quán)限。3. 三種安裝模式完整實(shí)操記錄3.1 一鍵腳本模式適合“今天就要用起來(lái)”的場(chǎng)景一鍵腳本最大的優(yōu)勢(shì)是省事但我不推薦“網(wǎng)上隨便找一個(gè)命令就粘貼執(zhí)行”。安全習(xí)慣是先下載下來(lái)看一遍內(nèi)容再跑。curl -fsSL https://openclaw.example.com/install.sh -o install.sh less install.sh腳本內(nèi)容大致分為幾塊檢查系統(tǒng)架構(gòu)、下載對(duì)應(yīng)版本的二進(jìn)制包、解壓到/opt/openclaw、生成 systemd unit 文件、啟動(dòng)服務(wù)。重點(diǎn)檢查三點(diǎn)下載地址是否走 HTTPS、配置目錄在哪里、服務(wù)名是什么。確認(rèn)沒(méi)問(wèn)題后執(zhí)行sudo bash install.sh --channel stable --port 9527這里有兩個(gè)參數(shù)值得解釋--channel stable表示安裝穩(wěn)定版。如果你需要測(cè)試預(yù)覽版可以改成--channel beta但我不建議生產(chǎn)環(huán)境裝 beta。--port 9527指定監(jiān)聽(tīng)端口這個(gè)參數(shù)會(huì)直接體現(xiàn)在生成的 systemd unit 里比裝完再去改配置方便。安裝完成后的預(yù)期輸出大概是OpenClaw has been installed successfully. Service: openclaw.service Config: /opt/openclaw/config.yaml Web: http://localhost:9527接著啟動(dòng)并檢查狀態(tài)sudo systemctl enable --now openclaw sudo systemctl status openclaw如果看到Active: active (running)說(shuō)明已經(jīng)跑起來(lái)了。此時(shí)訪問(wèn)http://服務(wù)器IP:9527應(yīng)該能看到初始配置頁(yè)面。關(guān)于腳本安裝模式我提醒一個(gè)實(shí)際問(wèn)題腳本里默認(rèn)下載的是最新版安裝包下次重新下載腳本安裝時(shí)版本會(huì)漂移。如果你在某次生產(chǎn)環(huán)境裝的是 v1.4.2另外一臺(tái)機(jī)器隔了三個(gè)月再裝可能變成 v1.5.0兩邊的配置結(jié)構(gòu)不一定完全一致。所以腳本安裝模式的意外之處不在安裝過(guò)程而在版本一致性上。想避免這個(gè)問(wèn)題最好直接用 Docker 鎖定鏡像版本。3.2 Docker 模式用容器隔離跑生產(chǎn)服務(wù)Docker 模式在服務(wù)器上管理起來(lái)最順手。我自己生產(chǎn)環(huán)境用的是這種方式核心原因是鏡像版本可以固定升級(jí)和回滾都是 docker 命令一行的事。創(chuàng)建一個(gè)工作目錄并編寫docker-compose.ymlmkdir -p /opt/openclaw-docker cd /opt/openclaw-docker nano docker-compose.yml寫入以下內(nèi)容services: openclaw: image: openclaw/server:1.4.2 container_name: openclaw restart: unless-stopped ports: - 9527:9527 environment: - TZAsia/Shanghai - LANGzh_CN.UTF-8 - OPENCLAW_DATA_DIR/data volumes: - ./data:/data - ./locales:/app/locales healthcheck: test: [CMD, node, -e, fetch(http://localhost:9527/health).then(rprocess.exit(r.ok?0:1)).catch(()process.exit(1))] interval: 30s timeout: 5s retries: 3逐段解釋image指定了固定版本號(hào) 1.4.2。生產(chǎn)環(huán)境不建議寫latest因?yàn)槟悴恢老乱淮蝑ocker compose pull會(huì)拉到什么行為變更的版本。鎖版本是容器部署的基本習(xí)慣。restart: unless-stopped表示容器意外退出時(shí)自動(dòng)拉起除非你手動(dòng)停止它。跑生產(chǎn)服務(wù)比always好用因?yàn)槭謩?dòng)docker stop之后不會(huì)被強(qiáng)制重啟。TZAsia/Shanghai和LANGzh_CN.UTF-8對(duì)應(yīng)漢化后的時(shí)區(qū)與語(yǔ)言環(huán)境這個(gè)變量必須放在容器環(huán)境里否則容器內(nèi)默認(rèn) UTC 時(shí)間日志時(shí)間和你本地時(shí)間差八小時(shí)。./locales:/app/locales是為了讓后續(xù)替換語(yǔ)言文件不重新構(gòu)建鏡像直接把宿主機(jī)目錄掛載進(jìn)容器漢化資源在宿主機(jī)里改完就能生效。啟動(dòng)命令docker compose up -d docker compose ps看到Status: Up之后再確認(rèn)健康檢查狀態(tài)docker inspect --format{{json .State.Health.Status}} openclaw返回healthy表示服務(wù)正常。Docker 模式下如果要升級(jí)流程是docker compose pull docker compose up -d執(zhí)行pull時(shí)會(huì)拉取新的鏡像up -d會(huì)用新鏡像重建容器。關(guān)鍵是卷沒(méi)有變所以/data下的配置和任務(wù)數(shù)據(jù)不會(huì)丟。升級(jí)之前我會(huì)先docker compose down再docker compose up -d這個(gè)順序能避免直接up -d時(shí)在舊容器尚未停止的情況下覆蓋文件導(dǎo)致的偶發(fā)鎖沖突。Docker 還有一個(gè)隱藏優(yōu)點(diǎn)如果你想在同一臺(tái)機(jī)器上跑多個(gè) OpenClaw 實(shí)例做環(huán)境隔離只需要復(fù)制一份 compose 文件改掉端口和容器名即可。腳本模式和 npm 模式很難同時(shí)運(yùn)行兩個(gè)版本因?yàn)楣蚕硗粋€(gè)全局可執(zhí)行文件。3.3 npm 全局安裝輕量試玩的快速路徑npm 方式適合本地開(kāi)發(fā)、臨時(shí)驗(yàn)證場(chǎng)景。不想裝 Docker也不想拉腳本就用 npm 直接安裝。前置條件是系統(tǒng)里已經(jīng)有 Node.js 20 和 npm。確認(rèn)之后sudo npm install -g openclaw-cli注意命令行工具的包名是openclaw-cli和 Docker 鏡像名openclaw/server不是同一個(gè)。安裝完成后which openclaw openclaw --version啟動(dòng)服務(wù)openclaw start --host 0.0.0.0 --port 9527 --data-dir /opt/openclaw-data這里要解釋--host 0.0.0.0的含義。如果不指定OpenClaw 默認(rèn)綁定到127.0.0.1也就是只能本機(jī)訪問(wèn)。在服務(wù)器上部署時(shí)忘記加0.0.0.0是最常見(jiàn)的坑頁(yè)面永遠(yuǎn)打不開(kāi)但所有看日志的手段都查不出問(wèn)題因?yàn)榉?wù)其實(shí)在正常監(jiān)聽(tīng)。npm 模式下停止服務(wù)openclaw stop如果你在管理目錄之外可以通過(guò)openclaw status查看當(dāng)前運(yùn)行狀態(tài)。npm 模式的隱藏問(wèn)題在于全局 node_modules 的版本沖突。比如你機(jī)器上之前已經(jīng)裝了另一個(gè)依賴axios的知名工具而 OpenClaw 內(nèi)部對(duì) axios 的版本需求不同安裝時(shí)會(huì)強(qiáng)制覆蓋或報(bào)ERESOLVE錯(cuò)誤。解決辦法是在安裝時(shí)加--legacy-peer-depssudo npm install -g openclaw-cli --legacy-peer-deps但我建議你思考一下如果一個(gè)工具連 peer dependency 都理不清那它確實(shí)更適合放在容器里跑?；谶@個(gè)原因我現(xiàn)在只建議“臨時(shí)體驗(yàn)”用 npm 模式生產(chǎn)環(huán)境不要用。4. 中文漢化界面適配把英文界面換成中文漢化聽(tīng)起來(lái)是小事但如果你不明白 OpenClaw 的語(yǔ)言文件加載機(jī)制替換后很可能出現(xiàn)“界面一半英文一半中文”的怪狀態(tài)。這一章我把語(yǔ)言文件結(jié)構(gòu)、替換方法、字體和時(shí)區(qū)適配完整講透。4.1 先弄清這個(gè)項(xiàng)目的語(yǔ)言文件結(jié)構(gòu)OpenClaw 的前端是標(biāo)準(zhǔn) Vue 應(yīng)用語(yǔ)言資源文件路徑一般是/app/locales/en-US.json /app/locales/zh-CN.json其中en-US.json是默認(rèn)語(yǔ)言包zh-CN.json是中文語(yǔ)言包。代碼啟動(dòng)時(shí)會(huì)讀取config.yaml里的language字段來(lái)決定加載哪個(gè) json 文件。你可以理解為“語(yǔ)言包就是一張翻譯對(duì)照表”界面上的每個(gè)按鈕、每條提示都有唯一一個(gè) key比如{ common.save: Save, common.cancel: Cancel, task.add: Add Task }中文語(yǔ)言包就是把value部分換成中文{ common.save: 保存, common.cancel: 取消, task.add: 新增任務(wù) }了解了這個(gè)結(jié)構(gòu)你就能明白為什么有些漢化包安裝之后只漢化了一半因?yàn)樾掳嬖创a里新增了頁(yè)面組件但第三方漢化包沒(méi)有跟上導(dǎo)致zh-CN.json里缺少新 key。此時(shí)界面會(huì)回退到英文顯示。4.2 手工替換語(yǔ)言包的具體步驟我先假設(shè)你使用 Docker 模式宿主機(jī)已經(jīng)創(chuàng)建了/opt/openclaw-docker/locales目錄。第一步確認(rèn)容器內(nèi)語(yǔ)言目錄docker exec -it openclaw ls -la /app/locales正常能看到en-US.json等資源目錄。假設(shè)需要下載第三方漢化包zh-CN.json并放到宿主機(jī)目錄curl -fsSL https://openclaw.example.com/locales/zh-CN.json \ -o /opt/openclaw-docker/locales/zh-CN.json第二步修改docker-compose.yml中備注的掛載路徑后重建并啟動(dòng)容器。或者直接進(jìn)入容器臨時(shí)調(diào)試docker cp /opt/openclaw-docker/locales/zh-CN.json openclaw:/app/locales/zh-CN.json第三步修改配置文件config.yaml。先找到配置文件容器內(nèi)路徑一般是/data/config.yamldocker exec -it openclaw cat /data/config.yaml輸出里能看到一行l(wèi)anguage: en-US改它docker exec -it openclaw sed -i s/language: en-US/language: zh-CN/ /data/config.yaml第四步重啟服務(wù)docker compose restart openclaw如果是腳本安裝模式操作更直接cd /opt/openclaw cp locales/en-US.json locales/en-US.json.bak cp zh-CN.json locales/zh-CN.json sed -i s/language: en-US/language: zh-CN/ /opt/openclaw/config.yaml sudo systemctl restart openclaw重啟之后瀏覽器強(qiáng)制刷新頁(yè)面CtrlShiftR就能看到中文界面了。這里我說(shuō)“強(qiáng)制刷新”是因?yàn)榍岸速Y源會(huì)被瀏覽器緩存語(yǔ)言文件加載過(guò)一次之后哪怕你換掉了刷新不清緩存還是舊頁(yè)面。漢化包替換過(guò)程中需要注意一個(gè)細(xì)節(jié)zh-CN.json的文件編碼必須是 UTF-8不能是帶 BOM 的 UTF-8更不能是 GBK。帶 BOM 會(huì)導(dǎo)致 JSON 解析報(bào)錯(cuò)頁(yè)面白屏。如果編輯工具是 Windows 記事本保存前務(wù)必備份原文件。4.3 中文顯示相關(guān)的字體、時(shí)區(qū)與日期配置界面文字換成中文后通常還會(huì)出現(xiàn)兩個(gè)問(wèn)題字體渲染發(fā)虛、時(shí)間日期格式不對(duì)。OpenClaw 默認(rèn) CSS 里font-family一般是Helvetica Neue, Arial, sans-serif。這套字體方案在英文環(huán)境很清爽但中文下會(huì)落到系統(tǒng)默認(rèn)中文字體顯示效果不穩(wěn)定。修改方式是在自定義 CSS 文件里覆蓋字體棧。我使用的方案是body { font-family: Noto Sans CJK SC, Source Han Sans SC, PingFang SC, Microsoft YaHei, sans-serif; }如果 Ubuntu 系統(tǒng)沒(méi)有安裝 Noto CJK 字體先裝sudo apt install -y fonts-noto-cjk容器內(nèi)則需要再掛載一個(gè)字體目錄volumes: - ./fonts:/usr/share/fonts/custom宿主機(jī)把字體文件放進(jìn)去后執(zhí)行docker exec -it openclaw fc-cache -f時(shí)間日期格式的問(wèn)題根源在時(shí)區(qū)。前面環(huán)境變量里已經(jīng)設(shè)置了TZAsia/Shanghai但如果你在 npm 模式或者腳本模式下沒(méi)設(shè)系統(tǒng)默認(rèn) UTC 時(shí)間任務(wù)列表里的“下次運(yùn)行時(shí)間”會(huì)和本地實(shí)際時(shí)間相差 8 小時(shí)。腳本模式下可以在啟動(dòng)命令前臨時(shí)設(shè)置sudo TZAsia/Shanghai systemctl restart openclaw更徹底的辦法是在 systemd unit 文件里加EnvironmentTZAsia/Shanghai然后重載。日期格式方面OpenClaw 的 24 小時(shí)制與 12 小時(shí)制選項(xiàng)在語(yǔ)言包里。有些第三方漢化包會(huì)把時(shí)間格式覆蓋成YYYY-MM-DD HH:mm:ss如果你更習(xí)慣YYYY年MM月DD日需要在zh-CN.json里找到時(shí)間格式化相關(guān)的 key 手動(dòng)改。這一步?jīng)]有統(tǒng)一標(biāo)準(zhǔn)按自己團(tuán)隊(duì)的閱讀習(xí)慣調(diào)就可以了。5. 部署與漢化過(guò)程中的常見(jiàn)問(wèn)題排查部署環(huán)節(jié)的問(wèn)題很多不是 OpenClaw 本身的問(wèn)題而是系統(tǒng)環(huán)境與配置細(xì)節(jié)。我在不同機(jī)器上踩了幾個(gè)坑整理成速查式的內(nèi)容后臺(tái)管理報(bào)錯(cuò)時(shí)直接按這個(gè)思路查能省不少時(shí)間。5.1 端口被占用改端口前必須做的一件事啟動(dòng)服務(wù)時(shí)報(bào)EADDRINUSE說(shuō)明 9527 端口被別的進(jìn)程占用了。查看占用情況的命令sudo ss -lntp | grep 9527假設(shè)看到輸出里有 PID 1234先確認(rèn)這個(gè)進(jìn)程能不能停掉ps -p 1234 -o pid,comm,args如果占用者是遺留的 OpenClaw 進(jìn)程直接停掉重啟即可。如果是其他服務(wù)建議換一個(gè)端口。改端口最直接的做法是在配置文件中指定。Docker 模式改端口要同時(shí)改兩處compose 文件的宿主機(jī)映射端口以及容器內(nèi) config.yaml 的監(jiān)聽(tīng)端口。ports: - 9528:9527容器內(nèi)監(jiān)聽(tīng)端口保持 9527 不變宿主機(jī)映射改成 9528意思是“宿主機(jī)的 9528 端口轉(zhuǎn)給容器的 9527 端口”。這個(gè)寫法比改容器內(nèi)監(jiān)聽(tīng)端口省事不需要重新構(gòu)建鏡像。改完記得重跑docker compose down docker compose up -d這里必須down再up只執(zhí)行restart可能不會(huì)重新綁定端口。5.2 中文亂碼八成是本地環(huán)境變量出了問(wèn)題如果你已經(jīng)設(shè)置language: zh-CN但頁(yè)面上中文顯示為方塊或問(wèn)號(hào)先不要急著懷疑語(yǔ)言包去查系統(tǒng) locale。在宿主機(jī)執(zhí)行l(wèi)ocale如果輸出是LANGC或者LANGen_US.UTF-8那容器或進(jìn)程里的中文編碼大概率也不會(huì)正常。腳本模式下在/etc/default/locale寫入LANGzh_CN.UTF-8 LC_ALLzh_CN.UTF-8Docker 模式下檢查 compose 文件環(huán)境變量里是否漏了LANGdocker exec -it openclaw env | grep LANG沒(méi)有輸出就說(shuō)明環(huán)境變量沒(méi)生效需要重新docker compose up -d。還有一種情況是語(yǔ)言包本身有問(wèn)題。比如 JSON 里某個(gè)字符串在引號(hào)內(nèi)缺失轉(zhuǎn)義前端解析失敗表現(xiàn)為頁(yè)面整體白屏同時(shí)控制臺(tái)報(bào) parsererror。排查方式node -e JSON.parse(require(fs).readFileSync(/opt/openclaw-docker/locales/zh-CN.json,utf8)); console.log(OK)這一步能把語(yǔ)法問(wèn)題提前暴露不會(huì)讓你翻遍整個(gè)界面。5.3 每次重啟數(shù)據(jù)就丟容器卷映射欠債容器模式下數(shù)據(jù)全丟絕大多數(shù)情況是 compose 文件里沒(méi)有正確映射卷。我先給你一個(gè)自查命令docker compose exec openclaw ls -la /data如果看到任務(wù)和配置都在說(shuō)明卷沒(méi)丟。但還是建議在啟動(dòng)前就規(guī)劃好卷映射別等重啟之后才想起來(lái)。卷映射最容易犯的錯(cuò)誤是把宿主機(jī)某個(gè)已經(jīng)存在的目錄掛載到容器的/app而/app是程序代碼目錄掛載之后直接用宿主機(jī)目錄覆蓋了代碼啟動(dòng)時(shí)程序文件全是空的服務(wù)起不來(lái)。正確的映射是分兩個(gè)卷一個(gè)掛/data存配置和數(shù)據(jù)庫(kù)另一個(gè)掛/app/locales存語(yǔ)言包。別貪圖省事直接把整個(gè)源碼目錄掛出來(lái)。升級(jí)容器時(shí)還有個(gè)典型操作失誤直接用docker rm -f openclaw刪掉容器然后又重新docker compose up。如果當(dāng)時(shí)你用了命名容器而不是 compose 項(xiàng)目新容器可能無(wú)法綁定舊卷數(shù)據(jù)看起來(lái)就像丟了。穩(wěn)妥的做法永遠(yuǎn)是用docker compose down停止不要手動(dòng)去刪容器。6. 在真實(shí)使用中總結(jié)的幾條避坑經(jīng)驗(yàn)6.1 升級(jí)之后漢化失效怎么辦我遇到過(guò)最尷尬的情況是鏡像從 1.4.2 升級(jí)到 1.4.6 后界面回到了英文。原因是新版前端代碼改名了語(yǔ)言文件里的 key 對(duì)不上zh-CN.json里的 key 全部失效。這類問(wèn)題沒(méi)辦法通過(guò)“重新替換語(yǔ)言包”根治必須更新語(yǔ)言包版本。第三方漢化包一般會(huì)跟著上游版本同步發(fā)布升級(jí) OpenClaw 的同時(shí)把/opt/openclaw-docker/locales/zh-CN.json換成對(duì)應(yīng)版本。所以我建議記錄兩個(gè)版本號(hào)OpenClaw 版本號(hào)和漢化包版本號(hào)。兩者不是綁定關(guān)系但必須匹配。否則就是漢化覆蓋不完整的尷尬狀態(tài)。6.2 備份清單不止數(shù)據(jù)語(yǔ)言文件也要備份OpenClaw 的任務(wù)配置、運(yùn)行日志、用戶數(shù)據(jù)都在/data目錄。做備份時(shí)很多人只備份/data忘了語(yǔ)言文件。我自己的備份習(xí)慣是同時(shí)打包三個(gè)目錄tar -czf openclaw-backup-$(date %Y%m%d).tar.gz \ -C /opt/openclaw-docker data locales恢復(fù)時(shí)直接解壓到對(duì)應(yīng)目錄再docker compose restart。因?yàn)檎Z(yǔ)言文件不在/data里備份時(shí)漏了它恢復(fù)后服務(wù)能跑但界面永遠(yuǎn)是英文。如果是 script 安裝模式備份命令略有不同tar -czf openclaw-backup-$(date %Y%m%d).tar.gz \ /opt/openclaw/config.yaml \ /opt/openclaw/data \ /opt/openclaw/locales6.3 給新手的最小可用配置模板如果你第一次搭 OpenClaw還不知道自己需要哪些高級(jí)配置我給你一個(gè)可以直接照抄的 compose 模板services: openclaw: image: openclaw/server:1.4.2 container_name: openclaw restart: unless-stopped ports: - 9527:9527 environment: - TZAsia/Shanghai - LANGzh_CN.UTF-8 - OPENCLAW_DATA_DIR/data - OPENCLAW_SERVER_NAMEnode-01 volumes: - ./data:/data - ./locales:/app/locales配置里加了OPENCLAW_SERVER_NAMEnode-01這個(gè)環(huán)境變量會(huì)顯示在管理后臺(tái)的節(jié)點(diǎn)名稱里。如果你打算同時(shí)管理多臺(tái)服務(wù)器這個(gè)字段能幫你區(qū)分來(lái)源屬于“早期不多想、后期多出淚”的典型配置。我個(gè)人在實(shí)際操作中的體會(huì)是別急著把所有高級(jí)參數(shù)配齊。先把服務(wù)跑起來(lái)、界面漢化、跑通一條 Webhook再逐步加限制和告警。否則你根本連配置項(xiàng)對(duì)應(yīng)的現(xiàn)象都分不清出現(xiàn)異常時(shí)會(huì)陷入“不知道改誰(shuí)”的困境。先簡(jiǎn)單后復(fù)雜這比任何安裝指南都重要。最后再分享一個(gè)習(xí)慣每次大版本升級(jí)前手動(dòng)在管理后臺(tái)導(dǎo)出一次任務(wù)配置再打一個(gè) tar 包存到獨(dú)立目錄。OpenClaw 的基本盤是它的開(kāi)放性和可控性但所有自托管系統(tǒng)的共同規(guī)律都是一樣的數(shù)據(jù)留在自己手里工具換多少代都不慌。