上下文压缩

适用 OpenCode V2 · 核验日期：2026-11-12。 来源：官方压缩说明↗。本文为官方当前文档的中文操作指南；未在本站执行安装、认证或模型请求。

压缩用摘要替代较早的会话上下文，为长任务腾出模型窗口。它有损，不是无限记忆，也不等于删除已存储的旧消息。

# 默认行为#

接近上下文上限时，OpenCode 对当前完整对话生成摘要，同时保留约 15,000 tokens 的近期对话，以保留精确细节。后续压缩从已有检查点继续更新。摘要通常使用当前会话模型，可通过 agents.compaction.model 指定，无法解析时回退。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "compaction": {
4    "auto": true,
5    "keep": { "tokens": 15000 },
6    "buffer": "20%"
7  }
8}

buffer 是预留空间，20% 表示约 80% 满时开始压缩，不是等到 20% 满。默认预留 15%，至少 16k tokens；也接受固定 token 数。百分比允许 1% 到 99%，含小数。keep.tokens 越大保留越多，但新工作可用空间越少。

# 手动请求#

以下示例需用真实会话 ID 替换 ses_example：

bash
opencode api post /api/session/ses_example/compact --data '{}'

返回只表示请求被接受，不会等待摘要完成。订阅 session.compaction.* 事件确认结果。请求在下一个安全点执行，优先于仍等待的提示；已有待处理请求会合并，关闭 auto 仍可手动压缩。

# 后台压缩是实验功能#

json
{
  "experimental": { "background_compaction": true }
}

它提前在后台写摘要，到阈值再应用；摘要若未完成仍需等待。未用上的摘要也花费 tokens，暂存摘要仅在内存、重启会丢失。模型或指令变化等情况会退回普通压缩。该实验可能随版本改变或移除。

# 提供商原生压缩#

提供商或模型 settings.compaction.type 可选择 native 或 summary。当前官方列出的原生支持为 OpenAI Responses 模型，具体可用性取决于模型和部署。原生检查点不可读且绑定原提供商和模型，换模型时改从原始对话继续。

# 无法解决的情况#

固定系统指令与工具 schema 已占满窗口时，压缩不能凭空释放空间。请求过长通常只压缩并重试一次；再次拒绝则报错。近期工具输出可能缩短，附件内容可能变成描述。重要要求应存放在明确的指令文件中，而不是只依赖很早以前的一条聊天消息。

V1 的 compaction.prune、tail_turns 不再提供原行为；V2 使用 keep.tokens 和检查点。升级契约边界见迁移指南。