1. 為什么你的 OpenClaw 跑不起來(lái)四個(gè)組件各管一段路OpenClaw 是一個(gè)可長(zhǎng)期運(yùn)行的本地 AI Agent 框架核心由 Gateway、Agent、Skills、Memory 四個(gè)組件構(gòu)成。它適合正在搭建本地 Agent 環(huán)境、希望把消息接入、模型推理、工具調(diào)用和長(zhǎng)期記憶串成一條鏈路的開(kāi)發(fā)者。很多人第一次部署 OpenClaw 時(shí)會(huì)把注意力全放在模型 Key 上結(jié)果 Gateway 起來(lái)了、Agent 卻收不到消息或者 Agent 能回復(fù)但記不住上一輪說(shuō)了什么。問(wèn)題往往不在模型而在于沒(méi)搞清楚這四個(gè)組件各自負(fù)責(zé)哪一段路。我試過(guò)把 OpenClaw 拆成一條流水線(xiàn)來(lái)理解Gateway 是門(mén)衛(wèi)和調(diào)度臺(tái)負(fù)責(zé)接消息、驗(yàn)權(quán)限、管會(huì)話(huà)Agent 是干活的負(fù)責(zé)組裝上下文、調(diào)模型、跑工具循環(huán)Skills 是工具箱按需告訴 Agent 這類(lèi)任務(wù)該怎么做Memory 是筆記本把偏好和日志落到本地磁盤(pán)。四者缺一不可但邊界很清楚——Gateway 不推理Agent 不直接對(duì)外暴露端口Skills 不主動(dòng)執(zhí)行Memory 不參與決策。這篇內(nèi)容面向正在搭 OpenClaw 本地環(huán)境的開(kāi)發(fā)者交付四份可復(fù)制的配置骨架并給出逐組件啟動(dòng)驗(yàn)證動(dòng)作。模型通道統(tǒng)一走 TaoToken 的 Key/API這樣你只需要維護(hù)一套憑據(jù)就能在 Gateway 和 Agent 之間完成端到端聯(lián)調(diào)。下面按“先配通道、再配組件、最后聯(lián)調(diào)”的順序展開(kāi)每一步都有可粘貼的配置和驗(yàn)證命令。2. TaoToken 前置統(tǒng)一 Key 與 API 通道在動(dòng) OpenClaw 的 config.toml 之前先把模型通道準(zhǔn)備好。TaoToken 提供統(tǒng)一的 API 入口OpenClaw 的 Agent 在調(diào)用大模型時(shí)只需要指向這個(gè)入口并帶上 Key 即可。這樣做的好處是你換模型、加模型都不用改 OpenClaw 的組件配置只改模型名就行。先拿到 API Key。打開(kāi)控制臺(tái)頁(yè)面登錄后進(jìn)入 API Keys 管理創(chuàng)建一個(gè)新 Key 并復(fù)制保存。這個(gè) Key 只顯示一次建議直接寫(xiě)進(jìn)環(huán)境變量而不是硬編碼進(jìn)配置文件。export TAOTOKEN_API_KEYsk-你的KeyTaoToken 的 API 基礎(chǔ)地址是https://taotoken.net/api兼容 OpenAI 風(fēng)格的/v1/chat/completions路徑。也就是說(shuō)OpenClaw 里凡是需要填base_url的地方統(tǒng)一填這個(gè)地址需要填api_key的地方讀環(huán)境變量。模型名按你實(shí)際要用的填比如gpt-4o、claude-sonnet-4-20250514這類(lèi)具體以控制臺(tái)模型列表為準(zhǔn)。如果你還沒(méi)決定用哪個(gè)模型可以先在模型對(duì)話(huà)頁(yè)面里發(fā)一條測(cè)試消息確認(rèn) Key 和通道是通的再回來(lái)配 OpenClaw。這一步能省掉后面大量“到底是通道問(wèn)題還是組件問(wèn)題”的排查時(shí)間。注意API 地址不要加末尾斜杠OpenClaw 內(nèi)部拼接路徑時(shí)如果出現(xiàn)雙斜杠部分 HTTP 客戶(hù)端會(huì)直接報(bào) 404。3. 可復(fù)制配置骨架config.toml 與 settings.jsonOpenClaw 的配置分兩層config.toml管 Gateway 和全局通道settings.json管 Agent、Skills、Memory 的行為。下面給的是最小可運(yùn)行骨架你可以直接復(fù)制后改路徑和 Key。3.1 config.tomlGateway 與模型通道# ~/.openclaw/config.toml [gateway] host 127.0.0.1 port 18789 # 串行優(yōu)先隊(duì)列保證會(huì)話(huà)狀態(tài)穩(wěn)定 queue_mode serial max_concurrent_sessions 4 [gateway.auth] # 設(shè)備配對(duì)白名單首次啟動(dòng)后把 CLI 設(shè)備 ID 填進(jìn)來(lái) allow_pairing true whitelist [] [model] # 統(tǒng)一走 TaoToken 通道 base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model gpt-4o timeout_seconds 60 [channels.cli] enabled true [channels.web] enabled true這里queue_mode serial是 OpenClaw 的默認(rèn)推薦值。它的含義是每個(gè)會(huì)話(huà)獨(dú)立排隊(duì)、串行執(zhí)行避免多個(gè)執(zhí)行過(guò)程同時(shí)讀寫(xiě)同一會(huì)話(huà)導(dǎo)致?tīng)顟B(tài)錯(cuò)亂。max_concurrent_sessions控制同時(shí)活躍的會(huì)話(huà)數(shù)本地開(kāi)發(fā)機(jī)建議 4 到 8別開(kāi)太大。3.2 settings.jsonAgent、Skills、Memory{ agent: { identity_file: ~/.openclaw/SOUL.md, system_prompt_file: ~/.openclaw/system.md, max_tool_rounds: 8, model: gpt-4o }, skills: { load_order: [builtin, local, plugin], local_dir: ~/.openclaw/skills, auto_match: true }, memory: { root: ~/.openclaw/memory, long_term_file: MEMORY.md, daily_log_pattern: memory/%Y-%m-%d.md, retrieval: { keyword: true, vector: false } } }max_tool_rounds是 Agent 在一次回復(fù)里最多執(zhí)行多少輪工具調(diào)用設(shè)太小會(huì)導(dǎo)致復(fù)雜任務(wù)中途斷掉設(shè)太大又容易陷入循環(huán)8 輪是個(gè)穩(wěn)妥起點(diǎn)。skills.load_order決定同名技能誰(shuí)覆蓋誰(shuí)本地技能放最后加載就能覆蓋內(nèi)置技能。memory.retrieval.vector先關(guān)掉等關(guān)鍵詞檢索跑通再開(kāi)向量檢索否則 Embedding 模型沒(méi)配好會(huì)直接讓會(huì)話(huà)啟動(dòng)失敗。3.3 SOUL.md 與 system.md 最小示例!-- ~/.openclaw/SOUL.md -- 你是一個(gè)本地運(yùn)行的助手語(yǔ)氣簡(jiǎn)潔回答前先確認(rèn)是否需要用工具。!-- ~/.openclaw/system.md -- 當(dāng)前時(shí)間{{now}} 可用技能{{skills}} 長(zhǎng)期記憶摘要{{memory_summary}}這兩個(gè)文件是 Agent 組裝上下文時(shí)的輸入。{{now}}、{{skills}}、{{memory_summary}}是 OpenClaw 的模板占位符啟動(dòng)時(shí)會(huì)被替換成實(shí)際值。如果你發(fā)現(xiàn) Agent 回復(fù)里出現(xiàn)了未替換的花括號(hào)說(shuō)明模板變量名寫(xiě)錯(cuò)了。4. 逐組件啟動(dòng)驗(yàn)證與端到端聯(lián)調(diào)配置寫(xiě)完不要一次性全啟按 Gateway → Agent → Skills → Memory 的順序逐個(gè)驗(yàn)證出問(wèn)題能立刻定位到組件。4.1 驗(yàn)證 Gatewayopenclaw gateway start --config ~/.openclaw/config.toml預(yù)期輸出里會(huì)出現(xiàn)listening on 127.0.0.1:18789和queue_modeserial。另開(kāi)一個(gè)終端確認(rèn)端口curl -s http://127.0.0.1:18789/health返回{status:ok,sessions:0}說(shuō)明 Gateway 正常。如果返回連接拒絕檢查 config.toml 里的 host 是不是被改成了0.0.0.0之外的地址或者端口被占用。4.2 驗(yàn)證 Agent 與模型通道openclaw agent run --config ~/.openclaw/config.toml --message 只回復(fù)兩個(gè)字通了這一步會(huì)走完整的 Agentic Loop組裝上下文 → 調(diào) TaoToken 通道 → 拿回復(fù)。如果返回通了說(shuō)明 Agent 和模型通道都正常。如果報(bào) 401檢查T(mén)AOTOKEN_API_KEY是否在當(dāng)前 shell 里 export 了如果報(bào) 404檢查 base_url 是不是多寫(xiě)了/v1——OpenClaw 內(nèi)部會(huì)自己拼/v1/chat/completions。4.3 驗(yàn)證 Skills 加載在~/.openclaw/skills/下建一個(gè)測(cè)試技能mkdir -p ~/.openclaw/skills/echo-test cat ~/.openclaw/skills/echo-test/SKILL.md EOF # echo-test 當(dāng)用戶(hù)要求“測(cè)試技能”時(shí)直接回復(fù)技能已加載。 EOF然后openclaw skills list --config ~/.openclaw/config.toml預(yù)期在輸出里看到echo-test且來(lái)源標(biāo)記為local。再發(fā)一條openclaw agent run --message 測(cè)試技能如果回復(fù)“技能已加載”說(shuō)明 Skills 的匹配和加載鏈路通了。4.4 驗(yàn)證 Memory 寫(xiě)入與檢索openclaw agent run --message 記住我的時(shí)區(qū)是 Asia/Shanghai然后檢查磁盤(pán)cat ~/.openclaw/memory/MEMORY.md ls ~/.openclaw/memory/預(yù)期MEMORY.md里出現(xiàn)時(shí)區(qū)記錄memory/目錄下出現(xiàn)當(dāng)天的YYYY-MM-DD.md日志文件。再發(fā)一條openclaw agent run --message 我的時(shí)區(qū)是什么如果 Agent 能答出Asia/Shanghai說(shuō)明混合檢索的關(guān)鍵詞分支生效了。4.5 端到端聯(lián)調(diào)四個(gè)組件都單獨(dú)驗(yàn)證過(guò)后走一次完整鏈路openclaw gateway start --config ~/.openclaw/config.toml openclaw agent run --message 幫我記住明天上午十點(diǎn)提醒我看構(gòu)建結(jié)果預(yù)期 Gateway 日志里出現(xiàn)消息分發(fā)記錄Agent 回復(fù)確認(rèn)Memory 里寫(xiě)入提醒事項(xiàng)。到這一步Gateway 接消息、Agent 推理、Skills 按需加載、Memory 持久化的協(xié)作鏈路就完整跑通了。5. 本篇常見(jiàn)錯(cuò)排查Gateway 啟動(dòng)報(bào)端口占用lsof -i :18789找到占用進(jìn)程要么殺掉要么在 config.toml 里換端口。換端口后記得同步改 CLI 的連接配置。Agent 報(bào)model not found模型名寫(xiě)錯(cuò)了。TaoToken 通道下模型名以控制臺(tái)列表為準(zhǔn)別憑記憶寫(xiě)?？梢韵仍谀Ｐ蛯?duì)話(huà)頁(yè)面確認(rèn)模型名再填。Skills 不生效先看openclaw skills list里有沒(méi)有這個(gè)技能。沒(méi)有就是目錄結(jié)構(gòu)不對(duì)——必須是skills/技能名/SKILL.md文件名大小寫(xiě)敏感。有但沒(méi)觸發(fā)檢查auto_match是否為 true以及 SKILL.md 里的觸發(fā)描述是否和用戶(hù)消息語(yǔ)義匹配。Memory 檢索不到關(guān)鍵詞檢索依賴(lài)全文索引如果MEMORY.md是剛寫(xiě)入的索引可能有延遲。重啟一次 Agent 進(jìn)程會(huì)強(qiáng)制重建索引。另外確認(rèn)memory.root路徑存在且可寫(xiě)路徑不存在時(shí) OpenClaw 不會(huì)自動(dòng)創(chuàng)建。上下文里出現(xiàn)未替換的模板變量檢查 system.md 里的占位符拼寫(xiě){{skills}}和{{skill_list}}是兩個(gè)不同的變量寫(xiě)錯(cuò)不會(huì)報(bào)錯(cuò)只會(huì)原樣輸出。串行隊(duì)列導(dǎo)致響應(yīng)慢這是設(shè)計(jì)行為不是 bug。如果確實(shí)需要并發(fā)調(diào)大max_concurrent_sessions但要接受狀態(tài)一致性下降的風(fēng)險(xiǎn)。本地開(kāi)發(fā)場(chǎng)景建議保持串行。6. 把 Key 和通道固定下來(lái)再談擴(kuò)展四個(gè)組件跑通之后你會(huì)發(fā)現(xiàn)真正需要長(zhǎng)期維護(hù)的其實(shí)只有兩樣?xùn)|西模型通道的 Key和組件的配置骨架。Key 統(tǒng)一走 TaoToken 之后換模型、加模型都只是改一個(gè)模型名的事不用動(dòng) Gateway 和 Agent 的代碼。配置骨架固定下來(lái)之后Skills 和 Memory 的擴(kuò)展就是往目錄里加文件風(fēng)險(xiǎn)可控。如果你還在選模型階段可以先去模型對(duì)話(huà)頁(yè)面把幾個(gè)候選模型各發(fā)一條消息對(duì)比一下響應(yīng)速度和格式遵循度再?zèng)Q定default_model填哪個(gè)。如果你打算把 OpenClaw 用在長(zhǎng)期編碼或 Agent 自動(dòng)化場(chǎng)景建議看一下 Coding Plan 的額度模型避免跑長(zhǎng)任務(wù)時(shí)中途斷供。接入過(guò)程中遇到通道報(bào)錯(cuò)優(yōu)先查 API Keys 頁(yè)面確認(rèn) Key 狀態(tài)再對(duì)照接入文檔核對(duì) base_url 和路徑拼接規(guī)則。把這兩步做完大部分“組件沒(méi)問(wèn)題但就是不通”的情況都能定位到通道層。