跳转至

上下文

“Context” 是 OpenClaw 在一次运行中发送给模型的全部内容。它受模型的上下文窗口（token 限制）约束。

初学者心智模型：

  • 系统提示（System prompt）（OpenClaw 构建）：规则、工具、技能列表、时间/运行时，以及注入的工作区文件。
  • 会话历史（Conversation history）：你发送的消息 + 本次会话中助手的消息。
  • 工具调用/结果 + 附件：命令输出、文件读取、图像/音频等。

上下文与“记忆”不是一回事：记忆可以存储在磁盘上并在之后重新加载；上下文是模型当前窗口内部的内容。

快速开始（检查上下文）

  • /status → 快速查看“我的窗口有多满？” + 会话设置。
  • /context list → 显示注入了什么 + 大致大小（每个文件 + 合计）。
  • /context detail → 更详细的分解：每个文件、每个工具 schema 的大小，每个技能条目的大小，系统提示大小，以及可压缩的转录消息数量。
  • /context map → 当前会话中被跟踪的上下文贡献者的 WinDirStat 风格树状图图像。
  • /usage tokens → 在普通回复末尾附加每次回复的用量页脚。
  • /compact → 将较早的历史记录总结为紧凑条目，以释放窗口空间。

另请参阅：斜杠命令、Token 使用与成本、压缩。

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 条目
  • 工具 JSON schemas

会话组会随会话增长而变化，因此该地图每一轮都会变化；压缩后，它会折叠为摘要块。

当没有缓存的运行报告时，/context list、/context detail 和 /context json 仍然可以检查按需估算。

哪些内容会计入上下文窗口

模型接收到的所有内容都会计入，包括：

  • 系统提示（所有部分）。
  • 会话历史。
  • 工具调用 + 工具结果。
  • 附件/转录（图像/音频/文件）。
  • 压缩摘要与剪枝产物。
  • 提供商的“包装器”或隐藏头部（不可见，但仍会计入）。

OpenClaw 如何构建系统提示

系统提示是 OpenClaw 所有，并在每次运行时重建。它包括：

  • 工具列表 + 简短描述。
  • 技能列表（仅元数据；见下文）。
  • 工作区位置。
  • 时间（UTC + 转换后的用户时间（如果配置））。
  • 运行时元数据（主机/操作系统/模型/思考）。
  • Project Context 下注入的工作区引导文件。

完整分解：System Prompt。

注入的工作区文件（Project Context）

默认情况下，OpenClaw 会注入一组固定的工作区文件（如果存在）：

  • AGENTS.md
  • SOUL.md
  • IDENTITY.md
  • USER.md
  • BOOTSTRAP.md（仅首次运行）

大文件会使用 agents.defaults.bootstrapMaxChars（默认 20000 字符）按文件进行截断。OpenClaw 还通过 agents.defaults.bootstrapTotalMaxChars（默认 60000 字符）对所有文件执行总 bootstrap 注入上限。/context 显示 raw vs injected 的大小以及是否发生了截断。

当发生截断时，运行时会在 Project Context 下注入一条简洁的提示内通知，说明某些 bootstrap 文件已被截断；每个文件的名称和大小保留在 /context 和其他诊断信息中。此通知是内置的，不可配置。

技能：注入 vs 按需加载

系统提示中包含一个紧凑的 技能列表（名称 + 描述 + 位置）。该列表有实际的开销。

默认情况下不包含技能指令。模型应在需要时才 read 技能的 SKILL.md。

工具：存在两种成本

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

  1. 系统提示中的 工具列表文本（即你看到的“Tooling”）。
  2. 工具 schemas（JSON）。这些会发送给模型以便其调用工具。即使你不会以纯文本形式看到它们，它们也会计入上下文。

/context detail 会拆解最大的工具 Schema，让你看清哪些内容占主导。

命令、指令与“内联快捷方式”

斜杠命令由 Gateway 处理。有几种不同的行为：

  • 独立命令：仅包含 /... 的消息会作为命令运行。
  • 指令（Directives）：/think、/fast、/verbose、/trace、/reasoning、/elevated、/exec、/model、/queue 会在模型看到消息之前被剥离。
  • 仅包含指令的消息会使会话设置持续生效。
  • 普通消息中的内联指令会充当单条消息的提示。
  • 内联快捷方式（仅限白名单发送者）：普通消息中的某些 /... Token 可以立即执行（例如：“hey /status”），并会在模型看到剩余文本之前被剥离。

详细信息：斜杠命令。

会话、压缩与剪枝（什么会持久保留）

消息之间哪些内容会持久保留，取决于具体机制：

  • 正常历史记录会一直保留在会话记录中，直到按策略被压缩或剪枝。
  • 压缩（Compaction）会将摘要持久化到会话记录中，并保持最近的消息完整。
  • 剪枝（Pruning）会从_内存中的_ Prompt 中丢弃旧的工具结果，以释放上下文窗口空间，但不会重写会话记录——完整历史仍可在磁盘上查看。

对于嵌入式 Responses 请求，当前请求的元数据会保留在用户消息或压缩检查点之后、其工具调用之前。这使得受支持的传输方式能够在工具轮次之间复用先前的响应，而不会丢失实时上下文。在 OpenAI Responses 系列会话中，后续的用户回合会以仅追加（append-only）方式保留隐藏的运行时上下文载体，因此上一个回合（包括工具调用及其结果）会保持为不变的缓存前缀。保留的载体会计入上下文窗口，直到发生压缩；压缩不会将用户消息与其载体拆分开。载体仅包含定界后的上下文主体；解读指导只存在于稳定的 System Prompt 中。其他传输方式会将临时元数据保留在请求尾部，以便在下一次用户回合将其移除时，保留其缓存的历史前缀。

文档：会话、压缩、会话剪枝。

默认情况下，OpenClaw 使用内置的 legacy 上下文引擎来进行上下文组装和压缩。如果你安装的插件提供了 kind: "context-engine"，并通过 plugins.slots.contextEngine 选择了它，那么 OpenClaw 会将上下文组装、/compact 以及相关的子智能体上下文生命周期钩子委托给该引擎。ownsCompaction: false 不会自动回退到 legacy 引擎；活动引擎仍必须正确实现 compact()。完整的可插拔接口、生命周期钩子和配置，请参阅上下文引擎。

/context 实际报告什么

/context 在可用时会优先采用最新的运行构建（run-built）System Prompt 报告：

  • System prompt (run) = 从最近一次嵌入式（支持工具的）运行中捕获，并持久化在会话存储中。
  • System prompt (estimate) = 在没有运行报告时（或通过不生成报告的 CLI 后端运行时）即时计算得出。

无论哪种方式，它都会报告大小和主要贡献者；它不会转储完整的 System Prompt 或工具 Schema。在详细模式下，它还会将会话记录与压缩所用的同一个真实对话消息谓词进行比对，因此较高的 Prompt/缓存占用更容易与可压缩的对话历史区分开来。

上下文引擎

通过插件进行自定义上下文注入。

压缩

对长对话进行摘要总结，使其保持在模型窗口内。

System Prompt

System Prompt 是如何构建的，以及每轮会注入什么内容。

智能体循环

从入站消息到最终回复的完整智能体执行周期。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw