813 lines
22 KiB
Markdown
813 lines
22 KiB
Markdown
# OpenClaw 架构蓝图
|
||
|
||
> 完整的系统架构可视化
|
||
|
||
---
|
||
|
||
## 1. 整体系统架构
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "客户端层 Clients"
|
||
APP1[macOS App]
|
||
APP2[iOS App]
|
||
APP3[Android App]
|
||
UI[Web UI]
|
||
CLI[CLI Tool]
|
||
NODES[Nodes<br/>macOS/iOS/Android]
|
||
end
|
||
|
||
subgraph "网关层 Gateway (18789)"
|
||
WS[WebSocket Server]
|
||
HTTP[HTTP Server]
|
||
PROTO[Protocol Validator<br/>AJV]
|
||
CHANNELS[Channel Manager]
|
||
EVENTS[Event Dispatcher]
|
||
METHODS[Method Handlers]
|
||
CRON[Cron Service]
|
||
CANVAS["Canvas Host<br/>a2ui (18793)"]
|
||
end
|
||
|
||
subgraph "通道层 Channels"
|
||
WA[WhatsApp Web<br/>Baileys]
|
||
TG[Telegram<br/>grammY]
|
||
DC[Discord]
|
||
SL[Slack]
|
||
SG[Signal]
|
||
IM[iMessage]
|
||
LN[LINE]
|
||
GO[Google Chat]
|
||
MS[MS Teams]
|
||
EXT[Extensions<br/>Matrix/Zalo/etc]
|
||
end
|
||
|
||
subgraph "Agent 层"
|
||
ROUTER[Message Router<br/>Bindings]
|
||
SESSION[Session Manager]
|
||
AGENT[Agent Runtime]
|
||
TOOLS[Tool Execution]
|
||
MEMORY[Memory Store]
|
||
PROVIDERS[Model Providers<br/>OpenAI/Anthropic/etc]
|
||
end
|
||
|
||
subgraph "基础设施层Infrastructure"
|
||
MEDIA[Media Pipeline<br/>Store/Fetch/Process]
|
||
CONFIG[Config System<br/>JSON5/Zod]
|
||
PAIRING[Device Pairing]
|
||
AUTH[Authentication]
|
||
LOGS[Logging System]
|
||
DIAG[Diagnostic Events]
|
||
end
|
||
|
||
subgraph "扩展层Plugins"
|
||
PLUGINSDK[Plugin SDK]
|
||
CHANNEL_PLG[Channel Plugins]
|
||
MEMORY_PLG[Memory Plugins]
|
||
PROVIDER_PLG[Provider Plugins]
|
||
HOOKS[Lifecycle Hooks]
|
||
end
|
||
|
||
%% 连接关系
|
||
APP1 -->|WebSocket| WS
|
||
APP2 -->|WebSocket| WS
|
||
APP3 -->|WebSocket| WS
|
||
UI -->|WebSocket| WS
|
||
CLI -->|WebSocket| WS
|
||
NODES -->|WebSocket| WS
|
||
|
||
WS --> PROTO
|
||
PROTO --> METHODS
|
||
PROTO --> EVENTS
|
||
|
||
HTTP --> METHODS
|
||
|
||
METHODS --> CHANNELS
|
||
METHODS --> ROUTER
|
||
METHODS --> CONFIG
|
||
METHODS --> MEDIA
|
||
|
||
CHANNELS --> WA
|
||
CHANNELS --> TG
|
||
CHANNELS --> DC
|
||
CHANNELS --> SL
|
||
CHANNELS --> SG
|
||
CHANNELS --> IM
|
||
CHANNELS --> LN
|
||
CHANNELS --> GO
|
||
CHANNELS --> MS
|
||
CHANNELS --> EXT
|
||
|
||
CHANNELS -.->|事件| EVENTS
|
||
EVENTS -.->|广播| WS
|
||
|
||
CRON -.->|触发| EVENTS
|
||
|
||
WA -->|入站| CHANNELS
|
||
TG -->|入站| CHANNELS
|
||
DC -->|入站| CHANNELS
|
||
SL -->|入站| CHANNELS
|
||
SG -->|入站| CHANNELS
|
||
IM -->|入站| CHANNELS
|
||
LN -->|入站| CHANNELS
|
||
GO -->|入站| CHANNELS
|
||
MS -->|入站| CHANNELS
|
||
EXT -->|入站| CHANNELS
|
||
|
||
CHANNELS -->|路由| ROUTER
|
||
ROUTER --> AGENT
|
||
|
||
AGENT --> TOOLS
|
||
AGENT --> MEMORY
|
||
AGENT --> PROVIDERS
|
||
|
||
AGENT -->|出站| CHANNELS
|
||
AGENT -.->|事件| EVENTS
|
||
|
||
SESSION -->|持久化| ROUTER
|
||
|
||
METHODS --> MEDIA
|
||
CONFIG -->|加载| CHANNELS
|
||
CONFIG -->|加载| ROUTER
|
||
|
||
WS --> AUTH
|
||
PAIRING --> AUTH
|
||
|
||
LOGS -->| everywhere | *
|
||
DIAG -->| everywhere | *
|
||
|
||
PLUGINSDK --> CHANNEL_PLG
|
||
PLUGINSDK --> MEMORY_PLG
|
||
PLUGINSDK --> PROVIDER_PLG
|
||
|
||
CHANNEL_PLG --> CHANNELS
|
||
MEMORY_PLG --> MEMORY
|
||
PROVIDER_PLG --> PROVIDERS
|
||
|
||
HOOKS --> AGENT
|
||
HOOKS --> CHANNELS
|
||
HOOKS --> EVENTS
|
||
|
||
style Gateway fill:#e1f5fe
|
||
style Clients fill:#f3e5f5
|
||
style Channels fill:#fff3e0
|
||
style Agent fill:#e8f5e9
|
||
style Infrastructure fill:#fce4ec
|
||
style Plugins fill:#fff9c4
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Gateway 详细架构
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "Gateway Server：端口 18789"
|
||
ENTER[客户端连接] --> WS_CONN
|
||
|
||
subgraph "WebSocket 层"
|
||
WS_CONN[WebSocket Server]
|
||
WS_HANDLER[WS Handler]
|
||
FRAME_PARSER[Frame Parser]
|
||
FRAME_VALIDATOR[Frame Validator<br/>JSON Schema]
|
||
end
|
||
|
||
subgraph "连接管理 Connect Management"
|
||
HELLO[req:connect]
|
||
AUTH_CHECK[Auth Check<br/>Token Check]
|
||
PAIRING_CHECK[Pairing Check<br/>Device Approval]
|
||
CLIENT_REGISTRY[Client Registry]
|
||
end
|
||
|
||
subgraph "方法层 Method Layer"
|
||
METHOD_DISPATCH[Method Dispatcher]
|
||
CORE_HANDLERS[Core Handlers<br/>health/status/send/agent]
|
||
GATEWAY_METHODS[Gateway Methods<br/>channels.* / media.*]
|
||
PLUGIN_METHODS[Plugin Methods]
|
||
end
|
||
|
||
subgraph "状态层 State Layer"
|
||
RUNTIME_STATE[Runtime State<br/>健康查看 / 缓冲]
|
||
CHANNEL_STATE[Channel State<br/>运行时实例]
|
||
NODE_REGISTRY[Node Registry]
|
||
end
|
||
|
||
subgraph "事件层 Event Layer"
|
||
EVENT_EMITTER[Event Emitter]
|
||
AGENT_EVENTS[agent Events]
|
||
CHAT_EVENTS[chat Events]
|
||
PRESENCE_EVENTS[presence Events]
|
||
HEARTBEAT[heartbeat Events]
|
||
DIAGNOSTICS[diagnostic Events]
|
||
end
|
||
|
||
subgraph "资源层 Resource Layer"
|
||
CONFIG_RELOAD[Config Reloader]
|
||
CHANNEL_MANAGER[Channel Manager]
|
||
CANVAS_HOST[Canvas Host<br/>a2ui:18793]
|
||
MEDIA_SERVER[Media Server]
|
||
CRON_SCHEDULER[Cron Scheduler]
|
||
end
|
||
end
|
||
|
||
%% 连接关系
|
||
WS_CONN --> WS_HANDLER
|
||
WS_HANDLER --> FRAME_PARSER
|
||
FRAME_PARSER --> FRAME_VALIDATOR
|
||
|
||
FRAME_VALIDATOR --> HELLO
|
||
FRAME_VALIDATOR --> METHOD_DISPATCH
|
||
|
||
HELLO --> AUTH_CHECK
|
||
AUTH_CHECK --> PAIRING_CHECK
|
||
PAIRING_CHECK --> CLIENT_REGISTRY
|
||
CLIENT_REGISTRY --> RUNTIME_STATE
|
||
|
||
METHOD_DISPATCH --> CORE_HANDLERS
|
||
METHOD_DISPATCH --> GATEWAY_METHODS
|
||
METHOD_DISPATCH --> PLUGIN_METHODS
|
||
|
||
CORE_HANDLERS -->|使用| RUNTIME_STATE
|
||
CORE_HANDLERS -->|使用| CHANNEL_STATE
|
||
CORE_HANDLERS -->|使用| CHANNEL_MANAGER
|
||
|
||
GATEWAY_METHODS --> CHANNEL_MANAGER
|
||
GATEWAY_METHODS --> MEDIA_SERVER
|
||
GATEWAY_METHODS --> NODE_REGISTRY
|
||
|
||
CHANNEL_MANAGER --> CHANNEL_STATE
|
||
CHANNEL_MANAGER -->|启动/停止| WA_SVC
|
||
CHANNEL_MANAGER -->|启动/停止| TG_SVC
|
||
CHANNEL_MANAGER -->|启动/停止| DC_SVC
|
||
|
||
RLGA_EVENTS -.->|广播| WS_HANDLER
|
||
HEARTBEAT -.->|广播| WS_HANDLER
|
||
DIAGNOSTICS -.->|广播| WS_HANDLER
|
||
|
||
CONFIG_RELOAD -.->|通知| CORE_HANDLERS
|
||
CONFIG_RELOAD -.->|通知| CHANNEL_MANAGER
|
||
|
||
CRON_SCHEDULER -.->|触发| EVENT_EMITTER
|
||
CRON_SCHEDULER -.->|触发| CANVAS_HOST
|
||
|
||
subgraph "外部服务 External Services"
|
||
WA_SVC[WhatsApp Service]
|
||
TG_SVC[Telegram Service]
|
||
DC_SVC[Discord Service]
|
||
end
|
||
|
||
style GatewayServer fill:#e1f5fe
|
||
style WebSocket层 fill:#e3f2fd
|
||
style MethodLayer fill:#bbdefb
|
||
style StateLayer fill:#90caf9
|
||
style EventLayer fill:#64b5f6
|
||
style ResourceLayer fill:#42a5f5
|
||
style ExternalServices fill:#ffecb3
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 消息流转图 Message Flow
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant USER as 用户
|
||
participant CH as 通道通道<br/>WhatsApp/Telegram/etc
|
||
participant GATEWAY as Gateway
|
||
participant ROUTER as Message Router
|
||
participant AGENT as Agent Runtime
|
||
participant PROVIDER as AI Provider
|
||
participant TOOLS as Tools
|
||
|
||
%% 入站消息流
|
||
USER->>CH: 发送消息
|
||
CH->>GATEWAY: 接入事件
|
||
GATEWAY->>ROUTER: 解析路由<br/>(channel/account/peer)
|
||
ROUTER-->>GATEWAY: 返回匹配结果<br/>(agentId, sessionKey)
|
||
GATEWAY->>AGENT: 调用 agent.execute
|
||
|
||
AGENT->>AGENT: 加载会话历史
|
||
AGENT->>AGENT: 构建系统提示
|
||
AGENT->>PROVIDER: 发起 LLM 调用
|
||
|
||
alt 需要工具调用
|
||
PROVIDER-->>AGENT: 返回 tool_calls
|
||
AGENT->>TOOLS: 执行工具
|
||
TOOLS-->>AGENT: 返回工具结果
|
||
AGENT->>PROVIDER: 继续调用 (with tool results)
|
||
end
|
||
|
||
PROVIDER-->>AGENT: 返回完整响应
|
||
AGENT->>AGENT: 更新会话历史
|
||
AGENT-->>GATEWAY: 返回响应 (events: agent)
|
||
|
||
GATEWAY->>CH: 发送消息 (channel.message.send)
|
||
CH->>USER: 接收回复
|
||
|
||
%% 出站消息流 (CLI/Web/App 触发)
|
||
rect rgb(255, 255, 200)
|
||
Note over GATEWAY,USER: 出站消息流 (从客户端触发)
|
||
USER->>GATEWAY: 调用 gateway.send
|
||
GATEWAY->>ROUTER: 解析路由
|
||
ROUTER-->>GATEWAY: 返回匹配结果
|
||
GATEWAY->>CH: 发送消息
|
||
CH->>USER: 接收消息
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 插件系统架构 Plugin System
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "插件 API Plugin SDK"
|
||
API[OpenClawPluginApi]
|
||
end
|
||
|
||
subgraph "插件运行时 Plugin Runtime"
|
||
RUNTIME[Plugin Runtime]
|
||
CONFIG_API[Config API<br/>loadConfig/writeConfigFile]
|
||
SYSTEM_API[System API<br/>enqueueSystemEvent]
|
||
MEDIA_API[Media API<br/>loadWebMedia/detectMime]
|
||
TTS_API[TTS API<br/>textToSpeechTelephony]
|
||
TOOLS_API[Tools API<br/>createMemoryGetTool]
|
||
CHANNEL_API[Channel API<br/>routing/network/session]
|
||
LOGGING_API[Logging API<br/>getChildLogger]
|
||
end
|
||
|
||
subgraph "注册接口 Registrations"
|
||
REG_TOOL[registerTool]
|
||
REG_HOOK[registerHook]
|
||
REG_HTTP[registerHttpRoute/registerHttpHandler]
|
||
REG_CHANNEL[registerChannel]
|
||
REG_GW_METHOD[registerGatewayMethod]
|
||
REG_CLI[registerCli]
|
||
REG_SERVICE[registerService]
|
||
REG_PROVIDER[registerProvider]
|
||
REG_CMD[registerCommand]
|
||
end
|
||
|
||
subgraph "钩子系统 Hook System"
|
||
H_BEFORE_AGENT[before_agent_start]
|
||
H_AFTER_AGENT[after_agent_start]
|
||
H_BEFORE_SEND[before_message_send]
|
||
H_AFTER_SEND[after_message_send]
|
||
H_RECEIVED[message_received]
|
||
H_TOOL[tool_called]
|
||
H_CONFIG[config_changed]
|
||
end
|
||
|
||
subgraph "插件类型 Plugin Types"
|
||
P_CHANNEL[Channel Plugin<br/>must implement ChannelPlugin]
|
||
P_MEMORY[Memory Plugin<br/>LanceDB/etc]
|
||
P_PROVIDER[Provider Plugin<br/>Custom AI API]
|
||
end
|
||
|
||
subgraph "插件生命周期 Plugin Lifecycle"
|
||
LOAD[loadPlugin]
|
||
VALIDATE[validateConfig]
|
||
REGISTER[register]
|
||
ACTIVATE[activate]
|
||
DISPOSE[dispose]
|
||
end
|
||
|
||
%% 连接关系
|
||
API --> RUNTIME
|
||
RUNTIME --> CONFIG_API
|
||
RUNTIME --> SYSTEM_API
|
||
RUNTIME --> MEDIA_API
|
||
RUNTIME --> TTS_API
|
||
RUNTIME --> TOOLS_API
|
||
RUNTIME --> CHANNEL_API
|
||
RUNTIME --> LOGGING_API
|
||
|
||
API --> REG_TOOL
|
||
API --> REG_HOOK
|
||
API --> REG_HTTP
|
||
API --> REG_CHANNEL
|
||
API --> REG_GW_METHOD
|
||
API --> REG_CLI
|
||
API --> REG_SERVICE
|
||
API --> REG_PROVIDER
|
||
API --> REG_CMD
|
||
|
||
REG_HOOK --> H_BEFORE_AGENT
|
||
REG_HOOK --> H_AFTER_AGENT
|
||
REG_HOOK --> H_BEFORE_SEND
|
||
REG_HOOK --> H_AFTER_SEND
|
||
REG_HOOK --> H_RECEIVED
|
||
REG_HOOK --> H_TOOL
|
||
REG_HOOK --> H_CONFIG
|
||
|
||
REG_CHANNEL --> P_CHANNEL
|
||
|
||
LOAD --> VALIDATE
|
||
VALIDATE --> REGISTER
|
||
REGISTER --> ACTIVATE
|
||
ACTIVATE --> DISPOSE
|
||
|
||
P_CHANNEL -.->|loose coupling| H_RECEIVED
|
||
P_CHANNEL -.->|loose coupling| H_BEFORE_SEND
|
||
|
||
style PluginSDK fill:#fff9c4
|
||
style PluginRuntime fill:#fff59d
|
||
style Registrations fill:#ffee58
|
||
style HookSystem fill:#fdd835
|
||
style PluginTypes fill:#fbc02d
|
||
style PluginLifecycle fill:#f9a825
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 路与绑定系统 Routing & Bindings
|
||
|
||
```mermaid
|
||
graph TD
|
||
subgraph "路由输入 Route Input"
|
||
CFG[User Config<br/>bindings 数组]
|
||
IN_CHANNEL[channel<br/>消息来源]
|
||
IN_ACCOUNT[accountId<br/>账户 ID]
|
||
IN_PEER[peer<br/>用户/组 ID]
|
||
IN_GUILD[guildId<br/>Discord 服务器]
|
||
IN_TEAM[teamId<br/>Slack/Teams]
|
||
end
|
||
|
||
subgraph "路由匹配优先级 Matching Priority"
|
||
P1[1. peer<br/>具体用户/组]
|
||
P2[2. peer.parent<br/>线程继承]
|
||
P3[3. guildId<br/>Discord 服务器]
|
||
P4[4. teamId<br/>Slack/Teams]
|
||
P5[5. account<br/>非通配符账户]
|
||
P6[6. account<br/>通配符账户]
|
||
P7[7. default<br/>默认绑定]
|
||
end
|
||
|
||
subgraph "路由输出 Route Output"
|
||
AGENT_ID[agentId<br/>目标 Agent]
|
||
SESSION_KEY[sessionKey<br/>会话唯一标识]
|
||
MAIN_KEY[mainSessionKey<br/>主会话]
|
||
MATCHED_BY[matchedBy<br/>匹配方式]
|
||
end
|
||
|
||
subgraph "会话管理 Session Management"
|
||
SESSION_STORE[Session Store<br/>~/.openclaw/sessions/]
|
||
SESSION_FILE[.jsonl 文件<br/>role/content/timestamp]
|
||
HISTORY[上下文历史<br/>消息 turnover]
|
||
end
|
||
|
||
%% 连接关系
|
||
CFG -->|解析| P1
|
||
IN_CHANNEL -->|输入| P1
|
||
IN_ACCOUNT -->|输入| P1
|
||
IN_PEER -->|输入| P1
|
||
IN_GUILD -->|输入| P1
|
||
IN_TEAM -->|输入| P1
|
||
|
||
P1 -->|无匹配| P2
|
||
P2 -->|无匹配| P3
|
||
P3 -->|无匹配| P4
|
||
P4 -->|无匹配| P5
|
||
P5 -->|无匹配| P6
|
||
P6 -->|无匹配| P7
|
||
|
||
P1 -->|匹配| AGENT_ID
|
||
P2 -->|匹配| AGENT_ID
|
||
P3 -->|匹配| AGENT_ID
|
||
P4 -->|匹配| AGENT_ID
|
||
P5 -->|匹配| AGENT_ID
|
||
P6 -->|匹配| AGENT_ID
|
||
P7 -->|匹配| AGENT_ID
|
||
|
||
AGENT_ID -->|构建| SESSION_KEY
|
||
AGENT_ID -->|构建| MAIN_KEY
|
||
P1 -->|设置| MATCHED_BY
|
||
P2 -->|设置| MATCHED_BY
|
||
P3 -->|设置| MATCHED_BY
|
||
P4 -->|设置| MATCHED_BY
|
||
P5 -->|设置| MATCHED_BY
|
||
P6 -->|设置| MATCHED_BY
|
||
P7 -->|设置| MATCHED_BY
|
||
|
||
SESSION_KEY -->|读写| SESSION_STORE
|
||
MAIN_KEY -->|读写| SESSION_STORE
|
||
|
||
SESSION_STORE -->|包含| SESSION_FILE
|
||
SESSION_FILE -->|构建| HISTORY
|
||
|
||
style RouteInput fill:#e8f5e9
|
||
style MatchingPriority fill:#c8e6c9
|
||
style RouteOutput fill:#a5d6a7
|
||
style SessionManagement fill:#81c784
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 媒体管道架构 Media Pipeline
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph "入站 Inbound"
|
||
A[收到媒体] --> B[parse<br/>提取媒体]
|
||
B --> C[mime.ts<br/>检测 MIME]
|
||
C -->|magic number<br/>+ content type| MIME_TYPE{MIME 类型?}
|
||
MIME_TYPE -->|image| D[store.ts<br/>保存到磁盘]
|
||
MIME_TYPE -->|audio| D
|
||
MIME_TYPE -->|video| D
|
||
MIME_TYPE -->|unknown| DROP[丢弃/警告]
|
||
end
|
||
|
||
subgraph "存储 Storage"
|
||
D --> STORAGE[~/.openclaw/media/inbound/]
|
||
STORAGE --> FILES["{original}---{uuid}.ext"]
|
||
end
|
||
|
||
subgraph "处理 Processing (可选)"
|
||
FILES --> E[image_ops.ts<br/>image/image-ops.ts]
|
||
E -->|resizeToJpeg| RESIZED[调整大小的 JPEG]
|
||
end
|
||
|
||
subgraph "出站 Outbound"
|
||
OUT_REQ[出站请求] --> OUT_MIME[mime.ts<br/>检测 MIME]
|
||
OUT_MIME -->|需要处理?| OUT_PROC[image_ops/audio.ts]
|
||
OUT_MIME -->|不需要处理| OUT_STORE[store.ts<br/>保存到磁盘]
|
||
OUT_PROC --> OUT_STORE
|
||
OUT_STORE --> OUT_STORAGE[~/.openclaw/media/outbound/]
|
||
end
|
||
|
||
subgraph "服务服务 & Fetch"
|
||
STORAGE --> HOST[host.ts<br/>HTTP 服务]
|
||
OUT_STORAGE --> HOST
|
||
HOST -->|GET /media/*| CLIENT[客户端]
|
||
FETCH[fetch.ts<br/>远程获取] --> STORAGE
|
||
end
|
||
|
||
style Inbound fill:#e3f2fd
|
||
style Storage fill:#bbdefb
|
||
style Processing fill:#90caf9
|
||
style Outbound fill:#64b5f6
|
||
style ServeFetch fill:#42a5f5
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Gateway 通信协议 Gateway Protocol
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
direction LR
|
||
|
||
%% 定义带有复杂描述的状态名（规避连线上的解析Bug）
|
||
state "Authenticated (已认证)" as Authenticated
|
||
state "Connected (已就绪)" as Connected
|
||
state "Requesting (请求中)" as Requesting
|
||
state "Streaming (流式传输中)" as Streaming
|
||
state "Waiting (异步等待中)" as Waiting
|
||
state "Error (发生错误)" as Error
|
||
state "Closed (连接关闭)" as Closed
|
||
|
||
[*] --> Disconnected
|
||
|
||
note right of Disconnected
|
||
未连接状态
|
||
end note
|
||
|
||
Disconnected --> Connecting: 客户端发起WS连接
|
||
|
||
%% 连线描述尽量保持简洁，避开特殊字符
|
||
Connecting --> Authenticated: req_connect_auth_ok
|
||
Connecting --> Closed: 认证失败
|
||
Connecting --> Closed: 非首帧为connect
|
||
|
||
Authenticated --> Connected: res_hello_ok
|
||
|
||
Connected --> Requesting: req_method
|
||
Connected --> Streaming: event_stream
|
||
|
||
Requesting --> Connected: res_ok_sync
|
||
Requesting --> Waiting: method_processing
|
||
|
||
Waiting --> Connected: res_ok
|
||
Waiting --> Error: res_error
|
||
|
||
Streaming --> Connected: stream_end
|
||
Streaming --> Streaming: stream_continue
|
||
|
||
Connected --> Closed: 客户端断开
|
||
Error --> Connected: error_recovery
|
||
Authenticated --> Closed: connection_close
|
||
Closed --> [*]
|
||
|
||
note right of Streaming
|
||
agent 事件流示例:
|
||
{
|
||
"type": "event",
|
||
"event": "agent",
|
||
"payload": {
|
||
"agentId": "xxx",
|
||
"runId": "yyy",
|
||
"status": "running"
|
||
}
|
||
}
|
||
end note
|
||
|
||
note right of Requesting
|
||
request 示例:
|
||
{
|
||
"type": "req",
|
||
"id": 1,
|
||
"method": "send",
|
||
"params": {
|
||
"channel": "whatsapp",
|
||
"target": "...",
|
||
"text": "..."
|
||
}
|
||
}
|
||
end note
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 认证与配对流程 Authentication & Pairing
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant DEV as 设备(Device)<br/>CLI/App/Node
|
||
participant WS as Gateway<br/>WebSocket Server
|
||
participant AUTH as Auth Module
|
||
participant PAIRING as Pairing Store
|
||
participant USER as 操作员
|
||
|
||
%% 首次连接 - 本地
|
||
rect rgb(200, 255, 200)
|
||
Note over DEV,USER: 场景：首次本地连接 (自动批准)
|
||
DEV->>WS: WS connect
|
||
WS->>AUTH: 生成 deviceIdentity
|
||
AUTH-->>WS: deviceIdentity (含 deviceID)
|
||
WS-->>DEV: res:connect + deviceIdentity
|
||
DEV->>WS: req:connect (带 deviceID)
|
||
WS->>AUTH: 验证 deviceID 是否本地
|
||
AUTH->>PAIRING: 检查 pairing 状态
|
||
PAIRING-->>AUTH: 新设备 (需要批准)
|
||
AUTH->>AUTH: 本地地址 -> 自动批准
|
||
AUTH->>PAIRING: 生成 deviceToken
|
||
AUTH-->>WS: 设备已批准
|
||
WS-->>DEV: res:hello-ok (带 deviceToken)
|
||
end
|
||
|
||
%% 首次连接 - 远程
|
||
rect rgb(255, 200, 200)
|
||
Note over DEV,USER: 场景：首次远程连接 (需要批准)
|
||
DEV->>WS: WS connect (via Tailscale/VPN)
|
||
WS->>AUTH: 生成 deviceIdentity (带 challenge)
|
||
AUTH-->>WS: deviceIdentity + challenge
|
||
WS-->>DEV: res:connect + deviceIdentity + challenge
|
||
DEV->>DEV: 签名 challenge
|
||
DEV->>WS: req:connect (带 deviceID + signature)
|
||
WS->>AUTH: 验证签名
|
||
AUTH->>PAIRING: 检查 pairing 状态
|
||
PAIRING-->>AUTH: 新设备，非本地
|
||
AUTH-->>USER: 通知等待批准
|
||
USER-->>AUTH: 批准设备
|
||
AUTH->>PAIRING: 生成并保存 deviceToken
|
||
AUTH-->>WS: 设备已批准
|
||
WS-->>DEV: res:hello-ok (带 deviceToken)
|
||
end
|
||
|
||
%% 后续连接
|
||
rect rgb(200, 200, 255)
|
||
Note over DEV,USER: 场景：后续连接
|
||
DEV->>WS: WS connect
|
||
DEV->>WS: req:connect (带 deviceID + deviceToken)
|
||
WS->>PAIRING: 验证 deviceToken
|
||
PAIRING-->>WS: Token 有效
|
||
WS-->>DEV: res:hello-ok
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 完整组件关系图 Component Relationships
|
||
|
||
```mermaid
|
||
graph TB
|
||
%% CLI 层
|
||
CLI[openclaw CLI<br/>openclaw.mjs]
|
||
PROG[src/index.ts<br/>buildProgram]
|
||
CMDS[src/commands/]
|
||
|
||
CLI --> PROG
|
||
PROG --> CMD_DEPS[createDefaultDeps]
|
||
|
||
%% Gateway 层
|
||
GW_SERVER[src/gateway/server.impl.ts<br/>startGatewayServer]
|
||
GW_PROT[src/gateway/protocol/]
|
||
GW_METHODS[src/gateway/server-methods/]
|
||
GW_CHAN[src/gateway/server-channels.ts]
|
||
|
||
GW_SERVER --> GW_PROT
|
||
GW_SERVER --> GW_METHODS
|
||
GW_SERVER --> GW_CHAN
|
||
|
||
%% 通道层
|
||
CHAN_SYS[src/channels/]
|
||
PLUG_TYPES[src/channels/plugins/types.plugin.ts]
|
||
PLUG_ADAPTER[src/channels/plugins/types.adapters.ts]
|
||
|
||
WHAST[whatsapp.ts]
|
||
TELEG[telegram.ts]
|
||
DISC[discord.ts]
|
||
SLACK[slack.ts]
|
||
SIGNL[signal.ts]
|
||
IMMSG[imessage.ts]
|
||
|
||
CHAN_SYS --> PLUG_TYPES
|
||
CHAN_SYS --> PLUG_ADAPTER
|
||
CHAN_SYS --> WA
|
||
CHAN_SYS --> TG
|
||
CHAN_SYS --> DC
|
||
CHAN_SYS --> SL
|
||
CHAN_SYS --> SI
|
||
CHAN_SYS --> IM
|
||
|
||
GW_CHAN --> CHAN_SYS
|
||
|
||
%% Agent 层
|
||
AGENT_RT[src/agents/runtime.ts]
|
||
AGENT_TOOLS[src/agents/tools/]
|
||
ROUTER[src/routing/resolve-route.ts]
|
||
|
||
ROUTER --> AGENT_RT
|
||
AGENT_RT --> AGENT_TOOLS
|
||
GW_METHODS --> ROUTER
|
||
|
||
%% 配置层
|
||
CONFIG[src/config/]
|
||
ZOD_TYPES[src/config/zod-schema.*.ts]
|
||
|
||
CONFIG --> ZOD_TYPES
|
||
GW_SERVER --> CONFIG
|
||
ROUTER --> CONFIG
|
||
|
||
%% 媒体层
|
||
MEDIA[src/media/]
|
||
MIME[mime.ts]
|
||
STORE[store.ts]
|
||
FETCH[fetch.ts]
|
||
|
||
MEDIA --> MIME
|
||
MEDIA --> STORE
|
||
MEDIA --> FETCH
|
||
GW_METHODS --> MEDIA
|
||
|
||
%% 插件层
|
||
PLUG_SYS[src/plugins/]
|
||
PLUG_SDK[src/plugin-sdk/]
|
||
|
||
PLUG_SYS --> PLUG_SDK
|
||
GW_SERVER --> PLUG_SYS
|
||
|
||
%% 钩子
|
||
HOOKS[src/hooks/types.ts]
|
||
|
||
HOOKS --> AGENT_RT
|
||
PLUG_SDK --> HOOKS
|
||
|
||
%% 基础设施
|
||
INFRA[src/infra/]
|
||
PORTS[ports.ts]
|
||
LOGG[logging/]
|
||
|
||
INFRA --> PORTS
|
||
INFRA --> LOGG
|
||
GW_SERVER --> INFRA
|
||
|
||
style CLI fill:#e1f5fe
|
||
style GatewayServer fill:#bbdefb
|
||
style ChannelLayer fill:#90caf9
|
||
style AgentLayer fill:#64b5f6
|
||
style ConfigLayer fill:#42a5f5
|
||
style MediaLayer fill:#1e88e5
|
||
style PluginLayer fill:#0d47a1
|
||
```
|
||
|
||
---
|
||
|
||
## 附录：组件职责
|
||
|
||
| 组件 | 职责 |
|
||
| ------------------ | ---------------------------------------------- |
|
||
| **CLI** | 命令行界面，启动 gateway、发送消息、配置管理等 |
|
||
| **Gateway** | WebSocket 服务器，协议验证，事件广播，通道管理 |
|
||
| **Channels** | 消息平台适配器，入站/出站消息，状态管理 |
|
||
| **Routing** | 消息路由解析，绑定匹配，会话键构建 |
|
||
| **Agent Runtime** | AI Agent 执行，工具调用，会话管理 |
|
||
| **Media Pipeline** | 媒体上传、存储、处理、服务 |
|
||
| **Config System** | 配置加载、验证、迁移、监听 |
|
||
| **Plugin SDK** | 插件开发接口，运行时 API |
|
||
| **Hooks** | 生命周期钩子，插件扩展点 |
|
||
| **Infrastructure** | 端口管理、日志、诊断事件、SSRF 防护 |
|
||
|
||
---
|
||
|
||
**文档结束**
|