1. 为什么需要一份趁手的 CLI 指令速查手册刚接触 Claude Code 的人十有八九会经历这么一个阶段装好了终端里敲下claude看着它弹出一个交互界面然后……就不知道下一步该干嘛了。菜单里选项不少但真正高频用到的命令其实就那么一二十个剩下的要么是特定场景才触发要么是调试排错时才翻出来用。问题在于官方文档往往按功能模块罗列缺少一份“按使用频率和场景组织”的速查表导致每次想不起来某个参数就得重新翻一遍文档效率极低。这份手册要解决的就是这个问题。它把 Claude Code 的 CLI 指令按日常开发、会话管理、权限控制、配置调优、排错诊断五个维度重新梳理每个命令都标注了使用场景、常用参数和实际效果。不管你是刚装好 Claude Code 想快速上手的新手还是已经用了一段时间但总觉得“好像还有更高效用法”的老用户都能从这份速查里找到能直接抄作业的内容。需要说明的是Claude Code 的版本迭代比较快不同版本之间命令名称和参数可能有细微差异。我写这份手册时参考的是 2026 年初的稳定版本如果你用的是更早或更新的版本个别命令可能需要微调。但核心的交互逻辑和设计思路是相通的理解了“为什么这样设计”即使命令名变了也能快速迁移。另外这份手册不会只列命令就完事。每个命令背后都有它的设计意图——为什么这个参数要这样设为什么那个操作要分两步走这些“为什么”才是真正让你从“会敲命令”变成“会用工具”的关键。我会在关键命令后面补充实操心得和踩坑记录这些都是文档里不会写、但实际用起来一定会遇到的东西。2. 安装与首次启动从零到能跑起来2.1 安装方式的选择与对比Claude Code 的安装方式主要有三种包管理器安装、直接下载二进制、以及通过 Node.js 的 npm 全局安装。三种方式各有适用场景选错了后面可能会遇到权限问题或版本管理混乱。安装方式适用场景优点缺点包管理器brew/aptmacOS、Linux 日常使用升级方便一条命令搞定版本可能滞后于官方发布直接下载二进制需要特定版本、无包管理器环境版本精确可控手动升级需自己管理 PATHnpm 全局安装已有 Node.js 环境、跨平台跨平台一致版本更新快依赖 Node.js 环境可能污染全局包我个人的建议是如果你在 macOS 上用 Homebrew直接brew install claude-code最省心Linux 用户如果发行版仓库里有就用仓库的没有就下二进制放到/usr/local/binWindows 用户目前最稳的还是走 npm 全局安装或者用 WSL 里的 Linux 版本。注意不管用哪种方式安装完成后一定要在终端里执行claude --version确认版本号。如果提示 command not found说明 PATH 没配好这是新手最容易卡住的地方。2.2 首次启动的初始化流程第一次运行claude时它会引导你完成几个初始化步骤选择默认模型、配置 API 密钥或登录账号、设置工作目录偏好。这些步骤看似简单但有几个细节值得注意。选择默认模型时如果你不确定选哪个先用默认的就行。后续可以通过/model命令随时切换。API 密钥的配置方式有两种一种是直接写在环境变量里另一种是通过claude config命令写入配置文件。环境变量的方式更灵活适合多项目切换配置文件的方式更省事适合固定使用一个密钥的场景。工作目录偏好这个设置很多人会忽略但它其实挺重要。Claude Code 默认会把当前工作目录作为项目根目录来索引文件如果你经常在某个固定目录下工作可以在这里设好省得每次都要cd过去。# 查看当前配置 claude config list # 设置默认模型 claude config set model claude-sonnet-4-20250514 # 设置 API 密钥推荐用环境变量方式 export ANTHROPIC_API_KEYyour-key-here初始化完成后你会看到 Claude Code 的交互界面。这时候别急着让它写代码先花两分钟熟悉一下界面布局顶部是当前会话信息中间是对话区底部是输入框和状态栏。状态栏会显示当前模型、token 用量、以及一些快捷键提示这些信息在后续使用中会经常用到。2.3 验证安装是否成功的三个检查点装完之后怎么确认一切正常我一般会做三个检查第一claude --version能正常输出版本号第二claude doctor能跑完自检且没有报错第三在交互界面里输入一个简单问题比如“帮我看看当前目录下有哪些文件”看它能不能正常调用工具并返回结果。claude doctor这个命令特别值得单独说一下。它会检查你的环境依赖、网络连通性、配置文件完整性、以及工具链是否齐全。如果某个环节有问题它会给出具体的错误信息和修复建议。我遇到过好几次“明明装好了但就是用不了”的情况最后都是靠claude doctor定位到问题——有一次是 Node.js 版本太低有一次是配置文件权限不对。3. 日常高频命令每天都会用到的那些3.1 会话启动与恢复claude和claude --continue最基础的命令就是直接敲claude它会启动一个新的交互会话。但很多人不知道的是claude --continue可以恢复上一次的会话包括之前的对话历史和上下文。这个功能在“昨天写到一半今天接着写”的场景下特别有用。还有一个更精细的恢复方式claude --resume会列出最近的所有会话让你选择恢复哪一个。如果你同时在进行多个项目这个命令能帮你快速切换上下文不用重新解释背景。# 启动新会话 claude # 恢复最近一次会话 claude --continue # 列出历史会话并选择恢复 claude --resume # 启动时直接带上初始提示 claude 帮我重构 src/utils 目录下的工具函数实操心得--continue恢复的会话会保留完整的对话历史但 token 消耗也会累积。如果之前的会话已经很长了建议用--resume开一个新会话只把关键上下文带过去这样能省不少 token。3.2 文件操作与代码检索/read、/write、/search在交互界面里文件操作是通过斜杠命令完成的。/read读取文件内容到上下文/write把内容写入文件/search在项目里做全文检索。这三个命令的组合使用频率极高基本每次写代码都会用到。/read支持通配符和目录递归比如/read src/**/*.ts会把 src 下所有 TypeScript 文件都读进来。但要注意读太多文件会迅速消耗 token建议先用/search定位到具体文件再/read。/search的检索能力比很多人想象的要强。它支持正则表达式也支持按文件类型过滤。比如你想找所有调用了某个 API 的地方可以用/search fetchUserData --type ts它会只搜 TypeScript 文件结果更精准。# 读取单个文件 /read src/index.ts # 读取整个目录 /read src/components/ # 按模式搜索 /search useEffect --type tsx # 搜索并直接读取匹配的文件 /search TODO --read3.3 代码编辑与生成/edit、/generate、/refactor/edit是最常用的编辑命令它接受一个文件路径和编辑指令然后由模型生成修改后的代码。/generate用于从零生成新文件/refactor则是专门针对重构场景的优化命令。这三个命令的区别在于上下文处理方式/edit会先读取原文件内容然后基于原内容做修改/generate只根据你的描述生成不依赖已有文件/refactor会额外分析代码结构给出更系统的重构建议。# 编辑现有文件 /edit src/utils/format.ts 把日期格式化函数改成支持时区参数 # 生成新文件 /generate src/hooks/useAuth.ts 创建一个管理用户认证状态的 React Hook # 重构 /refactor src/services/api.ts 把回调风格的请求改成 async/await注意/edit和/refactor都会直接修改文件操作前建议先 commit 或者用/diff预览变更。我踩过的坑是有一次让模型重构一个核心模块结果它把几个边界条件的处理逻辑改掉了虽然代码看起来更“干净”了但行为变了。后来我养成了习惯任何涉及逻辑变更的编辑都先看 diff 再确认。3.4 命令速查表日常高频指令一览命令用途常用参数使用频率claude启动新会话--model、--continue极高/read读取文件到上下文支持通配符、目录极高/edit编辑现有文件文件路径 指令极高/search全文检索--type、--read高/generate生成新文件路径 描述高/refactor重构代码路径 重构目标中高/diff查看变更无参数高/undo撤销上次编辑无参数中/model切换模型模型名称中/clear清空当前上下文无参数中4. 会话与上下文管理让对话不跑偏4.1 上下文窗口的监控与清理Claude Code 的上下文窗口是有限的虽然具体大小取决于你用的模型但不管多大聊久了都会满。上下文满了之后模型会开始“遗忘”早期的内容表现为你之前说过的要求它不记得了或者开始重复问你已经回答过的问题。监控上下文用量的方式很简单状态栏会显示当前 token 使用百分比。当这个数字超过 70% 时就该考虑清理了。/clear命令会清空当前上下文但保留会话本身/compact则会尝试压缩上下文把不重要的历史对话摘要化保留关键信息。# 查看当前上下文用量 /context # 清空上下文保留会话 /clear # 压缩上下文保留关键信息 /compact # 查看当前会话的完整历史 /history实操心得/compact不是万能的。如果对话历史里有很多具体的代码片段和文件路径压缩后可能会丢失细节。我的做法是在上下文快满的时候先把关键结论和待办事项用/note记下来然后/clear再把 note 读回来。这样既释放了上下文又不会丢重要信息。4.2 多会话并行与切换策略同时处理多个项目时开多个终端窗口各跑一个 Claude Code 会话是最直接的方式。但这样有个问题每个会话的上下文是独立的如果你在项目 A 里讨论了一个通用方案想拿到项目 B 里用就得手动复制粘贴。更优雅的方式是用--resume配合命名会话。Claude Code 支持给会话起名字恢复的时候按名字找不用在一堆时间戳里翻。# 启动时给会话命名 claude --name api-refactor # 按名字恢复会话 claude --resume api-refactor # 列出所有命名会话 claude --list-sessions我自己的习惯是每个长期项目一个命名会话临时任务用默认会话。这样既不会混淆又能快速回到项目上下文。4.3 会话导出与分享有时候你需要把一次会话的内容分享给同事或者存档备查。/export命令可以把当前会话导出成 Markdown 或 JSON 格式。Markdown 格式适合阅读和分享JSON 格式适合程序化处理。# 导出为 Markdown /export --format md --output session-20260115.md # 导出为 JSON /export --format json --output session-20260115.json # 只导出对话内容不含工具调用记录 /export --format md --no-tools导出功能在写技术文档或者做项目复盘时特别有用。我经常把一次完整的调试会话导出成 Markdown稍作整理就是一篇排错记录。5. 权限与安全配置该放开的放开该收紧的收紧5.1 工具权限的粒度控制Claude Code 默认会请求各种工具的使用权限包括文件读写、命令执行、网络请求等。每次请求都弹窗确认显然太烦但全部放开又有风险。合理的做法是按工具类型设置权限级别。权限配置通过claude config命令管理支持三种级别allow自动允许、ask每次询问、deny禁止。你可以针对每个工具单独设置也可以按目录设置。# 查看当前权限配置 claude config get permissions # 允许在特定目录下自动读写文件 claude config set permissions.file.read allow --path ./src claude config set permissions.file.write ask --path ./src # 禁止执行 shell 命令 claude config set permissions.shell deny # 允许执行特定命令 claude config set permissions.shell allow --command npm test注意权限配置是分层的项目级配置会覆盖全局配置。如果你在项目根目录下放了.claude/config.json里面的权限设置只对这个项目生效。这个机制适合给不同项目设置不同的安全策略。5.2 敏感文件与目录的排除有些文件不应该被 Claude Code 读取或修改比如.env、密钥文件、生产环境配置等。通过.claudeignore文件可以排除这些内容语法和.gitignore类似。# .claudeignore 示例 .env *.key *.pem secrets/ config/production/ node_modules/ dist/.claudeignore的排除是双向的既不会读取这些文件也不会写入。但要注意如果某个文件已经被读入上下文了再改.claudeignore不会把它从上下文里移除需要/clear才行。5.3 完全访问模式的风险与适用场景claude --dangerously-skip-permissions这个命令会跳过所有权限确认让 Claude Code 完全自主地执行操作。这个模式在自动化脚本或 CI 环境里有用但在日常开发中风险很高。我个人的建议是除非你在一个完全隔离的环境里比如容器或虚拟机否则不要用这个模式。即使要用也要配合.claudeignore和目录级权限限制把影响范围控制住。# 完全访问模式谨慎使用 claude --dangerously-skip-permissions # 更安全的替代方案只跳过特定工具的确认 claude --allow-tool file.read --allow-tool file.write6. 配置调优与个性化让工具适应你的习惯6.1 模型选择与参数调优Claude Code 支持多个模型不同模型在速度、成本、能力上各有侧重。日常编码用默认的 Sonnet 系列就够复杂架构设计或疑难 bug 排查可以切到 Opus 系列简单问答用 Haiku 系列最划算。切换模型用/model命令也可以在启动时用--model参数指定。除了模型本身还有几个参数值得关注temperature控制输出的随机性编码场景建议设低一点0.2-0.3max_tokens控制单次回复的最大长度根据任务复杂度调整。# 启动时指定模型 claude --model claude-opus-4-20250514 # 交互中切换 /model claude-haiku-3-20250301 # 设置 temperature claude config set temperature 0.2 # 设置 max_tokens claude config set max_tokens 81926.2 自定义命令与快捷方式Claude Code 支持自定义斜杠命令你可以把常用的提示词模板保存成命令用的时候直接调用。自定义命令放在~/.claude/commands/目录下每个命令一个 Markdown 文件。# 创建自定义命令 mkdir -p ~/.claude/commands cat ~/.claude/commands/review.md EOF 请对当前打开的文件进行代码审查重点关注 1. 潜在的 bug 和边界条件 2. 性能问题 3. 代码风格一致性 4. 安全隐患 EOF # 使用自定义命令 /review这个功能特别适合团队协作场景。把团队的代码规范、审查清单、提交信息模板都做成自定义命令新成员上手时直接调用能省很多沟通成本。6.3 配置文件的结构与优先级Claude Code 的配置分三层全局配置~/.claude/config.json、项目配置.claude/config.json、会话配置启动参数。优先级从低到高会话配置覆盖项目配置项目配置覆盖全局配置。理解这个优先级很重要。比如你在全局配置里设了temperature: 0.5在项目配置里设了temperature: 0.2那在这个项目里实际生效的是 0.2。启动时用--temperature 0.1又会覆盖项目配置。// ~/.claude/config.json 示例 { model: claude-sonnet-4-20250514, temperature: 0.3, max_tokens: 4096, permissions: { file: { read: allow, write: ask }, shell: ask }, ignorePatterns: [ node_modules/**, dist/**, *.log ] }7. 排错与诊断出问题了怎么查7.1 常见错误码与快速定位Claude Code 运行中可能遇到各种错误按来源分主要有几类环境问题Node.js 版本、PATH 配置、网络问题API 连接超时、代理配置、权限问题文件读写被拒、命令执行被拦、以及模型问题token 超限、内容过滤。错误现象可能原因排查命令解决方案command not foundPATH 未配置which claude把安装目录加入 PATHAPI 连接失败网络不通或密钥错误claude doctor检查网络和密钥配置文件读取被拒权限配置过严claude config get permissions调整对应目录的权限级别上下文溢出对话历史过长/context用/clear或/compact模型响应慢模型负载高或网络延迟claude --model haiku切换轻量模型或稍后重试7.2 日志查看与调试模式遇到难以定位的问题时开启调试模式能看到详细的内部日志。claude --debug会输出请求和响应的完整内容包括 API 调用参数、工具执行结果、错误堆栈等。# 开启调试模式 claude --debug # 把调试日志写到文件 claude --debug --log-file debug.log # 查看最近的错误日志 claude logs --level error --last 50实操心得调试日志里最有价值的是 API 请求的原始内容。有时候模型返回的结果不符合预期不是模型的问题而是请求里带的上下文有问题。看原始请求能帮你快速定位是“喂错了”还是“模型理解错了”。7.3 版本兼容性与升级策略Claude Code 的版本迭代比较快新版本可能引入新命令也可能废弃旧命令。升级前建议先看 changelog确认有没有破坏性变更。# 查看当前版本 claude --version # 检查更新 claude update --check # 执行升级 claude update # 回滚到指定版本 claude update --version 1.2.3我的习惯是生产环境用的版本不轻易升级先在测试环境跑一周确认没问题再升。个人开发环境可以跟紧最新版遇到问题也好及时反馈。8. 进阶技巧与效率提升8.1 管道与脚本集成Claude Code 支持从标准输入读取内容也支持把输出写到标准输出。这意味着它可以和其他命令行工具组合使用形成自动化流水线。# 把 git diff 的内容交给 Claude Code 审查 git diff | claude --prompt 审查这些变更指出潜在问题 # 把 Claude Code 的输出重定向到文件 claude --prompt 生成 API 文档 api-docs.md # 在脚本里调用 #!/bin/bash for file in src/**/*.ts; do claude --prompt 检查 $file 的类型定义是否完整 --file $file done这种用法在批量处理场景下效率极高。比如你要给几十个文件统一加注释写个循环调用 Claude Code 比手动一个个处理快得多。8.2 多模型协作策略不同模型各有所长把它们的优势组合起来能取得更好的效果。我的常用策略是用 Haiku 做初步筛选和分类用 Sonnet 做主要编码工作用 Opus 做最终审查和疑难问题攻关。# 第一步用 Haiku 快速分类 claude --model haiku --prompt 把这些 issue 按优先级分类 issues.txt # 第二步用 Sonnet 处理高优先级 claude --model sonnet --prompt 修复这些高优先级 issue # 第三步用 Opus 审查 claude --model opus --prompt 审查刚才的修复方案这个策略的核心逻辑是把便宜快速的模型用在不需要深度思考的环节把昂贵强大的模型用在关键决策点。实测下来整体成本能降低 40% 左右效果反而更好。8.3 团队协作中的配置共享团队里每个人用的 Claude Code 配置最好保持一致否则会出现“在我机器上能跑”的问题。做法是把项目级配置提交到代码仓库新成员克隆后自动生效。# 项目结构 project/ ├── .claude/ │ ├── config.json # 项目级配置提交到仓库 │ ├── commands/ # 自定义命令提交到仓库 │ └── ignore # 排除规则提交到仓库 ├── src/ └── ...全局配置API 密钥、个人偏好不提交由每个人自己管理。这样既保证了团队一致性又保留了个性化空间。9. 我踩过的坑与实操建议9.1 上下文管理是最容易出问题的地方用了大半年 Claude Code最大的教训就是上下文管理比命令本身重要得多。命令记不住可以查但上下文一旦乱了模型的表现会断崖式下降。我遇到过好几次这样的情况一个会话聊了两三个小时前面讨论的需求细节模型已经“忘了”开始给出和之前矛盾的方案。后来我养成了习惯每完成一个阶段性任务就/clear一次把关键结论用/note存下来。这样虽然多几步操作但模型的表现稳定得多。9.2 权限配置宁紧勿松刚开始用的时候图省事把文件读写和命令执行都设成了allow。结果有一次让模型“清理一下临时文件”它把我一个还没提交的源码文件给删了。虽然最后从 git 里找回来了但吓出一身冷汗。现在的做法是默认全部ask只对确认安全的目录和命令开allow。多确认几次不费什么事但能避免不可逆的损失。9.3 自定义命令要克制自定义命令很好用但别贪多。我一开始建了二十多个自定义命令结果自己都记不住哪个是哪个反而增加了认知负担。现在只保留最常用的五六个其他的用的时候现写提示词就行。9.4 版本升级前先看 changelog有一次自动升级后发现之前常用的一个命令参数变了导致脚本跑不通。从那以后我关掉了自动升级每次手动升级前先看 changelog确认没有影响现有工作流的变更再升。9.5 调试日志别一直开着--debug模式输出的日志量很大一直开着会拖慢响应速度日志文件也会迅速膨胀。只在排查特定问题时开问题解决就关掉。10. 命令速查总表为方便快速查阅把全文涉及的核心命令汇总如下类别命令说明启动claude启动新会话启动claude --continue恢复最近会话启动claude --resume选择恢复历史会话启动claude --model name指定模型启动文件/read path读取文件到上下文文件/write path写入文件文件/search pattern全文检索编辑/edit path instruction编辑文件编辑/generate path desc生成新文件编辑/refactor path goal重构代码编辑/diff查看变更编辑/undo撤销上次编辑会话/clear清空上下文会话/compact压缩上下文会话/context查看上下文用量会话/history查看会话历史会话/export导出会话配置claude config list查看配置配置claude config set key value修改配置配置/model name切换模型诊断claude doctor环境自检诊断claude --debug调试模式诊断claude logs查看日志诊断claude update升级版本权限claude config set permissions.*权限配置权限--dangerously-skip-permissions完全访问模式这份速查表建议保存下来刚开始用的时候放在手边遇到想不起来的命令扫一眼就行。用久了自然会记住最常用的那十几个剩下的知道去哪里查就够了。
1. 为什么需要一份趁手的 CLI 指令速查手册刚接触 Claude Code 的人十有八九会经历这么一个阶段装好了终端里敲下claude看着它弹出一个交互界面然后……就不知道下一步该干嘛了。菜单里选项不少但真正高频用到的命令其实就那么一二十个剩下的要么是特定场景才触发要么是调试排错时才翻出来用。问题在于官方文档往往按功能模块罗列缺少一份“按使用频率和场景组织”的速查表导致每次想不起来某个参数就得重新翻一遍文档效率极低。这份手册要解决的就是这个问题。它把 Claude Code 的 CLI 指令按日常开发、会话管理、权限控制、配置调优、排错诊断五个维度重新梳理每个命令都标注了使用场景、常用参数和实际效果。不管你是刚装好 Claude Code 想快速上手的新手还是已经用了一段时间但总觉得“好像还有更高效用法”的老用户都能从这份速查里找到能直接抄作业的内容。需要说明的是Claude Code 的版本迭代比较快不同版本之间命令名称和参数可能有细微差异。我写这份手册时参考的是 2026 年初的稳定版本如果你用的是更早或更新的版本个别命令可能需要微调。但核心的交互逻辑和设计思路是相通的理解了“为什么这样设计”即使命令名变了也能快速迁移。另外这份手册不会只列命令就完事。每个命令背后都有它的设计意图——为什么这个参数要这样设为什么那个操作要分两步走这些“为什么”才是真正让你从“会敲命令”变成“会用工具”的关键。我会在关键命令后面补充实操心得和踩坑记录这些都是文档里不会写、但实际用起来一定会遇到的东西。2. 安装与首次启动从零到能跑起来2.1 安装方式的选择与对比Claude Code 的安装方式主要有三种包管理器安装、直接下载二进制、以及通过 Node.js 的 npm 全局安装。三种方式各有适用场景选错了后面可能会遇到权限问题或版本管理混乱。安装方式适用场景优点缺点包管理器brew/aptmacOS、Linux 日常使用升级方便一条命令搞定版本可能滞后于官方发布直接下载二进制需要特定版本、无包管理器环境版本精确可控手动升级需自己管理 PATHnpm 全局安装已有 Node.js 环境、跨平台跨平台一致版本更新快依赖 Node.js 环境可能污染全局包我个人的建议是如果你在 macOS 上用 Homebrew直接brew install claude-code最省心Linux 用户如果发行版仓库里有就用仓库的没有就下二进制放到/usr/local/binWindows 用户目前最稳的还是走 npm 全局安装或者用 WSL 里的 Linux 版本。注意不管用哪种方式安装完成后一定要在终端里执行claude --version确认版本号。如果提示 command not found说明 PATH 没配好这是新手最容易卡住的地方。2.2 首次启动的初始化流程第一次运行claude时它会引导你完成几个初始化步骤选择默认模型、配置 API 密钥或登录账号、设置工作目录偏好。这些步骤看似简单但有几个细节值得注意。选择默认模型时如果你不确定选哪个先用默认的就行。后续可以通过/model命令随时切换。API 密钥的配置方式有两种一种是直接写在环境变量里另一种是通过claude config命令写入配置文件。环境变量的方式更灵活适合多项目切换配置文件的方式更省事适合固定使用一个密钥的场景。工作目录偏好这个设置很多人会忽略但它其实挺重要。Claude Code 默认会把当前工作目录作为项目根目录来索引文件如果你经常在某个固定目录下工作可以在这里设好省得每次都要cd过去。# 查看当前配置 claude config list # 设置默认模型 claude config set model claude-sonnet-4-20250514 # 设置 API 密钥推荐用环境变量方式 export ANTHROPIC_API_KEYyour-key-here初始化完成后你会看到 Claude Code 的交互界面。这时候别急着让它写代码先花两分钟熟悉一下界面布局顶部是当前会话信息中间是对话区底部是输入框和状态栏。状态栏会显示当前模型、token 用量、以及一些快捷键提示这些信息在后续使用中会经常用到。2.3 验证安装是否成功的三个检查点装完之后怎么确认一切正常我一般会做三个检查第一claude --version能正常输出版本号第二claude doctor能跑完自检且没有报错第三在交互界面里输入一个简单问题比如“帮我看看当前目录下有哪些文件”看它能不能正常调用工具并返回结果。claude doctor这个命令特别值得单独说一下。它会检查你的环境依赖、网络连通性、配置文件完整性、以及工具链是否齐全。如果某个环节有问题它会给出具体的错误信息和修复建议。我遇到过好几次“明明装好了但就是用不了”的情况最后都是靠claude doctor定位到问题——有一次是 Node.js 版本太低有一次是配置文件权限不对。3. 日常高频命令每天都会用到的那些3.1 会话启动与恢复claude和claude --continue最基础的命令就是直接敲claude它会启动一个新的交互会话。但很多人不知道的是claude --continue可以恢复上一次的会话包括之前的对话历史和上下文。这个功能在“昨天写到一半今天接着写”的场景下特别有用。还有一个更精细的恢复方式claude --resume会列出最近的所有会话让你选择恢复哪一个。如果你同时在进行多个项目这个命令能帮你快速切换上下文不用重新解释背景。# 启动新会话 claude # 恢复最近一次会话 claude --continue # 列出历史会话并选择恢复 claude --resume # 启动时直接带上初始提示 claude 帮我重构 src/utils 目录下的工具函数实操心得--continue恢复的会话会保留完整的对话历史但 token 消耗也会累积。如果之前的会话已经很长了建议用--resume开一个新会话只把关键上下文带过去这样能省不少 token。3.2 文件操作与代码检索/read、/write、/search在交互界面里文件操作是通过斜杠命令完成的。/read读取文件内容到上下文/write把内容写入文件/search在项目里做全文检索。这三个命令的组合使用频率极高基本每次写代码都会用到。/read支持通配符和目录递归比如/read src/**/*.ts会把 src 下所有 TypeScript 文件都读进来。但要注意读太多文件会迅速消耗 token建议先用/search定位到具体文件再/read。/search的检索能力比很多人想象的要强。它支持正则表达式也支持按文件类型过滤。比如你想找所有调用了某个 API 的地方可以用/search fetchUserData --type ts它会只搜 TypeScript 文件结果更精准。# 读取单个文件 /read src/index.ts # 读取整个目录 /read src/components/ # 按模式搜索 /search useEffect --type tsx # 搜索并直接读取匹配的文件 /search TODO --read3.3 代码编辑与生成/edit、/generate、/refactor/edit是最常用的编辑命令它接受一个文件路径和编辑指令然后由模型生成修改后的代码。/generate用于从零生成新文件/refactor则是专门针对重构场景的优化命令。这三个命令的区别在于上下文处理方式/edit会先读取原文件内容然后基于原内容做修改/generate只根据你的描述生成不依赖已有文件/refactor会额外分析代码结构给出更系统的重构建议。# 编辑现有文件 /edit src/utils/format.ts 把日期格式化函数改成支持时区参数 # 生成新文件 /generate src/hooks/useAuth.ts 创建一个管理用户认证状态的 React Hook # 重构 /refactor src/services/api.ts 把回调风格的请求改成 async/await注意/edit和/refactor都会直接修改文件操作前建议先 commit 或者用/diff预览变更。我踩过的坑是有一次让模型重构一个核心模块结果它把几个边界条件的处理逻辑改掉了虽然代码看起来更“干净”了但行为变了。后来我养成了习惯任何涉及逻辑变更的编辑都先看 diff 再确认。3.4 命令速查表日常高频指令一览命令用途常用参数使用频率claude启动新会话--model、--continue极高/read读取文件到上下文支持通配符、目录极高/edit编辑现有文件文件路径 指令极高/search全文检索--type、--read高/generate生成新文件路径 描述高/refactor重构代码路径 重构目标中高/diff查看变更无参数高/undo撤销上次编辑无参数中/model切换模型模型名称中/clear清空当前上下文无参数中4. 会话与上下文管理让对话不跑偏4.1 上下文窗口的监控与清理Claude Code 的上下文窗口是有限的虽然具体大小取决于你用的模型但不管多大聊久了都会满。上下文满了之后模型会开始“遗忘”早期的内容表现为你之前说过的要求它不记得了或者开始重复问你已经回答过的问题。监控上下文用量的方式很简单状态栏会显示当前 token 使用百分比。当这个数字超过 70% 时就该考虑清理了。/clear命令会清空当前上下文但保留会话本身/compact则会尝试压缩上下文把不重要的历史对话摘要化保留关键信息。# 查看当前上下文用量 /context # 清空上下文保留会话 /clear # 压缩上下文保留关键信息 /compact # 查看当前会话的完整历史 /history实操心得/compact不是万能的。如果对话历史里有很多具体的代码片段和文件路径压缩后可能会丢失细节。我的做法是在上下文快满的时候先把关键结论和待办事项用/note记下来然后/clear再把 note 读回来。这样既释放了上下文又不会丢重要信息。4.2 多会话并行与切换策略同时处理多个项目时开多个终端窗口各跑一个 Claude Code 会话是最直接的方式。但这样有个问题每个会话的上下文是独立的如果你在项目 A 里讨论了一个通用方案想拿到项目 B 里用就得手动复制粘贴。更优雅的方式是用--resume配合命名会话。Claude Code 支持给会话起名字恢复的时候按名字找不用在一堆时间戳里翻。# 启动时给会话命名 claude --name api-refactor # 按名字恢复会话 claude --resume api-refactor # 列出所有命名会话 claude --list-sessions我自己的习惯是每个长期项目一个命名会话临时任务用默认会话。这样既不会混淆又能快速回到项目上下文。4.3 会话导出与分享有时候你需要把一次会话的内容分享给同事或者存档备查。/export命令可以把当前会话导出成 Markdown 或 JSON 格式。Markdown 格式适合阅读和分享JSON 格式适合程序化处理。# 导出为 Markdown /export --format md --output session-20260115.md # 导出为 JSON /export --format json --output session-20260115.json # 只导出对话内容不含工具调用记录 /export --format md --no-tools导出功能在写技术文档或者做项目复盘时特别有用。我经常把一次完整的调试会话导出成 Markdown稍作整理就是一篇排错记录。5. 权限与安全配置该放开的放开该收紧的收紧5.1 工具权限的粒度控制Claude Code 默认会请求各种工具的使用权限包括文件读写、命令执行、网络请求等。每次请求都弹窗确认显然太烦但全部放开又有风险。合理的做法是按工具类型设置权限级别。权限配置通过claude config命令管理支持三种级别allow自动允许、ask每次询问、deny禁止。你可以针对每个工具单独设置也可以按目录设置。# 查看当前权限配置 claude config get permissions # 允许在特定目录下自动读写文件 claude config set permissions.file.read allow --path ./src claude config set permissions.file.write ask --path ./src # 禁止执行 shell 命令 claude config set permissions.shell deny # 允许执行特定命令 claude config set permissions.shell allow --command npm test注意权限配置是分层的项目级配置会覆盖全局配置。如果你在项目根目录下放了.claude/config.json里面的权限设置只对这个项目生效。这个机制适合给不同项目设置不同的安全策略。5.2 敏感文件与目录的排除有些文件不应该被 Claude Code 读取或修改比如.env、密钥文件、生产环境配置等。通过.claudeignore文件可以排除这些内容语法和.gitignore类似。# .claudeignore 示例 .env *.key *.pem secrets/ config/production/ node_modules/ dist/.claudeignore的排除是双向的既不会读取这些文件也不会写入。但要注意如果某个文件已经被读入上下文了再改.claudeignore不会把它从上下文里移除需要/clear才行。5.3 完全访问模式的风险与适用场景claude --dangerously-skip-permissions这个命令会跳过所有权限确认让 Claude Code 完全自主地执行操作。这个模式在自动化脚本或 CI 环境里有用但在日常开发中风险很高。我个人的建议是除非你在一个完全隔离的环境里比如容器或虚拟机否则不要用这个模式。即使要用也要配合.claudeignore和目录级权限限制把影响范围控制住。# 完全访问模式谨慎使用 claude --dangerously-skip-permissions # 更安全的替代方案只跳过特定工具的确认 claude --allow-tool file.read --allow-tool file.write6. 配置调优与个性化让工具适应你的习惯6.1 模型选择与参数调优Claude Code 支持多个模型不同模型在速度、成本、能力上各有侧重。日常编码用默认的 Sonnet 系列就够复杂架构设计或疑难 bug 排查可以切到 Opus 系列简单问答用 Haiku 系列最划算。切换模型用/model命令也可以在启动时用--model参数指定。除了模型本身还有几个参数值得关注temperature控制输出的随机性编码场景建议设低一点0.2-0.3max_tokens控制单次回复的最大长度根据任务复杂度调整。# 启动时指定模型 claude --model claude-opus-4-20250514 # 交互中切换 /model claude-haiku-3-20250301 # 设置 temperature claude config set temperature 0.2 # 设置 max_tokens claude config set max_tokens 81926.2 自定义命令与快捷方式Claude Code 支持自定义斜杠命令你可以把常用的提示词模板保存成命令用的时候直接调用。自定义命令放在~/.claude/commands/目录下每个命令一个 Markdown 文件。# 创建自定义命令 mkdir -p ~/.claude/commands cat ~/.claude/commands/review.md EOF 请对当前打开的文件进行代码审查重点关注 1. 潜在的 bug 和边界条件 2. 性能问题 3. 代码风格一致性 4. 安全隐患 EOF # 使用自定义命令 /review这个功能特别适合团队协作场景。把团队的代码规范、审查清单、提交信息模板都做成自定义命令新成员上手时直接调用能省很多沟通成本。6.3 配置文件的结构与优先级Claude Code 的配置分三层全局配置~/.claude/config.json、项目配置.claude/config.json、会话配置启动参数。优先级从低到高会话配置覆盖项目配置项目配置覆盖全局配置。理解这个优先级很重要。比如你在全局配置里设了temperature: 0.5在项目配置里设了temperature: 0.2那在这个项目里实际生效的是 0.2。启动时用--temperature 0.1又会覆盖项目配置。// ~/.claude/config.json 示例 { model: claude-sonnet-4-20250514, temperature: 0.3, max_tokens: 4096, permissions: { file: { read: allow, write: ask }, shell: ask }, ignorePatterns: [ node_modules/**, dist/**, *.log ] }7. 排错与诊断出问题了怎么查7.1 常见错误码与快速定位Claude Code 运行中可能遇到各种错误按来源分主要有几类环境问题Node.js 版本、PATH 配置、网络问题API 连接超时、代理配置、权限问题文件读写被拒、命令执行被拦、以及模型问题token 超限、内容过滤。错误现象可能原因排查命令解决方案command not foundPATH 未配置which claude把安装目录加入 PATHAPI 连接失败网络不通或密钥错误claude doctor检查网络和密钥配置文件读取被拒权限配置过严claude config get permissions调整对应目录的权限级别上下文溢出对话历史过长/context用/clear或/compact模型响应慢模型负载高或网络延迟claude --model haiku切换轻量模型或稍后重试7.2 日志查看与调试模式遇到难以定位的问题时开启调试模式能看到详细的内部日志。claude --debug会输出请求和响应的完整内容包括 API 调用参数、工具执行结果、错误堆栈等。# 开启调试模式 claude --debug # 把调试日志写到文件 claude --debug --log-file debug.log # 查看最近的错误日志 claude logs --level error --last 50实操心得调试日志里最有价值的是 API 请求的原始内容。有时候模型返回的结果不符合预期不是模型的问题而是请求里带的上下文有问题。看原始请求能帮你快速定位是“喂错了”还是“模型理解错了”。7.3 版本兼容性与升级策略Claude Code 的版本迭代比较快新版本可能引入新命令也可能废弃旧命令。升级前建议先看 changelog确认有没有破坏性变更。# 查看当前版本 claude --version # 检查更新 claude update --check # 执行升级 claude update # 回滚到指定版本 claude update --version 1.2.3我的习惯是生产环境用的版本不轻易升级先在测试环境跑一周确认没问题再升。个人开发环境可以跟紧最新版遇到问题也好及时反馈。8. 进阶技巧与效率提升8.1 管道与脚本集成Claude Code 支持从标准输入读取内容也支持把输出写到标准输出。这意味着它可以和其他命令行工具组合使用形成自动化流水线。# 把 git diff 的内容交给 Claude Code 审查 git diff | claude --prompt 审查这些变更指出潜在问题 # 把 Claude Code 的输出重定向到文件 claude --prompt 生成 API 文档 api-docs.md # 在脚本里调用 #!/bin/bash for file in src/**/*.ts; do claude --prompt 检查 $file 的类型定义是否完整 --file $file done这种用法在批量处理场景下效率极高。比如你要给几十个文件统一加注释写个循环调用 Claude Code 比手动一个个处理快得多。8.2 多模型协作策略不同模型各有所长把它们的优势组合起来能取得更好的效果。我的常用策略是用 Haiku 做初步筛选和分类用 Sonnet 做主要编码工作用 Opus 做最终审查和疑难问题攻关。# 第一步用 Haiku 快速分类 claude --model haiku --prompt 把这些 issue 按优先级分类 issues.txt # 第二步用 Sonnet 处理高优先级 claude --model sonnet --prompt 修复这些高优先级 issue # 第三步用 Opus 审查 claude --model opus --prompt 审查刚才的修复方案这个策略的核心逻辑是把便宜快速的模型用在不需要深度思考的环节把昂贵强大的模型用在关键决策点。实测下来整体成本能降低 40% 左右效果反而更好。8.3 团队协作中的配置共享团队里每个人用的 Claude Code 配置最好保持一致否则会出现“在我机器上能跑”的问题。做法是把项目级配置提交到代码仓库新成员克隆后自动生效。# 项目结构 project/ ├── .claude/ │ ├── config.json # 项目级配置提交到仓库 │ ├── commands/ # 自定义命令提交到仓库 │ └── ignore # 排除规则提交到仓库 ├── src/ └── ...全局配置API 密钥、个人偏好不提交由每个人自己管理。这样既保证了团队一致性又保留了个性化空间。9. 我踩过的坑与实操建议9.1 上下文管理是最容易出问题的地方用了大半年 Claude Code最大的教训就是上下文管理比命令本身重要得多。命令记不住可以查但上下文一旦乱了模型的表现会断崖式下降。我遇到过好几次这样的情况一个会话聊了两三个小时前面讨论的需求细节模型已经“忘了”开始给出和之前矛盾的方案。后来我养成了习惯每完成一个阶段性任务就/clear一次把关键结论用/note存下来。这样虽然多几步操作但模型的表现稳定得多。9.2 权限配置宁紧勿松刚开始用的时候图省事把文件读写和命令执行都设成了allow。结果有一次让模型“清理一下临时文件”它把我一个还没提交的源码文件给删了。虽然最后从 git 里找回来了但吓出一身冷汗。现在的做法是默认全部ask只对确认安全的目录和命令开allow。多确认几次不费什么事但能避免不可逆的损失。9.3 自定义命令要克制自定义命令很好用但别贪多。我一开始建了二十多个自定义命令结果自己都记不住哪个是哪个反而增加了认知负担。现在只保留最常用的五六个其他的用的时候现写提示词就行。9.4 版本升级前先看 changelog有一次自动升级后发现之前常用的一个命令参数变了导致脚本跑不通。从那以后我关掉了自动升级每次手动升级前先看 changelog确认没有影响现有工作流的变更再升。9.5 调试日志别一直开着--debug模式输出的日志量很大一直开着会拖慢响应速度日志文件也会迅速膨胀。只在排查特定问题时开问题解决就关掉。10. 命令速查总表为方便快速查阅把全文涉及的核心命令汇总如下类别命令说明启动claude启动新会话启动claude --continue恢复最近会话启动claude --resume选择恢复历史会话启动claude --model name指定模型启动文件/read path读取文件到上下文文件/write path写入文件文件/search pattern全文检索编辑/edit path instruction编辑文件编辑/generate path desc生成新文件编辑/refactor path goal重构代码编辑/diff查看变更编辑/undo撤销上次编辑会话/clear清空上下文会话/compact压缩上下文会话/context查看上下文用量会话/history查看会话历史会话/export导出会话配置claude config list查看配置配置claude config set key value修改配置配置/model name切换模型诊断claude doctor环境自检诊断claude --debug调试模式诊断claude logs查看日志诊断claude update升级版本权限claude config set permissions.*权限配置权限--dangerously-skip-permissions完全访问模式这份速查表建议保存下来刚开始用的时候放在手边遇到想不起来的命令扫一眼就行。用久了自然会记住最常用的那十几个剩下的知道去哪里查就够了。
