1. 为什么你的 Claude Code 总是“重新认识你”Claude Code 是一个能读写文件、执行终端命令、搜索代码库的 AI 代理它通过“读取上下文 → 调用工具 → 检查结果 → 继续下一步”的循环自主完成开发任务。但很多人第一次用它时会有个共同困惑每次新开会话它就像失忆一样项目约定、代码风格、常用命令全都要重新讲一遍。这不是它笨而是你还没把它的扩展机制用起来。Claude Code 真正的能力不在“聊天”而在于六层可组合的扩展体系CLAUDE.md 记忆系统、Skills 技能包、Subagents 子代理、Hooks 确定性钩子、MCP 外部工具接入、插件分发。这六层各有定位上下文成本也完全不同——CLAUDE.md 始终加载最贵Subagents 和 Hooks 几乎零成本。选错机制轻则上下文爆炸重则 Claude 反复犯同一个错。这篇指南聚焦一件事用一份可复制的settings.json骨架把 Skills、Subagents、Hooks、MCP 串起来并通过 TaoToken 统一管理 Key 和 API 通道。适合刚装好 Claude Code、想从“能用”走到“好用”的开发者。下面每一步都有完整配置和验证动作你可以边看边在本地落地。2. 前置准备用 TaoToken 统一 Key 与 API 通道在配置扩展机制之前先把调用通道理顺。Claude Code 默认走 Anthropic 官方通道但如果你同时用多个模型、多个项目Key 管理会变得很乱。TaoToken 的作用是提供一个统一的 API 入口把 Key 和通道集中管理Claude Code 只需要指向一个地址。2.1 获取 Key 与确认接入地址先到 TaoToken 控制台创建一个 API Key。地址是https://taotoken.net/api注意 API 调用不加 UTM 参数。创建后你会拿到一串以sk-开头的密钥先复制保存。然后确认两个关键信息项目值说明API Base URLhttps://taotoken.net/apiClaude Code 的请求入口API Keysk-xxxxxx控制台生成妥善保存模型对话入口控制台 → 模型对话用于验证 Key 是否可用如果你还没创建 Key可以直接进控制台操作https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapikeys。创建后建议先用模型对话页面发一条测试消息确认通道正常再往下配置 Claude Code。2.2 环境变量注入Claude Code 读取环境变量来定位 API。在~/.zshrc或~/.bashrc里加入export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的密钥保存后执行source ~/.zshrc让配置生效。验证一下echo $ANTHROPIC_BASE_URL # 应输出 https://taotoken.net/api注意不要把 Key 硬编码进settings.json或提交到 git。环境变量是最稳妥的方式团队协作时每人本地注入自己的 Key。3. settings.json 骨架串联 Skills、Subagents、Hooks 与 MCPClaude Code 的扩展配置主要落在.claude/settings.json项目级和~/.claude/settings.json用户级。项目级配置会提交到 git团队共享用户级只影响你自己。下面这份骨架把四类扩展都留了位置你可以按需增删。3.1 完整骨架配置在项目根目录创建.claude/settings.json{ model: claude-sonnet-4-6, permissions: { allow: [Read, Glob, Grep], deny: [Bash(rm -rf *)] }, hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: jq -r .tool_input.file_path | xargs npx prettier --write } ] } ], PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: echo \即将执行: $CLAUDE_TOOL_INPUT\ .claude/audit.log } ] } ] }, mcpServers: { postgres: { command: npx, args: [-y, modelcontextprotocol/server-postgres], env: { DATABASE_URL: ${DATABASE_URL} } } } }这份配置做了四件事指定默认模型、限制权限、挂两个 Hook、注册一个 MCP 服务器。下面逐项拆解。3.2 Skills 目录结构Skills 不写在settings.json里而是以目录形式放在.claude/skills/下。每个 Skill 是一个含SKILL.md的文件夹.claude/ skills/ code-review/ SKILL.md deploy/ SKILL.mdSKILL.md由 YAML frontmatter 和 Markdown 正文组成--- name: code-review description: 审查代码变更的质量、安全性和性能 --- # 代码审查流程 当被要求审查代码时按以下步骤进行 1. 先运行 git diff 获取变更文件列表 2. 逐个文件审查关注类型安全、错误处理、性能隐患 3. 给出分级反馈必须修复 / 建议改进 / 可选优化description写得越准确Claude 自动匹配的命中率越高。你也可以用/code-review显式调用。3.3 Subagents 定义子代理放在.claude/agents/下同样是 Markdown 文件--- name: code-explorer description: 只读探索代码库返回结构化摘要 tools: Read, Glob, Grep model: claude-haiku-4-5 --- 你是一个只读代码探索代理。收到任务后 1. 用 Glob 定位相关文件 2. 用 Grep 搜索关键符号 3. 用 Read 读取核心文件 4. 返回结构化摘要不要返回原始文件内容关键字段是tools和model。审查类任务只给Read, Glob, Grep就够了不给写权限简单探索用 Haiku 模型成本远低于主会话用 Opus。3.4 Hooks 与 MCP 的配置位置Hooks 和 MCP 都写在settings.json里就是上面骨架中的hooks和mcpServers字段。Hooks 是事件驱动的确定性执行MCP 是 Claude 主动调用的外部工具。两者的区别用一句话概括Hooks 是“到点必跑”MCP 是“需要时才调”。4. 逐项验证确认每个扩展真的生效配置写完不代表生效。下面给出每个机制的验证动作你照着跑一遍就知道有没有配对。4.1 验证 Key 与模型通道先确认 Claude Code 能正常调用模型claude --model claude-sonnet-4-6 -p 回复 OK 两个字母如果返回OK说明 Key 和通道正常。如果报 401 或连接错误回到第 2 章检查环境变量。你也可以在 TaoToken 的模型对话页面直接发消息验证https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat。4.2 验证 Skill 加载在 Claude Code 会话里输入/code-review如果 Skill 配置正确Claude 会加载对应流程并开始审查当前 diff。如果提示找不到命令检查.claude/skills/code-review/SKILL.md路径和 frontmatter 格式。4.3 验证 Hook 触发随便让 Claude 编辑一个文件然后看.claude/audit.log有没有新增记录cat .claude/audit.log有记录说明 PreToolUse Hook 生效。再检查被编辑的文件是否被 Prettier 格式化过确认 PostToolUse Hook 也正常。4.4 验证 MCP 连接在会话里输入/mcpClaude Code 会列出已注册的 MCP 服务器及其状态。如果postgres显示 connected说明连接成功。然后可以试着问“帮我查一下 users 表有多少行”看 Claude 是否会调用 MCP 工具。4.5 验证 Subagent 隔离让 Claude 执行一个探索任务“用 code-explorer 子代理分析 src 目录的结构”。观察主会话是否只收到摘要而不是一堆原始文件内容。如果主会话被文件内容刷屏说明子代理没生效检查tools字段是否限制了读取范围。5. 本篇常见错排查配置过程中最容易踩的坑集中在路径、权限和上下文成本三块。下面按现象列排查思路。5.1 Skill 不触发或自动匹配失败现象输入/code-review提示未知命令或 Claude 不自动加载 Skill。排查顺序先确认目录是.claude/skills/name/SKILL.md注意是文件夹套文件不是单个.md。再检查 frontmatter 的name和description是否都有值缺一个都会导致加载失败。最后确认description是否足够具体——“审查代码”太泛“审查代码变更的质量、安全性和性能”才容易被匹配。5.2 Hook 命令执行报错现象编辑文件后 Hook 没跑或终端报command not found。Hook 命令是在 shell 里执行的依赖的工具必须在 PATH 里。比如npx prettier要求项目装了 prettierjq要求系统装了 jq。先在终端手动跑一遍 Hook 命令确认能执行再写进配置。另外注意matcher的写法Edit|Write是正则匹配工具名。5.3 MCP 服务器连不上现象/mcp显示 failed 或一直 connecting。先看command和args是否正确npx -y的-y不能省否则会卡在安装确认。再看env里的环境变量是否真的存在${DATABASE_URL}这种写法要求变量已在 shell 里导出。如果 MCP 服务器本身启动慢可以手动在终端跑一遍它的启动命令看报什么错。5.4 上下文被 MCP 工具定义占满现象会话刚开始上下文就用了不少。MCP 工具的定义在会话启动时就加载进上下文即使你当天没调用也占空间。解决办法是只注册真正需要的 MCP 服务器不用的从settings.json里删掉。同理CLAUDE.md 控制在 200 行以内超出的规则分流到.claude/rules/按路径加载。5.5 子代理返回结果不可信现象子代理说“已完成”但实际没做。子代理返回的是自报告它说完成了不代表真的完成了。对于关键操作自己验证一下子代理的输出——比如让它返回具体文件路径和行号你手动核对。另外给子代理限制工具权限审查类任务不给写权限避免它擅自改代码。6. 下一步把配置变成团队资产到这里你已经有一份能跑的settings.json骨架Skills、Subagents、Hooks、MCP 都验证过了。接下来两件事值得做一是把验证过的配置打包成插件分发给团队新同事入职直接装上就能用二是把长期编码和 Agent 任务交给 Coding Plan 管理避免每次手动配 Key。如果你还在调通道和 Key先去 API Keys 页面把密钥管理好https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapikeys。接入细节和参数说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc。想先验证模型效果用模型对话页面发几条消息最直接https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat。如果你的场景是长期编码或 Agent 自动化Coding Plan 更适合统一管理调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodingplan。最后提醒一句不要一次性把所有扩展都堆上去。从 CLAUDE.md 和一份 Skill 开始跑顺了再加 Hook再试 Subagent最后接 MCP。每层都有学习曲线循序渐进才不会把自己绕进去。
