度系統(tǒng)：OpenClaw架構(gòu)解析與實(shí)戰(zhàn))
1. 從零到一為什么我們需要一個(gè)純 TypeScript 的 Agent 調(diào)度系統(tǒng)最近在折騰 AI Agent 項(xiàng)目特別是想把一些想法落地成可用的服務(wù)時(shí)遇到了一個(gè)挺典型的問(wèn)題市面上現(xiàn)成的 Agent 框架要么太重像 LangChain為了通用性封裝了太多層調(diào)試起來(lái)像在走迷宮要么就是生態(tài)綁定太深比如一些框架強(qiáng)依賴特定的云服務(wù)或運(yùn)行時(shí)想在自己的服務(wù)器上跑或者想深度定制一下調(diào)度邏輯感覺處處掣肘。更別提那些用 Python 寫的框架雖然生態(tài)好但想在 Node.js 或?yàn)g覽器端復(fù)用核心邏輯基本就得重寫一遍。這時(shí)候一個(gè)叫 OpenClaw 的項(xiàng)目進(jìn)入了我的視野。它最吸引我的點(diǎn)就是標(biāo)題里寫的用純 TypeScript 造了一套 Agent 調(diào)度系統(tǒng)。這聽起來(lái)像是個(gè)“輪子”但在 AI 應(yīng)用開發(fā)尤其是 Agent 領(lǐng)域這個(gè)“輪子”可能恰恰是很多團(tuán)隊(duì)缺的那一個(gè)。TypeScript 意味著什么首先它是 JavaScript 的超集能編譯成純凈的 JS這帶來(lái)了無(wú)與倫比的運(yùn)行時(shí)靈活性。你的調(diào)度核心可以跑在 Node.js 服務(wù)器上可以跑在瀏覽器里甚至可以打包進(jìn) Electron 桌面應(yīng)用或者 React Native 移動(dòng)端。一次編寫多處部署這對(duì)于需要跨端能力的 AI 應(yīng)用來(lái)說(shuō)價(jià)值巨大。其次TypeScript 的靜態(tài)類型系統(tǒng)在構(gòu)建像“調(diào)度系統(tǒng)”這樣復(fù)雜的、狀態(tài)機(jī)式的邏輯時(shí)簡(jiǎn)直是救命稻草。Agent 的執(zhí)行流往往涉及多個(gè)步驟、條件分支、異步操作和共享狀態(tài)。用純 JS 寫很容易就變成“面條代碼”調(diào)試時(shí)一個(gè)變量的類型搞錯(cuò)可能就得花半天時(shí)間。TypeScript 能在編碼階段就幫你卡住很多低級(jí)錯(cuò)誤并且它的接口Interface和類型別名Type Alias非常適合用來(lái)定義 Agent 的“技能”Skill、工具Tool、以及執(zhí)行上下文Context的數(shù)據(jù)結(jié)構(gòu)讓整個(gè)系統(tǒng)的設(shè)計(jì)從一開始就清晰可控。OpenClaw 選擇純 TypeScript在我看來(lái)不是炫技而是針對(duì) Agent 開發(fā)中“快速迭代”和“可靠部署”這兩個(gè)核心痛點(diǎn)的務(wù)實(shí)選擇。它試圖提供一套輕量、類型安全、不綁定特定后端的調(diào)度內(nèi)核讓開發(fā)者能更專注于 Agent 本身的行為邏輯而不是陷在框架的復(fù)雜性里。接下來(lái)我們就深入這套系統(tǒng)的內(nèi)部看看它是如何被“造”出來(lái)的。2. 調(diào)度系統(tǒng)的核心架構(gòu)事件驅(qū)動(dòng)與工作流引擎OpenClaw 的調(diào)度系統(tǒng)其核心思想可以概括為“事件驅(qū)動(dòng)的工作流”。它沒(méi)有采用一些傳統(tǒng)后臺(tái)服務(wù)那種復(fù)雜的隊(duì)列和消費(fèi)者模型而是設(shè)計(jì)了一個(gè)更貼合 Agent 交互場(chǎng)景的輕量級(jí)中樞。整個(gè)架構(gòu)圍繞幾個(gè)關(guān)鍵概念展開理解了它們就理解了調(diào)度的脈絡(luò)。2.1 調(diào)度中樞SVR Operator 與事件總線在 OpenClaw 的代碼中你經(jīng)常會(huì)看到一個(gè)核心類比如叫SvrOperator。這個(gè) Operator 不是 Kubernetes 里那個(gè) Operator在這里你可以把它理解為“服務(wù)操作員”或“調(diào)度員”。它是整個(gè)調(diào)度系統(tǒng)的入口和總控。它的核心職責(zé)是接收外部的請(qǐng)求比如來(lái)自 HTTP API、WebSocket 消息、命令行指令這個(gè)請(qǐng)求通常包含了要執(zhí)行哪個(gè) Agent、以及初始的輸入?yún)?shù)。SvrOperator會(huì)將這些請(qǐng)求轉(zhuǎn)化成一個(gè)標(biāo)準(zhǔn)的內(nèi)部事件比如AgentExecutionRequestEvent然后拋給系統(tǒng)內(nèi)部的事件總線Event Bus。這里的事件總線是一個(gè)典型的發(fā)布-訂閱模式實(shí)現(xiàn)。為什么用事件驅(qū)動(dòng)因?yàn)?Agent 的執(zhí)行過(guò)程本質(zhì)上是異步的、離散的。一個(gè) Agent 執(zhí)行一個(gè)技能Skill可能需要調(diào)用語(yǔ)言模型LLM、查詢數(shù)據(jù)庫(kù)、執(zhí)行一段代碼每一步都可能成功或失敗都可能產(chǎn)生需要后續(xù)步驟處理的數(shù)據(jù)。用事件來(lái)串聯(lián)這些狀態(tài)變化比用一個(gè)大而全的同步函數(shù)調(diào)用鏈要清晰和靈活得多。每個(gè)模塊如技能執(zhí)行器、工具調(diào)用器、狀態(tài)管理器只監(jiān)聽自己關(guān)心的事件完成自己的工作后再發(fā)出新的事件從而驅(qū)動(dòng)流程向下進(jìn)行。這種松耦合的設(shè)計(jì)也使得擴(kuò)展新的技能或工具變得非常容易你只需要編寫一個(gè)新的監(jiān)聽器Listener并注冊(cè)到總線即可。一個(gè)常見的錯(cuò)誤提示比如openclaw llamap svr operator(): got exception: { error: { code: 400, me...往往就發(fā)生在SvrOperator處理請(qǐng)求的初始階段。這可能是請(qǐng)求格式不符合預(yù)期、必要的參數(shù)缺失、或者請(qǐng)求的 Agent 或 Skill 不存在。好的調(diào)度系統(tǒng)會(huì)在這一層就做好完備的請(qǐng)求驗(yàn)證和錯(cuò)誤格式化把問(wèn)題盡可能早地暴露出來(lái)而不是讓錯(cuò)誤滲透到后續(xù)復(fù)雜的執(zhí)行鏈路中。2.2. 工作流定義用 TypeScript 類型描述執(zhí)行藍(lán)圖Agent 不是一個(gè)黑盒函數(shù)它通常有一個(gè)預(yù)設(shè)的執(zhí)行流程也就是工作流Workflow。OpenClaw 如何定義這個(gè)流程它充分利用了 TypeScript 的類型能力。通常我們會(huì)用一個(gè) TypeScript 接口Interface或類型別名Type來(lái)定義一個(gè)工作流。這個(gè)類型可能長(zhǎng)這樣interface AgentWorkflow { id: string; entrySkill: string; // 入口技能如 “analyze_user_query” skills: { [skillName: string]: { execute: (context: WorkflowContext) PromiseSkillResult; next?: string | ((result: SkillResult) string); // 下一個(gè)技能名或根據(jù)結(jié)果決定的函數(shù) onError?: string; // 出錯(cuò)時(shí)跳轉(zhuǎn)到哪個(gè)技能如 “handle_error” }; }; }這里WorkflowContext是一個(gè)貫穿整個(gè)工作流執(zhí)行過(guò)程的上下文對(duì)象它用 TypeScript 嚴(yán)格定義了在每個(gè)階段可以存取的數(shù)據(jù)結(jié)構(gòu)。比如interface WorkflowContext { sessionId: string; userInput: string; llmResponse?: string; extractedData?: Recordstring, any; error?: Error; // ... 其他自定義字段 }通過(guò)類型定義我們?cè)诰幋a時(shí)就能清晰地知道在執(zhí)行“分析用戶查詢”這個(gè)技能后context.llmResponse字段會(huì)被填充在執(zhí)行“數(shù)據(jù)提取”技能時(shí)我們可以安全地讀取llmResponse并期望它是字符串類型。這種編譯時(shí)的安全保障是純 JavaScript 項(xiàng)目難以企及的。工作流引擎的職責(zé)就是根據(jù)這個(gè)藍(lán)圖監(jiān)聽技能執(zhí)行完成的事件然后查找next規(guī)則決定下一個(gè)要執(zhí)行的技能并再次派發(fā)事件。它可能還需要處理循環(huán)、條件分支比如根據(jù)結(jié)果決定走 A 路徑還是 B 路徑、以及并行執(zhí)行等復(fù)雜邏輯。OpenClaw 的實(shí)現(xiàn)通常會(huì)有一個(gè)WorkflowExecutor類它內(nèi)部維護(hù)著當(dāng)前執(zhí)行到了哪個(gè)技能、上下文狀態(tài)是什么并作為事件總線的一個(gè)主要監(jiān)聽者和驅(qū)動(dòng)者。2.3. 技能Skill與工具Tool的注冊(cè)與發(fā)現(xiàn)技能是 Agent 能力的原子單位。一個(gè)“總結(jié)文檔”的技能內(nèi)部可能調(diào)用了“調(diào)用 LLM API”和“解析 Markdown”兩個(gè)工具。OpenClaw 需要一套機(jī)制來(lái)管理這些技能和工具。通常會(huì)有一個(gè)全局的注冊(cè)中心Registry。在系統(tǒng)初始化時(shí)所有定義好的技能和工具模塊會(huì)向這個(gè)注冊(cè)中心“報(bào)到”登記自己的名字、描述、輸入輸出參數(shù)類型等信息。這個(gè)注冊(cè)過(guò)程同樣可以借助 TypeScript 的裝飾器Decorator來(lái)實(shí)現(xiàn)讓代碼看起來(lái)非常清晰Skill({ name: summarize_document, description: 總結(jié)一篇長(zhǎng)文檔的核心內(nèi)容 }) export class SummarizeDocumentSkill implements ISkill { async execute(context: WorkflowContext): PromiseSkillResult { // 1. 從 context 中獲取文檔內(nèi)容 const doc context.documentContent; // 2. 調(diào)用 LLM 工具 const llmResult await ToolRegistry.getTool(call_llm).invoke({ model: gpt-4, prompt: 請(qǐng)總結(jié)以下文檔\n${doc} }); // 3. 將結(jié)果存入 context context.summary llmResult.content; return { success: true, output: context.summary }; } }工具Tool的注冊(cè)也類似它們更像是底層的、可復(fù)用的功能函數(shù)比如 HTTP 請(qǐng)求、數(shù)據(jù)庫(kù)查詢、代碼執(zhí)行等。調(diào)度系統(tǒng)在需要調(diào)用工具時(shí)不會(huì)硬編碼而是通過(guò)注冊(cè)中心按名查找這實(shí)現(xiàn)了徹底的解耦。當(dāng)你需要新增一個(gè)工具時(shí)只需要編寫實(shí)現(xiàn)類并注冊(cè)所有技能都能立即使用它無(wú)需修改調(diào)度核心代碼。這種基于注冊(cè)的模式也使得 OpenClaw 能夠?qū)崿F(xiàn)類似“技能市場(chǎng)”或動(dòng)態(tài)加載的功能。理論上你可以從遠(yuǎn)程加載一個(gè)符合接口規(guī)范的技能模塊在運(yùn)行時(shí)注冊(cè)進(jìn)去Agent 就立刻獲得了新能力。3. 狀態(tài)管理、持久化與容錯(cuò)機(jī)制一個(gè)健壯的調(diào)度系統(tǒng)不能是“一錘子買賣”。Agent 與用戶的對(duì)話可能是多輪的一個(gè)復(fù)雜任務(wù)可能被中斷后需要恢復(fù)。因此OpenClaw 必須考慮狀態(tài)管理和持久化。3.1. 會(huì)話狀態(tài)與上下文持久化每一次用戶與 Agent 的交互通常會(huì)被關(guān)聯(lián)到一個(gè)唯一的會(huì)話 IDSession ID。WorkflowContext對(duì)象就是這個(gè)會(huì)話在內(nèi)存中的實(shí)時(shí)狀態(tài)。但是內(nèi)存狀態(tài)是脆弱的服務(wù)重啟就沒(méi)了。所以調(diào)度系統(tǒng)需要將關(guān)鍵的上下文狀態(tài)持久化到外部存儲(chǔ)比如 Redis、數(shù)據(jù)庫(kù)或文件系統(tǒng)。OpenClaw 的做法通常是在工作流引擎的某些關(guān)鍵節(jié)點(diǎn)例如一個(gè)技能執(zhí)行完成后、或等待外部輸入時(shí)觸發(fā)持久化操作。它不會(huì)每次都全量保存而是可能采用快照Snapshot機(jī)制。定義一個(gè)ContextPersistenceService其接口可能是interface IContextPersistenceService { save(sessionId: string, contextSnapshot: PartialWorkflowContext): Promisevoid; load(sessionId: string): PromiseWorkflowContext | null; }在持久化時(shí)一個(gè)重要的細(xì)節(jié)是序列化。WorkflowContext里可能包含復(fù)雜的對(duì)象、甚至函數(shù)雖然不推薦。純 TypeScript/JavaScript 環(huán)境里直接用JSON.stringify可能會(huì)丟失信息如 Date 對(duì)象變成字符串undefined 字段被忽略。因此OpenClaw 可能需要引入一個(gè)序列化庫(kù)或者自定義一套序列化規(guī)則確保上下文恢復(fù)后類型和結(jié)構(gòu)依然正確。3.2. 錯(cuò)誤處理與重試邏輯在熱詞里我們看到openclaw llamap svr operator(): got exception錯(cuò)誤處理是調(diào)度系統(tǒng)必須精心設(shè)計(jì)的部分。錯(cuò)誤可能發(fā)生在各個(gè)層面技能執(zhí)行錯(cuò)誤比如調(diào)用 LLM API 超時(shí)、返回格式異常。工具調(diào)用錯(cuò)誤比如數(shù)據(jù)庫(kù)連接失敗、第三方服務(wù)不可用。工作流邏輯錯(cuò)誤比如next指向了一個(gè)不存在的技能。OpenClaw 的調(diào)度系統(tǒng)需要有一個(gè)統(tǒng)一的錯(cuò)誤捕獲和分發(fā)機(jī)制。事件總線在這里再次發(fā)揮作用。任何一個(gè)技能或工具在執(zhí)行中拋出的異常不應(yīng)該直接導(dǎo)致整個(gè)進(jìn)程崩潰而應(yīng)該被包裝成一個(gè)AgentExecutionErrorEvent事件。工作流引擎監(jiān)聽到這個(gè)錯(cuò)誤事件后會(huì)根據(jù)當(dāng)前技能定義中的onError字段決定錯(cuò)誤處理路徑。例如可以跳轉(zhuǎn)到一個(gè)專門的“錯(cuò)誤處理”技能這個(gè)技能可能會(huì)嘗試重試原操作對(duì)于網(wǎng)絡(luò)波動(dòng)錯(cuò)誤、或者向用戶發(fā)送友好的錯(cuò)誤信息、亦或是將任務(wù)標(biāo)記為失敗并通知管理員。對(duì)于可重試的錯(cuò)誤如網(wǎng)絡(luò)超時(shí)調(diào)度系統(tǒng)可以實(shí)現(xiàn)一個(gè)簡(jiǎn)單的重試機(jī)制。但這需要謹(jǐn)慎對(duì)于非冪等的操作如創(chuàng)建訂單盲目重試會(huì)導(dǎo)致嚴(yán)重問(wèn)題。因此重試邏輯最好與具體技能/工具綁定由開發(fā)者根據(jù)業(yè)務(wù)語(yǔ)義來(lái)決定調(diào)度系統(tǒng)只提供重試的基礎(chǔ)設(shè)施比如一個(gè)Retry(maxAttempts: 3)的裝飾器。3.3. 超時(shí)控制與資源隔離Agent 任務(wù)可能陷入死循環(huán)或者某個(gè)外部調(diào)用永遠(yuǎn)不返回。調(diào)度系統(tǒng)必須有能力強(qiáng)制終止長(zhǎng)時(shí)間運(yùn)行的任務(wù)。這可以通過(guò)為每個(gè)工作流的執(zhí)行設(shè)置一個(gè)全局超時(shí)或者為每個(gè)技能設(shè)置單獨(dú)的超時(shí)來(lái)實(shí)現(xiàn)。在實(shí)現(xiàn)上可以利用 JavaScript 的Promise.race或AbortController。當(dāng)啟動(dòng)一個(gè)技能執(zhí)行時(shí)同時(shí)啟動(dòng)一個(gè)定時(shí)器。如果技能在超時(shí)前完成則取消定時(shí)器如果定時(shí)器先觸發(fā)則向技能執(zhí)行發(fā)送中止信號(hào)并拋出超時(shí)錯(cuò)誤事件。async executeSkillWithTimeout(skill: ISkill, context: WorkflowContext, timeoutMs: number): PromiseSkillResult { const abortController new AbortController(); const timeoutId setTimeout(() abortController.abort(), timeoutMs); try { // 將 abortController.signal 傳遞給技能技能內(nèi)部需要支持中止 const result await skill.execute(context, abortController.signal); clearTimeout(timeoutId); return result; } catch (error) { clearTimeout(timeoutId); if (error.name AbortError) { throw new AgentExecutionError(Skill execution timeout, TIMEOUT); } throw error; } }資源隔離則更為復(fù)雜。在 Node.js 環(huán)境下多個(gè) Agent 會(huì)話共享同一個(gè)進(jìn)程內(nèi)存。如果一個(gè)技能有內(nèi)存泄漏或者某個(gè)任務(wù)消耗了巨量 CPU可能會(huì)影響其他任務(wù)。OpenClaw 作為輕量級(jí)調(diào)度系統(tǒng)可能不會(huì)實(shí)現(xiàn)完整的沙箱隔離但可以通過(guò)一些模式來(lái)緩解比如限制單個(gè)技能的執(zhí)行時(shí)間超時(shí)控制、監(jiān)控進(jìn)程內(nèi)存使用并在超過(guò)閾值時(shí)報(bào)警或重啟、以及最重要的——在技能開發(fā)規(guī)范中強(qiáng)調(diào)資源清理如關(guān)閉數(shù)據(jù)庫(kù)連接、清理臨時(shí)文件。4. 實(shí)戰(zhàn)從零配置一個(gè) OpenClaw Agent 并集成大模型理論說(shuō)了這么多我們動(dòng)手配置一個(gè)最簡(jiǎn)單的 OpenClaw Agent并讓它接入一個(gè)大模型比如通過(guò) Ollama 本地運(yùn)行的 Llama 3來(lái)直觀感受一下這套調(diào)度系統(tǒng)是如何運(yùn)作的。這里假設(shè)你已經(jīng)按照一些教程如“ubuntu極速部署openclaw完全指南”完成了基礎(chǔ)環(huán)境的搭建。4.1. 項(xiàng)目初始化與核心依賴安裝首先創(chuàng)建一個(gè)新的 TypeScript 項(xiàng)目并安裝 OpenClaw 的核心包這里假設(shè)包名為openclaw/core具體名稱需查閱官方文檔。mkdir my-openclaw-agent cd my-openclaw-agent npm init -y npm install typescript ts-node types/node --save-dev npm install openclaw/core --save接著初始化 TypeScript 配置。注意熱詞中的警告選項(xiàng)“baseurl”已棄用,并將停止在 typescript 7.0 中運(yùn)行。指定 compileroption。這是 TypeScript 配置的更新。在你的tsconfig.json中避免使用已棄用的baseUrl而是使用compilerOptions下的paths等新方式進(jìn)行路徑映射。{ compilerOptions: { target: ES2020, module: commonjs, lib: [ES2020], outDir: ./dist, rootDir: ./src, strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true, resolveJsonModule: true, // 使用 paths 替代已棄用的 baseUrl paths: { /*: [./src/*] } }, include: [src/**/*], exclude: [node_modules] }4.2. 定義第一個(gè)技能與工具調(diào)用本地 LLM我們創(chuàng)建一個(gè)簡(jiǎn)單的“問(wèn)答”技能它調(diào)用本地的 Ollama 服務(wù)。首先定義一個(gè)調(diào)用 LLM 的工具。在src/tools/llm-tool.ts中import { Tool, ITool, ToolContext } from openclaw/core; export interface LLMCallParams { model: string; prompt: string; systemPrompt?: string; } export interface LLMCallResult { content: string; model: string; usage?: { prompt_tokens: number; completion_tokens: number }; } // 使用裝飾器注冊(cè)工具 Tool({ name: call_ollama_llm, description: 調(diào)用本地 Ollama 服務(wù)的 LLM 模型, inputSchema: { /* 可以用 JSON Schema 定義參數(shù)結(jié)構(gòu) */ } }) export class OllamaLLMTool implements IToolLLMCallParams, LLMCallResult { private ollamaBaseUrl: string; constructor(baseUrl: string http://localhost:11434) { this.ollamaBaseUrl baseUrl; } async invoke(params: LLMCallParams, context?: ToolContext): PromiseLLMCallResult { const response await fetch(${this.ollamaBaseUrl}/api/generate, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ model: params.model, prompt: params.prompt, system: params.systemPrompt, stream: false // 簡(jiǎn)單起見關(guān)閉流式 }) }); if (!response.ok) { const errorBody await response.text(); throw new Error(Ollama API call failed: ${response.status} ${errorBody}); } const data await response.json(); return { content: data.response, model: data.model, usage: { prompt_tokens: 0, completion_tokens: 0 } // Ollama 可能不返回這里示意 }; } }接著在src/skills/qa-skill.ts中定義技能import { Skill, ISkill, SkillResult, WorkflowContext } from openclaw/core; import { OllamaLLMTool, LLMCallParams } from ../tools/llm-tool; Skill({ name: answer_question, description: 根據(jù)用戶問(wèn)題調(diào)用 LLM 生成回答 }) export class QASkill implements ISkill { private llmTool: OllamaLLMTool; constructor() { this.llmTool new OllamaLLMTool(); } async execute(context: WorkflowContext): PromiseSkillResult { // 從上下文中取出用戶問(wèn)題 const userQuestion context.userInput; if (!userQuestion) { return { success: false, error: 用戶輸入為空 }; } try { const llmParams: LLMCallParams { model: llama3, // 假設(shè)本地已拉取 llama3 模型 prompt: 請(qǐng)回答以下問(wèn)題${userQuestion}, systemPrompt: 你是一個(gè)樂(lè)于助人的AI助手。 }; const result await this.llmTool.invoke(llmParams); // 將回答存入上下文供后續(xù)技能或輸出使用 context.llmAnswer result.content; return { success: true, output: result.content }; } catch (error) { // 錯(cuò)誤處理記錄日志并返回失敗結(jié)果 console.error(QASkill 執(zhí)行失敗:, error); context.lastError error.message; return { success: false, error: 獲取答案失敗: ${error.message} }; } } }4.3. 組裝 Agent 與啟動(dòng)調(diào)度服務(wù)現(xiàn)在我們需要?jiǎng)?chuàng)建一個(gè) Agent將技能組裝起來(lái)并啟動(dòng)調(diào)度服務(wù)。在src/agent/simple-qa-agent.ts中import { Agent, IAgent, Workflow, SvrOperator } from openclaw/core; import { QASkill } from ../skills/qa-skill; // 1. 定義工作流 const qaWorkflow: Workflow { id: simple_qa_workflow, entrySkill: answer_question, skills: { answer_question: { execute: async (context) { const skill new QASkill(); return await skill.execute(context); }, // 執(zhí)行完就結(jié)束沒(méi)有下一個(gè)技能 next: null } } }; // 2. 創(chuàng)建 Agent export class SimpleQAAgent implements IAgent { name Simple QA Agent; workflow qaWorkflow; async onStartup() { console.log(Agent ${this.name} 已初始化。); } async onShutdown() { console.log(Agent ${this.name} 已關(guān)閉。); } }最后在src/index.ts中創(chuàng)建服務(wù)入口import { SvrOperator } from openclaw/core; import { SimpleQAAgent } from ./agent/simple-qa-agent; async function main() { // 1. 初始化調(diào)度操作員 const operator new SvrOperator(); // 2. 創(chuàng)建并注冊(cè)我們的 Agent const myAgent new SimpleQAAgent(); operator.registerAgent(myAgent); // 3. 啟動(dòng) HTTP 服務(wù)器或其它傳輸層等待請(qǐng)求 // 這里以簡(jiǎn)單的 HTTP 服務(wù)器為例 const http require(http); const server http.createServer(async (req, res) { if (req.method POST req.url /ask) { let body ; req.on(data, chunk body chunk); req.on(end, async () { try { const { question, sessionId sess_${Date.now()} } JSON.parse(body); // 構(gòu)造執(zhí)行上下文 const initialContext { userInput: question, sessionId }; // 通過(guò)調(diào)度操作員執(zhí)行 Agent const result await operator.executeAgent(Simple QA Agent, initialContext); res.writeHead(200, { Content-Type: application/json }); res.end(JSON.stringify({ answer: result.output, success: result.success })); } catch (error) { console.error(請(qǐng)求處理錯(cuò)誤:, error); res.writeHead(500, { Content-Type: application/json }); res.end(JSON.stringify({ error: Internal Server Error, details: error.message })); } }); } else { res.writeHead(404).end(); } }); server.listen(3000, () { console.log(OpenClaw Agent 調(diào)度服務(wù)已啟動(dòng)監(jiān)聽端口 3000); console.log(嘗試發(fā)送 POST 請(qǐng)求到 http://localhost:3000/ask 并攜帶 JSON 體: {question: 你的問(wèn)題}); }); } main().catch(console.error);運(yùn)行npx ts-node src/index.ts你的純 TypeScript Agent 調(diào)度服務(wù)就跑起來(lái)了。你可以用 curl 或 Postman 測(cè)試它。這個(gè)簡(jiǎn)單的例子串聯(lián)了從 HTTP 請(qǐng)求進(jìn)入SvrOperator到觸發(fā)工作流執(zhí)行技能調(diào)用工具最后返回結(jié)果的完整調(diào)度鏈條。4.4. 配置多模型與技能擴(kuò)展熱詞中提到“本地openclaw如何添加多個(gè)大模型”。在我們的架構(gòu)里這非常直觀。你不需要修改調(diào)度核心只需擴(kuò)展工具層。創(chuàng)建新的 LLM 工具類比如OpenAITool、AzureOpenAITool實(shí)現(xiàn)相同的ITool接口但內(nèi)部調(diào)用不同的 API。在技能中動(dòng)態(tài)選擇模型可以通過(guò)上下文中的某個(gè)配置字段來(lái)決定使用哪個(gè)工具。例如修改QASkill的execute方法async execute(context: WorkflowContext): PromiseSkillResult { const modelProvider context.modelProvider || ollama; // 默認(rèn)為 ollama let llmTool: ITool; if (modelProvider openai) { llmTool new OpenAITool(process.env.OPENAI_API_KEY); } else { llmTool new OllamaLLMTool(); } // ... 后續(xù)調(diào)用邏輯不變 }通過(guò)注冊(cè)中心更優(yōu)雅地管理更高級(jí)的做法是將所有 LLM 工具都注冊(cè)到全局工具注冊(cè)中心技能只需要根據(jù)名稱來(lái)獲取工具。這樣新增模型提供商時(shí)只需要編寫并注冊(cè)新工具所有技能自動(dòng)獲得支持。技能擴(kuò)展同理。如果你想增加一個(gè)“聯(lián)網(wǎng)搜索”后再回答的技能只需定義一個(gè)新的WebSearchSkill然后在工作流定義中將answer_question技能的next指向它或者在answer_question之前插入它。工作流引擎會(huì)自動(dòng)按照新的藍(lán)圖來(lái)調(diào)度執(zhí)行順序。通過(guò)這個(gè)實(shí)戰(zhàn)流程你可以看到 OpenClaw 這類純 TypeScript 調(diào)度系統(tǒng)的靈活性。它的核心價(jià)值不在于提供了多少預(yù)置的 AI 能力而在于提供了一套類型安全、松耦合、可擴(kuò)展的框架讓你能像搭積木一樣快速構(gòu)建和迭代屬于自己的 AI Agent 應(yīng)用。從簡(jiǎn)單的問(wèn)答到復(fù)雜的多步驟工作流如分析需求 - 搜索信息 - 生成報(bào)告 - 發(fā)送郵件這套調(diào)度系統(tǒng)都能提供清晰、可靠的控制骨架。 基于TypeScript的AI Agent調(diào)度系統(tǒng)：OpenClaw架構(gòu)解析與實(shí)戰(zhàn)
1. 從零到一為什么我們需要一個(gè)純 TypeScript 的 Agent 調(diào)度系統(tǒng)最近在折騰 AI Agent 項(xiàng)目特別是想把一些想法落地成可用的服務(wù)時(shí)遇到了一個(gè)挺典型的問(wèn)題市面上現(xiàn)成的 Agent 框架要么太重像 LangChain為了通用性封裝了太多層調(diào)試起來(lái)像在走迷宮要么就是生態(tài)綁定太深比如一些框架強(qiáng)依賴特定的云服務(wù)或運(yùn)行時(shí)想在自己的服務(wù)器上跑或者想深度定制一下調(diào)度邏輯感覺處處掣肘。更別提那些用 Python 寫的框架雖然生態(tài)好但想在 Node.js 或?yàn)g覽器端復(fù)用核心邏輯基本就得重寫一遍。這時(shí)候一個(gè)叫 OpenClaw 的項(xiàng)目進(jìn)入了我的視野。它最吸引我的點(diǎn)就是標(biāo)題里寫的用純 TypeScript 造了一套 Agent 調(diào)度系統(tǒng)。這聽起來(lái)像是個(gè)“輪子”但在 AI 應(yīng)用開發(fā)尤其是 Agent 領(lǐng)域這個(gè)“輪子”可能恰恰是很多團(tuán)隊(duì)缺的那一個(gè)。TypeScript 意味著什么首先它是 JavaScript 的超集能編譯成純凈的 JS這帶來(lái)了無(wú)與倫比的運(yùn)行時(shí)靈活性。你的調(diào)度核心可以跑在 Node.js 服務(wù)器上可以跑在瀏覽器里甚至可以打包進(jìn) Electron 桌面應(yīng)用或者 React Native 移動(dòng)端。一次編寫多處部署這對(duì)于需要跨端能力的 AI 應(yīng)用來(lái)說(shuō)價(jià)值巨大。其次TypeScript 的靜態(tài)類型系統(tǒng)在構(gòu)建像“調(diào)度系統(tǒng)”這樣復(fù)雜的、狀態(tài)機(jī)式的邏輯時(shí)簡(jiǎn)直是救命稻草。Agent 的執(zhí)行流往往涉及多個(gè)步驟、條件分支、異步操作和共享狀態(tài)。用純 JS 寫很容易就變成“面條代碼”調(diào)試時(shí)一個(gè)變量的類型搞錯(cuò)可能就得花半天時(shí)間。TypeScript 能在編碼階段就幫你卡住很多低級(jí)錯(cuò)誤并且它的接口Interface和類型別名Type Alias非常適合用來(lái)定義 Agent 的“技能”Skill、工具Tool、以及執(zhí)行上下文Context的數(shù)據(jù)結(jié)構(gòu)讓整個(gè)系統(tǒng)的設(shè)計(jì)從一開始就清晰可控。OpenClaw 選擇純 TypeScript在我看來(lái)不是炫技而是針對(duì) Agent 開發(fā)中“快速迭代”和“可靠部署”這兩個(gè)核心痛點(diǎn)的務(wù)實(shí)選擇。它試圖提供一套輕量、類型安全、不綁定特定后端的調(diào)度內(nèi)核讓開發(fā)者能更專注于 Agent 本身的行為邏輯而不是陷在框架的復(fù)雜性里。接下來(lái)我們就深入這套系統(tǒng)的內(nèi)部看看它是如何被“造”出來(lái)的。2. 調(diào)度系統(tǒng)的核心架構(gòu)事件驅(qū)動(dòng)與工作流引擎OpenClaw 的調(diào)度系統(tǒng)其核心思想可以概括為“事件驅(qū)動(dòng)的工作流”。它沒(méi)有采用一些傳統(tǒng)后臺(tái)服務(wù)那種復(fù)雜的隊(duì)列和消費(fèi)者模型而是設(shè)計(jì)了一個(gè)更貼合 Agent 交互場(chǎng)景的輕量級(jí)中樞。整個(gè)架構(gòu)圍繞幾個(gè)關(guān)鍵概念展開理解了它們就理解了調(diào)度的脈絡(luò)。2.1 調(diào)度中樞SVR Operator 與事件總線在 OpenClaw 的代碼中你經(jīng)常會(huì)看到一個(gè)核心類比如叫SvrOperator。這個(gè) Operator 不是 Kubernetes 里那個(gè) Operator在這里你可以把它理解為“服務(wù)操作員”或“調(diào)度員”。它是整個(gè)調(diào)度系統(tǒng)的入口和總控。它的核心職責(zé)是接收外部的請(qǐng)求比如來(lái)自 HTTP API、WebSocket 消息、命令行指令這個(gè)請(qǐng)求通常包含了要執(zhí)行哪個(gè) Agent、以及初始的輸入?yún)?shù)。SvrOperator會(huì)將這些請(qǐng)求轉(zhuǎn)化成一個(gè)標(biāo)準(zhǔn)的內(nèi)部事件比如AgentExecutionRequestEvent然后拋給系統(tǒng)內(nèi)部的事件總線Event Bus。這里的事件總線是一個(gè)典型的發(fā)布-訂閱模式實(shí)現(xiàn)。為什么用事件驅(qū)動(dòng)因?yàn)?Agent 的執(zhí)行過(guò)程本質(zhì)上是異步的、離散的。一個(gè) Agent 執(zhí)行一個(gè)技能Skill可能需要調(diào)用語(yǔ)言模型LLM、查詢數(shù)據(jù)庫(kù)、執(zhí)行一段代碼每一步都可能成功或失敗都可能產(chǎn)生需要后續(xù)步驟處理的數(shù)據(jù)。用事件來(lái)串聯(lián)這些狀態(tài)變化比用一個(gè)大而全的同步函數(shù)調(diào)用鏈要清晰和靈活得多。每個(gè)模塊如技能執(zhí)行器、工具調(diào)用器、狀態(tài)管理器只監(jiān)聽自己關(guān)心的事件完成自己的工作后再發(fā)出新的事件從而驅(qū)動(dòng)流程向下進(jìn)行。這種松耦合的設(shè)計(jì)也使得擴(kuò)展新的技能或工具變得非常容易你只需要編寫一個(gè)新的監(jiān)聽器Listener并注冊(cè)到總線即可。一個(gè)常見的錯(cuò)誤提示比如openclaw llamap svr operator(): got exception: { error: { code: 400, me...往往就發(fā)生在SvrOperator處理請(qǐng)求的初始階段。這可能是請(qǐng)求格式不符合預(yù)期、必要的參數(shù)缺失、或者請(qǐng)求的 Agent 或 Skill 不存在。好的調(diào)度系統(tǒng)會(huì)在這一層就做好完備的請(qǐng)求驗(yàn)證和錯(cuò)誤格式化把問(wèn)題盡可能早地暴露出來(lái)而不是讓錯(cuò)誤滲透到后續(xù)復(fù)雜的執(zhí)行鏈路中。2.2. 工作流定義用 TypeScript 類型描述執(zhí)行藍(lán)圖Agent 不是一個(gè)黑盒函數(shù)它通常有一個(gè)預(yù)設(shè)的執(zhí)行流程也就是工作流Workflow。OpenClaw 如何定義這個(gè)流程它充分利用了 TypeScript 的類型能力。通常我們會(huì)用一個(gè) TypeScript 接口Interface或類型別名Type來(lái)定義一個(gè)工作流。這個(gè)類型可能長(zhǎng)這樣interface AgentWorkflow { id: string; entrySkill: string; // 入口技能如 “analyze_user_query” skills: { [skillName: string]: { execute: (context: WorkflowContext) PromiseSkillResult; next?: string | ((result: SkillResult) string); // 下一個(gè)技能名或根據(jù)結(jié)果決定的函數(shù) onError?: string; // 出錯(cuò)時(shí)跳轉(zhuǎn)到哪個(gè)技能如 “handle_error” }; }; }這里WorkflowContext是一個(gè)貫穿整個(gè)工作流執(zhí)行過(guò)程的上下文對(duì)象它用 TypeScript 嚴(yán)格定義了在每個(gè)階段可以存取的數(shù)據(jù)結(jié)構(gòu)。比如interface WorkflowContext { sessionId: string; userInput: string; llmResponse?: string; extractedData?: Recordstring, any; error?: Error; // ... 其他自定義字段 }通過(guò)類型定義我們?cè)诰幋a時(shí)就能清晰地知道在執(zhí)行“分析用戶查詢”這個(gè)技能后context.llmResponse字段會(huì)被填充在執(zhí)行“數(shù)據(jù)提取”技能時(shí)我們可以安全地讀取llmResponse并期望它是字符串類型。這種編譯時(shí)的安全保障是純 JavaScript 項(xiàng)目難以企及的。工作流引擎的職責(zé)就是根據(jù)這個(gè)藍(lán)圖監(jiān)聽技能執(zhí)行完成的事件然后查找next規(guī)則決定下一個(gè)要執(zhí)行的技能并再次派發(fā)事件。它可能還需要處理循環(huán)、條件分支比如根據(jù)結(jié)果決定走 A 路徑還是 B 路徑、以及并行執(zhí)行等復(fù)雜邏輯。OpenClaw 的實(shí)現(xiàn)通常會(huì)有一個(gè)WorkflowExecutor類它內(nèi)部維護(hù)著當(dāng)前執(zhí)行到了哪個(gè)技能、上下文狀態(tài)是什么并作為事件總線的一個(gè)主要監(jiān)聽者和驅(qū)動(dòng)者。2.3. 技能Skill與工具Tool的注冊(cè)與發(fā)現(xiàn)技能是 Agent 能力的原子單位。一個(gè)“總結(jié)文檔”的技能內(nèi)部可能調(diào)用了“調(diào)用 LLM API”和“解析 Markdown”兩個(gè)工具。OpenClaw 需要一套機(jī)制來(lái)管理這些技能和工具。通常會(huì)有一個(gè)全局的注冊(cè)中心Registry。在系統(tǒng)初始化時(shí)所有定義好的技能和工具模塊會(huì)向這個(gè)注冊(cè)中心“報(bào)到”登記自己的名字、描述、輸入輸出參數(shù)類型等信息。這個(gè)注冊(cè)過(guò)程同樣可以借助 TypeScript 的裝飾器Decorator來(lái)實(shí)現(xiàn)讓代碼看起來(lái)非常清晰Skill({ name: summarize_document, description: 總結(jié)一篇長(zhǎng)文檔的核心內(nèi)容 }) export class SummarizeDocumentSkill implements ISkill { async execute(context: WorkflowContext): PromiseSkillResult { // 1. 從 context 中獲取文檔內(nèi)容 const doc context.documentContent; // 2. 調(diào)用 LLM 工具 const llmResult await ToolRegistry.getTool(call_llm).invoke({ model: gpt-4, prompt: 請(qǐng)總結(jié)以下文檔\n${doc} }); // 3. 將結(jié)果存入 context context.summary llmResult.content; return { success: true, output: context.summary }; } }工具Tool的注冊(cè)也類似它們更像是底層的、可復(fù)用的功能函數(shù)比如 HTTP 請(qǐng)求、數(shù)據(jù)庫(kù)查詢、代碼執(zhí)行等。調(diào)度系統(tǒng)在需要調(diào)用工具時(shí)不會(huì)硬編碼而是通過(guò)注冊(cè)中心按名查找這實(shí)現(xiàn)了徹底的解耦。當(dāng)你需要新增一個(gè)工具時(shí)只需要編寫實(shí)現(xiàn)類并注冊(cè)所有技能都能立即使用它無(wú)需修改調(diào)度核心代碼。這種基于注冊(cè)的模式也使得 OpenClaw 能夠?qū)崿F(xiàn)類似“技能市場(chǎng)”或動(dòng)態(tài)加載的功能。理論上你可以從遠(yuǎn)程加載一個(gè)符合接口規(guī)范的技能模塊在運(yùn)行時(shí)注冊(cè)進(jìn)去Agent 就立刻獲得了新能力。3. 狀態(tài)管理、持久化與容錯(cuò)機(jī)制一個(gè)健壯的調(diào)度系統(tǒng)不能是“一錘子買賣”。Agent 與用戶的對(duì)話可能是多輪的一個(gè)復(fù)雜任務(wù)可能被中斷后需要恢復(fù)。因此OpenClaw 必須考慮狀態(tài)管理和持久化。3.1. 會(huì)話狀態(tài)與上下文持久化每一次用戶與 Agent 的交互通常會(huì)被關(guān)聯(lián)到一個(gè)唯一的會(huì)話 IDSession ID。WorkflowContext對(duì)象就是這個(gè)會(huì)話在內(nèi)存中的實(shí)時(shí)狀態(tài)。但是內(nèi)存狀態(tài)是脆弱的服務(wù)重啟就沒(méi)了。所以調(diào)度系統(tǒng)需要將關(guān)鍵的上下文狀態(tài)持久化到外部存儲(chǔ)比如 Redis、數(shù)據(jù)庫(kù)或文件系統(tǒng)。OpenClaw 的做法通常是在工作流引擎的某些關(guān)鍵節(jié)點(diǎn)例如一個(gè)技能執(zhí)行完成后、或等待外部輸入時(shí)觸發(fā)持久化操作。它不會(huì)每次都全量保存而是可能采用快照Snapshot機(jī)制。定義一個(gè)ContextPersistenceService其接口可能是interface IContextPersistenceService { save(sessionId: string, contextSnapshot: PartialWorkflowContext): Promisevoid; load(sessionId: string): PromiseWorkflowContext | null; }在持久化時(shí)一個(gè)重要的細(xì)節(jié)是序列化。WorkflowContext里可能包含復(fù)雜的對(duì)象、甚至函數(shù)雖然不推薦。純 TypeScript/JavaScript 環(huán)境里直接用JSON.stringify可能會(huì)丟失信息如 Date 對(duì)象變成字符串undefined 字段被忽略。因此OpenClaw 可能需要引入一個(gè)序列化庫(kù)或者自定義一套序列化規(guī)則確保上下文恢復(fù)后類型和結(jié)構(gòu)依然正確。3.2. 錯(cuò)誤處理與重試邏輯在熱詞里我們看到openclaw llamap svr operator(): got exception錯(cuò)誤處理是調(diào)度系統(tǒng)必須精心設(shè)計(jì)的部分。錯(cuò)誤可能發(fā)生在各個(gè)層面技能執(zhí)行錯(cuò)誤比如調(diào)用 LLM API 超時(shí)、返回格式異常。工具調(diào)用錯(cuò)誤比如數(shù)據(jù)庫(kù)連接失敗、第三方服務(wù)不可用。工作流邏輯錯(cuò)誤比如next指向了一個(gè)不存在的技能。OpenClaw 的調(diào)度系統(tǒng)需要有一個(gè)統(tǒng)一的錯(cuò)誤捕獲和分發(fā)機(jī)制。事件總線在這里再次發(fā)揮作用。任何一個(gè)技能或工具在執(zhí)行中拋出的異常不應(yīng)該直接導(dǎo)致整個(gè)進(jìn)程崩潰而應(yīng)該被包裝成一個(gè)AgentExecutionErrorEvent事件。工作流引擎監(jiān)聽到這個(gè)錯(cuò)誤事件后會(huì)根據(jù)當(dāng)前技能定義中的onError字段決定錯(cuò)誤處理路徑。例如可以跳轉(zhuǎn)到一個(gè)專門的“錯(cuò)誤處理”技能這個(gè)技能可能會(huì)嘗試重試原操作對(duì)于網(wǎng)絡(luò)波動(dòng)錯(cuò)誤、或者向用戶發(fā)送友好的錯(cuò)誤信息、亦或是將任務(wù)標(biāo)記為失敗并通知管理員。對(duì)于可重試的錯(cuò)誤如網(wǎng)絡(luò)超時(shí)調(diào)度系統(tǒng)可以實(shí)現(xiàn)一個(gè)簡(jiǎn)單的重試機(jī)制。但這需要謹(jǐn)慎對(duì)于非冪等的操作如創(chuàng)建訂單盲目重試會(huì)導(dǎo)致嚴(yán)重問(wèn)題。因此重試邏輯最好與具體技能/工具綁定由開發(fā)者根據(jù)業(yè)務(wù)語(yǔ)義來(lái)決定調(diào)度系統(tǒng)只提供重試的基礎(chǔ)設(shè)施比如一個(gè)Retry(maxAttempts: 3)的裝飾器。3.3. 超時(shí)控制與資源隔離Agent 任務(wù)可能陷入死循環(huán)或者某個(gè)外部調(diào)用永遠(yuǎn)不返回。調(diào)度系統(tǒng)必須有能力強(qiáng)制終止長(zhǎng)時(shí)間運(yùn)行的任務(wù)。這可以通過(guò)為每個(gè)工作流的執(zhí)行設(shè)置一個(gè)全局超時(shí)或者為每個(gè)技能設(shè)置單獨(dú)的超時(shí)來(lái)實(shí)現(xiàn)。在實(shí)現(xiàn)上可以利用 JavaScript 的Promise.race或AbortController。當(dāng)啟動(dòng)一個(gè)技能執(zhí)行時(shí)同時(shí)啟動(dòng)一個(gè)定時(shí)器。如果技能在超時(shí)前完成則取消定時(shí)器如果定時(shí)器先觸發(fā)則向技能執(zhí)行發(fā)送中止信號(hào)并拋出超時(shí)錯(cuò)誤事件。async executeSkillWithTimeout(skill: ISkill, context: WorkflowContext, timeoutMs: number): PromiseSkillResult { const abortController new AbortController(); const timeoutId setTimeout(() abortController.abort(), timeoutMs); try { // 將 abortController.signal 傳遞給技能技能內(nèi)部需要支持中止 const result await skill.execute(context, abortController.signal); clearTimeout(timeoutId); return result; } catch (error) { clearTimeout(timeoutId); if (error.name AbortError) { throw new AgentExecutionError(Skill execution timeout, TIMEOUT); } throw error; } }資源隔離則更為復(fù)雜。在 Node.js 環(huán)境下多個(gè) Agent 會(huì)話共享同一個(gè)進(jìn)程內(nèi)存。如果一個(gè)技能有內(nèi)存泄漏或者某個(gè)任務(wù)消耗了巨量 CPU可能會(huì)影響其他任務(wù)。OpenClaw 作為輕量級(jí)調(diào)度系統(tǒng)可能不會(huì)實(shí)現(xiàn)完整的沙箱隔離但可以通過(guò)一些模式來(lái)緩解比如限制單個(gè)技能的執(zhí)行時(shí)間超時(shí)控制、監(jiān)控進(jìn)程內(nèi)存使用并在超過(guò)閾值時(shí)報(bào)警或重啟、以及最重要的——在技能開發(fā)規(guī)范中強(qiáng)調(diào)資源清理如關(guān)閉數(shù)據(jù)庫(kù)連接、清理臨時(shí)文件。4. 實(shí)戰(zhàn)從零配置一個(gè) OpenClaw Agent 并集成大模型理論說(shuō)了這么多我們動(dòng)手配置一個(gè)最簡(jiǎn)單的 OpenClaw Agent并讓它接入一個(gè)大模型比如通過(guò) Ollama 本地運(yùn)行的 Llama 3來(lái)直觀感受一下這套調(diào)度系統(tǒng)是如何運(yùn)作的。這里假設(shè)你已經(jīng)按照一些教程如“ubuntu極速部署openclaw完全指南”完成了基礎(chǔ)環(huán)境的搭建。4.1. 項(xiàng)目初始化與核心依賴安裝首先創(chuàng)建一個(gè)新的 TypeScript 項(xiàng)目并安裝 OpenClaw 的核心包這里假設(shè)包名為openclaw/core具體名稱需查閱官方文檔。mkdir my-openclaw-agent cd my-openclaw-agent npm init -y npm install typescript ts-node types/node --save-dev npm install openclaw/core --save接著初始化 TypeScript 配置。注意熱詞中的警告選項(xiàng)“baseurl”已棄用,并將停止在 typescript 7.0 中運(yùn)行。指定 compileroption。這是 TypeScript 配置的更新。在你的tsconfig.json中避免使用已棄用的baseUrl而是使用compilerOptions下的paths等新方式進(jìn)行路徑映射。{ compilerOptions: { target: ES2020, module: commonjs, lib: [ES2020], outDir: ./dist, rootDir: ./src, strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true, resolveJsonModule: true, // 使用 paths 替代已棄用的 baseUrl paths: { /*: [./src/*] } }, include: [src/**/*], exclude: [node_modules] }4.2. 定義第一個(gè)技能與工具調(diào)用本地 LLM我們創(chuàng)建一個(gè)簡(jiǎn)單的“問(wèn)答”技能它調(diào)用本地的 Ollama 服務(wù)。首先定義一個(gè)調(diào)用 LLM 的工具。在src/tools/llm-tool.ts中import { Tool, ITool, ToolContext } from openclaw/core; export interface LLMCallParams { model: string; prompt: string; systemPrompt?: string; } export interface LLMCallResult { content: string; model: string; usage?: { prompt_tokens: number; completion_tokens: number }; } // 使用裝飾器注冊(cè)工具 Tool({ name: call_ollama_llm, description: 調(diào)用本地 Ollama 服務(wù)的 LLM 模型, inputSchema: { /* 可以用 JSON Schema 定義參數(shù)結(jié)構(gòu) */ } }) export class OllamaLLMTool implements IToolLLMCallParams, LLMCallResult { private ollamaBaseUrl: string; constructor(baseUrl: string http://localhost:11434) { this.ollamaBaseUrl baseUrl; } async invoke(params: LLMCallParams, context?: ToolContext): PromiseLLMCallResult { const response await fetch(${this.ollamaBaseUrl}/api/generate, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ model: params.model, prompt: params.prompt, system: params.systemPrompt, stream: false // 簡(jiǎn)單起見關(guān)閉流式 }) }); if (!response.ok) { const errorBody await response.text(); throw new Error(Ollama API call failed: ${response.status} ${errorBody}); } const data await response.json(); return { content: data.response, model: data.model, usage: { prompt_tokens: 0, completion_tokens: 0 } // Ollama 可能不返回這里示意 }; } }接著在src/skills/qa-skill.ts中定義技能import { Skill, ISkill, SkillResult, WorkflowContext } from openclaw/core; import { OllamaLLMTool, LLMCallParams } from ../tools/llm-tool; Skill({ name: answer_question, description: 根據(jù)用戶問(wèn)題調(diào)用 LLM 生成回答 }) export class QASkill implements ISkill { private llmTool: OllamaLLMTool; constructor() { this.llmTool new OllamaLLMTool(); } async execute(context: WorkflowContext): PromiseSkillResult { // 從上下文中取出用戶問(wèn)題 const userQuestion context.userInput; if (!userQuestion) { return { success: false, error: 用戶輸入為空 }; } try { const llmParams: LLMCallParams { model: llama3, // 假設(shè)本地已拉取 llama3 模型 prompt: 請(qǐng)回答以下問(wèn)題${userQuestion}, systemPrompt: 你是一個(gè)樂(lè)于助人的AI助手。 }; const result await this.llmTool.invoke(llmParams); // 將回答存入上下文供后續(xù)技能或輸出使用 context.llmAnswer result.content; return { success: true, output: result.content }; } catch (error) { // 錯(cuò)誤處理記錄日志并返回失敗結(jié)果 console.error(QASkill 執(zhí)行失敗:, error); context.lastError error.message; return { success: false, error: 獲取答案失敗: ${error.message} }; } } }4.3. 組裝 Agent 與啟動(dòng)調(diào)度服務(wù)現(xiàn)在我們需要?jiǎng)?chuàng)建一個(gè) Agent將技能組裝起來(lái)并啟動(dòng)調(diào)度服務(wù)。在src/agent/simple-qa-agent.ts中import { Agent, IAgent, Workflow, SvrOperator } from openclaw/core; import { QASkill } from ../skills/qa-skill; // 1. 定義工作流 const qaWorkflow: Workflow { id: simple_qa_workflow, entrySkill: answer_question, skills: { answer_question: { execute: async (context) { const skill new QASkill(); return await skill.execute(context); }, // 執(zhí)行完就結(jié)束沒(méi)有下一個(gè)技能 next: null } } }; // 2. 創(chuàng)建 Agent export class SimpleQAAgent implements IAgent { name Simple QA Agent; workflow qaWorkflow; async onStartup() { console.log(Agent ${this.name} 已初始化。); } async onShutdown() { console.log(Agent ${this.name} 已關(guān)閉。); } }最后在src/index.ts中創(chuàng)建服務(wù)入口import { SvrOperator } from openclaw/core; import { SimpleQAAgent } from ./agent/simple-qa-agent; async function main() { // 1. 初始化調(diào)度操作員 const operator new SvrOperator(); // 2. 創(chuàng)建并注冊(cè)我們的 Agent const myAgent new SimpleQAAgent(); operator.registerAgent(myAgent); // 3. 啟動(dòng) HTTP 服務(wù)器或其它傳輸層等待請(qǐng)求 // 這里以簡(jiǎn)單的 HTTP 服務(wù)器為例 const http require(http); const server http.createServer(async (req, res) { if (req.method POST req.url /ask) { let body ; req.on(data, chunk body chunk); req.on(end, async () { try { const { question, sessionId sess_${Date.now()} } JSON.parse(body); // 構(gòu)造執(zhí)行上下文 const initialContext { userInput: question, sessionId }; // 通過(guò)調(diào)度操作員執(zhí)行 Agent const result await operator.executeAgent(Simple QA Agent, initialContext); res.writeHead(200, { Content-Type: application/json }); res.end(JSON.stringify({ answer: result.output, success: result.success })); } catch (error) { console.error(請(qǐng)求處理錯(cuò)誤:, error); res.writeHead(500, { Content-Type: application/json }); res.end(JSON.stringify({ error: Internal Server Error, details: error.message })); } }); } else { res.writeHead(404).end(); } }); server.listen(3000, () { console.log(OpenClaw Agent 調(diào)度服務(wù)已啟動(dòng)監(jiān)聽端口 3000); console.log(嘗試發(fā)送 POST 請(qǐng)求到 http://localhost:3000/ask 并攜帶 JSON 體: {question: 你的問(wèn)題}); }); } main().catch(console.error);運(yùn)行npx ts-node src/index.ts你的純 TypeScript Agent 調(diào)度服務(wù)就跑起來(lái)了。你可以用 curl 或 Postman 測(cè)試它。這個(gè)簡(jiǎn)單的例子串聯(lián)了從 HTTP 請(qǐng)求進(jìn)入SvrOperator到觸發(fā)工作流執(zhí)行技能調(diào)用工具最后返回結(jié)果的完整調(diào)度鏈條。4.4. 配置多模型與技能擴(kuò)展熱詞中提到“本地openclaw如何添加多個(gè)大模型”。在我們的架構(gòu)里這非常直觀。你不需要修改調(diào)度核心只需擴(kuò)展工具層。創(chuàng)建新的 LLM 工具類比如OpenAITool、AzureOpenAITool實(shí)現(xiàn)相同的ITool接口但內(nèi)部調(diào)用不同的 API。在技能中動(dòng)態(tài)選擇模型可以通過(guò)上下文中的某個(gè)配置字段來(lái)決定使用哪個(gè)工具。例如修改QASkill的execute方法async execute(context: WorkflowContext): PromiseSkillResult { const modelProvider context.modelProvider || ollama; // 默認(rèn)為 ollama let llmTool: ITool; if (modelProvider openai) { llmTool new OpenAITool(process.env.OPENAI_API_KEY); } else { llmTool new OllamaLLMTool(); } // ... 后續(xù)調(diào)用邏輯不變 }通過(guò)注冊(cè)中心更優(yōu)雅地管理更高級(jí)的做法是將所有 LLM 工具都注冊(cè)到全局工具注冊(cè)中心技能只需要根據(jù)名稱來(lái)獲取工具。這樣新增模型提供商時(shí)只需要編寫并注冊(cè)新工具所有技能自動(dòng)獲得支持。技能擴(kuò)展同理。如果你想增加一個(gè)“聯(lián)網(wǎng)搜索”后再回答的技能只需定義一個(gè)新的WebSearchSkill然后在工作流定義中將answer_question技能的next指向它或者在answer_question之前插入它。工作流引擎會(huì)自動(dòng)按照新的藍(lán)圖來(lái)調(diào)度執(zhí)行順序。通過(guò)這個(gè)實(shí)戰(zhàn)流程你可以看到 OpenClaw 這類純 TypeScript 調(diào)度系統(tǒng)的靈活性。它的核心價(jià)值不在于提供了多少預(yù)置的 AI 能力而在于提供了一套類型安全、松耦合、可擴(kuò)展的框架讓你能像搭積木一樣快速構(gòu)建和迭代屬于自己的 AI Agent 應(yīng)用。從簡(jiǎn)單的問(wèn)答到復(fù)雜的多步驟工作流如分析需求 - 搜索信息 - 生成報(bào)告 - 發(fā)送郵件這套調(diào)度系統(tǒng)都能提供清晰、可靠的控制骨架。