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