1. Ubuntu 部署 OpenClaw 前先把 Node.js 運(yùn)行環(huán)境這件事想清楚OpenClaw 是一個(gè)跑在 Node.js 上的 AI 助手網(wǎng)關(guān)你可以把它理解成一個(gè)「本地中樞」它負(fù)責(zé)連接各種大模型 API、管理會(huì)話、調(diào)度技能然后通過 Web 控制臺(tái)或消息渠道跟你交互。適合誰用想在自有服務(wù)器上跑一個(gè)可控 AI 助手的開發(fā)者、需要把模型能力接進(jìn)內(nèi)部工具的小團(tuán)隊(duì)以及單純想折騰一下自托管 AI 網(wǎng)關(guān)的技術(shù)愛好者。它不是什么輕量腳本而是一個(gè)需要長期駐留后臺(tái)的服務(wù)所以部署方式直接決定了你后面維護(hù)起來是省心還是糟心。很多人第一次在 Ubuntu 上裝 OpenClaw卡住的地方往往不是 OpenClaw 本身而是 Node.js 版本和 systemd 服務(wù)托管這兩件事。Ubuntu 自帶的 apt 源里 Node.js 版本通常偏舊直接apt install nodejs裝出來的可能是 18.x 甚至更早而 OpenClaw 要求 Node.js 22 以上。版本不對后面npm install -g openclaw要么報(bào) engine 不兼容要么裝上了運(yùn)行時(shí)報(bào)語法錯(cuò)誤。另一個(gè)坑是服務(wù)托管如果你只是openclaw gateway start手動(dòng)跑著SSH 一斷開進(jìn)程就沒了服務(wù)器一重啟更是全丟。所以這篇的重點(diǎn)就放在兩件事上——把 Node.js 22 裝干凈用 systemd 把 OpenClaw 托管成開機(jī)自啟的常駐服務(wù)。我試過在一臺(tái) 2 核 4G 的 Ubuntu 22.04 云主機(jī)上從零走一遍整個(gè)過程大概十幾分鐘其中大部分時(shí)間花在下載依賴上。下面按順序來先準(zhǔn)備系統(tǒng)基礎(chǔ)環(huán)境再裝 Node.js然后裝 OpenClaw 并初始化最后寫 systemd unit 文件做服務(wù)托管和驗(yàn)證。每一步都給可復(fù)制的命令和預(yù)期輸出你照著敲就行。在開始之前先確認(rèn)你的 Ubuntu 版本。執(zhí)行l(wèi)sb_release -a預(yù)期看到Ubuntu 22.04.x LTS或24.04.x LTS。20.04 也能用但建議至少 22.04。硬件方面?zhèn)€人測試 2 核 4G 夠跑網(wǎng)關(guān)本身如果你打算在本地加載模型權(quán)重那內(nèi)存和顯存要另算這篇只講網(wǎng)關(guān)部署不涉及本地模型推理。系統(tǒng)基礎(chǔ)工具先補(bǔ)齊避免后面編譯原生模塊時(shí)缺東西sudo apt update sudo apt upgrade -y sudo apt install -y curl git wget build-essential libssl-dev python3 make g libvips-dev libatomic1這里build-essential提供 gcc/g/makelibssl-dev是很多 npm 原生模塊編譯時(shí)要用的libvips-dev跟圖像處理相關(guān)libatomic1提供原子操作支持。裝完這些Node.js 環(huán)境準(zhǔn)備的地基就打好了。順手把時(shí)間同步確認(rèn)一下時(shí)間不對會(huì)導(dǎo)致 HTTPS 證書校驗(yàn)失敗后面調(diào)模型 API 會(huì)莫名其妙報(bào)錯(cuò)timedatectl status sudo timedatectl set-ntp true看到System clock synchronized: yes就放心了。這一步很多人忽略但確實(shí)是排查「API 調(diào)用失敗」時(shí)經(jīng)常被翻出來的原因。2. Node.js 22 安裝與 TaoToken 接入前置準(zhǔn)備Node.js 的安裝方式有三種我按推薦程度排一下。第一種是 NodeSource 官方源適合生產(chǎn)環(huán)境裝完就是系統(tǒng)級(jí)的 node 和 npmsystemd 服務(wù)調(diào)用路徑清晰不會(huì)出現(xiàn)「手動(dòng)能跑、服務(wù)里找不到 node」的問題。第二種是 nvm適合你機(jī)器上還要跑別的 Node 項(xiàng)目、需要多版本切換的場景但要注意 nvm 裝出來的 node 在用戶目錄下systemd 服務(wù)里得寫絕對路徑。第三種是二進(jìn)制包手動(dòng)解壓適合離線或需要精確控制安裝位置的場景維護(hù)成本最高。生產(chǎn)部署我建議直接用 NodeSource路徑干凈。執(zhí)行curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs裝完驗(yàn)證node -v npm -v預(yù)期輸出v22.x.x和對應(yīng)的 npm 版本比如v22.14.0和10.9.x。如果node -v還是舊版本說明系統(tǒng)里之前裝過 node先sudo apt remove nodejs清掉再重裝。接下來是 OpenClaw 的安裝。官方提供一鍵腳本也支持 npm 全局安裝。一鍵腳本會(huì)自動(dòng)檢測環(huán)境、裝依賴適合新手curl -fsSL https://openclaw.ai/install.sh | bash如果你更想自己掌控安裝過程用 npm 全局裝npm install -g openclawlatest裝完跑一下診斷openclaw --version openclaw doctoropenclaw doctor輸出No blocking issues found就說明基礎(chǔ)環(huán)境沒問題。如果這里報(bào) Node 版本不兼容回到上一步確認(rèn) node 版本?，F(xiàn)在說 TaoToken 的前置準(zhǔn)備。OpenClaw 本身是個(gè)網(wǎng)關(guān)它需要接一個(gè)大模型后端才能干活。TaoToken 提供統(tǒng)一的模型接入能力你可以在它的控制臺(tái)里創(chuàng)建 API Key然后把這個(gè) Key 填到 OpenClaw 的模型配置里。具體來說你需要拿到三樣?xùn)|西Base URL、API Key、Model ID。Base URL 用https://taotoken.net/apiAPI Key 去控制臺(tái)的 API Keys 頁面生成Model ID 根據(jù)你選的模型填比如claude-sonnet-4-5這類。這里要提醒一句OpenClaw 的模型配置支持 OpenAI 兼容協(xié)議TaoToken 的接口正好是兼容格式所以填進(jìn)去就能用。你不需要改 OpenClaw 的源碼只要在配置文件里把 provider 的 baseUrl 指向 TaoToken 就行。這一步做完OpenClaw 就有了「大腦」后面 systemd 托管起來它才能正常響應(yīng)請求。如果你還沒生成 Key先去控制臺(tái)建一個(gè)注意 Key 只在創(chuàng)建時(shí)顯示一次復(fù)制好存起來。模型對話頁面可以先測一下 Key 是否可用確認(rèn)能正常返回再往下走避免后面服務(wù)起來了卻因?yàn)?Key 問題一直報(bào) 401。3. 可復(fù)制的 OpenClaw 配置與 systemd unit 文件模板OpenClaw 的配置文件默認(rèn)在~/.openclaw/openclaw.json。初始化向?qū)penclaw onboard會(huì)生成一份基礎(chǔ)配置但模型接入部分我建議手動(dòng)改因?yàn)橄驅(qū)Ю锏倪x項(xiàng)不一定覆蓋 TaoToken。下面是一份可以直接參考的配置片段路徑和字段名跟實(shí)際文件保持一致{ gateway: { port: 18789, mode: local, bind: loopback }, models: { providers: { taotoken: { type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密鑰, models: [ { id: claude-sonnet-4-5, name: Claude Sonnet 4.5 } ] } }, default: taotoken/claude-sonnet-4-5 } }三個(gè)關(guān)鍵字段對齊一下Base URL 是https://taotoken.net/apiAPI Key 是你控制臺(tái)生成的那串Model ID 填你實(shí)際要用的模型標(biāo)識(shí)。default字段的格式是provider名/模型id這里就是taotoken/claude-sonnet-4-5。改完保存先別急著起服務(wù)用openclaw doctor再跑一遍確認(rèn)配置能被解析。接下來是 systemd unit 文件。OpenClaw 自帶openclaw service install命令但如果你想完全掌控服務(wù)定義手動(dòng)寫 unit 文件更透明。在~/.config/systemd/user/目錄下創(chuàng)建openclaw-gateway.service[Unit] DescriptionOpenClaw Gateway Service Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple ExecStart/usr/bin/openclaw gateway --port 18789 Restartalways RestartSec5 WorkingDirectory%h/.openclaw EnvironmentNODE_ENVproduction StandardOutputjournal StandardErrorjournal [Install] WantedBydefault.target幾個(gè)地方要注意。ExecStart里的路徑必須是 node 和 openclaw 的絕對路徑用which openclaw確認(rèn)一下如果是 nvm 裝的路徑會(huì)類似/home/你的用戶名/.nvm/versions/node/v22.x.x/bin/openclaw。WorkingDirectory指向配置目錄這樣 OpenClaw 能找到openclaw.json。Restartalways配合RestartSec5實(shí)現(xiàn)崩潰后 5 秒自動(dòng)拉起。WantedBydefault.target是用戶級(jí)服務(wù)開機(jī)自啟的關(guān)鍵。寫完后重新加載并啟用systemctl --user daemon-reload systemctl --user enable openclaw-gateway systemctl --user start openclaw-gateway這里有個(gè)容易踩的坑用戶級(jí) systemd 服務(wù)默認(rèn)在你登出后就停了。要讓它在沒登錄的情況下也保持運(yùn)行需要開啟 lingersudo loginctl enable-linger $USER執(zhí)行完可以用loginctl show-user $USER | grep Linger確認(rèn)輸出Lingeryes。這一步不做服務(wù)器重啟后服務(wù)不會(huì)自動(dòng)起來很多人以為 enable 了就萬事大吉結(jié)果重啟后訪問不了就是漏了 linger。4. 驗(yàn)證請求從服務(wù)狀態(tài)到模型對話的完整鏈路服務(wù)起來之后先看狀態(tài)systemctl --user status openclaw-gateway預(yù)期看到Active: active (running)下面有進(jìn)程 ID 和最近的日志行。如果顯示failed直接看日志journalctl --user -u openclaw-gateway -n 50 --no-pager日志里最常見的兩類錯(cuò)誤一是Cannot find module說明 openclaw 路徑不對或沒裝好二是EADDRINUSE說明 18789 端口被占用lsof -i :18789找到占用進(jìn)程處理掉或者改配置里的端口。服務(wù)狀態(tài)正常后用 OpenClaw 自帶的檢查命令確認(rèn)網(wǎng)關(guān)運(yùn)行時(shí)openclaw gateway status預(yù)期輸出里有Runtime: running和RPC probe: ok。如果 RPC probe 失敗通常是配置里的 mode 或 bind 設(shè)置有問題回到配置文件確認(rèn)gateway.mode是local、bind是loopback。接下來驗(yàn)證模型鏈路。最直接的方式是用 OpenClaw 的命令行發(fā)一條測試消息openclaw message send --to default --text 你好請回復(fù)你的模型名稱如果配置正確你會(huì)看到模型返回的內(nèi)容。如果報(bào) 401說明 API Key 不對或沒生效如果報(bào)連接超時(shí)檢查服務(wù)器能不能訪問https://taotoken.net/api用curl -I https://taotoken.net/api測一下連通性。Web 控制臺(tái)也可以驗(yàn)證。默認(rèn)監(jiān)聽http://127.0.0.1:18789如果你在本地機(jī)器上直接瀏覽器打開如果是遠(yuǎn)程服務(wù)器用 SSH 端口轉(zhuǎn)發(fā)ssh -L 18789:127.0.0.1:18789 你的用戶名服務(wù)器IP然后在本地瀏覽器訪問http://127.0.0.1:18789輸入配置里的 token 就能進(jìn)控制臺(tái)。在對話框里發(fā)一條消息收到回復(fù)就說明整條鏈路通了systemd 拉起服務(wù) → 網(wǎng)關(guān)監(jiān)聽端口 → 模型配置指向 TaoToken → API 調(diào)用成功返回。再補(bǔ)一個(gè)開機(jī)自啟的驗(yàn)證。重啟服務(wù)器sudo reboot等機(jī)器起來后重新 SSH 上去直接執(zhí)行systemctl --user status openclaw-gateway如果顯示active (running)且啟動(dòng)時(shí)間是你重啟后的時(shí)間說明開機(jī)自啟生效了。這一步是整個(gè)部署的最終驗(yàn)收過了就說明你的 OpenClaw 已經(jīng)是一個(gè)穩(wěn)定的常駐服務(wù)。5. 本篇常見報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuth部署過程中有幾類報(bào)錯(cuò)出現(xiàn)頻率特別高我按實(shí)際遇到的順序整理一下每個(gè)都給定位方法和處理動(dòng)作。401 Unauthorized。這個(gè)基本都出在模型配置上?，F(xiàn)象是服務(wù)能起來但一發(fā)消息就報(bào) 401。先確認(rèn)openclaw.json里apiKey字段填的是完整的 Key沒有多余空格或換行。然后確認(rèn)baseUrl是https://taotoken.net/api注意結(jié)尾不要多加/v1之類的路徑OpenClaw 會(huì)自己拼接。如果 Key 確認(rèn)沒問題還是 401去控制臺(tái)看這個(gè) Key 是否被禁用或額度耗盡。改完配置記得systemctl --user restart openclaw-gateway配置不會(huì)熱加載。local proxy failed。這個(gè)報(bào)錯(cuò)通常出現(xiàn)在你環(huán)境里配了 HTTP 代理但代理不可達(dá)的時(shí)候。OpenClaw 啟動(dòng)時(shí)會(huì)讀取http_proxy/https_proxy環(huán)境變量如果這些變量指向一個(gè)已經(jīng)關(guān)掉的代理請求就會(huì)失敗。檢查env | grep -i proxy如果有輸出且代理確實(shí)不用了在 systemd unit 文件里顯式清掉加一行EnvironmentNO_PROXY*或者在[Service]段里UnsetEnvironmenthttp_proxy https_proxy。改完daemon-reload再重啟服務(wù)。reading choices 相關(guān)報(bào)錯(cuò)。這類錯(cuò)誤一般長這樣Cannot read properties of undefined (reading choices)。它說明 OpenClaw 拿到了一個(gè)不符合 OpenAI 格式的響應(yīng)解析choices字段時(shí)炸了。原因通常是 baseUrl 指向的接口返回了錯(cuò)誤頁或非標(biāo)準(zhǔn) JSON。用 curl 直接打一下接口確認(rèn)返回結(jié)構(gòu)curl -s https://taotoken.net/api/chat/completions \ -H Authorization: Bearer 你的Key \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-5,messages:[{role:user,content:hi}]}正常應(yīng)該返回帶choices數(shù)組的 JSON。如果返回的是 HTML 或錯(cuò)誤信息說明 baseUrl 或路徑不對回到配置里核對。OAuth 相關(guān)報(bào)錯(cuò)。如果你在初始化時(shí)選了需要 OAuth 的模型提供商但沒完成授權(quán)流程會(huì)看到 token 獲取失敗之類的提示。處理方式是重新跑openclaw onboard在模型提供商那一步選 TaoToken 這種基于 API Key 的方式避開 OAuth 流程。已經(jīng)配好的可以手動(dòng)改openclaw.json把 provider 的type改成openai-compatible填上 baseUrl 和 apiKey。再補(bǔ)一個(gè) systemd 特有的坑服務(wù)啟動(dòng)時(shí)報(bào)status203/EXEC。這是ExecStart路徑不對systemd 找不到可執(zhí)行文件。用which openclaw拿到絕對路徑填進(jìn)去nvm 用戶尤其容易遇到因?yàn)?nvm 的路徑帶版本號(hào)升級(jí) node 后路徑會(huì)變。解決辦法是在 unit 文件里用固定的絕對路徑或者干脆用 NodeSource 裝的系統(tǒng)級(jí) node路徑穩(wěn)定在/usr/bin/openclaw。排查完這些你的服務(wù)基本就能穩(wěn)定跑了。如果還有問題journalctl --user -u openclaw-gateway -f實(shí)時(shí)看日志錯(cuò)誤信息通常寫得很直白。6. 把 OpenClaw 長期跑起來接入方式與后續(xù)維護(hù)服務(wù)穩(wěn)定運(yùn)行之后接下來要考慮的是怎么把它用起來以及長期維護(hù)的幾個(gè)動(dòng)作。OpenClaw 的接入方式主要有兩種Web 控制臺(tái)和消息渠道。Web 控制臺(tái)適合調(diào)試和日常對話消息渠道適合把 AI 助手接進(jìn)你的工作流。如果你打算長期用它做編碼輔助或 Agent 任務(wù)建議了解一下 Coding Plan 這類按周期計(jì)費(fèi)的方式比按量調(diào)用更可控適合高頻使用場景。日常維護(hù)方面幾個(gè)命令要記牢。更新 OpenClawnpm update -g openclaw systemctl --user restart openclaw-gateway看日志journalctl --user -u openclaw-gateway -f改配置后重啟systemctl --user restart openclaw-gateway日志輪轉(zhuǎn)也建議配上避免 journal 占滿磁盤。在/etc/systemd/journald.conf里設(shè)置SystemMaxUse500M然后sudo systemctl restart systemd-journald。如果你需要從局域網(wǎng)其他設(shè)備訪問控制臺(tái)改配置里的gateway.bind為lan并在controlUi.allowedOrigins里加上你的局域網(wǎng) IP。但記住不要把 18789 端口直接暴露到公網(wǎng)需要遠(yuǎn)程訪問就用 SSH 隧道或反向代理加認(rèn)證。最后說一個(gè)實(shí)際經(jīng)驗(yàn)systemd 用戶服務(wù)的環(huán)境變量跟你的登錄 shell 是隔離的。你在.bashrc里export的變量服務(wù)里讀不到。如果 OpenClaw 依賴某個(gè)環(huán)境變量一定要寫進(jìn) unit 文件的Environment行里。這個(gè)坑我在第一次配的時(shí)候踩過手動(dòng)跑正常、服務(wù)跑就報(bào)錯(cuò)查了半天才發(fā)現(xiàn)是環(huán)境變量沒傳進(jìn)去。整套流程走下來你得到的是一臺(tái)重啟后自動(dòng)拉起、崩潰后自動(dòng)重啟、配置集中在~/.openclaw/openclaw.json的 OpenClaw 網(wǎng)關(guān)。后面要換模型改配置重啟即可要加消息渠道在控制臺(tái)里配要升級(jí)npm update加重啟。部署這件事一次做對后面就省心了。