Claude Code三大配置详解：settings.json、CLAUDE.md与memory实践

Claude Code 火了这么久，我发现聊它的人特别多，但能把三个关键配置讲清楚的少之又少。大多数人上来就问“怎么装”“怎么接 DeepSeek”，结果装完发现它不好用，其实不是模型不行，是没把 settings.json、CLAUDE.md、memory 当成一套体系来配。它们一个管运行行为，一个管项目上下文，一个管跨项目长期记忆。今天我就按自己的使用习惯，把三者拆开讲透，再给你一套可以直接照着抄的配置模板。这篇内容适合刚装好 Claude Code 但在配置上迷路的人，也适合已经用了一段时间、想彻底理清项目上下文和记忆边界的开发者。

1. 先把三大配置体系的分工说清楚

1.1 三个名字像三兄弟，性格完全不同

settings.json 最像系统控制面板，它决定 Claude Code 这个“员工”的上岗规则：允许干什么、拒绝干什么、环境里有哪些变量、模型 API 连到哪个地址。CLAUDE.md 是项目交接文档，只在当前项目里生效，用来告诉 Claude“这个项目到底是怎么回事”。memory 则是私人小抄，跨项目跟着你走，把你长期稳定的个人偏好和使用习惯记录下来。

很多人一开始都搞混。我见过有人把项目启动命令写进 memory，结果跑到别的项目里 Claude 也尝试去执行那个命令，报错之后还一脸懵。也有人把个人偏好塞进 CLAUDE.md，导致换了项目之后依然带着上一份工作的习惯。这三个东西不是同一个功能的三种形态，它们的生命周期和作用范围完全不同，必须分开用。

1.2 什么时候用哪个，一次讲明白

直接用场景来区分最省心。如果你想改 Claude Code 的模型、权限、环境变量，能选 settings.json。如果你希望 Claude 一进目录就自动知道项目结构、启动命令、代码规范，能选 CLAUDE.md。如果你希望它会记住你个人的长期偏好、禁用项、常用工作流，无论到哪个项目都生效，那就是 memory 的活。

下面这张表是我自己整理的，日常够用：

理解了这张表，你后面所有配置都不会跑偏。接下来先从最硬核的 settings.json 开始。

2. settings.json：给 Claude Code 定规矩

2.1 配置文件的位置和基本结构

settings.json 分为全局配置和项目配置。全局配置一般在用户目录下：

• macOS / Linux：~/.claude/settings.json
• Windows：%USERPROFILE%\.claude\settings.json

项目配置则放在项目根目录的.claude/settings.json。两边会合并，项目级优先级更高。之所以保留两层，是为了让你把“个人风格”和“项目约束”分开。比如你全局习惯用某个模型，但某个旧项目必须固定用另一个模型，那就只在那个项目里覆盖一次。

一个最小可用示例长这样：

{ "model": "claude-sonnet-4", "permissions": { "allow": [ "Read", "Bash(git status)" ], "deny": [] }, "env": { "ANTHROPIC_BASE_URL": "https://api.anthropic.com", "ANTHROPIC_API_KEY": "${API_KEY}" } }

这里的model指定模型 ID，具体值要以你账号实际开通的模型为准。permissions控制权限，env用来注入环境变量。要注意的是，JSON 文件里不能写注释，搜到网上那些带//注释的配置，复制下来多半会报错。

2.2 权限控制：宁可抠门，不要放纵

settings.json 里最值得花时间的就是 permissions。默认情况下，Claude Code 遇到需要调用工具或执行命令时会弹确认，但那样太打断节奏。合理做法是提前把安全、高频的命令加入允许列表，把危险命令直接拉黑。

{ "permissions": { "allow": [ "Read", "Glob", "Bash(npm run build)", "Bash(git status)", "Bash(git diff)" ], "deny": [ "Bash(rm -rf *)", "Bash(mkfs.*)" ], "ask": [ "Edit", "WebFetch" ] } }

三档逻辑很简单：allow 直接放行，deny 直接拒绝，ask 每次询问。我的习惯是 deny 里永远放着rm -rf *这类不可逆操作，免得它在改代码时头脑发热。允许列表方面，一开始只放Read和Glob，跑熟了哪个命令，再把对应的Bash(...)加进去。别贪多，多一点确认就多一点安全。

2.3 同一个文件，怎么同时管住模型和端点

如果你不想用 Anthropic 官方 API，而是想把 Claude Code 接到 DeepSeek 或其他兼容模型上，也可以改 settings.json。原理很简单：Claude Code 支持定义ANTHROPIC_BASE_URL和认证字段，兼容协议的服务商可以直接复用。下面的配置就是一个常见接法：

{ "model": "deepseek-chat", "env": { "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic", "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥" } }

不同服务商要求的字段略有差异，有的用ANTHROPIC_API_KEY，有的用ANTHROPIC_AUTH_TOKEN，以对方文档为准。这里有个经验：不要把密钥直接写死在 JSON 里，尤其是项目配置如果提交到 Git 仓库，等于把密钥共享了。正确的做法是让配置去读环境变量，比如"ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"，然后在你的 shell 配置里 export，或者用一个密钥管理器注入。

3. CLAUDE.md：把项目背景写进上下文的正确姿势

3.1 它解决的最大问题，是你不用反复解释项目

CLAUDE.md 这个名字里的大写没有道理，就是官方的命名习惯。它在项目里起的作用类似“给 Claude 的入职说明”。当你在这个目录下启动 Claude Code，它会自动读取 CLAUDE.md 内容，塞进当前的对话上下文。

假设你在维护一个用户登录服务，如果没有 CLAUDE.md，每次新开会话你都得说“这是个 Go 写的微服务，依赖 Redis，启动命令是go run ./cmd/server，测试用make test”。有它之后，这些信息自动在上下文里，聊需求、改代码都顺畅得多。token 也省了，因为不用反复解释背景。这不光省时间，更重要的是减少表达的偏差——AI 的理解完全来自你写的那份说明。

3.2 自动加载规则与多级设计

CLAUDE.md 的加载规则比很多人以为的灵活：它不是只在项目根目录找，而是从你当前所在目录开始向上逐级查找。换句话说，你可以在项目根目录写一份宏观说明，再在src/api这样的子目录里写一份模块专属说明。

my-project/ ├── CLAUDE.md ├── src/ │ ├── api/ │ │ ├── CLAUDE.md │ │ └── handlers/ │ └── core/ │ └── CLAUDE.md

当你在src/api/handlers里操作时，根目录的 CLAUDE.md 和src/api/CLAUDE.md都有可能被加载，具体合并规则不同版本略有差异。我自己的做法是：根目录只写全局架构和通用命令，子目录里写模块的边界、依赖、易错点。这样上下文不会一次性塞太多无关内容，Claude 也更聚焦。

3.3 写 CLAUDE.md 的黄金内容清单

CLAUDE.md 不是 README 的 AI 版，两者侧重点完全不同。README 是给人类看的项目介绍，CLAUDE.md 是给模型看的协作规范。我常用的模板结构是这个样子的：

# 项目一句话定位 这是一个用户注册与登录服务，基于 Go + PostgreSQL 实现。 # 常用命令 - 启动：go run ./cmd/server - 测试：make test - 数据库迁移：make migrate # 代码约定 - 所有接口返回 JSON，错误格式统一为 {"error": "message"} - 服务层不允许直接操作数据库，必须走 repository 接口 - 日志统一使用 slog，不要使用第三方 logger # 已知注意事项 - Redis 版本必须在 6.2 以上，否则缓存连接会超时 - 生产环境环境变量必须从 secrets manager 读取，禁止写死

哪些东西不该写进 CLAUDE.md？我认为有三类：第一是密钥和敏感信息，别把密码、token 放进去；第二是很快过期的东西，比如“当前正在开发登录模块”这种状态，改两行代码就过时了；第三是大段日志和报错堆栈，对上下文是负担，不如放问题定位文档。把内容控制在一页以内，Claude 才能完整理解。

3.4 让 CLAUDE.md 长期可维护

CLAUDE.md 既然是项目文档，就要跟着项目走，而不是建完之后再也不管。我自己是把 CLAUDE.md 纳入版本控制的，每次项目架构改动、命令变动，都会同步更新它。代码评审的时候也把这份文件带上，因为它的质量直接影响 AI 助手在这个项目里的表现。

另一个技巧是：项目里能自动生成的内容不用手写。比如有些工具支持基于代码扫描生成文档草稿，先让 Claude 自己读一遍项目结构生成初稿，再人工修正，比自己从头写快得多。你只需要确保生成的文档是真实准确的，别让它把那些“听起来挺对、实际跑不通”的内容写进去。

4. memory：跨项目的长期记忆怎么用

4.1 它不是又一个 CLAUDE.md

memory 是我见过被误解最深的一个概念。很多人以为它就是把 CLAUDE.md 搬到用户目录，或者干脆复制到所有项目里。它真正的定位是用户级长期记忆，不属于任何项目，跨项目共享。比如你个人习惯用 pnpm，希望所有项目的依赖安装命令都优先用 pnpm；或者你要求代码注释必须写中文；再或者你不希望 Claude 在非授权情况下直接改动 package.json。这些信息放进 memory，任何项目里都会带上。

和 CLAUDE.md 相比，memory 的内容更偏“人”而不是“项目”。CLAUDE.md 说的是“这个项目有什么特点”，memory 说的是“我这个用户有什么偏好”。如果把项目信息和用户偏好混在一起，会导致换项目时记忆错乱，所以一定要分开。

4.2 memory 的写入、读取与删除

不同版本和插件形态下，memory 的操作入口会有些差异。但基本逻辑是一致的：你可以在对话里直接用明确指令让 Claude 记住某个偏好，也可以打开交互面板中的记忆管理入口来查看、编辑、删除条目。

写入的典型方式是：

请记住：我所有项目的依赖管理默认使用 pnpm，只有在项目 CLAUDE.md 中说明使用 npm 的才用 npm。

读取相对简单，直接问“你记住我之前说过的规则吗”就能看到效果。如果发现某条记忆已经过时，建议在面板里删除，而不是留着让它继续影响后续对话。一个是定期清理。我每个月会检查一遍 memory，把那些已经不再适用的旧规则清掉。因为记忆越多，上下文负担越大，真正高价值的记忆应该像保密卡一样短而准确。

4.3 三类信息最适合放进 memory

第一类是高频个人偏好。比如“所有代码中的类型定义必须显式写出”“日志输出必须包含调用方文件名”。第二类是跨项目禁用项。比如“禁止自动安装依赖”“提交信息必须遵循 conventional commits 规范”。第三类是稳定的工作流约定。比如“每次修改前先解释方案，再动手改代码”。

不适合放进 memory 的也有三类：临时任务状态、某个项目的细节、任何形式的密钥。临时状态今天写了明天就过期，纯属污染；项目细节应该放 CLAUDE.md；密钥不论放哪里都不安全，更别说长期记忆。记住，memory 是用来记“你这个人怎么工作”的，不是用来记“某项工作做到哪一步”的。

4.4 memory 与 CLAUDE.md 联合使用示例

我给你一个完整场景。假设你在维护 A 和 B 两个项目，A 用 npm，B 用 pnpm。CLAUDE.md 里分别写了 A 项目用 npm install，B 项目用 pnpm install。memory 里则写上“所有项目优先使用 pnpm，如果项目文档明确用 npm 则以项目为准”。这样两个项目都能正确安装依赖，也不会产生冲突。

再看一个例子：你在全局偏好里要求“所有接口文档必须用 OpenAPI 3.0 格式”，这是 memory。而某个项目里因为历史原因只能用 2.0 格式，真的会在 CLAUDE.md 里特殊说明。这就是两者协作的精髓：通用规则走 memory，项目特例走 CLAUDE.md。用好了，整个配置体系才算真正闭环。

5. 从零到一：配齐一套能落地的 Claude Code 环境

5.1 安装与初始化

先解决能跑起来的问题。Claude Code 最常见的安装方式是 npm 全局安装，前提是电脑里有 Node.js 18 或更高版本。终端里执行：

npm install -g @anthropic-ai/claude-code

装完直接输入claude启动。首次启动需要登录，按提示完成认证后，它会自动生成~/.claude目录，里面大概率已经有一份默认的 settings.json。如果你在安装后找不到这个文件，可以手动创建，不影响的。顺便说一句，很多新手卡在“没反应”上，往往是 Node 版本太低，先node -v确认一下，再考虑其他问题。

5.2 VSCode 集成与桌面端

如果你主要用 VSCode，建议装官方扩展。扩展安装后，侧边栏会出现 Claude Code 面板，登录方式和命令行一致。它的好处是可以在编辑器里直接选中代码段丢给 Claude，不用来回切换终端。桌面版则适合那些不喜欢命令行窗口、又不想装 VSCode 的用户。

这三者共用同一份配置文件。也就是说，你别在桌面版改 settings.json，在 VSCode 里不生效，它们读的是同一个~/.claude目录。我遇到过一次问题，VSCode 扩展里改了 model，但桌面版还是旧配置，最后发现是项目级.claude/settings.json覆盖了全局配置。排了半天，教训就是：改配置前先确认有没有被项目级覆盖。

5.3 把 DeepSeek 或其他兼容模型接进来

前面第 2 章已经提到了基础写法，这里把完整步骤走一遍。假设你要把 Claude Code 接到 DeepSeek 上，你会经历以下流程：

1. 在 DeepSeek 开放平台申请 API Key。
2. 确认它提供的 Anthropic 兼容端点地址，通常形如https://api.deepseek.com/anthropic。
3. 修改全局 settings.json，设置 base_url、认证字段和模型名。
4. 重启 Claude Code，执行一个简单任务验证连通。

{ "model": "deepseek-chat", "env": { "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic", "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥" } }

接其他兼容模型也是一样的套路。最容易踩的坑是模型名写错。服务商后台显示的模型 ID 和 API 接受的模型名经常不是同一个，查好文档再填。另一个坑是 base_url 结尾是否带斜杠，有的接口要求必须去掉/，有的必须保留，按照服务商示例为准。

5.4 Windows 与 Mac 的实操差异

Windows 下安装往往比 Mac 多一点波折，主要是终端环境差异。很多命令在 PowerShell 里能跑，但脚本里涉及到 bash 语法就可能出问题。我的建议是优先在 Git Bash 或 WSL 里运行 Claude Code，交互体验和命令兼容性都会好很多。Windows 的配置文件路径在%USERPROFILE%\.claude，注意环境变量里取 Vale 别拼错。

Mac 下用 Terminal 直接跑就很顺。不过要注意 zsh 的环境变量加载顺序：如果你把ANTHROPIC_API_KEY写在了~/.zshrc里，但 Claude Code 是从某个图形界面启动的，可能加载不到。简单办法是在配置里用环境变量占位，然后通过系统级的 launchctl 或 launchd 设置 key，具体看你的使用方式。

5.5 在线升级与版本检查

Claude Code 更新很频繁，功能变化也大。用 npm 安装的话，可以定期执行：

npm install -g @anthropic-ai/claude-code@latest

或者直接跑claude update（如果你的版本支持）。升级前别慌，配置文件一般不会丢。但我会养成一个习惯：升级后先看一眼claude --version，然后跑一个最简单的任务验证整体链路。因为曾经遇到过升级后某个权限字段不兼容、导致原来能跑的命令被拦截。配置备份一下总没坏处，把~/.claude/settings.json多存一份到私有仓库，改坏了好恢复。

6. 实际操作中的坑和排查方法

6.1 settings.json 改了没生效

这是我在社区里看到最多的问题。先检查文件路径，全局配置在用户目录，项目配置在项目根目录的.claude下。再检查 JSON 合法性，不能有注释，不能多逗号，推荐用 JSON 校验工具过一遍。然后确认是不是被项目级配置覆盖了——你全局写了一个 model，项目里又写了一个 model，最终生效的是项目的。

还有一种情况是环境变量没生效。如果你用的是${VAR}占位，要确保 shell 里真的 export 过这个变量，并且 Claude Code 是从同一个 shell 启动的。改完配置后必须重启会话，不是新开对话框就行，要完全退出再进入。我自己的排查顺序是：先看文件在不在，再校验 JSON，再看有没有覆盖，最后重启，整套流程下来九成问题都能解决。

6.2 CLAUDE.md 没被自动加载

明明写了文件，但感觉 Claude 完全不知道，这种情况也常见。首先看文件名大小写，CLAUDE.md不是claude.md，大小写不对就不会被识别。其次看当前目录层级，如果工作目录在/home/user/project/src/api，而 CLAUDE.md 放在/home/user/other-project/CLAUDE.md，自然加载不到。只有从当前目录向上递推能找到才行。

另外，如果 CLAUDE.md 太大，上下文过长时它可能被截断，导致后半部分信息没能进到当前对话。这时不是没加载，是加载了一部分。解决办法是把文件精简到必要的核心内容，把详细命令和背景拆到子目录的 CLAUDE.md 里。符号链接目录也可能有问题，我试过把项目放到一个 symlink 路径下，Claude 往上查找时识别不了外层真实路径，最终放弃 symlink 直接走真实路径才稳定。

6.3 memory 和 CLAUDE.md 相关内容混用

很多人问我“把 X 写进 memory 了为什么不管用”。最常见的原因是：那条信息根本不是用户级偏好，而是项目特定内容。比如“数据库连接方式是 localhost:5432”，写在 memory 里，到了另一个数据库端口完全不同的项目里就误导了判断，甚至 Claude 会尝试连一个不存在的连接。项目细节就该进 CLAUDE.md，memory 只留抽象规则。

还有一点：如果你通过对话让 Claude “记住”某件事，但没有明确持久化动作，下次会话照样可能忘。别默认它什么都能记住，重要规则建议用最直白的话说清楚：“请记住这条规则，将来自动遵守。”而且在 session 里观察到它遵守之后，再转成持久记忆。如果发现 memory 里有一批过期内容，果断清理，旧规则比没有规则更危险。

6.4 模型连接与权限报错

接第三方模型时，最常见的报错绕不开几个点。第一个是base_url不对，可能少了路径，可能多了/。第二个是认证字段名搞错，有的要求ANTHROPIC_API_KEY，有的要求ANTHROPIC_AUTH_TOKEN。第三个是模型名填错，服务商的模型列表里没有这个名字，接口直接拒绝。这三个问题都能在日志里看到明确提示，先把日志拉出来看，别乱改配置。

权限类报错也很典型。settings.json 里 deny 列表写死了某个命令，结果真的需要执行时被拦，就会很困惑。遇到这种问题，先查看当前会话的权限日志，确认到底是谁拦的。如果确实需要放行，把白名单更新之后重启会话。多个 claude 实例同时跑时，可能因为读的是同一个配置文件而相互影响，那时建议按项目拆.claude/settings.json来隔离。

6.5 一套完整的排查顺序

我把日常排障顺序总结成五步：第一看版本，确认不是旧版本 bug；第二看配置文件路径和合法性；第三看是否有项目级覆盖；第四看日志，重点是连接和权限相关的输出；第五看官方文档，看当前版本字段是否有变化。按这个顺序走，基本能覆盖掉 95% 的问题。

还有一个很土但好用的技巧：实在搞不定时，把~/.claude目录里的 settings.json 暂时改名掉，让 Claude Code 回到默认配置跑一遍。如果默认配置没问题，那问题必然出在你的配置里，二分法排查会快很多。别一上来就怀疑模型问题，更多时候是配置细节在搞鬼。

我个人的体会是，三大配置体系最理想的用法就是各管一摊，互不越界。settings.json 管运行规则，CLAUDE.md 管项目事实，memory 管用户偏好。三条线清晰之后，Claude Code 的稳定性、可维护性都会明显提升。最后再分享一个小习惯：每次项目结构大调整，我都会顺手更新 CLAUDE.md，同时在对话里提醒 Claude 忽略旧的目录约定。这样三个配置能长期保持一致，后面用起来会越来越顺手。