在终端里跑AI编程工具这事儿，我一开始是抵触的，总觉得图形界面才是生产力，命令行敲来敲去太费劲。直到我把Claude Code完整跑完一个中型项目重构之后，这个偏见被彻底击碎了——它不只是一个聊天框，而是一个能直接读目录、改文件、跑命令、看报错的AI工程师。这篇《Claude Code从入门到精通》手册，就是基于我这几个月高频使用总结出来的东西，从最基础的安装开始，到VSCode集成、权限模式、Skills扩展，再到用CCSwitch切换DeepSeek模型这些进阶操作，全都揉碎了讲。不管你是第一次听说这个词的纯小白，还是已经被各种权限确认搞得心烦的老手，都能在这里找到对应的章节直接用。
这份手册我顺手做成了可下载的PDF和Markdown版本，里面除了本文所有内容，还额外加了常用命令速查表和报错对照表，下载方式放在最后一节，懒得找可以直接翻过去拿。
1. Claude Code到底是什么？为什么值得折腾它
1.1 一个长在终端里的AI工程师
Claude Code是Anthropic推出的一款命令行AI编程工具，本质上是把一个大语言模型直接塞进了你的开发环境里。它不依赖于某个IDE插件，而是独立运行在终端中，通过读取你的项目文件、执行Shell命令、调用各种开发工具来完成编程任务。与传统“问一句答一句”的AI助手相比，它的核心差异在于具备完整的工具调用能力：它可以列出目录结构、读取特定文件、定位报错位置、自动修改多个文件，甚至在得到授权后直接运行构建、测试等命令。
我用一个生活化的类比来解释：普通AI助手就像你身边有个经验丰富但只能动嘴的顾问，你问什么他答什么；Claude Code则像一个真正坐在你工位旁边的工程师，你说一下目标，他会自己翻代码、自己敲键盘、自己跑测试，然后告诉你有问题需要拍板。这个“动手指改代码”和“动嘴皮子讲方案”的差别，就是质变所在。
1.2 它和Copilot、Codex这类工具差在哪
很多读者一定用过GitHub Copilot，也听说过OpenAI Codex。Claude Code和它们确实有重叠，但定位和交互方式差异挺大：
| 对比维度 | GitHub Copilot | OpenAI Codex | Claude Code |
|---|---|---|---|
| 运行形态 | IDE插件 | 云端环境/插件 | 终端CLI为主 |
| 核心交互 | 补全、聊天 | 对话生成代码 | 对话+自主执行任务 |
| 文件操作 | 需要插件辅助 | 部分支持 | 原生支持读写项目文件 |
| 命令执行 | 不直接执行 | 云端执行 | 本地终端直接执行 |
| 适合场景 | 日常补全加速 | 生成独立脚本 | 整项目改造、调试、重构 |
当然这不是说某个工具绝对更好，而是各有侧重点。Claude Code最激进的地方在于它默认信任你可以给它“动手权”，让AI真正成为开发工作流里的执行者，而不是建议者。这个定位在开源社区里引发了大量二次开发热情，这也是为什么会有“Claude Code接DeepSeek”“Claude Code挂Skills”这类玩法层出不穷。
1.3 什么样的人适合花时间学它
如果你是以下几类人，Claude Code大概率值得你折腾：第一类是日常在终端里工作超过一半时间的开发者，比如长期用Vim、Neovim、tmux的人，Claude Code和这套工具链天然协同；第二类是经常接手陌生项目的程序员，让AI先读代码、画结构图、找异常逻辑，能省掉大量“考古”时间；第三类是搞自动化脚本和DevOps的人，Claude Code在“写脚本-执行-根据报错修脚本”这个循环里表现非常稳定。
反过来，如果你只喜欢在IDE里点鼠标，或者对命令行有很强的抗拒心理，可以先用它的桌面版或VSCode扩展过渡，不必一上来就强迫自己完全切换到终端。但说实话，命令行模式下才是它能力释放最完整的形态，这个适应成本值得付。
2. 安装前的准备：三件事没搞清会卡半天
2.1 先确认Node.js环境版本
Claude Code的安装方式多种多样，但大多数路径都绕不开Node.js和npm。官方要求Node.js版本建议在18.0以上，实测下来20.x和22.x都很稳，低于16的旧版本基本装不上或者装上就跑不了。如果你本机还没有Node环境，我建议直接用nvm（Node Version Manager）安装，不要手动去官网下载安装包——nvm可以随时切换Node版本，后面踩到兼容性问题时你会感谢这个决定。
安装nvm之后再装Node：
# 安装nvm后，重新打开终端让命令生效 nvm install 20 nvm use 20 node -v npm -v这里有个很常见的坑：很多人装完Node发现npm -v报错，十有八九是nvm初始化脚本没有正确写入shell配置。检查一下~/.bashrc或~/.zshrc里是否有nvm相关的加载行，没有的话手动加上再source一次。
2.2 账号与鉴权：登录方式提前想清楚
Claude Code启动时需要一个身份凭证。目前主流方式有两种：一种是使用Claude账号直接登录，启动后它会提示你去浏览器完成授权；另一种是在环境变量里配置API Key，这种方式更适合自动化脚本和服务器场景。
如果你打算接第三方模型（比如DeepSeek），那么账号登录就暂时用不上了，你需要配置的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个环境变量。具体配置方法我在第五章详细讲。这里只提醒一句：API Key一定不要写进项目代码里，更不要提交到Git仓库，这是从第一天就该养成的习惯。
2.3 安装方式怎么选：npm、安装脚本还是桌面版
Claude Code目前有几种安装入口：最常见的是npm全局包安装，命令简洁、升级方便，适合绝大多数人；官方还提供了安装脚本，适用于不想装Node.js的环境；此外还有桌面版客户端，适合可视化操作。从我实际体验看，npm方式最省心，卸载也干净，所以下文主要以npm安装为主线，其他方式作为备用方案介绍。
3. 全平台安装实操：Windows、macOS、Ubuntu一条龙
3.1 Windows上两种靠谱的装法
Windows环境下的安装其实没想象中复杂。前提是先把Node.js装好，然后打开PowerShell（管理员权限不是必须的，但如果装全局包时报权限错误，就需要管理员窗口）执行：
npm install -g @anthropic-ai/claude-code装完之后新开一个终端，输入claude --version，能输出版本号就说明成功了。这里有个Windows特有的坑：如果你用的是PowerShell，执行外部命令报“无法加载claude”或“npm.ps1无法运行”，多半是脚本执行策略限制。解决办法是用管理员身份执行：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser如果你不想折腾终端，还可以直接下载官方桌面版安装包。桌面版的交互界面更友好，适合刚开始接触的人，但底层能力和CLI版是同一个引擎，所以不影响后面照着这份手册练习。
3.2 macOS和Ubuntu：命令几乎一样，注意权限
macOS只要装好了Node.js，直接在终端执行：
sudo npm install -g @anthropic-ai/claude-codeUbuntu和Debian系Linux也是同样的命令。用sudo的原因很简单：npm全局安装目录通常需要root权限。如果你不想用sudo，可以修改npm的全局前缀到自己的用户目录：
npm config set prefix ~/.npm-global echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc npm install -g @anthropic-ai/claude-code实测下来，Ubuntu 20.04和22.04都能顺利跑通，唯一要留意的是系统自带的Node版本太老，建议用nvm装新的Node再操作，否则会碰到各种奇怪的依赖报错。
3.3 VSCode里配置Claude Code：让IDE和终端无缝配合
很多人想把Claude Code嵌进VSCode里用，这个需求太常见了。实现方式很简单：先安装VSCode官方市场里的“Claude Code”扩展，安装完成后左侧边栏会出现Claude面板，可以直接在IDE里开对话、看文件变动；同时你依然可以在VSCode集成终端里直接敲claude命令启动CLI版。扩展和CLI共享同一个项目目录上下文，不需要重复授权。
配置VSCode时我建议改两个设置：一是把默认终端设置为bash或PowerShell都行，但一定要确保和nvm环境兼容；二是在settings.json里给Claude Code配置好PATH环境变量，否则在图形界面里启动时可能会找不到claude命令：
{ "terminal.integrated.env.linux": { "PATH": "/home/你的用户名/.nvm/versions/node/v20.11.1/bin:${env:PATH}" }, "terminal.integrated.env.osx": { "PATH": "${HOME}/.nvm/versions/node/v20.11.1/bin:${env:PATH}" } }3.4 安装完成后的验证与日常更新
安装完成后，先跑一次claude命令，第一次启动会问你是否登录。登录成功后你会看到一个交互式终端界面，输入/status能看到当前版本和会话状态。日常更新也很简单：
npm update -g @anthropic-ai/claude-codeClaude Code的版本迭代速度比我用过的任何开发工具都快，有时候一周能更新两三次。新版本往往伴随着命令变化和bug修复，遇到怪问题时先检查一下是不是版本太旧，经常能省掉半天排查时间。
4. 核心使用手册：从第一条命令到顺手的工作流
4.1 第一次启动该做什么：/help、/init、/status
启动后在交互提示符下输入/help，你会看到一长串内置命令。刚上手的人我建议只记三个：/init用于让Claude Code读取项目结构并生成初始索引，相当于给它画一张项目地图；/status用于查看当前会话和文件状态；/clear用于清理上下文重开会话。
特别说一下/init的作用：Claude Code不是靠模型瞎猜来理解项目的，它需要扫描目录结构、读取关键配置、识别代码语言，这个过程叫上下文构建。如果跳过/init直接让它干活，它也能响应，但可能会忽略项目原有的代码规范、忽略某些关键目录，导致给出的代码风格和项目格格不入。所以每到一个新项目，第一件事永远是/init。
4.2 高频命令速查：我标注了使用场景
下面这张表是我在实际开发中使用频率最高的命令，后面对应的场景说明都来自真实项目记录：
| 命令 | 作用 | 我的使用场景 |
|---|---|---|
/help | 显示全部命令 | 不确定某个命令时先翻一遍 |
/init | 初始化项目上下文 | 进入新仓库第一件事 |
/status | 查看会话与文件状态 | 长时间任务后确认进度 |
/clear | 清空上下文 | 聊偏了之后就重置 |
/config | 查看和修改配置 | 改权限模式、改思考等级 |
/cost | 查看token消耗 | 评估一次任务花了多少量 |
/undo | 回滚最近一次文件改动 | AI改坏代码时的后悔药 |
/model | 切换模型 | 简单任务用小模型提速 |
/vim | 切换vim模式 | 在终端输入太麻烦时启用 |
这个列表别急着一次背完，第一次打开/help对着看一遍，用一天后再回来看，自然就记住了。
4.3 权限模式：怎么避开每一次都弹确认的麻烦
Claude Code为了安全，默认情况下每执行一条外部命令都会弹一次确认框，这在初期很烦人。它提供几种权限模式：
默认模式：每次执行Shell命令都要按y确认，适合刚上手时观察它准备干什么。acceptEdits模式：自动接收文件编辑，但执行命令仍需确认。plan模式：只生成计划不落地执行，适合复杂需求先过一遍思路。auto模式：完全自动执行，适合在可信项目里跑批量任务。
你可以直接输入下面这句来切换：
/权限 auto或者用命令参数在启动时指定：
claude --permission-mode acceptEdits我自己的习惯是：在独立分支或测试项目里开auto模式，在主分支上保持acceptEdits。给AI过大的权限有一个隐藏风险是它会连着执行一串命令，中间如果某个命令跑了很久，你想中断都不知道从哪里下手。所以就算不怕它乱来，也别轻易在核心项目上开auto。
4.4 思考等级与Workflows：把AI的“深思熟虑”调到顶配
Claude Code近期的版本支持调整思考等级，我实测在复杂重构任务里，把思考等级调高之后，AI给出的方案质量明显提升。调整入口在/config配置菜单里，找到thinking相关选项，从默认调到high甚至xhigh。简单说：
- 低等级：响应快，适合查文档、解释代码、生成一次性小脚本。
- 默认等级：日常开发平衡点。
- 高等级/最高等级：适合多文件重构、性能优化、架构分析这类需要长链条推理的任务。
再配合Workflows功能，可以把“分析需求-制定方案-分步实施-自测验证”这个过程固化下来。我的做法是在项目根目录放一个workflows目录，里面写好各种任务的执行模板，比如“修bug工作流”包含：定位报错、读取相关文件、找出根因、最小化改动、回归测试。启动后我只需要把报错粘贴过去，Claude会按模板顺序执行，这比每次都现场口述需求高效得多。
5. 进阶玩法：把Claude Code变成你的专属模型工作台
5.1 Skills是什么？如何手动安装GitHub上的Skills
Skills机制本质上是给Claude Code装“专业技能包”。它不像插件那样是一堆代码，而是一个个带说明文档的指令集，里面封装了某个领域的最佳实践。官方仓库和社区里有各种现成Skills，比如代码评审、SQL优化、Dockerfile检查、Git提交规范等。安装方式非常直接，就是把对应目录放到Claude Code的skills目录下。
手动安装的完整步骤是这样的：先确认你的Claude配置目录位置，Linux和macOS一般在~/.claude，Windows是%USERPROFILE%\.claude。在配置目录下创建skills文件夹，然后从GitHub上把Skill仓库克隆进去或者直接复制对应的技能文件夹：
mkdir -p ~/.claude/skills cd ~/.claude/skills git clone https://github.com/某用户/某-skill.git装完之后重启会话，在对话里输入/context或者/help就能看到新技能是否被加载。我踩过的坑是：有些人直接clone整个仓库而不是clone里面对应的skill子目录，导致Claude Code识别不到SKILL.md文件。安装后务必确认目录结构是skills/技能名/SKILL.md，这一步错了技能就是无效的。
5.2 接入DeepSeek：用CCSwitch切换两种模型
社区里关于“Claude Code接DeepSeek”的讨论特别多，原因很简单：DeepSeek的API价格实惠，而且它的reasoner模型在复杂推理上口碑很好。最顺手的工具是CCSwitch，它本质上是一个配置切换器，可以让你在多个模型供应商之间快速切换，不用每次手动改环境变量。
先把DeepSeek接入所需的环境变量准备好：
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic export ANTHROPIC_API_KEY=你的DeepSeek密钥 export ANTHROPIC_MODEL=deepseek-chat这样Claude Code的请求就会走DeepSeek的接口。DeepSeek有两类常用模型，deepseek-chat响应快，适合日常对话和简单编码；deepseek-reasoner是推理增强版，适合复杂问题。用CCSwitch你就可以提前把这两个模型配置成两个预设档位，切换时一行命令搞定：
ccswitch use deepseek-reasoner ccswitch use deepseek-chat我个人的使用习惯是写业务代码时用deepseek-chat，调bug和设计架构时切到deepseek-reasoner。需要留意的是，接第三方模型后集成能力不受影响，Skills、Workflows照常工作，但不同模型对指令的遵循程度有差异，同一个workflow在切换模型后效果可能会有波动，需要微调提示词。
5.3 用Shell脚本把Claude Code嵌进日常工作流
Claude Code本身支持非交互模式，这让我经常把它当“脚本化AI”用。非交互模式就是通过claude -p "你的指令"直接执行一次任务并输出结果，适合集成到各种自动化流程里。比如每天上班第一件事跑一遍测试并让AI检查失败用例，可以写成：
claude -p "读取test目录下的失败日志，分析失败原因，给出修复建议，输出一份markdown报告" --output-format text > daily-report.md这个模式在CI/CD里也很有用，比如代码合并前自动跑一轮Code Review。不过注意非交互模式下默认不会主动改文件，想让它自动修东西需要显式加上相应权限参数，这个我在实际操作中踩过坑，不加权限它只会给建议不动手。
6. 卸载、更新与常见问题排查实录
6.1 干净卸载其实比安装讲究
有很多人问怎么卸载Claude Code，这个看起来简单，其实有两层意思：卸载程序本身和清理残留配置。如果用npm安装，执行反安装命令就能删掉程序主体：
npm uninstall -g @anthropic-ai/claude-code但配置文件、会话记录、Skills这些默认不会跟着一起删，它们存在~/.claude目录（Windows是%USERPROFILE%\.claude）。如果你想连历史会话和Skill一起清掉，手动删这个目录即可。如果你接过DeepSeek等第三方模型，记得把环境变量里的ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_MODEL一并清理，否则卸载后打开终端还会看到这些变量。
6.2 高频报错速查表：照着抄答案
在我使用和帮读者解决问题的过程中，最常见的问题其实非常集中，我整理成了一张对照表，照顺序排查基本十分钟内能解决：
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 输入claude提示找不到命令 | npm全局目录不在PATH | 检查npm prefix并加入PATH |
启动后提示unable to connect to Anthropic | 网络策略/服务不可达/API端点配置错误 | 检查环境变量是否设了错误URL；确认出网白名单是否放行api.anthropic.com或对应API域名 |
| 登录授权反复失败 | 系统时间偏差/浏览器缓存 | 校准系统时间、换个浏览器授权 |
| 对话时AI总是“答非所问” | 上下文被污染/项目结构没初始化 | 先/clear，再/init重建上下文 |
| 文件改了但一直停在“已确认”状态不动 | 权限模式限制 | 切换为acceptEdits或auto |
| 接上DeepSeek后报401 | API Key无效或URL路径不对 | 核对key；确认URL末尾是否带/anthropic |
| 更新到新版后原配置失效 | 配置格式升级 | 重新跑/config逐项确认，必要时重置配置 |
6.3 几个没人提醒但迟早会踩的坑
第一个坑是在仓库里直接开auto权限模式并让它执行包管理器命令。Claude Code可能自作主张装了一堆依赖，而这些依赖可能与你的项目版本冲突。我的建议是给它设一个专门的沙箱分支进行高风险操作，出问题直接丢弃分支。
第二个坑是无限扩大的上下文。每次会话都是有token上限的，长session聊到后面它会把早期内容忘掉，表现就是“明明已经交代过的事情又开始重复问”。解决方法是长任务拆短任务，每个会话聚焦一件事，做完就/clear。
第三个坑是模型切换后工作流“变笨了”。这个问题在接第三方模型后尤其明显，因为不同模型的指令遵循能力不一样。我在5.2里提过，这里再强调一次：换模型后务必跑一遍你的核心workflow试水，别想当然认为所有模型表现一样，这会省掉很多尴尬时刻。
7. 《Claude Code从入门到精通》手册内容与下载
7.1 手册里到底有什么
为了让这份指南能在脱离文章后依然可用，我把内容整理成了《Claude Code从入门到精通》手册，它在文章基础上做了三样增量优化：第一，把基础命令拆成一张A4纸速查表，适合打印出来贴显示器边上；第二，新增了“报错信息-排查路径”对照表，每条都是我实际跑出来的经验记录；第三，补上了10个可直接复用的Workflows配置模板，包括需求分析、代码审查、Bug修复、自动化测试等高频场景。
手册的目录结构是这样的：
claude-code-handbook/ ├── README.md # 使用说明与FAQ ├── handbook.pdf # 整册合订PDF，适合阅读 ├── cheatsheet/ │ └── command-quick-ref.md # 常用命令速查表 ├── troubleshooting/ │ └── error-mapping-table.md # 报错对照表 └── workflows/ ├── bug-fix.md ├── code-review.md ├── requirement-analysis.md └── auto-test.md7.2 下载方式与更新节奏
手册的下载入口放在项目仓库的Releases页面，找最新release下的claude-code-handbook.pdf和claude-code-handbook-md.zip两个资产即可。仓库目录下也能直接在线看各个Markdown文件，不下载也能用。更新节奏方面，我计划跟随Claude Code的大版本迭代来更新，每次官方有命令、参数或行为层面的明显变化，我就会同步修订对应页面。
7.3 使用建议：别把手册当小说读
拿到手册之后，我建议你的打开方式是“用的时候查”，而不是从头到尾读完。第一周只学/init、/status、/clear这条最小闭环，第二周再开始调权限模式，等你能熟练指使Claude Code改文件了，再去研究Workflows和Skills。这样节奏最不容易劝退。
我个人在实际操作中最有成就感的一刻，是第一次让它独立完成了一个跨20个文件的接口改造，然后我自己一行一行Review完，发现自己只改了不到三处。这种“AI干活、人类把方向”的协作方式，就是Claude Code这套工具最厉害的地方。如果你在自己的项目里跑通了一条顺手的工作流，回去翻翻手册里的模板，把它们改造成自己的版本，那才是真正“从入门到精通”的状态。
