How do I enable or disable auto compact in Claude Code?

Auto compact is on by default — there is no enable toggle. To control it, set the trigger window with /autocompact (for example /autocompact 500k; range 100K–1M tokens) or /autocompact auto to return to the model-tuned default. The env var DISABLE_COMPACT=1 disables all compaction, but that only means you hit hard “prompt too long” errors instead, so it is rarely what you want.

What threshold or percentage triggers Claude Code auto compact?

There is no fixed percentage. Unset, Claude Code compacts when the conversation reaches the model's context limit: 200K-window sessions compact at the 200K boundary, and native 1M-context models compact at about 967K tokens by default. /context visualizes it — the reserved “Autocompact buffer” row (33k tokens, 16.5% in our screenshot) is the headroom kept for summarization. You choose the trigger yourself with /autocompact.

Is auto compact on by default in Claude Code?

Yes. Unless you configure otherwise, Claude Code compacts automatically when the conversation reaches the model's context limit, and v2.1.288 tightened the behavior further: auto mode now compacts long conversations instead of prompting for or failing every tool call. The only off switch is the DISABLE_COMPACT environment variable.

Why is auto compact not working — why do I still hit “Prompt is too long”?

First, update: builds before v2.1.288 had a bug where long conversations hit “Prompt is too long” instead of auto-compacting when the last reply reported zero token usage. If you are current, check the other known causes: DISABLE_COMPACT set in your environment, a gateway that rejects requests over 200K tokens (set CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000), a managed-settings scope overriding your /autocompact value, or compaction thrashing on one huge file or tool output until Claude Code gives up after a few attempts.

Does Claude Code auto compact lose work or details?

Your code changes on disk are never touched — compaction reshapes conversation memory only. Per the official docs, your requests and key code snippets are preserved while detailed instructions from early in the conversation may be lost. If a summary drops something, the compacted notes link the full transcript (.jsonl) so you can read back what fell out; durable rules belong in CLAUDE.md, which is re-read every session.

What is the difference between auto compact, /compact and /clear?

Auto compact is the same summarization triggered automatically near the limit. /compact runs it on demand — the menu describes it as “Clear conversation history but keep a summary in context” — and accepts a focus instruction. /clear wipes the conversation with no summary and costs nothing, while compacting a large context is itself a large request. Working the same feature past the limit: compact. New task: clear (after /rename, so /resume can find the old session).

Why does “Compacting conversation…” take so long or hang?

Compaction reads the whole conversation, so near-full windows genuinely take a while — give it time before re-running. If it loops or fails, one huge file read or tool output may be refilling context after every summary (thrashing); Claude Code stops auto-compacting after a few attempts and errors out. Split the task, delegate the heavy read to a subagent, or /clear and resume later. And update to v2.1.288+, which fixed the zero-token-usage bug that left sessions failing instead of compacting.

上下文管理 · 已更新至 v2.1.288

Claude Code Auto Compact：/autocompact、触发阈值与排障

上下文窗口快满时 auto compact 会做什么、/autocompact 窗口怎么设（现在按模型分别保存）、什么时候该 compact 什么时候该 clear，以及「Compacting conversation…」变慢卡住时的急救办法。

看图解步骤常见问题

太长不看版

对话接近上下文上限时，auto compact 自动摘要更早的历史。从 v2.1.288 起，auto 模式遇到超长对话会压缩，而不是让每个工具调用失败。
/autocompact 500k 设置触发窗口（100K–1M tokens），而且从 v2.1.288 起按模型分别保存；/autocompact auto 恢复模型调优默认值。
/context 能看到空间都被谁占了，以及预留的 Autocompact buffer。同一个功能继续干就 compact；开新任务就 /clear。
压缩要读整段对话，长会话就是会慢。卡住先升级 Claude Code——2.1.288 修了报「Prompt is too long」而不压缩的问题。

Context Management in Claude Code

频道：Anthropic · Claude3:31

打开

Claude Code release notes — v2.1.288

更新日志：github.com/anthropics/claude-code

打开

Set the auto-compact window — official documentation

文档：code.claude.com/docs

打开

本页事实均与 Claude Code 官方文档和 v2.1.288 更新日志交叉核对过；截图来自上方视频。所述行为对应 Claude Code v2.1.288（2026 年 9 月）。

文中截图均取自 Anthropic 的「Context Management in Claude Code」视频，已注明出处，每一步都附了跳回原视频对应时间点的链接。

Auto compact 一步步图解

先搞清什么占满了上下文

1
列出上下文里都装了什么
运行 /context 并往下翻明细。MCP 工具按需加载，但工具定义、自定义 agent 和 skill 都会预先占掉 token——你还没发第一个提示词就已经扣了。把项目用不上的 MCP server 关掉，是省上下文最便宜的一招。
/context 明细里列出了 MCP 工具、自定义 agent 和 skill 各自占用的 token，开工前就能看到。看视频 0:10 处
2
看懂剩余空间和 autocompact buffer
/context 顶部显示模型的窗口大小和已用量——演示里 claude-opus-4-6 用了 21k/200k tokens（11%）。最后一行 Autocompact buffer 是 Claude Code 预留的余量，保证窗口真正满之前 auto compact 还有地方施展。
/context 里的 Autocompact buffer 行就是压缩预留空间——此处为 33k tokens（16.5%）。看视频 2:38 处
3
识别一个正在被填满的会话
长会话是被工具结果撑大的：每次读文件、每条 code review 发现、每个修复都会往窗口里塞消息。演示里的会话跑了一次代码审查，列出「缺少输入校验」「硬编码 JWT secret」等发现，再让 Claude 逐个修——这正是最容易顶到上限的那类工作。
带发现、带修复的代码审查是典型的长会话工作，会把上下文窗口一路推向极限。看视频 0:24 处
4
从回顾里看什么能留下来
对话变长后，Claude Code 自己的回顾——优先级排序、全部用户消息、待办任务——正好展示了摘要必须保住什么。auto compact 的取舍一样：你的请求和关键代码片段会保留，最先被丢掉的是旧的工具输出。
优先级排序、用户消息、待办任务——压缩后的摘要要带走的就是这类状态。看视频 0:50 处

按需手动压缩

5
在斜杠菜单里选中 /compact
输入 / 看菜单描述：/clear 是「Clear conversation history and free up context」，/compact 是「Clear conversation history but keep a summary in context」。一句话道尽区别——compact 用摘要换连续性，clear 换最大空间。/compact 还能带焦点指令，比如 /compact Focus on the API changes。
斜杠菜单说得明明白白：/compact 留摘要续命，/clear 全部腾空。看视频 0:09 处
6
认识 Compacting conversation 转圈
运行 /compact 后会出现「Compacting conversation…」，模型正在读取并摘要到目前为止的全部内容。auto compact 在接近上限时自动跑同一套流程——v2.1.288 还让 auto 模式在超长对话下改为压缩而不是逐个工具调用失败，任务不会再卡在半路。
无论手动还是自动压缩，看到的都是同一个「Compacting conversation…」。看视频 0:46 处
7
读懂压缩摘要
输出以「This session is being continued from a previous conversation that ran out of context」开头，然后把 Primary Request and Intent、Key Technical Concepts、Files and Code Sections 带进新窗口。你拿着摘要继续干活，替代原来的完整历史。
压缩摘要开头就承认会话上下文耗尽，然后逐项列出保住了什么。看视频 0:48 处
8
从完整记录里找回细节
如果摘要漏了你要的东西，压缩后的笔记写明了去哪找：「read the full transcript at」某个 .jsonl 路径，外加 Current Work 和 Optional Next Step 两节。文档的警告依然成立——对话早期的详细指令可能丢失，所以长期规则要放进 CLAUDE.md。
Current Work、Optional Next Step 和完整记录路径，是压缩后的三个找回入口。看视频 0:52 处

清空、委托、恢复

9
任务收尾时用 /clear
要开新功能？/clear 直接清空对话——文档明确说它几乎零成本，而压缩一个大上下文本身就是一次大请求。先跑 /rename 给会话起个名字，之后 /resume 还能找回来；未来会话需要知道的东西写进 CLAUDE.md。
/clear 不留摘要、从零开始——先给会话改个名，/resume 才找得回来。看视频 3:14 处
10
把大读取委托给 subagent
Subagent 在自己独立的上下文窗口里干活，只把摘要交回主会话。像演示那样派出 code-reviewer subagent，审查产出完全不占你的主窗口——文档推荐的正是这种「只要答案、不要过程」的问法。
派出 code-reviewer subagent：脏活累活发生在主上下文窗口之外。看视频 2:50 处
11
让 subagent 干活，主会话只留答案
Subagent 在那边摘要重构、更新待办，主窗口只收到结果。主线程里的工具输出变少，auto compact 触发得更晚——甚至不会触发。这是让长项目永远摸不到 buffer 的最省钱的办法。
Subagent 只回传摘要后的结论——中间输出从未进过主会话。看视频 2:53 处

Auto compact、/compact、/clear、/rewind 怎么选

四个命令都在 Claude Code 的同一个角落里——都会重置或重塑对话——但回答的是不同的问题。什么时候该用哪一个，这篇说清楚。

1auto compact（自动）：对话触及上下文上限——或你用 /autocompact 设的窗口——时触发，摘要更早的历史让会话无缝继续；从 v2.1.288 起，auto 模式在超长对话下也会压缩而不是让工具调用失败。
2/compact（手动、留摘要）：按需执行同一套摘要——菜单原话「Clear conversation history but keep a summary in context」。同一个功能超出窗口还要继续时用它；可以加焦点，比如 /compact Focus on the test output。
3/clear（从零开始）：不留摘要直接清空，几乎零成本——压缩大上下文本身就是一次大请求。计划做完、下一个任务无关时用它。先 /rename，/resume 才能把旧会话找回来。
4/rewind（撤销）：性质完全不同——双击 Esc 打开 rewind 菜单，把代码和对话恢复到更早的检查点。想反悔最近的改动用它，想在超限后继续干活别用它。
5Anthropic 官方视频里的经验法则：同一个功能超窗口但要连续性，compact；开新东西，clear；未来会话要记住的东西写进 CLAUDE.md，两种操作都冲不掉。

还有一个区别值得记住：压缩天生有损。你的请求和关键代码片段会保留，但对话早期的详细指令可能丢失——这是腾空间的代价，也是长期规则应该住进 CLAUDE.md 而不是聊天记录的原因。

Compacting conversation 慢或卡住？急救指南

压缩要读整段对话，大会话摘要耗时明显偏长——这本身不是 bug。下面是真正出问题的几种情况，以及对应的处理办法。

1报「Prompt is too long」而不是压缩——先升级 Claude Code。v2.1.288 修复了上一条回复 token 用量为零时超长对话报错、不自动压缩的 bug；旧版本恰好会卡在这里。
2压缩刚结束上下文又被瞬间填满（thrashing）。某个超大文件读取或工具输出会在每次摘要后立刻灌满窗口，Claude Code 尝试几次后停止自动压缩并报错，不会死循环。/clear、拆任务，或者把大读取交给 subagent。
3网关或代理拒绝大请求。如果接入点不接受超过 200K tokens 的请求，设 CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000，让压缩早点触发，别让会话涨到网关不认。
4/autocompact 提示已保存但没生效。说明有更高优先级的配置（比如 managed settings）压住了它，命令本身会提示这种情况。环境变量 CLAUDE_CODE_AUTO_COMPACT_WINDOW 优先级最高，连 /autocompact 都压不过它。
5真的只是慢。摘要接近满的窗口就是一次大请求，先等一分钟再重跑 /compact；如果你其实不需要摘要，/clear 立竿见影还免费。关掉不相关的 MCP server，也能让以后每次压缩都快一点。

如果同一个会话反复压缩失败，手动逃生通道是：/rename 改名、/clear 清空、之后 /resume 找回——或者从上次压缩生成的摘要继续。磁盘上什么都不会丢，压缩只重塑对话记忆。

Claude Code Auto Compact：/autocompact、触发阈值与排障

太长不看版