03 · 流程图
运行时结构 · 状态机 · 核心流程
OpenClaw 的核心是一个持久化 TypeScript 进程（Gateway），通过 WebSocket 18789 接收所有消息，路由到 Agent 循环执行，写回 Markdown 记忆文件。
Gateway 启动流程
entry.ts 是 CLI 入口，依次完成 Compile Cache 预热、respawn 检查、插件加载、WebSocket 服务启动，最后激活所有已配置渠道的监听器。
flowchart TD
A([🦞 openclaw onboard --install-daemon]) --> B[entry.ts: process.title = openclaw]
B --> C[enableOpenClawCompileCache\n编译缓存预热]
C --> D{buildCliRespawnPlan\n需要 Respawn?}
D -->|是| E[重新启动进程\n应用环境变量]
D -->|否| F[runCli: 解析 argv]
E --> F
F --> G[加载 ~/.openclaw/openclaw.json\n解析配置]
G --> H[初始化 Plugin Registry\n加载 extensions/ 插件]
H --> I[启动 WebSocket Server\nlocalhost:18789]
I --> J[加载工作区文件\nSOUL.md / MEMORY.md / AGENTS.md]
J --> K[激活渠道监听器\nSlack / Telegram / Discord…]
K --> L[启动 Cron 任务调度器\n定时/主动执行]
L --> M[启动性能追踪\nOPENCLAW_GATEWAY_STARTUP_TRACE]
M --> N([✅ Gateway Ready — 等待消息])
style A fill:#1a0a0a,stroke:#dc2626,color:#f87171
style N fill:#0d1a0d,stroke:#22c55e,color:#86efac
style D fill:#1a1030,stroke:#a855f7,color:#d8b4fe
消息处理全链路流程
消息从任一渠道进入 Gateway，经过 Auth 验证、Allowlist 检查、路由决策，最终到达对应 Agent 的推理循环，回复通过原渠道发回。
flowchart TD
IN([📨 消息抵达\nSlack / Telegram / WhatsApp / …]) --> TRANSPORT[渠道 Transport 接收\nPlugin 解析消息格式]
TRANSPORT --> INBOUND[Inbound Event 处理\n统一消息结构]
INBOUND --> AUTH{Auth 检查\n发送者已知?}
AUTH -->|未知发送者| PAIR[发送配对码\n等待审批]
PAIR -->|审批通过| ALLOW
PAIR -->|拒绝/超时| DROP[丢弃消息]
AUTH -->|已知/已配对| ALLOW[Allowlist 检查\n是否有权发消息?]
ALLOW -->|拒绝| DENY[忽略消息]
ALLOW -->|通过| ROUTE[Routing: resolve-route\n确定目标 Agent]
ROUTE --> SESSION{Session Key\n会话存在?}
SESSION -->|新会话| SPAWN[Spawn Agent\n加载 Workspace Context]
SESSION -->|已有会话| EXISTING[复用现有 Agent Session]
SPAWN & EXISTING --> AGENT_LOOP[进入 Agent 推理循环]
AGENT_LOOP --> RESPONSE[生成回复]
RESPONSE --> SEND[通过原渠道发回\nTransport.send]
SEND --> MEMORY_WRITE[追加到今日日志\nYYYY-MM-DD.md]
MEMORY_WRITE --> DONE([✅ 消息处理完成])
style IN fill:#0d1220,stroke:#3b82f6,color:#93c5fd
style DONE fill:#0d1a0d,stroke:#22c55e,color:#86efac
style AUTH fill:#1a1030,stroke:#a855f7,color:#d8b4fe
style SESSION fill:#1a1030,stroke:#a855f7,color:#d8b4fe
style DROP fill:#1a0808,stroke:#6b7280,color:#9ca3af
style DENY fill:#1a0808,stroke:#6b7280,color:#9ca3af
Agent 推理循环（ReAct Loop）
OpenClaw 的 Agent 实现标准的 ReAct 模式：读取记忆上下文 → 调用 LLM（流式）→ 解析工具调用 → 执行 → 结果回传，直到 LLM 输出最终答案。
flowchart TD
START([收到用户消息]) --> CONTEXT[构建上下文\n加载 SOUL.md + MEMORY.md\n昨日 + 今日日志]
CONTEXT --> SKILL_INJ[注入 Skills\nSKILL.md 文件描述可用能力]
SKILL_INJ --> PROMPT[构建 System Prompt\n人格 + 记忆 + 工具列表]
PROMPT --> LLM[调用 LLM Provider\n流式输出]
LLM --> PARSE{解析 LLM 输出}
PARSE -->|text delta| STREAM[流式推送\n实时回复用户]
STREAM --> PARSE
PARSE -->|tool_use| TOOL_REQ[工具调用请求\n解析 tool_name + args]
TOOL_REQ --> APPROVAL{需要用户审批?}
APPROVAL -->|危险操作\n/ 群组沙箱| ASK_USER[向用户请求审批\n等待确认]
ASK_USER -->|批准| EXEC
ASK_USER -->|拒绝| CANCEL[取消工具调用\n告知 LLM]
CANCEL --> LLM
APPROVAL -->|主会话\n低风险| EXEC[执行工具\n见工具执行流程]
EXEC --> RESULT[工具结果\n追加到上下文]
RESULT --> LLM
PARSE -->|thinking| THINK[内部推理\n/think level 控制深度]
THINK --> PARSE
PARSE -->|end_turn| FINAL[最终回复\n完整 response]
FINAL --> APPEND[追加到日志文件\nappend-only YYYY-MM-DD.md]
APPEND --> DONE([✅ 回复用户])
style START fill:#1a0a0a,stroke:#dc2626,color:#f87171
style DONE fill:#0d1a0d,stroke:#22c55e,color:#86efac
style PARSE fill:#1a1030,stroke:#a855f7,color:#d8b4fe
style APPROVAL fill:#1a1030,stroke:#a855f7,color:#d8b4fe
工具执行流程（三层扩展体系）
OpenClaw 的工具体系分三层：Tools（原子操作）→ Skills（Markdown 能力描述）→ Plugins（完整 npm 包）。执行时根据 Session 类型选择沙箱后端。
flowchart TD
REQ([LLM 发出 tool_use 请求]) --> LOOKUP[Tool Registry 查找\ntool_name → 实现]
LOOKUP --> SANDBOX{Session 类型\n/ 沙箱策略}
SANDBOX -->|主会话 Host| HOST[直接在宿主机执行\n完全访问权限]
SANDBOX -->|群组 / 多用户| DOCKER[Docker 沙箱\n隔离容器执行]
SANDBOX -->|远程 SSH| SSH[SSH 沙箱\n远程服务器执行]
SANDBOX -->|OpenShell| SHELL[OpenShell 沙箱\n受限 Shell]
subgraph TOOL_TYPES[工具类型]
T1[🖥️ Bash 执行\nbash-executor.ts\n支持审批工作流]
T2[📁 文件操作\n读写/列举/搜索]
T3[🌐 Web 工具\n搜索 + 抓取 + 浏览器]
T4[📅 Schedule/Cron\n定时 / 主动执行]
T5[🔌 MCP 工具\nModel Context Protocol]
T6[🎬 媒体生成\n图像/视频/音乐]
T7[💬 Channel 操作\n发送消息 / 管理会话]
end
HOST & DOCKER & SSH & SHELL --> TOOL_TYPES
T1 & T2 & T3 & T4 & T5 & T6 & T7 --> RESULT[工具执行结果]
RESULT --> SAFETY[安全检查\n输出过滤]
SAFETY --> RETURN([返回结果给 LLM])
style REQ fill:#1a1030,stroke:#a855f7,color:#d8b4fe
style RETURN fill:#0d1a0d,stroke:#22c55e,color:#86efac
style SANDBOX fill:#1a1030,stroke:#a855f7,color:#d8b4fe
三层扩展体系：
Tools — 带类型的 TypeScript 函数，代表原子操作（文件 / API）
Skills — Markdown 文件描述能力和触发条件（
Plugins — 完整 npm 包，支持复杂逻辑和外部依赖
Tools — 带类型的 TypeScript 函数，代表原子操作（文件 / API）
Skills — Markdown 文件描述能力和触发条件（
~/.openclaw/workspace/skills/<skill>/SKILL.md）Plugins — 完整 npm 包，支持复杂逻辑和外部依赖
记忆读写流程
OpenClaw 使用极简的纯 Markdown 记忆系统，无向量数据库，无嵌入。所有记忆可 grep 审计，完全透明可读。
flowchart LR
subgraph READ[读取阶段（构建上下文）]
direction TB
SOUL[SOUL.md\n人格 + 行为边界]
AGENTS_MD[AGENTS.md\nAgent 配置说明]
TOOLS_MD[TOOLS.md\n工具使用规则]
MEMORY_MD[MEMORY.md\n精选长期记忆]
YESTERDAY[昨日日志\nYYYY-MM-DD.md]
TODAY[今日日志\nYYYY-MM-DD.md\n实时追加]
end
subgraph INJECT[注入到 System Prompt]
CTX[完整上下文\n人格 + 记忆 + 今日历史]
end
subgraph WRITE[写入阶段（对话后）]
direction TB
APPEND[追加到今日日志\nappend-only]
COMPACT[/compact 命令\n压缩历史]
CURATE[用户/Agent 编辑\nMEMORY.md 精选内容]
end
READ --> INJECT --> LLM[LLM 推理]
LLM --> WRITE
COMPACT --> MEMORY_MD2[更新 MEMORY.md\n长期记忆]
style LLM fill:#1a0a0a,stroke:#dc2626,color:#f87171
设计哲学：「没有向量数据库，没有 Embeddings，纯 Markdown 文件。」工程师可以用 grep 直接审计记忆，理解 Agent 如何召回信息。
文件位置：
文件位置：
~/.openclaw/workspace/Auth 鉴权 & 设备配对流程
Gateway 实现两层鉴权：WebSocket 连接层（Token）和消息层（发送者配对）。群组场景下新成员需通过配对码审批。
sequenceDiagram
participant Device as 新设备 / App
participant GW as Gateway (WS :18789)
participant Owner as 机器拥有者
Device->>GW: WebSocket connect
GW->>GW: auth-token-resolution\n验证连接 Token
alt Token 有效
GW-->>Device: ✅ 连接建立
else 无 Token / 无效
GW-->>Device: ❌ 拒绝连接
end
Note over Device,GW: 消息层鉴权（auth_mode=pairing）
Device->>GW: 发送消息（首次）
GW->>GW: auth-resolve: 发送者未知
GW-->>Device: 发送配对码（6位）
GW-->>Owner: 通知：有新设备请求配对
Owner->>GW: /approve 或 /deny
alt 批准
GW->>GW: 将设备加入 Allowlist
GW-->>Device: ✅ 配对成功，可以使用
else 拒绝
GW-->>Device: ❌ 配对被拒绝
end
Note over Device,GW: auth_mode=open 时跳过配对直接通过
Plugin 生命周期状态机
所有扩展插件（extensions/ 目录）遵循相同的生命周期：Discover → Register → Activate → Running，支持热重载和健康监控。
stateDiagram-v2
[*] --> Discovered : Gateway 启动\n扫描 extensions/
Discovered --> Registered : 验证 plugin-package-contract\nManifest 格式合法
Registered --> Activating : Gateway 调用 activate()\n注入 plugin-sdk API
Activating --> Active : activate() 成功\n能力注册到 Registry
Activating --> Failed : activate() 抛出异常\n或超时
Active --> Running : 首次调用\n（渠道/工具/LLM）
Running --> Active : 调用完成\n返回 Idle
Active --> Deactivating : Config 热重载\n或 shutdown
Deactivating --> [*] : cleanup() 完成\n资源释放
Failed --> Registered : 重试\n/doctor repair-flow
note right of Active
能力已注册：
- LLM Provider
- 渠道 Transport
- 工具函数
- 记忆后端
end note
note right of Running
热路径传递：
provider_id
model_ref
channel_id
capability_family
end note
Config 热重载流程
修改 openclaw.json 后，Gateway 无需重启即可应用新配置。通过 Diff + Plan + Apply 三步确保安全切换，最小化服务中断。
flowchart TD
CHANGE([📝 openclaw.json 文件变更]) --> DETECT[config-reload.ts\n文件监听器触发]
DETECT --> DIFF[config-diff.ts\n计算新旧配置差异]
DIFF --> PLAN[config-reload-plan.ts\n生成重载计划\n确定影响范围]
PLAN --> SETTINGS[config-reload-settings.ts\n验证新配置合法性\nJSON Schema 校验]
SETTINGS --> VALID{配置有效?}
VALID -->|无效| ERROR[记录错误\n保留旧配置\n告知用户]
VALID -->|有效| APPLY[执行重载计划]
APPLY --> CHAN_RELOAD{渠道配置变更?}
CHAN_RELOAD -->|是| CHAN_RESTART[重启受影响渠道\nTransport 重连]
CHAN_RELOAD -->|否| SKIP_CHAN[跳过渠道重载]
APPLY --> MODEL_RELOAD{模型配置变更?}
MODEL_RELOAD -->|是| MODEL_SWITCH[切换 LLM Provider\n下次调用生效]
MODEL_RELOAD -->|否| SKIP_MODEL[跳过]
APPLY --> PLUGIN_RELOAD{插件变更?}
PLUGIN_RELOAD -->|是| PLUGIN_CYCLE[Plugin Deactivate → Activate\n热重载插件]
PLUGIN_RELOAD -->|否| SKIP_PLUGIN[跳过]
CHAN_RESTART & SKIP_CHAN & MODEL_SWITCH & SKIP_MODEL & PLUGIN_CYCLE & SKIP_PLUGIN --> DONE([✅ 重载完成\n无需重启 Gateway])
style CHANGE fill:#0d1a20,stroke:#14b8a6,color:#5eead4
style DONE fill:#0d1a0d,stroke:#22c55e,color:#86efac
style VALID fill:#1a1030,stroke:#a855f7,color:#d8b4fe
style ERROR fill:#1a0808,stroke:#ef4444,color:#fca5a5
并发运行时结构：Gateway 进程内同时运行：渠道监听器（50+ 渠道）、Agent Session（按需创建）、Cron 调度器、健康检查 Doctor、Config 文件监听器——所有任务共享同一 Node.js 事件循环，通过 async/await 协作调度。