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 API(DeepSeek)
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 插件解耦 | 消息总线模式 |
评论 · 0
发表评论