1. 為什么要在本地跑 OpenClaw 對接阿里云百煉OpenClaw 是一個開源的 AI 自動化助理框架你可以把它理解成一個「能自己動手干活」的機器人底座它本身不帶大模型而是通過配置把外部模型 API 接進來再掛到釘釘、Web 面板這類入口上讓 AI 在群聊里自動回消息、跑任務(wù)、生成內(nèi)容。2026 年 4 月這個時間點OpenClaw 的本地集成鏈路已經(jīng)比較成熟尤其是和阿里云百煉的對接官方兼容模式接口穩(wěn)定配置項也不復(fù)雜。這篇教程面向的是第一次接觸 OpenClaw 的開發(fā)者目標很明確在本地機器上用大約 8 分鐘把 OpenClaw 跑起來把阿里云百煉的 API Key 寫進配置最后在釘釘側(cè)發(fā)一條消息驗證整條鏈路通不通。全程不需要你懂 Node.js 底層也不需要買服務(wù)器一臺能聯(lián)網(wǎng)的開發(fā)機就夠。我會把每一步的命令、配置文件片段、驗證動作都寫清楚你復(fù)制粘貼就能跟做。先說清楚幾個概念避免后面看配置時懵。OpenClaw 的模型調(diào)用走的是「provider」抽象層每個 provider 有自己的 baseUrl、apiKey 和模型列表。阿里云百煉提供的是 OpenAI 兼容接口所以 baseUrl 填https://dashscope.aliyuncs.com/compatible-mode/v1模型 ID 用qwen3-max-2026這類百煉側(cè)的標識。釘釘側(cè)則是通過開放平臺的機器人能力接入OpenClaw 內(nèi)置了釘釘通道你只要把 Client ID 和 Client Secret 填進去再開一個觸發(fā)前綴機器人就能在群里響應(yīng)指令。很多人卡住不是因為技術(shù)難而是幾個細節(jié)沒對齊API Key 復(fù)制時帶了空格、端口沒放行、釘釘權(quán)限沒申請全、配置改完沒重啟服務(wù)。這篇教程會把這些坑提前標出來你按順序走基本不會翻車。下面從環(huán)境準備開始一步步來。2. 環(huán)境準備與 TaoToken 前置配置在正式寫 OpenClaw 配置之前先把兩件事準備好本地運行環(huán)境和模型 API 的接入憑證。環(huán)境這塊OpenClaw 依賴 Node.js 22 及以上版本官方推薦用 nvm 管理版本避免和系統(tǒng)自帶的舊 Node 沖突。如果你機器上已經(jīng)有 Node 22可以跳過安裝直接驗證版本。# 檢查 Node 版本必須 22 node -v # 如果沒有或版本過低用 nvm 安裝 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22Node 就緒后全局安裝 OpenClaw CLI。這里建議同時把 npm 鏡像切到國內(nèi)源依賴下載會快很多尤其是后面裝技能包的時候。npm config set registry https://registry.npmmirror.com/ npm install -g openclaw-cli openclaw --version接下來是模型 API 憑證。阿里云百煉的 API Key 在百煉控制臺的「密鑰管理」里創(chuàng)建格式是sk-開頭的一串字符。創(chuàng)建時注意兩點一是復(fù)制后檢查首尾有沒有多余空格或換行二是這個 Key 只顯示一次創(chuàng)建完立刻保存到安全的地方。如果你還沒開通百煉先去控制臺完成實名認證否則創(chuàng)建 Key 的入口是灰的。除了百煉直連如果你希望統(tǒng)一管理多個模型的接入憑證可以用 TaoToken 做一層聚合。它的 API 地址是https://taotoken.net/api在控制臺里可以創(chuàng)建和管理 Key然后 OpenClaw 側(cè)只需要填 TaoToken 的 baseUrl 和 Key就能同時調(diào)用多個后端模型。對于需要頻繁切換模型做對比的場景這種方式省事很多。具體操作是登錄 TaoToken 控制臺在 API Keys 頁面創(chuàng)建一個新 Key復(fù)制保存然后在 OpenClaw 的 provider 配置里把 baseUrl 指向 TaoToken 的 API 地址apiKey 填剛創(chuàng)建的 Key模型 ID 按 TaoToken 文檔里支持的標識填。這里要提醒一句不管用百煉直連還是 TaoToken 聚合Key 都不要硬編碼在會提交到 Git 的文件里。OpenClaw 的配置文件默認在~/.openclaw/openclaw.json這個路徑不在項目倉庫內(nèi)相對安全但如果你要分享配置記得把 Key 替換成占位符。環(huán)境準備好之后先別急著寫完整配置用一條最小命令驗證 OpenClaw CLI 能正常跑openclaw doctor這個命令會檢查 Node 版本、配置文件是否存在、端口占用等基礎(chǔ)項。如果輸出里有紅色報錯先按提示修掉再往下走。很多人跳過這步后面配置寫完發(fā)現(xiàn)服務(wù)起不來回頭排查反而更費時間。3. 可復(fù)制的 OpenClaw 配置文件片段OpenClaw 的核心配置都集中在~/.openclaw/openclaw.json。這個文件是 JSON 格式改的時候注意逗號和大括號配對少一個符號服務(wù)就起不來。下面給出一份完整的、可以直接復(fù)制修改的配置片段包含百煉 provider、默認模型、釘釘通道三部分。先創(chuàng)建配置目錄和文件mkdir -p ~/.openclaw touch ~/.openclaw/openclaw.json然后用編輯器打開寫入以下內(nèi)容。注意把sk-你的百煉APIKey和釘釘?shù)膬蓚€憑證替換成你自己的{ models: { default: bailian/qwen3-max-2026, providers: { bailian: { baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1, apiKey: sk-你的百煉APIKey, models: [ { id: qwen3-max-2026, maxTokens: 65536 }, { id: qwen3.5-plus, maxTokens: 8192 } ] } } }, channels: { dingtalk: { enabled: true, clientId: 你的釘釘ClientID, clientSecret: 你的釘釘ClientSecret, prefix: ! } }, gateway: { port: 18789, host: 0.0.0.0 } }這份配置里幾個關(guān)鍵點解釋一下。models.default指定默認走哪個模型格式是provider名/模型ID這里指向百煉的 qwen3-max-2026。providers.bailian.baseUrl是百煉的 OpenAI 兼容端點不要寫成 dashscope 的原生端點否則 OpenClaw 的調(diào)用格式會對不上。maxTokens按模型實際支持的上限填qwen3-max 支持到 65536qwen3.5-plus 是 8192填大了請求會被拒。釘釘部分prefix是群聊里觸發(fā)機器人的前綴默認!你可以改成/或$但要注意別和釘釘本身的指令沖突。gateway.port是 Web 面板和 API 的監(jiān)聽端口默認 18789如果你本地這個端口被占用改成 18790 之類也行但后面訪問面板的地址要跟著改。如果你用 TaoToken 聚合provider 段改成這樣providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: 你的TaoToken Key, models: [ { id: qwen3-max-2026, maxTokens: 65536 } ] } }同時把models.default改成taotoken/qwen3-max-2026。這樣 OpenClaw 請求先到 TaoToken再由它轉(zhuǎn)發(fā)到對應(yīng)模型Key 的管理和輪換都在 TaoToken 控制臺完成本地配置不用頻繁改。配置寫完后先別啟動服務(wù)用一條命令校驗 JSON 語法python3 -m json.tool ~/.openclaw/openclaw.json /dev/null echo JSON OK輸出JSON OK說明格式?jīng)]問題。如果報錯按提示的行號去檢查通常是漏了逗號或者多了一個括號。這一步花十秒能省掉后面看日志排查的幾分鐘。4. 啟動服務(wù)并驗證請求鏈路配置校驗通過后就可以啟動 OpenClaw 網(wǎng)關(guān)服務(wù)了。啟動命令帶--daemon參數(shù)讓它后臺運行這樣你關(guān)掉終端服務(wù)也不會停。openclaw gateway start --daemon啟動后立刻查狀態(tài)openclaw gateway status輸出里看到active (running)就說明服務(wù)起來了。如果顯示failed或inactive先看日志openclaw logs -f日志里最常見的報錯是EADDRINUSE意思是 18789 端口被別的進程占了。用lsof -i:18789找到占用進程要么殺掉要么改配置里的端口號再重啟。服務(wù)正常后先驗證模型調(diào)用通不通這一步不依賴釘釘純粹測 OpenClaw 到百煉的鏈路openclaw model test這個命令會發(fā)一條測試請求給默認模型返回內(nèi)容里如果有正常的文本回復(fù)說明 API Key、baseUrl、模型 ID 三者都對上了。如果返回 401檢查 Key 有沒有復(fù)制錯如果返回 404檢查模型 ID 是不是百煉側(cè)真實存在的如果超時檢查本地網(wǎng)絡(luò)能不能訪問 dashscope.aliyuncs.com。模型通了之后生成一個管理員 Token用于登錄 Web 面板openclaw token generate把輸出的 Token 復(fù)制下來瀏覽器訪問http://127.0.0.1:18789?token你的Token能看到對話界面就說明網(wǎng)關(guān)和面板都正常。在面板里發(fā)一句「幫我總結(jié) OpenClaw 的配置步驟」如果模型正常回復(fù)整條本地鏈路就算跑通了。最后驗證釘釘側(cè)。在釘釘群里添加你創(chuàng)建的機器人發(fā)送!你好如果機器人回復(fù)了內(nèi)容說明釘釘通道也通了。這里有個細節(jié)釘釘機器人的消息回調(diào)需要你的本地服務(wù)能被釘釘服務(wù)器訪問到。如果你是在本地機器跑沒有公網(wǎng) IP釘釘?shù)幕卣{(diào)會失敗。解決辦法有兩個一是用內(nèi)網(wǎng)穿透工具把 18789 端口暴露出去注意合規(guī)使用二是先把 OpenClaw 部署到有公網(wǎng) IP 的服務(wù)器上再配釘釘。本地純驗證模型鏈路的話釘釘這步可以暫時跳過等有公網(wǎng)環(huán)境再補。驗證順序建議按「模型測試 → Web 面板 → 釘釘」來每步確認通過再走下一步出問題容易定位。5. 常見報錯排查對照這一節(jié)把新手最常撞到的幾個報錯列出來對照著改基本能解決。401 Unauthorized模型測試返回 401九成是 API Key 問題。先檢查 Key 有沒有復(fù)制完整首尾有沒有空格。百煉的 Key 是sk-開頭如果你復(fù)制時漏了后面幾位或者把創(chuàng)建時的顯示內(nèi)容截斷了都會 401。另一個可能是 Key 被禁用或欠費去百煉控制臺確認狀態(tài)。local proxy failed / connection refused這個報錯說明 OpenClaw 連不上 baseUrl。先確認baseUrl寫的是https://dashscope.aliyuncs.com/compatible-mode/v1不要多寫或少寫路徑。然后用curl直接測一下curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d {model:qwen3-max-2026,messages:[{role:user,content:hi}]}如果 curl 也失敗說明是網(wǎng)絡(luò)或 Key 的問題和 OpenClaw 無關(guān)如果 curl 成功但 OpenClaw 失敗檢查配置文件里的 baseUrl 有沒有拼寫錯誤。reading choices 報錯這個通常出現(xiàn)在模型返回格式和 OpenClaw 預(yù)期不一致時。百煉的兼容模式返回結(jié)構(gòu)是標準的 OpenAI 格式choices數(shù)組里帶message.content。如果你用的是非兼容端點返回結(jié)構(gòu)不同OpenClaw 解析就會報這個錯。確認 baseUrl 帶/compatible-mode/v1后綴。OAuth 相關(guān)報錯釘釘通道如果報 OAuth 或 token 獲取失敗檢查 Client ID 和 Client Secret 是否配對以及釘釘應(yīng)用是否發(fā)布了版本。釘釘?shù)膽{證在「憑證與基礎(chǔ)信息」頁面Client Secret 只顯示一次如果忘了只能重置。另外確認應(yīng)用權(quán)限里申請了qyapi_robot_sendmsg沒有這個權(quán)限機器人發(fā)不出消息。服務(wù)啟動后立即退出看日志如果沒有任何報錯就退出檢查配置文件路徑對不對。OpenClaw 默認讀~/.openclaw/openclaw.json如果你把文件放在了別處啟動時要加--config參數(shù)指定路徑。另外確認 Node 版本是 22 以上低版本會有兼容問題。釘釘機器人不回復(fù)先確認服務(wù)在跑、釘釘通道 enabled 為 true、prefix 和發(fā)送的前綴一致。然后在日志里看有沒有收到釘釘?shù)幕卣{(diào)請求。如果日志里沒有回調(diào)記錄說明釘釘服務(wù)器沒訪問到你的服務(wù)檢查公網(wǎng)可達性和端口放行。排查的核心思路是分層先確認模型鏈路curl 直測再確認 OpenClaw 服務(wù)status logs最后確認釘釘回調(diào)日志有無請求。每層單獨驗證不要混在一起猜。6. 后續(xù)接入與長期使用建議本地跑通之后如果你打算長期用 OpenClaw 做自動化有幾個方向可以繼續(xù)。一是把服務(wù)從本地遷到有公網(wǎng) IP 的環(huán)境這樣釘釘回調(diào)穩(wěn)定也能 7×24 運行。遷移時只需要把~/.openclaw/openclaw.json復(fù)制過去改一下 gateway 的 host 和端口重新啟動即可。二是把常用技能裝上OpenClaw 的技能生態(tài)通過 clawhub 管理裝幾個基礎(chǔ)技能能明顯擴展能力邊界npm install -g clawhub-cli clawhub install search clawhub install document-parser clawhub install summarize openclaw gateway restart裝完重啟服務(wù)技能就生效了。search讓模型能聯(lián)網(wǎng)查資料document-parser能讀 PDF/Wordsummarize做長文提煉。這幾個都是低風(fēng)險、高頻用的建議先裝。模型側(cè)如果你用量大可以關(guān)注百煉的 Coding Plan 這類按次計費的套餐比純按 token 計費在固定任務(wù)量下更劃算。配置方式和普通 API Key 一樣只是 baseUrl 和模型 ID 換成 Coding Plan 對應(yīng)的值。如果你需要同時接多個模型做對比用 TaoToken 聚合會更方便Key 和模型列表都在一個控制臺管理OpenClaw 側(cè)只配一個 provider 就行。最后說一個實際使用中的小技巧OpenClaw 的日志默認會滾動長時間運行后日志文件可能占不少空間。可以在配置里加日志級別和輪轉(zhuǎn)策略或者定期用openclaw logs --clear清理。另外配置文件改完一定要openclaw gateway restart很多人改完不重啟以為沒生效其實是服務(wù)還在用舊配置。整條鏈路跑通后你手里就有了一個能接釘釘、能調(diào)百煉模型的本地 AI 助理底座。后面要加新通道、換模型、裝技能都是在這份配置上做增量修改不用推倒重來。先把最小可用鏈路跑穩(wěn)再逐步擴展比一上來就堆一堆功能要靠譜得多。