claude code命令整理：从CLAUDE.md到MCP的REPL工作流配置清单

claude code命令整理：从CLAUDE.md到MCP的REPL工作流配置清单

发布时间：2026/10/5 19:56:38
claude code命令整理：从CLAUDE.md到MCP的REPL工作流配置清单 1. 从一次“上下文丢失”说起claude code 命令与 CLAUDE.md 到底解决什么问题如果你刚接触 claude code最容易踩的坑不是命令记不住而是每次开新会话都要重新解释一遍项目结构。我试过在一个中型前端仓库里连续问三个问题前两个回答得挺准第三个开始就把目录结构搞混了——因为它没记住我上一轮说过的“这个项目用的是 pnpm workspace不是 npm”。claude code 是 Anthropic 推出的终端 AI 编码工具它把大模型能力直接塞进你的 shell 里能读文件、跑命令、改代码、提交 git。但它的“记忆”不是无限的默认只靠当前目录结构和对话历史来推断上下文。真正让它稳定工作的是两样东西一套可复用的命令工作流以及一个叫 CLAUDE.md 的项目记忆文件。CLAUDE.md 是什么你可以把它理解成“给 AI 看的 README”。每次 claude 启动时它会自动读取项目根目录下的 CLAUDE.md把里面的内容作为系统提示的一部分。你写清楚项目用什么框架、目录怎么分、测试怎么跑、有哪些禁忌AI 就不用每次靠猜。这套工作流适合谁三类人最受益一是经常在多个仓库之间切换的开发者每个项目一份 CLAUDE.md 能省下大量重复解释二是想把 claude code 接入团队协作的人MCP 配置和权限管理能让它更可控三是刚上手、被一堆斜杠命令和启动参数搞晕的新手需要一份能直接抄的清单。下面我会按“先配好、再跑通、后排错”的顺序把 CLAUDE.md 模板、MCP 接入片段、REPL 验证步骤和常见报错一次性梳理清楚。你不需要全部记住跟着做一遍把模板存下来以后每个新项目复制粘贴改几行就行。2. TaoToken 前置准备Base URL、API Key 与 Model ID 三件套怎么拿claude code 默认走 Anthropic 官方接口但在国内网络环境下直接调用经常遇到连接问题。更稳妥的做法是使用兼容 Anthropic 协议的 API 网关把请求转发到可用的通道上。TaoToken 就是这样一个入口它提供与 Anthropic API 兼容的接口你只需要改 Base URL 和 Keyclaude code 的命令和配置基本不用动。先说清楚三件套是什么这是后面所有配置的基础Base URL 是接口地址TaoToken 的 API 入口是https://taotoken.net/api。注意这里不要加任何查询参数保持干净。API Key 是你的身份凭证在控制台里生成。每个 Key 可以单独命名方便区分用途比如“claude-code-本地”和“claude-code-CI”。Model ID 是你要调用的模型标识。claude code 里常用的有claude-sonnet-4-20250514这类复杂任务可以换更强的模型。具体可用列表以控制台展示为准不要凭记忆写。获取步骤不复杂打开https://taotoken.net/api-keys登录后创建一个新 Key复制保存。然后到https://taotoken.net/console确认账户状态和可用模型。如果你打算长期用 claude code 做编码和 Agent 任务可以看看https://taotoken.net/coding-plan里的方案比按量计费更适合高频使用。这里有个容易忽略的点claude code 读取配置的优先级是“环境变量 配置文件 默认值”。所以你可以用环境变量临时覆盖也可以写进 settings 文件持久化。我建议本地开发用环境变量团队共享用配置文件避免 Key 泄露到 git 里。配置前先确认 claude code 已安装。如果还没装执行npm install -g anthropic-ai/claude-code装完后运行claude --version确认版本。然后设置环境变量Linux/macOS 用 exportWindows PowerShell 用$env:export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的Key export ANTHROPIC_MODELclaude-sonnet-4-20250514Windows PowerShell$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEY你的Key $env:ANTHROPIC_MODELclaude-sonnet-4-20250514设置完不要急着跑先用claude auth status看一下当前认证状态。如果显示未登录或指向了旧地址说明环境变量没生效检查一下是不是在同一个终端窗口里执行的。3. 可复制配置CLAUDE.md 模板、settings.json 与 MCP 接入片段这一节是整篇的核心给你三份可以直接抄的配置。先建 CLAUDE.md再写 settings.json最后接 MCP。3.1 CLAUDE.md 模板在项目根目录创建CLAUDE.md内容按你的项目改。下面这份是我在多个仓库里迭代出来的通用版# 项目上下文 ## 技术栈 - 语言TypeScript 5.x / Node.js 20 - 框架React 18 Vite - 包管理pnpm禁止使用 npm install会破坏 lockfile - 测试Vitest Testing Library ## 目录结构 - src/componentsUI 组件每个组件一个目录 - src/hooks自定义 hooks - src/utils纯函数工具必须有单测 - src/api接口封装统一走 request.ts ## 编码规范 - 组件用函数式禁止 class 组件 - 样式用 CSS Modules文件名 *.module.css - 提交信息遵循 Conventional Commits ## 常用命令 - 安装依赖pnpm install - 启动开发pnpm dev - 跑测试pnpm test - 类型检查pnpm typecheck ## 注意事项 - 不要修改 pnpm-lock.yaml - 不要直接操作生产数据库 - 改完代码必须跑 pnpm typecheck 和 pnpm test这份文件的关键是“具体”。不要写“遵循最佳实践”这种空话要写“禁止 npm install”“必须跑 typecheck”。AI 读得越具体行为越可控。你也可以用/init让 claude 自动生成初稿然后手动补充。3.2 settings.json 配置片段claude code 的配置文件在~/.claude/settings.json全局或项目内.claude/settings.json项目级。项目级优先级更高适合团队共享。下面这份包含 Base URL、Key 引用和权限预设{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Bash(pnpm test), Bash(pnpm typecheck), Bash(git diff *) ], deny: [ Bash(rm -rf *), Bash(git push --force *) ] } }注意 Key 直接写进文件有泄露风险。更安全的做法是用环境变量引用settings.json 里只写ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}实际值放在 shell 的 profile 里。团队共享时把 settings.json 提交到 gitKey 用占位符每个人本地覆盖。3.3 MCP 接入片段MCP 是 Model Context Protocol让 claude code 能连接外部工具和数据源。配置命令是claude mcp add也可以直接写配置文件。下面以接入一个本地文件系统 MCP 为例claude mcp add filesystem -- npx -y modelcontextprotocol/server-filesystem /path/to/your/project这条命令做了三件事注册一个叫filesystem的 MCP server用 npx 启动对应的包把项目路径传进去。加完后用claude mcp list确认。如果你用的是 Cline 或 CC Switch 这类工具配置格式类似核心都是三件套Base URL 填https://taotoken.net/apiKey 填你的凭证Model ID 填可用模型。Codex 的auth.json也是同样逻辑把这三个值对应填进去即可。MCP 配置写完后重启 claude 会话才会生效。在 REPL 里输入/mcp可以查看当前连接的 server 和可用工具。4. 验证请求REPL 交互、命令速查与成功结果确认配置写完接下来跑一遍验证。这一步的目的是确认三件事claude 能启动、能读到 CLAUDE.md、能通过 TaoToken 正常请求模型。4.1 启动与基础验证在项目根目录执行claude进入 REPL 后先输入/help看命令列表再输入/context查看当前上下文。如果 CLAUDE.md 配置正确/context里应该能看到它的内容被加载。然后问一个和项目相关的问题比如“这个项目用什么包管理器”如果回答是 pnpm说明 CLAUDE.md 生效了。再验证 API 通道。输入/cost查看当前会话的 token 消耗如果有正常数字说明请求已经通过 TaoToken 走通了。如果显示 0 或报错回到第 5 节排查。4.2 常用命令速查REPL 内部命令按功能分几类下面这些是高频使用的会话与上下文类/clear清空当前上下文重新开始/compact压缩历史节省 token/context查看当前加载的上下文/cost看消耗/export导出对话/rewind回退到某个检查点。项目与记忆类/init生成或更新 CLAUDE.md/memory管理记忆文件/add-dir dir把额外目录纳入上下文。配置与诊断类/config打开配置/permissions管理工具权限/model切换模型/doctor检查运行环境/mcp查看 MCP 连接/debug读调试日志。代码审查类/diff看交互式 diff/review让 AI 审查改动/security-review做安全审查。启动参数里几个实用的claude -c继续上次会话claude -r 会话名按名称恢复claude -p 提示词打印模式执行一次就退出claude --add-dir ../lib加额外工作目录claude --model claude-sonnet-4-20250514指定模型。4.3 一次完整的成功请求在 REPL 里输入请读取 src/utils/format.ts解释它的导出函数并指出有没有边界情况没处理。正常的话claude 会先调用 Read 工具读取文件然后给出分析。你会看到工具调用记录和最终回答。如果它说“我无法读取文件”检查/permissions里 Read 是否被允许。再试一个带 shell 的! pnpm test!前缀会直接执行 shell 命令并把输出纳入上下文。如果测试通过输出会显示在会话里后续提问可以引用这些结果。管道模式也值得试cat package.json | claude -p 给这个项目加一个 dev:watch 脚本这条命令把 package.json 内容通过管道传给 claude让它基于实际内容给建议。-p表示打印模式执行完自动退出适合写进脚本。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth配置过程中最容易卡在几个报错上。下面按真实遇到的顺序列出来对照排查。5.1 401 Unauthorized这是最常见的。原因通常是 Key 没生效或写错了。检查顺序先echo $ANTHROPIC_API_KEY看环境变量有没有值再claude auth status看 claude 读到的认证状态。如果环境变量有值但 status 显示未认证可能是 settings.json 里的 Key 覆盖了环境变量或者 Key 本身失效了。到https://taotoken.net/api-keys重新生成一个替换后重启终端。还有一种情况是 Base URL 写成了带路径的形式比如https://taotoken.net/api/v1。claude code 会自己拼接路径你只需要填https://taotoken.net/api多写反而会 404 或 401。5.2 local proxy failed这个报错说明 claude 尝试走本地代理但连不上。检查你的 shell 里有没有设置HTTP_PROXY或HTTPS_PROXY环境变量。如果有先 unset 掉再试unset HTTP_PROXY HTTPS_PROXY然后确认ANTHROPIC_BASE_URL指向的是https://taotoken.net/api不是 localhost。如果你之前配过其他工具的代理可能残留了配置检查~/.claude/settings.json里有没有多余的 proxy 字段。5.3 reading choices 相关报错这个通常出现在模型返回格式不符合预期时比如你指定的 Model ID 不存在或拼错了。回到控制台确认可用模型列表把ANTHROPIC_MODEL改成正确的值。另外如果你在 settings.json 里同时写了model字段和环境变量可能冲突以环境变量为准把配置文件里的删掉。5.4 OAuth 相关报错claude code 支持 OAuth 登录但如果你用的是 API Key 模式就不需要走 OAuth。报错里出现 OAuth 通常是因为 claude 尝试用登录态而不是 Key。执行claude auth logout退出登录态然后确认环境变量里的 Key 生效。如果之前登录过 Anthropic 账号登录信息可能缓存在~/.claude/下清理后重新用 Key 认证。5.5 MCP 连接失败claude mcp list显示 server 但状态是 failed先手动跑一遍启动命令看 npx 包能不能正常下载。常见原因是网络问题导致 npx 拉包失败或者路径参数写错。把claude mcp add命令里的路径改成绝对路径再试。如果用的是需要 API Key 的 MCP server确认 Key 通过环境变量传进去了。排查完这些基本能覆盖 90% 的配置问题。剩下的看/doctor的输出它会给出环境检查的详细报告。6. 把工作流固定下来从模型对话到 Coding Plan 的接入路径配置跑通只是第一步真正省时间的是把它变成习惯。我的做法是每个新项目先跑/init生成 CLAUDE.md 初稿花五分钟补充技术栈和禁忌然后提交到 git。这样团队里任何人 clone 下来claude 都能立刻理解项目。日常使用中/compact要养成习惯。对话超过二三十轮后上下文会变重响应变慢、费用上升这时候压缩一下AI 会总结关键信息继续。/clear则用在切换任务时避免旧上下文干扰新问题。如果你需要验证某个模型的实际表现可以到https://taotoken.net/model-chat里直接对话测试确认模型可用性和响应质量后再写进配置。长期做编码和 Agent 任务的话https://taotoken.net/coding-plan里的方案比按量计费更划算适合每天都要用 claude code 的人。MCP 的扩展性值得多花点时间。除了文件系统还可以接数据库查询、API 文档、内部知识库。每接一个claude 能做的事就多一层。配置入口在https://taotoken.net/doc里有详细说明照着改参数就行。最后提醒一句权限配置不要图省事全开。--dangerously-skip-permissions这种选项只在完全可控的沙箱里用日常开发老老实实配 allow 和 deny 列表。CLAUDE.md 里写清楚“不要动生产数据库”“不要 force push”比事后补救强得多。