蓝盐泳池1983我第一次被“Claude Code到底是什么”这个问题问懵，是在一次技术群里。有人贴了一张终端截图，一个Agent自动创建了三个文件、跑完测试又把结果写进README，底下评论清一色在问：这是VS Code的插件吗？怎么装的？老实说，刚看到这玩意儿的时候我也以为是某个IDE的AI补全插件，直到自己装完跑通才发现，它压根不是“在编辑器里聊天”这么简单——它是一套真正住在命令行里的编程Agent，能自己读代码、改文件、执行命令、看结果，然后继续干活。今天这篇就把Claude Code从安装、配置到实战、选型、排错完整讲透，顺便把网上那些支离破碎的教程里没说清的坑都填上。
1. 先搞懂Claude Code是什么：一个住在终端里的全职Agent，不是又一个补全插件
1.1 它到底能干什么
Claude Code是Anthropic在2025年推出的命令行编程Agent，通过claude命令启动。它的核心形态不是“对话框”，而是“任务执行器”：你给它一个目标，它会自主规划步骤，读完整个项目结构，然后一个文件一个文件地改，必要时直接执行shell命令跑测试、装依赖、查报错。
打个不太准确的比方：Copilot类工具像是坐在你旁边的副驾，你打一行它补一行；Claude Code像是你把车钥匙直接扔给了一个代驾，你跟它说“去机场”，它自己规划路线、变道、加油，到了还会告诉你用了多少油。整个过程在终端里实时可见，你随时可以打断、纠正、让它重来。
它底层跑的是Claude的Sonnet和Opus系列模型，所以对代码语义的理解、多文件跨模块的改动能力，是传统IDE插件很难比的。再加上MCP（Model Context Protocol）这套工具协议，它还能外接数据库、浏览器、内部API，让它“摸”到你项目之外的系统。
1.2 哪些人适合把它放进日常工作流
先说结论：适合“愿意在终端里干活”的人。我见过最顺利上手的用户画像基本是这几种：
- 独立开发者，项目在自己电脑上，希望用自然语言驱动完成重复性增删改；
- 团队里的工程效能角色，需要批量重构、迁移、补测试；
- 已经在用VS Code但不想切IDE的人，把Claude Code作为终端侧的主力Agent；
- 对AI编程工具好奇、能接受“读终端输出”这件事的进阶用户。
反过来，如果你习惯纯图形界面、看到命令行就头大，那Claude Code的初始学习曲线会比想象中陡。它不是不能给你图形界面——官方有桌面版打包——但深入用下去，操作核心还是命令行。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. CLI安装全流程：macOS、Windows两条线分别走一遍
2.1 安装前要确认的事情
Claude Code的CLI目前主流安装方式是通过npm分发：npm install -g @anthropic-ai/claude-code。所以第一步是确认Node环境。
- Node.js版本建议18及以上，低于这个版本会报
engine相关错误； - 确认npm可用，Windows用户建议先把Windows Terminal装好，别再用老的cmd或者PowerShell 5.1，后面乱码问题会少一半；
- macOS用户建议先确认是否装了Xcode Command Line Tools，很多后续编译类工具会依赖它。
2.2 macOS / Linux 安装
macOS和Linux走npm安装是最省事的：
bash复制npm install -g @anthropic-ai/claude-code
如果不想用npm，官方也提供了原生安装脚本：
bash复制curl -fsSL https://claude.ai/install.sh | bash
这个脚本会自动检测系统架构、下载对应二进制并写入PATH，适合没有Node环境又想尝鲜的人。不过我实测下来，npm方式在后续升级、卸载上更统一，所以我的建议是：有Node就用npm，没有Node再用脚本。
2.3 Windows 安装与PowerShell权限问题
Windows上同样是npm主路：
powershell复制npm install -g @anthropic-ai/claude-code
很多人在这一步就卡住了，报的错长这样：
code复制claude.ps1无法加载，因为在此系统上禁止运行脚本。
这是PowerShell的执行策略（ExecutionPolicy）限制，默认Restricted状态下任何.ps1脚本都不让跑。解决办法是给当前用户放开远程签名脚本的权限：
powershell复制Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
然后敲Y确认，再执行claude --version验证。
还有一类报错是npm WARN开头的权限问题，多见于Node装在系统目录的情况。这时候不建议直接拿管理员开终端，更好的做法是改npm的全局目录到用户空间：
bash复制npm config set prefix "$HOME/.npm-global"
再把$HOME/.npm-global/bin加进PATH，一劳永逸。
2.4 安装后的版本确认
装完以后：
bash复制claude --version
能看到类似1.0.x的版本号，说明CLI已经就绪。然后直接在项目目录执行claude，会进入首次认证引导，这一步我们放到第4章详细说。
提示：如果你装完以后
claude命令还是找不到，八成是npm全局bin目录不在PATH里。macOS/Linux执行which claude，Windows执行where claude，没有输出就去翻npm配置文件里的prefix路径，手动补进环境变量。
3. 把Claude Code接进VS Code：告别“CLI not found”的折腾
3.1 VS Code扩展与CLI的关系
搜索热词里“vscode配置claude code”“claude code for vscode”“vs code + claude code 插件接入本地大模型ollama”出现的频率极高。官方确实提供VS Code扩展，但扩展本身只是一个“壳”，真正的引擎还是你命令行里装的那个claude CLI。理解这一点，后面所有“找不到CLI”的问题就都好解释了。
VS Code扩展的作用是：在编辑器里给你一个更好看的对话面板，并把当前打开的工作区路径、选中的代码上下文传给CLI。它不会自己下载模型、不会自己推理——一切能力都来自你本地的CLI进程。
3.2 排查“could not locate the Claude CLI on path”的完整链路
这是VS Code环境下最经典的一个报错：
code复制Failed to run Claude Code: error: could not locate the Claude CLI on path.
排查思路其实就一条线：扩展在PATH里找不到claude这个可执行文件。顺着这个方向，按顺序查：
bash复制which claude # macOS/Linux
where claude # Windows
有输出，说明CLI在某个路径下。但VS Code的PATH环境和你终端里的PATH不一定一样——尤其是macOS上通过GUI启动的VS Code，不会自动继承shell里配置的.zshrc路径。这时候需要手动告诉扩展CLI的位置。
在VS Code设置里搜索claude-code.path，把CLI的绝对路径填进去，比如：
json复制{
"claude-code.path": "/Users/你的用户名/.npm-global/bin/claude"
}
填完以后重启VS Code，再执行命令面板里的Claude Code: Focus on Claude Code View，基本就能起来。
如果which claude本身就没输出，那就不是扩展的问题，是CLI没装好或者没进PATH，回到第2章的步骤重新搞。
3.3 用集成终端首次打开
我个人的习惯是：不依赖扩展自带的视图，直接在VS Code集成终端里跑claude。原因很简单：
- 集成终端继承的PATH和VS Code进程一致，少一层环境错位；
- CLI原生的交互模式、彩色输出、快捷键，用起来最顺手；
- 扩展面板本质上也是把这个CLI的输出渲染出来，多一层包装反而可能引入显示问题。
打开方式：Ctrl + ~（Mac上是Control + ~）打开集成终端，输入claude回车。如果第一次跑，会进入登录流程。
4. 第一次项目实战：认证、权限模型和会话恢复
4.1 两种认证方式怎么选
Claude Code支持两种认证方式：订阅登录和API Key。
订阅登录：在CLI里执行/login，会跳转到浏览器完成Claude账号授权。Claude Pro或Max订阅用户可以这样用，费用含在订阅里，适合日常高频使用、想在固定额度内干活的人。
API Key方式：设置环境变量：
bash复制export ANTHROPIC_API_KEY="sk-ant-..."
然后启动claude。这种方式按token计费，适合脚本化、自动化场景，也适合团队统一走API网关。
我的建议是：个人日常开发优先用订阅登录，按量付费的焦虑感会小很多；要写自动化脚本、跑CI、做批量任务时用API Key，方便配额控制和账单统计。
4.2 权限模式：先学会让Agent“听话”
Claude Code默认是“每次执行敏感操作前问你一次”。比如它要改文件、跑命令，会停在原地等你确认。你会看到类似这样的选项：
y：允许本次操作；a/always allow：允许本次会话内所有同类操作；x：拒绝；s：跳过本轮。
如果你希望它自动接受文件编辑，启动时加权限模式：
bash复制claude --permission-mode acceptEdits
这样它改文件不再逐条确认，但执行命令前仍会问。还有一个--dangerously-skip-permissions，直接跳过所有确认，全自动跑。我强烈不建议在生产环境用这个，原因很简单：Agent理解意图有一定概率出错，自动跑完一个不该跑的rm -rf或者DROP TABLE，后悔都来不及。
4.3 跑一个真实任务，并学会恢复对话历史
我们拿一个实际场景走一遍。假设项目根目录下有一个Express应用，我想要它加一个/health健康检查接口：
bash复制cd your-express-app
claude
在交互界面里输入：
code复制请给我加一个 /health 接口，返回 JSON 格式的 { status: "ok" }，并补充对应的单元测试。
它会开始读项目里的package.json、路由文件、测试框架配置文件，然后动手改。改完以后自己执行测试，看到失败会自动修，直到通过或放弃告诉你卡在哪。
这过程中有几个常用命令：
/status：查看当前上下文占用和工具调用统计；/clear：清空当前会话上下文，开始新任务；/resume：选择历史会话恢复，断线、换电脑后接着聊；Shift+Tab：切换到原生交互模式，tab补全、直接敲shell命令。
会话历史默认存在~/.claude/projects/目录下，按项目目录名加时间戳存成JSONL文件。这就是“Claude Code怎么保存对话历史”的底层答案：不用你手动保存，每次会话结束它都自动落盘，/resume就是去读这些文件。
注意：
.claudeignore文件的作用等同于Git的.gitignore。如果你的项目里有一堆node_modules、dist、第三方代码目录，一定要在.claudeignore里排除掉，否则Agent会花大量token去读这些无意义文件，既慢又费钱。
5. 和Codex正面对线：两边都用过之后的选型参考
“codex和claude code有什么区别”“选codex还是claude code?一篇讲透”这类问题，几乎每隔几天就有人问。我把两个工具都用了不短的时间，直接给结论：它们是同一赛道里两款气质完全不同的产品，选型的关键不是比参数，而是看你已经站在哪个生态里。
5.1 一张表看清核心差异
| 对比项 | Claude Code | Codex CLI |
|---|---|---|
| 出品方 | Anthropic | OpenAI |
| 底层模型 | Claude Sonnet / Opus 系列 | GPT-5-Codex 系列 |
| 安装方式 | npm + 官方安装脚本 | npm（codex） |
| 订阅支持 | Claude Pro / Max | ChatGPT Plus / Pro |
| API计费 | Anthropic API | OpenAI API |
| 扩展生态 | MCP协议，支持工具外接 | 插件机制，支持自定义命令 |
| 核心优势 | 多文件重构、长上下文理解、代码风格贴合 | 代码生成速度快、OpenAI生态整合好 |
| 上手门槛 | 终端操作，偏开发者向 | 终端操作，但引导流程更简化 |
| 典型场景 | 大型代码库改造、跨模块重构 | 快速生成脚本、写单文件功能 |
5.2 我自己的选择逻辑
如果是老Claude用户、已经有Pro/Max订阅，选Claude Code几乎不用犹豫，订阅额度直接用起来，零额外成本。而且Claude Code在“先读全项目再做改动”这件事上做得更稳，遇到那种“改A文件还要顺带改B文件类型定义”的跨文件任务，它的完成度明显更高。
Codex CLI赢在轻快——启动快、响应快，适合“这个脚本帮我写一下”“这个bash命令帮我生成”这种单点任务。尤其你已经买了ChatGPT Plus的情况下，用它是最顺的。
一句话总结：代码库越大、改动越深、越需要Agent自己规划方案，Claude Code越有优势；写小工具、跑一次性脚本、追求速度，Codex更合适。两不误的方案是都装上，按任务性质切换。它们在机器上互不干扰，不存在“装了一个就不能装另一个”的问题。
6. 进阶玩法实录：省token、自定义Skills、MCP连数据库、接本地模型
6.1 省token的四板斧
“claude code如何用省token”是很多人关心的问题，尤其API计费模式下token就是钱。我实测下来，最有效的四招：
-
善用会话恢复。碰到一次任务做一半，用
/resume或启动时加--continue，让Agent复用之前上下文，而不是重新读一遍项目再从头开始。每重新开一次会话，光是重新读目录结构就烧掉不少token。 -
用
.claudeignore把无关目录拒之门外。node_modules、构建产物、日志目录、.git这些都是token黑洞。只让Agent看它该看的文件。 -
任务描述里写清范围。比如“只改src/controllers下的文件”“不要动测试目录”，比笼统地说“帮我优化这个项目”省太多token。Agent不会自作主张去扫描整个仓库。
-
用小上下文入口。如果只是问一个简单的API用法、写一段小函数，不需要在项目目录里启动
claude。直接在任意目录启动后问问题，它不会加载项目上下文，消耗就少很多。
6.2 用Skills给Claude Code装上“私教课”
“claude code skills 官方文档”这个词条热度很高，说明很多人已经注意到Skills功能了。它的本质是：给Claude Code预设一套“行为规范+工具脚本”，让它遇到特定任务时按你定义的方法来干。
Skills的目录结构很简洁：
code复制.claude/
└── skills/
└── code-review/
├── SKILL.md
└── scripts/
└── review.py
SKILL.md用Markdown描述这个技能触发的条件、执行步骤、要读哪些文件、产出什么格式。比如我给自己写了一个“代码审查”Skill，内容是：
markdown复制---
name: code-review
description: 对当前项目的代码改动做一次全面审查，关注性能、安全和可维护性
---
1. 读取 git diff --stat 查看改动文件
2. 逐个文件审查，重点是性能瓶颈、安全问题、错误处理缺失
3. 输出审查报告，问题按严重级别排序
存好之后，只要跟Claude Code说“按我们的规范审查一下这次改动”，它就会自动加载这个Skill里的步骤执行。社区里已经有人做了生成PPT的Skill、写周报的Skill，本质上都是这套机制。
6.3 MCP接入数据库：让Agent直接查表
“claude code 安装mcp读取数据库”这个需求很典型。MCP（Model Context Protocol）是Anthropic推动的一个开放协议，目的是让AI模型能标准化地外接各种工具。Claude Code对MCP的支持是原生级别的。
添加一个Postgres数据库服务端：
bash复制claude mcp add --scope user my-db \
-- npx @modelcontextprotocol/server-postgres \
--connection-string "postgresql://user:pass@localhost:5432/mydb"
然后在Claude Code会话里，它就能看到my-db提供的工具，比如query、list_tables。你可以直接说“查一下users表里最近10个注册用户的邮箱”，它就会自己调用工具、执行SQL、把结果整理给你。
MCP的价值在于：Agent不再局限于“读代码”，而是能触达真实的业务系统。排查线上问题的时候，让它直接查数据库比对数据，效率比人肉复制粘贴高一个量级。
6.4 把DeepSeek/Ollama接进来跑本地模型
“claude code接入deepseek”“claude code + cc switch + ollama”这两个搜索词热度不低。这个需求本质上是：不想用Anthropic官方API，想让Claude Code跑在别的模型上。原理是通过环境变量把模型接口重定向到OpenAI兼容的网关：
bash复制export ANTHROPIC_BASE_URL="http://localhost:3000"
网关层可以用LiteLLM、one-api这类工具，把OpenAI格式的请求转成Claude格式，或者直接用社区方案claude-code-router。接到DeepSeek之后，启动claude，底层驱动模型就是DeepSeek了。Ollama同理，本地起一个模型服务，走同样的转发层。
但这里我要泼一盆冷水：这种方案只适合实验和预算敏感的项目。原因有两个：
- Claude Code的很多系统提示词、工具调用协议，是围绕Claude模型调优的。换到别的模型后，工具调用的准确率、长任务规划的稳定性都会明显下降；
- 本地小参数模型跑复杂代理任务，速度和正确率都跟不上，体验和官方模型差距很大。
所以我的建议是：本地模型/Ollama拿来玩、学习、验证想法可以；生产级任务还是回到官方模型。
cc switch本身倒是值得单独说一句——它是社区里一个管理多账号/多配置的小工具，核心解决的是“我既想用Pro订阅、又想切API Key，或者在不同模型网关之间切换”的麻烦。如果只是个人使用，手写环境变量切换也够用；账号多的话，用cc switch确实省心。
7. 高频报错的实测排查记录：乱码、企业禁用、找不到CLI的连环坑
7.1 中文乱码问题
“claude code乱码问题”在Windows用户群里特别常见。表现是Claude Code输出中文变成乱码，或者输入中文提交后显示异常。根因基本都是终端编码不是UTF-8。
Windows PowerShell 5.1默认使用GBK编码，解决办法有两个：
第一，切成Windows Terminal，默认UTF-8，省心一半以上。
第二，老终端里手动切换：
powershell复制chcp 65001
还不行的话，检查系统区域设置是否开启了“Beta: 使用Unicode UTF-8提供全球语言支持”。开启后重启终端，乱码问题基本绝迹。
7.2 Your organization has disabled Claude subscription access for Claude Code
这个报错信息很长，完整出现是：
code复制Your organization has disabled Claude subscription access for Claude Code
它跟本地环境没关系，是账号层面的限制。如果你用公司发的Claude账号登录，管理员可能在企业控制台里关闭了“Claude Code订阅访问”权限。那就不是你能在本地解决的问题了：
- 找管理员确认企业策略，看看能不能开放Claude Code权限；
- 或者换个人订阅账号登录；
- 或者改用
ANTHROPIC_API_KEY这种API方式绕过订阅限制——注意前提是你的Key本身有权限。
7.3 切换Node版本后CLI“消失”
这个坑我踩得特别扎实。我用nvm管理Node版本，某次切换Node版本后，claude命令直接报“不是内部或外部命令”。原因很简单：npm全局包是按Node版本独立安装的，切到另一个Node版本，全局包目录也跟着变了。
解决办法：
bash复制nvm use <你的项目Node版本>
npm install -g @anthropic-ai/claude-code
或者直接用claude的绝对路径启动，绕开PATH查找。如果你用Volta、fnm，原理一样：切换Node版本后，全局CLI需要重新装一遍。
7.4 安装过程的权限与缓存问题
还有两类低频但遇到了就很烦的问题：
- npm全局安装报
EACCES：这是npm全局目录权限不足，别用sudo硬装，用第2章说的npm config set prefix改到用户目录最干净； - 安装后版本号没更新：
npm cache clean --force清掉缓存再重装，十有八九能解决； - 某些网络环境下
npm install超时：可以用镜像源，但注意镜像同步有延迟，新版本可能刷不出来。
我的习惯是，凡是CLI类工具装完第一次跑不起来，先按顺序排查：环境变量PATH、Node版本、权限、缓存。这四板斧解决九成问题。
用了大半年Claude Code，最大的感受是：它把“AI写代码”这件事从“聊天框里生成一段代码”推进到了“把整个开发任务交给Agent去执行”。这种转变带来的效率提升是真实的，但前提是你要愿意把终端当成工作台、愿意花一个下午把环境打磨顺。工具本身还在快速迭代，今天写的安装方式，过几个月可能会有更傻瓜的官方安装包，但底层那套“Agent在本地环境里自主执行任务”的模型，大概率会一直沿下去。希望你读完这篇，能少走几个我已经替你们蹚平的弯路。