1. 第一次跑 OpenClaw CLI為什么卡在 openclaw.json剛接觸 OpenClaw圈內(nèi)也叫“龍蝦”的開(kāi)發(fā)者大概率會(huì)遇到同一個(gè)場(chǎng)景照著文檔敲下openclaw init終端刷出一堆日志然后停在某個(gè)地方不動(dòng)了或者直接拋出一句config not found/invalid gateway config。你打開(kāi)目錄一看確實(shí)生成了一個(gè)openclaw.json但里面字段一大堆不知道哪些是必須的、哪些能刪、哪些填錯(cuò)了會(huì)導(dǎo)致 CLI 起不來(lái)。這個(gè)問(wèn)題的本質(zhì)是OpenClaw 的 CLI 在啟動(dòng)時(shí)會(huì)先加載openclaw.json作為網(wǎng)關(guān)gateway配置骨架校驗(yàn)通過(guò)后才去連接模型通道、加載技能skills。新手最容易踩的坑是把“配置文件骨架”和“模型接入配置”混在一起寫(xiě)結(jié)果骨架字段缺失CLI 連第一步校驗(yàn)都過(guò)不去。這篇面向剛上手 OpenClaw 的開(kāi)發(fā)者聚焦三件事一份可復(fù)制的最小openclaw.json骨架、TaoToken 統(tǒng)一 Key/API 通道該填在骨架的哪個(gè)位置、以及用 CLI 命令逐項(xiàng)驗(yàn)證配置是否真的生效。目標(biāo)很明確——讓你跑通第一條鏈路而不是對(duì)著報(bào)錯(cuò)猜字段。適合人群會(huì)用終端、裝過(guò) Node 環(huán)境、但沒(méi)系統(tǒng)配過(guò) OpenClaw 網(wǎng)關(guān)配置的新手。2. 前置準(zhǔn)備TaoToken 統(tǒng)一 Key 與 API 通道在寫(xiě)openclaw.json之前先把模型通道這塊準(zhǔn)備好。OpenClaw 本身是網(wǎng)關(guān) CLI 的框架它需要一個(gè)能對(duì)話、能補(bǔ)全的模型后端。我試過(guò)把通道統(tǒng)一到 TaoToken 上好處是 Key 和 API 地址只維護(hù)一份后面換模型、加技能都不用改多處配置。你需要拿到兩樣?xùn)|西一是 API Key。登錄 TaoToken 控制臺(tái)在 API Keys 頁(yè)面創(chuàng)建一個(gè)新 Key復(fù)制保存。這個(gè) Key 就是后面填進(jìn)openclaw.json的憑證。二是 API 基礎(chǔ)地址。TaoToken 的 API 入口是https://taotoken.net/api注意這個(gè)地址不帶任何查詢參數(shù)直接作為 base URL 使用。模型對(duì)話、coding plan、控制臺(tái)、API Keys、接入文檔這些入口都可以從官網(wǎng) https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 進(jìn)去后按導(dǎo)航找到。注意Key 只創(chuàng)建一次就夠不要每個(gè)技能都單獨(dú)建 Key。統(tǒng)一通道的意義就在于“一處配置多處復(fù)用”。Key 泄露風(fēng)險(xiǎn)高別寫(xiě)進(jìn)會(huì)提交到 Git 的文件里用環(huán)境變量或本地配置文件隔離。如果你后面要做長(zhǎng)期編碼或 Agent 類任務(wù)可以了解下 Coding Plan它更適合持續(xù)性的代碼生成場(chǎng)景只是驗(yàn)證模型通不通用模型對(duì)話頁(yè)面點(diǎn)幾下就能確認(rèn)。這兩條路徑和本篇的 CLI 驗(yàn)證是互補(bǔ)的不沖突。3. 可復(fù)制的 openclaw.json 最小骨架下面這份骨架是我實(shí)測(cè)能跑通 CLI 啟動(dòng)的最小集合。字段名以 OpenClaw 官方配置文檔為準(zhǔn)你可以直接復(fù)制把a(bǔ)piKey換成自己的。{ gateway: { name: local-gateway, port: 8787, host: 127.0.0.1 }, providers: [ { id: taotoken, type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密鑰, models: [ { id: gpt-4o-mini, name: default-chat } ] } ], defaultProvider: taotoken, defaultModel: default-chat, skills: { enabled: true, dir: ./skills } }逐段說(shuō)明一下方便你理解每個(gè)字段為什么在骨架里gateway是網(wǎng)關(guān)自身的信息。port和host決定 CLI 本地監(jiān)聽(tīng)的地址新手保持127.0.0.1和8787即可別急著改端口改了要同步改驗(yàn)證命令。providers是模型通道數(shù)組。type填openai-compatible因?yàn)?TaoToken 的 API 兼容 OpenAI 風(fēng)格的請(qǐng)求格式。baseUrl就是上一步的https://taotoken.net/api注意結(jié)尾不要多加/v1具體路徑由 OpenClaw 內(nèi)部拼接。apiKey填你的 Key。models里給模型起個(gè)別名default-chat這樣defaultModel引用它時(shí)不用記原始模型 ID換模型只改這一處。skills段控制技能加載。enabled: true打開(kāi)技能系統(tǒng)dir指向技能目錄。新手如果暫時(shí)不裝技能可以先把enabled設(shè)為false減少啟動(dòng)時(shí)的變量。提示openclaw.json對(duì) JSON 格式很敏感多一個(gè)逗號(hào)、少一個(gè)引號(hào)都會(huì)導(dǎo)致解析失敗。建議用編輯器的 JSON 校驗(yàn)功能或者保存后用node -e JSON.parse(require(fs).readFileSync(openclaw.json,utf8))先驗(yàn)一遍語(yǔ)法。4. CLI 逐項(xiàng)驗(yàn)證配置是否生效配置文件寫(xiě)完不等于生效。OpenClaw CLI 提供了一組命令可以分層驗(yàn)證。按下面順序走哪一步失敗就停在哪一步排查比一次性啟動(dòng)再看一堆日志高效得多。第一步驗(yàn)證 JSON 語(yǔ)法和骨架結(jié)構(gòu)openclaw config validate這條命令只做靜態(tài)校驗(yàn)不啟動(dòng)網(wǎng)關(guān)。如果輸出config is valid說(shuō)明骨架字段沒(méi)缺、JSON 沒(méi)寫(xiě)錯(cuò)。如果報(bào)missing required field: gateway.port這類錯(cuò)誤就回到上一節(jié)對(duì)照字段補(bǔ)。第二步驗(yàn)證 provider 通道能否連通openclaw provider test taotoken它會(huì)用你配置的baseUrl和apiKey發(fā)一個(gè)最小請(qǐng)求。成功時(shí)返回模型列表或一個(gè)簡(jiǎn)短的響應(yīng)失敗常見(jiàn)的是401Key 錯(cuò)或404baseUrl 路徑錯(cuò)。這一步過(guò)了說(shuō)明 TaoToken 通道是通的。第三步啟動(dòng)網(wǎng)關(guān)并確認(rèn)監(jiān)聽(tīng)openclaw start終端會(huì)打印網(wǎng)關(guān)啟動(dòng)日志包含監(jiān)聽(tīng)地址。另開(kāi)一個(gè)終端用 curl 探一下curl -s http://127.0.0.1:8787/health返回{status:ok}之類的健康響應(yīng)說(shuō)明網(wǎng)關(guān)進(jìn)程活著。第四步跑一次端到端對(duì)話確認(rèn)模型鏈路完整openclaw chat 用一句話說(shuō)明什么是網(wǎng)關(guān)如果終端返回了模型生成的回答恭喜第一條鏈路跑通了。這一步同時(shí)驗(yàn)證了 gateway、provider、defaultModel 三段配置的聯(lián)動(dòng)。第五步確認(rèn)技能系統(tǒng)狀態(tài)openclaw skills list列出已加載的技能。如果skills.enabled是true但列表為空檢查dir路徑是否存在、里面有沒(méi)有技能包。新手階段列表為空不影響主鏈路可以先放著。5. 本篇常見(jiàn)報(bào)錯(cuò)與排查新手在配openclaw.json時(shí)報(bào)錯(cuò)集中在幾個(gè)固定位置。下面按“報(bào)錯(cuò)信息 → 原因 → 動(dòng)作”整理方便你對(duì)號(hào)入座。Error: config file not foundCLI 沒(méi)在當(dāng)前目錄找到openclaw.json。確認(rèn)你在項(xiàng)目根目錄執(zhí)行命令或者用openclaw --config /path/to/openclaw.json顯式指定路徑。SyntaxError: Unexpected token }JSON 語(yǔ)法錯(cuò)誤通常是多逗號(hào)或漏引號(hào)。用第 3 節(jié)的node -e命令定位到具體行。401 UnauthorizedapiKey無(wú)效或過(guò)期。去 TaoToken 控制臺(tái)重新生成一個(gè) Key替換后重跑openclaw provider test。404 Not FoundbaseUrl寫(xiě)錯(cuò)常見(jiàn)的是多寫(xiě)了/v1或少了/api。正確值是https://taotoken.net/api。EADDRINUSE: port 8787 already in use端口被占用。要么關(guān)掉占用進(jìn)程要么改gateway.port改完記得同步改 curl 驗(yàn)證的地址。defaultModel not founddefaultModel引用的別名在models數(shù)組里不存在。檢查models[].name和defaultModel是否完全一致大小寫(xiě)敏感。skills dir not existskills.dir指向的目錄不存在。要么創(chuàng)建目錄要么把skills.enabled設(shè)為false先跳過(guò)。注意排查時(shí)一次只改一個(gè)字段改完立刻重跑對(duì)應(yīng)的驗(yàn)證命令。同時(shí)改多處報(bào)錯(cuò)消失了你也不知道是哪處修好的下次還會(huì)踩。6. 跑通之后把 Key 和通道固定下來(lái)第一條鏈路跑通后建議做兩件收尾的事能省掉后面大量重復(fù)勞動(dòng)。一是把 Key 從openclaw.json里挪出去改用環(huán)境變量引用。OpenClaw 支持在配置里寫(xiě)${TAOTOKEN_API_KEY}這類占位符實(shí)際值從環(huán)境變量讀。這樣配置文件可以安全地進(jìn)版本庫(kù)Key 不會(huì)跟著泄露。二是把openclaw.json的骨架部分單獨(dú)抽一份模板放在項(xiàng)目里。以后新建項(xiàng)目直接復(fù)制模板只改providers里的 Key 和模型別名骨架字段不用重新想。TaoToken 的 Key 和 API 通道統(tǒng)一維護(hù)一份換模型時(shí)只動(dòng)models數(shù)組gateway和skills段完全不用碰。如果你后面要接長(zhǎng)期編碼任務(wù)或 Agent 流程可以在 TaoToken 的 Coding Plan 里看下適合持續(xù)調(diào)用的方案只是日常驗(yàn)證模型模型對(duì)話入口點(diǎn)幾下就夠。接入細(xì)節(jié)和字段說(shuō)明接入文檔里有完整對(duì)照。把這篇的骨架和驗(yàn)證命令存下來(lái)下次配新環(huán)境十分鐘內(nèi)能跑通。