1. 从零跑通 Claude Code为什么 settings 才是第一道坎Claude Code 是 Anthropic 推出的终端级编码代理它能在你的项目目录里读文件、改代码、跑命令、连外部工具适合已经会用命令行、想让 AI 真正参与工程流程的开发者。很多人第一次装完就卡在登录和模型调用上或者装好了却不知道怎么让它记住项目规范、怎么挂 MCP、怎么拆 Subagents最后只当成一个高级聊天框用。这篇指南按“装好就能跑通一次完整任务闭环”的目标来写重点放在 settings 配置、CLAUDE.md 项目记忆、MCP 与 Skills 挂载、Subagents 分工这四件事上每一步都给可复制的片段和验证动作。先说清楚它和普通补全插件的区别。Claude Code 的工作方式是“代理式”的你给它一个目标它会自己规划步骤、调用工具、读你的代码库、执行 bash、再根据结果调整。这意味着两件事——第一它需要明确的权限边界否则会乱改文件第二它需要项目上下文否则每次都要你重复解释。settings.json 和 CLAUDE.md 就是解决这两个问题的核心文件。前者管权限、模型、语言、插件开关后者管项目记忆和规范。我试过在一台干净的开发机上从零走一遍最容易踩的坑不是安装本身而是模型接入和配置文件的路径搞混。全局配置在~/.claude/项目配置在项目根目录的.claude/两者会合并项目级优先。很多人改了全局 settings 却发现项目里不生效就是因为项目目录下还有一份覆盖配置。下面会先把接入层配好再逐层往上搭工作流。这一节你要建立的认知是Claude Code 的能力上限取决于你给它的配置质量。一个只填了 API Key 的环境和一个配好 CLAUDE.md、挂上 MCP、定义好 Subagents 的环境产出质量差得很远。所以别急着写业务代码先把地基打牢。2. 接入前置把 Base URL、Key、Model ID 三件套配到 TaoTokenClaude Code 默认走 Anthropic 官方端点但在国内网络环境下直接连经常超时或认证失败。TaoToken 提供兼容 Anthropic 协议的接入层你只需要把 Base URL 指向它配上自己的 Key再指定 Model ID就能让 Claude Code 正常发起请求。这三件套缺一不可少任何一个都会在启动或首次请求时报错。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制保存。注意 Key 只在创建时完整显示一次关掉页面就看不到了建议直接存进密码管理器。拿到 Key 之后Base URL 用https://taotoken.net/api这个地址不加任何查询参数直接作为 Anthropic 兼容端点使用。接下来是配置。Claude Code 读取环境变量的方式最省事你可以在 shell 配置文件里写死也可以用项目级 settings。推荐先用环境变量验证连通性确认没问题再固化到配置文件。在~/.zshrc或~/.bashrc里加export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥 export ANTHROPIC_MODELclaude-sonnet-4-5改完执行source ~/.zshrc让变量生效。Model ID 这里填claude-sonnet-4-5日常编码够用需要更强推理时换成claude-opus-4-5。如果你不确定当前账号能用哪些模型可以先去 https://taotoken.net/models 看一眼可用列表或者在模型对话页 https://taotoken.net/chat 里试一条消息确认 Key 有效再回来配 Claude Code。环境变量验证通过后把它固化进全局 settings。编辑~/.claude/settings.json{ language: Chinese, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5 }, permissions: { allow: [ Bash(npm test), Bash(git status), Read(src/**) ], deny: [ Bash(git push --force), Write(config/production.json) ] } }这里env块负责接入三件套permissions块负责行为边界。注意 deny 规则优先级高于 allow所以像git push --force这种危险操作即使被误加进 allow 也会被拦。配置写完后用claude --version确认 CLI 装好了再进项目目录跑一次claude启动。如果启动时提示认证失败先检查 Key 有没有多余空格再确认 Base URL 结尾没有斜杠。对于长期做编码和 Agent 任务的场景可以考虑 Coding Plan额度更稳定适合每天都要跑多轮任务的开发者入口在 https://taotoken.net/coding-plan 。如果你只是偶尔用按量付费的 API Key 就够了。两种方式都走同一套 Base URL切换时只改 Key 或套餐绑定即可。3. 可复制配置settings.json、CLAUDE.md 与 MCP 挂载这一节给三份可以直接抄的配置分别对应全局设置、项目记忆、MCP 服务器。路径必须和原文一致否则 Claude Code 读不到。全局配置放~/.claude/settings.json项目配置放项目根目录的.claude/settings.json项目记忆放项目根目录的CLAUDE.md。先看完整的全局 settings在上一节基础上补上插件和主题{ language: Chinese, theme: dark, defaultModel: claude-sonnet-4-5, vimModeByDefault: false, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5 }, permissions: { allow: [ Bash(npm test), Bash(npm run lint), Bash(git status), Bash(git diff), Read(src/**) ], deny: [ Bash(rm -rf *), Bash(git push --force), Write(config/production.json) ] }, enabledPlugins: { code-reviewclaude-code-plugins: true, feature-devclaude-code-plugins: true } }项目级 settings 只需要写和全局不同的部分比如项目专属的权限或模型。放在.claude/settings.json{ permissions: { allow: [ Bash(pytest), Bash(python -m pytest) ] } }然后是 CLAUDE.md这是项目记忆的核心。它会在每次会话启动时被读入上下文所以内容要精炼、可执行。放在项目根目录# 项目规范 ## 语言规范 - 所有对话和文档使用中文 - 代码注释使用中文 - commit message 使用英文 ## 代码规范 - 语言版本Python 3.11 - 架构模式分层架构service 层不直接操作数据库 - 代码风格遵循 ruff 规则缩进 4 个空格 - 所有函数必须有类型提示 ## 项目结构 - /src - 源代码 - /tests - 测试代码 - /docs - 文档 ## 常用命令 - 运行测试pytest - 代码格式化ruff format . - 代码检查ruff check . ## 重要规则 - 禁止直接操作生产数据库 - 所有 API 调用必须有错误处理 - 敏感信息从环境变量读取写完 CLAUDE.md 后在 Claude Code 里输入/memory可以随时打开编辑输入/init可以让它自动分析项目生成一份初版。建议把 CLAUDE.md 提交到代码仓库团队共享同一份 AI 指导文件。最后是 MCP 挂载。MCP 是 Model Context Protocol让 Claude Code 连接外部数据源和工具。以连接一个本地文件系统 MCP 为例在项目.claude/settings.json里加{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/projects/your-project ] } } }配好后重启 Claude Code输入/mcp查看服务器状态显示 connected 就成功了。之后可以用filesystem:前缀引用该服务器提供的资源。注意 MCP 服务器不要直连生产数据库本地开发库或只读副本更安全。4. 验证请求跑通一次完整任务闭环配置写完必须验证否则你不知道是接入层的问题还是配置写错了。验证分三步先确认模型能响应再确认项目记忆被读到最后确认 MCP 和 Subagents 能协同工作。第一步在项目目录启动 Claude Code输入一条最简单的请求cd ~/projects/your-project claude进入交互界面后输入你好请用一句话说明你当前使用的模型和语言设置如果返回中文且模型名和你配置的一致说明接入三件套生效了。如果报 401检查 Key如果报连接超时检查 Base URL 是否写成https://taotoken.net/api而不是带斜杠的版本。这一步也可以用 headless 模式快速验证claude -p 用一句话说明你当前使用的模型第二步验证 CLAUDE.md 是否被读到。输入请复述本项目 CLAUDE.md 里的代码规范要点如果它能说出“Python 3.11”“ruff”“类型提示”这些你写进去的内容说明项目记忆加载成功。如果它说不知道检查 CLAUDE.md 是不是放在项目根目录文件名大小写是否正确。第三步验证 MCP。输入/mcp看服务器状态然后试着引用filesystem: 列出 src 目录下的所有 Python 文件如果它能列出文件说明 MCP 挂载成功。这一步常见问题是 npx 首次运行需要下载包网络慢会超时可以提前在终端手动跑一次npx -y modelcontextprotocol/server-filesystem预热缓存。第四步验证 Subagents。在.claude/agents/目录下创建一个子代理定义文件比如.claude/agents/code-reviewer.md你是一个专业的代码审查专家专注于检查代码质量、安全漏洞和性能问题。 审查时优先关注错误处理是否完整、是否有硬编码敏感信息、是否有明显的性能瓶颈。 输出格式按文件分组每条问题给出文件路径、行号、问题描述和修复建议。然后在会话里调用使用 code-reviewer agent 审查 src 目录下最近修改的文件如果它按你定义的格式输出审查结果说明 Subagents 生效。Subagents 的价值在于分工审查、写测试、生成文档可以并行每个子代理有独立上下文不会互相污染。你可以定义多个子代理在.claude/agents/下每个.md文件就是一个代理。跑通这四步你就完成了一次完整闭环接入层通、项目记忆通、外部工具通、任务分工通。之后所有工作流都是在这个地基上叠加。5. 常见报错排查401、local proxy failed、reading choices、OAuth配置过程中最容易遇到四类报错每一个都对应明确的排查路径。下面按报错原文对照给出原因和修复动作。第一类401 Unauthorized或authentication_error。原因通常是 Key 无效、Key 前后有空格、或者 Base URL 和 Key 不匹配。排查顺序先在终端执行echo $ANTHROPIC_API_KEY确认变量值没有多余字符再去 https://taotoken.net/api-keys 确认这个 Key 还在有效期内、没有被删除最后确认ANTHROPIC_BASE_URL是https://taotoken.net/api结尾没有斜杠。如果环境变量和 settings.json 里都配了 Key以 settings.json 为准检查两处是否一致。第二类local proxy failed或ECONNREFUSED。这通常出现在你本地配了某个转发端口但该端口没有服务在监听。Claude Code 本身不需要本地转发如果你之前为了别的工具配过HTTP_PROXY或HTTPS_PROXY环境变量先临时清掉unset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY然后重启 Claude Code。如果清掉后恢复正常说明是残留的转发配置在干扰。注意不要在任何配置里写本地转发地址直接让 Claude Code 走https://taotoken.net/api即可。第三类reading choices或Cannot read properties of undefined (reading choices)。这个报错说明返回的响应结构不符合预期常见原因是 Base URL 指向了一个 OpenAI 格式的端点而 Claude Code 期望的是 Anthropic 格式。确认你的 Base URL 是https://taotoken.net/api不要手动拼/v1/chat/completions这类路径。另一个可能是 Model ID 写错了去 https://taotoken.net/models 核对可用模型名确保拼写完全一致。第四类OAuth相关报错比如OAuth token expired或failed to refresh token。Claude Code 在某些登录模式下会走 OAuth 流程如果你用的是 API Key 模式不应该出现 OAuth 报错。出现时先执行/logout清除本地凭证再重新用 API Key 配置。如果之前登录过官方账号本地可能残留了 OAuth 凭证删掉~/.claude/下的凭证缓存文件再重启。确认 settings.json 里只配了ANTHROPIC_API_KEY没有混入其他认证字段。排查时有一个通用技巧用claude --version确认 CLI 版本用/status查看当前连接状态和模型用/doctor做系统自检。这三个命令能覆盖大部分环境问题。如果/doctor报 Node.js 版本不满足升级到 18 以上报配置文件格式错误用 JSON 校验工具检查 settings.json 是否有尾逗号。6. 把工作流固化下来Skills、Subagents 与长期编码地基打牢之后真正提升效率的是把重复性工作固化。Skills 是知识型扩展给 Claude 提供特定领域的专业能力Subagents 是任务型分工让不同代理并行处理不同环节。两者结合能把一次性的对话变成可复用的工作流。Skills 的安装有三种方式。最省事的是自然语言安装直接在会话里说帮我安装这个 skill地址https://github.com/anthropics/skillsClaude 会自动下载并放到~/.claude/skills/。手动安装则是把 skill 目录复制到~/.claude/skills/全局或项目.claude/skills/项目级然后重启 Claude Code。安装后用ls ~/.claude/skills/确认目录存在用/status查看已加载的 Skills。使用的时候直接描述任务即可比如“使用 frontend-design skill 创建一个贪吃蛇网页小游戏”。Subagents 的配置放在.claude/agents/目录每个.md文件定义一个代理。除了前面写的 code-reviewer再给两个实用的# .claude/agents/test-writer.md 你是一个测试工程师专注于编写全面的单元测试和集成测试。 优先覆盖边界情况和错误路径测试命名遵循 test_功能_场景 格式。 输出完整的测试文件内容不要省略。# .claude/agents/doc-generator.md 你是一个技术文档专家专注于生成清晰、准确的技术文档。 文档结构概述、参数说明、返回值、示例、注意事项。 示例代码必须可运行参数说明用表格呈现。定义好之后可以在一个请求里让它们并行工作我需要完成用户认证功能请 1. 使用 code-reviewer agent 审查现有认证代码 2. 使用 test-writer agent 编写测试用例 3. 使用 doc-generator agent 更新 API 文档 这三个任务并行执行Claude Code 会创建三个独立子代理各自分配上下文并行执行后汇总结果。这种分工方式特别适合功能开发收尾阶段审查、测试、文档三件事互不依赖并行能省不少时间。对于长期编码和 Agent 任务建议把常用配置沉淀成模板。全局 settings 管接入和通用权限项目 settings 管项目专属规则CLAUDE.md 管项目记忆.claude/agents/管分工.claude/skills/管领域知识。这套结构建好之后新项目只需要复制.claude/目录再改 CLAUDE.md几分钟就能拉起一套可用的工作流。如果你每天都要跑多轮任务Coding Plan 的额度模型比按量付费更省心入口在 https://taotoken.net/coding-plan 接入文档在 https://taotoken.net/doc 有更细的参数说明需要临时验证模型行为时模型对话页 https://taotoken.net/chat 可以快速试一条。把这几件事做完Claude Code 才算真正从“装好了”变成“用起来了”。
