OpenClaw 底层原理：从 Agent 运行时到工具调用的全链路拆解

1. OpenClaw 是什么：它解决了哪类问题

• 把“大模型能力”封装成可控的 任务执行系统。

• 用 工具（Tools）、记忆（Memory）、规划（Planning）、执行（Execution） 等模块，把一次对话变成可重复、可观测、可评估的流程。

• 将“模型输出文本”升级为“在约束内完成目标”的工程化能力。

• 多步骤任务自动化（信息收集、对齐、生成、校验、落库）。

• 带外部依赖的工作流（调用 API、数据库、文件系统、浏览器）。

• 需要回溯与审计的生产任务（可观测、可重放、可评测）。

2. 核心抽象：OpenClaw 的关键对象

1. Agent
• 对外暴露的执行入口。
• 绑定模型、工具集、策略与状态。

2. Model Adapter（模型适配层）
• 统一不同厂商、不同接口范式（Chat Completions / Responses / Function Calling）。
• 产出结构化的 assistant_message，包含 tool call 或普通文本。

3. Tool（工具）
• 标准化的可执行动作：name、schema、handler。
• 运行时会进行参数校验、超时控制、重试、隔离。

4. Planner / Policy（规划与策略）
• 决定“要不要调用工具、调用哪个工具、何时停止”。
• 常见实现：ReAct、Plan-and-Execute、Graph/State Machine。

5. Memory（记忆）
• 短期记忆：当前对话窗口内的信息。
• 长期记忆：向量检索、知识库、历史轨迹。
• 关键在于“写入策略”和“读取策略”。

6. State / Trace（状态与轨迹）
• 每一步的输入、输出、工具调用、耗时、错误，形成可观测链路。
• 支持回放、评测与问题定位。

3. 运行时全链路：一次请求是如何被执行的

• Prompt 不是一次性模板：运行时会把系统提示、工具描述、上下文、记忆检索结果、上一步工具结果按策略拼装。

• 工具调用是强约束出口：LLM 只能“声明要调用工具”，真正执行由 Tool Executor 完成。

• Stop 条件是工程策略：不是“模型说结束就结束”。可以结合最大步数、置信度、评估器结果、预算等限制。

4. 工具调用（Tool Calling）的底层机制

4.1 工具的“接口契约”

• name: 全局唯一标识。

• description: 给模型看的行为说明。

• input_schema: JSON Schema 或等价的参数约束。

• handler(ctx, args): 真正执行。

• 参数校验（缺字段、类型不对、越界）。

• 结果格式化（让模型更稳定地消费工具结果）。

• 观测与审计（每次调用可追踪）。

4.2 Tool Executor 的工程职责

• 参数校验与反序列化：将 LLM 输出的 arguments 变成安全的结构化输入。

• 超时与取消：防止工具卡死拖垮链路。

• 重试与幂等：对可重试错误做退避重试，并避免重复副作用。

• 沙箱隔离：不同工具可在独立进程或容器内执行。

• 结果截断与脱敏：避免把过长或敏感数据直接喂回模型。

5. 记忆系统：如何“记得住”又“不乱记”

• 会话记忆（Conversation Buffer）：始终存在，但窗口有限。

• 摘要记忆（Summarization Memory）：对长会话做压缩，保留决策与结论。

• 检索记忆（RAG / Vector Store）：把事实与文档索引起来，按需检索。

• 只有当信息满足“长期可复用”才写入检索记忆。

• 只有当信息满足“对后续决策重要”才写入摘要记忆。

6. 规划与执行：从“想”到“做”的两段式

1. 规划（Plan）：先输出一个可执行计划（若干步骤）。

2. 执行（Execute）：按步骤逐个执行，每步允许调用工具，并把结果写入状态。

• 可控：可以审计计划，也可以让人类在关键步骤审批。

• 可评测：每个步骤可以做单独指标（成功率、成本、耗时）。

• 可恢复：失败时只重试失败步骤。

7. 架构图：推荐的工程分层

• Runtime 只做编排与通用能力，不要把业务逻辑写在 Runtime。

• Tool 层与业务系统集成要“窄接口”，避免把业务复杂度泄漏给模型。

8. 实操体验教程：本地跑一个最小可用 Agent

• 一个 Agent

• 两个工具：calculator 与 http_get

• 一次任务：先计算，再拉取网页，再总结

说明：不同 OpenClaw 版本或实现会有差异。你可以把下面示例当作“工程骨架”，按你的实际 SDK/接口名替换。

8.1 环境准备

• Node.js 18+ 或 Python 3.10+

• 一个可用的大模型 API Key

8.2 定义工具（示例：Python）

8.3 运行时循环（工具调用 + 继续推理）

1. 把 tools 描述传给模型。

2. 如果模型返回 tool call，就执行工具。

3. 把 tool result 再喂给模型。

4. 直到模型返回最终答案，或达到最大步数。

8.4 你应该看到什么

• Trace 里有清晰的步骤：
• tool: calculator
• tool: http_get
• assistant: final answer

• 每一步都有耗时与 token 使用（如果你的运行时接入了观测）。

9. 常见问题与调优建议

1. 模型乱编工具参数
• 给工具 schema 加严格约束。
• 对关键字段做白名单校验。

2. 工具结果太长导致上下文爆炸
• 工具层做截断与结构化摘要。
• 把原文放存储，模型只拿到引用与摘要。

3. 循环不停止
• 设定 max_steps。
• 增加“完成条件”评估器（例如：是否已满足用户要求）。

4. 成本与延迟过高
• 先用小模型做规划或筛选，再用大模型做关键生成。
• 缓存工具结果与检索结果。

10. 结语：把 OpenClaw 当作“可控的执行系统”

• 通过稳定抽象把模型放进工程体系。

• 通过工具与状态让执行可控、可观测、可评测。

• 通过记忆与规划让任务可复用、可扩展。