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