跳转至

上下文

“上下文”是 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.md
  • SOUL.md
  • IDENTITY.md
  • USER.md
  • BOOTSTRAP.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。

工具:存在两种成本

工具会以两种方式影响上下文:

  1. 系统提示中的工具列表文本(你看到的 “Tooling”)。
  2. 工具模式(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