AI Agent 运行时架构解析

OpenClaw：一个 AI Agent 框架的分层解剖

核心理念：分层隔离，职责单一

一个生产级的 AI Agent 框架，本质上是一套关注点分离的工程实践。用户看到的是"和 AI 对话"，框架内部却在协调五个截然不同的层次：接入层、控制层、智能层、能力层、执行层。每一层只做自己该做的事，层与层之间通过标准接口通信。

这种分层思想并不新鲜——它和经典的 OSI 网络模型、MVC 架构一脉相承。新鲜的是：当 LLM 成为核心决策单元后，如何在它的上下游构建可靠的工程脚手架。

OpenClaw 五层架构全景

flowchart LR
    subgraph ChatChannels["💬 ChatChannels\n接入层"]
        WhatsApp["WhatsApp"]
        Telegram["Telegram"]
    end

    subgraph ControlPlane["🔀 OpenClawGateway\nControlPlane 控制层"]
        SessionRouter["SessionRouter"]
        Config["Config\n(openclaw.json)"]
        WSServer["WSServer\n(18789)"]
    end

    subgraph AgentLayer["🧠 AgentLayer\n智能层"]
        PIAgentRuntime["PIAgentRuntime"]
        Sessions["Sessions\n(main/group)"]
        SkillsRegistry["SkillsRegistry\n(ClawHub+Workspace)"]
    end

    subgraph LLMProviders["☁️ LLMProviders\nLLM 提供商"]
        AnthropicClaude["AnthropicClaude"]
        OpenAI["OpenAI"]
        CNModels["CNModels\n(DeepSeek/Qwen/etc.)"]
    end

    subgraph ToolsLayer["🔧 ToolsLayer\n工具层"]
        BrowserTool["BrowserTool\n(Chromium)"]
        SystemRun["SystemRun\n(Shell/FS)"]
        CronJobs["CronJobs"]
        Webhooks["Webhooks"]
    end

    subgraph DeviceNodes["📱 DeviceNodes\n设备节点"]
        macOSNode["macOSNode"]
        IOSNode["IOSNode"]
        AndroidNode["AndroidNode"]
    end

    ChatChannels --> ControlPlane
    ControlPlane --> AgentLayer
    AgentLayer --> LLMProviders
    AgentLayer --> ToolsLayer
    ToolsLayer --> DeviceNodes

    style ChatChannels fill:#fff9c4
    style ControlPlane fill:#fff9c4
    style AgentLayer fill:#fff9c4
    style LLMProviders fill:#fff9c4
    style ToolsLayer fill:#fff9c4
    style DeviceNodes fill:#fff9c4

五层职责对比

层次	核心职责	关键组件	设计要点
💬 ChatChannels	多渠道消息接入	WhatsApp、Telegram	屏蔽渠道差异，统一消息格式
🔀 ControlPlane	会话路由与配置管理	SessionRouter、WSServer(18789)	单一入口，配置驱动（openclaw.json）
🧠 AgentLayer	智能决策核心	PIAgentRuntime、SkillsRegistry	技能注册表连接 ClawHub 与本地 Workspace
☁️ LLMProviders	模型调用抽象	Claude、OpenAI、国产模型	多模型适配，避免厂商锁定
🔧 ToolsLayer	真实世界能力执行	Browser、Shell/FS、CronJobs	Agent 的"手脚"，工具调用的落地层
📱 DeviceNodes	跨平台设备执行	macOS、iOS、Android	工具层的物理延伸，实现跨设备操作

关键设计决策解读

为什么 ControlPlane 独立于 AgentLayer？

ControlPlane 处理的是会话管理（谁在说话、说到哪了），AgentLayer 处理的是智能决策（该怎么回答）。两者的变化频率和扩展方向完全不同：前者随渠道增加而扩展，后者随模型能力提升而演进。强行耦合会导致"换个 LLM 要改路由逻辑"的荒谬局面。

为什么 ToolsLayer 和 DeviceNodes 分离？

工具的定义（BrowserTool 能做什么）和工具的执行环境（在哪台设备上跑）是两个正交维度。分离后，同一个 CronJob 工具可以在 macOS 节点或 Android 节点上执行，无需为每个设备重写工具逻辑。

---

Agentic Loop：AI Agent 的心跳

核心理念：循环是智能的本质

如果说五层架构是 Agent 的骨架，那么 Agentic Loop 就是它的心跳。

一个 LLM 的单次调用是无状态的——它接收输入、产生输出、然后结束。但真实世界的任务需要多步推理、工具调用、结果验证、再次推理。Agentic Loop 正是将这个"单次调用"变成"持续循环"的工程机制：只要 LLM 还想调用工具，循环就不停止；直到 LLM 决定输出最终文本，循环才结束。

这个设计的深刻之处在于：决策权在 LLM，而非框架。框架只负责忠实地执行 LLM 的意图，不预设任务步骤数。

完整消息流：从用户输入到最终回复

flowchart TD
    User(["👤 用户\n(Telegram/Discord 等)"])
    ChannelAdapter1["渠道适配器\n（标准化消息，提取附件）"]
    GatewayServer["Gateway Server\n网关服务器（协调器）\n将消息路由到正确的会话"]
    SessionRouter["会话路由器"]
    LaneQueue["Lane 队列\n（会话控制层）"]

    subgraph AgentRunner["🧠 Agent Runner 智能体运行器"]
        ModelParser["模型解析器"]
        SystemPromptBuilder["System Prompt 构建器\n(tools, skills, memory)"]
        SessionHistoryLoader["Session 历史加载器"]
        ContextWindowGuard["Context Window Guard\n上下文窗口守卫（必要时压缩）"]
        ModelParser --- SystemPromptBuilder --- SessionHistoryLoader
        ModelParser --> ContextWindowGuard
        SystemPromptBuilder --> ContextWindowGuard
        SessionHistoryLoader --> ContextWindowGuard
    end

    LLMAPI["LLM API"]

    subgraph AgenticLoop["🔄 Agentic Loop 智能体循环"]
        LLMResponse["LLM 响应"]
        ToolCallCheck{"tool call?"}
        Execute["执行工具"]
        FinalText["Final Text 最终文本"]
        ToolA["Tool A"]
        ToolB["Tool B"]
        ToolC["Tool C"]
        ToolD["Tool D"]
        LLMResponse --> ToolCallCheck
        ToolCallCheck -->|"是"| Execute
        ToolCallCheck -->|"否"| FinalText
        Execute --> ToolA & ToolB & ToolC & ToolD
        Execute -->|"结果回注"| LLMResponse
    end

    subgraph ResponsePath["📤 Response Path 回复路径"]
        StreamChunker["流式分块"]
        ChannelAdapter2["渠道适配器"]
        StreamChunker --> ChannelAdapter2
    end

    User -->|"消息"| ChannelAdapter1
    ChannelAdapter1 --> GatewayServer
    GatewayServer --> SessionRouter
    SessionRouter --> LaneQueue
    LaneQueue --> AgentRunner
    AgentRunner --> LLMAPI
    LLMAPI --> AgenticLoop
    AgenticLoop -->|"Final Text"| ResponsePath
    ResponsePath --> User
    AgentRunner <-->|"上下文压缩/重建"| ContextWindowGuard

    style AgentRunner fill:#1a1a2e,color:#ffffff
    style AgenticLoop fill:#1a1a2e,color:#ffffff
    style ResponsePath fill:#1a1a2e,color:#ffffff
    style GatewayServer fill:#2d2d2d,color:#ffffff

六个核心模块的职责拆解

1. 渠道适配器（Channel Adapter）

入口处的标准化层。无论用户通过 Telegram 发来图片、Discord 发来 Markdown、还是 Slack 发来 @mention，渠道适配器都将其转换为框架内部统一的消息格式。

这是**防腐层（Anti-Corruption Layer）**的经典应用：外部世界的混乱不应该污染内部系统的整洁。

2. Gateway Server（网关服务器）

会话的交通指挥官。核心职责是"将消息路由到正确的会话"——听起来简单，实则复杂：

• 同一个用户可能有多个并发会话（主会话 + 群组会话）
• 消息需要按会话隔离，不能串台
• Lane 队列提供背压控制，防止消息洪峰压垮 Agent Runner

3. Agent Runner（智能体运行器）

上下文的组装工厂，也是整个架构中最复杂的模块。每次调用 LLM 之前，它需要：

子组件	职责	类比
模型解析器	根据任务选择合适的 LLM	派单系统
System Prompt 构建器	组装工具列表、技能说明、记忆摘要	给员工发工作手册
Session 历史加载器	加载本次会话的对话历史	翻看会议记录
Context Window Guard	监控 Token 用量，必要时压缩历史	会议室容量管理员

Context Window Guard 是最容易被忽视却最关键的组件。LLM 的上下文窗口是有限资源，长对话必然触顶。Guard 的策略通常是：保留最近 N 轮对话 + 对早期历史做摘要压缩，在"记得住"和"放得下"之间找平衡。

4. Agentic Loop（智能体循环）

框架的心跳，也是"智能"真正发生的地方：

LLM 响应
    ↓
是否包含 tool_call？
    ├── 是 → 执行对应工具 → 将结果追加到消息历史 → 再次调用 LLM
    └── 否 → 输出 Final Text → 退出循环

这个循环的优雅之处在于：工具执行结果会作为新的上下文回注给 LLM，LLM 基于新信息做出下一步决策。这正是 ReAct（Reasoning + Acting）范式的工程实现。

多个工具（Tool A/B/C/D）可以并行执行——当 LLM 在一次响应中请求多个独立工具调用时，框架无需串行等待，可以并发执行后统一回注结果，显著降低延迟。

5. Response Path（回复路径）

出口处的用户体验层。Final Text 不是直接发给用户的，而是经过：

• 流式分块（Stream Chunker）：将完整响应切成小块，实现"打字机效果"，降低用户感知延迟
• 渠道适配器：将内部格式转换回目标渠道的消息格式（Telegram Markdown、Discord Embed 等）

注意这里的渠道适配器和入口处是同一个组件的两个方向——这是双向适配器模式，入口标准化、出口还原化。

---

两张图的本质关联

第一张图（OpenClaw 五层架构）回答的是：系统由哪些部分组成？

第二张图（Agentic Loop 消息流）回答的是：一条消息是如何在系统中流动的？

两者的关系是静态结构与动态行为的互补：

静态视角（OpenClaw 架构）
    ChatChannels → ControlPlane → AgentLayer → LLMProviders/ToolsLayer → DeviceNodes
                                      ↕
动态视角（Agentic Loop 消息流）
    用户 → 渠道适配器 → Gateway → Agent Runner → LLM API → Agentic Loop → Response Path → 用户

AgentLayer 在静态视角中是一个方框，在动态视角中展开为 Agent Runner + Agentic Loop 的完整机制。架构图告诉你有什么，时序图告诉你发生了什么——两种视角缺一不可。

---

深层反思：为什么 Agentic Loop 是不可绕过的设计

✅ 它解决了 LLM 的根本局限

LLM 本身是无状态的函数：f(context) → response。它不能主动发起网络请求，不能记住上次对话，不能执行代码。Agentic Loop 通过外部状态管理 + 工具执行 + 历史注入，将无状态函数变成了有状态的智能体。

✅ 它保持了 LLM 的决策主权

框架不预设"这个任务需要几步"。LLM 自己决定何时调用工具、调用哪个工具、何时停止。这意味着同一个框架可以处理"查一下天气"（1次工具调用）和"帮我写一个完整的 Web 应用并部署"（数十次工具调用）——复杂度由任务决定，而非框架硬编码。

⚠️ 它也带来了新的工程挑战

挑战	根因	应对策略
无限循环风险	LLM 可能陷入"调用工具 → 结果不满意 → 再调用"的死循环	设置最大迭代次数上限
上下文爆炸	每次工具调用都会增加历史长度，最终超出窗口	Context Window Guard 压缩策略
工具调用失败	外部工具不可靠，网络超时、权限不足等	重试机制 + 错误信息回注给 LLM
成本失控	多轮调用 = 多倍 Token 消耗	预算上限 + 轻量模型处理简单步骤

最终洞察

Agentic Loop 的本质是一个反馈控制系统：LLM 是控制器，工具是执行器，工具结果是传感器反馈，最终文本是系统稳定后的输出。这和工业控制系统的 PID 控制器、生物体的神经反射弧，在结构上惊人地相似。

AI Agent 框架的成熟标志，不是支持多少种工具，而是在 Loop 失控时能否优雅降级——这才是工程可靠性的真正考验。