Agent的实现逻辑（OpenClaw）#

OpenClaw 单次消息处理链路

本文讨论了对 OpenClaw 这一 Agent 实现的深度技术分析，基于 v2026.2.26 版本的开发机运行数据、抓包日志等材料，拆解其运行机制与核心特性，关键要点包括：

核心定位与优势：OpenClaw 未突破技术边界，但突破了用户感知边界，其抓包部署脚本由大模型执行，基本实现全自动化。
单次消息处理链路：单条飞书消息从接收到回复总耗时约 40.5 秒，包含 9 秒首次模型推理、<1 秒飞书文档工具执行、32 秒二次模型推理三个核心阶段。
双层并发排队机制：采用 Session Lane（单会话串行，并发 1）+ Main Lane（全局并发上限 4）的双层排队设计，同时还有 Cron Lane（并发 1）、Subagent Lane（并发 8）分别对应定时任务、子 Agent 场景。
会话存储架构：采用内存层（最大 5000 会话，24 小时空闲过期）+ 文件层（JSON 索引+JSONL 对话历史，45 秒读缓存）的双层存储，按 per-channel-peer 策略做会话隔离。
模型交互配置：基于火山引擎 ARK API，使用端点 ep-20250224191545-96p8j，上下文窗口 200000 tokens，单次请求包含 30642 字符的 System Prompt、37 个工具定义。
Token 消耗特征：调用飞书文档工具后，单次输入 token 会从约 19K 跳增至约 49K，主要增量为返回的文档内容，对应上下文窗口利用率约 24.6%。
Skill 加载规则：共加载 14 个 Skill，按 4 个优先级从不同路径加载，执行由模型驱动，通过 System Prompt 注入列表指导工具调用。

前言#

Agent的实现逻辑（ClaudeCode），本篇分析对象为OpenClaw，改进之处为抓包部署脚本完全是由大模型执行，基本全自动化。

优质资料整理#

内容类型

内容链接

OpenClaw 工作原理深度解析

万字长文：OpenClaw一轮交互的完整执行链路

万字长文：OpenClaw 背后的 pi-mono 框架原理

内容原理解析

这只爪子里装了什么 — OpenClaw/Clawdbot 技术解构

聊聊OpenClaw的AgentLoop

OpenClaw Memory 功能解析

这只爪子的脑子里装了什么 - OpenClaw/Clawdbot Memory 解析

Memory 分析

对产品形态的理解

OpenClaw 为什么火：它没有突破技术边界，但突破了“用户感知边界”

OpenClaw过程解析#

分析对象: 开发机上运行的 OpenClaw Gateway (v2026.2.26)

数据来源: mitmproxy 抓包 + Gateway stdout/stderr 日志 + ARK API Payload + 会话存储文件

复现方式参考：OpenClaw 技术链路分析 - 抓包准备工作流

1. 采集数据总览#

本次分析基于以下采集数据，所有数据均来自同一开发机同一时间窗口：

traffic-20260315-151111.mitm

5 MB

mitmproxy 抓包文件，记录 Gateway 与外部 API 间的 HTTP 流量

gateway-stdout.log

27 MB

Gateway 主进程标准输出，包含完整诊断日志

gateway-stderr.log

6 KB

启动冲突诊断日志

ark-request-full.json

87 KB

单次 ARK API 完整请求体（含 system prompt + messages + tools）

payload.jsonl

3 条记录

3 次模型调用的 usage 统计（token 消耗）

sessions.json

会话索引文件，含 4 个会话记录

system-prompt-full.txt

31 KB

实际注入模型的完整 system prompt 文本

文件

openclaw.json

大小

说明

Gateway 运行配置（provider、channel、并发等）

采集数据间的关联关系#

飞书用户消息
│
▼
┌─────────────────────────────┐
│  gateway-stdout.log        │ ◄── 记录完整处理链路 (接收→排队→执行→完成)
│  (诊断事件 + 时间戳)         │
└────────────┬────────────────┘
│ Gateway 构建请求
▼
┌─────────────────────────────┐     ┌──────────────────────────────┐
│  ark-request-full.json     │ ──► │  traffic-*.mitm            │
│  (完整请求体)                │     │  (HTTP 层面抓包验证)          │
└────────────┬────────────────┘     └──────────────────────────────┘
│ ARK API 返回
▼
┌─────────────────────────────┐     ┌──────────────────────────────┐
│  payload.jsonl              │     │  sessions.json               │
│  (3次调用的 token 统计)       │     │  (会话索引 + prompt 报告)      │

2. Gateway 启动链路验证#

2.1 日志证据：正常启动#

从 gateway-stdout.log 开头可见完整启动序列：

07:21:35

feishu_doc: Registered feishu_doc, feishu_app_scopes

飞书文档工具注册

07:21:35

feishu_wiki: Registered feishu_wiki tool

飞书知识库工具注册

07:21:35

feishu_drive: Registered feishu_drive tool

飞书云盘工具注册

07:21:35

feishu_bitable: Registered bitable tools

飞书多维表格工具注册

07:21:35

[plugins] task-reporter: loaded

插件加载

07:21:35

listening on ws://127.0.0.1:18789, ws://[::1]:18789 (PID 4172607)

开始监听

时间

07:21:35

日志事件

Browser control listening on

说明

浏览器控制端就绪

验证: 启动耗时 < 1s，单进程同时绑定 IPv4 + IPv6 回环地址。

2.2 启动流程与源码位置#

配置加载

读取 openclaw.json，合并默认值

src/gateway/server.impl.ts → startGatewayServer()

Provider 注册

src/gateway/server.impl.ts → provider 初始化段

Lane 并发设置

设置 Main=4, Cron=1, Subagent=8

src/gateway/server-lanes.ts → applyGatewayLaneConcurrency()

Plugin 加载

扫描并加载 extensions 目录

src/gateway/server.impl.ts → plugin 加载段

Channel 创建

初始化飞书等 channel manager

src/gateway/server.impl.ts → channel manager 段

阶段

WebSocket 监听

功能

绑定端口，开始接收请求

源码位置

src/gateway/server.impl.ts → listen 段

2.3 配置验证#

openclaw.json 中的实际运行配置：

配置项

值

说明

gateway.port

18789

与日志中监听端口一致

gateway.bind

loopback

仅本地访问

gateway.auth.mode

token

Bearer token 认证

models.providers.ark.baseUrl

火山引擎方舟 API

models.providers.ark.api

openai-completions

OpenAI 兼容接口

agents.defaults.maxConcurrent

Main Lane 最大并发

agents.defaults.subagents.maxConcurrent

Subagent Lane 最大并发

channels.feishu.appId

cli_a9e9cb832a38dcd0

飞书应用 ID

配置项

plugins.entries.feishu.enabled

值

true

说明

飞书 channel 已启用

3. 消息处理全链路：从飞书到模型再回飞书#

3.1 完整链路时序（日志实证）#

以下为 gateway-stdout.log 中完整记录的一次消息处理链路（runId: 07fbfb50），时间戳均来自原始日志：

时间轴 (07:23:01 ~ 07:23:42, 共 41 秒)
═══════════════════════════════════════════════════════════════════════

07:23:01.000 ┌─ [feishu] received message from ou_4ba231a86e6e13148880a270cbf2afa1 (p2p)

│ [feishu] dispatching to agent (session=agent:main:feishu:direct:ou_…)

│

07:23:01.xxx ├─ [diagnostic] lane enqueue: lane=session:…ou_4ba… queueSize=1

│ [diagnostic] lane dequeue: lane=session:…ou_4ba… waitMs=28 queueSize=0

│

07:23:01.xxx ├─ [diagnostic] lane enqueue: lane=main queueSize=1

│ [diagnostic] lane dequeue: lane=main waitMs=1 queueSize=0

│

07:23:01.xxx ├─ [agent/embedded] run start: runId=07fbfb50… provider=ark thinking=off

│ [diagnostic] session state: prev=idle new=processing reason=“run_started”

3.2 链路各阶段分解#

阶段

耗时

日志证据

源码位置

飞书消息接收

received message from ou_4ba2…

飞书 channel handler

Session 路由

dispatching to agent (session=agent:main:feishu:direct:ou_…)

src/auto-reply/dispatch.ts

Session Lane 排队

28ms

lane enqueue → dequeue waitMs=28 (session 专属 lane)

src/process/command-queue.ts → enqueueCommandInLane()

Main Lane 排队

1ms

lane enqueue → dequeue waitMs=1 (主 lane)

同上

Agent Run 启动

run start: runId=07fbfb50… provider=ark

src/agent/embedded-runner.ts

上下文构建

messages=8 systemPromptChars=30642 promptChars=495

src/agent/system-prompt.ts → buildAgentSystemPrompt()

模型首次推理

~9s

(07:23:01 → 07:23:10, 推理 + 流式返回)

ARK API streaming

Tool 执行

<1s

tool start → tool end: feishu_doc

工具执行器

模型二次推理

~32s

(07:23:10 → 07:23:42, 含文档内容的长推理)

ARK API streaming

会话状态归位

session state: processing → idle

src/agent/session.ts

阶段

Run 完成

耗时

总计 40.5s

日志证据

durationMs=40475 aborted=false

源码位置

3.3 处理流程图#

┌─────────┐    Event     ┌──────────────┐   dispatch    ┌─────────────┐
│  飞书    │ ──────────► │ Channel Mgr  │ ──────────►  │  Session Lane  │
│  用户    │   Webhook    │  (feishu)    │             │  （per-user）  │
└─────────┘              └──────────────┘               └───────┬─────┘
│ dequeue
▼
┌──────────────┐    ┌────────────────┐
│  Main Lane   │ ◄────────── │  Lane Router   │
│  (并发≤4)    │              └────────────────┘
└───────┬──────┘
│ dequeue
▼
┌───────────────────────────────────── ─────┐
│            Agent Run (embedded)              │
│  ┌─────────────────────────────────────┐    │
│  │ 1. buildAgentSystemPrompt() → 30KB  │    │
│  │ 2. 组装 messages[] + tools[]         │    │
│  │ 3. POST → ARK API (streaming)       │    │

4. 并发控制机制：Lane 双层排队验证#

4.1 日志中发现的双层排队模式#

这是本次分析中最有价值的发现之一。从诊断日志中可以清楚看到，每条消息经历两次排队：

第一次排队 (Session Lane):
lane enqueue: lane=session:agent:main:feishu:direct:ou_4ba2...  queueSize=1
lane dequeue: lane=session:agent:main:feishu:direct:ou_4ba2...  waitMs=28 queueSize=0

第二次排队 (Main Lane):

lane enqueue: lane=main queueSize=1

lane dequeue: lane=main waitMs=1 queueSize=0

4.2 双层排队的设计意图#

第一层

session:{sessionKey}

1 (默认)

保证同一用户的消息串行处理，避免同一会话内的并发冲突

层级

第二层

Lane 名称

main

并发限制

4 (配置值)

作用

控制全局并发上限，防止多用户同时触发时耗尽系统资源

验证数据：

Session Lane waitMs=28ms → 排队几乎无等待（当时仅一个用户活跃）
Main Lane waitMs=1ms → 全局无竞争（总并发 < 4）

4.3 Lane 类型总览#

main

所有入站消息处理

openclaw.json → agents.defaults.maxConcurrent

cron

定时任务

src/gateway/server-lanes.ts 硬编码

subagent

子 Agent 并行执行

openclaw.json → agents.defaults.subagents.maxConcurrent

session:*

每个会话的消息串行化

默认值 (源码: src/process/command-queue.ts)

Lane

并发数

用途

配置来源

4.4 核心源码位置#

队列入口 + pump 循环

src/process/command-queue.ts → enqueueCommandInLane(), drainLane()

Lane 类型枚举

src/process/lanes.ts → CommandLane enum (Main, Cron, Subagent, Nested)

Gateway 并发初始化

src/gateway/server-lanes.ts → applyGatewayLaneConcurrency()

并发上限常量

src/agent/agent-limits.ts → DEFAULT_AGENT_MAX_CONCURRENT=4, DEFAULT_SUBAGENT_MAX_CONCURRENT=8

SIGUSR1 重启恢复

src/process/command-queue.ts → resetAllLanes() (递增 generation，清除 stale activeTaskIds)

功能

位置

5. 会话管理与存储机制#

5.1 会话索引验证 (sessions.json)#

从 sessions.json 中提取的实际会话数据：

字段

值

说明

sessionKey

agent:main:feishu:direct:ou_4ba2…

格式: agent:{agentId}:{channel}:{chatType}:{userId}

sessionId

5c46a96a-a7d1-4a6a-a159-5b08884a9efc

UUID，与日志中 runId 关联

channel

feishu

来源渠道

chatType

direct

私聊

modelProvider

ark

使用的模型提供商

model

ep-20250224191545-96p8j

ARK 端点 ID

contextTokens

200,000

模型上下文窗口

inputTokens

69,666

当前会话累计输入 token

sessionFile

…/sessions/5c46a96a-…-.jsonl

对话历史文件

字段

compactionCount

值

说明

未触发压缩

文件中共有 4 个会话记录（4 个不同的飞书用户），验证了 “per-channel-peer” 的会话隔离策略。

5.2 双层存储架构#

内存层 (ACP)

进程内 Map

最大 5000 会话, 24h 空闲过期

src/agent/session.ts

文件层

JSON 文件 + JSONL 历史

无限容量, 45s 读缓存 TTL

src/agent/store.ts

层级

存储方式

容量/TTL

源码位置

文件层存储路径模式（从 sessions.json 验证）：

~/.openclaw/agents/{agentId}/sessions/
├── sessions.json              ← 会话索引 (所有会话的 metadata)
└── {sessionId}.jsonl          ← 对话历史 (append-only)

路径解析逻辑: src/agent/paths.ts

5.3 会话状态机（日志验证）#

从 diagnostic 日志中观察到的状态转移：

idle ──[run_started]──► processing ──[run_completed]──► idle

日志证据：

session state: prev=idle    new=processing  reason="run_started"   queueDepth=0
session state: prev=processing  new=idle    reason="run_completed" queueDepth=0

6. System Prompt 构建与注入验证#

6.1 实测 System Prompt 组成#

从 sessions.json 的 systemPromptReport 字段提取的精确数据：

总字符数

30,642 chars

项目上下文占比

14,171 chars (46.3%)

指标

非项目上下文占比

值

16,471 chars (53.7%)

6.2 注入的 Workspace 文件#

文件名

路径

字符数

是否截断

AGENTS.md

~/.openclaw/workspace/AGENTS.md

7,804

否

SOUL.md

~/.openclaw/workspace/SOUL.md

2,613

否

BOOTSTRAP.md

~/.openclaw/workspace/BOOTSTRAP.md

1,449

否

TOOLS.md

~/.openclaw/workspace/TOOLS.md

850

否

USER.md

~/.openclaw/workspace/USER.md

474

否

HEARTBEAT.md

~/.openclaw/workspace/HEARTBEAT.md

167

否

IDENTITY.md

~/.openclaw/workspace/IDENTITY.md

153

否

MEMORY.md

~/.openclaw/workspace/MEMORY.md

否

文件名

合计

路径

字符数

13,553

是否截断

验证: 这些文件的总字符数 (13,553) 接近 projectContextChars (14,171)，差额为格式化标记和注入头部。

6.3 System Prompt 结构段落 (从 system-prompt-full.txt 验证)#

从实际抓包的 ark-request-full.json 中 system 消息，以及 system-prompt-full.txt 还原出以下段落结构：

段落

内容概要

Tooling

37 个工具名、简要说明、调用约定

Tool Call Style

默认不解释，复杂操作才解释

Safety

无独立目标、优先安全和人类监督

OpenClaw CLI Quick Reference

子命令参考（gateway status/start/stop）

Skills (mandatory)

14 个可用 skill 的 <available_skills> XML 列表

Memory Recall

memory_search/memory_get 强制工作流

Workspace

工作目录 /home/openclaw/.openclaw/workspace

Documentation

文档路径、ClaWHub 链接

Reply Tags

[[reply_to_current]] 等标记系统

Messaging

消息路由规则、feishu 特殊处理

Inbound Context

当前消息的 JSON metadata

Project Context

AGENTS.md / SOUL.md / TOOLS.md / IDENTITY.md / USER.md / HEARTBEAT.md / BOOTSTRAP.md / MEMORY.md

Silent Replies

NO_REPLY 机制

Heartbeats

HEARTBEAT_OK 机制

段落

Runtime

内容概要

agent/host/os/node/model/channel 运行时信息

构建逻辑源码: src/agent/system-prompt.ts → buildAgentSystemPrompt()

7. 模型交互：ARK API 请求/响应分析#

7.1 请求结构 (ark-request-full.json)#

从 87KB 的完整请求体中提取的关键字段：

model

ep-20250224191545-96p8j

ARK 端点 ID

messages[0].role

system

30,642 字符的 system prompt

messages[].length

8 条

对话历史 (user:3, assistant:4, toolResult:1)

tools[].length

37 个

工具定义数量

字段

stream

值

true (推测)

说明

流式返回

7.2 工具概况#

共注册 37 个工具，按功能分类：

飞书系列 (doc/wiki/drive/bitable)

feishu_doc, feishu_wiki, feishu_bitable_*

文件操作

read, write, edit

Shell / 进程

exec, process

浏览器 / 网络

browser, web_search, web_fetch

会话管理

sessions_list, sessions_spawn, sessions_send, sessions_history, subagents

消息发送

message (85 个参数，schema 最大)

记忆系统

memory_search, memory_get

其他 (canvas/nodes/tts/status/agents)

canvas, nodes, tts, session_status, agents_list, feishu_app_scopes

分类

工具数量

代表工具

工具 schema 总字符数: 20,292 chars（不含工具列表说明 3,135 chars）

完整工具清单见附录 C：完整工具列表

7.3 请求中的消息结构#

从 ark-request-full.json 验证的 messages 数组结构：

system

完整 system prompt (30,642 chars)

user

飞书消息 (含 inbound metadata + 用户文本)

assistant

助手回复 (含 reasoning_content)

user

第二条用户消息

assistant

助手回复 (包含 tool_calls: feishu_doc/read)

tool

feishu_doc 工具返回结果

assistant

基于工具结果的回复

索引

role

user

内容概要

当前消息: “帮我写一下这篇文档的内容”

关键发现: 第 2 条 assistant 消息中包含 reasoning_content 字段，说明 ARK 模型返回了推理过程（虽然配置 thinking=off，但模型内部仍有 reasoning）。

7.4 Tool Call 循环#

日志中验证的 Tool Call 执行流程：

模型第一次推理 (9s)
│
▼ 返回 tool_calls: [{name: "feishu_doc", id: "call_g9xj..."}]
│
├─ tool start: feishu_doc (07:23:10)
│  (调用飞书 API 读取文档)
└─ tool end: feishu_doc   (07:23:10)
│
▼ 工具结果追加到 messages，发起第二次请求
│
模型第二次推理 (32s)
│
▼ 返回最终文本回复 → 发送给飞书用户

8. Skill 加载与执行机制验证#

8.1 Skill 加载概况#

从 sessions.json 的 skillsSnapshot 验证，共加载 14 个 skill，Prompt 总字符数 5,259 chars。

完整 Skill 清单见附录 D：完整 Skill 列表

8.2 Skill 来源层级#

openclaw-bundled

node_modules/openclaw/skills/

openclaw-extra

node_modules/openclaw/extensions/*/skills/

openclaw-managed

~/.openclaw/skills/

优先级

source 标识

路径

本实例加载数

openclaw-workspace

~/.openclaw/workspace/skills/

完整的 6 层优先级加载逻辑: src/agent/workspace.ts → skill 加载段

8.3 Skill 执行流程（日志+请求体验证）#

Skill 的执行是模型驱动的，不是代码驱动。从抓包数据可以验证完整流程：

1. System Prompt 中注入 `<available_skills>` XML 列表
↓ (模型读到 skill 名称 + description)

关键验证: ark-request-full.json 中 messages[4] 为 assistant 消息包含 tool_calls，messages[5] 为 tool role 消息返回结果，证实了模型→工具→模型的闭环。

8.4 Skill 限制常量#

MAX_SKILLS_IN_PROMPT

150

src/agent/workspace.ts

MAX_SKILLS_PROMPT_CHARS

30,000

src/agent/workspace.ts

常量

MAX_SKILL_FILE_BYTES

值

256,000

源码位置

src/agent/workspace.ts

9. Token 消耗趋势与上下文膨胀分析#

9.1 三次调用的 Token 对比 (payload.jsonl)#

31a623b5

07:13:22

18,763

1,549

20,312

381b2512

07:17:17

19,513

1,035

20,548

+750 input (正常历史增长)

runId (前8位)

时间

Input Tokens

Output Tokens

Total

显著变化

07fbfb50

07:23:42

49,143

1,292

50,435

+29,630 input (2.5倍跳增!)

9.2 Token 跳增根因分析#

第 3 次调用 input token 暴增 ~30K 的原因，可以从日志和请求体中交叉验证：

gateway 日志 context-diag

messages=8, historyTextChars=5662

对话历史本身仅 5.6K chars

gateway 日志 context-diag

systemPromptChars=30642

System Prompt 约 30K chars → ~8K tokens

日志 tool end: feishu_doc

第 3 次 run 中调用了 feishu_doc

飞书文档内容被注入为 tool result

sessions.json

inputTokens: 69,666

累计输入 (非单次)

第 2 次 run input

19,513 tokens

跳增前的基线

证据来源

第 3 次 run input

数据

49,143 tokens

推断

包含了飞书文档全文内容

结论: 第 3 次调用中，模型先调用 feishu_doc 读取文档内容（约 30K tokens），然后这些内容作为 tool result 追加到 messages 中，随第二次推理请求一并发送，导致 input tokens 从 ~19K 跳增至 ~49K。

9.3 Token 构成估算（第 3 次调用）#

代码块

Plain Text

复制

9.4 上下文窗口利用率#

上下文窗口

200,000 tokens

第 3 次 input

49,143 tokens

利用率

指标

压缩触发次数

值

0 (compactionCount=0)

附录部分#

附录 A：数据文件索引#

mitmproxy 抓包

analyze/traffic-20260315-151111.mitm

HTTP 层流量验证

Gateway 主日志

analyze/gateway-stdout.log

完整诊断事件链

Gateway 错误日志

analyze/gateway-stderr.log

启动失败记录

ARK 完整请求

analyze/ark-request-full.json

模型请求体验证

Token 统计

analyze/payload.jsonl

3 次调用 usage 记录

会话索引

analyze/sessions.json

会话 metadata + prompt 报告

System Prompt

analyze/system-prompt-full.txt

完整 system prompt 文本

文件

运行配置

路径

analyze/openclaw.json

用途

Gateway 配置文件

附录 B：源码文件索引#

文件

核心功能

src/gateway/server.impl.ts

Gateway 启动入口、初始化全流程

src/gateway/server-lanes.ts

Lane 并发初始化 (10 行)

src/process/command-queue.ts

命令队列核心: enqueue/dequeue/drain/reset

src/process/lanes.ts

Lane 类型枚举 (6 行)

src/agent/agent-limits.ts

并发上限常量

src/agent/session.ts

内存层会话管理 (ACP store)

src/agent/store.ts

文件层会话持久化

src/agent/paths.ts

会话文件路径解析

src/agent/system-prompt.ts

System Prompt 构建 (buildAgentSystemPrompt)

src/agent/workspace.ts

Skill 6 层优先级加载

src/auto-reply/dispatch.ts

入站消息分发

src/auto-reply/reply/provider-dispatcher.ts

Provider 分发封装

文件

核心功能

附录 C：完整工具列表（37 个）#

从 sessions.json 的 tools 报告中提取，按 schema 字符数排序：

工具名

说明字符数

Schema 字符数

参数数

分类

message

4,181

消息发送

browser

1,251

1,897

浏览器控制

nodes

115

1,500

节点管理

exec

181

1,086

Shell 执行

process

961

进程管理

feishu_wiki

971

飞书知识库

feishu_bitable_create_field

911

飞书多维表格

web_search

175

895

网页搜索

工具名

说明字符数

Schema 字符数

参数数

分类

canvas

106

661

画布

feishu_doc

116

612

飞书文档

edit

129

591

文件编辑

feishu_bitable_create_record

549

飞书多维表格

sessions_spawn

134

492

子会话

feishu_drive

486

飞书云盘

feishu_bitable_update_record

473

飞书多维表格

feishu_bitable_list_records

462

飞书多维表格

工具名

说明字符数

Schema 字符数

参数数

分类

read

298

392

文件读取

web_fetch

129

374

网页抓取

feishu_bitable_get_record

335

飞书多维表格

write

127

313

文件写入

sessions_send

273

消息转发

feishu_bitable_list_fields

255

飞书多维表格

feishu_bitable_create_app

243

飞书多维表格