Claude Code完全指南：终端AI编程助手的安装、配置与实战

Claude Code最近在开发者圈子里热度确实高，我身边不少人都在用它。如果你还没搞明白这玩意到底是什么、怎么装、怎么配，这篇文章正好帮你一次性理清楚。它本质上是一个跑在终端里的AI编程助手，和你在网页上跟AI聊天完全是两回事，它能直接读你项目里的文件、帮你改代码、执行命令，甚至能自己跑测试，基本相当于给终端配了一个懂代码的副驾。这篇内容我尽量用大白话把安装、配置、常见问题都讲透，适合刚听说Claude Code、想上手试试的人，也适合装到一半卡住的朋友拿来当排查手册。

1. Claude Code到底是个什么东西

1.1 它不是网页对话框，而是住在终端里的Agent

网上很多介绍把Claude Code说成“AI编程助手”，这个说法方向对，但没有说到点子上。Claude Code的核心不是“问答”，而是“执行”。你可以把它理解成一个能操作你电脑的智能体，它运行在终端里，能读取你当前项目的目录结构、查看文件内容、调用命令行工具执行操作，然后根据对话目标持续迭代。

举个例子，你让它“修复一下登录接口的500错误”，它不是简单告诉你改哪行代码，而是会自己打开相关文件、定位可能的异常点、修改代码，然后运行测试验证结果。如果还报错，它会继续尝试，直到问题解决或者你喊停。这和你在Web端把代码粘进去再复制答案回来，体验上完全是两码事。

在终端里运行Claude Code，它通常还会配合claude这个命令来使用。安装完成后，你在项目根目录执行claude，它就进入交互模式。你可以用自然语言描述需求，也可以直接让它跑脚本、查日志、读配置文件，本质上它是把“IDE + 命令行 + AI”揉在了一起。

1.2 它适合谁来用

从适用人群来看，我大概分三类：

• 专业开发者：日常写业务代码、排查问题、做代码审查，能明显提效，尤其是处理重复性任务时省很多事。
• 懂点技术的爱好者：会打开终端、能装Node.js，想体验AI编程但又不想被复杂的IDE环境劝退，Claude Code的纯文本交互反而门槛更低。
• 做硬件开发或脚本类工作的人：比如写Verilog、Python脚本、Shell命令，Claude Code在终端里面跑非常顺手，不需要来回切换窗口。

1.3 官方认证、第三方模型和本地模型的选择

围绕Claude Code的热门话题，除了它本身的安装使用，还有一个很关键的方向：拿它接不同的模型。默认情况下Claude Code面向的是Anthropic官方的Claude系列模型，需要登录或者配置API Key。但社区很快发现，Claude Code的命令行底层构架比较开放，可以通过改配置接入别的兼容接口，比如DeepSeek、智谱GLM，甚至是完全跑在本地电脑上的Ollama模型。

这个自由度也是Claude Code能火起来的重要原因之一。它不再是“必须用某一家服务的封闭工具”，而是变成了一层通用的“终端Agent框架”，至于大脑是谁，可由你自己决定。官方模型效果好，第三方模型性价比高，本地模型数据不出门，各有各的适用场景。

2. 从零开始安装Claude Code

2.1 安装前需要准备什么

Claude Code本质上是一个基于Node.js的命令行工具，所以第一步是确保电脑上装了Node.js和npm。这里有个容易踩的坑：版本不要太老。我见过多次因为Node.js版本过低导致的安装失败或运行报错。建议装18以上的版本，稳妥起见直接用20 LTS或22 LTS。

检查是否已安装，可以在终端里执行：

node -v npm -v

如果提示找不到命令，那就先去Node.js官网下载LTS版本安装，千万别图新装Latest，后面会吃亏。装完Node.js后，npm会随之一起装好。

另外，Claude Code官方推荐的安装方式是用npm全局安装：

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

装完以后执行claude --version，如果能输出版本号，说明核心安装已经成功。

2.2 Windows下的PowerShell安装报错排查

Windows用户最容易在这里栽跟头。常见的报错长这样：claude : 无法加载文件，因为在此系统上禁止运行脚本。这是PowerShell的执行策略在拦你，它默认不允许运行未签名的脚本。

解决办法有两个，二选一：

方法一：临时放开当前用户的执行策略（推荐）

在PowerShell里执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

这条命令的意思是：当前用户允许运行本地脚本，远程下载的脚本需要有签名。设置完以后重新打开终端，再看claude命令是否可用。

注意：执行策略是安全机制，不要图省事直接设成Unrestricted，那样风险太大。RemoteSigned足够日常开发使用。

方法二：用管理员身份提权绕过

右键点击PowerShell，选择“以管理员身份运行”，然后再执行npm install -g @anthropic-ai/claude-code。这种方式适用于个别环境策略加密较严的情况。

还有一类Windows安装报错是npm本身的权限问题，比如提示EPERM或者EACCES。这种情况多半是npm的全局目录没有写入权限，解决办法是不要用默认的npm全局目录，单独配置一下：

npm config set prefix "$HOME/.npm-global"

然后把这个路径加到系统PATH里。再重新执行：

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

2.3 macOS和Linux安装的注意事项

macOS和Linux相对省心一些，直接在终端里执行：

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

macOS如果提示权限不足，尝试在前面加sudo，或者先执行sudo chown -R $(whoami) $(npm config get prefix)来修正npm目录归属权。不建议一上来就加sudo，能不加就不加，权限问题最好从根源上排查。

Linux需要留意的是shell环境变量。如果claude命令装完以后找不到，先检查npm全局bin目录是否在PATH里。用以下命令看一下：

npm config get prefix

然后把这个值拼上/bin加进~/.bashrc或~/.zshrc：

export PATH="$(npm config get prefix)/bin:$PATH"

2.4 桌面版和VSCode插件的安装区别

搜索热词里反复出现“claude code桌面版”、“claude code for vscode”这些词，很多同学可能搞混了它们和命令行版本的关系。

先说桌面版。Claude Code桌面版（Claude Code Desktop）是一个带图形界面的壳，底层封装了同一套Claude Code引擎。它的价值在于把终端交互转换成了图形化窗口，适合不习惯纯终端操作的人。如果你对终端一点也不排斥，直接用命令行版体验差不多。

再说VSCode插件。Claude Code官方提供了VSCode集成插件，装好插件的核心目的是在VSCode底部的终端里直接唤起claude，并不替代命令行版本，你仍然需要先通过npm安装Claude Code本体。插件的好处是可以把对话侧边栏和编辑器结合起来，查看上下文更直观，对习惯图形界面开发的用户来说节省了来回切窗口的时间。

在VSCode里使用Claude Code，基础操作就是在终端里敲claude进入交互，然后开始对话。如果你用的是第三方模型或本地模型，VSCode插件默认配置可能不生效，需要在项目根目录下手动创建配置文件来切换模型，具体配置方式在后面详细讲。

3. 配置模型接入：从官方认证到本地模型

3.1 为什么需要配置模型，默认入口怎么处理

Claude Code安装后第一次运行，会让你登录Anthropic账号或填写API Key。如果你有官方订阅或者API余额，直接用就行，这是最省心的路径，开箱即用。

但现实中很多人没有官方账号，或者想把Claude Code接到自己已有的第三方模型服务上。这不代表Claude Code不能用，它只是默认入口指向官方，不代表只能走这一条路。社区里现在最流行的做法，就是通过环境变量和配置文件，把Claude Code接到其他模型的兼容接口上。

3.2 用Ollama接本地模型

Ollama是现在本地跑大模型最方便的工具之一，支持Llama、Qwen、DeepSeek等一堆模型。

第一步，安装Ollama并下载一个模型：

ollama pull qwen2.5-coder:7b

第二步，让Ollama作为服务运行，默认端口是11434。第三步，给Claude Code设置环境变量，指向Ollama的接口。在终端里设置环境变量的参考做法：

export ANTHROPIC_BASE_URL="http://localhost:11434" export ANTHROPIC_AUTH_TOKEN="ollama" export ANTHROPIC_MODEL="qwen2.5-coder:7b" export ANTHROPIC_SMALL_FAST_MODEL="qwen2.5-coder:1.5b" export ANTHROPIC_API_KEY="ollama"

注意：上面这些变量名在不同版本的Claude Code里可能有调整。配置完以后，在项目目录里运行claude，如果顺利进入对话界面，就说明本地模型通道已经打通了。如果提示模型名不被识别，说明你的Claude Code版本不认识这个模型名，需要检查变量是否设置正确，或者用claude model命令查看当前可用的模型列表。

用本地模型最大的好处是数据不出本机，也不花Token费用，代价是模型参数小、效果肯定不如云端大模型，适合写点简单脚本、处理不复杂的重构任务。

3.3 接入DeepSeek或其他第三方模型

除了本地模型，现在很热门的是把Claude Code接到DeepSeek、智谱GLM这些国产模型的开放接口上。因为它们的API格式基本兼容Anthropic的调用协议，所以理论上只要改几个环境变量就能用。

以DeepSeek为例，比较常见的配置方式是：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_AUTH_TOKEN="你的DeepSeek API Key" export ANTHROPIC_MODEL="deepseek-chat" export ANTHROPIC_SMALL_FAST_MODEL="deepseek-chat" export ANTHROPIC_API_KEY="你的DeepSeek API Key"

然后运行claude，测试一段对话看能否正常返回。

如果你习惯把配置写进项目里，可以在项目根目录创建.claude/settings.json：

{ "env": { "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic", "ANTHROPIC_AUTH_TOKEN": "你的DeepSeek API Key", "ANTHROPIC_MODEL": "deepseek-chat", "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-chat" } }

注意：不同第三方平台用于Claude Code的接入地址不完全一样，有的平台是/anthropic路径，有的可能是/v1。如果你的请求总是报401或404，优先去对应平台官方文档里看看接入长什么样。

接入第三方模型的意义非常直接：省钱。Claude Code的强项在于终端Agent的编排能力，也就是“它能把任务拆开、读文件、改代码、跑测试”这一整套动作，而真正消耗Token大头是模型本身。换一个便宜的模型做同样的事，成本能降好几倍。

3.4 界面配置、Skill机制与settings.json

社区里越来越多人讨论Claude Code的Skills机制。所谓Skills，就是一套程序化的指令集，相当于给Claude Code定义了一套“做事规矩”。比如你希望它在写代码前先画测试用例、改完代码后自动跑语法检查、提交前自动生成commit message，这些都可以通过Skills来约束。

在Claude Code的配置目录（一般是~/.claude/或项目根目录下的.claude/），你可以写自定义Skill文件。每个Skill本质上是一个描述性的Prompt模板，Claude Code在遇到相关任务时会自动加载这个模板，从而保证输出风格和行为一致。官方文档里对Skills的描述比较简洁，但实际用起来你可以写得非常细。

新手最需要掌握的是settings.json，它管三件大事：模型接入、权限控制、行为偏好。简单说，你在~/.claude/settings.json写的配置是全局的，在项目.claude/settings.json写的配置是只对这个项目生效的。如果两边配置有冲突，项目级别的配置优先级更高。

4. Claude Code日常使用命令与关键操作

4.1 最常用的命令清单

Claude Code安装好、配置完模型之后，真正能不能提效，取决于你对命令的熟悉程度。我整理一下平时最高频用到的一组命令：

• claude：在当前目录启动交互式聊天。
• claude "描述你的需求"：直接启动并附带上第一条消息，适合写脚本时快速调用。
• claude -p "生成一个requests脚本"：-p表示非交互模式，输出结果后直接退出，适合在Shell脚本、CI流程里调用。
• claude --continue：继续上一次会话，能继承之前的上下文，非常适合在完成一次大修改后复查、收尾。
• claude --resume：进入一个会话选择界面，可以指定恢复某一次历史对话。
• claude model：查看或切换当前使用的模型。
• 在交互界面中按Shift+Tab：可以查看所有可用命令；按/：可以输入斜杠命令，比如/clear清空对话上下文、/status查看当前任务状态。

4.2 如何保存和恢复对话历史

很多新手会问Claude Code怎么保存对话历史。它在设计上其实自带会话持久化能力，你每次结束对话，它都会把会话记录保存在本地。下次运行claude --continue能直接回到上次的话题，这一点在IDE时代可能不太有感觉，但对于终端工具来说太重要了。

如果你做的是长周期任务，比如一个功能从设计到实现可能要改好几轮，我习惯这样用：每天开工先claude --continue，它会自动载入昨天所有上下文，我可以直接说“昨天留下的问题A解决了吗”，它能接得住。

除了官方自带的会话恢复，还可以通过给settings.json里的行为配置项加上自定义存储路径，把历史记录存到指定目录做备份。具体字段各版本略有差异，但这个思路是通用的。

4.3 怎么用才不费Token

提到Token消耗，这是用户搜索频率超高的问题。Claude Code这种终端Agent和聊天工具最大的不同是：它会在后台“偷偷”读很多文件、执行很多命令，这些动作全都要消耗Token。所以省Token的核心思路不是少问问题，而是“控制上下文长度”。

我总结了几条实测很有效的省Token经验：

• 控制工作范围：启动Claude Code时，先进到项目子目录而不是项目根目录。如果只是改某一个模块，就让它在固定目录下工作，它就不会去扫无关的文件。
• 及时清空上下文：当一个任务完成、要切换另一个无关任务时，在交互界面里执行/clear清空上下文，不然它会延续之前读过的文件内容，白白占Token。
• 给足明确约束：每次描述需求时，明确告诉它“只改src/utils下的文件，不碰其他地方”。Claude Code执行任务时会频繁读文件列表和文件内容，范围限制得越死，后台Token消耗越少。
• 把大文件拆出去：如果项目里有很大的配置文件或数据文件，Claude Code在读上下文时会整个吞进去，非常费Token。建议在.claude/settings.json里配置排除规则，把不需要模型看的目录和文件类型拦在外面。
• 用-p模式做一次性任务：像“给这段日志提取报错关键词”这种单纯的问答，直接用-p模式跑，运行完立刻退出，不会把上下文留在交互会话里。

4.4 权限控制：用它改代码前先给它“上锁”

初次使用时我建议设置一下权限控制，让Claude Code在改动文件或执行命令前先征求你的确认。这功能在各版本中叫做权限模式（permission mode），配置项大致包含：

• allow：白名单，哪些命令可以直接执行，比如ls、cat这类无副作用的命令。
• deny：黑名单，哪些命令直接禁止，比如rm -rf。
• ask：需要询问的敏感操作，比如修改文件、安装依赖包等。

在settings.json里大概长这样：

{ "permissions": { "allow": ["ls", "cat", "git status", "git diff"], "deny": ["rm -rf", "git push --force"], "ask": ["npm install", "git commit"] } }

这套配置能帮你减少不必要的误操作。尤其是AI自动执行命令时，如果它真的手滑执行了危险命令，白名单机制就是最后一道保险。

5. 常见问题与排查技巧

5.1 安装后提示could not locate the claude cli

这个报错在VSCode插件场景下特别常见：插件的安装路径里找不到claude命令行工具。核心原因很简单：插件只是“客户端”，还需要真正的CLI已经安装在系统里。

先确认系统终端里运行claude --version是否能正常输出。如果不能，说明CLI根本没装好，回到前面的安装步骤重新来一遍。如果能正常输出，但VSCode插件还是提示找不到，多半是VSCode没有继承Shell的PATH变量。

解决办法：重启VSCode，确保它是从终端里以你配置了claude命令的那个Shell启动的。还可以在VSCode的settings.json里手动指定CLI路径：

{ "claude-code.cliPath": "/usr/local/bin/claude" }

路径根据自己的环境来填，macOS/Linux用which claude查看，Windows用where claude查看。

5.2 模型名称不识别，提示is not a model this version recognizes

这属于配置错误里最容易遇到的一类。出现这类提示，说明Claude Code把请求发出去了，但接口返回的模型名不在它可识别的列表里。

排查思路分两步：第一步，确认你配置的ANTHROPIC_MODEL有没有写错，比如多了一个空格、少了一个字符，或者平台提供的模型名根本不是deepseek-chat，而是deepseek-coder或deepseek-reasoner，需要去平台后台核对。第二步，检查版本兼容性，如果你用的Claude Code版本太老，可能对新出的模型名不熟悉，需要先升级工具本体：

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

另外，如果用Ollama接本地模型，模型名写完整版本号很重要，因为Ollama的模型名带tag，比如qwen2.5-coder:7b，只写qwen2.5-coder会导致找不到。

5.3 乱码问题怎么解决

终端里出现乱码，常见于Windows PowerShell环境，尤其是中文Windows系统配合默认的GBK代码页，Claude Code输出UTF-8内容时就容易显示成乱码。

解决办法：在PowerShell里执行：

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

如果你想永久生效，把这一行添加到PowerShell的配置文件$PROFILE里。另外，在启动Claude Code之前，可以先执行chcp 65001把代码页切换到UTF-8。

5.4 你的组织已禁止Claude订阅访问

有些用户运行Claude Code时看到英文提示：Your organization has disabled Claude subscription access for Claude Code。这个信息本质上和安装、配置无关，是账号权限层面的限制。如果你用的是公司或学校统一分配的组织账号，管理员可能在管理后台关闭了Claude Code的订阅访问，要求所有成员必须通过API Key或者特定的集成方式才能使用。

解决办法是使用自己的个人账号登录，或者配置API Key。如果你不想用官方订阅，也可以直接用前面说的环境变量方式接第三方模型，绕开官方账号的认证流程。

5.5 VS Code接入本地Ollama失败

VSCode里配置本地模型失败，多数情况下不是你配置错了，而是VSCode终端的环境变量和系统终端不一样。你在系统终端里执行export设置的环境变量，VSCode新开的终端不一定能继承。

一个比较可靠的根因排查方法和解决办法是：在VSCode底部的终端里手动执行一遍环境变量的设置，然后再启动claude，确认能正常工作。如果这样可行，建议把这些环境变量写进系统的Shell配置文件（比如~/.zshrc或~/.bashrc），确保VSCode启动时能够自动加载。在Windows下，建议通过系统的“环境变量”面板添加，这样VSCode、PowerShell、CMD都能读到，避免只对某个终端生效导致的困惑。

5.6 常见问题速查表

5.7 多轮对话后变慢、回答质量下降怎么办

这个问题不算报错，但特别影响体验。多轮对话后Claude Code会积累大量上下文，导致响应变慢、Token消耗增加，甚至出现“答非所问”的情况。

我的建议是分阶段完成任务。比如一个需求涉及三个阶段，每完成一个阶段就执行/clear，让模型忘掉前面阶段的细节，然后开启新的会话，你只告诉它上一阶段的产出结论，再开始下一阶段。这样既保证了总体的方向感，又不会让上下文无限膨胀。你还可以在需要跨阶段保持信息时，用文件把中间结果保存下来，再在下一阶段让Claude Code读取这个文件，这比让模型一直“记着”所有细节要稳定得多。

6. 关于开源替代和生态扩展的一些想法

6.1 Claude Code和Codex有什么区别

很多人在网上纠结Claude Code和Codex到底该选哪个，甚至希望别人给个“谁更好”的结论。我的看法是：这俩的差异化远大于同质化。Codex更像一个深耕官方配套生态的助手，和自家IDE结合紧密，而Claude Code在终端里的开放度和可配置性更强，尤其是通过环境变量切换模型这一点，让它在社区里玩法非常多。

实际工作中我会做出选择：如果整条链路都在官方体系内且团队协作统一，那用Codex会省心；如果项目需要频繁对接异构模型、或者团队里有同学用的是不同平台，那Claude Code这层的灵活度就非常有价值，它更像是一个通用的Agent调度层。

6.2 为什么Claude Code社区如此关注本地模型

逛社区多了你会发现，讨论热度最高的帖子往往不是官方新功能，而是“用XX模型跑Claude Code”这种主题。原因不复杂：成本可控、数据隐私、离线可用、不怕被限流。

比如硬件开发场景里，代码涉及公司内部规范，不适合把源码送到外部API，本地模型就成了唯一可选方案。又比如学习场景，只想快速体验AI编程助手的流程，不想掏钱买订阅，那么通过Ollama接一个小模型跑通一遍流程，成本几乎为零。这套生态出来后，Claude Code的定位从“某个模型的专属客户端”变成了“个人电脑里的通用AI编程Agent”，这比单纯写代码要有想象空间得多。

6.3 Claude Code后续扩展方向

根据社区动向和个人经验，最值得关注的是下面这几条线：

• Skills机制的完善：把复杂的项目规范、团队约定、代码风格内置成Skill文件，换人、换项目都能保持同一套行为标准，这个思路特别适合团队使用。
• 与CI/CD流程结合：用-p模式在流水线里跑代码审查、自动生成变更说明，Claude Code完全可以当做一个远程编程机器人来用。
• 多Agent协作：目前Claude Code是一个会话一个Agent，后续如果能实现多个Agent并行处理不同模块、最后汇总结果，复杂项目的生产力会再上一个台阶。
• 更细的权限粒度：现在权限控制能做到“命令级别”，后续如果能做到“目录级别白名单”“文件类型白名单”，安全边界会清晰很多。

我个人在实际操作中的一个体会是，Claude Code不适合用来替代人的设计判断，它更像一个反应很快、很勤奋的实习生，你交代得越清晰，它做得就越好；你给一个大而空的题目，它可能交出一堆看似合理但方向偏离的东西。所以上手第一件事，先把你的项目结构、代码规范、目标文档准备好了再让它干活，你会发现它的靠谱程度提升不止一个档次。

假如你是因为看到“AI编程”这个概念入坑的，我的建议是不要在第一个星期就去研究所有命令的用法，先把最基础的三件事做透：装好它能跑起来、接上你想要用的模型、在项目里复现一次“改Bug到跑通测试”的完整流程。真正把这三件事做完，你对Claude Code的理解就已经超过了绝大多数停留在看教程阶段的人。