Claude Code 安装配置全攻略：从零上手到本地模型接入

1. 为什么我最终把主力开发工具换成了 Claude Code

先说结论：Claude Code 不是那种"装完就完事"的插件，它是一个跑在终端里的 AI 编程代理，能直接读写你本地的文件、执行命令、跑测试、改配置。我用了大概三个月，从最初抱着"试试看"的心态，到现在日常开发基本离不开它。这篇文章不讲虚的，只讲我从零装到顺手用起来的完整过程，包括中间踩过的坑、配置的取舍、以及怎么把本地模型接进来省钱。

如果你属于以下几类人，这篇内容会对你有直接帮助：一是刚听说 Claude Code 但不知道从哪下手的新手；二是装了但用不起来、卡在环境配置上的开发者；三是想把它和本地模型（比如 LM Studio、Ollama）结合使用、降低调用成本的老手；四是在 Windows、macOS、Linux 多平台之间来回切换、需要一套通用方案的人。

我先把最核心的认知摆出来：Claude Code 和你在 IDE 里用的那种代码补全插件完全是两码事。补全插件是被动的，你打字它猜；Claude Code 是主动的，你给它一个任务描述，它会自己去读项目结构、定位相关文件、修改代码、运行验证。这个区别决定了它的安装方式、使用习惯、以及你对它的预期都得重新调整。

很多人第一次接触会问：它和 Cursor、Copilot 有什么区别？我的实际感受是，Cursor 更像一个"AI 增强的编辑器"，你还是在编辑器里操作；Claude Code 更像一个"能动手的助手"，你在终端里跟它对话，它直接动你的文件系统。两者不冲突，我现在是 Cursor 写日常代码，Claude Code 处理跨文件重构、批量修改、环境搭建这类"重活"。

关于账号和订阅这块，网上信息很杂，我只说我自己验证过的：你需要一个可用的账号体系来登录，具体订阅方式以官方页面为准。我见过有人因为频繁切换环境、多设备同时登录触发风控，所以我的建议是固定一台主力机器使用，不要今天在这台明天在那台来回折腾。这一点后面我会单独展开讲。

2. 装之前必须想清楚的几件事：环境、账号与工具链

2.1 运行环境的最低要求和推荐配置

Claude Code 本质是一个命令行工具，通过 npm 分发。所以你的机器上必须有 Node.js 环境。我实测下来，Node.js 版本建议 18 以上，20 LTS 最稳。低于 18 的版本会在安装依赖时报各种奇怪的错，别问我怎么知道的。

Windows 用户这里有个关键选择：是直接在 PowerShell 里跑，还是走 WSL2。我两种都试过，直接跑能用，但涉及文件路径、权限、shell 脚本的时候容易出幺蛾子。WSL2 里跑体验最接近 Linux 原生，各种命令行为一致。如果你本来就熟悉 Linux 命令行，强烈建议走 WSL2；如果你完全没碰过 Linux，那就先在 PowerShell 里跑起来，别一上来就给自己加难度。

内存方面，纯跑 Claude Code 本身占用不大，2GB 足够。但如果你要同时跑本地模型（后面会讲），那显存和内存就是另一回事了，8GB 显存起步比较舒服。

2.2 Node.js 和 npm 的安装，别用系统自带的

这是第一个大坑。很多 Linux 发行版和 macOS 自带的 Node.js 版本又老又乱，npm 全局安装权限还经常出问题。我的做法是用版本管理工具。

macOS 和 Linux 上我推荐用 nvm：

# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 或 ~/.zshrc # 安装并使用 Node.js 20 nvm install 20 nvm use 20 nvm alias default 20 # 验证 node -v # 应输出 v20.x.x npm -v

Windows 上我推荐用 nvm-windows，或者干脆在 WSL2 里用上面的 nvm 方案。用 nvm 的好处是：不需要 sudo 就能全局装包，版本切换干净，卸载也彻底。

注意：如果你之前用系统包管理器装过 Node.js，先卸干净再装 nvm，否则 PATH 里会有多个 node，排查起来很痛苦。

2.3 账号准备与"规避封号"这件事的正确理解

标题里提到"规避封号风险"，我得把话说清楚：所谓封号，绝大多数情况不是因为你用了什么工具，而是因为账号行为异常。我总结了几条实际经验：

• 固定设备使用，不要频繁在多台机器、多个 IP 之间来回登录。
• 不要共享账号给多人同时使用，并发登录是风控的重点关注对象。
• 订阅和支付信息保持稳定，不要频繁更换。
• 遵守服务条款，不要用自动化脚本做违反条款的批量操作。

说白了，就是"像一个正常用户那样使用"。我自己的账号用了很久没出过问题，靠的就是这几点。任何声称能"绕过风控"的方法我都不会碰，也不建议你碰，风险远大于收益。

3. 安装 Claude Code 的完整流程与验证方法

3.1 全局安装与首次启动

环境准备好之后，安装本身其实就一行命令：

npm install -g @anthropic-ai/claude-code

装完之后验证：

claude --version

能输出版本号就说明装好了。如果报command not found，八成是 npm 全局 bin 目录没在 PATH 里。用npm config get prefix看看全局目录在哪，然后把它加到 PATH。

首次启动直接在项目目录下敲：

cd your-project claude

第一次运行会引导你完成登录授权。跟着提示走就行，会打开浏览器让你确认。授权完成后回到终端，你就进入交互界面了。

3.2 在 VS Code 里用起来：终端集成才是正解

很多人搜"vscode 配置 claude code"，其实不需要什么特殊插件。最顺手的做法是：在 VS Code 里打开集成终端，直接在项目根目录运行claude。这样你一边看代码一边跟它对话，它改完文件你立刻能在编辑器里看到 diff。

如果你想要更紧密的集成，可以装官方或社区的 VS Code 扩展，但我的经验是：终端版本功能最全、更新最快，扩展有时候会滞后。所以我的主力用法就是"VS Code + 集成终端 + claude 命令"。

3.3 验证它真的能干活：一个最小测试

装完别急着上大项目，先做个小测试确认它能读写文件。新建一个空目录，进去运行 claude，然后输入：

创建一个 hello.py，打印当前时间，然后运行它

如果它自动创建文件、执行、把输出贴给你，说明整条链路通了。这个测试能同时验证：文件读写权限、命令执行权限、模型响应。任何一环有问题都会在这一步暴露。

4. 把本地模型接进来：LM Studio 与 Ollama 的实操配置

4.1 为什么要接本地模型

Claude Code 默认走云端模型，能力强但按量计费。如果你有大量重复性的小任务（比如批量改注释、格式化、简单重构），全部走云端成本不低。这时候把本地模型接进来就很划算。本地模型跑在你自己的机器上，不产生调用费用，隐私性也好。

代价是：本地模型的能力通常不如云端大模型，复杂任务容易翻车。所以我的策略是"分级使用"——复杂任务用云端，简单批量任务切本地。

4.2 LM Studio 的配置步骤

LM Studio 是一个带图形界面的本地模型运行工具，对新手友好。步骤：

1. 去 LM Studio 官网下载对应平台的安装包，装好。
2. 在软件里搜索并下载一个适合代码的模型，比如 Qwen 系列的 coder 版本。
3. 加载模型，切到 "Local Server" 标签页，启动服务。默认端口是 1234。
4. 确认服务地址，通常是http://localhost:1234/v1。

然后在 Claude Code 这边，通过环境变量指向本地服务：

export ANTHROPIC_BASE_URL="http://localhost:1234/v1" export ANTHROPIC_API_KEY="lm-studio" # 本地服务通常不校验，随便填

再启动 claude，它就会走本地模型。这里要注意：不同版本的 Claude Code 对环境变量的读取方式可能有差异，如果发现没生效，检查一下是不是需要在配置文件里设置，而不是临时 export。

4.3 Ollama 方案与离线场景

Ollama 更适合喜欢命令行的用户，而且支持离线安装包，内网环境也能用。基本流程：

# 安装后拉取模型 ollama pull qwen2.5-coder # 启动服务（默认 11434 端口） ollama serve

Ollama 的 API 兼容 OpenAI 格式，地址是http://localhost:11434/v1。配置方式和 LM Studio 类似，改ANTHROPIC_BASE_URL即可。

提示：本地模型接进来之后，响应速度取决于你的硬件。显存不够会疯狂调用内存，速度断崖式下跌。跑之前先用小模型试水，别一上来就上大参数模型。

5. 日常使用中真正提效的几个习惯

5.1 用 CLAUDE.md 给它"立规矩"

这是我认为最值得花时间的一件事。在项目根目录放一个CLAUDE.md文件，写上项目的技术栈、代码规范、目录结构说明、常用命令。Claude Code 每次启动会读这个文件，相当于给它一份项目说明书。

我自己的CLAUDE.md大概包含这些内容：

# 项目说明 - 技术栈：Python 3.11 + FastAPI + PostgreSQL - 代码风格：遵循 PEP8，函数必须有类型注解 - 测试命令：pytest tests/ - 不要修改 migrations 目录下的历史文件

有了这个，它改代码时会自动遵守你的规范，省去大量来回纠正的口舌。

5.2 任务描述要具体，别让它猜

新手最容易犯的错是给一个模糊指令，比如"优化一下这个项目"。它会一脸懵地乱翻文件。正确的做法是给具体、可验证的目标：

• 差："改改登录逻辑"
• 好："在 auth.py 的 login 函数里，把密码校验从明文对比改成 bcrypt 校验，并更新对应的单元测试"

任务越具体，它干活越准。这跟带新人的道理一样，你说得越清楚，返工越少。

5.3 善用"先规划后执行"

对于复杂任务，我会先让它出方案，确认没问题再让它动手。比如：

先不要改代码，告诉我你打算怎么重构这个模块，列出涉及的文件和步骤

它给出计划后，我审一遍，觉得靠谱再让它执行。这一步能挡掉很多"它自作主张改错方向"的情况。

6. 踩过的坑与排查思路

6.1 安装报权限错误

npm install -g报 EACCES，这是 Linux/macOS 上的经典问题。根因是全局目录属于 root。解决方案有两个：一是用 nvm（前面推荐过），二是改 npm 全局目录到用户目录：

mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' export PATH=~/.npm-global/bin:$PATH

我强烈推荐第一种，一劳永逸。

6.2 登录后一直转圈或超时

这种情况我遇到过两次。一次是网络环境问题，换个网络就好了；一次是本地代理配置冲突，终端里残留了旧的代理环境变量。检查http_proxy、https_proxy这些变量，清掉再试。

6.3 本地模型接了但没反应

最常见的原因是 base URL 写错，或者本地服务没真正启动。排查顺序：先用 curl 直接打本地服务的接口，确认服务活着；再检查环境变量有没有被正确读取；最后看 Claude Code 的日志输出。别跳过第一步，很多人栽在"以为服务启动了其实没有"。

6.4 它改错了文件怎么办

这是必须提前想好的问题。我的做法是：所有项目都用 Git 管理，动手前确保工作区干净。这样它改错了，git diff一看便知，git checkout一键还原。没有版本控制就用 AI 改代码，等于裸奔。

7. 关于工具链搭配的一些个人体会

把 Claude Code 用顺之后，我的工作流大概是这样：Git 管版本，VS Code 写代码，集成终端跑 Claude Code 处理重活，本地模型兜底简单任务。这套组合跑下来，效率提升是实打实的。

我不建议一上来就追求"全自动"，让 AI 接管所有编码。更现实的做法是把它当成一个执行力很强但需要你把关的助手：你负责定方向和验收，它负责动手和跑腿。这个定位摆正了，用起来会舒服很多。

最后分享一个小技巧：每次让它做完一批修改，我都会让它自己跑一遍测试并汇报结果。它跑测试、看报错、再修，这个闭环能省掉我大量手动验证的时间。前提是你的项目得有像样的测试，没有测试的项目，这一步就只能靠人肉 review 了。