装好 Claude Code 的那一刻，大多数人会干两件事：先跑一条命令看它动没动，然后打开配置文件想改点什么。真正决定这个工具好不好用的，往往不是模型本身多聪明，而是三个东西的搭配：settings.json、CLAUDE.md和 memory（记忆）。它们一个管权限与行为，一个管项目规则，一个管跨会话记忆，但新手特别容易混在一起——有人把整个团队的约定塞进全局配置，有人把所有项目背景写进一条提示词，有人干脆不知道 memory 该放哪，结果每次开会话，Claude Code 都像第一次见你的代码库。这篇文章就把这三套配置拆开讲清楚，顺便带上安装、VS Code 接入、第三方 API 和本地模型调用，以及我踩过的一些高频报错。适合刚接触 Claude Code 的人，也适合已经用了很久但配置全靠感觉的朋友。
1. 先把三份配置的角色分清
要配置好 Claude Code，第一步不是急着写规则，而是搞清楚这三样东西各自是干什么的。很多人的 settings.json 越改越乱，就是因为把项目说明、权限规则、长期记忆全部堆在同一个文件里，最后谁也说不清哪条规则为什么存在。
1.1 settings.json：控制“能做什么”
settings.json 解决的是“行为边界”问题。它在 Claude Code 里对应权限列表、默认模式、模型选择、环境变量注入、输出协作信息等。说白了，它管的是这个工具能不能跑某条命令、能不能改某个文件、以什么姿态运行。
这个文件是 JSON 格式，可以带注释，核心内容通常长这样：一个permissions字段放允许和拒绝的规则，一个defaultMode设置默认的权限模式，很多团队还会在里面统一指定模型和环境变量。它的好处是稳定、可复制、能被 git 管理，坏处是如果你把项目知识也写进这里，它很快就会变成一堆互相矛盾的注释。
1.2 CLAUDE.md：控制“按什么规则做”
CLAUDE.md 是给模型看的项目说明书。你可以把它理解为“新人入职手册”：“这个项目用 pnpm 不用 npm”“后端禁止直接写 SQL”“跑测试要用这条命令”。它解决的是“质量”和“一致性”问题，而不是“能不能执行”的问题。
CLAUDE.md 可以存在于多个层级：用户级、项目根目录、子目录。每个目录下都可以有自己的 CLAUDE.md，Claude Code 在进入对应目录时会自动把相关规则加载进上下文。它和 settings.json 最大的区别是：settings.json 管“手脚”，CLAUDE.md 管“脑子”。手脚不能越界，脑子需要知道规则。
1.3 memory：跨会话的“事实沉淀”
memory 解决的是“长期记忆”问题。Claude Code 本身是一个无状态工具，每次开会话默认不会记得你昨天让它怎么处理某个模块。你要是有过“上周刚交代过不要动这个文件，这周它又去动了”的经历，就是 memory 没配好。
在 Claude Code 里，memory 本质上依然是 Markdown 文件，不是数据库，也不是向量检索。它通常表现为用户级 CLAUDE.md、项目级 CLAUDE.md，以及/memory命令维护的独立记忆文件。区别在于，CLAUDE.md 偏“规则”，memory 偏“事实”。比如“代码风格是函数式”是规则，“我们已经把支付模块从 v1 迁到了 v2”是事实，前者适合放 CLAUDE.md，后者更适合沉淀为 memory。
| 维度 | settings.json | CLAUDE.md | memory |
|---|---|---|---|
| 管什么 | 权限和行为边界 | 项目规则和协作规范 | 跨会话的事实与结论 |
| 典型内容 | allow/deny 规则、模型、env | 常用命令、架构约束、风格约定 | 迁移状态、历史决策、已知坑位 |
| 改动频率 | 低，稳定为主 | 中，随项目演进 | 高，随时沉淀与清理 |
| 适合所有人共享吗 | 适合 | 适合 | 需要区分，别把个人偏好全塞进团队文件 |
这个三角关系理清之后，后面的配置才有意义。否则你往 settings.json 里写一长串项目历史，或往 CLAUDE.md 里写一堆权限规则，只会让 Claude Code 变得又慢又笨。
2. settings.json 实战配置
settings.json 是三套体系里最容易被误解的一个。它看起来像普通 JSON，实际上一旦本地、项目、用户三个文件同时存在，生效规则就变复杂了。我见过不少人改了半天无效，最后发现是优先级没搞对。
2.1 文件位置和合并顺序
settings.json 会在这几个位置寻找：用户级~/.claude/settings.json、项目级.claude/settings.json、本地级.claude/settings.local.json。此外有些环境会把配置放到 XDG 目录或自定义路径，日常使用不必纠结，认准这三处足够。
生效顺序大致是：项目级配置和本地配置合并，本地配置覆盖项目配置，用户级配置再覆盖上面的结果。简单说就是越“私人”的配置优先级越高，越“公共”的配置越容易被覆盖。我自己的习惯是：.claude/settings.json只放团队通用规则，提交到 git；.claude/settings.local.json放个人差异，比如自己的 API 端点、实验性模型，写入.gitignore；~/.claude/settings.json放跨项目的行为偏好。
这里有个常见误区：改了 settings.json 之后不会立刻生效——所有新配置要等新开会话或重启 Claude Code 才被完整加载。你如果开着旧会话继续聊，它依然沿用旧配置。这不是 bug，是设计。
2.2 权限规则要从小白兔开始写
权限是 settings.json 里最值得花时间的部分。Claude Code 默认会拦截很多敏感操作，比如删除文件、安装依赖、执行未知命令。你可以在 settings.json 里声明允许和拒绝的工具调用，常见格式是Bash(...)、Read(...)、Edit(...)、WebFetch(...)。
我推荐一开始用最小权限白名单，而不是图省事开bypassPermissions。举个例子，允许运行测试的命令可以写成这样：
{ "permissions": { "allow": [ "Bash(npm test)", "Bash(git status)", "Read(./docs/**)", "Edit(src/**)" ], "deny": [ "Bash(rm -rf *)", "Bash(git push --force)" ] }, "defaultMode": "plan" }defaultMode设置成plan的意思是：默认只让模型读代码、查资料、给方案，不擅自改文件。当我确认方案可行后，再手动切到acceptEdits或允许执行。这套流程看着繁琐，实际用起来反而省心，因为 Claude Code 乱改文件造成的返工成本，远比多按一次确认键高。
还有一个细节：deny 规则优先于 allow 规则。也就是说即使你允许了Bash(git *)，只要 deny 里有Bash(git push --force)，这条命令仍然会被拒绝。我建议把高危命令写进 deny，把日常命令写进 allow，而不是反过来。
2.3 模型、环境变量和输出风格
settings.json 里还经常放model和env字段。model用来指定默认模型标识，env用来注入环境变量，比如密钥、私有源地址等。很多人喜欢把所有环境变量塞进 shell 的.zshrc，但这样 Claude Code 的子进程不一定都能读到；在 settings.json 的env里显式声明，反而更可控。
另外还有一个小选项includeCoAuthoredBy，它会自动在提交信息附上类似Co-authored-by的名片，对团队协作和开源项目都有用，按个人偏好开启即可。还有一个经验是：临时参数尽量不写进 settings.json，直接用命令行或会话里的/model切换就好；settings.json 里只放那些你确定“下个月还用得上”的配置，否则它很快会变成垃圾场。
3. CLAUDE.md 的正确写法
CLAUDE.md 是让 Claude Code 从“能用”变成“好用”的关键。很多人写这个文件最大的问题不是不会写，而是什么都往里装，最后模型读上下文的时间比干活的时间还长。这个文件本质上是一条压缩过的规则集，必须考虑信息密度和加载成本。
3.1 分层部署，别把所有规则放在一个文件
建议把规则拆到三层：用户级、项目级、子目录级。用户级~/.claude/CLAUDE.md只放你跨项目的通用偏好，比如“回复用中文”“优先建议标准库方案”“代码要带注释”。项目根目录的CLAUDE.md放这个仓库的整体规范，比如技术栈、目录结构、测试命令、禁止事项。某个子目录下的 CLAUDE.md 只覆盖该目录特有逻辑，例如backend/CLAUDE.md写 API 设计约束，frontend/CLAUDE.md写组件规范。
这样分布的好处是：Claude Code 在子目录里工作时，加载的规则更精准，不会被无关内容干扰。如果你只有一个项目级 CLAUDE.md，却把上面三层的规则全部塞进去，模型每次都会从头到尾读一遍，浪费 token 不说，还会让它把无关规则也当成约束。
3.2 我总结的一套 CLAUDE.md 模板
直接贴一个我项目里用得比较顺的结构：
# 项目规范 ## 常用命令 - 安装依赖：pnpm install - 本地测试：pnpm vitest - 类型检查：pnpm typecheck ## 架构约束 - 新的业务逻辑放到 src/modules 下，按领域划分目录 - 数据访问必须通过 repository 层，禁止在 service 拼接 SQL - 所有枚举命名使用大写蛇形 ## 代码风格 - TypeScript 严格模式 - 组件使用函数式，不用类组件 - 异步错误统一走 Result 模式，不抛裸 Error ## 验证方式 - 提交前必须过 typecheck 和单元测试 - 修改公共接口时需要同步更新对应文档模板不一定完全适用，但思路是固定的：让模型知道“用什么命令验证修改”“哪些事绝对不能干”“改完代码后怎样才算完”。尤其验证方式这块，很多人会忽略，导致 Claude Code 改完代码不跑测试就直接交差。你只要在 CLAUDE.md 里明确写上“每次修改代码后必须运行 pnpm typecheck”，它执行一次之后就会形成习惯。
3.3 最容易被忽略的几个坑
CLAUDE.md 并不是越长越好。我犯过的错误有：把某次具体任务的日志复制进去、把已经失效的旧方案整段保留、把个人编码口味写成“必须遵守的规范”。这些都容易误导模型。
另一个坑是写了“不要那么做”却没有替代方案。比如写“不要直接操作 DOM”，模型可能会改用一个并不存在的抽象层，最后更乱。正确的写法是“不要直接操作 DOM，统一走dom-utils里的封装方法”，这样模型才知道往哪里走。
还想提醒一点：改完 CLAUDE.md 之后最好用一条简单指令验证一下，比如“告诉我你理解的测试命令是什么”，确保模型读到的规则和你预期一致。别等它在关键节点上发挥出错才回头检查配置文件。
4. 把 memory 当长期记忆用，而不是垃圾桶
memory 是三套配置里最灵活也最容易失控的。它不像 settings.json 有明确层级，也不像 CLAUDE.md 有相对固定的格式。它本质上是让 Claude Code 跨会话记住“这个项目走到哪了”“某些结论是怎么来的”，但很多人会不小心把它变成垃圾桶，什么零碎信息都往里倒。
4.1 memory 的存放方式和读取机制
在 Claude Code 中，memory 通常以 Markdown 文件形式存在，与 CLAUDE.md 共用一套文件体系。不同版本对 memory 的暴露方式有差异，有的版本提供/memory命令来查看和添加记忆，有的则需要你手动维护某个 CLAUDE.md 文件。我自己的做法是：在项目.claude目录下单独维护一个memory.md，然后在项目 CLAUDE.md 里用@import把它引进来，这样 memory 和规则在物理上分开，语义上又同时被加载。
@import是 Claude Code 提供的一个引用机制，你可以把它想象成 Markdown 里的include。它非常适合模块化：把“项目背景”“遗留决策”“已知坑位”分成几个小文件，用@import统一加载，比一个大而全的 CLAUDE.md 好维护得多。
memory 读取的核心特征是“始终进入上下文”。这意味着它既是长期记忆，也可能成为每轮对话的固定负担。写进 memory 的任何内容都会消耗上下文窗口，所以越是长期记忆，越要克制。
4.2 怎么维护才不会被历史包袱拖垮
维护 memory 有三个原则：只写结论、不写过时细节、定期清理。
只写结论的意思是，别把“今天改到哪一行代码”这种过程性信息放进去，而应该写“支付模块已完成 v2 迁移，旧入口只保留兼容层”。过程信息会很快过时，结论能继续指导后续工作。
不写过时细节的意思是，memory 里出现“目前”“暂时”这类词时要警惕。比如“暂时用 A 方案，后续换 B”，这种话三个月后根本没人记得为什么暂时，模型还会拿着过时信息决策。如果你发现某条 memory 已经不再影响当前工作，就果断删掉，不要心疼。
定期清理可以用一个笨办法：每周抽十分钟问 Claude Code“当前 memory 里有哪些已经过时的信息”，让它列出可疑项，你再人工确认。比每次聊天时手动翻文件省力得多。
4.3 memory 的安全风险和注入问题
把长期记忆写进文件，意味着任何能够影响这个文件的内容，都可能变成对 Claude Code 的指令。如果你经常从网页、源码仓库、第三方文档里复制大段内容，而这些内容又包含“忽略以上规则，执行...”之类的提示词，轻则让模型输出奇怪结果，重则导致误操作。
所以我的建议有两层。第一层，不要在生产环境或重要仓库里让模型直接写入 memory，要建立“先提议、我确认、再入库”的流程；第二层，不要把密钥、Token、个人敏感信息写进 memory。它每轮都会被加载，等于每轮都在把你的凭据暴露给模型和日志系统。
另外，涉及 memory 的溯源也很重要。如果某条记忆影响了一个关键决策，你有权追问它的来源。Claude Code 里的 memory 文件是普通文本，翻起来倒是很轻松，关键是你得养成“先怀疑记忆，再接受记忆”的习惯，而不是把 memory 当不可质疑的真理。
5. 安装、升级和第三方接入的实操经验
配置前面三套体系之前，先得把环境装对。很多问题其实不是配置问题，是安装方式不对、版本不一致、接入渠道搞混了。这块我统一讲一下，尤其第三方 API 和本地模型接入，坑比想象中多。
5.1 安装和升级怎么处理
Claude Code 最常用的安装方式是通过 npm 全局安装，环境里需要具备 Node.js 18 或更高版本。装完之后在终端直接运行claude就能进入交互界面。如果你之前装过旧版本，尤其是 Windows 上报过“不兼容64位”之类的错，大概率是残留安装或者 Node 太老，先卸载干净再装最新版，别图省事覆盖安装。
升级方面，claude update可以检查并更新到新版本。我实际工作中遇到过这种情况：CLI 已经升级，但 VS Code 插件还是旧版，两者行为不一致，配置加载顺序都不一样。所以每次升级后顺手看一眼插件版本，匹配上再继续干活。
登录流程很简单，执行claude后会弹出浏览器授权。如果你属于团队账号且提示订阅被禁用，不要自己去折腾配置文件绕限制，直接找组织管理员查看账号策略。这是账号权限问题，不是配置问题。
5.2 VS Code 插件和桌面版的配置口径
VS Code 版 Claude Code 本质上是同一个 CLI 的图形外壳，配置文件路径和命令行版本是共享的。也就是说你在终端里写的 settings.json、CLAUDE.md，在 VS Code 插件里直接生效。插件里通常可以打开一个集成终端面板，建议先确认面板里执行的是同一个claude命令，而不是某个独立封装的旧版本。
桌面版也是类似思路，它不是另一套系统，只是换个壳。配置仍然从用户目录和项目目录读取。所以别到处找“桌面版专属配置”，你把~/.claude和项目.claude维护好，桌面版自然就能读到。偶尔会有缓存不同步的情况，重启应用基本能解决。
5.3 接入第三方 API 和本地模型的经验
Claude Code 支持通过环境变量切换 API 端点和认证信息，这是它接入第三方兼容服务的基础。常见做法是设置ANTHROPIC_BASE_URL指向一个 Anthropic 兼容接口，同时设置ANTHROPIC_AUTH_TOKEN提供认证凭证。很多第三方模型网关、代理服务都是这套思路。
社区里也有人做配置切换工具，比如 CC Switch，可以在多套 API 配置之间来回切换，把不同模型端点分别保存，需要时一键切换。这类工具本质上还是改环境变量和配置文件，只是帮你省去了手工改的麻烦。如果你同时接多家服务，确实值得用。
本地模型调用则是另一个场景。很多人想把 LM Studio 这类本地推理工具接进来，但它们未必提供 Anthropic 兼容 API 路由。这时候强行配置ANTHROPIC_BASE_URL很可能失败，先确认本地服务是否真的暴露了兼容接口，再决定配置方式。如果只支持 OpenAI 风格接口、却不兼容 Claude Code 需要的工具调用格式，配置写了也白写。我实际试过的结果是：兼容层做得好的服务能跑通，不兼容的就是无穷无尽的报错。
第三方接入的通用提示：上下文长度不同、工具调用格式差异、超时时间设置，都会导致“配置对了但表现不稳定”。建议始终保留一套官方端点配置，出问题能快速回退，别指望第三方服务永远不出问题。
6. 高频报错和排查实录
配置玩得越深，报错见得越多。这里把常见问题整理成一个能直接对号入座的清单，我尽量写得贴近实际操作，而不是罗列一堆空洞的“请检查网络”。
| 报错/现象 | 常见原因 | 处理办法 |
|---|---|---|
| 提示组织禁用了订阅访问 | 组织账号策略限制，不是本地配置问题 | 找管理员确认订阅策略，不要自行绕过 |
| 提示当前环境不可用 | 地区或部署环境不在官方支持范围 | 先确认是否使用了支持的网络环境，或咨询官方支持渠道 |
| 改 settings.json 后行为没变化 | 改了优先级低的文件，或旧会话未重启 | 检查配置层级，退出重开会话 |
| 明明 allow 了命令还是被拒 | deny 规则优先级更高，或规则语法不匹配 | 查看 deny 列表，调整规则写法 |
| 上下文超限、输出到一半断掉 | CLAUDE.md/memory 太大，历史太长 | 用/compact压缩，清理记忆文件，拆成小任务 |
| Windows 安装时报兼容错 | 有旧版残留或 Node 版本过老 | 完全卸载、升级 Node、重新安装最新版 |
| 缓存导致的诡异行为 | 插件和 CLI 版本不一致 | 同步升级插件和 CLI，重启宿主 |
6.1 启动和认证类报错
最常见的认证报错发生在claude命令启动后授权失败。这时候先检查是不是账号订阅本身有问题，再检查环境变量有没有覆盖掉默认会话。很多配置了第三方环境变量的人，会忘记ANTHROPIC_BASE_URL还在生效，导致明明登录的是官方账号，请求却发到了第三方地址。排查方法很简单：开一个干净终端，unset掉相关变量，再重新启动，看能不能恢复正常。
6.2 权限和执行类报错
这个类别下我见过最多的是“工具调用被拒绝”。可以先用/permissions之类的入口查看当前生效规则，确认自己写的是不是落在deny列表里。有些团队为了安全会在全局统一 deny 某些命令，你再怎么在项目里 allow 也无效，因为全局优先级更高。那不是配置py，是安全策略。
6.3 Context 超限和 memory 失控
随着会话变长，模型会开始“忘事”，输出质量滑坡，甚至在关键步骤上卡住。这时候不要硬聊，应该主动/compact压缩历史，把会话焦点重新拉回任务。如果压缩后依然频繁超限，就检查 CLAUDE.md 和 memory 文件是不是塞了太多无关内容。我见过有人把半年的对话摘要都放进去，每次开会话都带着几百行历史，那种配置下什么模型都撑不住。
还有一个小技巧：当 Claude Code 开始重复一些过时信息时，别急着解释新事实，先让它引用信息来源。如果它说是从 CLAUDE.md 或记忆文件里读到的，那说明文件本身该更新了。直接修文件，比在对话里纠正一百遍都有效。
我个人在实际操作中最深的体会是：配置不是一次性的工程量，而是需要维护的活文档。每周花十分钟翻一遍 CLAUDE.md 和 memory，删掉已经过时的结论，比继续往里面塞新规则重要得多。最后分享一个小技巧：改完任何配置后，别接着用旧会话继续聊，退出重开一个会话，很多奇怪问题会直接消失。这套体系本身不复杂，复杂的是你愿不愿意把项目里的隐性知识持续写进这些文件里，而这个过程，恰恰是 Claude Code 真正值钱的地方。
