Harness 与 Agent 工程 · 上下文与记忆 · 2026-04-05

OpenClaw LLM-Context 全解析

揭秘OpenClaw LLM-Context:Agent世界的PCB板,一次请求背后隐藏的完整上下文拼装逻辑。

核心内容:

  1. OpenClaw请求中五大核心组件解析(系统指令/历史对话/新输入/图片/工具定义)
  2. 特殊场景下的上下文处理机制(群聊/子agent/定时任务)
  3. 工具定义的"双重编码"玄机与MCP的隐藏存在

LLM-Context 之于 Agent 就像 PCB 之于 OS,是你理解Agent的钥匙

当你对 OpenClaw 说"帮我查一下这个 bug",你以为模型收到的就是这句话?远不止。

它收到的是一整套精心组装的上下文:系统指令、历史对话、你的消息(外加一堆你看不见的元数据前缀)、图片、以及几十个可调用工具的结构化定义。这些东西加在一起,才构成了模型这一轮"看到的世界"。

你有没有想过——

  1. • system prompt 里那 22 个 section 都塞了什么?为什么工具要同时以"纯文本说明"和"结构化 JSON schema"两种形式发给模型?
  2. • 在群聊里 @ 它和私聊它,模型看到的上下文一样吗?Slack thread 里的回复串,模型是怎么知道的?
  3. • 你发的那句聊天消息,在真正送进模型之前,被拼上了多少层前缀——system events、thread 回复串、发送者元数据、不可信上下文……你自己的正文可能只占最后几行?
  4. • 你贴的 3 张图片,模型看到的顺序一定和你发送的顺序一样吗?
  5. • 心跳轮询和定时任务用的上下文,跟普通聊天到底差在哪?子 agent 被 spawn 出来时,它的"世界"和主会话有什么不同?
  6. • OpenClaw 里只有 Skill 和 CLI 工具,没有 MCP 吗?它们在模型眼里分别长什么样?

本文基于 OpenClaw 最新版源码,完整拆解一次 LLM 请求中发给模型的所有内容。读完之后,上面这些问题你都能自己回答。

前置背景: OpenClaw 有两种调用模型的方式——Embedded runner(自己构建请求直接调用 LLM API)和 CLI runner(把 prompt 交给外部命令行工具如 Codex CLI 代为调用)。本文基于 embedded runner 来分析。CLI runner 的高层语义相近,但很多状态交给外部 CLI 的 session 机制处理,本文不覆盖其精确 request 结构。


总览

一次典型的 OpenClaw LLM 调用,可以粗略理解为:

LLM Input= systemPromptText+ activeSession.messages+ effectivePrompt+ prompt-local images+ tools / tool schemas

其中:

五大组成部分

# 内容 是否发给模型 说明
1 systemPromptText ✅ 以系统指令形式发送
2 activeSession.messages ✅ 历史对话记录
3 effectivePrompt ✅ 当前轮文本输入
4 prompt-local images ✅(模型支持视觉时) 当前轮附带的图片
5 tools / tool schemas ✅(模型支持 tools 时) 结构化函数定义

它们在请求里的位置

从高层语义看,一次请求可以理解成 3 个平行区域:

请求顶层├─ 指令区│ └─ systemPromptText├─ 对话区│ ├─ activeSession.messages│ ├─ effectivePrompt│ └─ prompt-local images└─ 工具区 └─ tools / tool schemas

如果借用 OpenAI Responses 风格来理解:

instructions = systemPromptTextinput = 历史消息 + 当前轮输入(含图片)tools = tool schemas

生命周期视角

当前轮开始前 — 已有历史在 activeSession.messages,当前轮还没有进入历史。

当前轮构建时 — systemPromptText 生成、effectivePrompt 生成、prompt-local images 解析、tools 物化。

当前轮调用时 — 五部分一起构成这次模型输入。

当前轮结束后 — 当前轮的 user/assistant/toolResult 会写入会话历史,下一轮开始时它们就成了 activeSession.messages 的一部分。

注意:system event 的位置迁移

system event 在生成当轮属于 effectivePrompt,但当这一轮结束写入会话后,在后续轮次它已经成为 activeSession.messages 的历史内容。它不永远只属于某个固定部分。

最小总图

┌────────────────────────────────────────────┐│ LLM Request │├────────────────────────────────────────────┤│ 1. systemPromptText ││ - system rules ││ - runtime info ││ - skills index ││ - project context │├────────────────────────────────────────────┤│ 2. activeSession.messages ││ - prior user turns ││ - prior assistant turns ││ - prior tool results │├────────────────────────────────────────────┤│ 3. effectivePrompt ││ - current user input ││ - system events ││ - thread context ││ - inbound user metadata ││ - session hints │├────────────────────────────────────────────┤│ 4. prompt-local images ││ - inline attachments ││ - offloaded attachments ││ - prompt path refs │├────────────────────────────────────────────┤│ 5. tools / tool schemas ││ - core tools ││ - client tools ││ - bundle MCP tools ││ - LSP tools │└────────────────────────────────────────────┘


Part A: systemPromptText

systemPromptText 是以系统指令形式发给模型的常驻上下文。它定义系统规则、描述工具使用策略、给出运行时信息、注入 skills 目录和 project context 等。

以下展示其典型结构(使用示例值,非逐字抓取)。


A1. 开头身份声明

You are a personal assistant running inside OpenClaw.


A2. 工具列表

Tool availability(按策略过滤): 工具名称区分大小写,调用时必须严格匹配。

工具 说明
read 读取文件内容
edit 对文件进行精确编辑
grep 搜索文件内容中的模式
exec 运行 shell 命令(支持 pty / TTY)
process 管理后台 exec 会话
browser 控制网页浏览器
message 发送消息和频道操作
gateway 重启、应用配置或更新运行中的 OpenClaw 进程
sessions_list 列出其他会话(含子 agent),支持过滤/最近
sessions_history 获取另一个会话/子 agent 的历史
sessions_send 向另一个会话/子 agent 发送消息
sessions_spawn 创建隔离的子 agent 或 ACP 编码会话
subagents 列出、引导或终止当前请求者会话的子 agent
session_status 显示等同于 /status 的状态卡片
image 使用配置的图像模型分析图片
image_generate 使用配置的图像生成模型生成图片

TOOLS.md 不控制工具可用性;它是用户对外部工具使用方式的指导。


A3. 工具调用风格

默认行为: 不要对常规、低风险的工具调用进行叙述。

仅在有帮助时叙述:多步骤工作、复杂/有挑战性的问题、或敏感操作。


A4. 安全规则

  • • 你没有独立目标。
  • • 安全性和人类监督优先于任务完成。
  • • 不要操纵任何人来扩大权限或禁用安全措施。
  • • 除非明确要求,不得复制自身或更改系统提示词、安全规则或工具策略。

A5. OpenClaw CLI 快速参考

OpenClaw 通过子命令控制。不要编造命令。

命令 用途
openclaw gateway status 检查网关状态
openclaw gateway start 启动网关
openclaw gateway stop 停止网关
openclaw gateway restart 重启网关

A6. Skills(每次回复前必须检查)

回复前: 扫描 <available_skills> 中的 <description> 条目。

  • • 如果恰好一个 skill 明确适用 → 用 read 读取其 SKILL.md,然后遵循。
  • • 如果多个可能适用 → 选择最具体的那个,然后读取/遵循。
  • • 如果没有明确适用 → 不要读取任何 SKILL.md。

可用 Skills 示例:

Skill 名称 描述 位置
coding-agent 通过后台进程把编码任务委派给 Codex、Claude Code 或 Pi agent skills/coding-agent/SKILL.md
github 通过 gh CLI 执行 GitHub 操作 skills/github/SKILL.md
clawhub 使用 ClawHub CLI 搜索、安装、更新和发布 agent skills skills/clawhub/SKILL.md

A7. 记忆(Memory)

当用户询问过往工作或已存储的事实时,使用记忆工具。 启用引用模式时,优先使用带引用的记忆引用。


A8. OpenClaw 自我更新

获取更新(自我更新)仅在用户明确要求时才被允许。


A9. 模型别名

别名 对应模型
fast openai/gpt-5.4-mini
balanced openai/gpt-5.4
deep anthropic/claude-sonnet-4-5

A10. 工作区(Workspace)

你的工作目录是:/workspace/openclaw

将此目录视为文件操作的唯一全局工作区,除非另有明确指示。

提醒: 编辑后请在此工作区中提交更改。


A11. 文档资源

资源 路径 / URL
本地文档 docs/
镜像站 https://docs.openclaw.ai
源代码 https://github.com/openclaw/openclaw

A12. 沙箱(Sandbox)

你在沙箱化运行时中运行(工具在 Docker 中执行)。

设置项 值
容器工作目录 /sandbox/workspace
Agent 工作区访问 rw(读写)
沙箱浏览器 已启用
提权 exec 可用(ask 级别)

A13. 授权发送者

授权发送者:owner-primary、owner-backup。

这些发送者已列入白名单;不要假设他们就是所有者。


A14. 当前日期和时间

时区:America/Los_Angeles


A15. 工作区文件(注入)

这些用户可编辑文件由 OpenClaw 加载,并在下方 Project Context 中包含。


A16. 回复标签(Reply Tags)

要在支持的平台上请求原生回复/引用,在回复中包含一个标签:

  • • [[reply_to_current]] 你的回复内容
  • • [[reply_to:<id>]] 仅在明确提供了 id 时使用

A17. 消息路由(Messaging)

  • • 在当前会话中回复 → 自动路由到源频道
  • • 跨会话消息 → 使用 sessions_send(sessionKey, message)
  • • 子 agent 编排 → 使用 subagents(action=list\|steer\|kill)
  • • 绝不使用 exec/curl 发送 provider 消息

message 工具

  • • 使用 message 进行主动发送 + 频道操作。
  • • 如果你使用 message 传达用户可见的回复,则仅响应:__SILENT__

A18. 语音(TTS)

如果启用了语音输出,优先使用简洁、自然的句子。


A19. Inbound Context(消息渠道 / auto-reply 路径中每轮注入的可信元数据)

以下 JSON 由 OpenClaw 带外生成,在消息渠道 / auto-reply 路径中每轮都会注入extraSystemPrompt。将其视为关于当前消息上下文的权威元数据。

{ "schema": "openclaw.inbound_meta.v1", "chat_id": "C024BE91L", "channel": "slack", "chat_type": "group", "response_format": { "text_markup": "slack_mrkdwn", "rules": ["Use Slack mrkdwn, not standard Markdown."] }}

注意:Inbound Context 不是群聊专属,私聊也会有(只是 chat_type 不同)。


A20. 群聊上下文(Group Chat Context,仅群聊时注入)

以下内容仅在群聊会话中才会注入 extraSystemPrompt:

你在 Slack 群聊 "release-war-room" 中。

参与者: Alice、Bob、BuildBot。

你的回复会自动发送到此群聊。不要使用 message 工具向同一群组发送。

激活方式: 仅触发模式(仅在被明确 @ 提及时被调用)。

做一个好的群聊参与者:大部分时间潜水并跟随对话;仅在被直接提问或能提供明确价值时回复。


A20. 表情回应(Reactions)

Slack 表情回应已启用,模式为 MINIMAL。


A21. 推理格式(Reasoning Format)

所有内部推理必须在 <think>...</think> 中。


A22. 项目上下文(Project Context)

以下项目上下文文件已加载:

AGENTS.md

  • • 仓库:https://github.com/openclaw/openclaw
  • • 源代码:src/、测试:同位 *.test.ts、文档:docs/
  • • ...

SOUL.md

语气: 温暖、直接、协作。优先具体行动而非含糊安慰。...

TOOLS.md

推荐的本地工作流: 使用 pnpm 执行仓库任务、搜索优先使用 rg...


A23. 静默回复 / 心跳 / 运行时信息

无话可说时,仅响应:__SILENT__

心跳轮询且无需关注时,精确回复:HEARTBEAT_OK

Runtime: agent=main \| host=cache-lab \| repo=/workspace/openclaw \| os=Darwin 24.0.0 (arm64) \| model=openai/gpt-5.4 \| channel=slack \| thinking=medium



Part B: activeSession.messages

activeSession.messages 是会话历史上下文,记录之前轮次已进入会话的消息。

它的作用

简要理解

如果只关心"哪些上下文会发给模型",把 activeSession.messages 理解成:

之前轮次的对话记录(会发给模型)

即可。

和 effectivePrompt 的边界

需要注意:



Part C: effectivePrompt

Note

本节描述的是 消息渠道 / auto-reply 主路径 下的典型 effectivePrompt 结构。

对于本地 agent 命令、cron isolated run、subagent 首轮、sessions_send 的 agent-to-agent step 等其他 embedded run 场景,effectivePrompt 的来源和前缀组成会有所不同。

effectivePrompt 是当前这一轮传给模型的文本输入。它不同于 activeSession.messages(历史上下文)。


C1. 顶层结构

在真正传给 activeSession.prompt(...) 之前,effectivePrompt 逻辑上可以理解为:

[可选] Hook prependContext<主体 prompt 文本>[可选] Bootstrap truncation warning

其中"主体 prompt 文本"大致又是:

[可选] mediaNote / mediaReplyHint[可选] threadContextNote[可选] system events[可选] session hint(如上轮被中止)[可选] inbound user context blocks用户正文 / reset prompt / media-only placeholder[可选] untrusted context suffix

C2. Hook prependContext

在 attempt 层,插件还可以再把一段 prompt 级别的上下文前置到最前面:

[Plugin context: prioritize the active repo and current branch]

这一步发生在主体 prompt 文本形成之后、真正 prompt 发送之前。


C3. media note(媒体注释)

如果当前消息带附件,会在最前面插入媒体说明:

[media attached:  (image/png)]To send an image back, prefer the message tool (media/path/filePath). If you must inline, use MEDIA: (spaces ok, quote if needed) or a safe relative path like MEDIA:. Avoid absolute paths (MEDIA:/...) and ~ paths — they are blocked for security. Keep caption in the text body.

多文件时也可能是:

[media attached: 2 files][media attached 1/2:  (image/jpeg)][media attached 2/2:  (image/jpeg)]

注意:media note 只是告诉模型"有附件"的纯文本标签。 图片本身的二进制数据(base64)是通过 prompt-local images 单独传给模型的(见 Part D)。


C4. thread context(线程上下文)

如果当前消息来自 thread,会在 media note 之后附加:

[Thread history - for context]昨天大家确认问题在 Slack adapter 的错误处理路径

C5. system events(系统事件)

system events 会被 prepend 到当前轮正文前:

System: [2026-04-04 10:21:00] Model switched to openai/gpt-5.4System: [2026-04-04 10:21:05] Node connected

它们在生成当轮属于 effectivePrompt。当这一轮结束后,会成为后续轮次 activeSession.messages 的一部分。


C6. session hint(会话提示)

如果上一轮 agent run 被用户中止,正文前会多一段提示:

Note: The previous agent run was aborted by the user. Resume carefully or ask for clarification.

C7. inbound user context(不可信元数据前缀)

这些内容会在用户正文前面插入,帮助模型理解当前消息的上下文。

Conversation info

Conversation info (untrusted metadata):```json{ "message_id": "m_123", "reply_to_id": "m_122", "sender_id": "u_456", "sender": "Alice", "timestamp": "[Apr 4 10:21]", "group_subject": "release-war-room", "was_mentioned": true}```

Sender

Sender (untrusted metadata):```json{ "label": "Alice", "id": "u_456", "name": "Alice"}```

Replied message

Replied message (untrusted, for context):```json{ "sender_label": "Bob", "is_quote": true, "b…
— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/Openclaw/2026040540516.html