1. Claude Code 配置目录到底管什么Claude Code 是 Anthropic 推出的命令行编程助手它能在终端里读代码、改文件、跑命令、做代码审查。很多人第一次装完就急着敲claude结果发现模型连不上、权限弹窗一堆、自定义 Agent 不生效——问题基本都出在配置目录没理清。Claude Code 的所有行为都由一个隐藏目录.claude/驱动里面最核心的三类东西是settings.json全局设置与权限、CLAUDE.md全局指令与规则、agents/自定义智能体定义。搞懂这三者的职责边界和放置位置你才能把模型通道、权限白名单、团队规范一次性配好。这篇聚焦配置目录结构本身同时给出一套通过统一 Key/API 通道接入 TaoToken 的配置骨架。适合已经装好 Claude Code、但被 settings.json 和 CLAUDE.md 搞晕的开发者也适合想把团队规范固化进 Agent 的工程同学。下面所有路径以 Windows 为例macOS/Linux 把C:/Users/你的用户名/换成~即可逻辑完全一致。2. 接入前先拿到统一 Key 与 API 地址Claude Code 默认走 Anthropic 官方端点但你可以通过环境变量把请求指向兼容的 API 通道。TaoToken 提供统一的 Key 和 API 地址配置进settings.json的env字段后Claude Code 发出的模型请求就会走这条通道不用改任何源码。你需要先准备两样东西一个 API Key以及 API 基础地址https://taotoken.net/api。Key 在控制台的 API Keys 页面创建建议按项目或按人分配方便后续排查是哪个 Key 出的问题。创建入口在这里控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleAPI Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys拿到 Key 后先别急着写进全局配置。我的习惯是先在项目级settings.local.json里试通确认请求能返回再决定要不要提升到全局。这样即使 Key 写错也不会污染所有项目。如果你还没决定用哪个模型可以先去模型对话页跑一句测试确认通道可用模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat3. 目录树与三类文件的职责划分先把.claude/的骨架摆出来你对着自己的目录看会更清楚。下面只保留和本篇相关的部分省略了 cache、backups 这类运行时目录C:/Users/你的用户名/.claude/ ├── CLAUDE.md # 全局指令所有项目生效 ├── settings.json # 全局设置模型、权限、env ├── settings.local.json # 项目级设置覆盖全局放在项目根目录 ├── agents/ # 自定义 Agent 定义 │ ├── architect.md │ └── code-reviewer.md ├── skills/ # 可复用技能 └── projects/ # 项目会话记录三类核心文件的职责可以这样理解CLAUDE.md是行为准则告诉模型该守什么规矩settings.json是运行参数决定用哪个模型、哪些命令免确认、环境变量是什么agents/是岗位说明书为重复性任务定义专用角色。优先级上项目级settings.local.json会覆盖全局settings.json而CLAUDE.md的指令优先级最高会覆盖模型的默认行为。3.1 settings.json 的字段与接入骨架settings.json放在C:/Users/你的用户名/.claude/settings.json是全局配置。接入 TaoToken 的关键在env字段把 API 地址和 Key 写进去Claude Code 启动时会读取这些环境变量。下面是一份可直接复制的骨架{ model: claude-sonnet-4-20250514, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的_TaoToken_Key }, permissions: { allow: [ Bash(git status:*), Bash(git diff:*), Bash(npm:*), Read(*) ], deny: [ Bash(rm -rf:*) ] }, theme: dark }几个字段说明model指定默认模型env里的ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址ANTHROPIC_API_KEY填你创建的 Key。permissions.allow是免确认白名单把高频只读命令放进去能少点很多次回车permissions.deny是硬拦截rm -rf这类危险命令直接禁掉。注意 Key 不要提交到 Git全局配置只存在本机。3.2 CLAUDE.md 写什么、不写什么CLAUDE.md放在C:/Users/你的用户名/.claude/CLAUDE.md定义所有项目都生效的全局规则。它适合放通用约束比如 Git 操作限制、文件修改前必须确认、代码风格要求。不适合放项目特定配置那些应该放到项目根目录的CLAUDE.md里。一份精简的全局指令长这样# 全局工作规则 ## Git 操作 - 只读操作git status / git diff / git log可直接执行 - 提交、推送、重置前必须先说明将要执行的操作 ## 文件修改 - 修改任何文件前先说明改动点和影响范围 - 不删除未被要求删除的文件 ## 代码风格 - 遵循项目已有的命名和缩进约定 - 新增依赖前先确认是否已有同类库这份文件会被注入每次会话的上下文所以别写太长控制在几十行以内只留真正需要模型每次都记住的规则。3.3 agents/ 定义专用角色agents/目录下每个.md文件就是一个自定义 Agent通过 YAML frontmatter 声明名称、描述、可用工具和模型。它和 Skill 的区别在于Agent 是独立子进程有独立上下文和工具权限Skill 是当前会话加载的流程指导。代码审查、架构分析这类需要隔离上下文的任务适合做成 Agent--- name: code-reviewer description: 审查代码变更关注安全和边界条件 tools: [Read, Grep, Glob] model: sonnet --- # 代码审查员 你是一名严格的代码审查员负责检查提交的变更。 ## 审查重点 - 输入校验是否完整 - 是否有硬编码的密钥或路径 - 错误处理是否覆盖异常分支 ## 输出格式 按严重程度分级列出问题每条给出文件位置和修改建议。把tools限制为只读工具审查 Agent 就不会误改代码这是比口头约束更硬的隔离手段。4. 验证配置是否生效配置写完必须验证否则你永远不知道请求到底走了哪条通道。第一步在终端里确认环境变量被正确读取claude --version echo $ANTHROPIC_BASE_URLWindows PowerShell 用echo $env:ANTHROPIC_BASE_URL。如果输出是https://taotoken.net/api说明全局配置已加载。第二步进入一个测试项目直接发起一次对话cd ~/test-project claude 用一句话说明这个目录里有哪些文件如果模型正常返回内容说明 Key 和 API 地址都通了。第三步验证权限白名单是否生效让 Claude Code 执行git status如果不再弹确认框说明permissions.allow里的规则被识别。第四步验证 Agent 是否注册成功在会话里输入/agents查看列表应该能看到code-reviewer。如果请求返回 401多半是 Key 写错或没生效返回 404检查ANTHROPIC_BASE_URL是否多了斜杠或路径。验证通过后这套骨架就可以复制到其他机器只改 Key 即可。5. 本篇常见错排查配置过程中最容易踩的坑集中在路径、优先级和字段名三处。下面按现象列排查方向。现象一改了 settings.json 但没生效。先确认文件位置对不对全局配置必须在~/.claude/settings.json不是项目目录。其次检查 JSON 语法多一个逗号就会导致整个文件被忽略用python -m json.tool settings.json校验一下。现象二项目级配置没覆盖全局。settings.local.json要放在项目根目录的.claude/下不是用户目录。优先级是settings.local.jsonsettings.json 默认值放错位置就不会覆盖。现象三Agent 不出现。检查 frontmatter 的---是否成对name字段是否重复。文件名和name不一致时以name为准建议保持一致避免混淆。现象四请求走了官方端点。说明ANTHROPIC_BASE_URL没被读取。确认它写在env对象里而不是文件顶层。环境变量名大小写敏感别写成anthropic_base_url。现象五权限白名单不匹配。Bash(git status:*)里的冒号和星号是固定语法写成Bash(git status)不会匹配带参数的命令。deny 规则优先级高于 allow冲突时以 deny 为准。6. 把配置固化成团队骨架配置目录理清后建议把settings.json和CLAUDE.md做成团队模板新同学克隆后只填自己的 Key 就能开工。长期做编码和 Agent 任务的话可以了解 Coding Plan把额度管理和多项目接入统一起来Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc我自己的做法是把全局CLAUDE.md控制在 30 行以内只放跨项目通用的安全规则项目特有的约定全部下沉到项目根目录的CLAUDE.md。这样换项目时不用改全局配置也不会让模型被无关规则干扰。Agent 则按团队角色建审查、架构、文档各一个工具权限按最小必要原则给跑一段时间后再根据实际误报调整description里的触发描述。