说实话我第一次看到 Claude Code 这个词是在一个技术群里看大家讨论“现在写代码都不自己敲了”。当时我以为是又一个套壳的聊天框结果用它跑完一个真实项目的 bug 修复之后我才意识到这东西和网页版 AI 根本不是一回事。它不是“给你贴一段代码让你自己粘贴”而是在你的终端里直接读你的项目、改你的文件、执行你的测试命令最后把改动结果摆在你面前。这种“代理式开发”的体验用过一次就很难回去。这篇教程写给三类人第一类是完全没用过 Claude Code、连装都还没装的新手第二类是已经在用网页版 Claude、但想在 VSCode 或终端里把 AI 变成真正“会动手”的同事第三类是被“你的组织已禁用”这类提示卡住、想通过第三方 API 或本地模型把它跑起来的开发者。我会从环境准备、安装方式、接入模型选择一路讲到第一次代码修改的完整过程最后给你一份常见问题的排查速查表。内容里会带不少我实际踩过的坑希望能帮你少走弯路。1. 它到底是个什么东西和网页聊天有什么区别1.1 一个“会动手”的 AI 助手而不是话痨Claude Code 是 Anthropic 推出的命令行编码助手基于 Claude 大模型但它和你在网页上打开聊天框完全不是一种东西。它的核心不是“聊天”而是一个叫 harness 的代理框架。所谓 harness你可以理解成一个“套在模型外面的工作台”模型通过这个工作台能感知到当前项目的文件结构、能搜索代码、能读取文件内容、能编辑文件、能在你的终端里执行命令、能运行测试然后把每一步的反馈再拿回去继续推理。打个比方网页版 Claude 像一个坐在你旁边的顾问他给你出主意但活还是你自己干Claude Code 像一个接了工位并且有项目目录权限的兼职程序员你说“把这个按钮的 loading 状态加上”他会自己打开文件、定位组件、改好代码、跑一遍 lint然后告诉你“改完了测试通过”。这种“能直接干活”的能力才是它真正值钱的地方。这也解释了为什么它主要跑在终端而不是网页里。终端是一个天然的操作界面它可以执行命令、调用编译工具、读取环境变量这些是网页不可能给你的。你在网页上让 AI“帮我跑一下测试看看结果”它是做不到的但在 Claude Code 里这只是它的常规操作。1.2 它适合谁、不适合谁先搞清边界我在实际使用中的感受是Claude Code 适合的人群比想象中宽但有明确的边界。适合做这些事修 bug你描述现象它去定位代码、改逻辑、补测试。写新功能给它一个需求描述它能按现有项目风格写出完整实现。重构把一段混乱的代码整理成清晰结构它能先分析引用关系再动手。写测试让它为某个函数补充单测它会先读源码再生成用例。处理工程杂务改配置文件、批量替换、查依赖版本、生成变更日志。不太适合的事需要大量产品创意判断的早期设计它还是会做但容易做出一堆你觉得不对的东西。超大规模的全仓重构上下文有限建议把它控制在一个模块或子目录范围内。完全没有编程基础的人虽然它会动手但你至少要能看懂 diff否则它改错你没发现后果比不用它还严重。所以严格来说Claude Code 不是“程序员替代品”它是“程序员的外挂”。你跟它的配合越专业产出越可靠。1.3 为什么我建议从命令行版本开始现在 Claude Code 已经有桌面版、有 VSCode 插件、有 IDE 集成但我强烈建议你第一课从命令行版本开始。原因很简单所有这些图形界面本质上都是在一个终端里跑同一个 CLI 工具。你先把claude这个命令搞明白了之后配 VSCode、配桌面版都是水到渠成的事反过来一上来就点图形界面出了问题你会根本不知道去哪里查日志、改配置。而且命令行版本是最容易做“高级玩法”的地方接入第三方 API、切到本地模型、设置环境变量、写自定义脚本全部依赖 CLI 层面的能力。所以这篇教程的主线就是命令行图形界面作为配套讲。2. 装之前先搞清楚前置环境别急着敲命令2.1 Node.js 版本要求顺手解决 Windows 兼容报错Claude Code 是基于 Node.js 的 CLI 工具所以第一个前置条件是 Node 环境。官方要求 Node 18 以上但我实测下来 Node 22 LTS 最稳建议直接装 LTS 版本别用太新的 odd 版本也别用老掉牙的 16。这里先解决一个很多人搜到过的问题安装时报错“与 64 位版本的 Windows 不兼容”。这大概率不是 Claude Code 本身不支持你的电脑而是你的 Node 是 32 位版本或者 Node 版本太老。装完 Node 后用node -p process.arch看一下输出x64就说明是 64 位如果是ia32就是 32 位 Node去 Node 官网装 64 位版本重来。Windows 上推荐用官方安装包或winget install OpenJS.NodeJS.LTSmacOS 上可以用brew install nodeUbuntu 上我一般用curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -拉取后apt install -y nodejs。装完统一验证node -v npm -v输出版本号没报错就说明基础环境 OK。2.2 三种官方安装方式选一种就行Claude Code 官方提供了几种安装方式我自己最常用的、也最推荐的是 npm 全局安装npm install -g anthropic-ai/claude-code装完验证claude --version如果你没装 Node 也不想装可以用官方原生安装脚本它会自动下载一个独立的可执行文件macOS/Linux 一行curl -fsSL https://claude.ai/install.sh | bashWindows 上对应的是 PowerShell 脚本不过我个人不太喜欢这种方式因为更新和卸载都得重新跑脚本不如 npm 干净。还有一种就是桌面版安装包它把 Node 运行时和 CLI 都打包进了一个桌面应用里。这个我会在后面的章节专门讲因为它有个容易踩的配置隔离问题。安装完成后直接在终端输入claude首次启动会提示你登录。正常情况下会唤起浏览器登录你的 Claude 账号并授权终端使用。登录成功后终端里会出现一个提示符这就说明基本环境已经跑通了。2.3 登录与不登录的差异很多人问过“Claude Code 注册账号和不注册账号有啥不同”。我的理解是如果你用的是官方支持渠道登录是必须的因为要校验订阅身份如果你走第三方 API 或本地模型不登录也能跑因为这时候身份校验已经不在 Anthropic 这边了。但要注意不登录的用法本质上是把 Claude Code 当成一个“支持 Anthropic 协议的客户端壳子”你校验的是你接入的那个模型服务端。所以别以为不登录就白嫖了官方模型它只是意味着你可以换别的模型来驱动这个 harness。这个逻辑搞清楚了第三章的接入方式你就不会混。3. 接入方式与模型选择官方、第三方 API、本地模型3.1 官方订阅模式以及“组织禁用”问题如果你有 Claude 的 Pro 或 Max 订阅那直接用官方模式是最省心的。登录后选对应模型Claude Code 会通过你的订阅额度计费不另收 API 费用体验也很稳定。但这里有个很多人反馈的报错“Your organization has disabled Claude subscription access for Claude Code”。这个提示的意思是你当前所在的组织可能是公司统一管理的 IT 账号或工作区在策略层面禁用了 Claude Code 调用个人订阅。这不是你的账号出了问题而是企业管理员在后台配置的治理策略。遇到这个情况有三个合法处理方向一是联系管理员询问是否可以放行个人订阅接入二是让公司统一采购团队版或企业版授权三是不走官方订阅改用第三方 API 或本地模型的方式驱动 Claude Code。第三种方式是目前很多开发者实际在用的路径也完全属于 Claude Code 官方开放的接口能力。3.2 用兼容端点接入 DeepSeek、Qwen、GLM 等模型Claude Code 默认按照 Anthropic 的 API 协议和官方端点通信但它在设计上留了一个非常关键的口子允许通过环境变量指定自定义的 API 端点和认证令牌。官方文档里提供了一套环境变量最核心的是这两个export ANTHROPIC_BASE_URLhttps://你使用的api服务商地址 export ANTHROPIC_AUTH_TOKEN你的密钥设置这两个变量之后Claude Code 会把所有请求发到ANTHROPIC_BASE_URL指向的地址并携带ANTHROPIC_AUTH_TOKEN作为认证信息。这意味着只要有一个服务商提供兼容 Anthropic 协议格式的接口你就能直接驱动 Claude Code而不需要拥有 Claude 账号。这就是为什么你可以把 DeepSeek、Qwen、GLM 这些第三方模型接进来。这些模型本身大多走 OpenAI 格式的接口但不少服务商已经提供了 Anthropic 协议兼容层你只需要在服务商后台找到它给的 Base URL 和 Token填到上面两个环境变量里就行。如果某个模型的服务商没有直接提供 Anthropic 兼容端点那就需要走一层协议转换比如用本地代理工具把 OpenAI 格式转成 Anthropic 格式再喂给 Claude Code。我自己实际用下来这类方案的效果取决于两个因素一是模型本身的代码能力二是服务商的兼容层稳定程度。DeepSeek V4 这类模型在推理和代码生成上的表现在线接进来后写点常规代码、修 bug、补测试都没问题GLM 和 Qwen 的量化版本在轻量任务上也够用。如果你有多个供应商建议用一个配置管理工具来切换这个后面会讲到 cc-switch。3.3 本地模型通过 LM Studio 跑起来的实操如果你想彻底不依赖云服务或者想用完全免费的方案本地模型是一条值得尝试的路。搜索热词里“claude code 调用 LM Studio 的本地模型”是个高频需求我来说说实际怎么配。思路拆开LM Studio 是一个本地模型管理工具它可以加载 GGUF 格式的开源模型并在本地启动一个 OpenAI 兼容的 HTTP 服务。但 Claude Code 说的是 Anthropic 协议所以中间需要有一个协议转换层。常用的做法是装一个第三方适配器比如 claude-code-router 这类开源工具它可以把 Claude Code 发出的 Anthropic 格式请求转换并路由到 OpenAI 兼容的服务端。实操步骤大概是安装并打开 LM Studio下载一个适合你本地硬件的模型比如 Qwen2.5-Coder-7B 这种中等大小的代码模型。在 LM Studio 里启动本地服务器默认地址一般是http://localhost:1234/v1确认模型已加载。安装 claude-code-router并写好配置文件内容大致长这样providers: local: adapter: openai baseUrl: http://localhost:1234/v1 apiKey: local models: - name: qwen2.5-coder-7b配置好环境变量让 Clud Code 走这个 router然后启动后输入/model local/qwen2.5-coder-7b切换到本地模型。这个方案的真实体验是7B 级别的模型在简单任务上没问题但复杂多文件重构会明显吃力响应速度也取决于你显卡的性能。如果你有 NVIDIA 显卡可以考虑用专门的本地推理框架把模型规模拉到更大一档比如 32B 量化版本体验会有质的提升。本地模型适合对隐私敏感、或者只是想低成本体验流程的人不适合追求最强代码能力的人。3.4 cc-switch同时管理多个接入配置当你手上同时有官方账号、两三个第三方 API、还有本地模型的时候最烦的事情就是环境变量来回改。今天用 DeepSeek明天切 GLM后天切回官方每次都要检查ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN不小心就会把生产环境变量弄乱。cc-switch 就是来解决这个痛点的。它可以看作一个“配置管理器”你提前把每个供应商的 Base URL、Token、模型名等存成一个预设之后想切换到哪个供应商一条命令就把对应的环境变量全部换好。它本身不调用模型不做协议转换纯粹省掉你手工改配置的麻烦。我的建议是当你只有一组配置时不需要它当你开始在两三个接入方式之间反复横跳时赶紧装上节省的时间绝对值回成本。4. 实战从零到完成第一次代码修改4.1 准备一个实验项目别拿生产项目练手既然是第一次用我强烈建议你准备一个本地实验项目哪怕是个刚npm init出来的空项目都行。我的习惯是找一个 100% 确定没问题的开源小项目 clone 到本地比如一个简单的 Todo 应用这样我可以大胆地让 AI 随便折腾折腾坏了删掉重来完全不心疼。然后进入项目目录再启动cd my-demo-project claude注意这个工作目录就是 Claude Code 的“工作根目录”它所有的文件读取、命令执行都限定在这个目录及其子目录范围内。所以千万不要从根目录启动然后跟它说“帮我看看 /home/user/projects 下的 xxx”第一个是权限会拦你第二个是上下文容易混乱。启动成功后你看到提示符就是这个 AI 同事开始上班了。4.2 你的第一句指令以及它会干什么这里给一个我常用的开场指令模板请看一下这个项目的 package.json 和 src 目录先告诉我这个项目是做什么的然后帮我修复登录模块中处理 401 响应的逻辑最后运行一次测试确认修复没有破坏其他功能。你敲下回车之后Claude Code 会开始一系列动作先列出目录、读取相关文件然后向你确认“我准备修改 src/auth.js是否允许”同时还会请求“我准备执行 npm test是否允许”。这两个权限请求是它开始“动手”的信号你在交互界面选允许它就会继续。这个过程我第一次用的时候还挺震撼的它真的在自己翻文件而不是等我粘贴代码。如果一切顺利终端里会显示它的修改记录和测试输出比如“修复了 401 的误判新增了对 token 过期的判断所有测试通过”。到这里你的第一次代码修改就完成了。但别高兴太早——永远不要直接信任 AI 给出的测试通过结果。我后面会讲为什么。4.3 权限模式它能执行命令但你得管住它Claude Code 能执行终端命令这是它高效的核心也是它最有风险的地方。默认情况下每一次执行命令前它都会向你请求许可你可以选择“允许一次”或“始终允许”。当你选择了“始终允许”某个安全命令比如npm test、git diff后续遇到同类命令就会自动放行效率会高很多。但有两类命令我建议永远不要“始终允许”一类是删除类操作比如rm -rf、git reset --hard一旦误判就是灾难另一类是安装依赖类的命令比如npm install因为它可能会在不知情的情况下改变项目的依赖树。它有几种启动模式可以用比如claude --dangerously-skip-permissions从名字就能看出这个模式会跳过所有权限确认。这个模式只适合在隔离的容器或一次性实验环境里开日常开发千万不要用。你可以在交互中用/permissions命令查看和修改当前会话的权限设置。4.4 常用命令是你和它配合的“手势”Claude Code 交互界面里有一些斜杠命令第一次使用务必记住这几个/init让它在项目根目录生成一份 CLAUDE.md这是给后续会话看的项目说明包含代码风格、构建命令、注意事项等。/status查看当前会话消耗了多少上下文、已经改了哪些文件。/compact压缩历史上下文当对话太长、模型反应变慢或答非所问时用。/clear清空当前会话重新开始。/model切换模型配合你配置的多个提供商。/permissions管理权限规则。这些命令不需要死记关键是知道有这些“手势”在需要时能想起来去用。5. 和 VSCode 配合插件配置与解释5.1 插件其实就是“把终端搬进了编辑器”VSCode 搜索并安装官方 Claude Code 插件后最直接的用法是从命令面板里选择在集成终端中打开 Claude Code。本质上插件启动的还是同一个 CLI但它的价值在于你在编辑器里能看到 AI 修改文件时的高亮 diff能快速定位它改了哪几行还能用快捷键在“你的光标位置”和“AI 的对话上下文”之间建立交互关系。插件的配置项并不多大多是从~/.claude/settings.json这个配置文件读取的。这个配置文件按用户级、项目级、命令行参数三层叠加优先级是命令行参数 项目级 用户级。项目级的配置文件放在项目根目录的.claude/settings.json适合团队统一约定用户级的放在~/.claude/settings.json适合个人偏好。一个典型的用户级配置文件长这样{ permissions: { allow: [npm test, git diff], deny: [rm -rf] }, model: claude-sonnet-4-5, env: { ANTHROPIC_BASE_URL: https://你的/api, ANTHROPIC_AUTH_TOKEN: 你的key } }如果你之前用命令行配好过第三方 API但 VSCode 插件里却提示未登录或连接失败先检查这个配置文件里的env是否被插件正确加载。因为有些插件版本并不会读取当前 shell 的环境变量只认配置文件里的env。5.2 终端命令执行权限插件和 CLI 是同一套很多人问“Claude Code 如何直接执行终端命令”这个问题在 VSCode 插件里的答案和 CLI 完全一样它通过集成终端的通道执行命令权限规则也走同一套配置。你在插件里允许过的命令CLI 里同样生效因为它们共享~/.claude下的用户配置文件反过来也一样。我在插件里最常用的操作路径是先在编辑器中框选一段有问题的代码然后打开 Claude Code 聊天它会自动带上你选中的代码上下文你说“解释并为这个报错修复”它就能精准定位到文件。如果项目较大建议先在项目根目录生成一份 CLAUDE.md插件在每次会话时都会读取它做背景知识这能显著减少理解偏差。5.3 桌面版适合不想折腾 Node 的人桌面版是官方打包的一个独立应用内置了 Node 运行时和 CLI。它的优势是零依赖安装特别适合你只想打开就用的场景。但它有个我踩过的坑桌面版使用的配置和命令行版可能不是同一套环境如果你之前用命令行配好了第三方模型打开桌面版会发现“现场干干净净”。所以我的建议是如果你已经是命令行用户桌面版没必要装直接用 VSCode 插件就够如果你完全不想碰 Node 和终端桌面版可以一试但后续想做深度配置时你还是绕不开环境和配置文件的。6. 高频问题与排查速查表6.1 组织禁用订阅访问到底该怎么办这个刚才在接入方式里提过这里展开讲讲排查思路。你先确认自己是不是用了公司统一管理的账号比如工作邮箱注册的 Claude 账号、或者电脑上安装了组织策略托管软件。如果是那么即使你自己付费开了 Pro也会被策略拦截。合法处理路径有三条第一找管理后台放行这在企业采购了 Claude 相关服务的场景下可行第二走团队版让管理员统一开通第三改用第三方 API 或本地模型这是最简单的开发自选路径。如果你用的是个人电脑账号也是个人注册的但仍然看到这个提示优先检查是不是浏览器登录态串了换个独立的浏览器 profile 重新登录试试。6.2 地区不可用提示以及我不建议你做什么如果你启动时看到类似“might not be available in your country”的提示那说明该服务在你当前所在地区的可用性受到限制。这是服务提供方根据自身的合规策略做出的安排用户需要尊重这一边界。我的建议很简单不要尝试任何规避手段也不要轻信那些号称“稳定可用”的方案它们要么是骗局要么会让你的账号和电脑处于风险中。如果你确实需要把机制跑起来正当的选择包括使用对你所在地区开放的正规第三方 API 服务商、走本地模型方案、或者联系公司购买企业版通道。这些都是在规则允许范围内的做法。6.3 Windows 不兼容、登录失效、超时罢工把这几个高频问题合在一起说因为它们背后都有共同原因。“与 64 位版本 Windows 不兼容”的报错绝大多数是 Node 版本或 Node 架构问题按 2.1 节的方法处理基本都能解决。如果升级 Node 后仍然存在再检查是否用的是系统盘下的深度路径有些命令解析在长路径下会出问题把 npm 全局目录和项目路径都挪到短路径可以规避。登录接头突然失效大多是因为掉了刷新凭据。重新执行claude并按提示重新登录即可如果是在 CI 环境里考虑使用 API 密钥而不是网页登录态。模型中途“罢工”表现是响应特别慢、答非所问、或者固定重复一句话。绝大多数情况是上下文太长导致。这时候用/compact压缩上下文再补一句“继续”通常就能恢复。如果还没用就/clear开新会话并把关键背景信息重新给它一份。6.4 常见问题速查表报错或现象可能原因解决方式与64位Windows不兼容Node为32位或版本过老安装64位Node 22 LTS并验证process.archorganization has disabled...组织策略禁止个人订阅接入联系管理员 / 团队版 / 改用第三方API或本地模型might not be available in your country服务可用地区限制使用合规第三方API、本地模型不尝试任何规避手段登录态失效凭据过期重新登录检查是否用了错误浏览器profile模型响应变慢或答非所问上下文过长使用/compact压缩必要时/clearVSCode插件不读环境变量插件只认配置文件env在settings.json中加入env字段7. 最后一些个人实操体会如果你能看到这里我猜你已经不只是想“看一篇教程”了而是打算真正把它跑起来。那在动手之前我再分享几条实操心得都是从我自己踩过的坑里爬出来的。第一千万别让它一路绿灯。我刚开始用的时候觉得“始终允许”很爽直到它有一次顺手执行了一个全局依赖更新把项目搞崩了。从那之后我所有的rm -rf和git reset --hard类命令都是手动确认哪怕慢一点也心安。第二代码改完之后一定要自己先看一遍 diff。AI 写的代码不一定错但它的风格可能和项目原有代码不一致也可能引入不必要的依赖。我在 review 中发现过它把业务逻辑直接写进组件里、导致复用性变差的情况。让 AI 出活可以但最终的责任始终在你这。第三每次会话最好只交一个任务。如果你让它“先修这个 bug顺便加个新功能再做一下性能优化”它的注意力会被稀释最后可能每个任务都做了但每个都不到位。我现在的习惯是一次会话只做一件事做完之后/clear然后开始下一件。第四个技巧是善用 CLAUDE.md。项目根目录里放一份简洁的说明告诉它项目的构建命令、测试命令、代码风格约束它的表现会有显著提升。你就把 CLAUDE.md 当成“给新入职同事看的入职手册”越清晰越省心。最后我第一次启动它时看着终端里那个光标闪了半天没反应我以为卡死了差点直接关掉。后来才知道那是它在思考。刚开始用的时候保持一点耐心给它一点时间完成第一轮分析和规划。当你看到它真正自己修改完第一个文件、并且跑通测试的那一刻你会来和我一样感叹这活儿以后真的可以交给它了。 Claude Code 完整入门：从安装配置到第一次实战代码修改
说实话我第一次看到 Claude Code 这个词是在一个技术群里看大家讨论“现在写代码都不自己敲了”。当时我以为是又一个套壳的聊天框结果用它跑完一个真实项目的 bug 修复之后我才意识到这东西和网页版 AI 根本不是一回事。它不是“给你贴一段代码让你自己粘贴”而是在你的终端里直接读你的项目、改你的文件、执行你的测试命令最后把改动结果摆在你面前。这种“代理式开发”的体验用过一次就很难回去。这篇教程写给三类人第一类是完全没用过 Claude Code、连装都还没装的新手第二类是已经在用网页版 Claude、但想在 VSCode 或终端里把 AI 变成真正“会动手”的同事第三类是被“你的组织已禁用”这类提示卡住、想通过第三方 API 或本地模型把它跑起来的开发者。我会从环境准备、安装方式、接入模型选择一路讲到第一次代码修改的完整过程最后给你一份常见问题的排查速查表。内容里会带不少我实际踩过的坑希望能帮你少走弯路。1. 它到底是个什么东西和网页聊天有什么区别1.1 一个“会动手”的 AI 助手而不是话痨Claude Code 是 Anthropic 推出的命令行编码助手基于 Claude 大模型但它和你在网页上打开聊天框完全不是一种东西。它的核心不是“聊天”而是一个叫 harness 的代理框架。所谓 harness你可以理解成一个“套在模型外面的工作台”模型通过这个工作台能感知到当前项目的文件结构、能搜索代码、能读取文件内容、能编辑文件、能在你的终端里执行命令、能运行测试然后把每一步的反馈再拿回去继续推理。打个比方网页版 Claude 像一个坐在你旁边的顾问他给你出主意但活还是你自己干Claude Code 像一个接了工位并且有项目目录权限的兼职程序员你说“把这个按钮的 loading 状态加上”他会自己打开文件、定位组件、改好代码、跑一遍 lint然后告诉你“改完了测试通过”。这种“能直接干活”的能力才是它真正值钱的地方。这也解释了为什么它主要跑在终端而不是网页里。终端是一个天然的操作界面它可以执行命令、调用编译工具、读取环境变量这些是网页不可能给你的。你在网页上让 AI“帮我跑一下测试看看结果”它是做不到的但在 Claude Code 里这只是它的常规操作。1.2 它适合谁、不适合谁先搞清边界我在实际使用中的感受是Claude Code 适合的人群比想象中宽但有明确的边界。适合做这些事修 bug你描述现象它去定位代码、改逻辑、补测试。写新功能给它一个需求描述它能按现有项目风格写出完整实现。重构把一段混乱的代码整理成清晰结构它能先分析引用关系再动手。写测试让它为某个函数补充单测它会先读源码再生成用例。处理工程杂务改配置文件、批量替换、查依赖版本、生成变更日志。不太适合的事需要大量产品创意判断的早期设计它还是会做但容易做出一堆你觉得不对的东西。超大规模的全仓重构上下文有限建议把它控制在一个模块或子目录范围内。完全没有编程基础的人虽然它会动手但你至少要能看懂 diff否则它改错你没发现后果比不用它还严重。所以严格来说Claude Code 不是“程序员替代品”它是“程序员的外挂”。你跟它的配合越专业产出越可靠。1.3 为什么我建议从命令行版本开始现在 Claude Code 已经有桌面版、有 VSCode 插件、有 IDE 集成但我强烈建议你第一课从命令行版本开始。原因很简单所有这些图形界面本质上都是在一个终端里跑同一个 CLI 工具。你先把claude这个命令搞明白了之后配 VSCode、配桌面版都是水到渠成的事反过来一上来就点图形界面出了问题你会根本不知道去哪里查日志、改配置。而且命令行版本是最容易做“高级玩法”的地方接入第三方 API、切到本地模型、设置环境变量、写自定义脚本全部依赖 CLI 层面的能力。所以这篇教程的主线就是命令行图形界面作为配套讲。2. 装之前先搞清楚前置环境别急着敲命令2.1 Node.js 版本要求顺手解决 Windows 兼容报错Claude Code 是基于 Node.js 的 CLI 工具所以第一个前置条件是 Node 环境。官方要求 Node 18 以上但我实测下来 Node 22 LTS 最稳建议直接装 LTS 版本别用太新的 odd 版本也别用老掉牙的 16。这里先解决一个很多人搜到过的问题安装时报错“与 64 位版本的 Windows 不兼容”。这大概率不是 Claude Code 本身不支持你的电脑而是你的 Node 是 32 位版本或者 Node 版本太老。装完 Node 后用node -p process.arch看一下输出x64就说明是 64 位如果是ia32就是 32 位 Node去 Node 官网装 64 位版本重来。Windows 上推荐用官方安装包或winget install OpenJS.NodeJS.LTSmacOS 上可以用brew install nodeUbuntu 上我一般用curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -拉取后apt install -y nodejs。装完统一验证node -v npm -v输出版本号没报错就说明基础环境 OK。2.2 三种官方安装方式选一种就行Claude Code 官方提供了几种安装方式我自己最常用的、也最推荐的是 npm 全局安装npm install -g anthropic-ai/claude-code装完验证claude --version如果你没装 Node 也不想装可以用官方原生安装脚本它会自动下载一个独立的可执行文件macOS/Linux 一行curl -fsSL https://claude.ai/install.sh | bashWindows 上对应的是 PowerShell 脚本不过我个人不太喜欢这种方式因为更新和卸载都得重新跑脚本不如 npm 干净。还有一种就是桌面版安装包它把 Node 运行时和 CLI 都打包进了一个桌面应用里。这个我会在后面的章节专门讲因为它有个容易踩的配置隔离问题。安装完成后直接在终端输入claude首次启动会提示你登录。正常情况下会唤起浏览器登录你的 Claude 账号并授权终端使用。登录成功后终端里会出现一个提示符这就说明基本环境已经跑通了。2.3 登录与不登录的差异很多人问过“Claude Code 注册账号和不注册账号有啥不同”。我的理解是如果你用的是官方支持渠道登录是必须的因为要校验订阅身份如果你走第三方 API 或本地模型不登录也能跑因为这时候身份校验已经不在 Anthropic 这边了。但要注意不登录的用法本质上是把 Claude Code 当成一个“支持 Anthropic 协议的客户端壳子”你校验的是你接入的那个模型服务端。所以别以为不登录就白嫖了官方模型它只是意味着你可以换别的模型来驱动这个 harness。这个逻辑搞清楚了第三章的接入方式你就不会混。3. 接入方式与模型选择官方、第三方 API、本地模型3.1 官方订阅模式以及“组织禁用”问题如果你有 Claude 的 Pro 或 Max 订阅那直接用官方模式是最省心的。登录后选对应模型Claude Code 会通过你的订阅额度计费不另收 API 费用体验也很稳定。但这里有个很多人反馈的报错“Your organization has disabled Claude subscription access for Claude Code”。这个提示的意思是你当前所在的组织可能是公司统一管理的 IT 账号或工作区在策略层面禁用了 Claude Code 调用个人订阅。这不是你的账号出了问题而是企业管理员在后台配置的治理策略。遇到这个情况有三个合法处理方向一是联系管理员询问是否可以放行个人订阅接入二是让公司统一采购团队版或企业版授权三是不走官方订阅改用第三方 API 或本地模型的方式驱动 Claude Code。第三种方式是目前很多开发者实际在用的路径也完全属于 Claude Code 官方开放的接口能力。3.2 用兼容端点接入 DeepSeek、Qwen、GLM 等模型Claude Code 默认按照 Anthropic 的 API 协议和官方端点通信但它在设计上留了一个非常关键的口子允许通过环境变量指定自定义的 API 端点和认证令牌。官方文档里提供了一套环境变量最核心的是这两个export ANTHROPIC_BASE_URLhttps://你使用的api服务商地址 export ANTHROPIC_AUTH_TOKEN你的密钥设置这两个变量之后Claude Code 会把所有请求发到ANTHROPIC_BASE_URL指向的地址并携带ANTHROPIC_AUTH_TOKEN作为认证信息。这意味着只要有一个服务商提供兼容 Anthropic 协议格式的接口你就能直接驱动 Claude Code而不需要拥有 Claude 账号。这就是为什么你可以把 DeepSeek、Qwen、GLM 这些第三方模型接进来。这些模型本身大多走 OpenAI 格式的接口但不少服务商已经提供了 Anthropic 协议兼容层你只需要在服务商后台找到它给的 Base URL 和 Token填到上面两个环境变量里就行。如果某个模型的服务商没有直接提供 Anthropic 兼容端点那就需要走一层协议转换比如用本地代理工具把 OpenAI 格式转成 Anthropic 格式再喂给 Claude Code。我自己实际用下来这类方案的效果取决于两个因素一是模型本身的代码能力二是服务商的兼容层稳定程度。DeepSeek V4 这类模型在推理和代码生成上的表现在线接进来后写点常规代码、修 bug、补测试都没问题GLM 和 Qwen 的量化版本在轻量任务上也够用。如果你有多个供应商建议用一个配置管理工具来切换这个后面会讲到 cc-switch。3.3 本地模型通过 LM Studio 跑起来的实操如果你想彻底不依赖云服务或者想用完全免费的方案本地模型是一条值得尝试的路。搜索热词里“claude code 调用 LM Studio 的本地模型”是个高频需求我来说说实际怎么配。思路拆开LM Studio 是一个本地模型管理工具它可以加载 GGUF 格式的开源模型并在本地启动一个 OpenAI 兼容的 HTTP 服务。但 Claude Code 说的是 Anthropic 协议所以中间需要有一个协议转换层。常用的做法是装一个第三方适配器比如 claude-code-router 这类开源工具它可以把 Claude Code 发出的 Anthropic 格式请求转换并路由到 OpenAI 兼容的服务端。实操步骤大概是安装并打开 LM Studio下载一个适合你本地硬件的模型比如 Qwen2.5-Coder-7B 这种中等大小的代码模型。在 LM Studio 里启动本地服务器默认地址一般是http://localhost:1234/v1确认模型已加载。安装 claude-code-router并写好配置文件内容大致长这样providers: local: adapter: openai baseUrl: http://localhost:1234/v1 apiKey: local models: - name: qwen2.5-coder-7b配置好环境变量让 Clud Code 走这个 router然后启动后输入/model local/qwen2.5-coder-7b切换到本地模型。这个方案的真实体验是7B 级别的模型在简单任务上没问题但复杂多文件重构会明显吃力响应速度也取决于你显卡的性能。如果你有 NVIDIA 显卡可以考虑用专门的本地推理框架把模型规模拉到更大一档比如 32B 量化版本体验会有质的提升。本地模型适合对隐私敏感、或者只是想低成本体验流程的人不适合追求最强代码能力的人。3.4 cc-switch同时管理多个接入配置当你手上同时有官方账号、两三个第三方 API、还有本地模型的时候最烦的事情就是环境变量来回改。今天用 DeepSeek明天切 GLM后天切回官方每次都要检查ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN不小心就会把生产环境变量弄乱。cc-switch 就是来解决这个痛点的。它可以看作一个“配置管理器”你提前把每个供应商的 Base URL、Token、模型名等存成一个预设之后想切换到哪个供应商一条命令就把对应的环境变量全部换好。它本身不调用模型不做协议转换纯粹省掉你手工改配置的麻烦。我的建议是当你只有一组配置时不需要它当你开始在两三个接入方式之间反复横跳时赶紧装上节省的时间绝对值回成本。4. 实战从零到完成第一次代码修改4.1 准备一个实验项目别拿生产项目练手既然是第一次用我强烈建议你准备一个本地实验项目哪怕是个刚npm init出来的空项目都行。我的习惯是找一个 100% 确定没问题的开源小项目 clone 到本地比如一个简单的 Todo 应用这样我可以大胆地让 AI 随便折腾折腾坏了删掉重来完全不心疼。然后进入项目目录再启动cd my-demo-project claude注意这个工作目录就是 Claude Code 的“工作根目录”它所有的文件读取、命令执行都限定在这个目录及其子目录范围内。所以千万不要从根目录启动然后跟它说“帮我看看 /home/user/projects 下的 xxx”第一个是权限会拦你第二个是上下文容易混乱。启动成功后你看到提示符就是这个 AI 同事开始上班了。4.2 你的第一句指令以及它会干什么这里给一个我常用的开场指令模板请看一下这个项目的 package.json 和 src 目录先告诉我这个项目是做什么的然后帮我修复登录模块中处理 401 响应的逻辑最后运行一次测试确认修复没有破坏其他功能。你敲下回车之后Claude Code 会开始一系列动作先列出目录、读取相关文件然后向你确认“我准备修改 src/auth.js是否允许”同时还会请求“我准备执行 npm test是否允许”。这两个权限请求是它开始“动手”的信号你在交互界面选允许它就会继续。这个过程我第一次用的时候还挺震撼的它真的在自己翻文件而不是等我粘贴代码。如果一切顺利终端里会显示它的修改记录和测试输出比如“修复了 401 的误判新增了对 token 过期的判断所有测试通过”。到这里你的第一次代码修改就完成了。但别高兴太早——永远不要直接信任 AI 给出的测试通过结果。我后面会讲为什么。4.3 权限模式它能执行命令但你得管住它Claude Code 能执行终端命令这是它高效的核心也是它最有风险的地方。默认情况下每一次执行命令前它都会向你请求许可你可以选择“允许一次”或“始终允许”。当你选择了“始终允许”某个安全命令比如npm test、git diff后续遇到同类命令就会自动放行效率会高很多。但有两类命令我建议永远不要“始终允许”一类是删除类操作比如rm -rf、git reset --hard一旦误判就是灾难另一类是安装依赖类的命令比如npm install因为它可能会在不知情的情况下改变项目的依赖树。它有几种启动模式可以用比如claude --dangerously-skip-permissions从名字就能看出这个模式会跳过所有权限确认。这个模式只适合在隔离的容器或一次性实验环境里开日常开发千万不要用。你可以在交互中用/permissions命令查看和修改当前会话的权限设置。4.4 常用命令是你和它配合的“手势”Claude Code 交互界面里有一些斜杠命令第一次使用务必记住这几个/init让它在项目根目录生成一份 CLAUDE.md这是给后续会话看的项目说明包含代码风格、构建命令、注意事项等。/status查看当前会话消耗了多少上下文、已经改了哪些文件。/compact压缩历史上下文当对话太长、模型反应变慢或答非所问时用。/clear清空当前会话重新开始。/model切换模型配合你配置的多个提供商。/permissions管理权限规则。这些命令不需要死记关键是知道有这些“手势”在需要时能想起来去用。5. 和 VSCode 配合插件配置与解释5.1 插件其实就是“把终端搬进了编辑器”VSCode 搜索并安装官方 Claude Code 插件后最直接的用法是从命令面板里选择在集成终端中打开 Claude Code。本质上插件启动的还是同一个 CLI但它的价值在于你在编辑器里能看到 AI 修改文件时的高亮 diff能快速定位它改了哪几行还能用快捷键在“你的光标位置”和“AI 的对话上下文”之间建立交互关系。插件的配置项并不多大多是从~/.claude/settings.json这个配置文件读取的。这个配置文件按用户级、项目级、命令行参数三层叠加优先级是命令行参数 项目级 用户级。项目级的配置文件放在项目根目录的.claude/settings.json适合团队统一约定用户级的放在~/.claude/settings.json适合个人偏好。一个典型的用户级配置文件长这样{ permissions: { allow: [npm test, git diff], deny: [rm -rf] }, model: claude-sonnet-4-5, env: { ANTHROPIC_BASE_URL: https://你的/api, ANTHROPIC_AUTH_TOKEN: 你的key } }如果你之前用命令行配好过第三方 API但 VSCode 插件里却提示未登录或连接失败先检查这个配置文件里的env是否被插件正确加载。因为有些插件版本并不会读取当前 shell 的环境变量只认配置文件里的env。5.2 终端命令执行权限插件和 CLI 是同一套很多人问“Claude Code 如何直接执行终端命令”这个问题在 VSCode 插件里的答案和 CLI 完全一样它通过集成终端的通道执行命令权限规则也走同一套配置。你在插件里允许过的命令CLI 里同样生效因为它们共享~/.claude下的用户配置文件反过来也一样。我在插件里最常用的操作路径是先在编辑器中框选一段有问题的代码然后打开 Claude Code 聊天它会自动带上你选中的代码上下文你说“解释并为这个报错修复”它就能精准定位到文件。如果项目较大建议先在项目根目录生成一份 CLAUDE.md插件在每次会话时都会读取它做背景知识这能显著减少理解偏差。5.3 桌面版适合不想折腾 Node 的人桌面版是官方打包的一个独立应用内置了 Node 运行时和 CLI。它的优势是零依赖安装特别适合你只想打开就用的场景。但它有个我踩过的坑桌面版使用的配置和命令行版可能不是同一套环境如果你之前用命令行配好了第三方模型打开桌面版会发现“现场干干净净”。所以我的建议是如果你已经是命令行用户桌面版没必要装直接用 VSCode 插件就够如果你完全不想碰 Node 和终端桌面版可以一试但后续想做深度配置时你还是绕不开环境和配置文件的。6. 高频问题与排查速查表6.1 组织禁用订阅访问到底该怎么办这个刚才在接入方式里提过这里展开讲讲排查思路。你先确认自己是不是用了公司统一管理的账号比如工作邮箱注册的 Claude 账号、或者电脑上安装了组织策略托管软件。如果是那么即使你自己付费开了 Pro也会被策略拦截。合法处理路径有三条第一找管理后台放行这在企业采购了 Claude 相关服务的场景下可行第二走团队版让管理员统一开通第三改用第三方 API 或本地模型这是最简单的开发自选路径。如果你用的是个人电脑账号也是个人注册的但仍然看到这个提示优先检查是不是浏览器登录态串了换个独立的浏览器 profile 重新登录试试。6.2 地区不可用提示以及我不建议你做什么如果你启动时看到类似“might not be available in your country”的提示那说明该服务在你当前所在地区的可用性受到限制。这是服务提供方根据自身的合规策略做出的安排用户需要尊重这一边界。我的建议很简单不要尝试任何规避手段也不要轻信那些号称“稳定可用”的方案它们要么是骗局要么会让你的账号和电脑处于风险中。如果你确实需要把机制跑起来正当的选择包括使用对你所在地区开放的正规第三方 API 服务商、走本地模型方案、或者联系公司购买企业版通道。这些都是在规则允许范围内的做法。6.3 Windows 不兼容、登录失效、超时罢工把这几个高频问题合在一起说因为它们背后都有共同原因。“与 64 位版本 Windows 不兼容”的报错绝大多数是 Node 版本或 Node 架构问题按 2.1 节的方法处理基本都能解决。如果升级 Node 后仍然存在再检查是否用的是系统盘下的深度路径有些命令解析在长路径下会出问题把 npm 全局目录和项目路径都挪到短路径可以规避。登录接头突然失效大多是因为掉了刷新凭据。重新执行claude并按提示重新登录即可如果是在 CI 环境里考虑使用 API 密钥而不是网页登录态。模型中途“罢工”表现是响应特别慢、答非所问、或者固定重复一句话。绝大多数情况是上下文太长导致。这时候用/compact压缩上下文再补一句“继续”通常就能恢复。如果还没用就/clear开新会话并把关键背景信息重新给它一份。6.4 常见问题速查表报错或现象可能原因解决方式与64位Windows不兼容Node为32位或版本过老安装64位Node 22 LTS并验证process.archorganization has disabled...组织策略禁止个人订阅接入联系管理员 / 团队版 / 改用第三方API或本地模型might not be available in your country服务可用地区限制使用合规第三方API、本地模型不尝试任何规避手段登录态失效凭据过期重新登录检查是否用了错误浏览器profile模型响应变慢或答非所问上下文过长使用/compact压缩必要时/clearVSCode插件不读环境变量插件只认配置文件env在settings.json中加入env字段7. 最后一些个人实操体会如果你能看到这里我猜你已经不只是想“看一篇教程”了而是打算真正把它跑起来。那在动手之前我再分享几条实操心得都是从我自己踩过的坑里爬出来的。第一千万别让它一路绿灯。我刚开始用的时候觉得“始终允许”很爽直到它有一次顺手执行了一个全局依赖更新把项目搞崩了。从那之后我所有的rm -rf和git reset --hard类命令都是手动确认哪怕慢一点也心安。第二代码改完之后一定要自己先看一遍 diff。AI 写的代码不一定错但它的风格可能和项目原有代码不一致也可能引入不必要的依赖。我在 review 中发现过它把业务逻辑直接写进组件里、导致复用性变差的情况。让 AI 出活可以但最终的责任始终在你这。第三每次会话最好只交一个任务。如果你让它“先修这个 bug顺便加个新功能再做一下性能优化”它的注意力会被稀释最后可能每个任务都做了但每个都不到位。我现在的习惯是一次会话只做一件事做完之后/clear然后开始下一件。第四个技巧是善用 CLAUDE.md。项目根目录里放一份简洁的说明告诉它项目的构建命令、测试命令、代码风格约束它的表现会有显著提升。你就把 CLAUDE.md 当成“给新入职同事看的入职手册”越清晰越省心。最后我第一次启动它时看着终端里那个光标闪了半天没反应我以为卡死了差点直接关掉。后来才知道那是它在思考。刚开始用的时候保持一点耐心给它一点时间完成第一轮分析和规划。当你看到它真正自己修改完第一个文件、并且跑通测试的那一刻你会来和我一样感叹这活儿以后真的可以交给它了。