不妧1. Claude Code 不是“又一个 AI 助手”，而是一个会动手的编程代理
第一次用 Claude Code 的感觉，和第一次用 ChatGPT 写代码完全不同。你不再是“把代码贴进去、拿到代码再贴回来”，而是直接在一个终端里看着它自己读项目文件、自己改文件、自己跑测试、甚至自己修自己犯的错。这个体验上的跳跃，是理解 Claude Code 到底值不值得学的前提。
很多人会把 Claude Code 和 Cursor 这类 AI 编辑器放在一起比较。说实话，两者解决的问题有重叠，但工作方式差异很大。Cursor 本质上是一个带 AI 能力的 IDE，它帮你补全、生成、解释、批量修改，主角仍然是“你在编辑器里操作”，AI 是辅助。而 Claude Code 是反过来，主角是那个跑在终端里的 AI 代理，你负责提需求、看结果、给反馈、卡权限，真正去翻文件、敲命令、做修改的是它。
这种“代理式”的工具，在 2025 年已经不是一个新概念了，但我依然建议大家认真把 Claude Code 用起来。原因很简单：它是目前把“AI 能独立完成编码任务”这件事，从演示变成日常工作的少数几个工具之一。它原生跑在命令行里，意味着它可以执行 bash 命令，可以调用编译器和测试框架，可以操作 Git，可以读日志、改配置、做部署脚本。这些能力一旦组合起来，它就不再是“聊天窗口里的程序员”，而是一个能实际在你的项目环境里干活的协作者。
我自己最深的感触是：过去我写 AI 辅助编程的流程，是人先思考、AI 补全；用了 Claude Code 之后，流程变成了人给方向和边界、AI 做执行、人做 review。这不是把程序员的价值降低了，而是把重复劳动大幅度压缩了，尤其是机械性的重构、批量改文件、写测试这类事情，效率提升非常明显。
当然，它也有明显的上手门槛。毕竟要面对一个终端、一堆权限提示、还有配置文件。这篇就是我系列里的第二篇，专门讲“开始使用”这四件事：装好它、跑起来、配明白、别踩坑。我会从零开始，把每一步背后的原因也讲清楚，不光是给命令。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 开始之前的三件事：Node 环境、npm 版本、账号登录
Claude Code 的安装方式已经做得比较成熟了，核心依赖是 Node.js 环境。官方推荐的安装方式是走 npm 全局安装，所以你在动手之前，要先确认两件事：Node 版本够不够、npm 源正不正常。
2.1 Node.js 版本到底要多少
Claude Code 要求 Node.js 18 以上。这个门槛放在 2025 年已经很低了，但如果你电脑上长期跑着一个旧项目留下来的 Node 14，那 npm install 的时候大概率会报 engine 相关的错误，或者装上之后启动直接崩。我个人建议直接用 20 LTS 或 22 LTS，这两个版本稳定且兼容性好。
先检查当前环境：
bash复制node -v
npm -v
如果你看到 v18.x、v20.x、v22.x 这类版本号，就没问题。如果版本太旧，先去官网下载对应的 LTS 安装包，或者用你习惯的版本管理工具（nvm、fnm 都行）装一个新版本。这里我想提醒一句：不要为了装 Claude Code 去动你项目正在用的 Node 版本，最好用 nvm 这类工具做版本隔离，避免“装了个新工具，老项目挂掉了”这种悲剧。
2.2 npm 全局安装的底层逻辑
确认 Node 环境没问题之后，安装命令就一条：
bash复制npm install -g @anthropic-ai/claude-code
很多人装完直接敲 claude，结果提示找不到命令。这个问题大概率出在 npm 的全局安装目录没有加到系统 PATH 里，后面排查章节我会专门讲。这里先说明一个概念：-g 参数代表全局安装，npm 会把可执行文件放到一个全局 bin 目录，如果你的终端没有把这个目录加进 PATH，Shell 就找不到 claude 命令。
安装完成之后，先验证一下：
bash复制claude --version
能看到版本号，说明安装这步已经通了。如果你在安装过程中遇到权限报错（比如 macOS 上常见的 EACCES），不要上来就加 sudo。先去查一下 npm 全局目录的权限配置，使用 npm config get prefix 看目录位置，然后调整目录归属或改用 nvm 管理 Node，这是更干净的做法。
2.3 账号登录与订阅状态
装好之后就可以启动了。首次运行 claude，它会引导你完成账号登录，方式比较常规，终端里会给一个授权链接，打开浏览器完成登录授权。这里需要注意一个情况：如果你用的是企业组织账号，组织管理员可能设置了策略，禁止 Claude Code 的订阅访问权限。这时候会看到类似这样的报错：
code复制your organization has disabled claude subscription access for claude code
意思很直白，不是你账号坏了，是组织关掉了这项能力。解决方式通常是找管理员开权限，或者换个人账号登录。还有一种情况，是你在用第三方 API 兼容服务来跑 Claude Code，这时候登录流程就不走官方账号授权了，而是通过环境变量注入 API Token。这个在第五章节详细讲。
这里多说一句，为什么 Claude Code 一定要先解决身份认证问题。因为它在工作时，需要依赖模型服务来完成推理，而模型服务的调用是有成本的，所以工具本身必须有账号体系来管理权限和计费。它不是本地纯离线工具，这一点在用之前要想清楚。
3. 第一次启动：交互界面、权限模型、还有那个“一堆符号”的终端
在你真正开始用 Claude Code 之前，有必要先理解它的交互方式。很多人第一次打开终端，看到满屏的符号、斜杠命令、权限按钮，会有点懵。这部分我会把它的界面和权限逻辑拆开讲。
3.1 首次启动时你会看到什么
在项目目录下输入 claude 并回车之后，你会进入一个交互式界面。底部是一个输入框，默认会有一个带颜色的箭头提示符。你可以直接输入自然语言，用中文、英文都行，甚至可以用半中半英的混合描述，模型的理解能力足够强。
界面上的文字会分两种：
- 普通对话流，展示模型的推理过程和分析结论；
- 操作步骤面板，展示它准备执行的工具调用，比如读取哪些文件、修改哪个文件、运行什么命令。
后者是 Claude Code 和普通聊天 AI 最明显的区别。它在动手之前，会先规划一组操作，然后通过工具调用去执行，操作结果会实时反馈到对话流里。你看到的不只是“它说你听听”，而是“它说你看看”。
3.2 权限系统：为什么每个操作都要问你
默认情况下，Claude Code 的安全策略是比较保守的。当它要执行敏感操作时，会弹出一个权限确认请求，你需要按对应的快捷键（通常是 y 表示允许、n 表示拒绝）来放行。常见的敏感操作包括：
- 运行 bash 命令，尤其是涉及修改文件、安装依赖、执行构建脚本的那类命令；
- 写入或修改项目文件；
- 发起网络请求。
为什么工具要设计成这样？因为 AI 代理一旦能执行命令，就意味着它拥有你机器的实际控制权。如果让它在没有任何确认的情况下乱跑命令，一旦它误解了你的需求，可能直接改坏文件、误删数据，甚至把不该提交的内容推到远端。权限确认机制就是一种安全缓冲，让你在关键节点把住关。
不过每次都确认确实会打断节奏。如果你对 Claude Code 已经比较信任，可以在项目初始化时调整权限策略，允许它自动执行某些低风险操作，比如 Bash(npm run test:*)，这样它能跑测试而不需要你一步步点头。建议一开始不要全面放开，等你摸清楚它的行为习惯之后再逐步放宽。
3.3 几个常用的斜杠命令
Claude Code 提供了一组斜杠命令，类似终端里的快捷指令，在输入框直接输入即可。刚上手建议记住这几个：
/init：在项目里生成 CLAUDE.md 文件，相当于给 AI 一份项目说明手册，包含项目结构、技术栈、常用命令等，它会后续所有对话里自动读取；/status：查看当前会话里 AI 已经做了哪些修改，有没有未提交的文件变更；/compact：当上下文太长、对话变慢或记忆开始丢失时，压缩历史对话，保留关键信息继续干活；/review：让 AI 对当前改动做一遍代码审查，适合提交前用；/clear：清空当前会话上下文，重新开一个新任务。
这些命令不需要死记，用多了自然就熟了。你只要记住一件事：斜杠命令是给你的“控制权”，当你想切换状态、查看进度、中断当前思路时，都可以先敲一个斜杠看看有哪些可用指令。
4. 真正动手：用 Claude Code 完成一次小重构
说再多界面和命令，不如实际跑一个任务。我这部分用一个真实的小例子，带你走一遍完整的操作流程，也顺便聊聊怎么把需求描述清楚。
4.1 把任务讲清楚的四个要素
我准备了一个小的 Node.js 项目，里面有一个计算折扣价的函数，写得比较啰嗦，还有一点边界问题。我不打算自己改，直接把需求丢给 Claude Code。
我给的提示是这样写的：
code复制项目里 src/price.js 有一个 getDiscountPrice 函数，逻辑是原价乘以折扣率，再做一个四舍五入。
现在有两个问题：折扣率传 0 到 1 之外的数值时没有报错；四舍五入希望保留两位小数而不是整数。
请帮我重构这个函数，并补充对应的单元测试，测试文件放在 test/price.test.js，跑通 npm test。
这段话包含了四个要素：上下文（哪个文件哪个函数）、任务（重构逻辑）、边界（折扣率校验）、验证方式（跑测试）。你给 AI 的信息越像给一个靠谱同事交代任务，它做出来的东西越贴合预期。反过来，如果你只丢一句“帮我改改价格函数”，它大概率会给出一个泛泛的重构，然后你来回改好几轮。
4.2 观察它工作：从读代码、改代码到跑测试
我把提示发出去之后，Claude Code 开始工作。它的流程大概是这样的：
- 先用工具读取
src/price.js，确认当前代码长什么样； - 查看项目里的
package.json，了解测试框架和脚本配置； - 动手修改
src/price.js，加边界校验、调整四舍五入逻辑； - 新建
test/price.test.js，写对应的测试用例； - 运行
npm test，发现第一次跑挂了，原因是某个用例预期值写错了，然后自己修正，再跑一遍，直到全绿。
这个过程看起来不复杂，但整个链条你能在终端里实时看到。它在每一步被执行之前，都会先描述“我要做什么”，然后请求执行权限。我在这期间只需要盯着它，遇到我不想让它执行的操作就直接拒绝。比如它中途想顺手改另一个文件，我看到了，确认了一下是相关改动才放行。
实测下来，这种“AI 主动干活，人做审查”的协作模式，比我以往用 Copilot 或 Cursor 的体验更接近“带一个实习生干活”的感觉：你给方向，它执行，你验收。不过它也真的会犯错，而且有时候错得挺自信，所以 review 的环节绝对不能省。
4.3 如何在不满意时安全撤回
如果你对它的修改不满意，最常见的做法是直接用 git checkout 或 git restore 把文件恢复到修改前的状态。这也是我建议在干净的 Git 工作区里使用 Claude Code 的原因——你永远可以一键回到起点。
操作方式：
bash复制git restor src/price.js test/price.test.js
或者想清理所有未提交的改动：
bash复制git checkout -- .
当然，这要求你在让 Claude Code 干活之前，确保 git status 是干净的。如果本来就有一堆未提交的改动，建议先 commit 或 stash，再放它出来干活。万一它把进度搞乱了，你也能基于一个干净的基点恢复。
5. settings.json 与模型配置：自定义接入时的真实坑
Claude Code 的能力不只来自官方默认配置，它支持通过配置文件定制行为，也支持接入第三方模型。这部分是新手最容易踩坑的地方，尤其是当你看到模型不识别、接口报错时，会很莫名其妙。我把常见的问题和原理一并讲清楚。
5.1 settings.json 到底控制什么
Claude Code 的配置体系分为两层：
- 用户级配置：
~/.claude/settings.json，影响你所有项目； - 项目级配置：
.claude/settings.json，只影响当前项目，适合团队共享。
settings.json 的作用很广，包括权限规则、环境变量注入、模型选择、输出偏好等。下面是一个简化示例：
json复制{
"permissions": {
"allow": [
"Bash(npm run test:*)",
"Read(~/.zshrc)"
],
"deny": [
"Bash(git push *)"
]
},
"env": {
"MY_CUSTOM_VAR": "some-value"
},
"model": "claude-sonnet-4-5"
}
这个文件的逻辑不复杂，但有一点要注意：settings.json 不是“写了就生效”，修改完通常需要重启会话，或者新建一个会话才生效。我一开始犯过这个错，改了权限配置以为立刻生效，结果当前会话还在不停弹权限请求，一度怀疑自己改错文件了。
5.2 为什么会出现 “deepseek-v4-pro is not a model this version of claude code recognizes”
这是一个很典型的问题。为了接入第三方模型服务，你需要通过环境变量把请求地址指向一个兼容 API 的端点，并在 settings.json 或环境变量里指定模型名称。但如果你指定的模型名，不在当前版本 Claude Code 内部的模型白名单里，就会报类似这样的错误：
code复制deepseek-v4-pro" is not a model this version of claude code recognizes
这个错误还有一个变体，就是 deepseek-v4-flash 这类模型名也不被识别。很多人的第一反应是“模型服务坏了”，其实不是，是 Claude Code 这一侧做了模型名校验。
为什么 Claude Code 要这么做？因为它需要根据模型名称来调整请求格式和参数，对不同模型的能力边界做适配。如果你传入一个它不认识的模型名，它不知道该如何处理，就直接拒绝。这个保护机制本质上是为了避免“传了不匹配的参数导致更奇怪的错误”。
那怎么解决呢？思路也很直接，有几个方向：
- 升级 Claude Code 到最新版本，新版本通常会同步更新模型白名单。如果你用的第三方模型是最近才发布的，旧版本大概率不认识；
- 确认你使用的第三方模型实际对外提供的模型名称。不要凭记忆猜，去看 API 文档里真实可用的模型标识；
- 在配置里指定一个 Claude Code 认识的模型别名，同时通过 API 网关做模型映射，这属于进阶做法，一般个人用不上。
我见过最多的情况，是网上教程写了某个模型名，实际 API 服务已经更新了命名规则，但用户没注意，直接复制配置就踩坑。所以遇到这个报错，第一件事不是找工具问题，而是去确认模型名称到底对不对。
5.3 用环境变量切换模型时的推荐做法
环境变量是配置模型接入最灵活的方式，比直接改 JSON 文件更不容易出错。下面是一个最小可用的示例：
bash复制export ANTHROPIC_BASE_URL="https://your-api-endpoint.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-token"
export ANTHROPIC_MODEL="deepseek-chat"
export ANTHROPIC_SMALL_FAST_MODEL="deepseek-chat"
这里的思路是：Claude Code 读取 ANTHROPIC_BASE_URL 来决定请求打到哪里，读取 ANTHROPIC_AUTH_TOKEN 来做鉴权，而 ANTHROPIC_MODEL 控制主模型，ANTHROPIC_SMALL_FAST_MODEL 控制轻量任务用的快速模型，比如标题生成、上下文摘要这类不太需要动脑的任务。
我建议把环境变量写进 ~/.zshrc 或者项目里的 .env 文件，而不是每次启动终端手动导。如果你怕影响其他项目，就在 settings.json 的 env 字段里加，这样只有 Claude Code 运行时会注入这些变量，不会污染全局环境。
6. 常见报错排查：PATH、版本、模型不识别
这一节我把自己和朋友在实际使用中踩过的几个高频问题，按照完整的排查思路写出来，不光是给答案，也让你知道下一次遇到同类问题该怎么定位。
6.1 PATH 找不到 claude 命令的完整排查链路
报错原文类似：
code复制failed to run claude code: error: could not locate the claude cli on path
或者只是终端提示 claude: command not found。这个问题的本质是：系统在 PATH 环境变量指定的目录里，找不到名为 claude 的可执行文件。
排查顺序是这样的：
第一步，确认安装是否真的成功了：
bash复制npm list -g @anthropic-ai/claude-code
如果这里能看到包名和版本号，说明安装成功，问题出在 PATH。
第二步，找到 npm 的全局安装目录：
bash复制npm config get prefix
如果你看到输出是 /usr/local 或 C:\Users\你的用户名\AppData\Roaming\npm 这类路径，那个全局 bin 目录通常就在这个 prefix 下的 bin 子目录里。
第三步，把 bin 目录加进 PATH。macOS / Linux 上编辑 ~/.zshrc，添加：
bash复制export PATH="$(npm config get prefix)/bin:$PATH"
Windows 上则是打开系统环境变量设置，把 npm 的全局目录加到 Path 里。
第四步，重新打开终端，再试一次 claude --version。
这里要提醒一个认知误区：装完工具立刻就能全局用的前提，是 PATH 已经包含对应目录。很多“按教程敲了命令但还是不行”的情况，不是命令错了，而是别人的环境里 PATH 和你不一样。
6.2 版本过旧导致的兼容性问题
Claude Code 的更新频率很高，功能变化也快，如果你安装之后几个月没更新，很容易遇到模型名不识别、某些新命令缺失的问题。更新方式很简单：
bash复制claude update
或者走 npm 重新安装最新版：
bash复制npm install -g @anthropic-ai/claude-code@latest
如果你想确认当前版本，用 claude --version。如果升级之后出现问题，想回滚到之前的稳定版本，可以指定版本号安装：
bash复制npm install -g @anthropic-ai/claude-code@1.0.57
我这里提这个，是因为我见过不少“新版本怎么这么难用”的吐槽，排查到最后发现是版本迭代还没跟上模型服务的节奏。工具版本和模型服务之间的兼容性，是这类 AI 编程工具特有的问题，传统编辑器很少会遇到。
6.3 卸载与重装时比较干净的做法
卸载 Claude Code 本身不复杂：
bash复制npm uninstall -g @anthropic-ai/claude-code
但如果你是因为配置彻底搞乱了想重装，我建议把本地的配置目录也一并清理掉，避免旧的错误配置残留影响新装版本。配置文件在 ~/.claude 目录下（Windows 上是 C:\Users\用户名\.claude）。不过要小心，这个目录里可能包含你有用的设置、Skills 文件、本地历史记录，删之前先备份：
bash复制mv ~/.claude ~/.claude.backup
重装之后再启动，工具会重新生成默认配置。如果你确认没有需要保留的东西，也可以直接排除这个目录，这样可以得到一个完全干净的环境。
这个操作能解决很多莫名其妙的奇怪问题，尤其是你改过 settings.json、装过各种插件、试过不同模型之后，回到一个干净起点通常比在混乱里继续调要高效得多。
7. 从终端到桌面：桌面版、VS Code 扩展和 Skills
用了一段时间纯命令行版本之后，你大概率会冒出两个新需求：能不能在 IDE 里直接用？能不能让它拥有更多“领域常识”？这两个需求分别对应 Claude Code 桌面版/编辑器集成，以及 Skills 机制。
7.1 桌面版和 CLI 的边界在哪里
Claude Code 有桌面版，也有 VS Code 插件。但先说明一个态度：桌面版本质上是把 CLI 的能力包了一层图形界面，核心引擎没有任何变化，它解决的是“不喜欢终端”或者“想在项目文件树里看变更”的体验问题。
对新手来说，桌面版确实更友好一些，因为它把文件变更、对话历史、操作记录都做了可视化，看起来不像终端那么抽象。但我个人还是更倾向于终端工作流，因为它在任何机器上都能工作，而且用 tmux 之类的工具可以轻松做会话管理。桌面版适合的场景是：你主要在一个固定环境工作，且已经习惯了 GUI 操作。
7.2 VS Code 插件的用法
VS Code 插件则可以做到更紧密的代码上下文联动。你可以在编辑器里选中一段代码，然后直接发送给 Claude Code 让它分析或修改。这个功能在处理局部代码时非常顺手，省去了在对话里粘贴代码的步骤。
使用方法很简单：装好插件之后，在集成终端里启动 Claude Code，选中的代码会作为上下文自动注入。这样你就不需要手动描述“哪个文件哪几行”，AI 看到的就是你选中的真实代码。
需要提醒的是：插件也好、桌面版也好，权限模型和核心命令是不变的。你在终端里要学会的权限确认、斜杠命令、settings.json 配置，在 GUI 里依然是同一套逻辑。所以不要认为“用桌面版就不用学配置了”，该懂的原理还是得懂。
7.3 Skills：让 Agent 具备“领域常识”
Skills 是一个值得单独拿出来讲的概念。通俗地说，它是一批预先写好的指令文件，放在 .claude/skills/ 目录下，告诉 Claude Code“当涉及某个领域时，你应该怎样做”。
举个例子，假设你经常在项目里跑一套特定的数据库迁移流程，每次都在对话里重新教 Claude Code 太麻烦。你可以创建一个 database-migration 的 Skill，里面写清楚：连接数据库的命令、迁移脚本的位置、执行前必须备份的规则、验证迁移成功的步骤。之后只要在对话里提到“做一次数据库迁移”，Claude Code 就会自动读取这个 Skill 文件，按照里面的规矩执行。
一个 Skill 的基本结构长这样：
code复制.claude/skills/database-migration/
├── SKILL.md
SKILL.md 里是 Markdown 格式的说明，描述技能的名字、适用场景、执行步骤、注意事项。如果你是想做个人使用，这个机制相当于给 AI 写了一个“岗位手册”，让它在特定场景下的行为更稳定、更符合你的预期。
我自己的体会是，Skills 很适合用来沉淀团队的工程规范。比如代码提交前必须跑哪些检查、发布流程分几步、错误日志往哪里看，这些写在 CLAUDE.md 里可能比较泛，但写成 Skills 之后，任务触发就会自动带上规范，效果比每次对话重新交代要稳定得多。
8. 我实际用了一段时间之后，最想说清楚的三件事
到了文章末尾，我不想给你一个“总结”，更不想说“以上介绍完毕”。我就讲三个我真正实践出来的体会，它们能决定你使用 Claude Code 的长期体验。
第一件事，它最擅长的是“范围明确、有验证手段”的任务。重构一个函数、写一批单元测试、批量替换 API 调用方式、迁移配置文件、修复 CI 错误——这些任务目标清晰，验证标准明确，它能干得又快又好。反过来，如果任务范围模糊，比如“帮我优化一下这个项目的架构”，它通常会给出一个看似合理但实际难以落地的方案，因为架构优化涉及太多你没有告诉它的约束条件。所以我的习惯是，接大任务之前，先通过对话让它梳理现状、产出一个计划，确认方向之后，再让它动手。
第二件事，上下文管理比提示词技巧更重要。Claude Code 的上下文窗口是有限的，会话越长，它越容易丢失早期信息，或者开始“自作聪明”忽略你之前强调的约束。我现在的做法是：一个会话只聚焦一个任务，干完就 /clear；任务中途如果发现上下文太长，就用 /compact 压缩。项目级的信息尽量写进 CLAUDE.md，而不是每次对话里重复交代，这样既能省上下文，也能让它在不同会话里保持一致的行为。
第三件事，也是最容易被忽略的：权限控制不是麻烦，是安全网。我见过有人把所有权限全部放开，换来一时的流畅，结果某次它运行了一个清理脚本，把临时目录里一个很重要的文件删了，虽然没有造成不可挽回的损失，但也足够让人后怕。我的做法是分阶段放开：第一周全部手动确认，摸清它的操作习惯；之后只对极低频、低风险的命令开启自动执行；凡是涉及删除、覆盖、push、依赖安装的敏感操作，一律保留确认。这个节奏能兼顾效率和安全感。
最后给你一个实用建议：每周花一点时间，整理你在这个项目里反复遇到的工程流程，把它们沉淀成 Skills。这可能是 Claude Code 最被低估的长期投资，你越往里写，它就越像真正了解你项目的协作者，而不是一个每次都要重新认识的实习生的。