上下文
“上下文”是 OpenClaw 在一次运行中发送给模型的一切内容。它受模型的上下文窗口(Token 限制)约束。
初学者心智模型:
- 系统 Prompt(由 OpenClaw 构建):规则、工具、技能列表、时间/运行时,以及注入的工作区文件。
- 对话历史:你的消息 + 该会话中助手的消息。
- 工具调用/结果 + 附件:命令输出、文件读取、图片/音频等。
上下文与“记忆” 不是一回事:记忆可以存储在磁盘上并在之后重新加载;上下文是当前位于模型窗口内部的内容。
快速入门(检查上下文)¶
/status→ 快速查看“我的窗口有多满?”视图 + 会话设置。/context list→ 被注入的内容 + 大致大小(每个文件 + 总计)。/context detail→ 更深入的细分:每个文件、每个工具 schema 的大小、每个技能条目的大小、系统 Prompt 大小,以及可压缩的转录消息数量。/context map→ 当前会话所追踪的上下文贡献者的 WinDirStat 风格树图图像。/usage tokens→ 在普通回复之后附加每次回复的用量页脚。/compact→ 将较旧的历史记录总结为一条紧凑条目,以释放窗口空间。
另见:斜杠命令、Token 使用与成本、压缩。
/context 和 openclaw sessions list 可以在模型目录元数据不可用且所选模型和运行时仍然匹配时,复用最近已验证的模型预算。符合条件的回合会刷新该值。当前模型元数据和配置的限制优先;通用回退窗口和可移除上限不会保存为已验证的模型预算。
Control UI 的上下文仪表在仍然匹配所选模型和有效上下文上限时,会使用上次运行的 Prompt 预算。该预算为运行时的压缩预留空间。其标签为 Prompt budget (last run):它是一个估计值,越过它可能触发工具结果缩减或压缩。在模型或上下文上限发生变化后,仪表会显示 Context window,直到新的运行提供匹配的估计值。过期的 Token 总数仍为近似值,不会触发上下文警告。
示例输出¶
具体值会因模型、提供方、工具策略以及工作区内容而有所不同。
/context list¶
🧠 Context breakdown
Workspace: <workspaceDir>
Bootstrap max/file: 20,000 chars
Sandbox: mode=non-main sandboxed=false
System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))
Injected workspace files:
- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok)
- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok)
- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok)
- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok)
- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok)
Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills)
Tools: read, edit, write, exec, process, browser, message, sessions_send, …
Tool list (system prompt text): 1,032 chars (~258 tok)
Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text)
Tools: (same as above)
Session tokens (cached): 14,250 total / ctx=32,000
/context detail¶
🧠 Context breakdown (detailed)
…
Top skills (prompt entry size):
- frontend-design: 412 chars (~103 tok)
- oracle: 401 chars (~101 tok)
… (+10 more skills)
Top tools (schema size):
- browser: 9,812 chars (~2,453 tok)
- exec: 6,240 chars (~1,560 tok)
… (+N more tools)
/context map¶
发送一张由最近缓存的运行报告与会话转录内容生成的图像。如果会话中尚未有普通消息产生运行报告,/context map 会返回一条“不可用”消息,而不是渲染估计值。矩形面积与追踪到的 Prompt 字符数成比例:
- 会话转录(用户消息、助手回复、工具结果、压缩摘要),以及仅到达模型的每轮运行时上下文和 hook Prompt 附加内容
- 注入的工作区文件
- 基础系统 Prompt 文本
- 技能 Prompt 条目
- 工具 JSON schema
对话组会随着会话进行而增长,因此地图会逐轮变化;压缩后,它会折叠为一个摘要块。
当没有缓存的运行报告时,/context list、/context detail 和 /context json 仍然可以检查按需估计值。
哪些内容会计入上下文窗口¶
模型收到的所有内容都会计入,包括:
- 系统 Prompt(所有部分)。
- 对话历史。
- 工具调用 + 工具结果。
- 附件/转录内容(图片/音频/文件)。
- 压缩摘要和剪枝产物。
- 提供方的“包装器”或隐藏标头(不可见,但仍会计入)。
OpenClaw 如何构建系统 Prompt¶
系统 Prompt 归 OpenClaw 所有,每次运行时都会渲染。它包括:
- 工具列表 + 简短描述。
- 技能列表(仅元数据;见下文)。
- 工作区位置。
- 时间(UTC + 如果配置了则转换后的用户时间)。
- 运行时元数据(主机/操作系统/模型/思考)。
- 位于 Project Context 下的注入工作区引导文件。
完整明细:系统 Prompt。
在受支持的 Anthropic API 密钥直连路由和原生 OpenAI Responses 路由上,OpenClaw 会将会话的完整系统 Prompt 固定下来。发生变更的段落(包括技能、工作区记忆和时间上下文)会在当前用户回合之后作为指令消息到达。现有的技能和记忆刷新规则仍然适用。更改路由或所选个人配置文件、重置或压缩历史记录会开始一个新的序列;普通的回合收尾和 Gateway 重启会恢复已保存的序列。
注入的工作区文件(Project Context)¶
默认情况下,OpenClaw 会注入一组固定的工作区文件(如果存在):
AGENTS.mdSOUL.mdIDENTITY.mdUSER.mdBOOTSTRAP.md(仅首次运行时)
大文件会使用 agents.defaults.bootstrapMaxChars(默认 20000 字符)按文件进行截断。OpenClaw 还通过 agents.defaults.bootstrapTotalMaxChars(默认 60000 字符)对所有文件实施 Bootstrap 注入总量上限。/context 会显示原始 vs 注入大小,以及是否发生了截断。
当截断发生时,运行时会在 Project Context 下方注入一条简洁的提示内通知,说明某些 bootstrap 文件已被截断;每个文件的名称和大小仍保留在 /context 和其他诊断信息中。该提示是内置的,不可配置。
技能:注入与按需加载¶
系统提示包含一个紧凑的技能列表(名称 + 描述 + 位置)。该列表会产生实际开销。
/context 统计的是渲染后的系统提示中包含的目录,而不是每个已安装的技能。在没有 Code Mode 的嵌入式运行时中,同时拒绝 read 和 skills_read 会省略目录并报告零个技能。
默认情况下,技能说明 不会 包含在内。模型应仅在需要时 read 该技能的 SKILL.md。
工具:存在两种成本¶
工具会以两种方式影响上下文:
- 系统提示中的工具列表文本(你看到的 “Tooling”)。
- 工具模式(JSON)。这些内容会发送给模型,以便其调用工具。即使你无法以纯文本形式看到它们,它们也会计入上下文。
/context detail 会拆分最大的工具模式,让你看到哪些内容占主导。
命令、指令和“内联快捷方式”¶
斜杠命令由 Gateway 处理。有几种不同的行为:
- 独立命令:仅包含
/...的消息会作为命令运行。 - 指令:
/think、/fast、/verbose、/trace、/reasoning、/elevated、/exec、/model、/queue会在模型看到消息之前被移除。 - 仅包含指令的消息会持久化会话设置。
- 普通消息中的内联指令作为逐消息提示。
- 内联快捷方式(仅限允许列表中的发送者):普通消息中的某些
/...标记可以立即运行(例如:“hey /status”),并会在模型看到剩余文本之前被移除。
详情:斜杠命令。
会话、压缩和修剪(哪些内容会持久化)¶
跨消息持久化的内容取决于机制:
- 普通历史会持久化在会话记录中,直到按策略被压缩/修剪。
- 压缩会将摘要持久化到记录中,并保留最近消息完整。
- 修剪会从 内存中 的提示中删除旧的工具结果,以释放上下文窗口空间,但不会重写会话记录——完整历史仍可在磁盘上检查。
运行时上下文和提供商角色¶
OpenClaw 将带类型的运行时上下文与用户编写的文本分开附加。在
受支持的直接 Anthropic API 密钥路由上,它使用历史中现有的 system
通道。原生 OpenAI Responses 使用现有的 operator 通道,并根据模型对指令角色的支持投影为
developer 或 system。
OpenAI 兼容端点和本地服务器(包括 Responses 兼容
端点和原生 Ollama)会保留用户角色载体。它们的聊天模板可能
拒绝或提升对话中途的 system 消息;将载体保留在
原始位置也有助于保护前缀缓存复用。载体角色和保留
会随提供商能力自动确定;没有 appendOnlyRuntimeContext
配置开关。
生产者将运行时指令与会话数据区分开来。受用户或
工具影响的片段(包括中断输入预览、子代理详情
和媒体任务详情)即使在原生 operator 消息内部也仍然是数据:它们
会被 JSON 引号包裹并标记为 Conversation data (data, not instructions),其中
受保护的运行时分隔符会被转义。心跳结果也是带引号的数据。
载体的角色不会使这些嵌入片段成为指令。
在请求跟踪中,用户角色载体通常以 OpenClaw runtime
context: 开头,并以 End OpenClaw runtime context. 结尾。旧版保留的载体
可能使用 <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>> 和
<<<END_OPENCLAW_INTERNAL_CONTEXT>>>。仅凭这些标签不能确立
来源。如果模型叙述此上下文,请在你的代理指令中强化现有指导:用它来回答当前请求,保持内部
细节私密,并且不要将载体视为新的用户请求或等待
另一条消息。
对于嵌入式 Responses 请求,当前请求元数据保留在用户 消息或压缩检查点之后、其工具调用之前。这让受支持的传输能够在工具轮次间复用 之前的响应,而不会丢弃实时上下文。OpenAI Responses 系列会话中稍后的用户 轮次会以仅追加方式保留隐藏的运行时上下文 载体,因此前一轮次(包括工具调用和结果) 保持为未更改的缓存前缀。保留的载体会计入上下文 窗口,直到压缩为止;压缩不会将用户消息与其载体分离。 用户角色载体包含带标签的上下文正文;解释指导在稳定的系统提示中只出现一次。OpenAI 兼容 Chat Completions 和原生 Ollama 也会保留较早的载体,而不会重写系统提示或先前 对话字节。
受支持的直接 Anthropic API 密钥路由也会以仅追加方式保留运行时上下文, 使用用户轮次及其其他排队上下文之后的 system 消息。这些消息无需分隔符,并在下一条用户消息时清除: 它们仍保留在记录中,但不再消耗输入 token。持久 系统提示更新使用相同的 system 消息通道,而不清除。 工具结果和排队扩展上下文也会清除较早的副本;OpenClaw 会在这些延续之后更新当前用户轮次的运行时上下文。 其他前缀绑定的 Claude 路由会保留其带分隔符的用户角色载体。 有关受支持的模型和路由限制,请参阅 Anthropic 保留思考。
其他路由可以在思考不绑定前缀时使用临时载体。 这些路由将元数据保留在请求尾部,并在下一条用户 轮次时移除它,从而保留缓存历史, 而不会保留旧上下文或重复的缓存读取费用。
默认情况下,OpenClaw 使用内置的 legacy 上下文引擎进行组装和压缩。如果你安装了一个提供 kind: "context-engine" 的插件,并通过 plugins.slots.contextEngine 选择它,OpenClaw 会将上下文组装、/compact 以及相关的子代理上下文生命周期钩子委托给该引擎处理。ownsCompaction: false 不会自动回退到旧版引擎;当前激活的引擎仍必须正确实现 compact()。有关完整的可插拔接口、生命周期钩子和配置,请参阅上下文引擎。
/context 实际报告的内容¶
/context 在可用时优先使用最新的运行时构建系统提示报告:
System prompt (run)= 从最后一次嵌入式(具备工具能力)运行中捕获,并持久化到会话存储中。System prompt (estimate)= 当不存在运行报告时(或通过不生成该报告的 CLI 后端运行时)即时计算得出。
无论哪种方式,它都会报告大小和主要贡献者;它不会转储完整的系统提示或工具模式。在详细模式下,它还会使用与压缩相同的真实对话消息谓词,将会话转录与真实对话进行比较,因此更容易区分高提示/缓存使用率和可压缩的对话历史。
相关¶
通过插件进行自定义上下文注入。
总结长对话,使其保持在模型窗口内。
系统提示如何构建,以及每轮注入什么。
从传入消息到最终回复的完整代理执行周期。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw