做终端里的AI编程搭档这两年Claude Code一直是我主力机上的常驻工具。它的上手门槛其实不高——装好、登录、进项目目录敲一行命令就能跑起来但真正让它从“能聊天的终端玩具”变成“知道你要什么的老同事”靠的是三样东西settings.json、CLAUDE.md以及背后那套memory机制。我刚用的时候也吃过不少亏权限弹窗一个接一个、跨会话记忆约等于没有、换模型之后各种奇怪报错。后来把整套配置体系捋顺了效率和稳定性完全两个样。这篇文章适合正在用或准备用 Claude Code 的人不管是刚装好的新手还是被权限和记忆问题困扰的老手都能在里面找到可以直接抄走的配置方案。我会把三个配置分别是什么、为什么这么设计、具体怎么填、踩过哪些坑一次讲清楚。放心不是官方文档的复读是我自己机器上跑过、验证过的落地经验。1. 三大配置体系的分工逻辑先说结论settings.json、CLAUDE.md、memory这三者不是三份重复的配置而是三层完全不同的东西。很多人配置混乱就是因为没想明白它们各自管什么。1.1 settings.json / CLAUDE.md / memory 分别解决什么问题settings.json管的是“机器和行为偏好”。比如允许 Claude 执行哪些命令、默认使用哪个模型、环境变量怎么注入、工具调用后要不要自动跑 lint这些都属于这层。它更像汽车的仪表盘和按钮——不负责记录你的驾驶习惯只负责定义当前这台车能跑多快、按什么规则跑。CLAUDE.md管的是“项目常识和协作规范”。Claude 每进入一个项目都会主动读取这个文件。你可以在这里写清楚项目技术栈、常用命令、代码风格、绝对不要碰的文件、工作流程等等。它本质上是一份给 Claude 看的员工手册而且是人类可读、可 review、可提交到 git 的。memory管的是“跨会话记住了什么”。Claude Code 在对话过程中会记住你的偏好、关键结论、你纠正过它的事情并在后续会话里自动应用。这层解决的是“上次明明跟你说过用 pnpm这次又问我 npm 行不行”的问题。打个比方settings.json是操作面板CLAUDE.md是贴在工位上的项目规则卡memory是这个同事自己的脑子。三者各司其职缺一个都会出现“配置了但不好用”的尴尬局面。1.2 为什么要拆成三层而不是一个大文件我最早的想法也是“搞一个全能配置文件不就完了”实际用下来才明白拆开的原因。权限和模型这类配置需要按机器隔离。公司电脑和个人电脑的目录结构不一样全局配置如果在团队里共享很容易出现“我这边能跑你那边报错”。settings.json支持全局、项目、本地局部覆盖就是为了让不同环境有独立的行为边界。CLAUDE.md 需要被项目团队共同维护。如果它混在个人偏好里提交到 git 时会反复冲突不提交又没法团队同步。拆出来独立成文件团队成员各自 clone 代码库就能获得同一套项目规范这是协作层面的需求。memory 是运行时动态增长的。它不应该成为一份需要人工维护的静态文档而应该像人的记忆一样在使用中自然积累。如果把它写进 CLAUDE.md那 Claude 每次读取的 token 会越来越长性能下降不说维护成本也高到离谱。所以这套分层的本质是让“静态配置、团队文档、动态记忆”各归其位。你不需要在配置文件里写满“我是谁、我在哪、我要干什么”只需要把每层该放的东西放对位置。2. settings.json全局行为与权限控制settings.json是三个配置里最像传统配置文件的一个但它比大多数人想象得灵活。这里只讲真正高频使用的部分冷门的字段我提一嘴但不过度展开。2.1 配置文件的存放位置与合并顺序settings.json不是只有一个它分布在多个层级Claude Code 会按优先级自动合并。通常你会用到这几个位置全局配置~/.claude/settings.json对所有项目生效项目配置项目根目录下.claude/settings.json只对当前项目生效本地覆盖项目根目录下.claude/settings.local.json用于不提交到 git 的机器特定配置合并优先级从高到低大致是本地覆盖 项目配置 全局配置。也就是说你可以在全局配置里设一个宽松的默认权限然后在某个特定项目里收紧这个项目的本地覆盖又能再加例外。我自己的使用习惯是全局配置只放基础项比如默认模型、是否在 commit 里加 co-author 信息项目配置放这个项目专属的权限规则和 hooks本地配置放绝对不想提交的东西比如本地调试用的密钥路径、临时开放的权限目录。提示.claude/settings.local.json不会提交到 git适合放个人开发机的局部偏好。别把密钥明文写进去它只是不提交并不会加密。2.2 核心字段与权限模型permissions字段是我最看重的部分。Claude Code 在执行命令、读写文件之前会先过一遍权限系统你在这里定义哪些操作可以直接放行、哪些必须拦住。一个比较完整的示例{ permissions: { allow: [ Read(./src/**), Edit(./src/**), Bash(npm run *), Bash(git *) ], deny: [ Edit(.env), Bash(rm -rf *), Bash(.* secret.*) ], defaultMode: acceptEdits }, model: sonnet, includeCoAuthoredBy: true, hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: npm run lint -- --fix } ] } ] } }allow和deny支持通配符匹配规则和 shell 的通配习惯比较接近。注意deny的优先级高于allow哪怕你在 allow 里放了Read(./src/**)只要 deny 里写了Edit(.env)涉及.env的写操作依然会被拦下来。权限匹配的粒度很细路径规则按项目相对路径写bash 规则允许用正则。你可以放行所有npm run开头的命令同时拦截包含rm -rf、curl管道到sh这类危险组合。这套设计让“给 Claude 足够自由度”和“别让它搞炸环境”这两个目标能同时满足。hooks字段是进阶玩法它在工具调用后自动触发脚本。典型场景是写完代码自动跑格式化、在生成大文件后自动压缩、或者把执行结果通过 webhook 发给飞书这类消息工具。我开始觉得 hooks 很鸡肋直到配了一次“每次编辑完自动跑 eslint --fix”从此再也回不去了。2.3 模型切换与第三方 API 接入settings.json里有个model字段默认可以指定 opus、sonnet、haiku 等 Anthropic 官方模型。但很多人想要的是接 DeepSeek、Qwen、GLM 这类第三方模型或者在本地用 LM Studio 跑开源模型。这里有一个认知需要先纠正Claude Code 默认只跟 Anthropic 的 API 通信你光改model字段是没法接其他厂商的。要接入第三方模型需要借助“API 端点切换工具”或者“协议转换网关”社区里最常用的是cc switch这类工具本质上是让你在 settings.json 层面替换掉 API base URL 和密钥。cc switch 的配置方式一般是在终端运行npx ccswitch然后在交互界面里添加 provider填入模型名、API 地址、密钥。比如接 DeepSeek就是配置一个指向 DeepSeek 官方 API 的 provider模型选deepseek-chat或deepseek-coder接 Qwen、GLM 同理都是指向各自的 OpenAI 兼容接口。接本地 LM Studio 模型也是同一个思路。先在 LM Studio 里加载模型并开启本地服务然后把 cc switch 的 target 指向http://localhost:1234/v1模型名填你在 LM Studio 加载的那个。实测下来本地模型在简单代码补全、解释代码方面够用但涉及复杂工具调用、多文件修改时稳定性确实不如官方模型。如果核心诉求是写生产级代码建议第三方模型用于实验和日常小任务主力还是保留官方模型。注意用 cc switch 接第三方 API 时配置的是你自己的 API 密钥和合法服务地址。它解决的是“接入不同模型供应商”的问题不代表可以用不明来源的服务冒充官方接口后者风险极高。3. CLAUDE.md项目级长期记忆与人设规范如果说settings.json是配置机器的行为那CLAUDE.md就是在给 Claude “洗脑”——把项目的隐藏知识、约定、规范一次性灌进去。它是唯一一个既是配置文件、又像文档、还能写给人看的东西。3.1 自动读取规则与初始化生成Claude Code 启动时会按目录层级自动读取CLAUDE.md路径规则并不复杂全局记忆~/.claude/CLAUDE.md对所有项目生效适合放你个人的通用偏好比如“我默认用 pnpm”“提交信息用 conventional commits”项目记忆项目根目录CLAUDE.md对当前整个项目生效子目录记忆嵌套子目录里的CLAUDE.md只在该目录及以下生效这意味着你可以针对不同的模块写不同的规则。比如前端目录的CLAUDE.md写“所有新组件用 Vue3 setup 语法”后端目录的写“接口改动必须先让我确认”互不干扰。首次进入新项目我建议用claude --init让它自动生成第一版CLAUDE.md。它会扫描项目结构、读关键文件、分析技术栈然后列出一份草稿。这份草稿往往比你自己凭感觉写更全面但别直接采用——它理解不了你们团队“为什么定这个规则”的上下文需要你手动修正。3.2 写一份真正好用的 CLAUDE.md很多人的 CLAUDE.md 写成了项目说明书几百行读下来 Claude 该犯的错一个不少。问题在于内容太散、没有可执行力。我的模板长这样# ai-shop 前端项目 ## 任务定位 维护 ai-shop 的营销页与会员模块新增功能优先复用 src/components/ 下已有组件。 ## 常用命令 - 启动: npm run dev - 测试: npm run test:unit - 提交: git cz ## 代码风格 - TypeScript Vue3 setup 语法 - 样式优先 Tailwind不写 scoped css - 异步请求必须走 src/api/ 下封装的方法 ## 执行约束 - 只改需求相关范围不要顺手重构 - 不要修改 src/config/env.* 文件 - 数据库变更必须先让我确认 SQL关键点是“可执行”。写“代码风格要好”没用写“样式用 Tailwind不写 scoped css”才有用写“注意安全”没用写“不要修改 .env 文件”才有用。Claude 是执行者不是语义理解大师指令越具体行为越精准。还有个容易忽略的细节CLAUDE.md 不要写太长。我见过有人把整个项目的 API 文档全塞进去结果每次读取消耗大量 token而且重点被淹没。原则是只写那些“不说就会犯错”的东西一般控制在 30 到 80 行为佳。全局 CLAUDE.md 更短三五条个人偏好足够。3.3 团队协作与版本管理CLAUDE.md 建议提交到 git并且和代码一起 review。团队里如果有人改动了开发流程顺手更新 CLAUDE.md下一个 clone 仓库的人就自动获得了新规范。这个习惯比任何内部 wiki 都有效因为它就贴在工具运行的现场。如果你的个人偏好和团队规范冲突不要把个人偏好写进项目 CLAUDE.md应该放进全局~/.claude/CLAUDE.md。比如团队项目里规定用 npm但你个人习惯 pnpm全局记忆里写“个人项目用 pnpm团队项目以项目 CLAUDE.md 为准”就能避免冲突。4. memory 机制让 Claude 真的记住你Claude Code 的memory是我认为它和普通“会话式 AI 编码工具”拉开差距的地方。普通工具关了终端就失忆Claude Code 会通过 memory 机制把对话中的关键信息沉淀下来下次会话直接生效。4.1 从会话记忆到跨会话记忆会话内记忆是任何大模型都有的能力——你在一次对话里说过的上下文它能理解并回应。但 Claude Code 默认不会在每次会话结束后把所有内容都保存下来它依赖 memory 机制做筛选和沉淀。两个记忆层级的区别很明显会话记忆本次会话内的上下文比如你让它改了三处代码它记得当前状态跨会话记忆通过 memory 保存下来的长期偏好和事实比如“这个项目使用 pnpm”“用户不喜欢自动提交代码”我在实际使用中发现Claude Code 会在交互中主动记忆一些信息。比如你跟它说“以后提交信息用中文”它可能会反问一句“是否要记住这个偏好”或者直接把这条写进记忆文件。这个过程不需要你手动编辑配置用得越久它越懂你。4.2 会话中的记忆管理方法处理记忆最直接的方式是使用记忆相关的斜杠命令比如/memory用来查看当前记住了哪些内容。不同小版本命令细节略有差异但原理一致把“需要长期记住的事”显式告诉它或者让它确认是否记住你的偏好。我常用的是一个两步工作流在会话中直接说“记住这个项目测试命令是 pnpm test”用/memory查看确认必要时手动增删条目这个方法比频繁修改 CLAUDE.md 轻量得多尤其适合记录临时但重要的事实比如某个文件的职责、某种异常的处理结论、某个用户偏好的最新版本。如果某条信息重要到团队其他人也该知道再抽出来写进项目 CLAUDE.md。这里有个很容易踩的坑memory 是自动增长的如果从不清理它会积累大量过时信息。比如你去年告诉它“用 npm”今年项目全面切到 pnpm旧的记忆不会自动失效它可能继续往新代码里写 npm 风格的脚本。定期审查 memory 内容删除过期条目是保持“记性好”的前提。4.3 memory 与 CLAUDE.md 的协同方式我会把 memory 和 CLAUDE.md 理解成一个“自动积累、手动发布”的关系。memory 是运行时自动积累的草稿CLAUDE.md 是经过人工筛选后发布的正式规范。举个例子我在会话里发现 Claude 总是忽略项目的错误处理约定于是说“记住所有接口调用都要有统一错误提示”这条会被记进 memory。如果验证下来这个规则很重要我再手动把它写进项目的 CLAUDE.md这样团队其他人协作时也能生效而不只是我本地机器的记忆。反向操作同样存在如果项目 CLAUDE.md 里规定了一条新规范但你本地 memory 里还有旧习惯记忆会覆盖项目规范。这时你需要手动清理 memory。所以我的建议是把 memory 当成私有草稿本把 CLAUDE.md 当成公开黑板两边定期同步一次。关于安全有一点必须提醒不要在 memory 或 CLAUDE.md 里写任何密钥、Token、数据库密码。Claude Code 在读取配置时可能会把内容发给模型服务敏感信息一旦进入记忆文件等于在硬盘上裸奔风险不可接受。5. 实操安装、初始化与 VS Code 接入理论讲得再多不如从零到一跑一遍。这一节按我实际走过的流程来写覆盖安装、配置、VS Code 集成和第三方模型接入。5.1 安装与初始化Claude Code 本质是一个 Node CLI 工具最常见也最不容易出错的安装方式是 npm。macOS 和 Linux 通常一行命令npm install -g anthropic-ai/claude-code全局安装完成后直接在项目目录运行claude或claude --init即可启动。--init会帮你在项目根目录生成最初的 CLAUDE.md推荐第一次都走一遍。Windows 下要特别留意。如果你下载的是老旧的安装包终端里容易报“由于与64位版本的Windows不兼容”这类错误多数是因为安装包位数或终端环境不匹配。更稳妥的方案是安装 Node.js LTS然后用上面那行 npm 命令全局安装。装完之后如果claude命令找不到优先检查 npm 全局 bin 目录有没有加进 PATH这不是 Claude Code 的问题是 Node 环境问题。登录方面官方流程需要登录 Anthropic 账号。实际使用中如果你通过 cc switch 配置了第三方 API 端点并且有自己的有效密钥工具层面就不依赖官方账号。但官方订阅的体验依然是最完整的尤其是复杂工具调用和长对话稳定性第三方接口会有波动。5.2 VS Code 里的集成与两个 settings.jsonVS Code 接入 Claude Code 有官方插件装完后在侧边栏可以直接打开 Claude 面板选中代码就能发送过去也可以让它直接读取当前打开文件、执行终端命令。插件本质上是在 VS Code 里嵌了一个 Claude Code 终端。这里有一个非常常见的混淆点VS Code 自己的settings.json和 Claude Code 的settings.json是两个完全不同的文件。前者控制编辑器行为后者控制 Claude 的工具权限和运行参数。很多人发现改了 VS Code settings.json 后 Claude 的权限没变其实改错了地方——Claude Code 的配置文件在刚说的~/.claude/settings.json和项目.claude/settings.json。在 VS Code 插件中通常需要指定 Claude Code CLI 的路径否则插件找不到claude命令。路径设置可以在插件的配置项里填多数时候会自动识别如果识别失败手动指向全局安装的 claude 入口即可。5.3 让 Claude 直接执行终端命令的完整配置很多人希望 Claude 能“自己干活”而不是每执行一条命令就弹窗问一次。办法是在 permissions 里放行对应命令。我实际配置的效果是Claude 可以自由跑npm run系列、git系列但rm -rf和涉及密钥的命令一律拦截。这样它在我确认过一次之后后续操作基本不需要频繁打断我同时危险操作又不会被静默执行。具体配置就是前面示例里的那段 allow/deny 规则。要让这套模型跑得更顺还可以在 CLAUDE.md 里写一句“执行环境macOS zsh需要检查依赖状态时直接运行 npm ls --depth0不要先征求我的同意”。这等于告诉它哪些判断属于你的既定授权范围大幅减少无效问答。如果你需要把 Claude Code 事件推送到飞书等 IM 工具常见做法是给她配一个 webhook 通知把工具调用结果或任务完成事件发送到指定群组。这部分属于外部集成依赖自己的机器人服务配置不在 settings.json 的默认范围里。6. 常见问题与排查技巧实录配置过程中报错才是常态。我根据自己实际踩过和帮朋友排查过的案例整理了一份速查表。6.1 常见错误速查表现象主要原因排查与解决Windows 报“由于与64位版本的Windows不兼容”使用旧安装包或终端架构不匹配改用 Node LTS npm 全局安装避免老式 exe 安装包启动时报 internetopenurl() failed 0x800Windows 网络请求初始化失败检查系统网络配置、安全软件拦截更新 Windows 网络组件换用新版 Windows Terminal提示“your organization has disabled claude subscription access”企业账号被管理员关闭订阅访问换用个人账号或者联系组织管理员确认订阅策略提示“claude code might not be available in your country”一类的可用性提示官方服务可用性限制通常和账号区域与订阅绑定有关确认账号与订阅状态、API 密钥有效以官方支持文档为准不要使用来路不明的第三方绕过方案Chrome out of memory / 内存溢出桌面版内置浏览器或长时间长会话占用内存过高缩短单次会话、清空 Context、重启进程、关闭非必要插件命令找不到 claudenpm 全局 bin 目录不在 PATH检查 Node 安装路径手动把全局 bin 目录加入 PATH改了 permissions 不生效改了 VS Code settings.json 而非 Claude Code 的配置文件确认路径Claude Code 配置在 ~/.claude/settings.json 或项目 .claude/ 下6.2 一次真实的排查过程之前有位同事在 Windows 上反复报internetopenurl() failed. 0x800系统里卸了装、装了卸都没用。我远程看了一圈发现问题不在 Claude Code而在系统的网络请求初始化环节——终端环境尝试发起网络请求时被系统级安全软件拦了。解决思路是“绕过 Claude Code 看网络层”。先在浏览器验证 API 是否可达再在终端里用 curl 模拟请求最后才排查 Claude Code 本身。如果你的网络请求在终端里都发不出去那换配置文件再多次也没用问题在网络栈。遇到“organization has disabled claude subscription access”这类提示先确认自己用的是不是公司管理员分发的账号。Claude Code 支持企业和团队订阅管理员可以在控制台关闭成员的访问权限个人账号遇到这个提示的概率极低。至于“Claude Code might not be available in your country”这类提示我的建议是先看账号与订阅绑定、密钥有效性而不是急着找非常规工具。这类提示通常和账号区域、服务配置有关配置正确后一般不会出现如果确实出现可用性限制请以官方文档的支持范围为准。7. 末尾想说的话配置体系的本质是让你和 AI 之间建立一套稳定的协作契约。settings.json 划定能力边界CLAUDE.md 传递项目规范memory 积累个人习惯三者缺一不可。我最开始总是想追求一份“完美配置”后来发现配置是长出来的——先写个粗糙版本每天根据实际使用增删改让它在冲突中进化。最后一个建议每次 Claude 做了一件“让你意外”的事别急着骂它先回头看看这三层配置里是不是你漏了该写进去的那一句。