装好 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.mdClaude 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.jsonCLAUDE.mdmemory管什么权限和行为边界项目规则和协作规范跨会话的事实与结论典型内容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 真正值钱的地方。