OpenClaw 核心运行流程

---

一、全局总览

---

二、会话管理 (Session Management)

会话是 Agent 与用户交互的持久化单元，一个 sessionKey 对应一个 session 文件。

sessionKey 格式（src/routing/session-key.ts:127 → buildAgentPeerSessionKey()）：

dmScope	格式
main	agent:{agentId}:main
per-peer	agent:{agentId}:direct:{peerId}
per-channel-peer	agent:{agentId}:{channel}:direct:{peerId}
per-account-channel-peer	agent:{agentId}:{channel}:{accountId}:direct:{peerId}
群聊	agent:{agentId}:{channel}:{peerKind}:{peerId}

文件路径（src/config/sessions/paths.ts）：

• sessions.json（第 34 行 resolveDefaultSessionStorePath()）：sessionKey → SessionEntry 映射
• {sessionId}.jsonl（第 248 行）：每个 session 的完整 Agent 对话和工具调用数据

---

三、Session Store 与执行分叉

代码映射：

• loadSessionStore() → src/config/sessions/store.ts:195，返回 Record<string, SessionEntry>，带 45 秒 TTL 缓存
• isCliProvider() → src/agents/model-selection.ts:76，检查 claude-cli、codex-cli 或自定义 cliBackends
• 分叉判断 → src/agents/agent-command.ts:357

---

四、Queue 并发控制

Queue 解决并发消息处理问题。session 并发度为 1（maxConcurrent: 1），全局并发度默认为 4。

代码映射：

• enqueueCommandInLane() → src/process/command-queue.ts:168
• QueueSettings → src/auto-reply/reply/queue/types.ts:13
• Session 并发度 → src/process/command-queue.ts:71（maxConcurrent: 1）
• 全局并发度 → setCommandLaneConcurrency()（src/process/command-queue.ts:161，默认 4）

---

五、Pi Coding Agent (Agent Session)

代码映射：

• runEmbeddedAttempt → src/agents/pi-embedded-runner/run/attempt.ts
• createOpenClawCodingTools() → src/agents/pi-tools.ts:198
• buildEmbeddedSystemPrompt() → src/agents/pi-embedded-runner/system-prompt.ts
• subscribeEmbeddedPiSession() → src/agents/pi-embedded-subscribe.ts:34（独立函数，非 session 方法）
• 回调类型 → src/agents/pi-embedded-subscribe.types.ts:20-31
• 工具目录 → src/agents/tool-catalog.ts:27-251（10 大类，25+ 工具）
• 策略解析 → src/agents/pi-tools.policy.ts:233-350（6 层逐级覆盖）
• Skills 目录 → 仓库根目录 skills/，扩展级 extensions/*/skills/

---

六、Memory 管理

代码映射：

• syncMemoryFiles() → src/memory/manager-sync-ops.ts:696
• syncSessionFiles() → src/memory/manager-sync-ops.ts:787
• indexFile() → src/memory/manager-embedding-ops.ts:803（非 manager-sync-ops.ts）
• chunkMarkdown() → src/memory/internal.ts:334
• embedChunksWithBatch() → src/memory/manager-embedding-ops.ts:268（按提供商路由：OpenAI/Gemini/Voyage/通用批处理）
• 写入 3 张表：chunks（第 875 行）、chunks_vec（第 902 行）、chunks_fts（第 907 行）

---

七、混合检索 (Hybrid Search)

代码映射：

• memory_search 工具 → src/agents/tools/memory-tool.ts:86
• memory_get 工具 → src/agents/tools/memory-tool.ts:135
• searchKeyword() → src/memory/manager.ts:395（调用 manager-search.ts:136）
• searchVector() → src/memory/manager.ts:369（调用 manager-search.ts:20）
• mergeHybridResults() → src/memory/hybrid.ts:57
• 融合公式：hybridScore = vectorWeight × vectorScore + textWeight × textScore（默认 0.7 / 0.3）
• 可选后处理：MMR（src/memory/mmr.ts）、时间衰减（src/memory/temporal-decay.ts）
• 默认阈值：minScore = 0.35，maxResults = 6

---

八、完整调用链路一览

从一条 Telegram 消息到 AI 回复，完整经过以下环节：

步骤	文件	函数
1. Channel 接收	extensions/telegram/src/monitor.ts	monitorTelegramProvider()
2. Gateway 分发	src/gateway/server.impl.ts	startGatewayServer()
3. Session 加载	src/config/sessions/store.ts:195	loadSessionStore()
4. Queue 入队	src/process/command-queue.ts:168	enqueueCommandInLane()
5. Agent 执行	src/agents/pi-embedded-runner/run/attempt.ts	runEmbeddedAttempt()
6. LLM 调用	@mariozechner/pi-coding-agent	activeSession.prompt()
7. 工具执行	src/agents/pi-tools.ts:198	createOpenClawCodingTools()
8. 记忆检索	src/memory/manager.ts:259	search() → mergeHybridResults()
9. 回复分发	src/auto-reply/reply/reply-dispatcher.ts:113	createReplyDispatcher()
10. 出站投递	src/infra/outbound/deliver.ts:479	deliverOutboundPayloads()

---

九、源码验证勘误表

以下为原图与实际代码的差异，已在本文档中修正：

原图内容	实际代码	验证位置
session.json	sessions.json（复数）	src/config/sessions/paths.ts:34
debounceMs: 60	Session Store TTL = 45 秒	src/config/sessions/store.ts:52
subagents session: 60秒	子 Agent 使用 :subagent: 前缀，未找到 60 秒值	src/sessions/session-key-utils.ts:77
session_delta	sessions.deltaBytes + sessions.deltaMessages	src/agents/memory-search.ts:62-63
sources.has('session')	sources.has('sessions')（复数）	src/memory/manager-sync-ops.ts:435
subscribe()	subscribeEmbeddedPiSession()（独立函数）	src/agents/pi-embedded-subscribe.ts:34
emitSessionTranscriptUpdate debounceMs: 1500	函数同步无 debounce；1500 是 memory watch 的 debounce	src/sessions/transcript-events.ts:16
indexFile 在 manager-sync-ops	实际在 manager-embedding-ops.ts:803	src/memory/manager-embedding-ops.ts
Queue 3 种模式	实际 6 种：collect/followup/steer/steer-backlog/interrupt/queue	src/auto-reply/reply/queue/types.ts:9
Tools Policy 5 层	实际 6 层：增加 provider 层	src/agents/pi-tools.policy.ts:253-262
openclaw/skills	仓库根目录 skills/（55+ skills）	skills/ 目录