上下文

Context（上下文）是每次 LLM 调用时发送的全部输入内容。有效管理上下文是 Agent 性能和成本的关键。

上下文组成

┌──────────────────────────────┐
│        Context Window        │
│         上下文窗口           │
├──────────────────────────────┤
│  System Prompt  系统提示词   │  ← 固定部分
├──────────────────────────────┤
│  Conversation History        │  ← 动态部分
│  对话历史                    │
├──────────────────────────────┤
│  Tool Call Results           │  ← 工具结果
│  工具调用结果                │
├──────────────────────────────┤
│  Injected Files              │  ← 注入文件
│  注入的工作区文件            │
└──────────────────────────────┘

每次 Agent Loop 执行时，以下内容被组装为模型输入：

组成部分	来源	说明
System Prompt	动态构建	Agent 行为定义与工具声明
Conversation History	JSONL 转录	近期对话记录
Tool Call Results	工具执行	当前轮次的工具返回值
Injected Files	工作区	Bootstrap 文件与记忆

Context Window（上下文窗口）

每个模型都有固定的上下文窗口大小：

# 常见模型的上下文窗口
models:
  openai/gpt-4o:        128000   # 128K tokens
  anthropic/claude-3-5:  200000  # 200K tokens
  deepseek/deepseek-chat: 64000  # 64K tokens

Token 限制

当上下文接近窗口上限时，Agent 会自动触发 压缩（Compaction） 来释放空间。

Token 计算

OpenClaw 在每次 LLM 调用前估算 Token 使用量：

Total Tokens = System Prompt Tokens
             + History Tokens
             + Tool Result Tokens
             + Injected File Tokens

成本优化

• 使用 promptMode: minimal 减少系统提示词 Token
• 设置 bootstrapMaxChars 限制注入文件大小
• 定期使用 /compact 压缩对话历史

截断策略

当上下文超出限制时，OpenClaw 按优先级截断：

优先级（从高到低）：
1. System Prompt      → 不截断（核心行为定义）
2. 最近 N 条消息     → 保留最近对话
3. Tool Results       → 截断大型结果
4. 早期历史消息      → 最先被移除

工具调用结果在返回 LLM 前会进行预处理：

• 超长文本结果被截断
• 图片载荷转换为引用
• 二进制数据被摘要替代

上下文状态查看

使用 /status 命令查看当前上下文使用情况：

/status

输出示例：

📊 Session Status
─────────────────────────
Model:    openai/gpt-4o
Tokens:   45,230 / 128,000 (35.3%)
Messages: 24
Session:  agent::user123
Uptime:   2h 15m

手动压缩

当上下文过大时，手动触发压缩：

/compact

这会将对话历史摘要化，大幅减少 Token 使用。详见 压缩。

工作区文件注入

Bootstrap 文件在每次运行时注入上下文：

# 注入限制配置
bootstrapMaxChars: 8000        # 单文件上限
bootstrapTotalMaxChars: 32000  # 总上限

跳过注入：

skipBootstrap: true

智能注入

Agent 不会每次都注入所有文件。基于当前对话上下文，某些文件可能被跳过或截断以节省 Token。

上下文管理最佳实践

1. 控制系统提示词长度 — 精简 AGENTS.md 和 SOUL.md
2. 合理设置截断阈值 — 根据模型窗口调整 bootstrapMaxChars
3. 定期压缩 — 长对话中使用 /compact 保持上下文健康
4. 选择大窗口模型 — 复杂任务建议使用 128K+ 窗口的模型
5. 监控用量 — 通过 /status 定期检查 Token 使用率

🇨🇳 中国用户须知

• 中文内容的 Token 密度与英文不同，同样长度的中文通常消耗更多 Token
• 国产模型（如 DeepSeek）的 Tokenizer 对中文优化较好，Token 效率更高
• 建议将 bootstrapMaxChars 适当调高以适应中文内容

下一步

• 了解 压缩机制 的自动摘要策略
• 查看 会话修剪 了解历史消息清理
• 探索 系统提示词 的构建细节