1. 從 OpenClaw 源碼看 Agent 到底由什么組成OpenClaw 是一個跑在生產(chǎn)環(huán)境里的 AI Agent 框架代碼量不小但核心就四個模塊——執(zhí)行循環(huán)、工具系統(tǒng)、記憶系統(tǒng)、插件系統(tǒng)。這篇文章把每個模塊拆開看看里面怎么寫的最后整理一份自己做 Agent 時可以參考的清單并且給出一份可以直接復(fù)制的 TaoToken 配置骨架讓你在本地把 Agent 跑起來。如果你熟悉 TypeScript 和 LLM API 的基本概念讀起來會很順。如果你還不了解 Function Calling建議先補一下工具調(diào)用Tool Use的基礎(chǔ)概念再回來看源碼結(jié)構(gòu)會清晰很多。一句話概括 OpenClaw 的架構(gòu)Gateway 接收消息 → Agent 循環(huán)調(diào)用 LLM 工具 → 記憶系統(tǒng)提供上下文 → 插件擴展一切。四個模塊各管各的耦合度不高。先掃一眼目錄結(jié)構(gòu)目錄一句話說明src/agents/Agent 執(zhí)行循環(huán)、工具注冊、模型管理src/memory/記憶索引、嵌入向量、混合檢索src/gateway/WebSocket 網(wǎng)關(guān)、認證、RPCsrc/plugin-sdk/插件 SDK、Hook 系統(tǒng)src/channels/通道抽象層狀態(tài)機、路由、線程綁定extensions/73 個插件通道 / LLM Provider / 工具擴展這篇的重點不是把每個文件都念一遍而是把「構(gòu)建一個 Agent 需要哪些零件」講清楚然后給你一份能直接跑的配置骨架。LLM 調(diào)用通道這塊我用 TaoToken 做統(tǒng)一入口一個 Key 就能覆蓋多種模型省得在多個 Provider 之間來回切。2. TaoToken 前置統(tǒng)一 Key 與 API 通道在動手寫 Agent 之前先把 LLM 調(diào)用通道準備好。OpenClaw 的模型管理模塊src/agents/ 下的 Provider 相關(guān)代碼本質(zhì)上就是維護一組「Provider Auth Profile 模型名」的映射然后按優(yōu)先級做 Failover。你自己做 Agent 時如果每個 Provider 都單獨配 Key、單獨處理限流和重試代碼會迅速膨脹。TaoToken 在這里扮演的角色是統(tǒng)一入口一個 API Key一個 Base URL就能調(diào)用多種模型。對 Agent 來說這意味著你的 LLM 調(diào)用層只需要維護一套認證邏輯模型切換只是改一個字符串。你需要準備的東西一個 TaoToken 賬號登錄后在控制臺創(chuàng)建 API Key記下 API Base URLhttps://taotoken.net/api選一個默認模型名比如claude-sonnet-4-20250514或gpt-4o具體以控制臺模型列表為準控制臺入口在這里https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Key 管理頁面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite拿到 Key 之后先別急著寫 Agent用一條 curl 驗證通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 只回復(fù)兩個字通了}], max_tokens: 32 }如果返回里能看到choices[0].message.content說明通道沒問題。這一步很重要因為后面 Agent 報錯時你需要快速判斷是「通道問題」還是「Agent 邏輯問題」。把通道單獨驗證過排障范圍就縮小了一半。注意API Key 不要硬編碼進源碼。用環(huán)境變量TAOTOKEN_API_KEY或者放進.env文件并加進.gitignore。3. 可復(fù)制配置settings.json 與 config.toml 骨架OpenClaw 的配置入口分散在幾個地方但核心就兩類一類是「運行時配置」模型、通道、記憶一類是「Agent 行為配置」System Prompt、工具開關(guān)、循環(huán)上限。下面給兩份骨架你可以直接復(fù)制到自己的項目里改。3.1 settings.jsonAgent 運行時配置這份配置對應(yīng) OpenClaw 里src/agents/和src/memory/的初始化參數(shù)。我把它整理成一份扁平結(jié)構(gòu)方便你對照源碼理解每個字段的作用{ agent: { id: my-first-agent, name: 本地 Agent 雛形, maxToolRounds: 12, stream: true, systemPromptFile: ./prompts/system.md }, llm: { provider: taotoken, baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, model: claude-sonnet-4-20250514, fallbackModels: [gpt-4o, claude-haiku-4-20250514], timeoutMs: 60000, maxRetries: 3 }, tools: { enabled: [read_file, write_file, exec, web_search], requireConfirm: [write_file, exec], loopDetection: { windowSize: 30, warnAt: 10, stopAt: 20, abortAt: 30 } }, memory: { enabled: true, dbPath: ./data/memory.sqlite, embeddingProvider: taotoken, embeddingModel: text-embedding-3-small, hybridWeights: { vector: 0.7, bm25: 0.3 }, temporalDecayHalfLifeDays: 30 } }幾個字段值得單獨說maxToolRounds對應(yīng) OpenClaw 里工具循環(huán)的上限。設(shè)太小復(fù)雜任務(wù)跑不完設(shè)太大一旦邏輯出錯會燒很多 token。12 是個比較穩(wěn)的起步值。fallbackModels就是 Failover 的簡化版。主模型限流或報錯時按順序切下一個。OpenClaw 的run.ts里做得更細會冷卻出問題的 Auth Profile但核心思路一致。loopDetection直接抄了 OpenClaw 的三級熔斷10 次警告、20 次強制提示、30 次終止?；瑒哟翱诖笮?30 是它的默認值。3.2 config.toml通道與網(wǎng)關(guān)配置如果你要接消息通道Discord、Slack、Web UI這部分對應(yīng)src/gateway/和src/channels/[gateway] host 127.0.0.1 port 8787 auth_token_env GATEWAY_TOKEN [channels.web] enabled true path /chat [channels.discord] enabled false bot_token_env DISCORD_BOT_TOKEN [state_machine] idle_timeout_sec 300 max_concurrent_sessions 4 [logging] level info file ./logs/agent.logstate_machine這段對應(yīng) OpenClaw 的src/channels/run-state-machine.ts。每個會話有獨立狀態(tài)idle → running → drafting → completed保證同一會話不會被并發(fā)請求搞亂。你自己做的時候哪怕先不做完整狀態(tài)機至少也要給每個會話加一把鎖。3.3 System Prompt 骨架OpenClaw 的system-prompt.ts是動態(tài)拼裝的——運行時信息、工具列表、通道能力、用戶指令按需注入。你可以先從一個靜態(tài)文件開始你是運行在本地環(huán)境中的 AI Agent。 ## 運行環(huán)境 - 操作系統(tǒng){{os}} - 當(dāng)前時間{{now}} - 工作目錄{{cwd}} ## 可用工具 {{tool_list}} ## 行為準則 1. 需要讀取文件時先調(diào)用 read_file不要憑記憶猜測內(nèi)容。 2. 執(zhí)行有副作用的操作寫文件、跑命令前先說明你要做什么。 3. 如果連續(xù)兩次工具調(diào)用沒有進展停下來向用戶確認。{{tool_list}}由代碼在啟動時注入格式就是工具名 描述。LLM 靠這段描述判斷什么時候該調(diào)哪個工具所以描述要寫清楚「做什么」和「什么時候用」。4. 驗證請求本地啟動并跑通一次 Agent 響應(yīng)配置寫好了接下來把它跑起來。下面給一個最小可運行的 TypeScript 入口對應(yīng) OpenClaw 的src/agents/pi-embedded-runner/run/attempt.ts——單次 LLM 調(diào)用加工具循環(huán)。4.1 安裝依賴npm init -y npm install openai dotenv npm install -D typescript tsx types/node這里用openai這個 SDK 就行因為 TaoToken 的 API 兼容 OpenAI 的請求格式改一下baseURL就能用。4.2 核心循環(huán)代碼// src/agent.ts import OpenAI from openai; import dotenv/config; const client new OpenAI({ apiKey: process.env.TAOTOKEN_API_KEY!, baseURL: https://taotoken.net/api/v1, }); const tools [ { type: function as const, function: { name: read_file, description: 讀取指定路徑的文件內(nèi)容, parameters: { type: object, properties: { path: { type: string } }, required: [path], }, }, }, ]; async function runAgent(userInput: string) { const messages: OpenAI.Chat.ChatCompletionMessageParam[] [ { role: system, content: 你是一個本地 Agent需要讀文件時調(diào)用 read_file。 }, { role: user, content: userInput }, ]; for (let round 0; round 12; round) { const res await client.chat.completions.create({ model: claude-sonnet-4-20250514, messages, tools, stream: false, }); const msg res.choices[0].message; messages.push(msg); if (!msg.tool_calls || msg.tool_calls.length 0) { console.log(最終回復(fù), msg.content); return msg.content; } for (const call of msg.tool_calls) { const args JSON.parse(call.function.arguments); let result ; if (call.function.name read_file) { try { result await import(fs/promises).then((fs) fs.readFile(args.path, utf-8)); } catch (e) { result 讀取失敗${(e as Error).message}; } } messages.push({ role: tool, tool_call_id: call.id, content: result.slice(0, 4000), }); } } throw new Error(工具循環(huán)超過上限已終止); } runAgent(讀一下 package.json告訴我項目名和依賴數(shù)量);4.3 運行與預(yù)期結(jié)果npx tsx src/agent.ts正常的話你會看到 Agent 先發(fā)起一次read_file工具調(diào)用拿到文件內(nèi)容后再生成一段自然語言回復(fù)類似最終回復(fù)項目名是 my-agent-demodependencies 里有 2 個依賴openai 和 dotenv。這個過程就是 Agent 的最小骨架LLM 決定調(diào)工具 → 代碼執(zhí)行工具 → 結(jié)果喂回 LLM → LLM 生成最終回復(fù)。OpenClaw 的attempt.ts做的也是這件事只是外面包了流式處理、容錯、上下文壓縮。4.4 加上流式輸出把stream: false改成true然后處理text_delta事件用戶就能邊生成邊看到字。OpenClaw 的pi-embedded-subscribe.ts就是干這個的它還會在語義邊界處切分文本塊避免把半個句子推給用戶。const stream await client.chat.completions.create({ model: claude-sonnet-4-20250514, messages, tools, stream: true, }); for await (const chunk of stream) { const delta chunk.choices[0]?.delta; if (delta?.content) process.stdout.write(delta.content); }流式模式下工具調(diào)用的參數(shù)是分片到達的需要自己拼接tool_calls的arguments字符串等finish_reason變成tool_calls再解析。這是新手最容易踩的坑之一。5. 本篇常見錯排查5.1 401 / 403Key 沒讀到或格式不對最常見的原因是環(huán)境變量沒加載。dotenv/config要在最頂部導(dǎo)入且.env文件里寫的是TAOTOKEN_API_KEYsk-xxx不要加引號。如果用的是 shell 導(dǎo)出確認echo $TAOTOKEN_API_KEY有輸出。另一個原因是 Base URL 寫錯。注意區(qū)分https://taotoken.net/api是根路徑SDK 里通常要寫https://taotoken.net/api/v1。如果你用的是原生 fetch 拼/v1/chat/completions那就用根路徑。5.2 模型名報錯 model_not_found模型名要以控制臺模型列表為準不要憑記憶寫。不同 Provider 的命名風(fēng)格不一樣有的帶日期后綴有的不帶。建議把模型名放進配置文件別散落在代碼里。5.3 工具調(diào)用死循環(huán)表現(xiàn)是 Agent 反復(fù)調(diào)同一個工具token 嘩嘩燒。原因通常是工具返回的結(jié)果 LLM 看不懂或者 System Prompt 沒告訴它「拿到結(jié)果后該干什么」。排查方法把每輪的工具調(diào)用名和參數(shù)打出來看是不是同一個調(diào)用重復(fù)出現(xiàn)。修復(fù)方法有兩個一是把工具返回內(nèi)容結(jié)構(gòu)化別返回一坨亂碼二是在循環(huán)里加計數(shù)超過閾值就強制讓 LLM 生成最終回復(fù)。const callCount new Mapstring, number(); // 在每次工具調(diào)用前 const key ${call.function.name}:${call.function.arguments}; const n (callCount.get(key) ?? 0) 1; callCount.set(key, n); if (n 3) { messages.push({ role: user, content: 同一工具已重復(fù)調(diào)用多次請基于現(xiàn)有信息直接回答。 }); }5.4 上下文超長導(dǎo)致請求失敗長對話跑到后面messages 數(shù)組會超過模型窗口。OpenClaw 的做法是用 Context Engine 對歷史做摘要壓縮compact.ts而不是簡單砍掉前面的消息。你自己實現(xiàn)時可以先做一個簡化版保留 System Prompt 和最近 N 輪對話把更早的內(nèi)容用一次 LLM 調(diào)用總結(jié)成一段話。5.5 流式模式下工具調(diào)用解析失敗前面提過流式返回的tool_calls是分片的。delta.tool_calls[0].function.arguments每次只給你一小段 JSON 字符串需要按index累積拼接等流結(jié)束后再JSON.parse。直接對每個 chunk 解析會報Unexpected end of JSON input。5.6 記憶檢索返回空結(jié)果如果你接了記憶系統(tǒng)搜索時返回空先檢查三件事嵌入模型是否配置正確、SQLite 里chunks表是否有數(shù)據(jù)、查詢向量維度是否和存儲時一致。維度不一致是最隱蔽的坑比如存儲用 1536 維查詢用了 1024 維的模型相似度計算會直接失效。6. 把 Agent 跑起來之后下一步做什么到這里你已經(jīng)有了一個能跑的最小 Agent統(tǒng)一 Key 通道、可復(fù)制配置、工具循環(huán)、流式輸出、基礎(chǔ)排障。接下來按優(yōu)先級補三件事。第一是容錯。裸循環(huán)跑 demo 沒問題上線必須加 Auth Failover 和上下文壓縮。前者解決限流和 Key 過期后者解決長對話崩潰。這兩塊 OpenClaw 的run.ts和compact.ts都有現(xiàn)成思路可以抄。第二是記憶。讓 Agent 從「一次性對話」變成「持續(xù)助手」最小實現(xiàn)就是 SQLite 加向量檢索加 FTS5 全文兜底。嵌入模型選text-embedding-3-small就夠用便宜且穩(wěn)定?；旌蠙z索權(quán)重先用 0.7 向量加 0.3 BM25跑一段時間再調(diào)。第三是擴展。等你要接第二個通道、加第三個工具的時候再考慮插件化和 Hook 系統(tǒng)。不用一開始就做 25 個 Hook先從before_prompt_build和before_tool_call這兩個高頻的做起。如果你在接入過程中遇到通道或 Key 的問題可以直接去 API Keys 頁面重新生成一個驗證https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite想先驗證模型響應(yīng)是否符合預(yù)期可以用模型對話頁面快速試一條https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite如果你打算長期跑編碼類 Agent 或做多輪工具調(diào)用Coding Plan 會更省心額度和模型調(diào)度都幫你管好了https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入文檔在這里配置字段和錯誤碼都有說明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite我自己的習(xí)慣是每加一個新工具先用模型對話頁面手動構(gòu)造一次工具調(diào)用請求確認返回格式對了再寫進 Agent 代碼。這樣能把「模型問題」和「代碼問題」分開排障快很多。