1. 从零跑通 Claude Code为什么新手总卡在 Key 和配置上Claude Code 是 Anthropic 推出的命令行编程 agent它本身就是一个 agent能读写文件、执行终端命令、调用工具链。适合谁适合已经会用终端、想让 AI 直接改项目代码而不是复制粘贴的开发者。但新手第一次装完最容易卡在两件事一是 Key 怎么填、base-url 写什么二是 skills、subagents、mcp 这三类能力到底怎么在settings.json里落地。我见过太多人装完 Claude Code输入claude之后报 401或者 agent 起来了但 skills 不生效、subagents 调不动、mcp 连不上。问题往往不在工具本身而在配置骨架没搭对。这篇就围绕一个目标用 TaoToken 的统一 Key把 agent、skills、subagents、mcp 四件事一次性配通并给出逐项验证动作。先说清楚概念避免后面混淆。Claude Code 本身是 agent所以它的 skills 叫 agent skills在它下面再写的 agent叫 subagent。skills 会继承主对话上下文适合处理与上下文关联大、但对上下文影响小的任务subagents 有独立上下文、独立工具、独立 skills干完活只把最终结果汇报回来。mcp 则是外部工具接入协议比如把 Figma 的远程 mcp 挂进来。这三类能力加上统一 Key就是新手接入 agent 工作流的最小闭环。TaoToken 在这里的角色是统一入口一个 Key 走通模型对话、coding plan、api-keys 管理省得你在 DeepSeek、千问、Claude 之间来回换 base-url。官网入口见 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 地址是 https://taotoken.net/api 注意 API 地址不加 UTM。2. TaoToken 前置准备拿 Key、装 Claude Code、定目录2.1 安装 Claude Code官方快速开始文档在 https://code.claude.com/docs/zh-CN/quickstart#homebrew 。macOS 用 Homebrew 最省事brew install --cask claude-codeLinux 和 Windows 按文档走对应安装方式。装完后终端输入claude --version能打印版本号就说明二进制就位了。2.2 拿 TaoToken 统一 Key打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来形如sk-xxxx。这个 Key 后面会同时用于ANTHROPIC_AUTH_TOKEN和 mcp 相关配置。如果你还没决定用哪个模型可以先在模型对话页 https://taotoken.net/models 试一下确认 Key 可用再往下配。2.3 确定配置目录Claude Code 读取配置的优先级是项目级./.claude/settings.json 用户级~/.claude/settings.json。新手建议先配用户级全局生效避免每个项目重复写。mkdir -p ~/.claude touch ~/.claude/settings.jsonWindows 用户注意Claude Code 在 Windows 上主要通过环境变量读取路径是%USERPROFILE%\.claude\settings.json但更稳的方式是用 PowerShell 设用户级环境变量后面会给命令。3. 可复制的 settings.json 配置骨架3.1 用户级 settings.json 完整骨架下面这份骨架把 env、skills、subagents、mcp 四块都留了位置。你可以直接复制把sk-你的TaoToken密钥替换成真实 Key。{ env: { ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_BASE_URL: https://taotoken.net/api, API_TIMEOUT_MS: 600000, ANTHROPIC_MODEL: claude-sonnet-4-5, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-5, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1 }, permissions: { allow: [ Bash(npm run *), Bash(git status), Read, Write ] }, mcpServers: { figma-remote-mcp: { type: http, url: https://mcp.figma.com/mcp } } }几个关键点解释一下。ANTHROPIC_BASE_URL填https://taotoken.net/api不要带 UTM 参数否则部分客户端会把它当成路径的一部分导致 404。API_TIMEOUT_MS给到 600000是因为 agent 跑长任务时容易超时默认值偏短。ANTHROPIC_SMALL_FAST_MODEL用于轻量任务能省 token。3.2 Windows 环境变量写法Windows 上如果不想用 settings.json可以用 PowerShell 设用户级变量[System.Environment]::SetEnvironmentVariable(ANTHROPIC_BASE_URL, https://taotoken.net/api, User) [System.Environment]::SetEnvironmentVariable(ANTHROPIC_AUTH_TOKEN, sk-你的TaoToken密钥, User) [System.Environment]::SetEnvironmentVariable(API_TIMEOUT_MS, 600000, User) [System.Environment]::SetEnvironmentVariable(ANTHROPIC_MODEL, claude-sonnet-4-5, User) [System.Environment]::SetEnvironmentVariable(ANTHROPIC_SMALL_FAST_MODEL, claude-haiku-4-5, User) [System.Environment]::SetEnvironmentVariable(CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, 1, User)设完要重开终端才生效。注意ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY二选一即可同时存在时以 AUTH_TOKEN 优先。3.3 skills 目录骨架skills 放在~/.claude/skills/下每个 skill 一个文件夹里面放SKILL.md。骨架长这样~/.claude/skills/ └── code-review/ └── SKILL.mdSKILL.md的 frontmatter 里name和description决定 Claude 什么时候调用它--- name: code-review description: 当用户要求审查代码、检查潜在 bug 或安全问题时使用 --- # Code Review Skill 审查步骤 1. 读取目标文件 2. 检查空指针、边界条件、资源泄漏 3. 输出问题清单和修复建议3.4 subagents 目录骨架subagents 放在~/.claude/agents/下每个 subagent 一个 md 文件~/.claude/agents/ └── test-runner.md内容示例--- name: test-runner description: 独立运行测试套件并汇报失败用例 tools: Bash, Read --- 你是一个测试执行 agent。收到任务后 1. 运行 npm test 2. 解析失败输出 3. 只汇报失败用例和原因不返回完整日志subagent 的tools字段限定它能用的工具description决定主 agent 什么时候委派给它。4. 逐项验证agent、skills、subagents、mcp 是否真的生效4.1 验证 agent 启动与 Key 生效终端输入claude进入交互后随便问一句「当前目录有哪些文件」。如果返回正常说明 Key 和 base-url 通了。如果报 401回到第 5 节排查。想恢复上次对话上下文用claude -c4.2 验证 skills 生效在交互里输入/skills应该能看到你放在~/.claude/skills/下的 skill 列表。如果列表为空检查目录名和SKILL.md的 frontmatter 是否写对。也可以显式引导/code-review 帮我审查 src/index.js如果 Claude 按 SKILL.md 里的步骤执行说明 skills 生效。4.3 验证 subagents 可调用输入/agents查看已注册的 subagent。然后显式委派用 test-runner 跑一下测试观察它是否开辟独立上下文、只返回失败用例。如果它把完整日志都倒回主对话说明tools或 description 写得不够收敛。4.4 验证 mcp 连接成功输入/mcp查看当前挂载的 mcp 服务。如果figma-remote-mcp显示 connected说明 settings.json 里的mcpServers被正确读取。也可以用命令行临时加claude mcp add --transport http figma-remote-mcp https://mcp.figma.com/mcp加完再/mcp确认。mcp 连不上时先确认 url 可访问再确认 settings.json 是合法 JSON多余逗号是最常见的坑。5. 本篇常见错排查5.1 401 / 403Key 或 base-url 写错最常见的是 base-url 带了 UTM 参数或者把https://taotoken.net/api写成了https://taotoken.net/api/末尾斜杠有时会出问题。检查ANTHROPIC_AUTH_TOKEN是否以sk-开头、有没有多余空格。改完 settings.json 后要重开终端。5.2 skills 不生效目录层级或 frontmatter 错skills 必须是~/.claude/skills/skill-name/SKILL.md这种两层结构不能直接把SKILL.md放在 skills 根目录。frontmatter 的---必须顶格name和description缺一不可。5.3 subagents 调不动description 太模糊主 agent 靠 description 判断何时委派。如果写「处理测试相关」它可能永远不触发。改成「当用户要求运行测试套件并汇报失败用例时使用」这种具体描述。5.4 mcp 连接失败JSON 语法或网络先用python -m json.tool ~/.claude/settings.json校验 JSON 合法性。再确认 mcp url 在浏览器能打开。如果公司网络限制mcp 的 http 传输可能被拦换成本地 stdio 类型的 mcp 试试。5.5 上下文被塞满skills 和 subagents 用混了skills 继承主对话上下文跑长任务会把上下文窗口塞满。涉及大量日志、大量文件扫描的任务应该交给 subagents让它独立上下文跑完只回传结论。这是两者最大的区别配错了会明显感觉对话变慢、变贵。6. 把统一 Key 用顺后续接入与长期编码配置骨架搭好之后日常使用还有几个提效点。上下文查看用ctrlo压缩用/compact可以带策略比如/compact 重点保留代码直接清空用/clear。回滚按两次esc或/rewind。后台任务用! npm run dev加ctrlb再用/tasks查看或 kill。项目级设定写在./CLAUDE.md全局设定写在~/.claude/CLAUDE.md用/init生成当前目录级别的用/memory编辑。hooks 类似切面能在特定事件前后插入动作文档在 https://code.claude.com/docs/zh-CN/hooks 。如果你打算长期用 Claude Code 做编码和 agent 工作流建议把 Key 管理收敛到 TaoToken 的 coding plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 一个 Key 覆盖模型对话、api-keys 和接入文档省得每个模型单独配。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到 base-url 或模型名不确定时先查这里。模型对话验证在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite api-keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。最后留一个我踩过的坑改完settings.json一定要重开终端Claude Code 不会热加载配置。另外 skills 和 subagents 的目录名不要用中文或空格否则在某些系统上会静默不加载。把这两点避开第 4 节的四项验证基本一次过。