Claude Code 保姆级使用指南：从安装配置到接入 DeepSeek/Ollama-平芜编程栈

从“帮我写一个函数”到“帮我完成一次重构、跑通测试、修复编译错误”，AI 编程助手的形态正在从浏览器聊天窗口走向开发者的真实工作流。Claude Code 是这条线上被讨论最多的工具之一，它不是一个简单的代码片段生成器，而是一个直接运行在终端里的协作代理：能读取项目文件、执行命令、运行测试，也能根据报错信息反复修改代码，直到任务满足验收条件。

这篇文章会按保姆级的节奏，把 Claude Code 的完整使用链路讲清楚，从环境准备、安装认证、配置文件，到接入 DeepSeek、Ollama 等第三方或本地模型，最后用一个最小开发任务验证整条工作流。无论你是第一次接触 Claude Code，还是已经安装但不知道如何系统使用，只要熟悉终端基本操作，都能按文章顺序把工具跑起来。

先说明一点：Claude Code 的版本迭代速度很快，安装命令和部分配置在不同小版本间可能有差异。下文示例以 2026 年初常见安装方式和官方文档中的命令为准，实际操作时要以claude --version的输出和官方文档为最终依据。

1. 先说清楚 Claude Code 的角色边界：它不是编辑器，是一个终端协作代理

1.1 网页版 AI 助手和 Claude Code 的使用差异

很多人会把 Claude Code 和网页版 Claude 混淆。网页版的使用方式是“提问 - 回答 - 复制代码”，你还需要手动创建文件，再把代码粘贴进去。Claude Code 的默认工作模式完全不同：它会被启动在某个项目目录下，拥有读取文件、写入文件、执行命令的权限，可以查看 Git 状态、运行测试，然后基于真实反馈修改代码。

举一个典型场景。普通 AI 助手经常在“修改一个函数，但忘了另一个文件里的调用方”这件事上翻车。在 Claude Code 中，它会自己执行grep搜索哪些文件调用了这个函数，逐个检查调用点，再统一修改。这就是“代理”和“聊天机器人”的核心差别：它有上下文闭环，不再依赖你手动复制粘贴代码。

维度	网页版 AI 助手	Claude Code
交互位置	浏览器	终端
读取本地文件	通常不行	可以，限定在授权目录内
执行命令	不能	可以运行 bash 命令
修改文件	复制粘贴	工具直接写入并给出 diff
适合任务	单段代码、概念解释	多文件修改、重构、排错、测试

1.2 一个代理工具适合做什么，不适合做什么

Claude Code 适合的任务类型很明确：

多文件重构：修改接口签名，同步调整实现和调用方。
排错辅助：根据报错定位日志、查看代码、提出修复方案并验证。
测试维护：生成测试用例、运行测试、修复失败用例。
小需求开发：在仓库里从零实现一个内部模块。
工程代码讲解：让工具阅读代码后解释某个业务模块的设计。

不适合的场景同样要提前知道：

大型架构评审：上下文窗口有限，无法理解超大型代码库的全部边界。
高并发生产变更：需要人工演练、灰度、回滚，不应直接交给工具执行。
安全敏感操作：例如删除数据库、修改线上配置，必须加人工确认环节。

理解边界是使用 Claude Code 的第一课。后面的权限配置文件，本质上就是在围绕这个边界做控制。

2. 安装前的环境检查和依赖准备：版本不匹配会白折腾一圈

2.1 必须先准备的三样东西

Claude Code 本身是一个 Node.js 命令行工具，安装前需要确认本机环境是否满足条件。最常见的方式是通过 npm 全局安装，所以 Node.js 和 npm 是硬依赖。

需要准备的依赖清单：

依赖	作用	建议要求
Node.js	Claude Code 运行时	18.0 或更高
npm	包管理器，安装 Claude Code 用	随 Node.js 安装
Git	仓库操作，AI 查看 diff、提交变更时使用	2.x 及以上
Claude 账号	认证和计费基础	官方订阅或 API 密钥

检查命令：

node -v npm -v git --version

如果本机还没有 Node.js，建议直接安装一个长期支持版本。JDK 17 并不是 Claude Code 的强制依赖，但如果你打算用它写 Java 项目，再单独准备 JDK 即可。不要在没有任何版本管理的情况下随便下载安装包，这样后面排查版本问题时很难判断是哪个依赖出了问题。

2.2 官方安装方式和“安装包”问题

安装 Claude Code 的标准命令：

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

在某些网络环境下，npm 安装可能失败。这时先检查 npm 镜像配置：

npm config get registry

如果镜像不是官方源，可以临时换成官方源重试：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmjs.org/

安装完成后，验证版本：

claude --version

这里需要特别提醒：Claude Code 是官方发布的命令行工具，官方推荐安装方式就是 npm。网上流传的“Claude Code 本地部署安装包”“一键安装包”多数是针对其他开源模型或辅助工具做的打包，并不是 Claude Code 本体。如果你在非官方渠道看到打包好的二进制文件，要先确认它的来源、数字签名和内容，不要在生产环境直接安装来源不明的软件包。

2.3 项目权限也是环境准备的一部分

很多人安装完工具就急着使用，却忽略了权限准备。Claude Code 默认只在授权目录内读写文件，不会主动遍历磁盘内容。

首次在某个目录启动 Claude Code 时，工具会询问是否信任该目录。加入信任列表后，它才能读取文件、执行命令。如果目录里存在.claude/settings.json，工具会读取其中的权限规则；如果不存在，则使用默认权限。

不要在系统根目录或用户主目录这样的宽泛位置启动 Claude Code。推荐进入具体项目目录再启动，这样工具的工作边界清晰，误操作文件的风险也小。

3. 安装和首次登录：用最小步骤跑通官方认证

3.1 从零到第一次对话的最小闭环

安装完成后，在终端进入一个空目录：

mkdir claude-code-demo cd claude-code-demo claude

首次运行会提示登录，常见有两种方式：

使用 Claude 订阅账号登录，适合个人开发者。
使用 Anthropic API 密钥登录，适合按量计费或脚本调用。

在 Claude Code 界面输入/login可以打开认证流程。按提示在浏览器中完成授权，再回到终端继续使用。认证成功后，界面会显示当前上下文信息。

然后输入第一句话，不需要太复杂：

请告诉我你现在位于哪个目录，并简单介绍这个目录里的内容。

正常输出会显示当前目录路径，并提示目录为空或只有初始化文件。这意味着读取链路、权限链路、输出链路全部正常。

3.2 认证成功不等于配置完成，还要确认模型

认证只是第一步。很多新用户接下来会遇到困惑：为什么同一个提示词，在不同项目里表现不一样？原因通常是配置里的模型名称不一致。

查看当前配置：

claude config list

如果输出里有一项model被设置成不存在的模型名称，Claude Code 启动时会提示类似错误：

"deepseek-v4-pro" is not a model this version of claude code recognizes

这类报错在社区中出现频率很高。原因主要有两个：一是配置文件里的模型名写错了；二是当前版本或服务商并不支持该模型名称。排查思路会放在第 7 节展开。

3.3 常用斜杠命令：还没开始写代码前先记住

Claude Code 运行后，输入/help可以查看全部可用命令。以下高频斜杠命令值得先记下来：

命令	作用
`/status`	查看当前任务的自动提交记录和状态
`/compact`	压缩上下文，长会话中减少 token 消耗
`/clear`	清空当前对话历史
`/cost`	查看当前会话消耗
`/config`	查看或打开配置文件位置

退出时输入/exit或按Ctrl+C。再次进入同一个目录时，Claude Code 会保留一定程度的会话恢复能力，但跨目录调用或长期会话最好依赖/compact管理上下文，不要指望自动恢复解决所有问题。

4. 配置文件和常用参数：改之前先弄懂每个参数影响什么

4.1 配置文件层级和优先级

Claude Code 的配置分为多个层级，搞清楚优先级是排查“我的配置为什么不生效”的前提。

配置层级	路径	生效范围
项目级	`<项目目录>/.claude/settings.json`	只影响当前项目
用户级	`~/.claude/settings.json`	影响当前系统的所有项目
环境变量	shell 中 export 设置	临时覆盖，影响当前进程

优先级大致是：项目级配置优先于用户级配置，用户级配置优先于默认配置。遇到“配置没生效”时，先确认你改的到底是不是当前项目正在读取的那份文件。

创建项目级配置：

{ "permissions": { "allow": [ "Bash(npm run *)", "Read(./src/**)" ] }, "model": "claude-sonnet-4-5", "env": { "MY_CUSTOM_ENV": "example" } }

4.2 高频参数含义和调整影响

重点解释几个高频参数。

model：指定使用的模型。设置错误会出现模型识别失败，表现形式就是启动时报错 “is not a model this version of claude code recognizes”。遇到这种情况，先把配置清掉，回到默认模型跑通，再确认服务商到底支持哪个模型名称。

permissions.allow：允许工具在执行某些操作前不弹确认。写法要尽量窄，例如Bash(npm run *)只匹配以npm run开头的命令。不要直接写Bash(*)，否则 AI 可以执行任意命令，等于把当前项目机器完全交给模型控制。

permissions.deny：显式禁止某些操作，例如禁止读取生产环境密钥文件、禁止强制推送。

env：注入环境变量。注意不要把真实密钥长期写进项目配置文件，因为项目文件会进入 Git，存在密钥泄露风险。

参数错误配置的表现差异很大，用一张表格概括：

参数	调大/加宽的影响	调小/收紧的影响	错误配置的表现
model	模型能力更强，消耗更大	更省 token	模型名称不支持时报错
permissions.allow	减少打断，自动化程度高	确认频繁，更安全	允许过宽会执行危险命令
maxTokens	单次输出更长	输出容易截断	代码生成不完整
env	注入更多配置	缺少自定义变量	工具读不到所需变量

4.3 配置文件该不该提交到 Git

这里要分情况讨论。.claude/settings.json如果只包含权限规则和工具启停配置，可以提交到仓库，方便团队统一。如果里面包含真实 token、密钥、个人登录态，就不能提交。

推荐方式：维护一份settings.sample.json作为配置模板，真实配置放在本地，并加入.gitignore。这是多成员项目最稳妥的做法。

5. 接入其他模型和本地模型：Claude Code 不只能连默认服务

5.1 为什么会有“接入 DeepSeek、Ollama 本地部署”的需求

Claude Code 默认调用的是 Anthropic 官方模型服务。但很多人希望在已有工作流里，把模型推理部分切换到更便宜、更可控，甚至运行在本地的大模型。“Claude Code 接入 DeepSeek”“Ollama 本地部署”这些搜索热点，本质都是一件事：复用 Claude Code 的终端工作流，把模型改成其他服务商或本地模型。

实现原理其实不复杂：Claude Code 支持通过环境变量或配置指向一个兼容 Anthropic API 格式的服务端点。只要目标服务提供兼容接口，就能让 Claude Code 通过该接口调用模型。

注意：Anthropic 官方模型能力与第三方模型并不完全对等。接入第三方或本地模型后，Claude Code 的工具调用链路仍然能工作，但模型本身的推理水平、指令遵循能力会直接影响最终效果。不要因为能接上模型，就认为它能完整替代官方模型的表现。

5.2 通过环境变量接入兼容服务

通用做法是设置ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN，把 Claude Code 的请求指向自定义端点。

export ANTHROPIC_BASE_URL="https://your-compatible-endpoint.example.com" export ANTHROPIC_AUTH_TOKEN="your-token" export ANTHROPIC_MODEL="your-model-name" claude

这里的ANTHROPIC_MODEL设置模型名称。如果端点不认识这个名称，就会报出类似 “is not a model this version of claude code recognizes” 的错误。遇到这类报错，先确认当前终端是否残留了自定义端点的环境变量。

Windows PowerShell 下：

$env:ANTHROPIC_BASE_URL = "https://your-compatible-endpoint.example.com" $env:ANTHROPIC_AUTH_TOKEN = "your-token" $env:ANTHROPIC_MODEL = "your-model-name" claude

5.3 接入 Ollama 本地模型的示例

如果本机安装了 Ollama，并拉取了qwen2.5-coder:7b等模型，可以尝试把 Claude Code 指向本地服务。

先确认模型存在：

ollama list

如果列表里已有模型，说明本地推理服务可用。Ollama 默认 API 地址通常是http://localhost:11434，但 Ollama 原生 API 与 Anthropic 消息格式并不完全一致，直接设置ANTHROPIC_BASE_URL不一定能成功。

通常需要额外安装一个支持 Anthropic 兼容格式的本地网关层，再把ANTHROPIC_BASE_URL指向网关地址。具体安装步骤依赖网关工具版本，落地前要阅读网关工具自己的 README，确认环境变量名和请求格式，不要照抄网上过期教程。

接入成功后，用一句话验证：

请用中文解释什么是函数柯里化，并给出一个 TypeScript 示例。

如果输出来自本地模型，说明链路已经打通。但要注意：本地小参数模型在复杂代码任务上准确度会明显偏低，适合用来学习流程和验证配置，不适合直接用于生产级代码审查。

5.4 接入 DeepSeek 等在线第三方时要注意什么

接入在线第三方服务时，下面几点优先确认：

服务商是否提供 Anthropic 兼容接口，还是需要自己搭网关转换。
接口地址是否支持 HTTPS，密钥是否只放在环境变量里。
模型名称是否在服务商官方文档中列明，不要自己猜测。
调用速度、并发限制、计费方式是否适合你的使用场景。

“Claude Code 接入 DeepSeek”在社区里讨论度很高，但从技术原理看，和接入任何兼容端点没有本质区别。具体的 API 地址、模型名称会随服务商更新变化，实际配置前务必以服务商最新文档为准。

6. 用一个小需求完整走一遍开发闭环：从任务描述到测试通过

6.1 一个适合第一次练习的多文件任务

为了验证 Claude Code 的真实工作流，这里设计一个简单但完整的任务：在一个空 Node.js 项目中，实现一个统计文本中单词出现频率的命令行工具。任务包含仓库初始化、模块设计、实现、测试、运行验证，适合作为第一次完整使用 Claude Code 的练习。

mkdir word-freq cd word-freq claude

在对话中输入需求，尽量把验收条件写清楚：

在这个目录下创建一个 Node.js 命令行工具。需求如下： 1. 读取命令行传入的文件路径。 2. 统计文件中单词出现次数，忽略大小写和标点。 3. 按出现次数降序输出，相同次数按字母升序。 4. 使用 Node.js 内置模块完成，不引入第三方依赖。 5. 提供 npm test 可运行的测试。

提示词里的每一条都对应一个验收点。给 AI 明确验收条件，比笼统地说“写个工具”要有效得多。

6.2 AI 生成代码时，你要观察什么

Claude Code 会创建文件并运行命令。在关键节点，它会停下来请求确认。例如：

创建package.json
创建src/index.js
运行node src/index.js验证输出
创建test/index.test.js

你应该关注：

文件是否都在当前项目目录内。
包名、入口文件是否合理。
测试是否覆盖了大小写、标点、空文件等边界。
命令是否只影响当前项目目录。

如果想确认工具对项目的理解，可以追问：

请解释你刚才的目录结构和每个文件的作用。

这能帮你判断它是否真的理解了需求。

6.3 运行测试，不是看“能启动”就够了

假设 Claude Code 生成的文件结构是：

word-freq/ package.json src/index.js test/index.test.js

在终端执行：

npm test

预期看到测试全部通过。再用一条真实文本验证：

echo "Hello world. Hello Claude Code." > sample.txt node src/index.js sample.txt

预期输出：

hello: 2 claude: 1 code: 1 world: 1

如果输出和预期不一致，把报错信息贴回 Claude Code 对话，让它继续修复。这个“运行 - 报错 - 修复 - 重跑”的迭代闭环，是 Claude Code 最有价值的地方。

6.4 任务完成后的检查清单

AI 辅助开发完成后，建议按清单检查：

所有文件是否在当前项目目录内，没有意外改动外部路径。
代码是否引入了不必要的第三方依赖。
测试是否覆盖了主要输入边界。
是否查看了关键 diff，而不是直接全盘接受。
是否把敏感信息留在代码或配置里。
Git 提交信息是否清晰可追溯。

这份清单适合作为 AI 辅助开发的通用检查项，不只是针对 Claude Code。

7. 常见的 6 类报错和排查路径：按现象倒推根因

7.1 排查逻辑先从“输入是否正确”开始

Claude Code 的报错形式很多，但大部分根因集中在少数几层。遇到问题，按下面顺序排查：

配置里是否设置了自定义模型端点或模型名称。
当前 shell 环境变量是否残留旧值。
依赖版本是否匹配。
是否在授权目录内启动。
网络和认证状态是否正常。
日志中是否有具体的错误信息。

7.2 常见报错速查表

问题现象	常见原因	检查方式	处理建议
启动报错 “is not a model this version of claude code recognizes”	配置或环境变量中的模型名称在当前版本/服务商中不存在	执行`claude config list`和`env \| grep -i anthropic`	清空自定义 model，或改为服务商文档列出的模型名
安装命令提示 npm 权限不足	全局目录无写权限	`npm prefix -g`查看安装目录	用 nvm 管理 Node，避免直接改系统目录权限
提示无法读取项目文件	没有信任当前目录	查看启动时是否出现信任确认	确认目录确实需要授权后，再允许访问
执行命令时一直被拒绝	permissions 配置不够宽	查看`.claude/settings.json`的 allow 和 deny	按需增删允许前缀，不要放开 Bash(*)
认证成功但会话无法恢复	换目录或缓存被清理	查看启动提示和会话保存路径	重要上下文用`/compact`或写成任务文档
接入本地模型后回复慢或乱答	本地模型参数太小，或网关格式转换错误	查看本地服务日志和请求地址	先跑通最简单的对话，再逐步增加工具调用

7.3 模型名报错专项排查

在“Claude Code 接入 DeepSeek 或本地模型”的场景中，最典型报错就是模型名不被识别。

逐步排查：

# 1. 检查当前是否有自定义 base url 或模型名 env | grep -i ANTHROPIC # 2. 查看 Claude Code 当前配置 claude config list # 3. 临时清空自定义模型名，回到默认

如果确认没有自定义配置，但模型名仍不被识别，常见原因是本机缓存了过期配置或版本过旧。先重启终端，再更新到最新版本：

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

如果问题依旧，备份自己的自定义配置后，清除 Claude Code 的本地缓存目录再启动。

7.4 日志和反馈是最后的证据

很多用户遇到问题只贴一句报错，很难定位。排查时，可以让 Claude Code 提供完整的运行信息：

请把刚才运行测试的命令、完整输出和退出码贴出来。

同时执行最小化还原：清空自定义配置、使用默认模型、在最小目录中测试。这一步能过滤掉大量干扰因素。

Claude Code 保姆级使用指南：从安装配置到接入 DeepSeek/Ollama