1. 新手第一次跑 Claude Code为什么总卡在 CLAUDE.md 和 MCP 上Claude Code 是 Anthropic 推出的终端级 AI 编程助手能读写项目文件、执行命令、调用外部工具适合已经有一定工程经验、想让 AI 深度参与重构和排障的开发者。它和 IDE 里的补全插件不是一类东西补全插件解决这一行怎么写Claude Code 解决这个模块怎么改、这个 bug 怎么查、这套流程怎么自动化。新手最容易卡住的地方恰好不是模型能力而是三个配置文件——CLAUDE.md、settings.json、MCP 服务定义。这三个文件决定了 Claude Code 知不知道你的项目背景、能不能调用外部工具、会不会每次操作都弹权限确认。我见过太多人装完 Claude Code第一句话就是帮我改个 bug结果它连项目用什么构建工具都不知道来回问三四轮才进入正题。问题不在模型在于你没给它一份入职手册。CLAUDE.md 就是这份手册MCP 是给它配的外挂工具箱settings.json 是门禁规则。这三样配好Claude Code 才从聪明但陌生的新人变成熟悉你项目的搭档。这篇按新手最高频的 10 个问题来组织每个问题都给可复制的配置和验证步骤。API 通道统一走 TaoToken一个 Key 覆盖 Claude 系列模型省去多平台切换的麻烦。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 下面所有配置示例都用这个 Base URL。先说清楚适合谁看如果你刚装好 Claude Code或者装了但一直没跑通 MCP或者每次操作都被权限弹窗打断节奏这篇就是给你写的。如果你已经在用 Claude Code 做日常开发可以重点看第 5、6、7 节的排错部分那些报错信息你大概率见过。2. TaoToken 前置准备一个 Key 打通 Claude Code 的 API 通道在配 CLAUDE.md 和 MCP 之前得先让 Claude Code 能正常发请求。Claude Code 默认走 Anthropic 官方通道但很多国内开发者在网络和计费上会遇到麻烦。TaoToken 提供统一的 API 通道一个 Key 就能调用 Claude 系列模型Base URL 固定为 https://taotoken.net/api 配置一次到处能用。第一步去控制台创建 API Key。打开 https://taotoken.net/api-keys 登录后点创建复制生成的 Key。这个 Key 只显示一次建议存到密码管理器里。注意不要把它硬编码进会提交到 Git 的文件后面我会讲怎么用环境变量管理。第二步配置 Claude Code 的 API 通道。Claude Code 读取环境变量来决定请求发往哪里。在终端里执行export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你用的是 zsh把这两行加到~/.zshrcbash 用户加到~/.bashrc。加完执行source ~/.zshrc让它生效。验证环境变量是否生效echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY | head -c 8第一条应该输出https://taotoken.net/api第二条输出你 Key 的前 8 位。如果第一条是空的说明没 source 成功检查一下文件路径。第三步确认模型 ID。TaoToken 的模型对话页面 https://taotoken.net/models 列出了当前可用的模型 ID。Claude Code 默认会用claude-sonnet-4-20250514这类 ID你可以在启动时用--model参数指定。日常编码用 Sonnet 就够复杂架构设计再切 Opus。这里有个新手常踩的坑把 Base URL 写成https://taotoken.net/api/带尾斜杠或者写成https://taotoken.net不带/api。Claude Code 拼接请求路径时对尾斜杠敏感多一个斜杠可能变成//v1/messages部分网关会返回 404。统一用https://taotoken.net/api不带尾斜杠。配好之后先别急着配 MCP跑一个最小验证claude --model claude-sonnet-4-20250514 -p 回复 OK 两个字母如果终端输出OK说明 API 通道通了。如果报 401说明 Key 不对或没生效如果报连接超时检查 Base URL 拼写。这一步过了再往下配 CLAUDE.md 和 MCP 才有意义。关于计费TaoToken 控制台 https://taotoken.net/console 能看到每次请求的 Token 消耗和费用明细。新手建议先跑几个小任务观察消耗心里有个数再上大任务。长期做编码和 Agent 任务的可以看 Coding Plan https://taotoken.net/coding-plan 比按量付费更适合高频使用。3. 可复制配置CLAUDE.md、settings.json 与 MCP 三件套这一节是全文的核心把三个配置文件一次讲清楚。每个都给完整可复制的片段路径和字段名严格按 Claude Code 的实际约定来。3.1 CLAUDE.md 的三层作用范围CLAUDE.md 是项目公约Claude Code 启动时自动读取。它有三层优先级从高到低文件位置作用范围适合写什么项目根目录/CLAUDE.md当前项目技术栈、编码规范、常用命令、已知坑点~/.claude/CLAUDE.md所有项目个人偏好、通用规则子目录/CLAUDE.md特定模块模块特有的架构说明项目级的 CLAUDE.md 模板直接复制改# 项目简介 用户订单系统Spring Boot 3.2 MyBatis-Plus MySQL 8.0 # 常用命令 - 启动: mvn spring-boot:run - 测试: mvn test - 构建: mvn clean package -DskipTests # 代码规范 - 命名: 驼峰命名表名用下划线分隔 - 分层: Controller 只做参数校验和路由业务逻辑全部在 Service 层 - 数据库: 禁止在代码里写 SQL统一用 XML mapper # 已知坑点 - 订单表的 create_time 字段用的是 UTC前端展示需要转东八区 - 第三方支付回调地址必须用 HTTPS本地调试用 ngrok全局的~/.claude/CLAUDE.md建议只写两条注释语言偏好和通用规则。比如注释用中文永远不要在 main 分支上直接提交。这样换项目不用重写。关键提醒CLAUDE.md 不是越长越好。我见过有人写 800 行结果每次对话都先把这 800 行塞进上下文反而挤占了真正用于理解代码的空间。控制在 100-200 行只写 Claude Code 自己读代码读不出来的东西——比如这个字段是 UTC 存储这种隐含约定它读代码是看不出来的。3.2 settings.json 的权限与 Hooks 配置settings.json 分项目级.claude/settings.json和全局~/.claude/settings.json两者会合并。权限白名单是最实用的配置把确认安全的操作加进去减少弹窗{ permissions: { allow: [ Bash(npm test), Bash(npm run lint), Bash(mvn test), Bash(git status), Bash(git diff), Bash(git log:*), Read, Edit ], deny: [ Bash(rm -rf *), Bash(git push --force) ] } }三个原则只放行确定安全的命令用:*做模糊匹配比如Bash(git log:*)匹配所有 git log 相关分层配置个人常用放全局项目特有放项目级。我的全局白名单大概 15 条覆盖日常 90% 的操作权限弹窗从一天 30 多次降到 3-5 次。Hooks 是自动化钩子在特定事件触发时执行脚本。最实用的场景是改完代码自动跑 lint{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: cd $CLAUDE_PROJECT_DIR npm run lint -- --fix } ] } ] } }Hook 事件有四种PreToolUse工具调用前做输入校验、PostToolUse工具调用后做格式化、Notification需要你关注时发通知、Stop对话结束时清理临时文件。踩过的坑我在 PostToolUse 里加了跑全量测试的 Hook结果每改一个文件等 15 秒差点以为网络卡了。后来改成只跑受影响的测试文件才恢复。3.3 MCP 服务配置三件套缺一不可MCP 是给 Claude Code 装外挂工具的标准接口。配置 MCP 服务时Base URL、Key、Model ID 三件套要写全缺一个就连不上。MCP 服务定义放在.claude/settings.json或~/.claude/settings.json的mcpServers字段{ mcpServers: { postgres: { command: npx, args: [ -y, modelcontextprotocol/server-postgres, postgresql://localhost:5432/mydb ] }, filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /path/to/allowed/dir ] } } }如果你用的是需要 API 通道的 MCP 服务比如某些远程 MCP配置里要带上 Base URL 和 Key{ mcpServers: { remote-service: { url: https://taotoken.net/api, env: { API_KEY: sk-你的TaoToken密钥, MODEL_ID: claude-sonnet-4-20250514 } } } }MCP 和 Skill 的区别要搞清楚MCP 是工具提供原子能力查数据库、读文件、调 APISkill 是工作流是预定义的指令模板告诉 Claude Code 遇到某类任务按什么流程走。打个比方MCP 是螺丝刀Skill 是如何组装书柜的说明书。Skill 文件放在~/.claude/skills/目录下每个 Skill 一个文件夹里面必须有SKILL.md。4. 验证请求从最小 MCP 服务到成功结果配置写完不代表能用得一步步验证。这一节给完整的验证流程从 API 通道到 MCP 服务逐个确认。4.1 验证 API 通道先确认 Claude Code 能通过 TaoToken 发请求。在终端执行claude --model claude-sonnet-4-20250514 -p 用一句话说明什么是 MCP预期输出是一段关于 MCP 的解释。如果输出正常说明 Base URL 和 Key 都对。如果报错对照第 5 节的排错表。4.2 验证 CLAUDE.md 是否被读取在项目根目录创建 CLAUDE.md写一条独特规则比如所有函数注释必须用中文。然后启动 Claude Codeclaude在对话里输入帮我写一个计算两数之和的函数。如果它生成的函数注释是中文说明 CLAUDE.md 被正确读取。如果注释是英文检查文件是否在项目根目录、文件名大小写是否正确必须是CLAUDE.md全大写。4.3 验证 MCP 服务启动配好 MCP 后启动 Claude Code 时它会自动拉起 MCP 服务。验证方式是看启动日志claude --verbose日志里会显示每个 MCP 服务的启动状态。如果看到MCP server postgres started这类信息说明启动成功。然后在对话里输入列出数据库里所有的表如果它能返回表名说明 MCP 工具调用链路通了。一个最小可跑的 MCP 验证用 filesystem 服务。配置好之后在对话里输入读取 /path/to/allowed/dir 下的 README.md 内容。如果它能读出文件内容说明 MCP 的 filesystem 工具正常工作。4.4 验证 Hooks 触发配了 PostToolUse Hook 之后让 Claude Code 改一个文件观察终端是否自动跑了 lint。如果 lint 输出出现在终端里说明 Hook 触发成功。如果没反应检查matcher字段是否匹配了工具名Edit和Write是两个不同的工具名用|分隔。4.5 验证权限白名单在白名单里加了Bash(git status)之后让 Claude Code 执行git status应该不再弹权限确认。如果还弹检查 settings.json 的 JSON 格式是否正确——多一个逗号或少一个引号都会导致整个文件解析失败Claude Code 会回退到默认权限策略。验证顺序建议先 API 通道再 CLAUDE.md再 MCP最后 Hooks 和权限。每一步确认通过再往下出问题容易定位。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错给排查路径。这些错误新手大概率会遇到提前知道怎么处理能省很多时间。5.1 401 Unauthorized最常见的报错。原因通常是 Key 不对或没生效。排查步骤echo $ANTHROPIC_API_KEY | head -c 8确认输出的前 8 位和你控制台里的一致。如果不一致说明环境变量没更新重新 source 一下。如果一致还报 401去 https://taotoken.net/api-keys 确认 Key 是否被禁用或过期。还有一种情况是 Key 里有空格或换行复制的时候带进去了用echo检查一下。5.2 local proxy failed这个报错说明 Claude Code 尝试走本地代理但失败了。检查环境变量里有没有HTTP_PROXY或HTTPS_PROXY指向一个不存在的本地端口。如果有unset 掉unset HTTP_PROXY unset HTTPS_PROXY然后重新启动 Claude Code。如果你确实需要走代理确认代理服务在运行且端口正确。5.3 reading choices 报错这个报错通常出现在 MCP 服务返回的数据格式不符合预期时。比如 MCP 服务返回了一个空响应Claude Code 尝试读取choices字段但找不到。排查方向确认 MCP 服务本身能正常工作单独跑一下服务的命令确认返回的 JSON 结构符合 MCP 协议。如果是自定义 MCP 服务检查返回体里有没有choices数组。5.4 OAuth 相关报错如果你用的是需要 OAuth 认证的 MCP 服务报错通常是 token 过期或 scope 不对。排查确认 OAuth token 是否还在有效期确认申请的 scope 是否包含你要调用的能力。TaoToken 的 API Key 方式不需要 OAuth如果你在配置里混用了两种认证方式去掉 OAuth 相关字段统一用 API Key。5.5 MCP 服务启动失败90% 的情况是两个原因Node.js 版本太低需要 v18或者参数里的路径写错了。先跑node --version如果低于 v18升级 Node.js。然后检查 MCP 配置里的路径用绝对路径而不是相对路径。npx命令第一次跑会下载包如果网络慢会超时可以先手动跑一次npx -y modelcontextprotocol/server-postgres --help确认能下载。5.6 权限弹窗太频繁如果配了白名单还频繁弹窗检查 settings.json 的 JSON 格式。用python -m json.tool .claude/settings.json验证格式有语法错误会直接报出来。另外确认白名单里的命令格式和实际执行的一致Bash(npm test)只匹配完全相同的命令Bash(npm test:*)才匹配带参数的。5.7 模型 ID 不识别如果报model not found去 https://taotoken.net/models 确认当前可用的模型 ID。模型 ID 会随版本更新用旧的 ID 可能已经下线。Claude Code 的--model参数要传完整的模型 ID不能只写sonnet。6. 语义一致 CTA把配置跑通之后往哪走配置跑通只是起点。Claude Code 的价值在于日常使用中不断积累 CLAUDE.md 的规则、扩展 MCP 工具链、用 Skill 固化重复流程。这里给几条实际的使用建议。第一CLAUDE.md 是活的文档。每次发现 Claude Code 犯了同类错误就把规则补进去。比如它总是忘记某个字段是 UTC 存储就在已知坑点里加一条。用一个月下来你的 CLAUDE.md 会变成项目最准确的隐性知识库。第二MCP 工具按需加不要一次配一堆。我日常用三个PostgreSQL 查数据库、filesystem 读文件、fetch 调 API覆盖后端开发 80% 的场景。每加一个 MCP 服务都会增加启动时间和上下文占用用不上的先别配。第三Hooks 从最简单的开始。先配一个 PostToolUse 跑 lint用顺了再加别的。Hook 脚本执行时间直接影响 Claude Code 的响应速度超过 3 秒就会觉得卡。第四权限白名单定期review。用一段时间后看看哪些命令经常弹窗确认安全就加进白名单。但rm -rf和git push --force这类永远放 deny 里。如果你还没创建 TaoToken 的 Key去 https://taotoken.net/api-keys 建一个按第 2 节配好环境变量。接入文档在 https://taotoken.net/doc 里面有各语言的调用示例和 MCP 配置说明。想先试试模型对话效果的可以直接在 https://taotoken.net/models 页面上测试。长期做编码和 Agent 任务的Coding Plan https://taotoken.net/coding-plan 比按量付费更划算。最后说一个实际经验Claude Code 的上下文窗口是有限的CLAUDE.md 写太长、MCP 配太多、对话不清理都会挤占真正用于理解代码的空间。定期用/compact压缩对话历史把不用的 MCP 服务注释掉保持 CLAUDE.md 精简。我试过在一个 12 万行的 Java 项目里配好 CLAUDE.md 之后改代码从平均 3-4 轮对话交代背景降到第一轮就能给出符合规范的方案Token 消耗砍掉将近一半。这个投入产出比值得每个新手花半小时把配置做扎实。