1. 为什么你的 Claude Code 用起来像“高级聊天框”很多人第一次打开 Claude Code输入一句“帮我写个登录接口”看着它噼里啪啦生成代码觉得挺爽。但用上一周就会发现三个问题每次新会话它都像失忆一样不知道你们项目用 uv 而不是 pip它偶尔会直接改坏.env文件团队里每个人用出来的效果完全不一样有人觉得神有人觉得鸡肋。这不是模型能力的问题而是你只用了 CLI 的“对话层”没碰它的“工程层”。Claude Code 真正的分水岭在于三件事CLAUDE.md 项目记忆、Hooks 确定性钩子、MCP 外部能力接入。这三样配好它才从一个会写代码的聊天框变成团队里可复用、可审计的工作流组件。这篇手册按“能跟着做”的路子写。我会先讲怎么拿到可用的 API 入口再给一份可直接复制的 CLAUDE.md 模板然后是 Hooks 配置片段和 MCP 接入步骤每一步都配一个验证动作——你敲完命令能立刻看到“成了”还是“没成”。适合已经装好 Claude Code CLI、想把它推进到团队协作阶段的开发者。如果你还没装 CLI先去官网看安装说明本文从配置层开始。核心检索词先明确Claude Code 是 Anthropic 官方的命令行编程工具CLI 是它的入口形态CLAUDE.md 是项目记忆合同Hooks 是确定性质量门禁MCP 是外部工具接入协议。这四个词串起来就是本文的主线。2. 前置准备拿到稳定的 API 入口与 KeyClaude Code CLI 本身是客户端它需要一个模型服务端点来干活。默认情况下它会走官方端点但在国内网络环境下直连经常出现超时、local proxy failed、401这类报错。所以第一步是把请求指向一个稳定的兼容端点。我实测下来用 TaoToken 作为 API 入口比较省心它兼容 Anthropic 的接口格式Claude Code 不需要改代码只要改环境变量。下面是从零到能跑通的完整步骤。2.1 注册并创建 API Key打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号后进入控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在左侧菜单找到“API Keys”点“创建新密钥”。创建时给它起个能认出来的名字比如claude-code-dev方便以后按项目区分。创建完会显示一串以sk-开头的密钥只显示一次立刻复制存到密码管理器里。如果你不小心关了页面只能删掉重建。注意不要把 Key 直接写进代码仓库或 CLAUDE.md。正确做法是写进 shell 的环境变量文件或者用.env加.gitignore。2.2 配置环境变量Claude Code 读取两个关键环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。前者指向 API 端点后者是你的密钥。API 基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数。在~/.zshrc或~/.bashrc里追加export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的密钥保存后执行source ~/.zshrc让配置生效。验证一下echo $ANTHROPIC_BASE_URL # 应输出 https://taotoken.net/api2.3 确认模型 IDClaude Code 默认会用一个模型 ID 去请求。不同端点支持的模型名可能不同你需要确认当前可用的模型 ID。进入模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 可以看到可用模型列表记下你要用的那个 ID比如claude-sonnet-4-20250514这类格式。如果你想让主 Agent 和子 Agent 用不同模型可以额外设置export ANTHROPIC_MODELclaude-sonnet-4-20250514 export CLAUDE_CODE_SUBAGENT_MODELclaude-haiku-4-20250514主 Agent 用强模型做决策子 Agent 用快模型执行这是省钱又提速的常用组合。2.4 三件套对照表配置 Claude Code 接入本质就是三件套Base URL、Key、Model ID。任何一处不对都会报错。对照下面这张表检查配置项值写在哪Base URLhttps://taotoken.net/apiANTHROPIC_BASE_URLAPI Keysk-开头ANTHROPIC_API_KEYModel ID控制台可见的模型名ANTHROPIC_MODEL这三样配齐Claude Code 才能正常发起请求。后面所有 CLAUDE.md、Hooks、MCP 的配置都建立在这个基础上。3. 可复制配置CLAUDE.md 模板与 Hooks 片段这一节是全文的核心给你可以直接抄进项目的配置。先讲 CLAUDE.md 的写法再讲 Hooks 的 JSON 片段。3.1 CLAUDE.md 的三层作用域Claude Code 会自动加载当前路径上的所有 CLAUDE.md分三层位置作用域放什么~/.claude/CLAUDE.md全局个人偏好语言、代码风格项目根CLAUDE.md项目级团队约定、框架、测试命令子目录CLAUDE.md目录级特定模块规则如src/auth/CLAUDE.mdMonorepo 里这个结构特别有用根目录放通用规则各子包放自己的特殊规则Claude 进入不同目录自动切换上下文。3.2 一份可直接复制的 CLAUDE.md 模板把下面这份存到项目根目录的CLAUDE.md按你的技术栈改掉具体命令即可# MyProject ## 技术栈 - Python 3.12 FastAPI - 依赖管理uv不要用 pip - 测试make test - 类型检查make typecheck - 格式化make format自动运行 ruff black ## 约定 - Service 层返回 Result[T, Error] 类型不要直接 raise - API 路由文件放在 src/api/routes/一个资源一个文件 - 数据库迁移用 alembic新建迁移后必须跑 make test-db ## 注意事项 - 遇到 ImportError 相关问题参阅 docs/troubleshooting.md - 禁止直接操作 prod 开头的环境变量文件用 ./scripts/env.sh 管理 - 禁止使用 --force 标志改用 --force-with-lease写 CLAUDE.md 有几个原则我踩过坑之后总结的先设限制再写指南。不要一上来写百科全书指令越多遵循质量越均匀下降。目标控制在 200 行以内根据 Claude 常犯的错误逐步添加。不要用 引用文档。很多人喜欢在 CLAUDE.md 里path/to/docs.md这会在每次运行时把整份文件塞进上下文。正确做法是告诉它“什么时候”去读# 好的写法 遇到 FooBarError 时请参阅 docs/troubleshooting.md 获取排查步骤。 # 不好的写法 docs/troubleshooting.md不要只说“禁止”。纯负面约束会让 Agent 左右为难永远给替代方案。上面模板里--force那条就是例子。用 Linter 管代码风格。Claude 能读.eslintrc、.prettierrc格式化交给工具链CLAUDE.md 只记录 Linter 管不了的东西——团队约定、架构决策、内部 API 用法。3.3 Hooks 配置片段CLAUDE.md 里的规则是“应该做”Hooks 是“必须做”。配置方式有两种在 Claude Code 里输入/hooks打开交互菜单或直接编辑.claude/settings.json。下面是几个实用片段。代码写入后自动格式化PostToolUse{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: npx prettier --write \$CLAUDE_FILE_PATHS\ } ] } ] } }阻止写入敏感文件PreToolUse{ hooks: { PreToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: echo \$CLAUDE_FILE_PATHS\ | grep -qE \\.env$|\\.git/ exit 2 || exit 0 } ] } ] } }exit 2表示阻止执行exit 0表示放行。这个钩子会拦截对.env和.git/目录的写入。提交时强制测试通过PreToolUse 包裹 git commit{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: echo \$CLAUDE_TOOL_INPUT\ | grep -q git commit make test || exit 0 } ] } ] } }测试不通过就阻止提交迫使 Claude 进入“测试-修复”循环。3.4 一个关键原则不要在写入时阻断我刻意不在 Edit 或 Write 操作上设阻断钩子。在 Agent 执行计划的中途打断它会让它困惑甚至“摆烂”。更好的做法是让它完成整个计划在提交阶段检查最终结果。就像代码审查应该在 PR 阶段做而不是在工程师每写一行代码时都打断他。4. 验证请求从 CLI 到 MCP 的逐项确认配置写完不算完得逐项验证。这一节给你每个环节的验证动作和预期结果。4.1 验证 CLI 基础连通打开终端进入你的项目目录运行claude -p 用一句话说明这个项目的技术栈 --output-format json如果配置正确你会看到一段 JSON 输出里面包含模型返回的文本。如果报401说明 Key 不对如果报local proxy failed或超时说明 Base URL 不通。回到第 2 节检查三件套。4.2 验证 CLAUDE.md 是否被加载在项目里运行claude -p 这个项目用什么管理依赖如果 CLAUDE.md 写对了它会回答“uv”而不是“pip”。如果它答错说明 CLAUDE.md 没被加载——检查文件是否在项目根目录文件名是否全大写。4.3 验证 Hooks 是否生效故意让 Claude 写一个.env文件claude -p 在项目根目录创建 .env 文件写入 TEST1如果 PreToolUse 钩子配对了它会拒绝执行并告诉你被拦截了。如果它真的创建了文件说明钩子没生效——检查.claude/settings.json的 JSON 格式是否正确可以用cat .claude/settings.json | python -m json.tool验证语法。4.4 验证 MCP 接入MCP 是连接外部工具的标准协议三种传输模式模式延迟适用场景stdio5ms本地服务器推荐默认SSE较高远程服务器连接HTTP Streamable中等生产环境云部署添加一个本地 stdio 模式的 MCP 服务器claude mcp add brave-search -- npx -y anthropic/mcp-server-brave-search添加后运行claude mcp list应该能看到brave-search在列表里。然后在会话里输入/mcp可以看到已连接的服务器状态。4.5 Skills 与 MCP 怎么选我的经验是分场景场景选择理由有状态的复杂环境数据库连接MCP需要管理连接和状态无状态的工具调用Jira、GitHubCLI Skills更轻量Agent 自己写脚本可复用的工作流代码审查Skills流程固化按需加载MCP 的最佳角色是安全网关——管理认证、网络和安全边界提供几个高层次的工具然后让开。不要变成臃肿的 API 镜像。Skills 是.claude/skills/或.claude/commands/下的 Markdown 文件输入/触发。我只保留两个高频命令/catchup读取当前 git 分支的所有变更文件/pr清理代码、暂存更改、准备 PR。如果你有一长串复杂的斜杠命令可能在制造反模式——Agent 的意义在于你可以用自然语言完成任何事。5. 本篇常见错排查401、local proxy failed、OAuth 报错配置过程中最容易撞上的几个报错我按真实日志对照给你排查路径。5.1 401 Unauthorized完整报错通常长这样API Error: 401 {error:{type:authentication_error,message:invalid x-api-key}}原因有三个Key 复制时带了空格、Key 已失效、环境变量没生效。排查顺序先echo $ANTHROPIC_API_KEY看值对不对注意有没有首尾空格再去控制台确认 Key 状态是“启用”最后确认你改的是当前 shell 用的配置文件zsh 改.zshrcbash 改.bashrc。5.2 local proxy failed完整报错Error: local proxy failed to connect: dial tcp ... connection refused这个通常是 Base URL 写错或者网络到端点不通。检查ANTHROPIC_BASE_URL是不是https://taotoken.net/api注意不要多加斜杠或路径。然后用curl -I https://taotoken.net/api看能不能通。如果 curl 也不通说明是网络层问题不是配置问题。5.3 reading choices 相关报错完整报错Error: reading choices: unexpected end of JSON input这个多半是端点返回了非预期格式常见于 Base URL 指向了一个不兼容 Anthropic 格式的地址。确认你用的是兼容端点而不是 OpenAI 格式的地址。Claude Code 走的是 Anthropic Messages API 格式端点必须兼容这个格式。5.4 OAuth 相关报错完整报错Error: OAuth token expired, please re-authenticate如果你之前用官方账号登录过本地可能残留了 OAuth 凭证它会覆盖环境变量里的 Key。解决办法是清掉本地凭证缓存通常在~/.claude/目录下。清掉后重启终端让它重新读环境变量。5.5 配置三件套自查清单每次报错先按这个清单过一遍检查项命令预期Base URLecho $ANTHROPIC_BASE_URLhttps://taotoken.net/apiAPI Keyecho $ANTHROPIC_API_KEYsk-开头无空格Model IDecho $ANTHROPIC_MODEL控制台可见的模型名连通性curl -I https://taotoken.net/api返回 HTTP 状态码三件套对了90% 的报错都会消失。剩下 10% 是本地凭证缓存或网络层问题。6. 把 CLI 升级为团队工程化工作流配置跑通只是起点。真正让 Claude Code 产生团队价值的是把它嵌进工程体系里。Plan 模式处理大活。对于大型功能变更让 Claude 先列计划、你确认了再动手。定义好“检查点”——这是 Claude 需要停下来让你验收的地方避免一口气改太多发现方向不对。用多了会培养出一种直觉提供多少最少的上下文能让它给出好计划又不会在实现阶段跑偏。Git Worktree 做并行隔离。多个 Agent 同时改代码最怕文件冲突。给每个并行任务创建独立工作树git worktree add ../project-auth feature/auth git worktree add ../project-payment feature/payment每个 Worktree 是独立工作目录改代码互不影响。核心原则读操作随便并行写操作必须隔离。上下文管理三策略。每个会话至少跑一次/context看 200k token 怎么被分配的。切换任务时用/clear清空再用自定义/catchup重新加载必要上下文。上下文超过 80% 时用/compact压缩但自动压缩不透明容易丢信息只在确实快满时用。大任务做到一半上下文快满了让 Claude 先把进展导出到.claude/progress.md然后/clear新会话读这个文件继续——相当于给 Agent 创建外部记忆。GHA 推到生产。在 GitHub Actions 里运行 Claude Code做自动 PR 审查。用/install-github-app一键设置之后在 PR 评论里claude就能触发。进阶玩法是事件驱动从 Slack、Jira、告警系统触发自动生成修复 PR。GHA 的日志就是完整的 Agent 日志定期审查这些日志找出 Agent 常犯的错误改进 CLAUDE.md——这形成一个数据驱动的飞轮Agent 犯错、日志记录、发现模式、改进配置、Agent 更聪明。安全建议。定期审计 permissions 里允许 Claude 自动运行的命令列表把curl、wget、nc、ssh加入全局 deny 规则审查第三方项目的 CLAUDE.md 和.claude/settings.json已有公开仓库发现恶意注入的案例。如果你想把长期编码和 Agent 工作流固定下来可以看看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它把常用的模型额度和调用方式打包好适合团队长期用。需要查接入细节就去文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Key 管理在 API Keys https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。验证模型效果可以直接在模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 里试。最后留一个我常用的 shell 别名提效明显alias ccclaude alias cchclaude --model claude-haiku-4-20250514简单任务用快模型复杂决策用强模型成本和质量都能兼顾。把这些配好Claude Code 就不只是编码助手而是团队工程系统里一个可审计、可自我改进的核心组件。