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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=console
• API Keys：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-keys

拿到 Key 后先别急着写进全局配置。我的习惯是先在项目级settings.local.json里试通，确认请求能返回，再决定要不要提升到全局。这样即使 Key 写错，也不会污染所有项目。如果你还没决定用哪个模型，可以先去模型对话页跑一句测试，确认通道可用：

• 模型对话：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=chat

3. 目录树与三类文件的职责划分

先把.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_URL

Windows 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.json>settings.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 Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding-plan
• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc

我自己的做法是把全局CLAUDE.md控制在 30 行以内，只放跨项目通用的安全规则，项目特有的约定全部下沉到项目根目录的CLAUDE.md。这样换项目时不用改全局配置，也不会让模型被无关规则干扰。Agent 则按团队角色建，审查、架构、文档各一个，工具权限按最小必要原则给，跑一段时间后再根据实际误报调整description里的触发描述。