1. 为什么你的 Claude Code 总是“不听话”装完 Claude Code 跑第一个项目时根目录会多出一个.claude/文件夹。多数人扫一眼就略过了觉得那不过是缓存或者日志。但如果你经常觉得 Claude Code “有时候很聪明有时候又犯傻”——比如明明项目用 Jest它偏给你写 Vitest 的用例明明团队约定错误处理走自定义 Logger它还是console.log满天飞——那问题大概率不在模型而在于你没打开过这个文件夹。.claude/是 Claude Code 的控制中心。你的指令、自定义斜杠命令、权限规则、跨会话记忆、自动触发的工作流全都沉淀在这里。它分两个层级项目根目录的./.claude/是团队共享配置可以提交到 gitHome 目录的~/.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 通道你只需要维护一份 KeyClaude Code、其他编码工具、模型对话都走同一个入口省去每个工具单独配一遍的麻烦。先到控制台创建一个 API Key建议按用途分开建比如claude-code-dev、claude-code-team方便后面排查是哪个 Key 出的问题。创建入口在控制台的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_settingsutm_campaignrewrite拿到 Key 之后先别急着写进项目里的settings.json。项目级配置会提交到 gitKey 写进去等于泄露。正确做法是Key 放全局~/.claude/settings.json或者系统环境变量项目级settings.json只放权限规则和命令不碰密钥。这一点后面配置骨架里会体现。如果你还没决定用哪个模型跑 Claude Code可以先去模型对话页面试一下响应风格确认通道通不通https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_settingsutm_campaignrewrite3. 可复制配置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.mdReview 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 Heres the current diff: ! git diff --staged反引号里的!前缀会执行 shell 命令并把输出嵌入 prompt这让命令不只是存一段静态文本而是能动态注入上下文。再建一个修 issue 的命令路径.claude/commands/fix-issue.mdFix 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_sourcetaotoken_aicg_blog_endutm_contentclaude_code_verifyutm_campaignrewrite5. 本篇常见错排查配置过程中最容易踩的坑集中在几个地方逐个说。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_sourcetaotoken_aicg_blog_endutm_contentclaude_code_settingsutm_campaignrewrite配置这件事花半小时做对后面每次对话都省几分钟纠正时间。先把settings.json和两个命令跑通剩下的 rules、skills、agents 等你有了固定工作流再加也不迟。