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 三件套配到 TaoToken
Claude 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_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的TaoToken密钥" export ANTHROPIC_MODEL="claude-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-review@claude-code-plugins": true, "feature-dev@claude-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 才算真正从“装好了”变成“用起来了”。
