Claude Code 深度教程：从安装到接入 DeepSeek 与本地模型-迪斯科星球

如果你最近在刷技术社区，八成会看到一个高频词：Claude Code。有人把它吹成“吊打付费神器”，有人拿它搞自动化重构，还有人用它连着本地模型做私有化开发。但大部分教程要么只讲安装，要么只贴几个命令，真正能让你从零跑通、理解原理、学会排错的内容反而不多。

这篇文章我会一次性讲清楚 Claude Code 的完整使用链路：包括它是什么、怎么安装、怎么配置、怎么接 DeepSeek 和本地模型、怎么在 VS Code 里用，以及最常见的报错怎么排查。内容尽量照顾零基础读者，也会给有经验的开发者一些能直接拿去用的配置和工程建议。

1. Claude Code 是什么：终端里的 AI 编程搭档

1.1 为什么突然大家都在聊 Claude Code

Claude Code 是 Anthropic 推出的一款命令行 AI 编程工具，它跑在终端里，能读取你的项目文件、搜索代码、运行命令、修改文件，甚至替你跑测试。

和传统的“AI 对话框”不同，Claude Code 不是让你复制代码再粘贴回去。它直接操作整个项目工作区，就像你的终端里坐了一个能看懂代码、能执行命令的结对编程助手。

很多开发者习惯用 ChatGPT 写代码片段，但 ChatGPT 不知道你项目的上下文，你每次都要贴文件、说明需求、再把生成的代码粘回编辑器。Claude Code 的定位就是解决这个割裂问题：它直接进入你的项目目录，自己读文件、自己改代码、自己运行验证。

1.2 它能做什么，不能做什么

先把能力边界说清楚，免得你抱着不切实际的期望。

Claude Code 的核心能力：

读取并理解整个项目结构，不只是单个文件。
检索关键词、定位函数定义、查看调用关系。
修改代码文件，支持多处改动。
执行终端命令，比如运行测试、打包、静态检查。
通过 CLAUDE.md 记录项目约定，实现跨会话记忆。
支持非交互式调用，可以写进脚本和 CI 流程。
通过配置项对接其他模型 API，比如 DeepSeek 或本地模型服务。

它不擅长做的事：

它本身没有“视觉界面”，需要和 VS Code 或桌面端搭配。
它默认依赖远端模型能力，离线状态无法调用云端模型。
它对项目完全陌生时，需要你提供足够上下文，否则也会瞎猜。
涉及生产环境、权限变更、破坏性操作时，它有确认机制，但最终责任仍然在开发者。

1.3 适用人群与典型场景

个人开发者：用来写脚本、做小工具、改造旧项目。
后端团队：让 AI 辅助处理重复 CRUD、接口补全、测试编写。
学习编程的新手：通过对话了解代码逻辑，快速建立项目认知。
需要私有化或低成本方案的团队：把 Claude Code 接到 DeepSeek 或本地模型上。

2. 环境准备与安装

2.1 环境要求

Claude Code 本质上是一个 Node.js 命令行程序，所以你需要先准备好 Node.js 环境。常见操作系统都可以用，包括 macOS、Windows、Linux。

官方对 Node.js 的版本有最低要求，一般建议使用 Node.js 18 或更高版本。如果你的系统里已经有 Node.js，可以先检查版本：

node -v npm -v

如果提示命令不存在，就需要先安装 Node.js。

2.2 安装 Node.js

macOS 用户推荐用 Homebrew：

brew install node

Windows 用户可以到 Node.js 官网下载 LTS 版本安装包，或使用 winget：

winget install OpenJS.NodeJS.LTS

Ubuntu / Debian 可以使用 NodeSource 源安装：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs

安装完成后重新打开终端，确认版本号能正常显示：

node -v

2.3 使用 npm 安装 Claude Code

推荐使用全局安装。打开终端后执行：

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

安装过程可能需要几十秒。完成后检查版本：

claude --version

如果 Mac 或 Linux 提示权限错误，可能是 npm 全局目录权限问题。更推荐配置 npm 全局目录到当前用户目录下，避免使用 sudo 安装：

mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' export PATH=~/.npm-global/bin:$PATH source ~/.bashrc

然后再重新执行安装命令。

2.4 离线安装包与本地部署说明

很多人搜索“Claude Code 本地部署安装包”，本质上是要在本机装好 Claude Code，而不是在网页里用。

官方主推 npm 安装方式和原生安装脚本。如果你所在环境无法访问 npm 官方源，可以配置国内 npm 镜像：

npm config set registry https://registry.npmmirror.com

也可以使用官方原生安装脚本：

macOS / Linux：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

关于“离线安装包”，社区中确实有把 Claude Code 和依赖打包成离线压缩包的方案，适合内网环境。但这类包往往版本滞后，也不是官方发布，建议优先使用官方安装方式。如果一定要离线安装，拿到压缩包后通常需要解压到全局 node_modules，并把 bin 目录加入 PATH，具体操作要看打包者的说明。

2.5 验证安装

安装完成后，在任意目录执行：

claude --help

如果能看到命令帮助列表，说明安装成功。执行claude会进入交互式界面，第一次运行时可能需要登录或配置 API 凭据，这部分我们下一节详细讲。

3. 十分钟快速入门：从零跑通第一个任务

3.1 完成 API 认证

Claude Code 本质上要调用模型服务，所以必须有认证凭据。常见两种方式：

使用 Anthropic 官方账号认证。
使用 Anthropic API Key 或第三方兼容 API 的 Token。

如果是官方账号，执行claude后按提示在浏览器中完成登录即可。

如果使用 API Key，可以设置环境变量：

export ANTHROPIC_API_KEY="你的API密钥"

如果使用 DeepSeek 这类第三方兼容服务，需要设置几个额外环境变量，后面专门有一节讲。

3.2 启动交互界面

进入项目目录后执行：

cd /path/to/your-project claude

启动后会进入一个交互式会话。你会发现它已经开始扫描项目结构，你可以直接输入自然语言描述任务。

第一次使用时，如果项目较大，它可能需要一些时间建立索引。耐心等一会儿即可。

3.3 给 Claude 分配第一个任务

假设你有一个 Python 项目，你可以直接输入：

请帮我看看这个项目的结构，并告诉我入口文件在哪里。

Claude 会调用文件读取工具，搜索目录结构，然后给出结论。

你也可以让它直接改代码。比如：

在 utils.py 中添加一个函数，用来计算两个日期之间的工作日天数。

Claude 会修改文件，并给出改动说明。修改完成后，你可以打开文件查看具体变化。

3.4 常用内置命令

在交互界面中，斜杠开头的是 Claude Code 的内置命令：

命令	作用
`/clear`	清空当前会话上下文
`/config`	查看和修改配置
`/init`	生成项目的 CLAUDE.md 档案
`/status`	查看当前会话状态
`/compact`	压缩会话上下文
`/help`	查看帮助

非交互模式下，可以直接使用-p参数执行一次性任务：

claude -p "请解释 src/main.py 的核心逻辑"

也可以把多个文件传给 Claude：

claude -p "请检查这两个包之间的版本兼容性" package.json requirements.txt

这种模式适合写脚本，也适合接入 CI 流水线。

4. 核心配置与原理：从“能用”到“好用”

4.1 CLAUDE.md 项目档案

CLAUDE.md 是 Claude Code 最核心的机制之一。它相当于项目的“交接文档”，Claude 每次启动会读取它，从而了解项目规范、常用命令、目录结构等信息。

在项目根目录创建CLAUDE.md：

# 项目说明 这是一个基于 Flask 的待办事项 API 服务。 ## 技术栈 - Python 3.11 - Flask 2.3 - SQLite ## 代码规范 - 所有接口返回 JSON - 数据库操作使用 SQLAlchemy - 配置项放在 config.py 中 ## 常用命令 - 启动服务：python app.py - 运行测试：pytest tests/ - 代码格式化：black .

有了 CLAUDE.md，Claude 生成的代码会更贴合项目风格，也会少问很多“你的数据库是什么”这类基础问题。

你也可以用/init命令让 Claude 自动生成这个文件。

4.2 环境变量与模型路由

Claude Code 通过环境变量控制模型服务和认证信息。下面这些变量是最常用的：

环境变量	作用
`ANTHROPIC_API_KEY`	Anthropic 官方 API Key
`ANTHROPIC_AUTH_TOKEN`	第三方兼容 API 的 Token
`ANTHROPIC_BASE_URL`	模型接口地址，可指向官方或本地服务
`ANTHROPIC_MODEL`	使用的模型名称
`ANTHROPIC_SMALL_FAST_MODEL`	小请求使用的轻量模型

注意：ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN作用类似，推荐在第三方服务时使用ANTHROPIC_AUTH_TOKEN，在官方服务时使用ANTHROPIC_API_KEY。

4.3 settings.json 与项目级配置

Claude Code 支持在项目目录中创建.claude/settings.json，用于配置权限白名单和模型参数。

示例：

{ "permissions": { "allow": [ "Read", "Grep", "Glob", "Bash(npm run *)", "Bash(pytest *)" ], "deny": [ "Bash(rm -rf *)" ] }, "model": "claude-sonnet-4-5", "env": { "MY_CUSTOM_VAR": "your-value" } }

这里的权限配置非常重要。默认情况下，Claude 执行命令前会征求你的许可，白名单可以让你免去重复授权。

需要提醒的是：不要把敏感密钥写进 settings.json 并提交到 git 仓库。密钥应通过环境变量注入。

4.4 权限、确认机制与安全性

Claude Code 能修改文件和执行命令，这意味着它有破坏力。它的默认安全策略是：执行敏感操作前先询问用户。

常见的操作类型包括：

修改文件。
执行终端命令。
安装依赖。
删除文件。
推送 git 提交。

在生产服务器或重要项目中，建议把权限收敛得更严一些，比如默认 deny 掉所有 Bash 执行，只允许特定命令。

我在项目中喜欢这样处理：

本地开发项目：允许 npm / pytest 等常规命令。
生产服务器：只允许 Read、Grep、Glob，禁止执行写命令。
涉及数据库或删除操作：强制每次确认。

5. 完整实战：用 Claude Code 完成一个小项目

5.1 实战场景设定

我以一个最简单的 Python 脚本项目为例，演示 Claude Code 从零到一的完整工作流。

假设场景：写一个脚本，读取 CSV 文件，按某一列分组统计，然后输出统计结果。

整个流程包含：

创建项目目录。
让 Claude 读取目录并理解任务。
生成核心代码。
让 Claude 跑测试并修复问题。

5.2 创建项目结构

mkdir csv-stats && cd csv-stats

然后启动 Claude Code：

claude

在交互界面中输入：

请帮我创建一个名为 csv_stats.py 的脚本，功能是读取指定 CSV 文件，按 category 字段分组，统计每个分组的数量总和，并输出到控制台。

5.3 让 AI 读代码、找问题、改代码

Claude 会生成类似下面的脚本：

import csv import sys from collections import Counter def read_csv(filepath): rows = [] with open(filepath, mode='r', encoding='utf-8') as f: reader = csv.DictReader(f) for row in reader: rows.append(row) return rows def group_count(rows, field='category'): counter = Counter() for row in rows: counter[row.get(field, '未知')] += 1 return counter def main(): if len(sys.argv) < 2: print("用法: python csv_stats.py <csv文件路径>") sys.exit(1) filepath = sys.argv[1] rows = read_csv(filepath) counter = group_count(rows) for key, value in counter.most_common(): print(f"{key}: {value}") if __name__ == '__main__': main()

生成代码后，你可以继续要求：

请给这个脚本添加参数 --limit，用于只显示数量最多的前 N 个分类。

Claude 会直接在原文件上修改，并且会告诉你改动位置。

5.4 运行与验证结果

生成之后，让 Claude 帮你运行验证：

请创建一个示例 data.csv，然后用这个脚本运行一次，确认输出正确。

Claude 可能会创建示例数据，并执行命令：

python csv_stats.py data.csv

如果脚本有 bug，比如字段名不匹配、编码问题，它会自动修复。

这个例子说明了一个关键点：Claude Code 的价值不在“生成一段代码”，而在“生成后能继续对话、运行、排查、修复”的完整闭环。

6. 连接 DeepSeek 与本地模型部署

6.1 为什么要把 Claude Code 接 DeepSeek / 本地模型

Claude Code 默认使用 Anthropic 的模型，但很多人因为成本、访问便利性或数据合规要求，希望换用其他模型。这时“Claude Code 接入 DeepSeek”就派上了用场。

DeepSeek 提供了 Anthropic 兼容 API，因此 Claude Code 只需改几个环境变量就能接入。

本地模型部署则更彻底：你可以用 Ollama、vLLM 等工具把模型跑在自己机器上，再让 Claude Code 连到本地服务。好处是数据不出本地、按需使用、不依赖外部 API。

6.2 Claude Code 接入 DeepSeek API

先到 DeepSeek 开放平台申请 API Key，然后设置环境变量：

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

也可以把变量写入当前用户的 shell 配置文件（如.bashrc或.zshrc），避免每次设置：

echo 'export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"' >> ~/.bashrc echo 'export ANTHROPIC_AUTH_TOKEN="你的DeepSeek API Key"' >> ~/.bashrc echo 'export ANTHROPIC_MODEL="deepseek-chat"' >> ~/.bashrc source ~/.bashrc

设置完成后，直接执行：

claude

此时 Claude Code 的请求会转发到 DeepSeek 的 Anthropic 兼容端点。

如果你需要使用 DeepSeek 的推理模型，可以尝试将ANTHROPIC_MODEL设置为对应模型名称，例如：

export ANTHROPIC_MODEL="deepseek-reasoner"

不同版本的 Claude Code 和模型列表适配情况不同，建议以 DeepSeek 官方文档的最新模型 ID 为准。

如果你收到“xxx is not a model this version of claude code recognizes”的报错，通常是模型名称不匹配或当前版本不识别该模型，需要对照文档检查模型名，并考虑升级 Claude Code 版本。

6.3 本地模型部署整体思路

把 Claude Code 接到本地模型，核心流程是：

部署一个本地模型服务。
让本地服务暴露一个 Claude Code 能访问的 API 地址。
设置ANTHROPIC_BASE_URL指向本地服务。
设置认证信息，本地服务通常用一个自定 Token 即可。

但有一个关键兼容性问题：Claude Code 使用的是 Anthropic Messages API 格式，而很多本地模型服务默认只提供 OpenAI 格式接口。

解决办法有两种：

选择自带 Anthropic 兼容层的推理服务或网关。
在本地模型服务和 Claude Code 之间加一层兼容代理，把 Anthropic 请求转换成目标模型能识别的格式。

市面上有开源社区维护的网关项目，可以搜索“Claude Code 本地模型网关”“Anthropic API 转换代理”了解，部署时注意选择活跃维护的项目。

6.4 Ollama 本地模型示例

Ollama 是最流行的本地模型运行工具之一。安装并拉取模型：

curl -fsSL https://ollama.com/install.sh | sh ollama pull deepseek-r1:7b ollama serve

验证本地接口是否可用：

curl http://localhost:11434/api/tags

如果返回模型列表，说明 Ollama 服务已启动。

但严格来说，Ollama 原生 API 和 Claude Code 的格式并不完全一致，直接设置ANTHROPIC_BASE_URL="http://localhost:11434"可能无法完全正常工作。你需要确认当前使用的 Ollama 版本是否提供 Anthropic 兼容端点，或者引入一层转换代理。

如果你使用了兼容层，配置看起来像这样：

export ANTHROPIC_BASE_URL="http://127.0.0.1:8080" export ANTHROPIC_AUTH_TOKEN="local-token" export ANTHROPIC_MODEL="deepseek-r1:7b"

这里的127.0.0.1:8080是本地转换代理的地址。

6.5 私有化部署注意事项

本地部署或私有化接入模型时，有几个地方要格外注意：

确认模型对工具调用的支持程度，弱模型可能无法稳定使用工具，导致 Claude Code 功能不完整。
本地模型上下文窗口有限，长项目可能需要频繁使用/compact压缩上下文。
注意本地硬件显存和内存，大模型量化版本能降低硬件门槛。
涉及企业内部数据时，不要随意安装来历不明的代理插件，优先选择开源可审计方案。

7. 在 VS Code 中使用 Claude Code

7.1 在 VS Code 集成终端启动

Claude Code 本身是命令行工具，但它和 VS Code 配合得非常顺畅。

最简单的方法是：打开 VS Code 的项目文件夹，用快捷键Ctrl + `打开集成终端，然后执行：

claude

这样 Claude 可以直接看到 VS Code 工作区里的文件，你在编辑器里改代码，旁边终端里 AI 在实时协作，体验非常自然。

7.2 配置快捷键与内联集成

很多开发者会搜索“vscode 配置 claude code”。不同版本的 VS Code 扩展提供了不同能力，有些版本可以在编辑器侧边栏打开 Claude Code 面板，查看文件改动差异，甚至直接接受或拒绝 AI 的修改。

如果你使用的版本支持扩展管理，可以在 VS Code 扩展市场搜索 Claude Code 相关扩展。安装后按扩展文档配置即可。

也可以把常用操作绑定到快捷键。在 VS Code 的 keybindings.json 中添加：

{ "key": "ctrl+alt+c", "command": "workbench.action.terminal.sendSequence", "args": { "text": "claude\n" } }

这样每次按快捷键就能快速启动 Claude Code。

7.3 提高协作效率的小技巧

把.claude/目录加入.gitignore，避免本地权限配置误提交。
使用/status查看当前使用的模型和上下文状态。
多文件修改后，用git diff检查 AI 的改动。
让 Claude 直接调用git log、git diff，它能更快理解项目当前状态。

8. 常见问题与排查思路

8.1 高频报错与解决方法

问题现象	可能原因	排查与解决思路
`command not found: claude`	npm 全局目录没有加入 PATH	检查 npm 全局路径，重新配置 PATH 后重试
执行`claude`后一直卡在登录页	登录凭据未正确配置	检查 API Key 或 Token；可尝试重新登录
`ECONNRESET`或连接超时	网络无法访问 API，或 Base URL 配置错误	检查`ANTHROPIC_BASE_URL`是否正确，测试接口连通性
`xxx is not a model this version of claude code recognizes`	模型名不存在，或版本不匹配	核对模型 ID；升级 Claude Code；查看 API 服务支持的模型列表
提示无权限执行 Bash 命令	权限策略拦截	使用`/permissions`授权，或在 settings.json 中配置 allow 列表
上下文过长，响应变慢	会话积累信息过多	使用`/compact`压缩上下文，或`/clear`开启新会话
中文回复变成乱码	终端编码问题	Windows 终端执行`chcp 65001`切换到 UTF-8；macOS/Linux 检查终端字符集

8.2 排查 checklist

遇到问题先按下面的顺序排查：

确认版本：claude --version，看是否过旧。
确认环境变量：打印相关配置，注意不要泄露密钥。
确认网络连通性：用 curl 测试 API 地址是否可访问。
确认模型名称：查询服务商文档中的最新模型 ID。
确认权限配置：看 settings.json 是否误 ban 了某些操作。
确认项目上下文：如果项目过大，手动补充 CLAUDE.md 或使用/clear重置。

9. 最佳实践与工程建议

9.1 从小任务开始，先让 AI 理解项目

不要一上来就让 Claude 执行“重构整个项目”这种大任务。先让它读 README、看目录结构、问几个小问题，确认它理解项目上下文后再逐步推进。

推荐流程：

创建 CLAUDE.md。
让 Claude 概括项目结构和核心流程。
从单个模块或单个接口开始改造。
测试通过后再扩大范围。

9.2 让 CLAUDE.md 成为团队知识库

在团队项目里，CLAUDE.md 的价值会被放大。把技术选型、部署方式、代码规范、常用命令都写进去，相当于给每个开发者配了一个“了解项目背景”的 AI 助手。

建议团队维护一份模板，内容包括：

项目简介和架构图。
本地开发环境要求。
启动和测试命令。
分支管理和提交流程。
路径规划：比如约定业务代码放哪个目录。

9.3 安全与密钥管理

密钥泄露是使用 AI 编程工具时最容易被忽视的问题。请严格遵守以下几点：

不要把 API Key 写入代码或配置文件中并提交 git。
使用.env文件并在.gitignore中排除它。
权限配置尽量最小化，生产环境禁止执行高风险命令。
定期轮换 API Key，尤其当怀疑泄露时。

9.4 成本控制与模型选择

不同模型的计费差异很大。如果使用第三方兼容 API，要关注 token 消耗。建议：

把重复性、简单任务使用轻量模型处理。
复杂架构分析和重构任务使用更强模型。
使用/compact减少长会话 token 消耗。
检查 API 服务商是否有按量统计，定期查看用量。

9.5 保留 Git 与代码评审防线

AI 能写代码，不代表它写的代码一定正确。建议始终保留 Git 版本管理和人工评审环节。

每次 AI 大改后先用git diff检查改动。
用git checkout回滚问题改动。
关键代码必须人工 review，尤其是涉及权限、支付、数据安全的业务。
不要因为 AI 生成了代码就跳过单测和静态检查。

10. 总结

Claude Code 不是一个普通的“代码生成器”，而是一个跑在终端里的 AI 编程代理。它的价值不仅在于帮你写代码，更在于它能理解项目、执行命令、修改文件、运行验证，形成一个完整的开发闭环。

这篇文章从安装讲到了配置，从官方模型讲到了 DeepSeek 和本地模型部署，也把 VS Code 集成、权限控制、常见报错和最佳实践都梳理了一遍。如果你能跟着把环境装好、跑通一个真实项目，并把 CLAUDE.md 建立起来，基本上就脱离了“只会复制粘贴命令”的阶段。

下一步建议你动手做三件事：

找一个小的开源项目，用 Claude Code 分析它的代码结构。
在项目里创建 CLAUDE.md，让 AI 参与一次真实功能开发。
对比一下官方模型、DeepSeek API、本地模型三种模式的体验差异。

AI 编程工具跑得快，但方向仍然由你来控制。理解工具的原理和边界，比记住一堆命令更重要。希望这篇教程能帮你少踩一些坑，把 Claude Code 真正变成日常开发里顺手的工具。

企业官网建设流程全解析