OpenClaw 内部工作机制:从输入到执行

以发送一条消息 "给我打开计算器,并计算222*555,然后用Bing搜索结果,再打开第一个网页" 为例,完整追踪 OpenClaw 的内部处理流程。


整体架构图

你的消息
  ↓
CLI 解析
  ↓
Gateway (WebSocket RPC)Agent Loop (PI Agent)LLM (DeepSeek/Anthropic...)
  ↓         ↑
工具调用  工具结果
  ↓
Node Host 执行(shell/浏览器)
  ↓
最终回复返回给你

第一层:CLI 解析

文件: src/cli/program/register.agent.ts 函数: registerAgentCommands(program, args)

// 解析你输入的参数
输入: --agent dev --message "给我打开计算器..."
输出: AgentCliOpts { message, agentId, to, thinking, ... }
  
调用: agentCliCommand(opts, runtime, deps)

第二层:通过 Gateway RPC 发消息

文件: src/commands/agent-via-gateway.ts 函数: agentViaGatewayCommand(opts)

文件: src/gateway/call.ts 函数: callGateway<T>(opts)

// 通过 WebSocket 发送 RPC 请求
输入: { method: "agent", params: { message, agentId, sessionKey, ... } }
输出: GatewayAgentResponse { runId, status, result }

第三层:Gateway 服务端处理

文件: src/gateway/server-methods/agent.ts 函数: agentHandlers["agent"]({ params, respond, context })

// 1. 幂等性检查(重复请求去重)
// 2. 解析附件
// 3. 后台调度
输入: RPC params
输出: 调用 dispatchAgentRunFromGateway() 异步处理

第四层:Agent 命令核心

文件: src/commands/agent.ts 函数: agentCommandInternal(opts)prepareAgentCommandExecution()

// 准备阶段
1. 验证 message
2. 加载配置 loadConfig()
3. 解析会话 resolveSession()   src/commands/agent/session.ts
4. 确定模型 resolveDefaultModelForAgent()
5. 加载 skill 快照

输出: { cfg, model, provider, sessionFile, workspaceDir, ... }
  
调用: runEmbeddedPiAgent(params)

第五层:AI 循环(最核心)

文件: src/agents/pi-embedded-runner/run.ts 函数: runEmbeddedPiAgent(params)

文件: src/agents/pi-embedded-runner/run/attempt.ts 函数: runEmbeddedAttempt()

// AI 循环
输入: {
  prompt: "给我打开计算器...",
  provider: "deepseek",
  model: "deepseek-chat",
  tools: [...],          // 工具列表
  systemPrompt: "...",   // 系统提示
  sessionHistory: [...], // 历史对话
}

循环:
  1. 调用 LLM APIDeepSeek
  2. LLM 返回  tool_use (调用工具)  text (最终回复)
  3. 执行工具  把结果回传给 LLM
  4. LLM 继续推理
  5. 直到 stopReason = "end_turn"

第六层:工具定义

文件: src/agents/pi-tools.ts 函数: createOpenClawCodingTools(options)

这个任务会用到的工具:

工具名 作用 文件
bash_tool 打开计算器(xdg-open gnome-calculator src/agents/bash-tools.exec.ts
browser_tool 控制浏览器(Bing 搜索 + 点击链接) src/agents/tools/browser-tool.ts

完整工具列表:

工具名 作用
bash_tool 执行 shell 命令
browser_tool 控制浏览器(导航、点击、截图)
canvas_tool 图形绘制
nodes_tool 设备节点控制
cron_tool 定时任务
message_tool 发送消息到渠道
tts_tool 语音合成
web_search 网络搜索
web_fetch 抓取网页内容

第七层:Bash 工具 → Node Host 执行 shell 命令

文件: src/node-host/invoke-system-run.ts 函数: handleSystemRunInvoke(opts)

// AI 调用 bash_tool { command: "gnome-calculator" }
处理流程:
  1. buildSystemRunApprovalPlan()  解析命令
  2. evaluateSystemRunPolicy()     检查安全策略
     - security=deny:    直接拒绝
     - allowlist:        检查白名单
     - full:             全部允许
  3. hardenApprovedExecutionPaths()  验证路径
  4. child_process.spawn()           真正执行命令

输入:  SystemRunParams { argv, cwd, env, timeoutMs }
输出: { ok: true, stdout: "...", stderr: "...", exitCode: 0 }

第八层:浏览器工具 → Playwright 控制浏览器

文件: src/browser/ 核心: 基于 Playwright/Chromium

// AI 调用 browser_tool
输入: { action: "navigate", url: "https://bing.com/search?q=123210" }
输出: { ok: true, screenshot: "...", title: "...", content: "..." }
// AI 看到截图/内容后决定下一步操作(点击第一个链接等)

第九层:结果返回

文件: src/commands/agent/delivery.ts 函数: deliverAgentCommandResult(opts)

// 工具结果 → 追加到会话历史 → 再次调用 LLM → 最终文字回复
输出到控制台: "我已经打开了计算器,222*555=123210,并在Bing中搜索了..."

会话持久化

文件: src/config/sessions.ts

每次对话以 .jsonl 格式存储在 ~/.openclaw/sessions/ 目录下,每行一条消息,支持增量追加和历史回溯。


关键文件速查表

步骤 文件 主要函数
1. CLI 解析 src/cli/program/register.agent.ts registerAgentCommands()
2. 命令路由 src/commands/agent-via-gateway.ts agentViaGatewayCommand()
3. Gateway 调用 src/gateway/call.ts callGateway()
4. Gateway 处理 src/gateway/server-methods/agent.ts agentHandlers["agent"]
5. Agent 核心 src/commands/agent.ts agentCommandInternal()
6. 会话解析 src/commands/agent/session.ts resolveSession()
7. 嵌入式 PI src/agents/pi-embedded-runner/run.ts runEmbeddedPiAgent()
8. AI 循环 src/agents/pi-embedded-runner/run/attempt.ts runEmbeddedAttempt()
9. 工具列表 src/agents/pi-tools.ts createOpenClawCodingTools()
10. Bash 工具 src/agents/bash-tools.exec.ts createExecTool()
11. Node Host src/node-host/invoke-system-run.ts handleSystemRunInvoke()
12. 结果交付 src/commands/agent/delivery.ts deliverAgentCommandResult()
13. 会话存储 src/config/sessions.ts updateSessionStore()

参数类型链

// CLI 选项
AgentCliOpts { message, to, sessionId, agent, thinking, ... }
  
// Agent 命令参数
AgentCommandOpts & { senderIsOwner: boolean }
  
// 嵌入式 PI 参数
RunEmbeddedPiAgentParams { prompt, provider, model, ... }
  
// 工具参数
{ command, cwd, timeout, env, ... }
  
// Node Host 系统运行参数
SystemRunParams { argv, cwd, env, timeoutMs, ... }

如果你要做自己的 AI 程序,参考这几个核心设计

设计点 OpenClaw 的做法 你可以参考
工具系统 createOpenClawCodingTools() 返回工具数组,每个有 name/description/inputSchema/handler 标准 Function Calling 模式
Agent Loop runEmbeddedAttempt() 循环调用 LLM + 执行工具直到结束 ReAct 模式
会话管理 .jsonl 文件按行追加,SessionManager 管理读写 轻量持久化
安全审批 exec-approvals.ts 白名单 + 策略评估 执行前鉴权
多渠道接入 Gateway 统一接收,channel 插件解耦 消息总线模式