1. 为什么 Claude Code 的上下文管理值得单独聊Claude Code 作为 CodeAgent 跑起来之后真正决定它能不能长时间稳定干活的往往不是模型本身有多强而是上下文窗口有没有被管好。我自己的体感是一个任务跑十几轮之后读取的文件、命令输出、错误日志、中间推理会迅速把窗口填满这时候如果没有任何管理策略模型就开始丢目标、重复劳动、甚至编造不存在的文件路径。上下文管理要解决的核心问题不是「塞得更多」而是让当前最有价值的信息出现在最合适的位置。围绕这个目标Claude Code 提供了两层可落地的抓手一层是settings.json负责把静态规则、权限、环境变量、模型参数这些稳定内容固定下来另一层是 CC Switch 这类配置切换骨架负责在不同项目、不同上下文策略之间快速切换。把这两层搭好你才有一个可复制的上下文工程底座而不是每次开新项目都从零拼 Prompt。这篇会从settings.json的字段结构讲起给出可直接复制的配置片段再补上 CC Switch 的骨架写法最后用具体动作验证上下文是否真的生效。适合已经在本地跑 Claude Code、想让 Agent 从「能跑」变成「能长期跑」的开发者。2. TaoToken 前置把模型接入和 Key 管理先理顺在动settings.json之前得先确认模型请求这条链路是通的。Claude Code 本身是客户端它需要一个兼容 Anthropic 接口的服务端点来发请求。我这边习惯用 TaoToken 来做接入层原因是它同时提供模型对话、Coding Plan、API Keys 和接入文档几个入口配置的时候不用在多个平台之间来回跳。具体来说你需要先拿到一个 API Key然后在 Claude Code 的配置里把 base URL 指向 TaoToken 的 API 地址。这里有个细节官网地址带推广参数API 地址不带配置的时候只填 API 那个别把 UTM 参数混进去否则请求路径会出错。拿 Key 和看接入文档https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档含 base URL 和请求格式https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite想先验证模型通不通https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期编码或跑 Agent 任务https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite注意API Key 属于敏感凭证不要写进会提交到 Git 的settings.json里。推荐用环境变量注入配置文件里只引用变量名。这一步做完你手里应该有一个可用的 Key 和一个确认能通的 base URL。接下来才是上下文管理的正题。3. settings.json 配置骨架把稳定规则固定下来settings.json在 Claude Code 里承担的角色类似上下文工程里的「静态规则层」。身份、安全原则、工具使用约束、权限边界这些内容适合稳定地放在配置里而不是每轮对话都重新描述。这样做还有一个附带好处稳定内容放在 Prompt 前部能提高缓存命中率省下重复计费。下面是我实际在用的一个配置骨架字段做了注释你可以按项目改{ model: claude-sonnet-4-20250514, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: ${TAOTOKEN_API_KEY} }, permissions: { allow: [ Read, Glob, Grep ], deny: [ Bash(rm -rf *), Bash(curl * | sh) ] }, context: { maxTokens: 180000, compactionThreshold: 0.75, keepRecentMessages: 12, persistLargeResults: true, resultStoragePath: .agent/results }, memory: { enabled: true, indexFile: .memory/MEMORY.md, autoLoad: [user-preference, project-facts] } }几个字段值得单独说。compactionThreshold设成 0.75意思是上下文用到 75% 就开始触发压缩留出余量给后续的工具结果避免跑到 100% 才手忙脚乱。persistLargeResults打开后大文件读取和长命令输出会落盘到.agent/results上下文里只留预览和路径模型需要时再回读。memory.autoLoad控制哪些记忆文件在会话启动时自动加载索引常驻、正文按需这个两级策略后面会展开。permissions.deny里我特意加了危险命令的拦截。上下文管理不只是「省 token」也包括防止 Agent 在长任务里因为上下文污染而执行破坏性操作。这条属于静态规则放在配置里比放在 Prompt 里更可靠。4. CC Switch 骨架多项目上下文策略的切换层如果你同时维护多个项目每个项目的上下文策略往往不一样有的项目记忆文件多、有的项目 Skill 目录大、有的项目需要更激进的压缩。这时候把所有配置写死在一个settings.json里就会互相打架。CC Switch 的思路是做一个切换骨架按项目或按场景加载不同的配置组合。骨架的核心是一个映射表加一个加载函数。我用 Node 写了个最小实现// cc-switch.js const fs require(fs); const path require(path); const PROFILES { default: { settings: settings.json, memory: [.memory/MEMORY.md], skills: [.skills/catalog.md] }, long-agent: { settings: settings.agent.json, memory: [.memory/MEMORY.md, .memory/project-facts.md], skills: [.skills/catalog.md, .skills/code-review.md], compactionThreshold: 0.6 }, quick-fix: { settings: settings.quick.json, memory: [], skills: [], compactionThreshold: 0.85 } }; function switchProfile(name) { const profile PROFILES[name]; if (!profile) throw new Error(未知 profile: ${name}); const base JSON.parse(fs.readFileSync(profile.settings, utf8)); if (profile.compactionThreshold) { base.context base.context || {}; base.context.compactionThreshold profile.compactionThreshold; } base.memory base.memory || {}; base.memory.autoLoad profile.memory.map(f path.basename(f, .md)); const out path.join(process.cwd(), settings.active.json); fs.writeFileSync(out, JSON.stringify(base, null, 2)); console.log(已切换到 profile: ${name} - ${out}); } switchProfile(process.argv[2] || default);用法就是node cc-switch.js long-agent它会生成一个settings.active.jsonClaude Code 启动时读这个文件。这样切换项目时不用手改配置上下文策略跟着项目走。提示long-agent这个 profile 把压缩阈值降到 0.6是因为长任务里工具结果堆积快早点压缩比等到临界点再处理更稳。quick-fix则相反短任务不需要频繁压缩阈值调高减少开销。5. 验证上下文是否真的生效配置写完不代表生效得用具体动作验证。我一般分三步查。第一步确认配置被读取。启动 Claude Code 后让它读一个文件然后看.agent/results目录下有没有生成落盘文件ls -la .agent/results/ # 期望看到类似 read_001.txt 这样的文件如果目录是空的说明persistLargeResults没生效回去检查settings.active.json里context.persistLargeResults是不是true。第二步验证记忆加载。在.memory/MEMORY.md里写一条索引然后新开一个会话问 Agent「你知道我的代码注释偏好吗」。如果它能答出索引里指向的内容说明autoLoad生效了。这里要注意索引文件本身要简短正文放在被索引的独立文件里否则又变成把全部内容塞进上下文。第三步验证压缩触发。跑一个会读取多个大文件的任务观察上下文用量。当用量接近compactionThreshold时Agent 应该开始把旧工具结果替换成占位符类似[旧工具结果已持久化.agent/results/read_013.txt]看到这个占位符说明分层压缩在工作。如果一直没出现可能是阈值设太高或者任务本身没产生足够大的工具结果。6. 本篇常见错排查配置链路跑不通多数问题集中在几个固定位置。我按遇到频率排一下。报错ANTHROPIC_BASE_URL无效或 401先确认环境变量TAOTOKEN_API_KEY真的被导出了echo $TAOTOKEN_API_KEY能看到值。如果 Key 没问题检查 base URL 是不是误填了带 UTM 的官网地址正确值应该是https://taotoken.net/api不带任何查询参数。上下文压缩不触发检查compactionThreshold是不是设成了 1.0 或者没设。另外如果任务本身工具结果都很小达不到触发条件也正常可以手动读一个大文件来测试。记忆文件加载了但 Agent 不引用多半是索引写得太长或者索引里的描述和实际内容对不上。索引应该只写「有什么」和「去哪找」正文细节留在独立文件里。另外确认autoLoad里的名字和文件名对得上大小写敏感。CC Switch 切换后配置没变确认 Claude Code 读的是settings.active.json而不是原来的settings.json。切换脚本只生成新文件不会自动改启动参数你需要在启动命令里指定读哪个文件。大工具结果落盘后模型找不到占位符里的路径是相对路径如果 Agent 的工作目录变了回读会失败。建议在配置里把resultStoragePath设成绝对路径或者确保 Agent 始终在项目根目录启动。7. 把上下文管理链路固化下来走到这里你手上应该有一套能跑通的链路settings.json管静态规则和压缩参数CC Switch 管多项目策略切换.agent/results管大结果落盘.memory管跨会话事实。这套骨架的价值在于它把上下文工程从「每次靠感觉调 Prompt」变成了「改配置、切 profile、看落盘文件」的可重复动作。如果你还没配好模型接入建议先把 Key 和 base URL 这条链路走通再回来搭上下文骨架顺序反了容易在排查时分不清是接入问题还是配置问题。接入文档和 Key 管理入口在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 和 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite长期跑 Agent 任务的话 Coding Plan 会更合适https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。最后留一个我踩过的坑别指望摘要能永久保真。摘要是有损压缩重要约束和项目事实要提前写进记忆文件而不是等压缩之后再从摘要里捞。上下文管理的终点不是「压缩得够狠」而是「该留的留得住、该查的查得到」。