1. 为什么我会把 Claude Code 装进终端而不是继续用网页版聊天我最早用 AI 编程助手的方式和大多数人一样网页上开一个对话框把代码整段贴进去问它哪里有 bug再把它给的修改复制回编辑器。一天下来大部分时间都耗在“复制—粘贴—对比—再粘贴”上而且一遇到跨文件的改动就崩——贴少了上下文它理解不了贴多了又超过窗口限制。直到我把 Claude Code 装进本地终端才发现“AI 改代码”这件事应该换一种用法。Claude Code 不是一个挂在网页后面的聊天窗口它是一个直接跑在项目目录里的命令行工具。你告诉它需求它自己读文件、搜代码、改代码、跑测试然后把每一步操作摆在桌面上等你确认。你要做的不是帮它搬代码而是像部门负责人一样看它提交的改动方案点头或摇头。这篇完整入门教程我会沿着自己从安装到完成第一次代码修改的真实路径走一遍环境检查、npm 安装、登录授权、首次会话、一个带测试的实战改动、VSCode 集成、第三方模型接入以及新手时期最容易遇到的几个报错。适合那些刚听说 Claude Code、想跟着一步步把它跑起来的人也适合已经在用但总觉得“没玩明白”的开发者。先说一个基本判断Claude Code 的门槛不在命令在于你是否适应“让 AI 直接动文件”这种工作方式。如果连 Git 回滚都不熟建议先把心态调整好——它改代码的能力越强你越需要一套保障机制。这个后面会展开讲。1.1 它和网页版聊天的本质区别网页版 Claude 是一个“顾问”你负责把所有材料递到它面前Claude Code 是一个“执行者”它自己会去文件系统里翻材料。具体来说它具备三件网页聊天没有的能力读写项目文件。它能打开你项目里的任意文件定位到具体行然后直接修改。执行终端命令。它可以运行测试、跑构建脚本、查看 git 状态甚至替你执行一些低风险指令。感知项目结构。你不用把整个目录贴给它它自己会看 README、找入口文件、追踪函数调用链。这三件事合在一起把“讨论代码”变成了“交付代码”。我自己的感受是网页版适合问“这段逻辑哪里有问题”Claude Code 适合说“把这个需求落地成代码搞定它”。1.2 适合什么样的人不适合什么样的人适合的人非常明确手上有一个真实项目愿意花半小时学会命令行并且对代码被改动这件事有基本掌控力的人。不管你是写 Python、JavaScript、C 还是做嵌入式只要项目在本地它都能接。不适合的人我也直说。第一种是完全不懂 Git 的因为你会很难判断它改了什么也难在出错时恢复现场。第二种是希望“零成本白嫖”的Claude Code 的登录需要付费订阅或 API 额度这不是一个完全免费的工具。第三种是心态上接受不了“AI 碰生产代码”的——这种朋友建议先在副本仓库里玩别一上来就拿业务项目练手。2. 动手安装前先把 Node.js 和 Git 这两个底座盘清楚很多人在安装 Claude Code 时翻车不是工具本身的问题而是前置环境没有准备好。Claude Code 是一个 npm 包这意味着你的电脑上必须先有 Node.js 和 npm它又要操作 git 仓库所以 Git 也是刚需。2.1 三条命令快速自查打开终端Windows 用 PowerShell 或 Git BashmacOS 用 Terminal依次输入下面三条命令node -v npm -v git --version只要这三条命令都能打印出版本号环境就算达标。如果哪一条提示“不是内部或外部命令”或“command not found”就说明对应的软件没装或者没加入系统环境变量。Node.js 的版本建议不低于 18我实测 20 以上的 LTS 版本最省心。版本太老会导致 Claude Code 启动时报错而且报错信息不太直白容易让人误以为是安装出了问题。2.2 Windows 安装时特别容易忽略的两件事Windows 上安装 Node.js 和 Git 本身是“一路 Next”的事但有两点经常被忽略第一安装完成后必须重新打开一次终端。很多新手装完软件发现命令仍然不可用其实只是因为终端窗口是在安装之前打开的没有读取到新的环境变量。关掉重开或者直接重启电脑问题就没了。第二Git 安装时有个选项叫“调整 PATH 环境变量”一定要选默认的“Git from the command line and also from 3rd-party software”。选了这个选项PowerShell 里才能直接用 git 命令选成另外两个后面 Claude Code 调用 Git 时就会经常抽风。macOS 用户相对省事Node.js 建议用官网 pkg 安装包Git 用系统自带的或者通过 Homebrew 装都行。Linux 用户只要记得用发行版包管理器装 nodejs、npm、git再注意一下 npm 的全局目录权限即可。2.3 为什么要“先有 Git 仓库”再用它改代码这一条我想单独拎出来说因为它决定你后面用得安不安全。Claude Code 修改文件是真实的、落盘的改。改坏了怎么办靠 Git 回滚。所以我强烈建议第一次用它之前先确保你的项目已经在一个 Git 仓库里。哪怕只有一次提交都行那是一个可以退回的锚点。我自己给团队讲这个工具时永远会重复一句话“让 AI 改代码本质上和你自己改代码一样——在 Git 仓库里你怎么改都不怕不在 Git 仓库你怎么改都心虚。”如果你手头的项目还没有纳入 Git我建议花五分钟先git init并做一次初始提交。这是整个使用过程中性价比最高的一道保险。3. 正式安装 Claude Codenpm 全局安装与登录授权环境准备好了接下来进入安装环节。这一步比想象中简单真正让人卡住的反而是登录授权我单独说明。3.1 一条命令装完验证版本Claude Code 官方的标准安装方式就是通过 npm 全局安装npm install -g anthropic-ai/claude-code装完后执行claude --version能输出版本号就说明安装成功了。整个安装过程一般几十秒取决于网络状况。如果安装过程中报权限错误EACCES千万别急着用 sudo 硬装。正确做法是先卸载全局 npm 包然后通过 nvmNode Version Manager重装一个 Node.js这样 npm 的全局目录就在用户目录下了不会再碰到权限问题。这一步不值得偷懒后面每次装全局工具都会受益。注意不要从不明第三方网站下载“Claude Code 安装包”或“桌面版整合包”。它的生命线是 npm、官方 GitHub 仓库和官方应用商店。信不过的来源只会给你带来未知风险而不是便利。3.2 首次登录的三种方式和我的选择建议安装完成后直接在项目目录里执行claude它会提示你登录授权。常见的登录路径有三条登录方式适用场景我的评价个人 Claude 订阅账号日常个人开发推荐体验最顺Anthropic 控制台的 API Key按量付费、有自己用量统计需求适合脚本化用法团队/企业账号公司统一管理注意管理策略限制这里有一段非常现实的踩坑经验如果你使用的是公司邮箱注册的账号登录时很容易碰到一个提示大意是“你的组织已禁用 Claude 订阅访问”。这不是你的电脑出问题也不代表安装失败而是企业管理员在后台把 Claude Code 的订阅通道关掉了。个人自用的话老老实实用自己的付费订阅账号登录最省心。首次登录成功后Claude Code 会生成一个本地凭证后续一段时间内不需要重复登录。如果换网络环境或者凭证过期在会话里重登一次即可。3.3 升级与卸载这个工具迭代很快官方几乎每周都有更新。升级同样是 npm 一条命令npm update -g anthropic-ai/claude-code卸载则是npm uninstall -g anthropic-ai/claude-code我自己的习惯是每个月主动升级一次。不是因为它不升级就不能用而是新版本通常会修掉一些权限、解析或兼容性问题升级后那些说不清的零散报错往往自己就消失了。4. 第一次启动进入项目目录先别急着让它改代码安装成功只是开始真正的高频翻车点出现在第一次启动后的对话里。很多人上来就甩一句“帮我优化这个项目”然后 Claude Code 刷了一屏操作完全失控——这是预期的教训AI 再强也需要你先给它画一张地图。4.1 在哪个目录启动最合适Claude Code 的工作范围默认是“当前目录及其子目录”。所以启动前先cd到目标项目根目录不要在一个杂乱的用户主目录里启动它。比如我的一个实践项目放在~/workspace/timelog那就这样启动cd ~/workspace/timelog claude启动后它会扫描目录结构并在会话里显示当前处于哪个项目下。确认工作目录正确是避免“它改错文件”的第一道防线。4.2 交互授权第一次发生什么第一次在真实项目里启动时Claude Code 会请求一系列权限。它想读文件、想执行命令、想改代码之前都会在终端里弹出操作确认由你决定放行还是拒绝。很多新手被这种“步步确认”吓到其实这是它最值得信赖的地方。你可以把权限理解为“让实习生进仓库干活但每一笔操作都要你签字”。刚开始建议保持这个确认机制开着等熟悉了它的行为模式再考虑在配置文件里放行一些低频安全操作。4.3 第一次对话应该说什么我最推荐的第一次对话不是提需求而是先让它“看项目”。可以在会话里输入这样一段话先不要动手改任何文件。帮我梳理一下这个项目的整体结构说清楚入口文件、核心模块和现有的测试然后再告诉我如果我想做 X最合适的改动点在哪里。这个动作有几个好处第一让它把上下文载入会话第二你能看到它对项目的理解是否准确第三它会主动暴露项目里可能存在的一些“坑”比如某个模块特别复杂、某个文件牵着一堆依赖。等它梳理完你再决定下一步改什么。我见过太多人跳过了这一步直接让 AI 动手结果它在错误的方向上折腾了十分钟——不是它不行是你没给它看图就让它画图。用到这里你已经完成了 Claude Code 的安装、登录和首次项目会话。下面进入这篇教程的核心从一次真实需求出发完成第一次代码修改。5. 第一次代码修改真实记录加法、测试、提交一条龙前面铺垫了那么多现在进入正题让 Claude Code 完成一次真实的代码修改。我用一个实际的小项目来说明整个过程你可以对照这个流程在自己的项目上复现。5.1 我挑的实践项目与需求项目是一个 Python 写的命令行时间记录工具timelog功能是记录每天的时间段。它已经有一个cli.py用 argparse 接收参数比如add、list、report。我提的需求很具体给这个工具加一个--dry-run参数。加了之后执行任何会写入数据的命令时系统只打印“将要执行的动作”不真正写文件。这个需求虽然不大但它会牵涉到参数解析、命令分发、测试用例三个地方非常适合第一次体验完整流程。5.2 完整交互过程复盘我启动 claude 后第一句话是“看下 cli.py 里 argparse 部分我想加一个全局参数 --dry-run在执行写入类操作时只预览不执行。”Claude Code 接着做了这么几件事先搜索了cli.py定位到参数定义区域再用 grep 找到了所有执行写入的调用点然后列出修改计划问我“是否允许修改以下 3 个文件”。确认之后它开始动手在 argparse 里加了--dry-run参数定义在命令分发函数里加了一个上下文标记在写入数据的函数入口处档了一道检测到标记就打印预览并跳过写文件每个文件改完终端里都会展示 diff我快速扫了一眼发现它的改动位置确实是之前梳理时提到的三个点没有越界于是继续。接着我做了一件最关键的验证动作我说“跑一下测试”。它执行了python -m pytest -q结果爆出一个失败——这个失败我非常熟悉因为老的测试用例直接调用了写入函数没有适配新的参数流。我没有自己动手修而是把这半句话丢给它“测试挂了看下是否是 --dry-run 改动导致的如果是把涉及到的测试用例同步更新。”Claude Code 分析了失败堆栈确认是参数签名变化导致的然后把三个测试用例补上了新的参数重新跑测试全部通过。整个过程没有手写一行代码但我始终知道它在干什么、改了什么、为什么改。5.3 修改完成后必做的三道检查AI 说“完成”不等于真的完成。每次让 Claude Code 改完代码我都会亲自做三道检查缺一不可看 git diff。逐文件扫一遍确认没有改到计划外的文件确认没有把调试代码带进来。跑一次全量测试或构建。如果项目没有测试就手动执行一次核心功能亲眼看到结果符合预期。用 git status 确认工作区状态。如果发现多了些奇怪的文件果断删掉。这三道检查做完我才允许它提交。提交信息我也是让它生成的但我会在提交前再读一遍改掉那些“update”这种没营养的描述。5.4 从这次体验里提炼的协作经验第一次完整跑下来后我总结了几条很实在的协作守则需求越小越好。让它“加一个参数”远比“重构这个项目”容易控制。先说清楚边界。在让它动手前可以加一句“只改 cli.py 和 tests 目录不要碰其他模块”。重大改动要求分步执行。如果改的是核心模块我会说“先告诉我方案不要立即动手”。让 AI 自己修测试。这是它最实用了之处但前提是测试本身要可靠烂测试会带坏 AI。这套流程下来“第一次代码修改”已经顺利落地。接下来要解决的问题是如何让它更自然地融入日常开发环境。6. 和 VSCode 组队终端之外的另一套配置方案虽然 Claude Code 的默认形态是终端工具但绝大多数人的日常编码还在编辑器里。这里我给出两套和 VSCode 组队的方案以及如何用配置文件把使用习惯固化下来。6.1 双轨使用的部署方式第一种方案是最简单也最不容易出错的方式在 VSCode 里打开项目用快捷键打开集成终端然后直接运行claude。好处是左边的编辑器窗口天然成为你的“审计台”——Claude Code 改完文件后VSCode 的源代码管理面板会立刻显示改动你点开文件就能看 diff比在终端里看上下文舒服得多。第二种方案是安装官方提供的 VSCode 扩展。装好后可以在编辑器里以面板的方式操作 Claude Code界面更友好。我的实际体验是扩展和终端命令底层是同一条通路不是两个割裂的工具。如果你喜欢“不离开编辑器”的体验装扩展没问题如果你更信任纯终端不装扩展也不影响任何核心功能。6.2 settings.json 与 CLAUDE.md把我的习惯写进配置Claude Code 支持通过配置文件固化使用偏好。全局配置文件一般在~/.claude/settings.json如果某个项目想单独定制可以在项目下建.claude/settings.json。下面是一个常见的最小配置示例{ permissions: { allow: [ Read(scripts/**), Edit(scripts/**), Bash(npm test) ], deny: [ Bash(git push origin main) ] }, env: { ANTHROPIC_MODEL: claude-sonnet-4-5 } }注意字段名和可用值会随版本更新变化最稳妥的方式是用会话里的/config命令交互式配置把配置结果写回去而不是手敲一份可能过时的 JSON。除了 settings.json还有一个文件值得从第一次使用就建立起来项目根目录下的CLAUDE.md。这个文件是你的“项目移交说明”Claude Code 每次进入会话都会读取它。你可以在里面写清楚项目的技术栈和目录约定代码风格要求测试命令和构建命令哪些目录不要碰常用的业务术语我就吃过不写 CLAUDE.md 的亏有一回项目里混用了两套命名风格Claude Code 每次改代码都随机挑一套后来我在 CLAUDE.md 里写死“新代码统一用 snake_case”再没有出现过这个问题。6.3 权限控制给初学者的安全感新手最没有安全感的时刻就是看着 AI 准备执行命令。settings.json 里的权限控制就是为了解决这个问题。我建议第一周至少把下面这些操作放进 deny 列表强制推送远端分支的命令删除分支的命令非测试目的的包管理全局安装命令没有任何提示的批量文件删除等到你对它的行为模式足够熟悉、对项目的保护机制足够信任再逐步把 deny 改成更宽松的策略。权限控制不是用来“锁死工具”的而是让你在它面前始终保有否决权——这就是安全感本身。7. 换模型路线接入 DeepSeek、Qwen、GLM 或本地模型的实测心得Claude Code 默认用的是 Anthropic 官方模型很多人不知道的是它其实预留了换模型的环境变量通道。这个话题最近搜索量很大我把我试过的经验整理一下。7.1 原理一套代码两个环境变量Claude Code 读取两个关键环境变量来决定请求到哪里去、用什么身份ANTHROPIC_BASE_URL修改 API 服务地址指向兼容 Anthropic 接口的服务商或网关。ANTHROPIC_AUTH_TOKEN修改身份凭证换成目标服务商分配的令牌。设置好后启动claude它就会把请求发到新的地址上。这意味着理论上只要能提供 Anthropic 兼容接口的服务都可以被 Claude Code 调用。DeepSeek、Qwen通义千问、GLM智谱等模型服务如果服务商提供了 Anthropic 兼容的接入点就能用这套方式接进来。我实际体验下来的结论是这条路可行但不要期待每个模型都能和官方模型表现一致。原因不是模型“笨”而是 Claude Code 的交互高度依赖“工具调用”能力——模型必须能理解何时该读文件、何时该执行命令、何时该返回一个结构化的编辑动作。有些模型聊天很强但在工具调用协议上不够稳定就会出现“能对话、不能动手改代码”的情况。7.2 本地模型LM Studio / Ollama为什么有的能改文件有的只能聊天我试过用 LM Studio 跑本地模型也试过用 Ollama 加载 Qwen 系列发现结论高度一致本地小模型想稳定地完成“找文件—改代码—跑测试”这条链路成功率远低于云端大模型。这不完全是模型质量问题而是协议栈的问题。Claude Code 发出的是 Anthropic Messages 格式的请求里面包含工具定义。本地模型服务如果是 OpenAI 兼容接口格式不匹配就需要额外的网关层来做格式转换。即便格式转换过关小模型的上下文窗口往往有限项目代码稍微大一点它就“记不住前置约定”改着改着就跑偏。我见过有人用 Ollama 跑 Qwen3想让它“操作电脑修改代码”最后停留在“能打字聊天不能真正稳定操作文件”的状态原因就在这里。不是操作不了是链路缺了太多环节。如果你想在本地跑我的建议是把它当作“理解代码的参谋”而不是“能落地的执行者”这样期待值比较合理。7.3 第三方模型切换工具的实际用法因为切换环境变量比较繁琐社区里出现了一些可视化切换工具比如常被提到的 CC Switch 之类的配置管理器。这类工具的本质是把多套 API 配置保存成不同方案点击即可切换底层的动作无非还是改写环境变量和凭证。使用这类工具时最需要留意的地方是“填入的接口地址和令牌必须对得上”。很多人配置失败并不是工具不好用而是抄错了服务商给的地址或者把 OpenAI 兼容地址当作 Anthropic 兼容地址填了进去。接入前先确认服务商的文档里是否明确写了“Anthropic 兼容”或“Claude Code 支持”再动手配置。我个人的原则是官方模型用于日常开发主力第三方兼容模型用于试探性需求、成本敏感场景本地模型用于隐私敏感且对成功率要求不高的实验。这样既省钱又不牺牲效率。8. 新手高频报错排查0x800、订阅禁用、EACCES 一个都不能慌第一次安装使用 Claude Code几乎每个人都会碰上至少一个报错。下面这几个是我见过最多、搜索热度也最高的连同排查思路一起写在这里。8.1 Windows 报错 0x800 InternetOpenUrl failed这是 Windows 平台上比较有代表性的一类报错字面意思是某个网络 API 调用失败常见表现是执行claude相关操作时终端弹出一段类似internetopenurl() failed. 0x800的提示。我的排查顺序是这样的先确认基本网络连通性能否正常访问外网服务。如果其他联网软件正常先排除“断网”这个低层原因。检查系统里是否残留了“旧的网络进出口配置”。这类残留多半是以前调试工具时设下的Node 进程会读到它们导致请求被送到一个已经失效的地址。检查终端环境变量里的 HTTP 相关条目如果有指向失效地址的值先将它清掉再重试。在 Windows 的管理员命令行里执行系统网络恢复命令把网络通道恢复为系统默认值然后重启终端再试。经过这几步绝大多数 0x800 都能解决。这个报错的本质不是你装错了 Claude Code而是请求没能从干净的通道发出去。8.2 Your organization has disabled Claude subscription access for Claude Code这条报错的场景我前面已经提到过当你用企业邮箱或组织托管的账号登录时管理后台可以单独关闭 Claude Code 的订阅通道。关闭之后哪怕你的订阅本身是有效的Claude Code 也会直截了当地拒绝启动。排查思路也很清晰可能性处理方式公司账号被管理员禁用用个人订阅账号登录或联系管理员开启通道登录到了企业入口退出并重新登录确认进入的是个人账户想用按量计费改用 API Key 方式授权绕开订阅通道限制如果你只是想自己写代码最省心的方案永远是把个人工作和公司账号彻底分开。这也算一个安全提醒别把个人代码工作绑在公司账号体系里。8.3 其他两个高频坑Node 版本和 npm 权限Node 版本过低的表现是很隐晦的Claude Code 装好了登录了一跑就崩报错信息指向某个不相干的模块。你大概率想不到是 Node 的锅。我的建议是直接上 20 以上的 LTS 版本省掉很多“莫名其妙”的兼容问题。npm 全局安装时的 EACCES 权限报错处理方式前面也说了不要 sudo不要胡乱改全局目录权限直接用 nvm 重装 Node 最干净。这一步做好了后面装任何全局工具都不会再遇到同类问题。9. 关于桌面版、长上下文、嵌入式开发的几个热门搜索题外话最后一部分我想把近期搜索热度特别高的几个话题一起回答掉。它们不直接影响“从安装到第一次代码修改”这条主线但确实卡住了不少人。9.1 桌面版怎么装Claude Code 除了命令行形态官方也提供桌面版应用适合不喜欢纯终端操作的人。下载时记住一个原则只走官方渠道在官网或官方应用市场直接获取安装包不要绕道第三方。安装过程和其他桌面软件没有本质区别装好后登录账号即可。如果从官网渠道下载或更新时不够顺畅先检查网络环境是否正常重试或者错峰下载但不要去找来路不明的“特殊安装包”这点比安装本身更重要。9.2 长上下文不是万能的很多人冲着大上下文窗口来用 Claude Code觉得既然能装下更多代码我就可以把整个项目一股脑丢进去。实测下来的感受是大上下文确实能减少“它忘记前面说过什么”的频次但不代表你可以无限堆叠。上下文越大请求处理越慢费用也越敏感而且过长的上下文里往往塞满了无效信息反而稀释了它对关键内容的注意力。我的经验是让会话保持“单任务”粒度做完一个大改动就开新会话实在需要延续时把CLAUDE.md和核心需求重新说一遍比拖着一个超长会话硬撑更可靠。官方后续如果在上下文长度上继续扩展那是锦上添花但你自己的对话管理习惯才是长期稳定的决定因素。9.3 嵌入式场景STM32的真实体验我在 STM32 项目上也试用过 Claude Code。它的价值集中在两方面一是快速解释现有代码库帮你把寄存器配置、中断回调这些散落的逻辑串起来二是处理编译报错把一堆晦涩的构建输出翻译成人话并给出修改建议。但嵌入式场景有它天然的边界真正的硬件调试、示波器量波形、看时序这些事 AI 干不了也不会替你跑下载器。所以我的建议是把 Claude 定位成“熟悉代码、能写测试逻辑的搭档”而你自己牢牢守住硬件和烧录这最后一道关。用它写出来的底层驱动务必逐行确认后再上板。9.4 本地小模型想“操作电脑”为什么会失败最后说说那个反复被问到的问题本地小模型比如通过 Ollama 跑 Qwen 系列能不能操作电脑、修改代码失败的原因前面拆过一半协议兼容、上下文有限、工具调用不稳定。还有一个容易被忽略的盲区——很多本地模型根本没有接受过“在真实文件系统里操作”的强化训练它能写出一段看起来对的代码但不具备“定位到第几行、替换哪个区块”的能力。这和网页聊天是完全两种能力不能混为一谈。如果真的很想在本地实现类似效果建议不要把目标设成“替代 Claude Code”而是选一个大模型能稳定承担的窄任务比如“阅读指定文件并解释逻辑”“生成单文件脚本草稿”。窄任务对工具调用的要求低本地模型更容易胜任。从安装环境检查到第一次代码修改落地再到 VSCode 配置、模型切换、报错排查这条路径我已经来回走过了很多遍。说说我个人最终的体会Claude Code 真正改变的不是“谁在写代码”而是“谁来检查代码”。它把执行速度提升到一个人类短期内追不上的级别也让“审查”这件事变得前所未有地重要。你越会看 diff、越熟悉自己的项目结构、越舍得花时间在配置和权限设计上这个工具带给你的收益就越大。第一次跑通之后不妨从一个最小的真实需求开始让它帮你完成一次改动——你会发现这种协作方式一旦上手就再也不想回到纯手工搬代码的日子了。