OpenClaw 系统设计

OpenClaw 系统设计

1. 架构总览

OpenClaw 采用“TypeScript 核心编排 + 原生平台桥接（Swift/Kotlin）”的分层架构：

• TypeScript：负责 AI Agent 主流程（对话编排、工具调用、记忆管理、状态机）。
• Swift/Kotlin：负责移动端原生能力（系统 API、权限、后台任务等）并通过桥接层暴露给 TS。
• UI 层：负责会话交互、结果流式渲染、执行状态可视化。
• 基础设施：日志、错误处理、配置、密钥管理、安全策略。

2. 核心模块

1. Orchestrator（编排器）

   • 组织上下文与提示词
   • 决策是否调用工具
   • 管理多轮“模型-工具-模型”循环

2. LLM Adapter（模型适配层）

   • 屏蔽不同 Provider 差异
   • 提供统一请求/流式输出接口
   • 处理重试、超时和 fallback

3. Tool Runtime（工具运行时）

   • 工具注册与参数校验
   • 权限控制与危险操作确认
   • 标准化结果回传

4. Memory & Session（记忆与会话状态）

   • 短期会话上下文
   • 长期偏好/历史摘要（可选）
   • 状态机驱动执行阶段切换

5. Native Bridge（原生桥接）

   • TS 与 Swift/Kotlin 双向通信
   • 错误码、线程、序列化统一

3. 底层执行流程

• 用户输入请求
• 编排器构造上下文并调用模型
• 模型返回直接答案或工具调用意图
• 运行时执行工具（必要时通过原生桥接）
• 工具结果灌回给模型做最终整合
• 将最终结果流式返回给 UI，并记录日志

flowchart TD
    A[用户输入] --> B[UI层: 会话请求事件]
    B --> C[Orchestrator: 上下文构建/任务编排]
    C --> D[LLM Adapter: 调用模型API]

    D --> E{模型输出类型}
    E -- 直接回答 --> F[流式响应聚合]
    E -- 工具调用 --> G[Tool Runtime: 参数校验/权限检查]

    G --> H{工具类型}
    H -- TS本地工具 --> I[执行工具逻辑]
    H -- 系统原生能力 --> J[Native Bridge]
    J --> K[Swift/Kotlin 原生模块执行]

    I --> L[结构化工具结果]
    K --> L
    L --> M[结果回灌上下文]
    M --> D

    F --> N[输出给UI并展示]
    D -->|最终整合后输出| N

    N --> O[日志/Trace/状态持久化]

4. 设计原则

• 业务核心跨平台复用
• 平台能力最小封装、清晰边界
• 工具与模型解耦、便于扩展
• 全链路可观测、可回放、可审计

5. 总结

• 跨平台一致性：业务逻辑集中在 TypeScript，一次实现多端复用。
• 原生能力可扩展：Swift/Kotlin 只负责系统能力，边界清晰。
• Agent 可进化：工具层与模型层解耦，替换模型或新增工具成本低。
• 去中心化： 结构清晰，可自行复刻并运行自己的“小龙虾”。