什么是 上下文管理？

上下文管理技能是为使用 AI 智能体的开发者提供的专业实用工具，旨在应对模型上下文窗口的技术限制。它解决了常见的“压缩死亡螺旋”问题——即累积的摘要最终消耗了大部分可用 Token——通过强制执行严格的子智能体生成和检查点流程来解决这一问题。

通过在您的 Openclaw Skills 库中实施此技能，您将获得一个分析上下文消耗模式的框架。它能区分固定基线、对话历史和工具输出，允许智能体在工作质量下降之前主动建议配置更改或会话移交。这对于在大规模审计或复杂调试会话等工具密集型环境中保持生产力至关重要。

下载入口:https://github.com/openclaw/skills/tree/main/skills/marcus-daemon/context-management

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

上下文管理 应用场景

• 防止长时间运行的开发会话中出现上下文耗尽。
• 决定何时为多文件审计或测试套件等工具密集型任务生成子智能体。
• 在内存压缩或会话重启期间保留关键状态和决策历史。
• 识别 Token 消耗大的操作以优化 Openclaw Skills 性能。
• 自动从检查点文件恢复智能体的工作状态。

1. 该技能通过会话状态工具持续监控上下文使用情况，以建立消耗基线。
2. 它应用 60/40 原则，识别出工具输出通常是节省上下文的主要目标。
3. 根据预定义阈值（50%、70%、85%），它会触发特定的逻辑来生成子智能体或向用户发出上下文临界预警。
4. 在任何压缩或会话重置之前，它会在工作区根目录生成一个结构化的 .context-checkpoint.md 文件，以记录当前任务、状态和后续步骤。
5. 压缩后，智能体会自动读取检查点和每日日志，以最小的上下文损失恢复工作。

上下文管理 配置指南

要将此技能集成到您的工作流中，请确保您的环境支持 Openclaw Skills 网关命令。

# 检查当前上下文窗口使用情况
session_status

# 获取当前网关配置设置
gateway config.get

# 初始化检查点实用程序脚本
chmod +x scripts/context-checkpoint.sh

您还可以在工作区根目录中创建一个可选的 .context-policy.yml 文件，以覆盖默认的生成阈值和任务分类。

上下文管理 数据架构与分类体系

该技能通过特定的文件结构和元数据日志管理上下文：

name: context-management
version: 1.0.0
description: >
  Manage AI agent context window consumption, prevent compaction death spirals,
  and enforce sub-agent spawn policies. Use when: (1) context is filling up and
  work quality may degrade, (2) deciding whether to spawn a sub-agent or work in
  main session, (3) preparing for compaction or session handoff, (4) user asks
  "what's eating my context?" or "how much runway left?", (5) after compaction to
  restore working state from checkpoint files. NOT for: general memory/workspace
  management (use memory-keeper or workspace-standard).

Context Management

Prevent context exhaustion, enforce spawn discipline, and make compaction survivable.

Core Concepts

1. Fixed baseline: Typically 5-15% of context consumed before any conversation — system prompt, workspace files, skill descriptions, tool definitions. Varies by setup (more skills/files = higher baseline).
2. 60/40 rule: ~60% of consumed context is tool outputs, ~40% conversation. Tool outputs are the primary target for savings.
3. Compaction is lossy: Summaries stack cumulatively. Each cycle raises the floor. After 3+ compactions, summaries alone can consume 30%+ of context.
4. Sub-agents are disposable context: A sub-agent can burn most of its context investigating something; only the summary (~500 tokens) enters main context.

All percentages are relative to the model's context window. Check session_status for actual window size and usage.

Procedures

When Context Pressure Rises

After every tool-heavy operation (>5 tool calls), assess:

1. Run session_status to check usage
2. If below 50%: continue normally
3. If 50-70%: spawn sub-agents for remaining tool-heavy work (>3 tool calls)
4. If 70-85%: spawn sub-agents for ANY tool work (>1 tool call). Warn user.
5. If above 85%: write checkpoint (see below), suggest /compact or /new

"What's Eating My Context?" — Estimation Method

Cannot get exact per-component breakdown. Estimate:

Fixed baseline:         ~5-15% (system prompt + workspace files + skills + tools)
Per user message:       ~100-500 tokens each
Per assistant response: ~200-1000 tokens each
Per tool call result:   ~500-5000 tokens each (exec/read heavy, search light)
Compaction summaries:   ~2000-5000 tokens each (cumulative!)

Count messages and tool calls in recent history, multiply by midpoint estimates. Report as ranges, not false precision. For per-operation cost detail, read references/operation-costs.md.

Spawn Policy

If .context-policy.yml exists in workspace root, use it as guidance for spawn thresholds and task categories. Otherwise use these defaults:

Always spawn (regardless of context level):

• Test suites (>3 tests)
• Multi-file audits (>5 files)
• Build/deploy pipelines
• Research tasks (web search + analysis)
• Bulk file operations

Never spawn (keep in main session):

• Single commands
• Conversations / discussions
• Quick edits (1-3 files)
• Status checks
• Tasks requiring user input mid-execution

Context-dependent (spawn when context exceeds threshold):

• Above 50%: spawn if task involves >5 tool calls
• Above 70%: spawn if task involves >2 tool calls

When spawning, write detailed task descriptions. Sub-agents have no conversation context — they only know what the task field tells them.

Pre-Compaction Checkpoint

Before compaction or /new, write .context-checkpoint.md in the workspace root (the agent reads this post-compaction):

# Context Checkpoint — {date} {time}

## Active Task
{what you were doing}

## Key State
{bullet list of current state — what's done, what's in progress}

## Decisions Made This Session
{numbered list of decisions with rationale}

## Files Changed
{list of files modified this session}

## Next Steps
{what to do after resuming}

This file survives compaction. On session start or post-compaction, check for it and use it to restore context. Delete after consuming.

Coordination with OpenClaw memoryFlush: OpenClaw may fire its own pre-compaction flush (writing to daily log). The checkpoint is complementary — the flush saves to the daily log, the checkpoint saves structured resume state. Both should exist. If the memoryFlush fires first, compaction may already be in progress. For critical sessions, write checkpoints proactively at 75%, don't wait for 85%.

The scripts/context-checkpoint.sh script handles basic write/read/clear. For the full 5-section checkpoint, write the file directly — multiline content works better that way.

Post-Compaction Recovery

After compaction or /new:

1. Read .context-checkpoint.md if it exists
2. Read today's daily log if the workspace has one (e.g. memory/{today}.md)
3. Resume from the checkpoint's "Next Steps"
4. Delete the checkpoint file after restoring context

Proactive Warning Template

When context exceeds 65%, warn:

?? Context: {pct}% ({used}k/{total}k). Estimated runway: ~{remaining_calls}
tool calls. {recommendation}

Recommendations by level:

• 65%: "Spawning sub-agents for remaining tool-heavy work."
• 75%: "Recommend compacting soon. Writing checkpoint."
• 85%: "Context critical. Writing checkpoint now. Suggest /compact or /new."

Session Profiling & Config Advice

After significant work (or on request), profile the current session and recommend config changes.

Step 1: Classify the Session Pattern

Run session_status. Count approximate tool calls and message exchanges. Classify:

Step 2: Recommend Config

There are four settings that matter. When explaining them to the user, always describe what they do in practice, not just the setting name:

1. When to compress the conversation (reserveTokensFloor) How full the context gets before the agent summarises and compresses the history. A higher number means it compresses sooner — producing a shorter summary with more room left afterwards.

• 30000 — waits until nearly full. Risk: huge summary, little room after.
• 50000 — compresses at ~75% full. Good balance.
• 60000 — compresses early at ~70%. Maximum breathing room.

2. How quickly old tool output is cleared (pruning TTL) After you stop talking for this long, the agent clears old command outputs, file reads, and search results from memory. Shorter = more aggressive cleanup.

• 5m — only clears after 5 minutes of silence. Rarely fires during active work.
• 2m — clears after 2 minutes. Good for most workflows.
• 1m — aggressive. Clears fast, but you might need to re-read files.

3. How many recent exchanges are protected from cleanup (keepLastAssistants) When clearing old tool output, this many of your most recent back-and-forth exchanges are kept untouched.

• 3 — keeps more history visible. Good for conversations.
• 2 — moderate protection.
• 1 — only the last exchange is safe. Most aggressive cleanup.

4. Minimum size before tool output gets trimmed (minPrunableToolChars) Only tool results larger than this (in characters) are eligible for trimming. Lower = more things get cleaned up.

• 50000 (default) — only trims very large outputs (long file reads, huge command output).
• 10000 — also trims medium outputs. Catches more.
• 5000 — aggressive. Most tool results are eligible.

Recommended combinations by work style:

Additional tips:

• Sessions with browser/canvas work: Ensure those tools are protected from cleanup in the config
• Long-running sessions (>2h): Use a higher compression trigger to survive multiple rounds

Step 3: Report

Use a compact list format — tables render poorly on mobile and narrow chat windows. For each setting, show current vs recommended only if they differ. Skip settings that are already correct.

?? Current Session Profile: {pattern}
Context: {pct}% ({used}k/{total}k) · Compressions: {c}

? When to compress — {current_description}. Good for this work style.
? Clear old output after — {current_description}. No change needed.
?? Protect last exchanges — currently {current}, recommend {recommended}. {why}
? Trim output above — {current_description}. No change needed.

Estimated runway: ~{time_or_calls} before next compression.

Lead with what's already right (builds confidence), then highlight what needs changing and why. Keep it short — the user wants a verdict, not a lecture.

If changes are recommended, tell the user everything up front before asking for approval:

1. Exact file being modified (full path — get from gateway config.get)
2. Exact changes — setting name, current value, new value
3. What happens — gateway restart (~2-3 second pause, auto-reconnects)
4. Safety net — backup taken first, rollback doc written to temp directory

Example closing:

One change recommended:
  File: {config_path}
  Change: {setting_name}: {old_value} → {new_value}
  
Applying means: I'll back up the config file first, write a rollback 
doc to {temp_path}, then restart the OpenClaw gateway (~2-3 second 
pause while it reloads). Want me to go ahead?

For multiple changes, list each one. Never summarise as "4 changes" — spell them out.

Never ask "want me to apply?" without the user seeing the exact file, exact values, and exact consequences. The user decides with full information, not blind trust.

If the user agrees, follow the full procedure below.

Step 4: Learn Over Time

After giving advice, note the session pattern and outcome in the daily log (if the workspace keeps one). Over multiple sessions, patterns emerge — the user's typical work style becomes clear and default config can be permanently tuned.

Applying Config Changes — Mandatory Procedure

When recommending config changes, follow this exact sequence. No shortcuts.

1. Find the Config File

Run gateway config.get to get the config file path and current values. Do not assume the path — it varies by installation.

2. Backup First

cp  .backup-$(date +%Y%m%d-%H%M%S)

3. Write a Rollback Document

Write a rollback doc to a location the user can access (not the agent workspace — the user may not have access to it). Use a temp directory (/tmp/ on Linux/macOS, or the system temp dir). Include:

# Context Config Rollback — {date}

## What Changed
| Setting | Before | After | File |
|---------|--------|-------|------|
| {setting} | {old} | {new} | {config_path} |

## Backup Location
{config_path}.backup-{timestamp}

## How to Rollback
cp {backup_path} {config_path}

## How to Restart the Gateway
Depends on local setup — check which applies:
- CLI (most common): openclaw gateway restart
- systemd service: sudo systemctl restart 
- Manual process: kill the gateway process, then: openclaw gateway start

## How to Check Health
- Process running: check for openclaw in process list
- Gateway responding: curl http://localhost:/health
- Logs: check system logs or terminal output depending on setup

## What to Do If Gateway Won't Start
1. Restore backup (cp command above)
2. Restart gateway
3. Check logs for config parse errors

Tell the user where this file is.

4. Explain to the User BEFORE Applying

Tell them:

• Which file is being modified (full path — get it from gateway config.get)
• What values change (before → after table)
• What "restart" means — the OpenClaw gateway process restarts (not the machine, not any other service). Brief 2-3 second pause, then the session reconnects automatically.
• Where the backup is (full path)
• Where the rollback doc is (full path)
• How to check if something goes wrong

5. Apply with gateway config.patch

Use the gateway tool with action: config.patch. Include a clear note parameter — this message is delivered to the user after the gateway restarts.

6. Post-Restart Confirmation (MANDATORY)

After the gateway restarts and the session reconnects, immediately confirm to the user:

? Gateway is back. Config changes applied successfully.

What changed:
- {setting}: {old} → {new} ({plain English explanation})
- [etc.]

Rollback doc: {path}
Backup: {path}

Everything is working normally. Ready to continue.

Never stay silent after a restart. The user needs to know:

1. We're back
2. The changes landed
3. Where to find the rollback doc
4. That we're ready to continue

Reference Docs

For detailed config options and profiles: references/config-guide.md For per-operation cost estimates: references/operation-costs.md