跳至主要內容

OpenClaw Context 上下文概念详解

2026/5/4大约 5 分钟

OpenClaw Context 上下文概念详解

上下文（Context）是 OpenClaw 在一次智能体运行中发送给模型的全部内容，是模型完成推理、工具调用与对话生成的唯一信息来源，其大小严格受模型上下文窗口（Token 上限）约束。本文基于官方概念文档，完整拆解上下文的组成、构建规则、开销管控、调试手段与优化方法。

一、上下文核心定义

上下文≠记忆：

  • 上下文：当前运行周期内模型可见的临时内容集合，仅存在于单次推理窗口中。

  • 记忆：存储在磁盘的持久化数据（如 MEMORY.md），可跨会话加载，不会自动进入上下文。

新手极简心智模型：
上下文 = 系统提示词 + 对话历史 + 工具调用/结果 + 附件

二、上下文的三大核心组成

  1. 系统提示词
    OpenClaw 自主构建，包含规则、工具清单、技能列表、时间/运行时信息、注入的工作区文件，不沿用 pi-coding-agent 默认提示词。

  2. 对话历史
    当前会话内用户与智能体的全部消息记录，按时序排列。

  3. 工具调用/结果 + 附件
    命令执行输出、文件读取内容、图片/音频转写、文档解析结果等富媒体与交互数据。

三、计入上下文窗口的全部内容

所有发送给模型的内容均占用 Token，包含可见与不可见部分：

  1. 完整系统提示词（所有模块）

  2. 全量对话历史

  3. 工具调用参数与执行结果

  4. 附件、音视频转文本内容

  5. 上下文压缩摘要、修剪后的精简内容

  6. 模型提供商的隐藏包装头（不可见但计入）

四、OpenClaw 系统提示词构建逻辑

系统提示词为每次运行动态重建，核心模块包括：

  • 工具列表与简要描述

  • 可用技能元数据（名称、描述、路径）

  • 工作区目录路径

  • 时间信息（UTC + 用户时区）

  • 运行时元数据（主机、系统、Node 版本、模型、思考级别）

  • 注入的工作区引导文件

  • 沙箱运行规则（启用时）

  • 安全防护、回复标签、心跳规则

五、工作区文件注入规则与截断机制

OpenClaw 自动注入固定工作区文件，作为项目上下文供模型直接读取：

  • 注入文件：AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md（仅全新工作区）

  • 截断规则：单文件最大长度由 agents.defaults.bootstrapMaxChars 控制（默认 20000 字符），超大文件自动截断并标记，缺失文件注入缺失标记

  • 自定义修改：可通过 agent:bootstrap 内部钩子拦截，替换注入文件

六、Skills 技能的上下文开销与加载策略

  • 轻量注入：仅在系统提示词中注入技能名称、描述、路径，不加载完整指令，控制基础开销

  • 按需加载：模型需使用技能时，主动通过 read 指令读取对应 SKILL.md 文件

  • 开销可视：/context detail 可查看每个技能的提示词条目大小，定位高开销技能

七、工具的双重上下文成本

工具会产生两部分上下文占用，是上下文膨胀的主要来源：

  1. 工具列表文本：系统提示词中可见的工具清单

  2. 工具 Schema（JSON）：供模型调用的参数定义，不可见但计入上下文，复杂工具（如 browser、exec）Schema 体积极大

八、斜杠命令对上下文的处理

斜杠命令由 Gateway 预处理，不进入模型上下文：

  • 独立命令：纯 /xxx 消息作为指令执行，不送入模型

  • 指令剥离：/think、/verbose、/model 等指令在模型接收前被剥离，仅留存会话配置

  • 内联快捷方式：消息中的 /status 等快捷指令被剥离执行，剩余文本送入模型

九、会话上下文的持久化、压缩与修剪

  1. 持久化
    正常对话历史持久化到会话记录，直至被策略压缩或修剪。

  2. 压缩（Compaction）
    上下文接近窗口上限时，自动将旧历史总结为紧凑条目，保留近期消息，释放 Token 空间；可手动执行 /compact 触发。

  3. 修剪（Pruning）
    从内存提示词中移除旧工具结果，不修改磁盘记录，减少实时上下文体积。

十、上下文调试与监控命令

通过内置命令实时查看上下文状态，定位开销问题：

  1. /status：快速查看上下文窗口占用率与会话设置

  2. /context list：查看注入文件、大小、截断状态、总开销

  3. /context detail：深度分解技能、工具 Schema、系统提示词的详细开销

  4. /usage tokens：在回复后附加 Token 使用量统计

  5. /compact：手动触发上下文压缩，释放窗口空间

十一、上下文优化最佳实践

  1. 控制工作区文件大小，核心文件尽量低于 15000 字符，避免自动截断丢失信息

  2. 精简工具启用列表，禁用未使用工具，减少 Schema 开销

  3. 长对话定期执行 /compact，避免历史累积导致上下文溢出

  4. 子智能体使用 minimal 提示词模式，省略非核心模块

  5. 技能按需启用，避免全量加载导致上下文膨胀

  6. 用 /context detail 定位高开销技能与工具，针对性精简