1. 从零到一为什么我们需要一个纯 TypeScript 的 Agent 调度系统最近在折腾 AI Agent 项目特别是想把一些想法落地成可用的服务时遇到了一个挺典型的问题市面上现成的 Agent 框架要么太重像 LangChain为了通用性封装了太多层调试起来像在走迷宫要么就是生态绑定太深比如一些框架强依赖特定的云服务或运行时想在自己的服务器上跑或者想深度定制一下调度逻辑感觉处处掣肘。更别提那些用 Python 写的框架虽然生态好但想在 Node.js 或浏览器端复用核心逻辑基本就得重写一遍。这时候一个叫 OpenClaw 的项目进入了我的视野。它最吸引我的点就是标题里写的用纯 TypeScript 造了一套 Agent 调度系统。这听起来像是个“轮子”但在 AI 应用开发尤其是 Agent 领域这个“轮子”可能恰恰是很多团队缺的那一个。TypeScript 意味着什么首先它是 JavaScript 的超集能编译成纯净的 JS这带来了无与伦比的运行时灵活性。你的调度核心可以跑在 Node.js 服务器上可以跑在浏览器里甚至可以打包进 Electron 桌面应用或者 React Native 移动端。一次编写多处部署这对于需要跨端能力的 AI 应用来说价值巨大。其次TypeScript 的静态类型系统在构建像“调度系统”这样复杂的、状态机式的逻辑时简直是救命稻草。Agent 的执行流往往涉及多个步骤、条件分支、异步操作和共享状态。用纯 JS 写很容易就变成“面条代码”调试时一个变量的类型搞错可能就得花半天时间。TypeScript 能在编码阶段就帮你卡住很多低级错误并且它的接口Interface和类型别名Type Alias非常适合用来定义 Agent 的“技能”Skill、工具Tool、以及执行上下文Context的数据结构让整个系统的设计从一开始就清晰可控。OpenClaw 选择纯 TypeScript在我看来不是炫技而是针对 Agent 开发中“快速迭代”和“可靠部署”这两个核心痛点的务实选择。它试图提供一套轻量、类型安全、不绑定特定后端的调度内核让开发者能更专注于 Agent 本身的行为逻辑而不是陷在框架的复杂性里。接下来我们就深入这套系统的内部看看它是如何被“造”出来的。2. 调度系统的核心架构事件驱动与工作流引擎OpenClaw 的调度系统其核心思想可以概括为“事件驱动的工作流”。它没有采用一些传统后台服务那种复杂的队列和消费者模型而是设计了一个更贴合 Agent 交互场景的轻量级中枢。整个架构围绕几个关键概念展开理解了它们就理解了调度的脉络。2.1 调度中枢SVR Operator 与事件总线在 OpenClaw 的代码中你经常会看到一个核心类比如叫SvrOperator。这个 Operator 不是 Kubernetes 里那个 Operator在这里你可以把它理解为“服务操作员”或“调度员”。它是整个调度系统的入口和总控。它的核心职责是接收外部的请求比如来自 HTTP API、WebSocket 消息、命令行指令这个请求通常包含了要执行哪个 Agent、以及初始的输入参数。SvrOperator会将这些请求转化成一个标准的内部事件比如AgentExecutionRequestEvent然后抛给系统内部的事件总线Event Bus。这里的事件总线是一个典型的发布-订阅模式实现。为什么用事件驱动因为 Agent 的执行过程本质上是异步的、离散的。一个 Agent 执行一个技能Skill可能需要调用语言模型LLM、查询数据库、执行一段代码每一步都可能成功或失败都可能产生需要后续步骤处理的数据。用事件来串联这些状态变化比用一个大而全的同步函数调用链要清晰和灵活得多。每个模块如技能执行器、工具调用器、状态管理器只监听自己关心的事件完成自己的工作后再发出新的事件从而驱动流程向下进行。这种松耦合的设计也使得扩展新的技能或工具变得非常容易你只需要编写一个新的监听器Listener并注册到总线即可。一个常见的错误提示比如openclaw llamap svr operator(): got exception: { error: { code: 400, me...往往就发生在SvrOperator处理请求的初始阶段。这可能是请求格式不符合预期、必要的参数缺失、或者请求的 Agent 或 Skill 不存在。好的调度系统会在这一层就做好完备的请求验证和错误格式化把问题尽可能早地暴露出来而不是让错误渗透到后续复杂的执行链路中。2.2. 工作流定义用 TypeScript 类型描述执行蓝图Agent 不是一个黑盒函数它通常有一个预设的执行流程也就是工作流Workflow。OpenClaw 如何定义这个流程它充分利用了 TypeScript 的类型能力。通常我们会用一个 TypeScript 接口Interface或类型别名Type来定义一个工作流。这个类型可能长这样interface AgentWorkflow { id: string; entrySkill: string; // 入口技能如 “analyze_user_query” skills: { [skillName: string]: { execute: (context: WorkflowContext) PromiseSkillResult; next?: string | ((result: SkillResult) string); // 下一个技能名或根据结果决定的函数 onError?: string; // 出错时跳转到哪个技能如 “handle_error” }; }; }这里WorkflowContext是一个贯穿整个工作流执行过程的上下文对象它用 TypeScript 严格定义了在每个阶段可以存取的数据结构。比如interface WorkflowContext { sessionId: string; userInput: string; llmResponse?: string; extractedData?: Recordstring, any; error?: Error; // ... 其他自定义字段 }通过类型定义我们在编码时就能清晰地知道在执行“分析用户查询”这个技能后context.llmResponse字段会被填充在执行“数据提取”技能时我们可以安全地读取llmResponse并期望它是字符串类型。这种编译时的安全保障是纯 JavaScript 项目难以企及的。工作流引擎的职责就是根据这个蓝图监听技能执行完成的事件然后查找next规则决定下一个要执行的技能并再次派发事件。它可能还需要处理循环、条件分支比如根据结果决定走 A 路径还是 B 路径、以及并行执行等复杂逻辑。OpenClaw 的实现通常会有一个WorkflowExecutor类它内部维护着当前执行到了哪个技能、上下文状态是什么并作为事件总线的一个主要监听者和驱动者。2.3. 技能Skill与工具Tool的注册与发现技能是 Agent 能力的原子单位。一个“总结文档”的技能内部可能调用了“调用 LLM API”和“解析 Markdown”两个工具。OpenClaw 需要一套机制来管理这些技能和工具。通常会有一个全局的注册中心Registry。在系统初始化时所有定义好的技能和工具模块会向这个注册中心“报到”登记自己的名字、描述、输入输出参数类型等信息。这个注册过程同样可以借助 TypeScript 的装饰器Decorator来实现让代码看起来非常清晰Skill({ name: summarize_document, description: 总结一篇长文档的核心内容 }) export class SummarizeDocumentSkill implements ISkill { async execute(context: WorkflowContext): PromiseSkillResult { // 1. 从 context 中获取文档内容 const doc context.documentContent; // 2. 调用 LLM 工具 const llmResult await ToolRegistry.getTool(call_llm).invoke({ model: gpt-4, prompt: 请总结以下文档\n${doc} }); // 3. 将结果存入 context context.summary llmResult.content; return { success: true, output: context.summary }; } }工具Tool的注册也类似它们更像是底层的、可复用的功能函数比如 HTTP 请求、数据库查询、代码执行等。调度系统在需要调用工具时不会硬编码而是通过注册中心按名查找这实现了彻底的解耦。当你需要新增一个工具时只需要编写实现类并注册所有技能都能立即使用它无需修改调度核心代码。这种基于注册的模式也使得 OpenClaw 能够实现类似“技能市场”或动态加载的功能。理论上你可以从远程加载一个符合接口规范的技能模块在运行时注册进去Agent 就立刻获得了新能力。3. 状态管理、持久化与容错机制一个健壮的调度系统不能是“一锤子买卖”。Agent 与用户的对话可能是多轮的一个复杂任务可能被中断后需要恢复。因此OpenClaw 必须考虑状态管理和持久化。3.1. 会话状态与上下文持久化每一次用户与 Agent 的交互通常会被关联到一个唯一的会话 IDSession ID。WorkflowContext对象就是这个会话在内存中的实时状态。但是内存状态是脆弱的服务重启就没了。所以调度系统需要将关键的上下文状态持久化到外部存储比如 Redis、数据库或文件系统。OpenClaw 的做法通常是在工作流引擎的某些关键节点例如一个技能执行完成后、或等待外部输入时触发持久化操作。它不会每次都全量保存而是可能采用快照Snapshot机制。定义一个ContextPersistenceService其接口可能是interface IContextPersistenceService { save(sessionId: string, contextSnapshot: PartialWorkflowContext): Promisevoid; load(sessionId: string): PromiseWorkflowContext | null; }在持久化时一个重要的细节是序列化。WorkflowContext里可能包含复杂的对象、甚至函数虽然不推荐。纯 TypeScript/JavaScript 环境里直接用JSON.stringify可能会丢失信息如 Date 对象变成字符串undefined 字段被忽略。因此OpenClaw 可能需要引入一个序列化库或者自定义一套序列化规则确保上下文恢复后类型和结构依然正确。3.2. 错误处理与重试逻辑在热词里我们看到openclaw llamap svr operator(): got exception错误处理是调度系统必须精心设计的部分。错误可能发生在各个层面技能执行错误比如调用 LLM API 超时、返回格式异常。工具调用错误比如数据库连接失败、第三方服务不可用。工作流逻辑错误比如next指向了一个不存在的技能。OpenClaw 的调度系统需要有一个统一的错误捕获和分发机制。事件总线在这里再次发挥作用。任何一个技能或工具在执行中抛出的异常不应该直接导致整个进程崩溃而应该被包装成一个AgentExecutionErrorEvent事件。工作流引擎监听到这个错误事件后会根据当前技能定义中的onError字段决定错误处理路径。例如可以跳转到一个专门的“错误处理”技能这个技能可能会尝试重试原操作对于网络波动错误、或者向用户发送友好的错误信息、亦或是将任务标记为失败并通知管理员。对于可重试的错误如网络超时调度系统可以实现一个简单的重试机制。但这需要谨慎对于非幂等的操作如创建订单盲目重试会导致严重问题。因此重试逻辑最好与具体技能/工具绑定由开发者根据业务语义来决定调度系统只提供重试的基础设施比如一个Retry(maxAttempts: 3)的装饰器。3.3. 超时控制与资源隔离Agent 任务可能陷入死循环或者某个外部调用永远不返回。调度系统必须有能力强制终止长时间运行的任务。这可以通过为每个工作流的执行设置一个全局超时或者为每个技能设置单独的超时来实现。在实现上可以利用 JavaScript 的Promise.race或AbortController。当启动一个技能执行时同时启动一个定时器。如果技能在超时前完成则取消定时器如果定时器先触发则向技能执行发送中止信号并抛出超时错误事件。async executeSkillWithTimeout(skill: ISkill, context: WorkflowContext, timeoutMs: number): PromiseSkillResult { const abortController new AbortController(); const timeoutId setTimeout(() abortController.abort(), timeoutMs); try { // 将 abortController.signal 传递给技能技能内部需要支持中止 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; } }资源隔离则更为复杂。在 Node.js 环境下多个 Agent 会话共享同一个进程内存。如果一个技能有内存泄漏或者某个任务消耗了巨量 CPU可能会影响其他任务。OpenClaw 作为轻量级调度系统可能不会实现完整的沙箱隔离但可以通过一些模式来缓解比如限制单个技能的执行时间超时控制、监控进程内存使用并在超过阈值时报警或重启、以及最重要的——在技能开发规范中强调资源清理如关闭数据库连接、清理临时文件。4. 实战从零配置一个 OpenClaw Agent 并集成大模型理论说了这么多我们动手配置一个最简单的 OpenClaw Agent并让它接入一个大模型比如通过 Ollama 本地运行的 Llama 3来直观感受一下这套调度系统是如何运作的。这里假设你已经按照一些教程如“ubuntu极速部署openclaw完全指南”完成了基础环境的搭建。4.1. 项目初始化与核心依赖安装首先创建一个新的 TypeScript 项目并安装 OpenClaw 的核心包这里假设包名为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 配置。注意热词中的警告选项“baseurl”已弃用,并将停止在 typescript 7.0 中运行。指定 compileroption。这是 TypeScript 配置的更新。在你的tsconfig.json中避免使用已弃用的baseUrl而是使用compilerOptions下的paths等新方式进行路径映射。{ 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. 定义第一个技能与工具调用本地 LLM我们创建一个简单的“问答”技能它调用本地的 Ollama 服务。首先定义一个调用 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 }; } // 使用装饰器注册工具 Tool({ name: call_ollama_llm, description: 调用本地 Ollama 服务的 LLM 模型, inputSchema: { /* 可以用 JSON Schema 定义参数结构 */ } }) 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 // 简单起见关闭流式 }) }); 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: 根据用户问题调用 LLM 生成回答 }) export class QASkill implements ISkill { private llmTool: OllamaLLMTool; constructor() { this.llmTool new OllamaLLMTool(); } async execute(context: WorkflowContext): PromiseSkillResult { // 从上下文中取出用户问题 const userQuestion context.userInput; if (!userQuestion) { return { success: false, error: 用户输入为空 }; } try { const llmParams: LLMCallParams { model: llama3, // 假设本地已拉取 llama3 模型 prompt: 请回答以下问题${userQuestion}, systemPrompt: 你是一个乐于助人的AI助手。 }; const result await this.llmTool.invoke(llmParams); // 将回答存入上下文供后续技能或输出使用 context.llmAnswer result.content; return { success: true, output: result.content }; } catch (error) { // 错误处理记录日志并返回失败结果 console.error(QASkill 执行失败:, error); context.lastError error.message; return { success: false, error: 获取答案失败: ${error.message} }; } } }4.3. 组装 Agent 与启动调度服务现在我们需要创建一个 Agent将技能组装起来并启动调度服务。在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); }, // 执行完就结束没有下一个技能 next: null } } }; // 2. 创建 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} 已关闭。); } }最后在src/index.ts中创建服务入口import { SvrOperator } from openclaw/core; import { SimpleQAAgent } from ./agent/simple-qa-agent; async function main() { // 1. 初始化调度操作员 const operator new SvrOperator(); // 2. 创建并注册我们的 Agent const myAgent new SimpleQAAgent(); operator.registerAgent(myAgent); // 3. 启动 HTTP 服务器或其它传输层等待请求 // 这里以简单的 HTTP 服务器为例 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); // 构造执行上下文 const initialContext { userInput: question, sessionId }; // 通过调度操作员执行 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(请求处理错误:, 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 调度服务已启动监听端口 3000); console.log(尝试发送 POST 请求到 http://localhost:3000/ask 并携带 JSON 体: {question: 你的问题}); }); } main().catch(console.error);运行npx ts-node src/index.ts你的纯 TypeScript Agent 调度服务就跑起来了。你可以用 curl 或 Postman 测试它。这个简单的例子串联了从 HTTP 请求进入SvrOperator到触发工作流执行技能调用工具最后返回结果的完整调度链条。4.4. 配置多模型与技能扩展热词中提到“本地openclaw如何添加多个大模型”。在我们的架构里这非常直观。你不需要修改调度核心只需扩展工具层。创建新的 LLM 工具类比如OpenAITool、AzureOpenAITool实现相同的ITool接口但内部调用不同的 API。在技能中动态选择模型可以通过上下文中的某个配置字段来决定使用哪个工具。例如修改QASkill的execute方法async execute(context: WorkflowContext): PromiseSkillResult { const modelProvider context.modelProvider || ollama; // 默认为 ollama let llmTool: ITool; if (modelProvider openai) { llmTool new OpenAITool(process.env.OPENAI_API_KEY); } else { llmTool new OllamaLLMTool(); } // ... 后续调用逻辑不变 }通过注册中心更优雅地管理更高级的做法是将所有 LLM 工具都注册到全局工具注册中心技能只需要根据名称来获取工具。这样新增模型提供商时只需要编写并注册新工具所有技能自动获得支持。技能扩展同理。如果你想增加一个“联网搜索”后再回答的技能只需定义一个新的WebSearchSkill然后在工作流定义中将answer_question技能的next指向它或者在answer_question之前插入它。工作流引擎会自动按照新的蓝图来调度执行顺序。通过这个实战流程你可以看到 OpenClaw 这类纯 TypeScript 调度系统的灵活性。它的核心价值不在于提供了多少预置的 AI 能力而在于提供了一套类型安全、松耦合、可扩展的框架让你能像搭积木一样快速构建和迭代属于自己的 AI Agent 应用。从简单的问答到复杂的多步骤工作流如分析需求 - 搜索信息 - 生成报告 - 发送邮件这套调度系统都能提供清晰、可靠的控制骨架。 
长河君 · 2026/8/26 23:12:19 · 阅读 1.2k 基于TypeScript的AI Agent调度系统：OpenClaw架构解析与实战
1. 从零到一为什么我们需要一个纯 TypeScript 的 Agent 调度系统最近在折腾 AI Agent 项目特别是想把一些想法落地成可用的服务时遇到了一个挺典型的问题市面上现成的 Agent 框架要么太重像 LangChain为了通用性封装了太多层调试起来像在走迷宫要么就是生态绑定太深比如一些框架强依赖特定的云服务或运行时想在自己的服务器上跑或者想深度定制一下调度逻辑感觉处处掣肘。更别提那些用 Python 写的框架虽然生态好但想在 Node.js 或浏览器端复用核心逻辑基本就得重写一遍。这时候一个叫 OpenClaw 的项目进入了我的视野。它最吸引我的点就是标题里写的用纯 TypeScript 造了一套 Agent 调度系统。这听起来像是个“轮子”但在 AI 应用开发尤其是 Agent 领域这个“轮子”可能恰恰是很多团队缺的那一个。TypeScript 意味着什么首先它是 JavaScript 的超集能编译成纯净的 JS这带来了无与伦比的运行时灵活性。你的调度核心可以跑在 Node.js 服务器上可以跑在浏览器里甚至可以打包进 Electron 桌面应用或者 React Native 移动端。一次编写多处部署这对于需要跨端能力的 AI 应用来说价值巨大。其次TypeScript 的静态类型系统在构建像“调度系统”这样复杂的、状态机式的逻辑时简直是救命稻草。Agent 的执行流往往涉及多个步骤、条件分支、异步操作和共享状态。用纯 JS 写很容易就变成“面条代码”调试时一个变量的类型搞错可能就得花半天时间。TypeScript 能在编码阶段就帮你卡住很多低级错误并且它的接口Interface和类型别名Type Alias非常适合用来定义 Agent 的“技能”Skill、工具Tool、以及执行上下文Context的数据结构让整个系统的设计从一开始就清晰可控。OpenClaw 选择纯 TypeScript在我看来不是炫技而是针对 Agent 开发中“快速迭代”和“可靠部署”这两个核心痛点的务实选择。它试图提供一套轻量、类型安全、不绑定特定后端的调度内核让开发者能更专注于 Agent 本身的行为逻辑而不是陷在框架的复杂性里。接下来我们就深入这套系统的内部看看它是如何被“造”出来的。2. 调度系统的核心架构事件驱动与工作流引擎OpenClaw 的调度系统其核心思想可以概括为“事件驱动的工作流”。它没有采用一些传统后台服务那种复杂的队列和消费者模型而是设计了一个更贴合 Agent 交互场景的轻量级中枢。整个架构围绕几个关键概念展开理解了它们就理解了调度的脉络。2.1 调度中枢SVR Operator 与事件总线在 OpenClaw 的代码中你经常会看到一个核心类比如叫SvrOperator。这个 Operator 不是 Kubernetes 里那个 Operator在这里你可以把它理解为“服务操作员”或“调度员”。它是整个调度系统的入口和总控。它的核心职责是接收外部的请求比如来自 HTTP API、WebSocket 消息、命令行指令这个请求通常包含了要执行哪个 Agent、以及初始的输入参数。SvrOperator会将这些请求转化成一个标准的内部事件比如AgentExecutionRequestEvent然后抛给系统内部的事件总线Event Bus。这里的事件总线是一个典型的发布-订阅模式实现。为什么用事件驱动因为 Agent 的执行过程本质上是异步的、离散的。一个 Agent 执行一个技能Skill可能需要调用语言模型LLM、查询数据库、执行一段代码每一步都可能成功或失败都可能产生需要后续步骤处理的数据。用事件来串联这些状态变化比用一个大而全的同步函数调用链要清晰和灵活得多。每个模块如技能执行器、工具调用器、状态管理器只监听自己关心的事件完成自己的工作后再发出新的事件从而驱动流程向下进行。这种松耦合的设计也使得扩展新的技能或工具变得非常容易你只需要编写一个新的监听器Listener并注册到总线即可。一个常见的错误提示比如openclaw llamap svr operator(): got exception: { error: { code: 400, me...往往就发生在SvrOperator处理请求的初始阶段。这可能是请求格式不符合预期、必要的参数缺失、或者请求的 Agent 或 Skill 不存在。好的调度系统会在这一层就做好完备的请求验证和错误格式化把问题尽可能早地暴露出来而不是让错误渗透到后续复杂的执行链路中。2.2. 工作流定义用 TypeScript 类型描述执行蓝图Agent 不是一个黑盒函数它通常有一个预设的执行流程也就是工作流Workflow。OpenClaw 如何定义这个流程它充分利用了 TypeScript 的类型能力。通常我们会用一个 TypeScript 接口Interface或类型别名Type来定义一个工作流。这个类型可能长这样interface AgentWorkflow { id: string; entrySkill: string; // 入口技能如 “analyze_user_query” skills: { [skillName: string]: { execute: (context: WorkflowContext) PromiseSkillResult; next?: string | ((result: SkillResult) string); // 下一个技能名或根据结果决定的函数 onError?: string; // 出错时跳转到哪个技能如 “handle_error” }; }; }这里WorkflowContext是一个贯穿整个工作流执行过程的上下文对象它用 TypeScript 严格定义了在每个阶段可以存取的数据结构。比如interface WorkflowContext { sessionId: string; userInput: string; llmResponse?: string; extractedData?: Recordstring, any; error?: Error; // ... 其他自定义字段 }通过类型定义我们在编码时就能清晰地知道在执行“分析用户查询”这个技能后context.llmResponse字段会被填充在执行“数据提取”技能时我们可以安全地读取llmResponse并期望它是字符串类型。这种编译时的安全保障是纯 JavaScript 项目难以企及的。工作流引擎的职责就是根据这个蓝图监听技能执行完成的事件然后查找next规则决定下一个要执行的技能并再次派发事件。它可能还需要处理循环、条件分支比如根据结果决定走 A 路径还是 B 路径、以及并行执行等复杂逻辑。OpenClaw 的实现通常会有一个WorkflowExecutor类它内部维护着当前执行到了哪个技能、上下文状态是什么并作为事件总线的一个主要监听者和驱动者。2.3. 技能Skill与工具Tool的注册与发现技能是 Agent 能力的原子单位。一个“总结文档”的技能内部可能调用了“调用 LLM API”和“解析 Markdown”两个工具。OpenClaw 需要一套机制来管理这些技能和工具。通常会有一个全局的注册中心Registry。在系统初始化时所有定义好的技能和工具模块会向这个注册中心“报到”登记自己的名字、描述、输入输出参数类型等信息。这个注册过程同样可以借助 TypeScript 的装饰器Decorator来实现让代码看起来非常清晰Skill({ name: summarize_document, description: 总结一篇长文档的核心内容 }) export class SummarizeDocumentSkill implements ISkill { async execute(context: WorkflowContext): PromiseSkillResult { // 1. 从 context 中获取文档内容 const doc context.documentContent; // 2. 调用 LLM 工具 const llmResult await ToolRegistry.getTool(call_llm).invoke({ model: gpt-4, prompt: 请总结以下文档\n${doc} }); // 3. 将结果存入 context context.summary llmResult.content; return { success: true, output: context.summary }; } }工具Tool的注册也类似它们更像是底层的、可复用的功能函数比如 HTTP 请求、数据库查询、代码执行等。调度系统在需要调用工具时不会硬编码而是通过注册中心按名查找这实现了彻底的解耦。当你需要新增一个工具时只需要编写实现类并注册所有技能都能立即使用它无需修改调度核心代码。这种基于注册的模式也使得 OpenClaw 能够实现类似“技能市场”或动态加载的功能。理论上你可以从远程加载一个符合接口规范的技能模块在运行时注册进去Agent 就立刻获得了新能力。3. 状态管理、持久化与容错机制一个健壮的调度系统不能是“一锤子买卖”。Agent 与用户的对话可能是多轮的一个复杂任务可能被中断后需要恢复。因此OpenClaw 必须考虑状态管理和持久化。3.1. 会话状态与上下文持久化每一次用户与 Agent 的交互通常会被关联到一个唯一的会话 IDSession ID。WorkflowContext对象就是这个会话在内存中的实时状态。但是内存状态是脆弱的服务重启就没了。所以调度系统需要将关键的上下文状态持久化到外部存储比如 Redis、数据库或文件系统。OpenClaw 的做法通常是在工作流引擎的某些关键节点例如一个技能执行完成后、或等待外部输入时触发持久化操作。它不会每次都全量保存而是可能采用快照Snapshot机制。定义一个ContextPersistenceService其接口可能是interface IContextPersistenceService { save(sessionId: string, contextSnapshot: PartialWorkflowContext): Promisevoid; load(sessionId: string): PromiseWorkflowContext | null; }在持久化时一个重要的细节是序列化。WorkflowContext里可能包含复杂的对象、甚至函数虽然不推荐。纯 TypeScript/JavaScript 环境里直接用JSON.stringify可能会丢失信息如 Date 对象变成字符串undefined 字段被忽略。因此OpenClaw 可能需要引入一个序列化库或者自定义一套序列化规则确保上下文恢复后类型和结构依然正确。3.2. 错误处理与重试逻辑在热词里我们看到openclaw llamap svr operator(): got exception错误处理是调度系统必须精心设计的部分。错误可能发生在各个层面技能执行错误比如调用 LLM API 超时、返回格式异常。工具调用错误比如数据库连接失败、第三方服务不可用。工作流逻辑错误比如next指向了一个不存在的技能。OpenClaw 的调度系统需要有一个统一的错误捕获和分发机制。事件总线在这里再次发挥作用。任何一个技能或工具在执行中抛出的异常不应该直接导致整个进程崩溃而应该被包装成一个AgentExecutionErrorEvent事件。工作流引擎监听到这个错误事件后会根据当前技能定义中的onError字段决定错误处理路径。例如可以跳转到一个专门的“错误处理”技能这个技能可能会尝试重试原操作对于网络波动错误、或者向用户发送友好的错误信息、亦或是将任务标记为失败并通知管理员。对于可重试的错误如网络超时调度系统可以实现一个简单的重试机制。但这需要谨慎对于非幂等的操作如创建订单盲目重试会导致严重问题。因此重试逻辑最好与具体技能/工具绑定由开发者根据业务语义来决定调度系统只提供重试的基础设施比如一个Retry(maxAttempts: 3)的装饰器。3.3. 超时控制与资源隔离Agent 任务可能陷入死循环或者某个外部调用永远不返回。调度系统必须有能力强制终止长时间运行的任务。这可以通过为每个工作流的执行设置一个全局超时或者为每个技能设置单独的超时来实现。在实现上可以利用 JavaScript 的Promise.race或AbortController。当启动一个技能执行时同时启动一个定时器。如果技能在超时前完成则取消定时器如果定时器先触发则向技能执行发送中止信号并抛出超时错误事件。async executeSkillWithTimeout(skill: ISkill, context: WorkflowContext, timeoutMs: number): PromiseSkillResult { const abortController new AbortController(); const timeoutId setTimeout(() abortController.abort(), timeoutMs); try { // 将 abortController.signal 传递给技能技能内部需要支持中止 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; } }资源隔离则更为复杂。在 Node.js 环境下多个 Agent 会话共享同一个进程内存。如果一个技能有内存泄漏或者某个任务消耗了巨量 CPU可能会影响其他任务。OpenClaw 作为轻量级调度系统可能不会实现完整的沙箱隔离但可以通过一些模式来缓解比如限制单个技能的执行时间超时控制、监控进程内存使用并在超过阈值时报警或重启、以及最重要的——在技能开发规范中强调资源清理如关闭数据库连接、清理临时文件。4. 实战从零配置一个 OpenClaw Agent 并集成大模型理论说了这么多我们动手配置一个最简单的 OpenClaw Agent并让它接入一个大模型比如通过 Ollama 本地运行的 Llama 3来直观感受一下这套调度系统是如何运作的。这里假设你已经按照一些教程如“ubuntu极速部署openclaw完全指南”完成了基础环境的搭建。4.1. 项目初始化与核心依赖安装首先创建一个新的 TypeScript 项目并安装 OpenClaw 的核心包这里假设包名为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 配置。注意热词中的警告选项“baseurl”已弃用,并将停止在 typescript 7.0 中运行。指定 compileroption。这是 TypeScript 配置的更新。在你的tsconfig.json中避免使用已弃用的baseUrl而是使用compilerOptions下的paths等新方式进行路径映射。{ 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. 定义第一个技能与工具调用本地 LLM我们创建一个简单的“问答”技能它调用本地的 Ollama 服务。首先定义一个调用 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 }; } // 使用装饰器注册工具 Tool({ name: call_ollama_llm, description: 调用本地 Ollama 服务的 LLM 模型, inputSchema: { /* 可以用 JSON Schema 定义参数结构 */ } }) 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 // 简单起见关闭流式 }) }); 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: 根据用户问题调用 LLM 生成回答 }) export class QASkill implements ISkill { private llmTool: OllamaLLMTool; constructor() { this.llmTool new OllamaLLMTool(); } async execute(context: WorkflowContext): PromiseSkillResult { // 从上下文中取出用户问题 const userQuestion context.userInput; if (!userQuestion) { return { success: false, error: 用户输入为空 }; } try { const llmParams: LLMCallParams { model: llama3, // 假设本地已拉取 llama3 模型 prompt: 请回答以下问题${userQuestion}, systemPrompt: 你是一个乐于助人的AI助手。 }; const result await this.llmTool.invoke(llmParams); // 将回答存入上下文供后续技能或输出使用 context.llmAnswer result.content; return { success: true, output: result.content }; } catch (error) { // 错误处理记录日志并返回失败结果 console.error(QASkill 执行失败:, error); context.lastError error.message; return { success: false, error: 获取答案失败: ${error.message} }; } } }4.3. 组装 Agent 与启动调度服务现在我们需要创建一个 Agent将技能组装起来并启动调度服务。在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); }, // 执行完就结束没有下一个技能 next: null } } }; // 2. 创建 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} 已关闭。); } }最后在src/index.ts中创建服务入口import { SvrOperator } from openclaw/core; import { SimpleQAAgent } from ./agent/simple-qa-agent; async function main() { // 1. 初始化调度操作员 const operator new SvrOperator(); // 2. 创建并注册我们的 Agent const myAgent new SimpleQAAgent(); operator.registerAgent(myAgent); // 3. 启动 HTTP 服务器或其它传输层等待请求 // 这里以简单的 HTTP 服务器为例 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); // 构造执行上下文 const initialContext { userInput: question, sessionId }; // 通过调度操作员执行 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(请求处理错误:, 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 调度服务已启动监听端口 3000); console.log(尝试发送 POST 请求到 http://localhost:3000/ask 并携带 JSON 体: {question: 你的问题}); }); } main().catch(console.error);运行npx ts-node src/index.ts你的纯 TypeScript Agent 调度服务就跑起来了。你可以用 curl 或 Postman 测试它。这个简单的例子串联了从 HTTP 请求进入SvrOperator到触发工作流执行技能调用工具最后返回结果的完整调度链条。4.4. 配置多模型与技能扩展热词中提到“本地openclaw如何添加多个大模型”。在我们的架构里这非常直观。你不需要修改调度核心只需扩展工具层。创建新的 LLM 工具类比如OpenAITool、AzureOpenAITool实现相同的ITool接口但内部调用不同的 API。在技能中动态选择模型可以通过上下文中的某个配置字段来决定使用哪个工具。例如修改QASkill的execute方法async execute(context: WorkflowContext): PromiseSkillResult { const modelProvider context.modelProvider || ollama; // 默认为 ollama let llmTool: ITool; if (modelProvider openai) { llmTool new OpenAITool(process.env.OPENAI_API_KEY); } else { llmTool new OllamaLLMTool(); } // ... 后续调用逻辑不变 }通过注册中心更优雅地管理更高级的做法是将所有 LLM 工具都注册到全局工具注册中心技能只需要根据名称来获取工具。这样新增模型提供商时只需要编写并注册新工具所有技能自动获得支持。技能扩展同理。如果你想增加一个“联网搜索”后再回答的技能只需定义一个新的WebSearchSkill然后在工作流定义中将answer_question技能的next指向它或者在answer_question之前插入它。工作流引擎会自动按照新的蓝图来调度执行顺序。通过这个实战流程你可以看到 OpenClaw 这类纯 TypeScript 调度系统的灵活性。它的核心价值不在于提供了多少预置的 AI 能力而在于提供了一套类型安全、松耦合、可扩展的框架让你能像搭积木一样快速构建和迭代属于自己的 AI Agent 应用。从简单的问答到复杂的多步骤工作流如分析需求 - 搜索信息 - 生成报告 - 发送邮件这套调度系统都能提供清晰、可靠的控制骨架。