最近后台收到不少关于 Claude Code 的提问很多人一上来就搜“安装教程”“VSCode 配置”“怎么接本地模型”。我用了这段时间最大的感受是它确实能大幅提高改代码、读项目的效率但很多人卡在最开始的安装和环境配置上还没体会到好处就放弃了。这篇东西我不会按教科书的方式罗列命令而是按我实际踩坑的顺序把 Claude Code 是什么、怎么装、怎么在 VSCode 里用、怎么接入 Ollama 和第三方模型、怎么省 token、遇到报错怎么处理全部串一遍。内容偏入门但每一步我都会解释为什么这么做方便你后面自己折腾。1. Claude Code是什么为什么值得入门1.1 一个跑在终端里的AI编程搭档Claude Code 是 Anthropic 官方推出的命令行编程助手核心是让你在终端里用自然语言和 Claude 对话再由 Claude 直接操作你的项目文件、执行命令、搜索代码。它不像普通的聊天窗口那样只给你贴代码而是能真正读你磁盘上的项目改文件后帮你跑测试甚至一条龙完成“修复 bug、运行验证、提交代码”的闭环。我最初以为它只是把 ChatGPT 搬到了终端里实际用过才发现差别很大。ChatGPT 的回答是静态的而 Claude Code 会先扫描你项目的目录结构读取相关文件然后给出针对性的修改建议。你同意之后它会直接改写文件并在终端里显示每处改动。这种“代理式”的工作方式让它更像一个坐在你旁边、能动手改代码的同事而不是一个只动嘴的顾问。1.2 和常见AI编码工具对比很多人会把 Claude Code 和 GitHub Copilot、Cursor、Codex 放一起比。简单说GitHub Copilot 是 IDE 里的自动补全助手适合在写代码过程中给即时建议但很难完成跨文件的复杂重构。Cursor 是一个 AI 原生的编辑器交互更图形化适合喜欢在图形界面里看 diff 的人。Claude Code 是纯命令行的代理式工具更适合习惯用终端、希望 AI 能直接调用命令和工具的场景。Codex 是 OpenAI 的类似产品玩法接近但背后的模型和生态不同。选择的时候不用太纠结。如果你主力编辑器是 VSCode 或 IDEA又不想离开编辑器Claude Code 也能很好地配合如果你喜欢和人聊天一样改代码它同样能胜任。关键是你想要“AI 动手改文件”还是“AI 只给建议”Claude Code 明显偏向前者。1.3 适合谁用不适合谁用根据我的观察下面几类人用 Claude Code 收益最大需要快速理解陌生项目的人。比如你刚接手一个老项目直接让它解释目录结构和核心流程比人肉看代码快得多。经常做机械重构的人。例如批量重命名、拆分函数、补测试它能稳定执行你只需要 review 结果。熟悉命令行的开发者。终端本身就是你工作流的一部分加一个 AI 助手是顺理成章的事。想控制成本的个人开发者。Claude Code 的对话是按 token 计费的但你可以通过限制上下文、缩小任务范围来控制费用比无脑把整个项目塞给它要省很多。不太适合的是完全不会 Git、看不懂终端报错的小白。因为它的很多能力依赖底层命令如果它改错了代码你需要能发现问题并手动回滚。最好先有一点点 Git 基础再上手。2. 安装前要准备的3件事2.1 Node.js版本怎么选Claude Code 是 Node.js 写的所以安装前必须先装 Node.js。官方要求 Node.js 18 以上但我建议直接装最新的 LTS 版本比如 20.x 或 22.x。为什么强调 LTS因为 Claude Code 经常依赖一些新特性版本太老的 Node 会导致安装完运行时报错而这类报错很容易被误认为是 Claude Code 自身的问题。你可以用node -v看一下当前版本。如果还没装去 Node.js 官网下载 LTS 安装包即可。装完记得检查 npm 是否可用。在终端里输入npm -v能输出版本号说明 npm 没问题。2.2 登录方式和订阅选择安装之前最好先有一个 Anthropic 账号。Claude Code 正式使用需要登录它会引导你完成 OAuth 或 API Key 的方式。如果你是 Claude Pro/会员用户可以直接用订阅登录这种方式在网页端和 CLI 之间共用额度如果你走 API则按实际 token 用量计费适合重度使用或者团队协作。另外要注意有一个很常见的提示是 “your organization has disabled claude subscription access for claude code”。这说明你用的 Anthropic 组织账号在后台关闭了 Claude Code 的订阅访问权限。遇到这种提示不要以为是软件坏了找组织管理员在设置里打开相关权限即可。我个人建议个人开发者优先用自己的账号避免这种组织策略限制。2.3 网络环境与API服务地址安装本身走 npm 公共仓库但登录和实际对话需要能正常访问 Anthropic 的服务。如果你在公司内网或者网络有一些特殊限制登录时可能会卡住或超时。这里我不展开网络设置只说一句确保你的网络可以正常访问 Anthropic 域名否则后续所有步骤都会卡在登录。对大多数个人用户而言通常不会遇到这个问题。如果你之后想接 DeepSeek、GLM 这类第三方模型原理是设置环境变量ANTHROPIC_BASE_URL指向兼容的 API 地址而不是修改 Claude Code 本身。这是后话我放到第 4 章详细讲。3. Claude Code完整安装与启动步骤3.1 安装命令与常见姿势安装 Claude Code 非常简单核心命令就一条npm install -g anthropic-ai/claude-code如果你之前装过旧版本想升级可以执行npm update -g anthropic-ai/claude-code安装完成后在终端里输入claude就会进入交互式对话界面。如果你不想全局安装也可以在当前项目目录下用npx anthropic-ai/claude-code临时启动。这种方式的好处是不会污染全局环境缺点是每次都要多敲几个字符。我建议个人电脑直接全局安装省事。另外很多人搜“claude code桌面版”“claude code desktop”。目前 Anthropic 也提供桌面客户端但本质上它还是封装了 CLI 的界面版。对于开发者来说用终端或 VSCode 插件就够了桌面版更多是为了降低门槛。如果你追求图形界面可以关注官方桌面客户端但不要以为桌面版和 CLI 是两个产品它们共享同一个账号和配额。3.2 验证安装成功开启第一次对话安装完先别急着乱敲命令用claude --version验证一下版本号能正常输出。如果显示anthropic-ai/claude-code/版本号说明安装成功。然后运行claude第一次会提示登录。按提示打开浏览器完成授权即可。登录成功后它会询问你要在哪个目录下工作。你可以直接进入一个测试项目目录再运行 claude比如mkdir ~/claude-test cd ~/claude-test claude进入后随便问一句“这个目录下有什么文件”它会先列出当前目录结构然后给出回答。如果它能正确输出恭喜你已经跑通了整个链路。这里分享一个我的经验第一次对话尽量选择一个小项目不要一上来就把几万行代码的仓库丢给它。Claude Code 一次能接收的上下文有限如果项目太大它会自动忽略部分内容导致回答不完整。先在小项目里摸清它的工作方式再慢慢放大。3.3 PowerShell安装报错和乱码问题Windows 用户最容易遇到两个问题PowerShell 安装报错和中文乱码。PowerShell 报错通常有两种。第一种是 npm 权限问题表现形式是EPERM或ENOENT。解决方法是用管理员身份打开 PowerShell再执行安装命令。第二种是执行策略限制报错类似“无法加载文件因为在此系统上禁止运行脚本”。解决办法是用管理员身份运行 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后关闭重开终端再运行claude。中文乱码问题主要出现在 Windows 终端。Claude Code 输出的中文变成横杠或问号八成是终端编码不是 UTF-8。解决方案有两个在 PowerShell 里先执行chcp 65001切到 UTF-8 代码页再运行 claude。在 Windows Terminal 的配置文件里把默认代码页改成 UTF-8。改完之后中文显示基本就正常了。我遇到过乱码问题排查到最后其实是终端字体不支持中文换一个支持中文的等宽字体也能解决。4. VSCode插件集成和本地大模型Ollama接入4.1 在VSCode里配置Claude Code很多人希望不离开 VSCode 就使用 Claude Code。目前最简单的方案是在 VSCode 内置终端里直接运行claude命令。因为 VSCode 的集成终端本质就是系统终端所以只要你系统安装好了 Claude Code打开 VSCode 的终端直接敲claude就能在编辑器里使用了。如果你想用带图形界面的插件官方也提供了 Claude Code for VSCode 插件。安装后在侧边栏能看到一个对话面板能直接读取当前打开的代码文件配合编辑器内的高亮和 diff体验比纯终端更友好。插件的本质还是调用 CLI所以第一次使用依然要登录。IDEA 用户也用类似思路。IDEA 自带的终端可以直接运行 claude也可以安装第三方插件但稳定性不如 VSCode 官方插件。我最推荐的方式还是“编辑器 集成终端 claude”组合简单且少踩坑。4.2 用Ollama跑本地模型Claude Code 本身默认使用 Anthropic 的云端 Claude 模型但因为它支持通过环境变量切换 API 地址所以也能接入 Ollama 这样的本地模型服务。大家常搜的“claude code cc switch ollama”就是一套典型的本地化方案。原理是Ollama 启动后会在本地提供一个 OpenAI 兼容接口而 Claude Code 允许你通过ANTHROPIC_BASE_URL把请求转发到自定义地址。但直接让 Claude Code 用 Ollama 的接口可能还需要中间层转换请求格式。这时可以用社区工具cc-switch来管理多个配置方案一键切换 Claude 官方 API、DeepSeek、Ollama 等。简单步骤大概是安装并启动 Ollama在本地拉取一个支持工具调用的模型比如 qwen2.5-coder 或 llama3.1。安装 cc-switch配置一个本地模型 Profile把 Base URL 指向http://localhost:11434。在 cc-switch 里切换到该 Profile再启动 Claude Code。需要提醒的是本地模型的代码理解和工具调用能力目前和 Claude 官方模型差距还是很大。如果你只是想体验流程或者在意数据不出本机可以玩一玩但日常开发效率说实话还是官方模型更靠谱。4.3 接入DeepSeek和第三方模型除了 Ollama也有不少人想让 Claude Code 接入 DeepSeek 或 GLM。热词里有一句报错很典型glm-5.2 is not a model this version of claude code recognizes。这个报错不是 Claude Code 坏了而是你配置的模型名称是自定义的或者当前版本压根不认识这个模型名。如果你要接 DeepSeek最稳妥的方式是在环境变量里设置好 Base URL 和 API Key。export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的DeepSeek API Key export ANTHROPIC_MODELdeepseek-chat然后运行claude。这样 Claude Code 的界面和操作逻辑不变但底层请求发给了 DeepSeek。同理接智谱、通义这类模型时只要对方提供 Anthropic 兼容接口都能用类似思路配置。不过我建议如果是拿 Claude Code 来做正经开发优先用官方 Claude 模型因为它在代码理解、工具调用、长上下文上的表现最稳定。第三方模型适合做备选、做成本对比不适合作为主力。5. 省Token、保存历史、Skills与MCP实战技巧5.1 基本操作让Claude读项目、改文件、执行命令进入 Claude Code 后最常用的操作不是写代码而是下指令。比如“帮我看看 src 目录下入口文件是怎么写的”“给 utils.js 里的 formatDate 函数补一个单元测试”“全局搜索所有 TODO 注释”“运行测试并修复失败用例”你不需要指定具体路径它会自己去找。但如果项目太大建议先手动cd到相关子目录再启动 claude缩小搜索范围。这个习惯能显著提升准确率也省 token。当你看到它准备修改文件时终端会列出 diff 并询问是否接受。你可以直接按 y 接受或按 n 拒绝。千万不要每一条都无脑接受尤其是涉及删除代码的操作先看 diff 再确认。5.2 省Token和成本控制大家都关心“claude code如何省token”。我的体会是省 token 的最大技巧不是调参数而是控制上下文。Claude Code 会把当前会话里聊过的内容、读过的文件都算进上下文。你让它读过一份几百 KB 的日志文件这轮对话的成本就会明显上涨。所以我的习惯是具体任务用小范围。比如只让它看某个函数而不是“你看看整个项目的性能问题”。多用/clear清理会话。换任务时不要让上一个任务的上下文继续留着。避免让它一次性读取多个大文件。如果必须读明确告诉它只总结关键部分。关闭自动汇总功能或者设置较小的上下文长度。官方在 CLI 里也提供了配置项比如/config可以查看当前模型的上下文设置。你还可以通过环境变量调整。重点不是追求极限省而是“任务和上下文匹配”这样钱花得值。5.3 保存对话历史与恢复上下文Claude Code 默认支持在会话中通过/export导出对话记录或者用/resume恢复之前的会话。有些人问“claude code怎么保存对话历史”实际上内置的命令是/resume启动后选择历史会话即可。我自己的习惯是一个较大的功能拆成几个子任务每完成一个子任务就手动把关键结论复制到项目里的 NOTES.md 文件。这样既不会丢失信息又方便下一个会话接着做。纯粹依赖历史恢复有个风险如果对话跨了很多轮上下文会被压缩或者被截断不如自己留一份精简记录可靠。5.4 Skills和MCP扩展“claude code skills 官方文档”这个词搜的人很多。Skills 可以理解为给 Claude Code 注入一套自定义能力和使用规范。比如你写一套项目规范告诉它在生成代码时必须遵循某个命名规则或者遇到某个关键词时自动执行一系列动作。官方文档里有很多示例适合团队统一开发规范。MCPModel Context Protocol则让 Claude Code 能读取外部数据源比如数据库、文件系统、第三方 API。热词里“claude code 安装mcp读取数据库”就是这个场景。你可以通过 MCP 服务器把 PostgreSQL 的连接暴露给 Claude Code之后就能直接用自然语言查询数据比如“查一下最近一周订单数量”。配置 MCP 需要一点 JSON 基础。常见玩法是在项目根目录添加.mcp.json然后在里面声明需要的 server。配置好后重启 claude通过/mcp命令查看状态。需要注意MCP 赋予了 AI 访问敏感数据的权限千万不要在生产环境随便开启尤其不要让 AI 直接执行删除或写入操作。6. Claude Code高频报错对照表与解决思路6.1 安装与启动阶段报错现象原因解决办法npm 安装时 EPERM/ENOENT权限不足用管理员终端执行安装提示禁止运行脚本PowerShell 执行策略限制执行Set-ExecutionPolicy RemoteSigned运行 claude 后卡在登录网络无法访问 Anthropic检查网络或使用第三方兼容接口输出乱码终端编码不是 UTF-8执行chcp 65001或换终端字体表格里的问题基本都是环境问题。尤其是 Windows 用户我强烈建议先安装 Windows Terminal它比老版 cmd 和 PowerShell 的兼容性好很多乱码概率低。6.2 限额与订阅相关提示热词里有一条“your limits are temporarily boosted. your weekly claude code limit is 50% hi”。这个是 Anthropic 在某种订阅套餐下给出的临时额度调整提示意思是你的每周限额被暂时提高了 50%并不是报错只是通知。看到它正常继续用就行。还有一条“your organization has disabled claude subscription access for claude code”。这个我在第 2 章提过是组织管理员关闭了 Claude Code 的订阅访问。解决办法是让管理员在 Anthropic 控制台打开权限或者改用个人账号。如果你遇到的是 API 账单余额不足通常会看到 429 或 401 错误。429 是限流需要等待401 是 API Key 不对检查ANTHROPIC_AUTH_TOKEN是否设置正确。6.3 不支持的模型名称报错“glm-5.2 is not a model this version of claude code recognizes”这类报错核心原因是当前 Claude Code 版本不认识你指定的模型名。第三方模型接入时模型名要么是官方接口支持的别名要么需要你自己写映射。解决思路很简单升级 Claude Code 到最新版打开官方文档查当前支持的模型名列表如果你用的是第三方兼容接口确认对方提供的模型名是否准确。比如接入 DeepSeek很多服务要求把模型名写成deepseek-chat而不是deepseek-v3。写错就会出现“not a model this version”的提示。遇到这种错误别慌先查配置再重启。6.4 插件和本地模型使用中的其他坑VSCode 插件偶尔会出现“连接失败”或“会话异常”多半是插件版本和 CLI 版本不一致。先升级插件再npm update -g anthropic-ai/claude-code就能解决大部分问题。Ollama 接入时常见错误是请求超时。原因是本地模型没启动或模型名写错。可以先在终端里用ollama list确认模型存在再用 curl 测试接口是否可用。不要一上来就怪 Claude Code很多问题出在本地服务。7. 入门期建议Codex还是Claude Code怎么选7.1 先拿小项目练手我见过太多人一上来就丢一个巨大仓库给 Claude Code然后抱怨“它怎么这么笨”。其实它不是你它也需要一步步理解项目。建议第一次用找一个你自己熟悉的小项目比如一个几千行的 Python 脚本或一个简单的前端页面然后试着让它完成一个小需求。因为你知道正确答案所以能判断它的输出是否靠谱也能更快摸索出怎么下指令效果最好。等你熟悉了它的工作节奏再逐步应用到陌生项目。这个过程中你会自然积累出一套属于自己的“指令风格”比如哪些词它会误解哪些表达能一步到位。7.2 培养几个好习惯根据我这段时间的实操几个习惯能明显提高使用体验每次只给一个明确任务。别让它“优化整个项目”而是“把 login 函数拆成两个函数并补测试”。重要操作前先问。如果它要删除文件或修改大量代码先让它说明计划再执行。经常看 diff。Claude Code 改完代码后花几秒钟扫一眼改动能避免很多潜在问题。用 Git 做保险。进入项目前先确保工作区是干净的如果它改乱了一条git checkout .就能恢复。这些习惯不是限制而是保护你自己。毕竟 AI 也会犯错你要做的是让它帮你省时间而不是替你做决定。7.3 Codex和Claude Code怎么选回到很多人纠结的问题选 Codex 还是 Claude Code我的判断标准很简单如果你更常用 OpenAI 生态或者需要和 GPT 系列模型联动优先考虑 Codex。如果你看重代码理解和长时间运行的稳定性我会推荐 Claude Code。如果你只是想体验两个都装也不冲突它们各自有 free tier 或试用额度可以用真实项目跑一轮对比。但我不建议今天换这个明天换那个。工具只是工具真正值钱的是你对项目的理解和对问题的拆解能力。选定一个用两个星期把它融入自己的日常工作流比纠结“哪个更强”更有意义。最后再分享一个小技巧Claude Code 开箱自带一些角色的能力你可以用claude 你是资深前端专家帮我 review 一下 components 目录这种前置身份设定输出质量会有明显提升。很多人不知道这个玩法其实比单纯的“请帮我看看”有效多了。我个人在实际使用中的体会是真正拉开效率差距的不是模型本身而是你愿不愿意花时间调教它、给它清晰的目标和上下文。Claude Code 给的是动手能力但方向感还是要你自己把握。希望这篇文章能让你少踩几个坑顺利把 Claude Code 用起来。