1. 为什么你的 Claude Code 总是“不听话”
装完 Claude Code 跑第一个项目时，根目录会多出一个.claude/文件夹。多数人扫一眼就略过了，觉得那不过是缓存或者日志。但如果你经常觉得 Claude Code “有时候很聪明，有时候又犯傻”——比如明明项目用 Jest，它偏给你写 Vitest 的用例；明明团队约定错误处理走自定义 Logger，它还是console.log满天飞——那问题大概率不在模型，而在于你没打开过这个文件夹。
.claude/是 Claude Code 的控制中心。你的指令、自定义斜杠命令、权限规则、跨会话记忆、自动触发的工作流，全都沉淀在这里。它分两个层级：项目根目录的./.claude/是团队共享配置，可以提交到 git；Home 目录的~/.claude/是个人偏好，只对你生效。两者结构类似，职责不同。
这篇不铺开讲所有子目录，只聚焦两个最影响日常体验的位置：settings.json和commands/。同时给出一套可复制的配置骨架，把 Claude Code 的请求统一走 TaoToken 的 Key/API 通道，让你在团队协作和个人使用之间切换时不用反复改环境变量。适合已经装好 Claude Code、想把它真正用顺的开发者，也适合刚接触、想一次把配置做对的小白。
2. 前置准备：TaoToken 通道与 Key 获取
在动settings.json之前，先把通道这件事理清楚。Claude Code 默认会读环境变量里的 API 地址和 Key，如果你在多台机器、多个项目之间来回切，靠手动export很容易漏。更稳的做法是把通道信息写进.claude/settings.json的env字段，让 Claude Code 启动时自动加载。
TaoToken 在这里扮演的角色是统一的 Key/API 通道：你只需要维护一份 Key，Claude Code、其他编码工具、模型对话都走同一个入口，省去每个工具单独配一遍的麻烦。先到控制台创建一个 API Key，建议按用途分开建，比如claude-code-dev、claude-code-team，方便后面排查是哪个 Key 出的问题。
创建入口在控制台的 API Keys 页面：
https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=claude_code_settings&utm_campaign=rewrite拿到 Key 之后先别急着写进项目里的settings.json。项目级配置会提交到 git，Key 写进去等于泄露。正确做法是：Key 放全局~/.claude/settings.json或者系统环境变量，项目级settings.json只放权限规则和命令，不碰密钥。这一点后面配置骨架里会体现。
如果你还没决定用哪个模型跑 Claude Code，可以先去模型对话页面试一下响应风格，确认通道通不通：
https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=claude_code_settings&utm_campaign=rewrite3. 可复制配置：settings.json 与 commands 骨架
3.1 全局 settings.json：放 Key 和通道
全局配置路径是~/.claude/settings.json。这个文件只对你生效，不会进 git，适合放密钥和通道地址。下面是一份可直接改的骨架：
{ "$schema": "https://code.claude.com/schema/settings.json", "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoTokenKey" }, "permissions": { "allow": [ "Bash(npm run *)", "Bash(pnpm *)", "Bash(git *)", "Read", "Write", "Edit", "Glob", "Grep" ], "deny": [ "Bash(rm -rf *)", "Bash(curl *)", "Read(.env)", "Read(secrets/*)" ] } }几个关键点。ANTHROPIC_BASE_URL指向https://taotoken.net/api，注意这里不带任何查询参数，保持干净。ANTHROPIC_API_KEY填你刚创建的 Key。permissions.allow里的操作不需要确认直接执行，deny里的完全禁止，两个列表都不在的，Claude Code 会先问你。把Read(.env)和Read(secrets/*)放进 deny 是基本安全习惯，避免模型在你不注意时读到敏感文件。
3.2 项目级 settings.json：只放规则
项目根目录的./.claude/settings.json会提交到 git，所以这里绝对不要出现 Key。它只负责团队共享的权限策略：
{ "$schema": "https://code.claude.com/schema/settings.json", "permissions": { "allow": [ "Bash(npm run test)", "Bash(npm run lint)", "Bash(git diff *)", "Bash(git status)" ], "deny": [ "Bash(git push --force *)", "Read(.env.local)" ] } }个人如果想覆盖团队规则，用同目录下的settings.local.json，这个文件自动 gitignore。优先级上，settings.local.json高于settings.json，全局配置作为兜底。
3.3 commands 骨架：把重复 prompt 变成斜杠命令
.claude/commands/里每个 markdown 文件就是一个自定义命令，文件名即命令名。项目级命令显示为/project:命令名，个人命令放~/.claude/commands/，显示为/user:命令名。
先建一个代码审查命令，文件路径.claude/commands/review.md：
Review the current git diff for bugs, performance issues, and style problems. Focus on: 1. Logic errors and edge cases 2. Missing error handling 3. Performance bottlenecks Here's the current diff: `! git diff --staged`反引号里的!前缀会执行 shell 命令并把输出嵌入 prompt，这让命令不只是存一段静态文本，而是能动态注入上下文。再建一个修 issue 的命令，路径.claude/commands/fix-issue.md：
Fix the GitHub issue described below: `! gh issue view $ARGUMENTS` After fixing, run the test suite and report results.跑/project:fix-issue 234就会把第 234 号 issue 的内容喂给 Claude，$ARGUMENTS负责接收参数。这两个命令覆盖了日常最高频的两个场景，先跑起来，后面按需加。
4. 验证配置是否生效
配置写完不代表生效，得实际验证。分三步走。
第一步，确认环境变量被正确加载。在项目里启动 Claude Code，输入/status，看输出里的 API 地址和 Key 来源。如果显示的还是默认地址，说明~/.claude/settings.json没被读到，检查文件路径和 JSON 格式是否合法。
第二步，验证自定义命令是否注册。输入/help，在命令列表里找/project:review和/project:fix-issue。如果没出现，多半是文件放错了目录，或者文件名带了多余后缀。确认路径是.claude/commands/review.md，不是.claude/commands/review.md.txt。
第三步，跑一次真实请求。先git add一些改动，然后执行：
/project:review正常情况你会看到 Claude 读取了暂存区的 diff，并逐条给出审查意见。如果它说“没有检测到 diff”，检查是不是忘了git add，因为命令里用的是git diff --staged。
再验证通道是否真的走了 TaoToken。执行一次普通对话，比如让它解释一段代码，然后到 TaoToken 控制台的用量页面看是否有对应请求记录。有记录，说明ANTHROPIC_BASE_URL和 Key 都生效了。
https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=claude_code_verify&utm_campaign=rewrite5. 本篇常见错排查
配置过程中最容易踩的坑集中在几个地方，逐个说。
JSON 格式错误导致整个文件被忽略。settings.json里多一个逗号、少一个引号，Claude Code 会静默跳过这个文件，不报错。排查方法是把内容贴到任意 JSON 校验工具里过一遍。写完配置后养成习惯，先校验再启动。
Key 写进了项目级 settings.json。这是安全事故高发点。项目级文件会进 git，一旦提交，Key 就泄露了。记住原则：Key 只放全局配置或环境变量，项目级只放权限规则。如果已经提交了，立刻去控制台吊销那个 Key 重新建一个。
命令文件放错层级。项目级命令在./.claude/commands/，个人命令在~/.claude/commands/。放错位置会导致命令不出现，或者出现的前缀不对。项目级显示/project:，个人级显示/user:，用/help一看便知。
$ARGUMENTS没生效。检查命令文件里是否真的写了$ARGUMENTS，以及调用时参数是否跟在命令后面。/project:fix-issue 234里的234会被替换进去，如果写成/project:fix-issue不带参数，$ARGUMENTS就是空字符串。
权限 deny 规则没拦住。权限匹配是前缀匹配，Bash(curl *)能拦住curl https://...，但拦不住bash -c "curl ..."。deny 列表是防线不是保险箱，敏感操作还是靠人工确认。
改了配置但没重启会话。settings.json在会话启动时加载，改完要退出重进才生效。命令文件是动态读取的，新增命令不用重启，但改已有命令的内容有时需要重进。
6. 把配置沉淀成团队资产
.claude/目录真正的价值，是让“项目规矩”从口头约定变成可执行配置。settings.json管住权限边界，commands/把重复 prompt 固化成斜杠命令，两者配合，新成员拉下代码就能用同一套规则，不用再靠文档口口相传。
如果你还在用零散的 export 管理 Key，建议把通道信息收进全局settings.json，项目级只留规则。这样换机器、换项目时，只需要维护一份 Key。长期跑编码任务或者 Agent 工作流的话，可以了解下 Coding Plan，把用量和通道统一管理：
https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=claude_code_settings&utm_campaign=rewrite配置这件事，花半小时做对，后面每次对话都省几分钟纠正时间。先把settings.json和两个命令跑通，剩下的 rules、skills、agents 等你有了固定工作流再加也不迟。
