1. OpenClaw 核心概念與基本語法從零搭建第一個可運行示例OpenClaw 是一套面向任務(wù)編排與工具調(diào)用的運行時框架你可以把它理解成一個“調(diào)度中樞”它負責把用戶輸入拆解成若干步驟再按順序或條件調(diào)用不同的工具Tool去執(zhí)行最后把結(jié)果拼裝成完整回復(fù)。它適合誰適合已經(jīng)會寫 Python 或 JavaScript、想快速把大模型能力接進自己業(yè)務(wù)流的開發(fā)者也適合需要把多個 API、腳本、數(shù)據(jù)庫查詢串成一條流水線的工程同學。我第一次接觸 OpenClaw 時最困惑的不是語法而是“任務(wù)編排”和“工具調(diào)用”這兩個詞到底對應(yīng)代碼里的什么結(jié)構(gòu)。后來跑通一個最小示例才明白編排就是一份聲明式的流程描述工具調(diào)用就是在這份描述里掛載可執(zhí)行函數(shù)。本文會用一個最小可運行示例把 OpenClaw 的核心概念、基本語法、配置片段和驗證動作全部串起來讓你在本地直接復(fù)制就能跑。核心檢索詞先記住三個OpenClaw 核心概念、OpenClaw 基本語法、OpenClaw 最小可運行示例。下面從場景問題開始一步步落地。1.1 為什么需要 OpenClaw從“單次問答”到“多步任務(wù)”很多人第一次用大模型 API都是寫一個messages數(shù)組直接請求拿到回復(fù)就結(jié)束。這種模式在簡單問答里夠用但一旦任務(wù)變成“先查天氣再根據(jù)天氣推薦穿搭最后生成一段文案”單次請求就撐不住了。你需要把任務(wù)拆成多個步驟每個步驟可能調(diào)用不同工具還要處理中間結(jié)果。手寫if/else和for循環(huán)當然可以但代碼會迅速膨脹且難以復(fù)用和調(diào)試。OpenClaw 要解決的就是這個問題。它把“任務(wù)”抽象成一份可聲明的流程把“工具”抽象成帶 schema 的函數(shù)運行時負責按流程調(diào)度。你不再需要手寫調(diào)度邏輯只需要描述“先做什么、再做什么、什么條件下走哪個分支”。我實測下來一個三步驟的編排流程用 OpenClaw 寫出來比裸寫 Python 少一半代碼而且出錯時能直接定位到具體步驟。這里要區(qū)分兩個概念。任務(wù)編排Orchestration關(guān)注的是步驟之間的順序、條件、循環(huán)和錯誤處理工具調(diào)用Tool Calling關(guān)注的是單個步驟如何執(zhí)行、參數(shù)如何校驗、結(jié)果如何返回。OpenClaw 把這兩層分開編排層用聲明式語法工具層用普通函數(shù)加裝飾器。這樣你可以單獨測試每個工具也可以單獨調(diào)整編排流程互不影響。還有一個容易被忽略的點OpenClaw 的編排是“可觀測”的。每個步驟執(zhí)行時都會產(chǎn)生事件你可以訂閱這些事件做日志、埋點或人工介入。這在生產(chǎn)環(huán)境里非常關(guān)鍵因為多步任務(wù)一旦失敗你需要知道是哪一步、什么參數(shù)、什么錯誤。裸寫循環(huán)很難做到這一點而 OpenClaw 默認就帶。所以如果你的任務(wù)超過兩步或者需要調(diào)用外部工具或者需要錯誤重試和條件分支OpenClaw 就值得上手。接下來先解決前置依賴再寫第一個示例。2. TaoToken 前置準備拿到 Base URL、API Key 和 Model IDOpenClaw 本身是編排框架它需要一個大模型來驅(qū)動“理解意圖”和“生成參數(shù)”。你可以把模型理解成 OpenClaw 的“大腦”工具是“手腳”。所以跑通示例前你需要一個可用的模型接入點。這里我用 TaoToken 作為模型接入層因為它同時提供 OpenAI 兼容接口和 Claude Code 兼容接口配置簡單適合本地快速驗證。你需要準備三樣東西Base URL、API Key、Model ID。這三件套是后面所有配置的基礎(chǔ)缺一不可。Base URL 是接口地址API Key 是身份憑證Model ID 是你要調(diào)用的具體模型。很多人卡在第一步就是因為只拿了 Key沒確認 Base URL 和 Model ID結(jié)果請求一直 401 或 404。先訪問 TaoToken 官網(wǎng)注冊并登錄https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。登錄后進入控制臺在 API Keys 頁面創(chuàng)建一個新的 Key。創(chuàng)建時建議命名成openclaw-local方便后面區(qū)分。Key 只顯示一次復(fù)制后先存到本地環(huán)境變量里不要直接寫進代碼提交到 Git。Base URL 用https://taotoken.net/api注意這個地址不帶任何查詢參數(shù)。Model ID 可以在模型列表頁看到常見的有claude-sonnet-4-20250514、gpt-4o等。如果你不確定選哪個先用claude-sonnet-4-20250514它在工具調(diào)用和長上下文場景下表現(xiàn)穩(wěn)定。我試過用較小的模型跑編排步驟一多就容易漏參數(shù)所以建議第一個示例用能力較強的模型。把這三件套寫進環(huán)境變量Linux/macOS 用exportWindows 用set或 PowerShell 的$env:。下面給一個.env文件示例OpenClaw 啟動時會自動讀取# .env TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEYsk-你的實際Key TAOTOKEN_MODEL_IDclaude-sonnet-4-20250514注意不要把.env提交到版本庫在.gitignore里加上它。如果你用 Docker可以在docker-compose.yml里通過env_file注入。這一步做完前置準備就結(jié)束了。接下來進入可復(fù)制配置環(huán)節(jié)。3. 可復(fù)制配置OpenClaw 項目結(jié)構(gòu)與 settings 片段OpenClaw 的項目結(jié)構(gòu)很輕一個最小示例只需要三個文件settings.json運行時配置、tools.py工具定義、flow.py編排流程。我建議你新建一個目錄openclaw-demo在里面創(chuàng)建這三個文件。下面逐個給出可復(fù)制內(nèi)容路徑和原文保持一致你直接粘貼即可。先看settings.json。這個文件告訴 OpenClaw 用哪個模型、哪個 Base URL、超時多久、日志級別是什么。注意model字段填 Model IDbase_url填 TaoToken 的 API 地址api_key從環(huán)境變量讀取不要硬編碼。{ runtime: { name: openclaw-local, log_level: info, timeout_seconds: 60 }, model: { provider: openai-compatible, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, model: claude-sonnet-4-20250514, max_tokens: 2048, temperature: 0.2 }, tools: { registry: ./tools.py, strict_schema: true }, flow: { entry: ./flow.py, max_steps: 10, retry_on_error: 2 } }這里有幾個參數(shù)值得說明。strict_schema設(shè)為true時工具參數(shù)會嚴格校驗類型不對直接報錯避免模型傳錯參數(shù)導(dǎo)致運行時崩潰。max_steps限制單次任務(wù)最多執(zhí)行多少步防止死循環(huán)。retry_on_error是失敗重試次數(shù)網(wǎng)絡(luò)抖動時很有用。temperature設(shè)低一點編排場景需要穩(wěn)定輸出不需要創(chuàng)意。再看tools.py。OpenClaw 的工具用裝飾器注冊函數(shù)簽名就是參數(shù) schema。下面定義兩個工具一個查天氣一個生成文案。查天氣用模擬數(shù)據(jù)避免依賴外部 API生成文案調(diào)用模型。# tools.py from openclaw import tool tool( nameget_weather, description查詢指定城市的當前天氣, parameters{ city: {type: string, description: 城市名稱如北京} } ) def get_weather(city: str) - dict: mock { 北京: {temp: 22, condition: 晴}, 上海: {temp: 26, condition: 多云}, 廣州: {temp: 30, condition: 小雨} } data mock.get(city, {temp: 20, condition: 未知}) return {city: city, temp: data[temp], condition: data[condition]} tool( namegenerate_copy, description根據(jù)天氣信息生成一段穿搭文案, parameters{ weather: {type: string, description: 天氣描述}, style: {type: string, description: 文案風格如輕松、正式} } ) def generate_copy(weather: str, style: str) - str: return f[{style}] 今天{weather}建議穿輕薄外套注意防曬。注意parameters里的類型和描述模型會根據(jù)這些信息決定傳什么參數(shù)。描述越清楚模型傳參越準。strict_schema會校驗city必須是字符串傳數(shù)字會直接報錯。最后看flow.py。這是編排入口用聲明式語法描述步驟。OpenClaw 的流程語法類似 YAML 加 Python 表達式的混合但這里用純 Python 字典方便你直接運行。# flow.py from openclaw import flow, step flow(nameweather_outfit) def weather_outfit(): return [ step( idfetch_weather, toolget_weather, input{city: {{ user_input.city }}}, outputweather_data ), step( idmake_copy, toolgenerate_copy, input{ weather: {{ weather_data.condition }}{{ weather_data.temp }}度, style: 輕松 }, outputfinal_copy ) ]{{ user_input.city }}是變量引用運行時從用戶輸入里取。output把結(jié)果存到上下文下一步用{{ weather_data.condition }}引用。這種聲明式寫法讓步驟之間的依賴一目了然。三個文件建好后目錄結(jié)構(gòu)如下openclaw-demo/ ├── settings.json ├── tools.py └── flow.py如果你用 Claude Code 或 Cline 這類工具可以把 Base URL、API Key、Model ID 填進它們的配置里讓它們幫你生成和調(diào)試 OpenClaw 代碼。三件套的對應(yīng)關(guān)系是Base URL 填https://taotoken.net/apiAPI Key 填你創(chuàng)建的 KeyModel ID 填claude-sonnet-4-20250514。配置完成后進入驗證環(huán)節(jié)。4. 驗證請求運行第一個 OpenClaw 流程并檢查結(jié)果配置寫好后用一條命令啟動 OpenClaw 運行時。假設(shè)你已經(jīng)安裝了 OpenClaw CLI在openclaw-demo目錄下執(zhí)行openclaw run --settings ./settings.json --input {city: 北京}如果一切正常你會看到類似下面的輸出{ status: success, steps: [ { id: fetch_weather, tool: get_weather, output: {city: 北京, temp: 22, condition: 晴} }, { id: make_copy, tool: generate_copy, output: [輕松] 今天晴22度建議穿輕薄外套注意防曬。 } ], final: [輕松] 今天晴22度建議穿輕薄外套注意防曬。 }看到status: success和final字段說明流程跑通了。steps數(shù)組里每一步的輸入輸出都記錄在案方便你排查。如果你只看到第一步成功、第二步失敗通常是變量引用寫錯了比如weather_data.condition拼成了weather.condition。再驗證一個邊界情況傳一個不存在的城市。執(zhí)行openclaw run --settings ./settings.json --input {city: 深圳}因為get_weather里對未知城市返回默認值流程仍然會成功輸出里condition是“未知”。這說明工具層的容錯生效了。如果你希望未知城市直接報錯可以在工具里拋異常OpenClaw 會根據(jù)retry_on_error決定是否重試。驗證模型調(diào)用是否真的走了 TaoToken可以打開log_level為debug重新運行你會看到請求的 Base URL 和 Model ID。確認 Base URL 是https://taotoken.net/apiModel ID 是claude-sonnet-4-20250514。如果看到的是其他地址說明settings.json沒生效檢查文件路徑和 JSON 格式。還有一個實用技巧用openclaw validate命令先校驗配置和工具 schema不實際執(zhí)行。這樣可以在跑流程前發(fā)現(xiàn)參數(shù)類型錯誤、工具名拼寫錯誤等問題。我踩過的坑是工具名大小寫不一致get_weather寫成GetWeather運行時才報錯用validate能提前發(fā)現(xiàn)。驗證通過后你可以把flow.py改成更復(fù)雜的流程比如加條件分支如果溫度低于 15 度走“保暖”文案否則走“輕薄”文案。OpenClaw 支持branch步驟語法類似if/else。這一步留給你自己擴展核心驗證已經(jīng)完成。5. 常見錯誤排查401、local proxy failed、reading choices、OAuth跑 OpenClaw 時最容易遇到的四類報錯我按出現(xiàn)頻率排序逐個給出原因和修復(fù)動作。第一類是401 Unauthorized通常伴隨invalid api key。原因有三個Key 沒填、Key 填錯、Key 對應(yīng)的環(huán)境變量沒加載。檢查.env文件是否被讀取或者直接在settings.json里臨時寫死 Key 測試。如果寫死能通說明環(huán)境變量注入有問題。注意不要用Bearer前綴重復(fù)拼接OpenClaw 會自動加。第二類是local proxy failed或connection refused。這個報錯說明 OpenClaw 嘗試連接 Base URL 時失敗了。先確認base_url是https://taotoken.net/api沒有多余斜杠或路徑。再確認本機網(wǎng)絡(luò)能訪問該地址可以用curl -I https://taotoken.net/api測試。如果 curl 通但 OpenClaw 不通檢查是否有本地代理配置干擾把HTTP_PROXY和HTTPS_PROXY環(huán)境變量臨時清空再試。第三類是reading choices相關(guān)報錯比如cannot read property choices of undefined。這通常發(fā)生在模型返回體不是預(yù)期格式時。原因可能是 Model ID 填錯或者 Base URL 指向了不兼容的接口。確認provider是openai-compatiblemodel字段是有效的 Model ID。如果返回體里沒有choices打印原始響應(yīng)看看可能是鑒權(quán)失敗返回了錯誤對象。第四類是OAuth相關(guān)報錯比如OAuth token expired或invalid_grant。如果你用 Claude Code 或 Cline 的 OAuth 模式接入需要重新走授權(quán)流程。但 OpenClaw 本身用 API Key 模式不涉及 OAuth。如果你在 CC Switch 或 Codex 的auth.json里配置確保三件套齊全Base URL、API Key、Model ID。缺任何一個都會導(dǎo)致鑒權(quán)失敗。下面給一個對照表方便你快速定位報錯關(guān)鍵詞可能原因修復(fù)動作401 UnauthorizedKey 缺失或錯誤檢查環(huán)境變量和 Key 拼寫local proxy failedBase URL 不可達確認地址并測試網(wǎng)絡(luò)reading choicesModel ID 或 provider 錯誤核對 Model ID 和 providerOAuth invalid_grant授權(quán)過期重新生成 Key 或走 API Key 模式還有一個隱蔽問題strict_schema開啟后模型傳的參數(shù)類型不對會直接報schema validation failed。這時看報錯里的字段名回到tools.py檢查parameters定義。比如temp定義成integer模型傳了字符串22就會失敗。把類型改成string或在工具里做轉(zhuǎn)換即可。排查完這些你的 OpenClaw 流程應(yīng)該能穩(wěn)定運行了。如果還想驗證模型對話能力可以訪問模型對話頁面直接測試如果要做長期編碼或 Agent 任務(wù)可以了解 Coding Plan。6. 從最小示例到真實任務(wù)下一步怎么走跑通最小示例后你手里已經(jīng)有了 OpenClaw 的核心骨架settings.json管配置tools.py管工具flow.py管編排。接下來擴展的方向有三個。第一是增加工具比如接入數(shù)據(jù)庫查詢、HTTP 請求、文件讀寫。每個工具都用tool裝飾器注冊參數(shù) schema 寫清楚。第二是增加編排復(fù)雜度比如加條件分支、并行步驟、循環(huán)重試。OpenClaw 的step支持branch、parallel、loop等類型語法和現(xiàn)有示例一致。第三是接入真實模型把generate_copy里的模擬返回換成實際調(diào)用讓模型根據(jù)天氣生成更自然的文案。如果你在擴展時遇到鑒權(quán)或接入問題可以到 API Keys 頁面重新生成 Key或查閱接入文檔確認參數(shù)格式。驗證模型能力時模型對話頁面可以快速測試不同 Model ID 的效果。長期做編碼和 Agent 任務(wù)的話Coding Plan 提供了更穩(wěn)定的配額和并發(fā)支持。最后給一個實用建議把settings.json里的log_level在開發(fā)階段設(shè)為debug上線前改回info。debug會打印每次模型請求和工具調(diào)用的詳細參數(shù)排查問題時非常有用但日志量大。另外工具函數(shù)盡量保持無副作用需要寫操作時單獨抽一個工具這樣編排層可以放心重試。OpenClaw 的編排能力在任務(wù)超過三步時優(yōu)勢最明顯你可以先從把現(xiàn)有腳本改造成工具開始逐步遷移到聲明式流程。