又见山人这些年在终端里折腾 AI 工具的经历不少，Claude Code 是少数让我觉得“值得认真学一遍”的那个。它不是一个普通聊天窗口，而是一个直接住在命令行里的编程代理，能读你的项目、改代码、跑命令、提交 Git 记录，你只负责把需求讲清楚，它负责拆解和执行。这篇文章是我从零开始折腾 Claude Code 的完整笔记，覆盖安装、CLI 与桌面版和 VSCode 插件三种形态的选型、接第三方模型、写 skill、改中文回复，以及那些最容易卡住人的报错。适合刚接触命令行工具的开发者，也适合已经用了几天但还被配置文件折磨的用户。
我先把结论放在最前面：Claude Code 的安装和基础配置并不难，真正麻烦的是环境变量、模型名、配置文件这三件事互相纠缠。一旦把这三件事理顺，它就是我见过的最贴近“程序员助理”这个定位的工具。
1. 先搞清楚：Claude Code 是什么，三种形态怎么选
1.1 从“聊天窗口”到“终端代理”
Claude Code 是 Anthropic 推出的终端编程代理工具，核心能力是一个运行在命令行里的 Agent。它和我之前用过的各种 AI 插件最大的不同，在于它拥有当前项目的读取和执行权限：它自己决定先看哪个文件、再跑哪条命令、看到执行结果之后下一步做什么，而不是等着用户一条一条喂指令。
我习惯用一个类比来解释：网页版对话像是你雇了一个顾问，只能动嘴给建议；Claude Code 则像是雇了一位坐在你电脑前的实习生，可以直接翻你的项目、动手改代码。当然，它不是无法无天，你可以在配置文件里设置权限，让它每次执行高风险的写操作或删除命令之前都先向你请示。这个“可授权的 Agent”定位，是我认为它比普通对话工具高一个维度的原因。
这个工具特别适合两类人：一是日常用 Vim、tmux、脚本写代码的开发者，二是想尝试“AI 自动编程”但不想离开命令行工作流的用户。如果你完全没接触过终端，也可以先用桌面版过渡，但最终你还是会回到配置文件上来，因为很多高级功能绕不开。
1.2 CLI、桌面版、VSCode 扩展，我该用哪个
Claude Code 现在有三种常见形态：纯 CLI、桌面版、VSCode 扩展。很多人第一次看到这三个名字就懵了，不知道装哪个。我给一个很直白的选型建议：
| 形态 | 适合人群 | 特点 |
|---|---|---|
| CLI | 习惯终端的开发者 | 功能最完整，支持 skill、脚本、环境变量集成 |
| 桌面版 | 不熟悉终端的人 | 本质是 CLI 的图形封装，自带终端窗口 |
| VSCode 扩展 | 日常在 VSCode 里写代码的人 | 编辑器和 Agent 同屏，看 diff 方便 |
我个人的主力是 CLI。原因很简单：它在脚本化、快捷键、tmux 多会话配合上最灵活，而且接第三方模型、写 skill 这些操作，最终都是通过 CLI 读取配置文件来完成的。桌面版只是把 CLI 包了一层，好处是初次上手压力小，坏处是你依然要理解同样的配置逻辑，只是界面友好一点。
VSCode 扩展则是在需要“边看 diff 边和 AI 讨论”的时候最舒服，选中一段代码直接丢给它解释或修改，上下文自动带过去，省去了终端里复制粘贴。我的建议是 CLI 为主、VSCode 扩展为辅，两个都装，反正它们共用同一套配置，不冲突。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 从零安装：Windows 和 Ubuntu 的实操记录
2.1 前置条件：Node.js 版本别太低
Claude Code 通过 npm 分发，所以第一件事是确认 Node.js 版本。官方要求通常是不低于 18，但我建议直接上 LTS 版本（20 或 22），没必要用最新版当小白鼠，也别用老版本给自己挖坑。
Windows 上检查版本很简单：
bash复制node -v
npm -v
如果版本偏低，我推荐用 nvm-windows 来管理 Node 版本，而不是直接下载安装包覆盖安装。因为以后你可能会在不同项目里需要不同 Node 版本，用 nvm 切换比重新安装省事太多。Ubuntu 上同样建议用 nvm 或者从 NodeSource 源安装，别用发行版自带的旧 node——我在 Ubuntu 20.04 上踩过一次坑，自带 node 是 10.x，npm install 直接报引擎不匹配，后来用 nvm 装了 20 才解决。
2.2 npm 全局安装与验证
确认 Node 环境没问题后，安装就是一条命令的事：
bash复制npm install -g @anthropic-ai/claude-code
安装完成后验证：
bash复制claude --version
如果提示找不到命令，分两种情况排查：
- Windows：npm 全局安装目录可能不在 PATH 里。先执行
npm config get prefix拿到全局目录，再把它的路径加入系统环境变量 PATH，然后重开终端。 - Ubuntu：如果用 sudo 安装，全局目录通常是
/usr/local/bin，一般已经在 PATH 里；如果当前用户权限不够，可能装到了别的目录，用which claude查看实际位置。
国内网络环境下，npm 直接下载大包有时候非常慢，甚至超时。我一般把 registry 临时指向镜像源：
bash复制npm config set registry https://registry.npmmirror.com
注意这是全局修改，如果你不想影响其他项目，可以只对单次安装生效：
bash复制npm install -g @anthropic-ai/cla