LLM-Context 之于 Agent 就像 PCB 之于 OS,是你理解Agent的钥匙
当你对 OpenClaw 说"帮我查一下这个 bug",你以为模型收到的就是这句话?远不止。
它收到的是一整套精心组装的上下文:系统指令、历史对话、你的消息(外加一堆你看不见的元数据前缀)、图片、以及几十个可调用工具的结构化定义。这些东西加在一起,才构成了模型这一轮"看到的世界"。
你有没有想过——
- • system prompt 里那 22 个 section 都塞了什么?为什么工具要同时以"纯文本说明"和"结构化 JSON schema"两种形式发给模型?
- • 在群聊里 @ 它和私聊它,模型看到的上下文一样吗?Slack thread 里的回复串,模型是怎么知道的?
- • 你发的那句聊天消息,在真正送进模型之前,被拼上了多少层前缀——system events、thread 回复串、发送者元数据、不可信上下文……你自己的正文可能只占最后几行?
- • 你贴的 3 张图片,模型看到的顺序一定和你发送的顺序一样吗?
- • 心跳轮询和定时任务用的上下文,跟普通聊天到底差在哪?子 agent 被 spawn 出来时,它的"世界"和主会话有什么不同?
- • 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
其中:
- •
systemPromptText= 系统规则、运行时信息、skills 索引、project context - •
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 是会话历史上下文,记录之前轮次已进入会话的消息。
它的作用
- • 提供历史对话上下文,让模型知道前面聊到哪里
- • 包含之前的 user/assistant 消息和 tool result
- • 为 compaction、tool result 修复、context engine、hooks 等流程提供历史基础
简要理解
如果只关心"哪些上下文会发给模型",把 activeSession.messages 理解成:
之前轮次的对话记录(会发给模型)
即可。
和 effectivePrompt 的边界
- •
activeSession.messages= 历史上下文 - •
effectivePrompt= 当前这一轮新输入
需要注意:
- •
system event在生成当轮先进入effectivePrompt - • 当这一轮结束并写入会话后,在后续轮次它就成了
activeSession.messages的一部分
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…