Claude Code 三套配置体系：settings.json、CLAUDE.md 与 memory 实战指南

Claude Code 用起来顺不顺手十有八九不在模型本身而在你有没有吃透它的三个配置体系settings.json、CLAUDE.md 和 memory。我见过太多人刚上手时只会对着对话框发指令遇到权限弹窗就一路点允许规则写了半天却不生效换了个会话模型就把之前的约定忘得一干二净——这些问题的根源基本都是没搞清楚这三样东西各自管什么、怎么配合、优先顺序是什么。这篇文章我就以实际配置为主线把三个配置的分工、写法、配合方式和排错经验一次讲清楚。不管你是刚装好 Claude Code 的新手还是用了两三周但总觉得“差点意思”的开发者都应该能在里面找到能立刻照着做的内容。1. 三大配置体系到底分别管什么1.1 三个文件三种受众很多人一上来就把配置全塞进一个文件里这其实是最大的误区。settings.json、CLAUDE.md 和 memory 的“受众”完全不同搞混了就会出现“明明配了却没用”的情况。settings.json 是给 Claude Code 这个工具本身看的系统配置文件。它控制的是工具的运行行为用哪个模型、环境变量怎么注入、哪些命令需要询问、哪些命令直接放行。它和安全、权限、网络连接这些“底层机制”相关模型不会主动去读它但工具在执行每一步操作前都会按它来做决定。CLAUDE.md 是给模型看的指导文档可以理解为“项目说明书”。它告诉模型这个项目的目录结构是什么、代码风格是什么、哪些操作必须先做哪些后做、哪些文件绝对不能碰。它是自然语言写的不涉及底层的执行权限只负责在行为层面约束模型。memory 是跨会话的记忆系统。我在上一个会话里确定的技术选型、踩过的坑、约定的命名规范靠聊天窗口是留不住的必须通过 memory 机制固化下来让下一次启动的时候模型还能想起来。打个比方解释一下settings.json 相当于公司行政部发的《IT系统使用规范》规定哪些软件装了之后不能乱删、访问哪些系统需要审批CLAUDE.md 相当于你工位上的岗位说明书写着“这个项目的活应该这么干”memory 则是你自己积累的笔记本记着“上次这么干出过问题这次别踩同一个坑”。1.2 为什么一定要区分“工具配置”和“模型规则”有开发者会问我不想搞那么复杂直接在对话里跟 Claude 说“以后帮我执行命令前先问我一声”不行吗答案是不行。聊天窗口里的指令属于会话内提示上下文一压缩或者会话一关这句话的权重就会急剧下降甚至完全失效。而且从机制上讲聊天指令没有真正的“强制性”。真正的强制性必须靠 permissions 这类硬机制。比如你在 settings.json 里把Bash(rm -rf *)写进 deny 列表那不管模型在当前对话里被怎么误导它都没法真正执行这条命令——这是工具层面的硬闸门。CLAUDE.md 里的规则则属于软约束模型大概率会遵守但它不是绝对保证。这两种约束不能互相替代。只配 permissions 不写 CLAUDE.md模型像个被五花大绑的实习生什么都不敢动只写 CLAUDE.md 不配 permissions模型又像个没有安全意识的实习生全靠自觉关键时刻容易出事。正确姿势是软硬结合。1.3 配置的加载层级与优先级Claude Code 的配置是分层的理解优先级非常关键。从高到低大致是这样层级位置说明命令行参数/环境变量启动时传入优先级最高覆盖下面所有配置项目级配置项目根目录.claude/settings.json跟随代码仓库走团队共享用户级配置~/.claude/settings.json当前机器上所有项目生效CLAUDE.md 也有类似的层级项目根目录的 CLAUDE.md 覆盖具体项目用户目录下的 CLAUDE.md 覆盖所有项目还有企业级托管配置覆盖整个组织。优先级背后的逻辑很直白局部需求应该覆盖全局默认。但这里我要给一句踩过坑之后的忠告绝大多数开发者根本不需要在项目级 settings.json 里做太多事情我通常的做法是全局只维护一份通用配置然后把项目特有的约束全部写进项目自己的 CLAUDE.md。这样既清晰又不会出现“换台机器配置丢了”的问题。2. settings.json 实操详解2.1 配置文件在哪怎么创建先说路径。Claude Code 的 settings.json 分两级用户级macOS/Linux 下是~/.claude/settings.jsonWindows 下是%USERPROFILE%\.claude\settings.json。这是当前电脑所有项目的全局配置。项目级在你项目根目录下的.claude/settings.json。这个文件通常应该跟着代码仓库走团队其他人拉下来就自动生效。如果你不确定文件该写什么可以直接用命令初始化claude config set --global model claude-sonnet-4-5这条命令会自动创建~/.claude/settings.json并写入配置。当然你也可以自己手写 JSON 文件编辑器校验更友好。注意一点项目级 settings.json 里别放个人密钥之类的东西因为它会进版本库。密钥应该通过环境变量注入而不是写在 JSON 里。2.2 核心字段逐个拆解一份完整的项目级 settings.json 大概长这样{ model: claude-sonnet-4-5, env: { APP_ENV: development, DATABASE_URL: postgres://localhost:5432/myapp }, permissions: { allow: [ Bash(git status), Bash(git diff), Read(./src/**) ], ask: [ Bash(git push *), Bash(pip install *), Bash(npm install *) ], deny: [ Bash(rm -rf *), Bash(git push --force), Bash(sudo *) ] }, includeCoAuthoredBy: true }逐圈解释model指定当前会话使用的模型名称比如 claude-sonnet-4-5、claude-opus-4-1 这类。切换模型时最先应该检查这个字段。env用于注入环境变量。它相当于每次启动 Claude Code 时自动帮你 export 一批变量。我经常用它来区分开发和测试环境或者在接入第三方服务时固定 API 地址。permissions是权重最高的安全机制分为三类allow直接放行、ask执行前询问我、deny直接拒绝。三者的优先级很关键deny 最高只要命中 deny 列表就直接拒掉不会再问其次是 ask命中后必须经过人工确认allow 最低只有既不在 deny 也不在 ask 里的命令正常执行。匹配规则采用前缀或通配符Claude Code 会从右向左做最长匹配——也就是说先看有没有更具体的规则命中再看模糊规则。includeCoAuthoredBy会在 Git 提交时自动附加 Co-Authored-By 信息如果你不想要每次都被标记为 AI 辅助提交直接设为 false 或删掉即可。2.3 权限配置的实战建议权限配置是我最想分享经验的部分。很多人刚接触时嫌弹窗麻烦直接在新手引导里把“Auto-accept”开了结果后面追悔莫及。我踩过一个很实际的坑有阵子为了图省事把所有 Bash 命令都放进了 allow觉得“反正模型很聪明”。结果有一天 Claude 在重构代码时把我暂存区里一批还没提交的改动给清了当时真的欲哭无泪。从那之后我养成了一个原则低风险高频的命令放 allow比如git status、git diff、cat影响面大但偶尔需要的命令放 ask比如git push、pip install、npm install没必要自动化、风险极高的命令直接 deny比如rm -rf、sudo、git push --force。推荐一套可以直接抄的配置permissions: { allow: [ Bash(git status), Bash(git diff *), Bash(git log *), Bash(ls *), Bash(cat *), Read(./**) ], ask: [ Bash(git commit *), Bash(git push *), Bash(npm install *), Bash(pip install *), Bash(python manage.py migrate) ], deny: [ Bash(rm -rf *), Bash(sudo *), Bash(git push --force) ] }这套配置的基本思路是日常读文件、看状态全自动改动外部环境或提交代码前跟你确认毁灭性操作直接封死。这样既不会每次都被烦人的弹窗打断又不会全面失控。2.4 通过配置接入第三方模型Claude Code 默认连接官方服务但配置层面预留了很灵活的接口可以通过环境变量指向兼容接口。很多人关心的“Claude Code 调用 LM Studio 本地模型”“通过 cc-switch 接入 DeepSeek / Qwen / GLM 等第三方模型”本质上就是在改这一层配置。方法一直接用环境变量指定接口地址。比如本地 LM Studio 默认跑在 11434 或 1234 端口你可以这样export ANTHROPIC_BASE_URLhttp://localhost:1234 export ANTHROPIC_API_KEYlocal-model-key然后把 settings.json 里的 model 改成本地模型实际的名字比如model: qwen2.5-coder-7b-instruct。如果你不清楚模型名可以在 LM Studio 的模型列表里直接复制。方法二用 cc-switch 这类切换工具管理多份配置。它的本质是维护多套“接口地址 密钥 模型名”的组合切换时帮你自动改写用户级或项目级的配置项省去手动改环境变量和 JSON 的麻烦。切换完之后我建议你立即检查两件事settings.json 里的 model 字段是否还指向旧模型环境变量 ANTHROPIC_BASE_URL 是否已被正确替换。我见过太多人切换之后报 model not found十有八九就是这两处没对齐。注意接入第三方模型时密钥不要写进项目级 settings.json。环境变量方式或者使用操作系统的密钥管理服务更安全另外接口地址要确保网络连通性没问题再排查其他环节。3. CLAUDE.md 规则文件实战3.1 为什么规则要写进文件而不是靠聊天CLAUDE.md 的本质是把“这个项目该怎么干活”的共识固化到仓库里。为什么它比对话里的临时叮嘱可靠得多原因有二。一是上下文会被压缩。你在这轮对话里详细嘱咐了“不要直接改数据库先写迁移脚本”但随着对话越来越长系统会自动压缩早期内容这条指令的权重会越来越低。而 CLAUDE.md 是每次会话启动时都会加载的内容权重最高一直稳定存在。二是团队协作需要一致性。CLAUDE.md 放在项目根目录跟着代码仓库走任何成员拉下来代码就自动获得了相同的行为约束。这样就不会出现“小张的 Claude Code 很听话小李的 Claude Code 乱改文件”这种混乱局面。3.2 分层机制项目级、用户级与企业级CLAUDE.md 的加载机制也是分层的。按照生效范围从宽到窄分别是企业级托管配置由管理员统一下发覆盖组织内所有项目适合公司级别的安全规范和流程要求。用户级~/.claude/CLAUDE.md当前机器上所有项目都生效适合写个人偏好的通用规则比如“所有提交信息用中文写”“所有 Python 项目优先用 uv 管理依赖”。项目级根目录 CLAUDE.md只对当前项目生效适合写项目特定的架构约束、目录约定、命令规范。三层会全部合并加载。如果你写了一堆规则却发现完全没有被遵守的迹象优先检查是不是放错了层级——比如把项目特有的规则写进了用户级结果换了个项目还在生效这个就容易造成混乱。3.3 怎么写一条“有效”的规则我调试过很多团队的 CLAUDE.md发现最大的通病就是写了太多“正确的废话”。比如“请写出高质量的代码”“注意代码可维护性”——这种规则模型看了跟没看一样因为缺乏可执行的判断标准。有效规则应该包含三段触发场景 具体动作 禁止事项。举几个实际例子## 数据库变更 - 在修改数据库表结构之前必须先执行 DESC 或 SHOW CREATE TABLE 确认当前结构 - 禁止执行不带 WHERE 条件的 DELETE 或 UPDATE - 所有数据库迁移脚本统一放在 db/migrations 目录文件名使用时间戳前缀## 依赖管理 - 本项目使用 pnpm禁止在命令中直接使用 npm install - 新增依赖前先检查 package.json 中是否已存在功能相似的包 - 锁文件 pnpm-lock.yaml 必须随依赖变更一起提交## 文件变更安全 - 修改任何文件前先 Read 该文件全文确认内容 - 删除文件前必须先向用户展示将被删除的文件清单 - 禁止修改 public/ 目录下的任何静态资源这类规则之所以有效是因为每一条都能被模型翻译成具体动作而且后续可以被检查——比如“有没有带 WHERE”模型看一眼就知道自己做得对不对。同时在写 CLAUDE.md 时尽量把最核心的规则往前放。因为文件内容如果太长模型处理时对前面的内容记忆更深刻尾部规则的命中率其实会下降。我的经验是控制在一屏之内最多不超过 80 行。3.4 CLAUDE.md 与 settings.json 的协同两者不是替代关系而是配合关系。CLAUDE.md 负责“该怎么做”settings.json 的权限负责“能不能自动做”。我特别推荐一种组合拳在 CLAUDE.md 里写“安装新依赖前必须检查 lockfile 是否有变更”在 settings.json 里把Bash(pnpm install *)设置为 ask。这样模型在准备安装依赖时会先依照 CLAUDE.md 的规则去检查 lockfile然后把结果连同执行请求交给你确认。软约束管住了行为逻辑硬闸门管住了风险边界体验会好很多。再举个例子CLAUDE.md 写了“禁止直接修改生产数据库”同时 settings.json 里把Bash(mysql *)、Bash(psql *)统统设为 ask 或 deny。如果你只写规则不配权限模型可能在你没注意的时候真的去连数据库如果只配权限不写规则模型会不理解为什么这个命令被拦还可能换个方式绕过——比如通过写 Python 脚本去连数据库。现在这种组合方式模型知道为什么不能做、“也被技术手段拦住”双保险。4. memory 机制跨会话记忆怎么管4.1 先分清“三种记性”memory 是最容易被误解的概念。很多人以为 Claude Code 能像人脑一样自动记得所有说过的话其实它的记忆体系分三个层次第一层是会话内临时记忆。就是当前窗口里你说过的所有内容模型在上下文窗口内都能看到。但会话一结束或者上下文被压缩这部分记忆基本就消失了。第二层是项目记忆文件。Claude Code 会在.claude/projects/目录下记录历史会话的摘要和关键信息下次启动时可以通过某种召回机制回顾历史。这部分相当于异步的工作日志但不保证每次都被完整加载。第三层是显式记忆就是我说的“要写下来的东西”。最直接的实现方式就是把长期不变的结论写进 CLAUDE.md或者配置你自己的 memory 管理流程。这种记忆是每次启动都会加载、优先级最高的。打个比方会话内临时记忆是办公桌上的便签项目记忆是抽屉里的工作日志显式记忆是贴在显示器边框上的“红色注意事项”。便签随手就丢日志想起来了才翻只有显示器上那张条子你每天都会看到。4.2 如何把结论固化下来不要指望系统自动把你上句话记下来。实际操作中养成“做决定就写规则”的习惯非常重要。每次对话里如果得出了稳定结论比如“本项目使用 pnpm 而不是 npm”“生产环境禁止执行 seed 脚本”“代码注释统一使用中文”你就要在项目 CLAUDE.md 里增加一个“长期记忆”区块把结论沉淀进去## 长期记忆 - 2024-12-01本项目使用 pnpm 管理依赖npm 相关命令一律不执行 - 2024-12-03评论模块的数据表结构已重构历史接口不再兼容旧字段 - 2024-12-05代码注释统一使用中文禁止中英混杂也可以借助 /memory 类的命令或插件直接把某句话写入长期记忆区。实际操作中我见过不少团队写了一个小工具脚本用/remember和/forget两条指令维护单独的记忆文件核心实现其实就是在编辑一个 markdown。关键不在于工具而在于纪律每当你发现自己在同一类问题上反复叮嘱 Claude 时就该考虑把叮嘱内容写进记忆文件了。4.3 记忆文件膨胀与清理项目记忆文件不会自动清理。用久了.claude/projects/底下会积累一大堆历史会话记录不仅占磁盘空间还会增加检索时的噪声——那些早已过时的信息偶尔也会被召回并干扰模型判断。我的清理习惯是每周一次。操作如下打开终端进入项目的.claude/projects/目录看看哪些会话文件已经是很久以前的确认无用后删掉或者归档到别处。如果你希望完全重置记忆直接删除对应项目的记忆文件夹再重新启动即可Claude Code 会自动重建。清理前我建议先整体备份目录避免误删。这里分享一个教训有次我清理时手快了把包含重要技术决策记录的会话文件也删了后来想回溯当时的方案对比时发现已经没了只能重新翻聊天记录整理浪费了不少时间。4.4 上下文溢出与压缩记忆文件多了、CLAUDE.md 写得长了项目又大就会出现“上下文溢出”或“提示词超限”的问题。尤其是同时加载多份长文档的时侯模型会变得迟钝甚至直接报错。我常用的对策有三个第一精简 CLAUDE.md。只保留“必须一进项目就知道”的信息把不常用的细节拆到单独文档里在 CLAUDE.md 里只写引用路径比如“细节见 docs/architecture.md”。模型需要时再读对应文件。第二善用/compact压缩当前会话的上下文。它会把冗长的历史对话归纳成简洁摘要释放空间。但压缩之后模型对很多细节的把握会下降重要信息尽量在压缩前写进 CLAUDE.md。第三必要时果断/clear重新开始。如果当前会话已经乱成一团、压缩之后还是感觉模型“状态不对”那就别恋战清空重来。前提是重要结论已经固化到 CLAUDE.md 或记忆文件里不然清空之后真的全忘了。5. 常见问题与排查技巧实录5.1 配置不生效的通用排错顺序“我改了 settings.json 但 Claude Code 好像没反应”是我被问最多的问题。这里有一套固定的排查流程按顺序来基本能定位问题先确认改对了文件。很多人改了用户级配置却以为项目生效了反过来也常见。用claude config list之类的命令看一下当前实际生效的值最靠谱。再确认优先级不能有覆盖。检查是否在环境变量里设置了同名配置因为环境变量的优先级高于文件配置。改完之后必须重启 Claude Code 进程。配置文件通常在启动时加载运行中修改不会实时生效。最后检查加载路径是否被缓存或损坏。如果确认文件都在但行为不对清理.claude下的缓存文件重启一般能解决。5.2 高频报错速查表整理一份我用下来最常见的报错和解决办法报错表现常见原因解决办法执行命令时报 InternetOpenUrl() failed 0x800…网络无法连通接口地址先检查网络连通性和 DNS确认接口地址可访问再检查防火墙拦截最后确认环境变量 ANTHROPIC_BASE_URL 是否填错报 Your organization has disabled Claude subscription access账号权限被组织限制确认当前账号类型联系管理员开通权限或改用个人订阅账号报 model not foundsettings.json 里的 model 字段和实际接口服务不匹配查看服务端支持的模型列表把 model 改成实际名称规则写了却像没生效改在了用户级而不是项目级或者改了没重启、尾部规则被忽略按 5.1 的顺序排查把核心规则往前放权限弹窗过多操作频繁被中断permissions 里 allow 太少、ask 太多把高频低风险命令从 ask 挪到 allowWindows 上提示与 64 位系统不兼容安装包版本过旧升级到最新版本尽量用官方安装渠道切换第三方模型后仍走旧模型环境变量或 settings.json 里残留旧配置用 cc-switch 切换后务必检查 model 字段和 ANTHROPIC_BASE_URL5.3 三个我想单独拎出来的避坑经验第一个不要把个人密钥写进项目级 settings.json 的 env 字段。之前在一家团队里见过有人把数据库密码写进了项目级配置结果代码仓库一同步密码也就跟着公司内网传了一遍后来花费大力气换了所有相关凭据。密钥只放环境变量或者在启动命令里注入坚决不进 JSON。第二个修改完 CLAUDE.md 之后记得新开一个会话再测试。CLAUDE.md 的内容通常在会话启动时加载同个会话内改了之后模型可能还在用旧版本但这不代表你的规则写错了。很多人在这一步浪费了大量时间反复排查。第三个cc-switch 这类工具切换模型之后检查两处。一处是model字段另一处是环境变量ANTHROPIC_BASE_URL。这类工具本质上是帮你去改配置但如果工具版本和你当前 Claude Code 的配置格式不完全兼容就会出现“工具显示已经切换成功实际跑的还是老接口”的问题。切换完先用/status确认实际加载的是哪套配置再开始干活。我个人在实际操作中的体会是Claude Code 的配置体系其实并不复杂大部分时间都花在“猜为什么没生效”上。与其等出了问题再查不如拿到新项目时先花 15 分钟做三件事写一份精简的项目级 settings.json把危险命令拒掉写一份包含核心约束的 CLAUDE.md把不能踩的坑标出来把已经确定的技术选型和规范写进长期记忆区。这个习惯帮我省掉了无数个“为什么会这样”的深夜排查时间。你先照这个思路试一周应该很快就能体会到配置理顺之后的差别。