Claude Code 实战指南：从安装到模型接入与排错全解析

如果你最近逛技术社区，八成会反复看到 Claude Code 这个名字。我花了一周时间，从命令行安装到 VS Code 集成，从官方模型切到本地模型，把能踩的坑基本都踩了一遍。这篇文章不打算照抄官方文档，而是按我实际操作的真实顺序，把 Claude Code 是什么、怎么安装、日常怎么用、怎么接第三方模型、怎么处理一堆报错，完整地捋一遍。不管你是刚听说想试试，还是已经装了一半卡在某个报错上，这篇应该都能帮上忙。

先说个结论：Claude Code 不是又一个聊天窗口式的 AI 助手，它是直接跑在终端里的 AI 编程代理，能读你项目里的文件、自己改代码、执行命令、提交 commit，甚至帮你排查线上问题。它解决的痛点是“AI 能听懂人话，但动不了手”，而 Claude Code 是把“听懂”和“动手”连起来的那个环节。下面我按自己的实操路径，把每个环节展开细讲。

1. Claude Code 到底是什么，解决什么问题

1.1 它和 ChatGPT、Claude 网页版的本质区别

很多人第一次听说 Claude Code 会问：这和我打开 Claude 网页版让它写代码有什么不一样？区别非常大。网页版聊天，是你复制粘贴代码片段，它给你生成一段回答，你再自己粘回去。整个过程里，AI 就像一个“顾问”，只动嘴不动手。Claude Code 不一样，它直接跑在你项目的终端里，它有权限读取你当前目录下的文件结构，可以打开文件、定位函数、修改代码、运行测试，然后根据运行结果自己决定下一步做什么。

我举一个实际场景：你想给项目加一个“导出 CSV”的功能。网页版的做法是你把 Controller、Service、前端页面全粘给它，它给你三段代码，你再一个一个文件手动处理。Claude Code 的做法是你在终端里说一句“给订单列表加个导出 CSV 的功能，字段和当前列表一致”，它会自己去找到列表接口和前端页面，修改对应代码，然后跑一遍检查有没有语法错误，最后告诉你怎么验证。这种差距，用惯了之后真的回不去。

1.2 核心能力与使用边界

Claude Code 的能力大致可以分成四块：

• 代码理解与检索：在大型代码库里快速定位某段逻辑、某个函数在哪些地方被调用，比人眼 grep 快很多。
• 多文件编辑：一次修改跨多个文件的重构任务，AI 能统一改完，并保持风格一致。
• 命令执行与反馈：它在终端里有执行权限，能跑测试、装依赖、运行构建，再读取输出调整方案。
• 上下文感知：能读取 git 状态、项目结构、近期改动，基于真实仓库做判断。

但它也不是万能的。我最直观的感受是，它对“小范围但多文件联动”的任务处理得最好，比如“给所有列表页加分页”“统一错误处理格式”这种，效率和准确率都高。但如果是需要从零设计一套复杂架构的任务，它给出的方案仍然需要人来把关，尤其是业务逻辑和取舍，AI 目前顶多给你一个“不错的起点”。

另外有一点必须提前说明：Claude Code 不是免费工具。它需要你有 Anthropic 账号和可用的 API 额度，或者订阅相关的付费套餐。网上那些“永久免费”“无限试用”的说法，基本都不可靠，有些还暗藏风险，建议直接用官方渠道。

2. 安装与环境准备：从零开始

2.1 安装前置条件，先检查这三件事

在动手安装之前，建议先确认三件事，不然很容易装完才发现跑不起来。

第一，确认 Node.js 环境。Claude Code 目前官方主推通过 npm 安装，所以本机需要 Node.js 18 以上版本。在终端里执行node -v，如果提示找不到命令，就是没装或者没配环境变量。第二，确认网络环境能够正常访问 Anthropic 的服务。Claude Code 本质上还是客户端，首次使用需要登录校验，网络不通畅会直接导致登录失败或者请求超时。第三，准备一个 Anthropic 账号，并且账号需要有可用的 API 额度或对应订阅权限。

第三点经常被忽略。有些人装好了一登录就报权限错误，排查半天发现账号本身就没开通对应权限。建议先去 Anthropic 官方控制台确认一下账号状态，再回来装工具。

2.2 命令行安装与更新

前置没问题之后，安装过程就非常简单了。在终端执行：

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

全局安装的好处是，之后在任何项目目录下都能直接用claude命令启动。如果之前装过旧版本，更新也一样：

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

装完之后，执行claude --version，能输出版本号就说明安装成功。我这边实测安装过程大概一两分钟，主要取决于网络速度。

这里有一个我在 Windows 上踩过的坑：如果你用的是 PowerShell，执行 npm 全局命令时可能遇到“无法加载文件，因为在此系统上禁止运行脚本”的报错。这是 PowerShell 的执行策略限制，不是安装本身的问题。用管理员身份打开 PowerShell，执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

然后再试就可以了。这里要提醒一句，这条命令修改的是当前用户的执行策略，影响范围有限，比直接改成 Unrestricted 要安全得多。

2.3 在 VS Code 中集成配置

很多人不习惯纯终端操作，更希望在编辑器里用。VS Code 集成 Claude Code 主要有两种方式：一种是直接用 VS Code 内置终端跑claude命令，另一种是安装第三方扩展，把 Claude Code 的输入框集成到编辑器侧边栏。我自己的经验是：第三方扩展适合轻度用户，重度使用还是终端里更顺。

如果你要用 VS Code 内置终端，什么都不用装。打开项目目录后，按Ctrl+`调出终端，输入claude启动即可。它会自动读取当前工作目录作为项目上下文。你也可以在 VS Code 里设置终端默认编码为 UTF-8，避免中文显示乱码。

第三方扩展的话，直接在 VS Code 扩展市场搜 “Claude Code”，装下载量最高的那个就行。安装后一般会新增一个侧边栏图标，点击可以打开独立的对话面板，不用再手动开终端。不过这种方式的本质还是调用本地的 Claude Code CLI，所以 npm 安装的那一步依然不能省。

2.4 桌面版与命令行版的取舍

Claude Code 官方也提供桌面客户端，界面像一个完整的聊天软件，左侧是对话列表，右侧是输入框和输出区。我第一次用的时候也犹豫过到底用桌面版还是命令行版，后来两个都用了一周，结论是：桌面版更适合管理多个项目、经常切来切去的场景，命令行版更适合一直待在某个项目里深入干活。

桌面版的优点是界面清晰，对话历史的管理更直观，适合“一次性管很多事”的人。命令行版的优势是轻、快、和你手头的编辑器、git 工具在同一个环境里，几乎不需要切换窗口。如果你主要做编码工作，我个人建议以命令行版为主，桌面版作为备用的对话管理工具。两者共用同一个登录账号，对话历史在一定条件下可以互通，不用担心信息分裂。

3. 核心操作流程：启动、交互、上下文管理

3.1 第一次启动与登录验证

安装完成后，进入你的项目根目录，执行claude，首次启动会进入登录流程。一般有两种登录方式：一种是在浏览器里打开一个验证链接，完成授权后回到终端继续；另一种是直接粘贴 API Key。我更推荐第一种授权登录方式，因为它走的是账号级权限，不需要手动管理 Key 的过期时间。

登录完成后，终端底部会出现一个输入框，类似聊天界面。到这里，Claude Code 就会加载当前目录的项目结构，扫描 git 状态，形成一个初始的“工作记忆”。你可以直接输入任务描述，比如“帮我看看这个项目目前的目录结构，然后给我一个整体介绍”，它会先梳理再回答。

有一个小细节值得注意：首次启动时，Claude Code 可能会询问一些权限问题，比如“是否允许我执行终端命令”“是否允许我读取 git 历史”，建议在可控范围内先允许它读取项目文件，命令执行权限则可以根据你的信任程度选择。如果完全不给它命令执行权限，很多自动化功能会打折扣。

3.2 常用操作指令与快捷键

Claude Code 的日常交互，其实不光是自然语言输入，它内置了一批斜杠命令，就像微信里的“/”快捷指令一样，非常实用。下面是我用得最多的一些：

其中/init是我最想推荐的一个命令。执行它之后，Claude Code 会自动分析项目结构、框架、构建方式，生成一个项目说明文件。这个文件会成为之后每一次会话的长期上下文，AI 会一直记得你项目的背景信息，不用每次重复解释。对于大项目，这个文件的价值非常明显。

除了斜杠命令，终端输入框还支持一些常用快捷键操作。比如多行输入时按住 Shift 回车换行，按 Esc 可以停止当前正在执行的任务。如果你发现 AI 跑偏了方向，按 Esc 中断，然后重新描述需求，比让它一直错下去再纠正要省时得多。

3.3 对话历史保存与恢复

Claude Code 默认会保存会话历史，这一点对长时间开发特别有用。因为一次会话可能持续很久，中途你可能会关掉终端，或者电脑重启，这时候如果不支持恢复，所有上下文就白费了。

手动恢复历史会话的方式，是在启动时带上--resume参数：

claude --resume

它会列出最近的会话记录，选择对应的编号就能继续之前的对话，AI 还记得之前分析到哪一步。这个功能在长时间断点开发时非常重要，我自己的习惯是每天收工前不关终端，第二天直接claude --resume接着干，上下文完全衔接。

也有一个坑需要提醒：如果你开启了多个终端窗口，同时运行多个 Claude Code 会话，它们之间的上下文是独立的，不会自动合并。所以尽量保持“一个项目、一个会话”的原则，避免自己都搞混哪个会话在哪个目录下。

4. 模型接入：官方模型、DeepSeek、Ollama 本地模型

4.1 默认使用官方 Claude 系列模型

Claude Code 默认使用 Anthropic 官方的 Claude 模型，具体版本会随客户端更新而同步变化。官方模型的好处是兼容性最好，Claude Code 的很多高级功能（比如工具调用、长上下文处理）都是围绕官方模型设计的，用起来最省心。

对大多数新手来说，我的建议是刚开始不要折腾模型切换，先用默认配置跑通核心流程。官方模型的编程能力确实强，尤其是在长上下文理解和多文件修改这类任务上，表现比很多第三方模型稳定。等你熟悉了基本操作，再考虑用第三方模型来省钱或满足特定需求。

需要提醒的是，官方模型是按 token 计费的。Claude Code 本身不是免费的，每次对话、每次读写文件都会消耗 token，实际费用取决于你用得多不多。网上有不少“省 token”的教程，后面我会专门讲这个话题。

4.2 接入 DeepSeek、GLM 等第三方模型

社区里有很多人尝试把 Claude Code 接到第三方模型，最常见的是通过环境变量把请求转发到兼容接口。以我实际配置过的方式为例，如果你有 DeepSeek 开放平台的 API Key，可以在启动 Claude Code 前设置两个环境变量：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_MODEL="deepseek-chat"

设置之后再执行claude，请求就会发往你指定的接口。类似的方式也适用于部分支持 Anthropic 兼容接口的其他模型服务。GLM 系列模型也可以用类似思路接入，具体模型名和接口地址以官方文档为准。

这里我必须说几句实话。第三方模型接入虽然能降低使用成本，但体验差异是实打实的。Claude Code 的很多机制，比如工具调用、自动修正、长文件操作，都需要模型底层有很强的指令遵循能力。我测试下来，部分第三方模型在简单任务上没问题，但一旦任务复杂，多文件联动、多次工具调用，失败率和返工率就会明显上升。所以我的建议是：日常小需求可以用第三方模型省钱，但核心项目、需要动大手术的重构，还是切回官方模型更稳妥。

4.3 通过 Ollama 接入本地大模型

除了线上 API，还有人会把 Claude Code 接到本地的 Ollama 模型上。选择这条路的人，多半是出于隐私、数据不落盘、或者长期成本考虑。Ollama 是一个本地大模型运行工具，装好之后拉取一个模型：

ollama pull qwen2.5-coder

然后启动 Ollama 服务，再把 Claude Code 的接口地址指向本地：

export ANTHROPIC_BASE_URL="http://localhost:11434"

这个方法理论上可行，但我要提醒一个现实问题：本地模型的能力目前还不足以完全替代官方 Claude 模型。如果你只跑一些小任务，比如“帮我格式化这段代码”“解释这个函数的作用”，体验还行。但如果是真正的代码库级任务，本地模型经常会出现理解偏差，或者执行过程中卡住。只能说期望值不要太高，适合尝鲜和数据敏感场景，真要高效干活，还是得靠在线模型。

4.4 用 CC Switch 管理多套模型环境

当你开始在不同模型之间切换，就会遇到一个麻烦：环境变量来回改太累了。CC Switch 就是为解决这个问题出现的社区工具，它能把不同的 API 地址、模型名、环境变量组合保存成一个个配置组，需要哪个一键切换。

我试用下来，CC Switch 的界面很简单，核心是管理“配置预设”。你可以建三套配置：官方模型、DeepSeek、本地 Ollama，切的时候直接选择对应配置，它会自动改写环境变量，然后你重新启动 Claude Code 就能生效。

这个工具适合那种“官方模型和第三方模型混用”的深度用户。如果你只是偶尔试一下第三方模型，完全没必要额外装工具，手动改环境变量就行。工具虽好，但别让工具本身成为你学习路上的负担。

5. Claude Code 和 Codex 怎么选，别再纠结

5.1 两者的定位差异

网上关于“Claude Code 和 Codex 到底选哪个”的争论很多。Codex 是 OpenAI 推出的类似终端 AI 编程工具，名字和 Claude Code 一样，都是跑在终端里的 AI 代理。表面看功能类似，实际操作风格还是有差异的。

我的体感是，Claude Code 更强调对长上下文的记忆和理解，适合大仓库、多文件、需要一步步推进的复杂任务，它写代码的风格也比较“稳”，会瞻前顾后。Codex 给我的感觉是执行速度更快，任务拆解更利落，尤其在快速实现明确功能时，它的响应节奏更爽快。但这只是个人感受，不同场景下结论可能完全相反。

5.2 从配置难度、费用、适用场景对比

这个表格仅供参考，因为两边产品迭代非常快，具体能力边界可能过几个月就变了。我建议不要把选型当成“站队”，而是看当下的项目需求。

5.3 我的选择建议

如果你刚接触终端型 AI 编程工具，我建议你先从你已有的生态入手。如果你的 API 和账号体系在 Anthropic 这边，直接用 Claude Code，少折腾。如果已经在用 OpenAI 服务，那 Codex 入手更顺。

如果你两边都是新账号，那就看任务类型。平时写代码小步快跑、功能点明确，Codex 会让你觉得痛快；要在陌生的大代码库里摸索、做跨文件重构，Claude Code 的长上下文优势更明显。我个人的日常组合是：Claude Code 做主力，负责重活累活；Codex 做副手，处理临时性小需求。当然这只是一种用法，不必照搬。

6. 进阶玩法：MCP 与 Skills

6.1 用 MCP 让 Claude Code 读取数据库等外部数据

MCP（Model Context Protocol）是 Claude Code 非常值得学的一个能力扩展协议。简单说，MCP 允许 Claude Code 通过标准化的接口去连接外部数据源，比如数据库、文件系统、第三方 API。通过它，你可以让 AI 直接查询数据库内容、读取远程服务数据，而不只是看代码文件。

MCP 的配置通常是在项目根目录或用户目录下维护一个配置文件，按官方格式声明你要引入的 MCP 服务。一个常见的简化配置是这样的：

{ "mcpServers": { "my-db": { "command": "npx", "args": ["-y", "some-mcp-database-server"] } } }

配置完成后，重启 Claude Code，你就可以在对话里直接说“查一下 users 表里的最近 10 条记录”，AI 会通过 MCP 工具连接数据库执行查询，再把结果带回来分析。这个能力对排查数据问题、快速了解业务数据非常有效。

需要提醒的是：MCP 服务一旦配置，就等于给了 AI 一条通往外部系统的通道，权限范围要谨慎控制。我的习惯是，只在专用的测试数据库上开启 MCP 连接，生产环境的库尽量不接。安全永远比方便重要，这一条请你一定记住。

6.2 Skills 自定义技能，把 AI 调教成你想要的样子

Skills 是 Claude Code 另一个让人上头的功能。它的思路是：你给 AI 定义一组“技能”，每个技能包含一个说明文件，描述了触发条件、操作步骤和注意事项。之后在合适的场景下，Claude Code 会主动调用这个技能来处理问题。

举个例子，你可以定义一个“代码审查技能”，说明文件里写上：审查时要重点检查安全问题、空指针风险、内存泄漏痕迹，并且按照某种固定格式输出报告。以后你执行代码审查任务时，Claude Code 就会自动按这个技能要求走，而不是给出泛泛的回答。这个功能特别适合团队统一规范，把团队积累的代码规范、公共经验沉淀成 Skills 文件。

Anthropic 官网有 Skills 的官方说明文档，关键词可以搜“Claude Code Skills 官方文档”。注意，Skills 的目录结构、加载方式在不同版本里可能有调整，配置前建议先读一遍对应版本的官方文档，别照搬网上的旧教程，这个坑我踩过。

7. 省 Token 与限额问题的实操经验

7.1 怎么控制 token 消耗，避免费用失控

提到 Claude Code，很多人的第一反应是“好用，但怕费钱”。我用了这段时间，总结了几条比较实用的省 token 经验。

第一条，善用/init生成项目说明文件，而不是每次对话都重新介绍项目背景。没有项目说明文件的情况下，AI 每次会话都要读一遍项目结构，重复消耗大量 token。有了 CLAUDE.md，它能直接基于已有的项目认知开始工作。

第二条，任务描述尽量具体。你让它“优化一下这个接口”，它会翻很多东西来确定范围；你直接说“优化src/api/order.ts第 85 行附近那个接口的异常处理”，它的探索范围就会小很多。给 AI 指路，就是在给钱包省钱。

第三条，控制读入内容。Claude Code 需要读文件才能改文件，但你不希望它把整个大仓库都翻一遍。启动会话时，尽量在项目根目录运行，同时通过对话明确告诉它“先只看src目录下的代码，不要读 node_modules”。这类边界约定能显著降低无效 token 消耗。

7.2 遇到限额提示和 50% 警告怎么办

很多人在使用中会看到类似 “your limits are temporarily boosted. your weekly claude code limit is 50%” 的提示。这句话的意思是，你当前的每周使用额度已经被用掉了一半，额度本身被临时提升了。这其实是正常机制，不是报错。

遇到这种提示，我的建议是：如果任务不急，可以缓一缓，等额度到下周自动重置；如果任务紧急，就把非核心任务切到第三方模型或本地模型跑，把有限额度留着给最重要的任务。官方提供额度通道，但不建议任何形式的“绕过”操作，一方面不稳定，另一方面也可能涉及违反服务条款，没必要为了省一点钱把账号置于风险中。

7.3 对话历史占用与控制

还有一个容易被忽略的 token 消耗点：长会话。一个会话如果拉得特别长，上下文越来越臃肿，后续每次交互都要带着这么多历史，token 消耗会越来越大。我的做法是：一个大的开发任务完成之后就/clear一下，开启新的会话，不让历史的包袱越拖越重。

如果你需要长期记忆某些信息，可以用/memory功能把关键点写进长期记忆，而不是一直开着同一个会话。这样既保留了重要信息，又避免上下文膨胀带来的费用飙升。用久了你会发现，管理好上下文，才是真正省 token 的核心心法。

8. 常见问题与排错记录

8.1 PowerShell 安装报错与执行策略问题

前面提过，Windows 下最常见的安装报错就是 PowerShell 执行策略限制，报错信息类似“无法加载文件 Claude.ps1，因为在此系统上禁止运行脚本”。解决方案就是前面说的：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

如果改了执行策略还是报错，检查一下是否安装了多个 Node.js 版本，npm 全局路径有没有配置到环境变量里。执行npm prefix -g看看全局安装路径，再把对应的 bin 目录加到系统 PATH，基本就能解决。

8.2 登录返回 403 的常见原因

登录时返回 403，是另一个高频问题。我遇到的情况大致有几种：账号本身没开通相应权限；本地时间不正确导致登录校验失败；或者网络环境异常导致请求被拒绝。排查顺序建议是：先确认账号在 Anthropic 官网能正常登录，再检查系统时间是否正确，最后检查网络环境是否稳定。

如果你用了第三方 API 服务，403 也可能是接口地址或 Key 配置错误造成的。这时候先把环境变量清空，回到官方接口试试，如果官方接口正常，再逐步排查是哪一层配置出了问题。这种“隔离法”在排错里最有效率。

8.3 终端中文乱码问题

Claude Code 输出中文，在某些终端里会变成乱码，尤其是 Windows 环境。这通常是终端编码和系统编码不一致导致的。最简单的解决方法是在启动 Claude Code 之前，在终端里执行：

chcp 65001

把代码页切换到 UTF-8，再启动 Claude Code。如果你用的是 Windows Terminal 或 VS Code 终端，也可以在设置里把默认编码改成 UTF-8，一劳永逸。还有一个容易被忽略的点：如果代码里本身有 GBK 编码的文件，AI 读取时也可能出现乱码，这属于文件编码问题，需要先统一项目文件编码。

8.4 模型不识别与版本过旧问题

有时候会看到类似"glm-5.2" is not a model this version of Claude Code recognizes的提示。这句话的意思是：你配置的模型名不是当前 Claude Code 版本能识别的模型。出现这个提示，要么是第三方模型名写错了，要么是 Claude Code 版本太老，不认识新模型。

处理方法很简单：先查一下你用的模型服务方提供的准确模型名，复制粘贴到环境变量里，不要手输；然后确认 Claude Code 是最新版本，执行npm update -g @anthropic-ai/claude-code。如果都还不行，看看模型服务方是否真的提供了 Anthropic 兼容接口，很多报错其实是接口不兼容，不是名字写错。

8.5 我的排错思路小结

遇到问题别急着搜报错原文，先想清楚是哪个环节出了问题。按我的经验，绝大多数 Claude Code 问题可以归为四类：环境问题（Node、网络）、权限问题（登录、账号额度）、配置问题（模型名、接口地址）、版本问题（客户端过旧）。先归类，再逐一排查，比自己瞎试快得多。如果某个第三方配置搞不定，最快的方案就是退回默认配置，把核心流程用起来，再慢慢加功能。

我个人在实际操作中的体会是，Claude Code 这类工具，真正难的不是安装，而是建立一套适合自己的使用习惯。模型、接口、配置都是可以随时换的，但你给它讲清楚任务的能力、管理上下文和 token 的意识、排查问题的思路，这些才是越用越值钱的东西。刚开始不熟练很正常，装好之后先拿一个小项目练手，把一个任务从接手到收尾完整跑几遍，比什么教程都管用。