前陣子有讀者問我OpenClaw 這種開源自動(dòng)化網(wǎng)關(guān)項(xiàng)目到底值不值得自己在本機(jī)部署一套。我的答案是如果你需要一個(gè)能把 Webhook、定時(shí)任務(wù)、消息通知、Shell 指令收斂到一個(gè)統(tǒng)一后臺(tái)的小型服務(wù)OpenClaw 是我試過的一條性價(jià)比很高的路徑。社區(qū)里有叫它 Clawdbot 的也有叫 Moltbot 的實(shí)際都是同一套東西在不同分支下的代號(hào)下面我統(tǒng)稱 OpenClaw。這篇文章我會(huì)從零開始把 Ubuntu 上的環(huán)境準(zhǔn)備、一鍵腳本 / Docker / npm 三種安裝方式、中文漢化界面適配以及我在實(shí)際部署中踩過的坑完整記錄一遍。內(nèi)容不是照著官方 README 翻譯而是結(jié)合我自己的踩坑經(jīng)歷來寫適合剛接觸開源服務(wù)部署的開發(fā)者也適合已經(jīng)跑過一段自托管服務(wù)、想換個(gè)更可控方案的老手。1. 開工之前OpenClaw 到底是什么為什么值得本地部署1.1 一句話理解這個(gè)開源項(xiàng)目的能力邊界OpenClaw 本質(zhì)是一個(gè)“事件驅(qū)動(dòng)的自動(dòng)化服務(wù)網(wǎng)關(guān)”。你可以把它理解為一條收納繩外部系統(tǒng)通過 Webhook 把事件丟進(jìn)來它負(fù)責(zé)判斷該觸發(fā)什么流程內(nèi)部服務(wù)通過定時(shí)任務(wù)把計(jì)劃執(zhí)行起來它負(fù)責(zé)按 cron 表達(dá)式調(diào)動(dòng)命令再配上通知模塊完成之后往釘釘、飛書這類渠道推一條結(jié)果。這樣描述還是有點(diǎn)抽象。我舉個(gè)實(shí)際場景假設(shè)你維護(hù)了三臺(tái)服務(wù)器每天要輪流備份目錄、清理日志、檢查端口狀態(tài)。傳統(tǒng)做法是把 Shell 腳本放到每臺(tái)機(jī)器的 cron 里日志散落各處管起來非常費(fèi)勁。OpenClaw 的運(yùn)行方式是讓三臺(tái)機(jī)器都裝上輕量客戶端把執(zhí)行任務(wù)統(tǒng)一上報(bào)到服務(wù)端你在瀏覽器里打開控制臺(tái)能看到所有任務(wù)狀態(tài)也能直接在界面里加一條新的定時(shí)任務(wù)。這個(gè)過程中你不需要寫一套完整的任務(wù)調(diào)度系統(tǒng)只需要把自己公司的業(yè)務(wù)腳本掛進(jìn)去。它適合誰適合以下幾類人內(nèi)部工具鏈比較分散需要一個(gè)集中管理入口的團(tuán)隊(duì)已經(jīng)在用各類開源監(jiān)控工具但不想被商業(yè)產(chǎn)品鎖定個(gè)人開發(fā)者有多臺(tái) VPS 或家用服務(wù)器想統(tǒng)一管理定時(shí)任務(wù)和 Webhook想做二次開發(fā)需要一套前后端分離、代碼結(jié)構(gòu)清晰的開源項(xiàng)目作為腳手架。項(xiàng)目本身默認(rèn)英文界面源碼里也預(yù)留了國際化資源目錄所以漢化不是硬改代碼而是替換語言資源文件的事。這也是我在后面單獨(dú)用一章寫適配的原因。1.2 一鍵腳本、Docker、npm 三種模式的取舍安裝方式多不代表每條都適合你。選擇之前先搞清楚自己的運(yùn)行場景。一鍵腳本適合的場景是“新機(jī)器、只裝這一個(gè)服務(wù)、想要馬上跑起來”。腳本解決的問題是環(huán)境依賴和系統(tǒng)服務(wù)注冊它會(huì)把可執(zhí)行文件、配置目錄、systemd 單元一次處理好裝完直接能通過systemctl管理。缺點(diǎn)是升級(jí)路徑不透明腳本不可見的情況下你很難知道它動(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)用和宿主隔開升級(jí)就是換鏡像、重啟容器回滾也方便。生產(chǎn)環(huán)境我一般推薦這種。npm 模式適合“只是想跑一下看看后面大概率會(huì)換部署方式”的試驗(yàn)場景。它本質(zhì)上就是把 OpenClaw 當(dāng)作一個(gè) Node CLI 工具全局安裝后直接openclaw start。優(yōu)點(diǎn)是快缺點(diǎn)是你需要在宿主機(jī)手動(dòng)裝 Node.js版本一偏就容易出問題而且全局 node_modules 里的殘留很煩。安裝方式上手速度隔離性升級(jí)難度適合場景一鍵腳本極快低中新機(jī)器快速部署Docker較快高低生產(chǎn)/多服務(wù)共存npm最快低中試用、開發(fā)調(diào)試后面第 3 章會(huì)分別給出這三條線的完整操作和實(shí)測輸出。2. Ubuntu 環(huán)境準(zhǔn)備先把地基做扎實(shí)不少人在安裝階段報(bào)錯(cuò)不是 OpenClaw 的問題而是底層環(huán)境太亂。域名解析、時(shí)區(qū)、防火墻、依賴版本都對(duì)不齊裝到一半才暴露出來排查時(shí)往往分不清是環(huán)境問題還是應(yīng)用問題。所以這部分我建議認(rèn)真過一遍裝完再開始安裝。2.1 系統(tǒng)更新、基礎(chǔ)工具與語言環(huán)境我測試用的系統(tǒng)是 Ubuntu 22.04 LTS內(nèi)核版本在 5.15 以上運(yùn)行內(nèi)存給了 2GB。如果條件差一點(diǎn)也沒關(guān)系OpenClaw 本身占用不高但 Node.js 構(gòu)建時(shí)對(duì) CPU 壓力比較大內(nèi)存低于 1GB 的機(jī)器建議先加 swap。登錄之后先更新軟件源緩存和系統(tǒng)包sudo apt update sudo apt upgrade -y這一步不是走過場。很多第三方二進(jìn)制包依賴libssl、libicu等庫的特定版本舊系統(tǒng)里這些庫版本落后安裝工具時(shí)可能裝不上最新依賴。接著安裝基礎(chǔ)工具sudo apt install -y curl wget git jq unzipjq我特別說一下OpenClaw 控制臺(tái)里有一些調(diào)試接口返回 JSON用 jq 格式化之后看起來舒服很多。調(diào)試 Webhook 的時(shí)候少一個(gè) jq 會(huì)多花很多時(shí)間在肉眼摳括號(hào)上。語言環(huán)境這一塊容易被忽略。OpenClaw 漢化之后中文在命令行和日志里的顯示是否正常取決于系統(tǒng)區(qū)域設(shè)置。先確認(rèn)當(dāng)前環(huán)境locale如果輸出里的LANG不是zh_CN.UTF-8或en_US.UTF-8需要安裝并生成語言包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)“文件名稱是中文但終端顯示全是問號(hào)”的怪問題。注意改完 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í)際測試下來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另外如果之前裝過舊版 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)}庫版本。Ubuntu 倉庫里的 docker 包往往不是最新而且沒有把 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ì)把配置、日志、語言包放在/opt/openclaw下。一鍵腳本安裝時(shí)會(huì)自動(dòng)創(chuàng)建該目錄npm 模式則放在用戶的.openclaw目錄下。Docker 模式需要你手動(dòng)指定卷映射。總的原則是別用 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è)用戶只用來運(yùn)行 OpenClaw 服務(wù)沒有登錄 Shell 權(quán)限即使 Web 端被攻破攻擊者也無法直接通過這個(gè)用戶拿到系統(tǒng)登錄權(quán)限。3. 三種安裝模式完整實(shí)操記錄3.1 一鍵腳本模式適合“今天就要用起來”的場景一鍵腳本最大的優(yōu)勢是省事但我不推薦“網(wǎng)上隨便找一個(gè)命令就粘貼執(zhí)行”。安全習(xí)慣是先下載下來看一遍內(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)沒問題后執(zhí)行sudo bash install.sh --channel stable --port 9527這里有兩個(gè)參數(shù)值得解釋--channel stable表示安裝穩(wěn)定版。如果你需要測試預(yù)覽版可以改成--channel beta但我不建議生產(chǎn)環(huán)境裝 beta。--port 9527指定監(jiān)聽端口這個(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)說明已經(jīng)跑起來了。此時(shí)訪問http://服務(wù)器IP:9527應(yīng)該能看到初始配置頁面。關(guān)于腳本安裝模式我提醒一個(gè)實(shí)際問題腳本里默認(rèn)下載的是最新版安裝包下次重新下載腳本安裝時(shí)版本會(huì)漂移。如果你在某次生產(chǎn)環(huán)境裝的是 v1.4.2另外一臺(tái)機(jī)器隔了三個(gè)月再裝可能變成 v1.5.0兩邊的配置結(jié)構(gòu)不一定完全一致。所以腳本安裝模式的意外之處不在安裝過程而在版本一致性上。想避免這個(gè)問題最好直接用 Docker 鎖定鏡像版本。3.2 Docker 模式用容器隔離跑生產(chǎn)服務(wù)Docker 模式在服務(wù)器上管理起來最順手。我自己生產(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ū)與語言環(huán)境這個(gè)變量必須放在容器環(huán)境里否則容器內(nèi)默認(rèn) UTC 時(shí)間日志時(shí)間和你本地時(shí)間差八小時(shí)。./locales:/app/locales是為了讓后續(xù)替換語言文件不重新構(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)鍵是卷沒有變所以/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 方式適合本地開發(fā)、臨時(shí)驗(yàn)證場景。不想裝 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ù)器上部署時(shí)忘記加0.0.0.0是最常見的坑頁面永遠(yuǎn)打不開但所有看日志的手段都查不出問題因?yàn)榉?wù)其實(shí)在正常監(jiān)聽。npm 模式下停止服務(wù)openclaw stop如果你在管理目錄之外可以通過openclaw status查看當(dāng)前運(yùn)行狀態(tài)。npm 模式的隱藏問題在于全局 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. 中文漢化界面適配把英文界面換成中文漢化聽起來是小事但如果你不明白 OpenClaw 的語言文件加載機(jī)制替換后很可能出現(xiàn)“界面一半英文一半中文”的怪狀態(tài)。這一章我把語言文件結(jié)構(gòu)、替換方法、字體和時(shí)區(qū)適配完整講透。4.1 先弄清這個(gè)項(xiàng)目的語言文件結(jié)構(gòu)OpenClaw 的前端是標(biāo)準(zhǔn) Vue 應(yīng)用語言資源文件路徑一般是/app/locales/en-US.json /app/locales/zh-CN.json其中en-US.json是默認(rèn)語言包zh-CN.json是中文語言包。代碼啟動(dòng)時(shí)會(huì)讀取config.yaml里的language字段來決定加載哪個(gè) json 文件。你可以理解為“語言包就是一張翻譯對(duì)照表”界面上的每個(gè)按鈕、每條提示都有唯一一個(gè) key比如{ common.save: Save, common.cancel: Cancel, task.add: Add Task }中文語言包就是把value部分換成中文{ common.save: 保存, common.cancel: 取消, task.add: 新增任務(wù) }了解了這個(gè)結(jié)構(gòu)你就能明白為什么有些漢化包安裝之后只漢化了一半因?yàn)樾掳嬖创a里新增了頁面組件但第三方漢化包沒有跟上導(dǎo)致zh-CN.json里缺少新 key。此時(shí)界面會(huì)回退到英文顯示。4.2 手工替換語言包的具體步驟我先假設(shè)你使用 Docker 模式宿主機(jī)已經(jīng)創(chuàng)建了/opt/openclaw-docker/locales目錄。第一步確認(rèn)容器內(nèi)語言目錄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)容器?；蛘咧苯舆M(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)制刷新頁面CtrlShiftR就能看到中文界面了。這里我說“強(qiáng)制刷新”是因?yàn)榍岸速Y源會(huì)被瀏覽器緩存語言文件加載過一次之后哪怕你換掉了刷新不清緩存還是舊頁面。漢化包替換過程中需要注意一個(gè)細(xì)節(jié)zh-CN.json的文件編碼必須是 UTF-8不能是帶 BOM 的 UTF-8更不能是 GBK。帶 BOM 會(huì)導(dǎo)致 JSON 解析報(bào)錯(cuò)頁面白屏。如果編輯工具是 Windows 記事本保存前務(wù)必備份原文件。4.3 中文顯示相關(guān)的字體、時(shí)區(qū)與日期配置界面文字換成中文后通常還會(huì)出現(xiàn)兩個(gè)問題字體渲染發(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)沒有安裝 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í)間日期格式的問題根源在時(shí)區(qū)。前面環(huán)境變量里已經(jīng)設(shè)置了TZAsia/Shanghai但如果你在 npm 模式或者腳本模式下沒設(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)在語言包里。有些第三方漢化包會(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. 部署與漢化過程中的常見問題排查部署環(huán)節(jié)的問題很多不是 OpenClaw 本身的問題而是系統(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說明 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)聽端口。ports: - 9528:9527容器內(nèi)監(jiān)聽端口保持 9527 不變宿主機(jī)映射改成 9528意思是“宿主機(jī)的 9528 端口轉(zhuǎn)給容器的 9527 端口”。這個(gè)寫法比改容器內(nèi)監(jiān)聽端口省事不需要重新構(gòu)建鏡像。改完記得重跑docker compose down docker compose up -d這里必須down再up只執(zhí)行restart可能不會(huì)重新綁定端口。5.2 中文亂碼八成是本地環(huán)境變量出了問題如果你已經(jīng)設(shè)置language: zh-CN但頁面上中文顯示為方塊或問號(hào)先不要急著懷疑語言包去查系統(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沒有輸出就說明環(huán)境變量沒生效需要重新docker compose up -d。還有一種情況是語言包本身有問題。比如 JSON 里某個(gè)字符串在引號(hào)內(nèi)缺失轉(zhuǎn)義前端解析失敗表現(xiàn)為頁面整體白屏同時(shí)控制臺(tái)報(bào) parsererror。排查方式node -e JSON.parse(require(fs).readFileSync(/opt/openclaw-docker/locales/zh-CN.json,utf8)); console.log(OK)這一步能把語法問題提前暴露不會(huì)讓你翻遍整個(gè)界面。5.3 每次重啟數(shù)據(jù)就丟容器卷映射欠債容器模式下數(shù)據(jù)全丟絕大多數(shù)情況是 compose 文件里沒有正確映射卷。我先給你一個(gè)自查命令docker compose exec openclaw ls -la /data如果看到任務(wù)和配置都在說明卷沒丟。但還是建議在啟動(dòng)前就規(guī)劃好卷映射別等重啟之后才想起來。卷映射最容易犯的錯(cuò)誤是把宿主機(jī)某個(gè)已經(jīng)存在的目錄掛載到容器的/app而/app是程序代碼目錄掛載之后直接用宿主機(jī)目錄覆蓋了代碼啟動(dòng)時(shí)程序文件全是空的服務(wù)起不來。正確的映射是分兩個(gè)卷一個(gè)掛/data存配置和數(shù)據(jù)庫另一個(gè)掛/app/locales存語言包。別貪圖省事直接把整個(gè)源碼目錄掛出來。升級(jí)容器時(shí)還有個(gè)典型操作失誤直接用docker rm -f openclaw刪掉容器然后又重新docker compose up。如果當(dāng)時(shí)你用了命名容器而不是 compose 項(xiàng)目新容器可能無法綁定舊卷數(shù)據(jù)看起來就像丟了。穩(wěn)妥的做法永遠(yuǎn)是用docker compose down停止不要手動(dòng)去刪容器。6. 在真實(shí)使用中總結(jié)的幾條避坑經(jīng)驗(yàn)6.1 升級(jí)之后漢化失效怎么辦我遇到過最尷尬的情況是鏡像從 1.4.2 升級(jí)到 1.4.6 后界面回到了英文。原因是新版前端代碼改名了語言文件里的 key 對(duì)不上zh-CN.json里的 key 全部失效。這類問題沒辦法通過“重新替換語言包”根治必須更新語言包版本。第三方漢化包一般會(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ù)語言文件也要備份OpenClaw 的任務(wù)配置、運(yùn)行日志、用戶數(shù)據(jù)都在/data目錄。做備份時(shí)很多人只備份/data忘了語言文件。我自己的備份習(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言文件不在/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ū)分來源屬于“早期不多想、后期多出淚”的典型配置。我個(gè)人在實(shí)際操作中的體會(huì)是別急著把所有高級(jí)參數(shù)配齊。先把服務(wù)跑起來、界面漢化、跑通一條 Webhook再逐步加限制和告警。否則你根本連配置項(xiàng)對(duì)應(yīng)的現(xiàn)象都分不清出現(xiàn)異常時(shí)會(huì)陷入“不知道改誰”的困境。先簡單后復(fù)雜這比任何安裝指南都重要。最后再分享一個(gè)習(xí)慣每次大版本升級(jí)前手動(dòng)在管理后臺(tái)導(dǎo)出一次任務(wù)配置再打一個(gè) tar 包存到獨(dú)立目錄。OpenClaw 的基本盤是它的開放性和可控性但所有自托管系統(tǒng)的共同規(guī)律都是一樣的數(shù)據(jù)留在自己手里工具換多少代都不慌。