1. 先搞清楚 OpenClaw 到底在跑什么OpenClaw 是一個可以部署在本地機器或云服務(wù)器上的開源 AI Agent 框架核心由三塊組成Gateway 負責通信調(diào)度Dashboard 提供可視化控制臺Skills 則是 Agent 能調(diào)用的能力插件集合。它和普通聊天工具最大的區(qū)別在于運行位置和權(quán)限邊界——普通工具跑在云端、權(quán)限受限、不能持久執(zhí)行OpenClaw 跑在你自己的環(huán)境里能讀寫文件、調(diào)用系統(tǒng)命令、請求外部 API還能長時間后臺運行。這意味著它適合想真正把 Agent 用起來的人需要自動化處理本地任務(wù)、想接入自己的業(yè)務(wù)系統(tǒng)、或者要做一個能持續(xù)干活的執(zhí)行體。但也正因為權(quán)限高部署方式必須認真對待不建議直接裝在日常辦公電腦上獨立服務(wù)器或容器隔離環(huán)境才是正確姿勢。這篇就按從零到跑通的順序把 Node.js 和 Docker 兩條路都走一遍配置骨架直接給報錯排查也一并列出來。2. 部署前先把 TaoToken 通道準備好OpenClaw 本身是框架它要調(diào)用大模型能力才能讓 Agent 真正干活。這里我用 TaoToken 作為統(tǒng)一的模型接入通道好處是一個 Key 可以覆蓋多種模型不用在配置文件里來回換不同廠商的地址和密鑰。你需要先去官網(wǎng)注冊并拿到 API Key然后確認兩件事一是 Key 有余額或額度二是你要用的模型名稱在文檔里有對應(yīng)說明。具體操作路徑打開官網(wǎng) https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注冊登錄后進入控制臺在 API Keys 頁面創(chuàng)建一個新 Key。創(chuàng)建時建議給 Key 起個能識別的名字比如 openclaw-local方便后面排查是哪個環(huán)境在用。拿到 Key 之后先別急著寫進配置用一條 curl 驗證通道是否通curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-3-5-sonnet, messages: [{role: user, content: ping}], max_tokens: 16 }如果返回里有正常的 choices 內(nèi)容說明 Key 和網(wǎng)絡(luò)都沒問題。這一步很關(guān)鍵因為后面 OpenClaw 報錯時你要能區(qū)分是框架問題還是通道問題。模型對話的調(diào)試入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以在網(wǎng)頁上直接試模型是否可用。長期跑編碼類 Agent 的話Coding Plan 頁面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 有更細的額度說明按自己用量選就行。3. Node.js 環(huán)境準備與 OpenClaw 安裝3.1 系統(tǒng)基礎(chǔ)依賴以 Ubuntu 22.04 為例先更新系統(tǒng)并裝基礎(chǔ)工具sudo apt update sudo apt install -y git curl unzip build-essentialbuild-essential 別省后面有些 skill 依賴原生模塊編譯缺了會報 node-gyp 相關(guān)錯誤。3.2 安裝 Node.js 18OpenClaw 要求 Node 18 以上推薦用 nvm 管理版本避免和系統(tǒng)自帶 Node 沖突curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 18 nvm use 18 nvm alias default 18驗證node -v # 應(yīng)輸出 v18.x.x npm -v如果 node -v 還是舊版本檢查 ~/.bashrc 里 nvm 的加載語句是否生效重新 source 一次。3.3 安裝 OpenClaw CLI最快的方式是全局安裝npm install -g openclaw openclaw --version看到版本號就說明 CLI 裝好了。如果你要改源碼或?qū)懽远x skill走源碼方式git clone https://github.com/openclaw/openclaw.git cd openclaw npm install -g pnpm pnpm install pnpm build源碼方式后續(xù)命令前面要加 pnpm比如 pnpm openclaw onboard。4. 配置文件骨架與啟動驗證4.1 config.toml 骨架OpenClaw 的配置分兩層全局配置和 Agent 配置。全局配置一般在 ~/.openclaw/config.toml骨架如下[gateway] host 127.0.0.1 port 18789 log_level info [model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的Key default_model claude-3-5-sonnet timeout_seconds 60 [agent] name local-agent workspace /home/youruser/openclaw-workspace max_concurrent_tasks 2 [security] allow_shell false allow_file_write true allowed_paths [/home/youruser/openclaw-workspace]幾個點要注意base_url 填 https://taotoken.net/api 即可不要帶多余路徑allow_shell 默認關(guān)掉等確認 Agent 行為可控后再按需開allowed_paths 一定要限制在工作目錄別寫根目錄。4.2 settings.json 骨架部分 skill 和 Dashboard 會讀 settings.json放在工作目錄下{ skills: { enabled: [http-request, file-read], disabled: [shell-exec] }, logging: { level: info, file: ./logs/agent.log }, dashboard: { enabled: true, port: 18790 } }4.3 初始化與啟動配置寫好后執(zhí)行 onboardingopenclaw onboard --install-daemon這一步會初始化 Gateway、生成本地配置、注冊后臺服務(wù)。完成后檢查狀態(tài)openclaw gateway status正常輸出包含 running、healthy、listening on port 18789。如果沒起來直接看日志openclaw gateway logs啟動 Dashboardopenclaw dashboard瀏覽器訪問 http://127.0.0.1:18790能看到 Agent 狀態(tài)、會話記錄、Skills 管理和 Gateway 連接情況就說明主鏈路通了。5. Docker 方式部署與連通性測試5.1 Docker 環(huán)境準備服務(wù)器上裝 Dockercurl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER newgrp docker docker --version5.2 用 Docker 跑 OpenClaw先建工作目錄和配置mkdir -p ~/openclaw-docker/{config,workspace,logs}把上面第 4 節(jié)的 config.toml 放到 ~/openclaw-docker/config/ 下注意 workspace 路徑改成容器內(nèi)路徑 /workspace。然后啟動容器docker run -d \ --name openclaw \ -p 18789:18789 \ -p 18790:18790 \ -v ~/openclaw-docker/config:/root/.openclaw \ -v ~/openclaw-docker/workspace:/workspace \ -v ~/openclaw-docker/logs:/workspace/logs \ --restart unless-stopped \ openclaw/openclaw:latest查看日志確認啟動docker logs -f openclaw看到 gateway listening 和 dashboard ready 就對了。5.3 連通性測試不管哪種方式跑通后做一次端到端驗證。在 Dashboard 里新建一個會話發(fā)一條指令讓 Agent 讀一個文件并總結(jié)echo OpenClaw test content ~/openclaw-docker/workspace/test.txt然后在 Dashboard 輸入讀取 workspace 下的 test.txt 并告訴我內(nèi)容。如果 Agent 返回了文件內(nèi)容說明模型通道、Gateway、Skill 三層都通了。這一步驗證的是 Agent 可控性——它只在你允許的路徑下操作沒有越權(quán)。6. 常見報錯排查Gateway 起不來先看 openclaw gateway logs。最常見的是 Node 版本不對低于 18和端口被占用。端口檢查用 ss -tlnp | grep 18789被占用就改 config.toml 里的 port。Dashboard 打不開如果是服務(wù)器部署檢查防火墻和安全組是否放行了 18790。本地的話確認 dashboard 進程在跑ps aux | grep dashboard 看一眼。模型調(diào)用返回 401Key 寫錯或沒帶 Bearer 前綴。檢查 config.toml 里 api_key 格式重新用第 2 節(jié)的 curl 驗證一次通道。Skill 不生效先確認 settings.json 里 enabled 列表包含該 skill然后看日志有沒有 schema 校驗失敗。改完配置要重啟 Gatewayopenclaw gateway restart。Agent 行為不可控檢查 security 段allow_shell 是否誤開allowed_paths 是否范圍過大。建議先用只讀類 skill 跑通再逐步放開。Docker 容器反復(fù)重啟docker logs 看具體錯誤多半是掛載路徑權(quán)限問題給 workspace 目錄加寫權(quán)限chmod -R 755 ~/openclaw-docker/workspace。7. 接入文檔與后續(xù)動作跑通之后建議把 Key 管理和接入細節(jié)再過一遍。API Keys 頁面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以隨時輪換 Key接入文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里有各模型的參數(shù)說明和兼容格式。如果你要接 Claude Code 這類編碼 Agent參考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 的配置方式base_url 和 Key 的填法跟本文一致?？刂婆_ https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里能看用量和調(diào)用記錄排查問題時對照日志時間點很有用。整套跑下來驗收標準就五條CLI 正常、Gateway running、Dashboard 可訪問、至少一個 skill 生效、Agent 能完成一次完整任務(wù)。滿足這五條你的 OpenClaw 就算真正搭起來了。