我扒了 Claude Code 源码，挖出一堆文档里根本没写的隐藏配置

发表于 2026-05-29 更新于 2026-06-12 分类于编程阅读次数：本文字数： 3.1k 阅读时长 ≈ 3 分钟

基于npm包源码整理Claude Code 2.1.87版本里没写进官方文档的隐藏配置并逐个实测，包括技能头部的effort投入度与model字段、钩子的once单次触发、async异步与出错唤醒、自动记忆开关和用大白话描述环境的字段，同时提醒标着实验性的字段随时可能被删，别接进日常流程。

cover

哈喽，我是飞飞。

前天聊 Opus 4.8 的时候，我夸了那个 effort 旋钮，能告诉模型这活儿该花多大力气。后来我顺手翻了下 Claude Code 的源码，才发现这种好东西，官方文档里压根没写全。

准确说，是有人把 @anthropic-ai/claude-code 这个 npm 包的源码从头读了一遍，扒出一大堆文档没提的可配置项。我对着清单，把自己最有体感的几个挨个开来试了试。

我验过的这几个里头，有些现在就值得开，有些还得盯着点，有一个我劝你先别碰。一条条说。

先打个预防针：这些都是从源码里扒的，没进官方文档，会随版本变。我装的是 2.1.87，你那边版本对不上的话，有些可能还没有。

effort 这个旋钮，现在能钉死在每个 skill 上

前天那个 effort 还是整个会话级别的，开一次管一整段对话。这回我在 skill 的 frontmatter 里直接看到了 effort 这个字段，能填 low、medium、high、max。

意思就是，我可以给每个 skill 单独定死它该用多大力气。

我手上有个天天用的小 skill，干的就是把一段文字塞进固定模板，纯体力活。我给它写上 effort: low，它就再也不会在这种破事上多想，秒回。另一个专门帮我捋复杂重构方案的 skill，我直接拉到 effort: max，让它每次都往死里想。

以前这个力度得我每次手动调。开个简单 skill 忘了降档，它就慢吞吞陪你想半天；开个复杂的又忘了拉满，它给的方案又潦草。现在写进 frontmatter 一劳永逸，每个 skill 的脾气我提前定好，再不用临场切。说白了，就是把「这活该使几分劲」这个判断，从每次手动变成了一次性写死。

跟它挨着的还有个 model 字段，能指定这个 skill 用哪个模型跑，haiku 还是 opus 自己挑。琐碎的 skill 我就挂 haiku，省钱又快。

但这里有个坑我替你踩了。如果你的 skill 用了 context: fork，又随手给它填了个跟父会话不一样的 model，prompt 缓存会被打断。本来缓存能省一大笔钱，这一改就白付了。我第一次没注意，给一个 fork 出来的 skill 随手挂了个小模型，结果那段对话的费用肉眼可见地往上窜，查了半天才定位到是缓存被打断了。源码里这块是专门用 CacheSafeParams 框住的，安全的做法是干脆别写 model，或者写 model: inherit，跟着父会话走。

hook 的 once、async，让我那些初始化脚本清爽多了

我平时挂了一堆 hook，有些只想在会话开头跑一次，可它每次都触发，烦得很。

源码里翻到一个 once: true，加上之后这个 hook 触发一次就自动把自己摘掉了。我拿它挂了个项目初始化的检查脚本，开场跑完就消失，后面再不打扰我。

还有个 async: true 更实用。标了它的 hook 会丢到后台跑，不卡 Claude 主流程。我有个 hook 要去拉一个有点慢的远程状态，以前每次它一跑，我就得干等着。改成 async 之后，Claude 那边照常往下走，互不耽误。

更骚的是 asyncRewake: true。它让 hook 在后台异步跑，但如果脚本退出码是 2，会反过来把模型唤醒。等于给后台任务留了个「出事了喊我一声」的口子。

我拿它配了个后台跑测试的脚本，平时安安静静不打扰，一旦测试挂了、退出码变成 2，它就把 Claude 叫回来处理。这种「平时别烦我、出事再喊我」的模式，正是我一直想要的。不过我目前只在这种小脚本上验过能触发，更复杂的场景还在摸。

autoMemory 和 autoDream，Claude 开始自己记事了

settings.json 里有两个字段我盯了挺久，挺新鲜的。

autoMemoryEnabled: true 打开后，Claude 会自动把会话里值得记的东西抽出来，存到 ~/.claude/projects 对应项目的 memory 目录下。我开了一天，回去翻那个目录，它真的把我反复强调的几条项目约定记下来了。比如我一直念叨的「提交信息别写英文」「这个仓库不准动 main 分支」，它都单独存成了小文件。下次开新会话，这些我不用再交代一遍，它自己就知道。

跟它配套的是 autoDreamEnabled: true。这名字起得挺浪漫，做梦。它的活儿是每隔 24 小时，把攒下来的 5 条以上记忆合并整理一遍。我理解就是趁你不用的时候，把零散的记忆归归档、去去重。

说实话这两个我还在观察期。自动记忆是方便，但它到底记了什么、会不会把我不想留的也记下来，我得多盯几天才敢完全放手。新鲜归新鲜，先看清楚它记的内容再说。

autoMode.environment，用大白话告诉它你在什么环境

这个字段让我有点惊喜。我一直以为环境配置都得写成 glob 那种死板的模式，结果 autoMode.environment 收的是大白话。

我直接往里写「这是本地开发机，没有生产数据库权限」「NODE_ENV=development」这种人话，它就懂了。比起记一堆通配符语法，对着它说自然语言舒服太多。

我试着加了句「这台机器连不上线上环境，别想着跑部署命令」，它后面真就没再手贱去碰那些操作。这种用人话划边界的感觉，比我去翻文档查该用哪个通配符顺手多了。

旁边那套 autoMode.allow 和 soft_deny 才是走 glob 的，* 是有界匹配、** 是递归。两套搭着用，硬规则归硬规则，软描述归软描述。

agent 的 frontmatter 里我还试了个 omitClaudeMd: true。挂上它的 agent 会跳过全局 CLAUDE.md 那套指令层级。我拿它跑过一个临时小活，不想让它被项目里那一长串规矩束住，开了之后确实清爽。但你得清楚自己在跳过什么，别回头怪它不守规矩。

这个标着 EXPERIMENTAL 的，我劝你先别碰

清单里有个字段叫 criticalSystemReminder_EXPERIMENTAL，名字就透着一股危险气。

它的作用是每一轮对话都给模型重新注入一条系统提醒，听着挺强，能强行让模型记住某条铁律。我试了一下确实管用。

但它名字后面那个 EXPERIMENTAL 不是装饰。源码注释里写明了这是实验性字段，不稳定，随时可能被删掉。你今天把工作流押在它身上，明天升级一下版本它没了，整套就崩。

所以这个我只是验证它能用，没敢真接进日常流程。图新鲜可以摸一下，别拿它当地基。

这也是我想再强调的：这一整批配置都是读源码扒出来的，没进官方文档。我上面讲的每一个都是在 2.1.87 上亲手开过的，但官方既然没写，就意味着它不保证向后兼容。拿来玩、拿来提效都行，别当成板上钉钉的承诺。

我现在 settings.json 里固定留着的，是这三个

折腾一圈，真正沉淀进我日常配置的没几个。

skill 级的 effort 加 model 是我现在天天用的，按 skill 轻重把投入度和模型钉死，省心又省钱。hook 的 once 和 async 让我那堆初始化脚本清爽了不少。autoMode.environment 那句大白话环境描述，我也一直留着。

autoMemory 那对还在我的观察名单上，那个 EXPERIMENTAL 的我碰都没往里接。

这些字段官方哪天写进文档、哪天又悄悄改掉，我也说不准。所以我打算每次 Claude Code 大版本更新，就回去重新扒一遍源码，看看又多了什么、少了什么。

你在 Claude Code 里挖到过什么文档没写的隐藏配置吗？评论区甩给我，我去试试，下次扒源码顺手验一验。

参考资料

[[claude-code-hidden-config-source]]