Claude Code 这个东西，说实话我第一次用的时候是有点不以为然的。命令行里面敲几个字，让 AI 帮你改代码？当时市面上这类工具已经不少了，我觉得多半又是噱头。但真正跑起来一个项目之后，我承认这个判断错得离谱。它不是一个简单的“终端里的聊天机器人”，而是把 AI 编程助手从“对话框”搬进了“真实工程环境”的一次质变。2026 年再看，Claude Code 基本已经成了我日常开发流水线里离不开的一环。这篇教程，我就从一个小白视角，把安装、配置、VSCode 集成、桌面版、高阶技巧到常见问题完整过一遍，全程讲人话，尽量让你看完就能上手。
这篇东西适合谁？如果你用过 Cursor 或者 GitHub Copilot，但觉得它们在大型项目、多文件重构、复杂命令执行上还不够“聪明”；或者你刚听说 Claude Code，想知道它和 Codex、Copilot 到底有啥区别；又或者你已经装上了，但卡在登录、权限、沙箱这些奇奇怪怪的问题上——那这篇就是写给你的。
1. 先搞清楚：Claude Code 到底是什么，为什么值得学
1.1 一句话定义和核心能力
Claude Code 是 Anthropic 官方出品的命令行编程代理工具。它的本质是一个跑在终端里的 AI agent，能直接读写你项目里的文件、执行终端命令、运行测试、提交代码，而且它背后强绑定 Claude 系列大模型，所以推理能力天然有优势。
和普通 AI 编程助手最大的区别在于：它不是“你问一句、它答一段代码”，而是可以理解你整个项目的上下文，像一个真正的结对程序员一样，帮你完成跨文件的改造任务。举个例子，我让它“把登录模块从 Session 换成 JWT，并更新所有相关测试”，它能自己找到依赖这些接口的文件，逐个改完，跑测试确认通过，然后告诉我改了哪些地方、为什么这么改。
这种能力听起来很爽，但问题也随之而来：它要动你的文件、执行命令，安全边界怎么控制？这就引出了权限机制和沙箱机制。很多人第一次用 Claude Code 卡住，十有八九是没搞懂这两个机制。
1.2 和 Codex、Cursor 这类工具比，差异在哪
我在接入 Claude Code 前后，重度用过 OpenAI Codex CLI，也用过 Cursor 一段时间。简单说下我的主观感受，不一定客观，但能帮你建立直觉：
- Codex：背靠 GPT 系列模型，代码生成质量很稳，但默认工作方式更偏向“你给任务它干活”，在长链路的自主规划上稍弱一些。它的“代码评审”模式我挺喜欢，适合做 code review。
- Cursor：IDE 形态，适合喜欢图形界面、鼠标点一点的人。但本质还是一个“编辑器 + AI 补全”的组合，agent 能力要弱一些，大型重构经常需要你手把手喂上下文。
- Claude Code：终端形态，极客感拉满，敲命令就能跑。它的核心强项是长上下文理解 + 自主工具调用。Claude 系列模型本身擅长复杂推理，配合终端环境，它能一口气处理十几个文件的联动修改。
如果你是非程序员，只想“让 AI 帮我写个小脚本”，那 Claude Code 不是最友好的选择，用 Cursor 或者网页版也就够了。但如果你天天在终端和项目代码打交道，想让 AI 真正进入你的开发循环，Claude Code 值得认真学。
2. 环境准备与安装：Windows / macOS 两条路都要讲透
2.1 安装前的环境要求
Claude Code 的主体是 Node.js 应用，所以第一前提是电脑上有Node.js 环境。建议装 18+ 版本，最好直接上 20 LTS 或更高。Node.js 的安装包我建议直接去官网下载，别用某些包管理器里版本老掉牙的源。
终端里先验证一下：
node -v npm -v如果这两条命令都能正常输出版本号，环境就过关了。另外，你的终端最好支持 UTF-8 编码和 ANSI 颜色输出，不然 Claude Code 的界面会乱码或者没有高亮。Windows 上建议用 Windows Terminal，别用老古董 cmd。
2.2 macOS 安装步骤
macOS 上安装非常简单，直接在终端执行：
npm install -g @anthropic-ai/claude-code等它跑完，敲claude --version验证，如果输出了版本号（比如 2.x.x），就装好了。后续升级同一条命令，npm 会自动覆盖到最新版。
补充一句：如果你在 macOS 上提示权限不足（多见于系统自带 Node 环境），建议先用 Homebrew 把 Node 装到用户目录，再执行 npm 全局安装。硬用 sudo 装虽然也能成，但后面升级、卸载容易留下权限坑。
2.3 Windows 安装步骤（Win11 / Win10）
Windows 上的安装路径分两种，看你的 Node 环境怎么来的：
- 如果你装的是 Node.js 官方安装包，那么在 PowerShell 或 Windows Terminal 里同样执行：
npm install -g @anthropic-ai/claude-code- 但是，这里有个 2026 年新版本的一个关键变化：新版 Claude Code 对 Windows 的原生支持已经做得相当好了，不再像早期版本那样强依赖 WSL。不过终端里跑 bash 类命令时会自动切换到内置模拟环境，所以你的 PowerShell 版本不能太老，Windows 10 建议升级到最新的 PowerShell 7。
安装完成后同样验证：
claude --version如果你在 Win10 上遇到“无法加载文件 claude.ps1，因为在此系统上禁止运行脚本”的报错，那是 PowerShell 执行策略的问题。管理员身份打开 PowerShell，执行：
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser然后重新打开终端再试一次。这个坑我当初踩了十分钟才反应过来。
2.4 安装后第一件事：登录与基础验证
装完先别急着干别的，运行一遍claude，首次会进入登录流程：
claude启动后终端会显示欢迎信息，然后提示你登录。按照提示打开浏览器完成授权，回到终端就会自动登录成功。如果你在无浏览器环境，可以用命令行的方式粘贴访问令牌，具体看当时的提示。
登录后输入/status确认账号状态，再输入/model查看当前使用的模型。默认情况下它会用 Anthropic 的官方模型，这也是它性能最稳定的工作模式。
这里要特别提醒：如果你看到类似Not logged in. Please run /login的提示，说明认证信息丢了或者从未生效。直接输入：
/login重新走一遍授权流程就行，不用卸载重装。
3. 权限模型与沙箱机制：搞懂它，你才能放心用
3.1 权限分级：让 AI 替你干活，但别让它乱来
Claude Code 默认会主动向你请求执行操作——比如它要修改package.json，会弹出一个交互询问，等你确认。这种模式在早期版本叫“人工确认模式”，现在变成了可配置的权限等级。
常用权限级别：
- 完全自主（bypassPermissions）：所有操作不再询问，AI 直接执行。适合你完全信任的场景，比如专门用来跑测试的临时目录。
- 默认询问（默认）：涉及文件修改、命令执行时逐条问你，最安全。
- 白名单模式（allowlist）：把某些命令（比如
npm test、git status）放进白名单，AI 执行白名单内的命令不问，其他操作继续询问。
设置方式是在交互界面输入：
/permissions它会打开权限配置面板，图形化操作，非常直观。配置文件最终写在~/.claude/settings.json里，你也可以手动改这个文件。
我的建议：新手上路先保持默认询问模式，跑顺了再逐步放开。尤其是rm、git push、DROP TABLE这类破坏性强的命令，尽量别放进白名单。
3.2 沙箱起不来的排查：2026 年最常见的报错之一
热词里那几条“claude code 沙箱起不来”基本是真实痛点。Claude Code 的沙箱机制，是为了把命令执行限制在隔离环境里，防止它误操作到你系统核心目录。
如果你启动后提示沙箱初始化失败，按顺序排查：
- 看版本：老版本沙箱依赖 Docker，需要你手动装并启动 Docker Desktop。如果你没装，自然起不来。新版本已经内置轻量沙箱，不再强制 Docker，但仍要求系统虚拟化能力正常。
- 看系统设置：Windows 上要确认“虚拟机平台”和“适用于 Linux 的 Windows 子系统”两个功能已开启。macOS 上如果开了 SIP 严格模式，也可能影响沙箱。
- 看日志：运行
claude --debug或者查看~/.claude/logs下的日志文件，里面会明确写失败原因，远比猜答案管用。
还有一个小技巧：如果内置沙箱实在起不来，你可以临时禁用沙箱运行。但我不建议这么干，沙箱本质是你和 AI 之间的一道防火墙，关了它等于裸奔。
3.3 CLI 完全访问权限设置
很多人在搜索“claude code cli 如何给完全访问权限”，说明这个设置确实藏得有点深。所谓“完全访问权限”，官方文档里叫full access mode。开启方式：
- 交互界面输入
/config，在配置菜单里找到权限模式，切换到acceptEdits或bypassPermissions。 - 或者直接编辑
~/.claude/settings.json，加一行：
{ "permissions": { "allow": ["Bash(npm run dev)", "Bash(git add .)"], "deny": ["Bash(rm -rf *)"] } }注意：这里的“完全访问”是对你允许范围内的命令完全访问，不是让它为所欲为。合理的做法是给高频、安全的命令放权，把破坏性命令永远留在 deny 里。
4. 把 Claude Code 装进 VSCode 和桌面端
4.1 VSCode 插件配置：图形界面党的福音
虽然 Claude Code 出生在终端，但 2026 年官方对 VSCode 的集成已经非常完善了。安装方式：
- 打开 VSCode 扩展市场，搜索
Claude Code，认准开发者是Anthropic那个官方插件。 - 安装后侧边栏会出现 Claude Code 图标，点开就是聊天面板。
- 点击面板上的登录按钮，走一遍授权流程。
配置要点：
- 模型选择：插件默认使用 Claude 系列模型，但可以在设置项里指定
claude-sonnet-4、claude-opus-4这类具体型号。同一个项目里，插件和终端版共享登录态和对话历史，切换起来不用重新登录。 - 工作区信任：VSCode 打开项目时，如果提醒“是否信任此文件夹”，要选择信任，否则 Claude Code 无法读取项目文件。
- 快捷键：
Ctrl+Shift+P输入Claude Code: Open可以快速唤起面板。
有件事提醒一下：VSCode 插件适合日常小改动和代码问答，但重度重构任务我仍然建议在终端里跑。因为终端里的 Claude Code 能看到完整的 git diff、Test 输出，并且能连续执行多步命令，处理复杂任务的稳定性更高。
4.2 桌面版使用与配置
很多人搜 “claude code desktop”，指的是 2025 年底开始推送的独立桌面客户端。它本质上是把终端版包装成了一个窗口程序，自带原生终端界面、主题切换、字体设置，还内置了自动更新。
桌面版的典型配置项：
- 界面主题：浅色、深色、跟随系统，还有几个高对比色主题。
- 默认工作目录：设置打开时进入哪个项目目录。
- 代理配置：如果你在公司内网，需要走
HTTP_PROXY等环境变量，桌面版提供了图形化输入框。 - 模型端点：如果要接入第三方网关（后面会讲），在这里改 Base URL 就行。
它和命令行版共用同一套配置文件（~/.claude/），所以两边切着用不会精神分裂。
4.3 保存对话历史：数据去哪了
关于“claude code 怎么保存对话历史”，答案是：它默认自动保存，你基本不用操心。
所有会话记录以 JSONL 格式存在~/.claude/projects/目录下，按项目路径名分文件夹。每个会话对应一个.jsonl文件，里面按行记录每一轮交互的输入输出、工具调用结果。
你可以手动翻这些文件找回某段历史，也可以直接输入/resume命令列出最近会话，选择某个继续聊。如果想让某段历史长期保留，复制一份 JSONL 文件到别处就行；想清理隐私数据，直接删掉对应目录也不影响主程序。
这个设计我自己非常喜欢。它意味着你过去所有做过的事情都留痕，你随时可以让 Claude Code “接着上次的活继续干”，它上下文不丢。
5. 高阶玩法：接入 DeepSeek、安装 Skill、二次开发
5.1 把 Claude Code 接到 DeepSeek 等第三方模型上
这个需求这两年特别火，原因很好理解：不少团队想 用 Claude Code 的工程能力和代理体验，但模型想换成自己采购或者更便宜的开源/国产模型，比如 DeepSeek。
先说结论：Claude Code 本身强绑定 Claude 系列模型，官方不支持直接换模型。但社区方案成熟，最常见的是用claude-code-router这类开源网关工具。
原理不复杂：Claude Code 外部请求走的是 Anthropic API 格式，router 在中间做了一层协议转换，把你请求里的模型名映射到 DeepSeek（或者其他 OpenAI 兼容接口）上。
具体操作（以 claude-code-router 为例）：
- 全局安装 router：
npm install -g claude-code-router- 配置文件里声明模型供应商，比如把
claude-sonnet-4映射到deepseek-chat，并填好你的 DeepSeek API Key。 - 设置环境变量，让 Claude Code 把请求发送到 router 的本地端口：
export ANTHROPIC_BASE_URL=http://localhost:5858- 重新运行
claude，交互界面里选对应模型就行。
注意几个坑：一是 DeepSeek 的上下文窗口和 Claude 原版不同，超长任务可能触发截断；二是 router 本质上做的是“尽力转发”，部分 Claude Code 特有功能（比如某些工具调用格式）在第三方模型上可能不工作。所以这种方式适合做日常编码问答，真要跑重活，我最后还是会切回 Claude 官方模型。
5.2 Skills 安装与自定义：让 AI 学会你的业务姿势
“claude code skill 安装”是 2026 年绕不开的话题。Skills 本质上是给 Claude Code 预设的“知识包”——你可以往~/.claude/skills/目录里放一个文件夹，里面包含SKILL.md描述文件和一些示例，这样 Claude Code 在遇到相关任务时会自动加载并按照其中方法执行。
安装一个 skill 的常规流程：
- 找一个你想用的 skill（官方有 skill 市场，GitHub 上也有海量社区版本）。
- 把仓库 clone 下来，或者手动下载，把整个目录拷贝到
~/.claude/skills/下。 - 在 Claude Code 里运行
/skills查看已加载的 skills，确认新 skill 出现在列表里。 - 不放心的话，重新启动
claude，让技能包正常初始化。
也可以自己写 skill。举个例子，如果你经常让 AI 做 Vue 项目重构，可以写一个vue-refactor技能，SKILL.md 里写明：
- 适用范围：Vue 2 迁移到 Vue 3、组件拆分。
- 操作步骤：先扫描目录结构、找出路由文件、再逐个组件迁移……
- 关键约束：不要动
node_modules、改完必须跑npm run build验证。
这样下次你只要说“用 vue-refactor 技能处理一下当前项目”，它就能按照你的套路来，而不是泛泛地自由发挥。
5.3 二开思路与扩展：闭源不意味着不能扩展
Claude Code 主程序是闭源的，但官方提供了丰富的扩展面：
- MCP Server：通过 Model Context Protocol 协议挂载外部工具和知识库，可以给 Claude Code 接上公司内部 API、数据库查询工具、文档检索服务。
- CLI Hook：在命令执行前/后触发自定义脚本，比如 git commit 后自动跑一次全量测试。
- 插件机制：新版支持本地插件系统，可以编写自定义命令和 UI 组件。
对于想要“二开”的朋友，我的建议是：不要试图去改 Claude Code 本体，它的配置、skill、MCP、hook 这四层扩展已经覆盖了绝大多数需求。我见过不少团队拿它做内部代码审查机器人、自动修 bug 的流水线，这些都是纯靠 MCP + skill 组合实现的。
6. 常见问题速查与避坑笔记
6.1 常见错误速查表
我把 2026 年社区里高频出现的报错整理成了一张表，方便你直接对照解决。
| 现象 | 原因 | 解决办法 |
|---|---|---|
Welcome to Claude Code ... unable to connect to Anthropic services | 网络无法访问 Anthropic API 服务 | 检查网络连通性、是否需要配置代理，重试或稍后再试 |
Not logged in. Please run /login | 登录态失效 | 输入/login重新授权 |
安装后claude不是内部或外部命令 | npm 全局路径未加入 PATH | Windows 检查 npm prefix，macOS 检查/usr/local/bin或 Homebrew 路径 |
| 沙箱起不来 | Docker 未启动 / 系统虚拟化关闭 | 安装并启动 Docker，或开启 Windows 虚拟机平台功能 |
| VSCode 插件连不上 | 未授权或版本过老 | 更新插件，重新登录，确认工作区已信任 |
| 接入 DeepSeek 后报模型名错误 | 模型映射配置不对 | 检查 router 的模型映射表，确保模型名与供应商接口一致 |
| 对话历史丢失 | 清理过~/.claude/projects/ | 无法恢复，建议定期备份该目录 |
这里面最容易被忽略的是第一条“网络连接失败”。不少人的第一反应是卸载重装，实际上大部分时候只是临时网络波动，或者需要配置环境变量走企业代理。登录状态丢失也一样，重新登录就完事，不要动不动就“删了重装”。
6.2 卸载与清理：别留下一地鸡毛
最后说一下卸载。很多人安装遇到问题就想卸载，结果卸载不干净，重装之后老问题还在，非常打击人。
干净卸载的步骤：
npm uninstall -g @anthropic-ai/claude-code然后手动清理残留配置：
- 删掉
~/.claude目录（macOS/Linux）或C:\Users\你的用户名\.claude（Windows）。注意：这一步会清掉所有对话历史和自定义 skills，卸载前如果有重要记录，先备份。 - 如果用过 VSCode 插件，在扩展列表里找 Anthropic 的 Claude Code 扩展，点卸载。
- 如果装过桌面版，把它从应用程序列表里卸载掉。
清理完再重新安装，遇到脏问题的概率会大大降低。
根据我个人用了大半年的经验，Claude Code 这类工具真正值钱的地方不在于“它能写代码”，而在于“它能把一个模糊的工程想法，拆解成一条明确的执行路径，并在你的监督下执行完”。我见过很多人在权限配置上畏手畏脚，结果每步都要点同意，体验差到劝退；也有看到过完全放开权限然后让 AI 乱跑命令，把 git 历史搞得一团糟的。找准自己的舒适区——在安全与效率之间，我给大多数朋友的建议是给命令加白名单而不是全信任，给文件修改加确认而不是全放手。
最后分享一个我觉得很实用的小技巧：在项目根目录建一个CLAUDE.md文件，第一行写上“本项目是 xx 项目，技术栈是 xx，测试命令是 xx，代码风格要求是 xx”。Claude Code 启动时会自动读取这个文件作为项目级上下文。做过这件事之后，你让它干的每件事都会更贴你的项目习惯，这比改十次模型参数都管用。
/O(1) 原地重排方案)