Claude Code国内使用教程：配置DeepSeek接口从安装到实战

Claude Code 这玩意我从拿到邀请就开始折腾中间踩过的坑比写过的代码还多。最近换了一台新电脑正好把从零到跑通的完整过程重新走了一遍顺手把关键步骤和坑位都记录下来。这篇东西不是官方文档的翻译是一个真实用户连续几天实测下来的汇总希望能让你少走弯路。先说结论Claude Code 是 Anthropic 官方出品的命令行编程工具闭源默认深度绑定 Claude 系列模型但它支持通过环境变量切换到兼容的第三方模型接口。对于国内开发者来说官方 API 的网络连接并不顺畅默认的 OAuth 登录流程也经常卡在账号验证界面。所以这篇教程的核心思路是安装官方 CLI 工具通过配置 ANTHROPIC_BASE_URL 接入 DeepSeek 等国内可用的大模型接口从而在国内网络环境下把 Claude Code 真正用起来。整个过程我实测跑通下面每一步都能直接照着做。1. Claude Code 是什么官方 CLI 工具的核心价值1.1 它到底解决什么问题Claude Code 是 Anthropic 在 2025 年上半年推出的命令行编程助手本质上是一个跑在终端里的 AI 编程代理。和你在网页对话框里问 Claude 问题完全不一样它可以直接读取你项目目录里的文件、执行终端命令、修改代码、运行测试甚至提交 Git。你可以把它理解成一位坐在你旁边的结对编程工程师你说需求它动手改代码改完自己跑测试验证。我自己的体会是Claude Code 特别适合这几类场景一是重构老项目你只需要告诉它“把这块逻辑抽成独立的模块”它会自己读文件、梳理依赖关系、改代码二是写测试用例它扫描完源码之后能快速生成覆盖率还不错的单测三是排查报错把报错信息甩给它它会结合上下文定位到具体代码行并给出修复方案。对于我这种日常要写大量胶水代码和脚本的人来说这东西的提效作用非常明显。1.2 和 Cursor、Copilot 这类工具有什么不一样可能有人会问我已经在用 Cursor 或者 GitHub Copilot 了还有必要折腾 Claude Code 吗区别其实蛮大的。Copilot 是“补全式”的你在编辑器里写代码它帮你续写下一段Cursor 是“对话式”的你选中代码问它问题它给出修改建议你再去应用。而 Claude Code 是“代理式”的它拥有执行权限能自己调命令、跑脚本、改文件然后告诉你它做了什么等你确认。这就带来了一个很实际的变化你可以把 Claude Code 挂在后台让它处理一个比较独立的子任务同时自己继续写别的代码。它不再是一个只能提建议的参谋而是一个真的能动手干活的同事。我用了一段时间之后已经习惯了给它派活“帮我把这几个接口的错误处理统一一下”“把这边的死代码清理掉”然后继续做手头的事情过一会儿去看它的执行日志和 diff。当然这也是最需要注意的地方它能跑命令也就意味着它有破坏性操作的能力。所以 Claude Code 在每次执行修改类操作之前都会先展示计划并且按键盘要求你确认。理解它的工作方式你才会知道在什么节点该认真审查在什么节点可以放心交给它。2. 国内使用的两条路线选对方案再动手2.1 路线对比官方通道与第三方接入安装 Claude Code 本身其实不难真正麻烦的是“怎么用起来”。目前国内用户能走的大致只有两条路线一条是走 Anthropic 官方 API。你需要有官方的 Claude API Key同时保证网络环境能正常访问 Anthropic 的服务。对大多数国内用户来讲这条路有几个绕不开的门槛海外账号的注册和支付、API 请求的网络延迟和稳定性。而且 Claude Code 默认的登录流程是走 OAuth 网页授权我身边很多朋友都卡在“浏览器打开登录页之后一直转圈”这一步。另一条是走第三方兼容接口。Claude Code 在启动时会读取环境变量其中 ANTHROPIC_BASE_URL 这个变量决定了它把请求发到哪个 API 地址。既然它是按 Anthropic API 的协议来发请求的那么任何实现了兼容接口的服务商都可以接进来。DeepSeek 官方就已经提供了 Anthropic API 兼容接口所以理论上可以把 Claude Code 的前端体验和 DeepSeek 的模型能力结合起来用。我不在这里评价哪条路更好因为每个人的条件和需求不一样。但如果你在国内、没有海外支付手段、又希望开箱即用那么 DeepSeek 接入这条路是实测下来最顺、性价比最高的方案。2.2 我为什么选择 DeepSeek 接入选 DeepSeek 有几个现实原因第一它国内直连可用注册简单支付宝就能充值没有支付门槛第二它的 API 定价相对亲民我日常拿 Claude Code 来写脚本、补测试、改 bug一个月的消耗量放到 DeepSeek 上也就几十块钱而官方 Claude API 的账单分分钟让你肉疼第三DeepSeek 的模型质量在代码场景下足够能打尤其是它的新版本模型写代码、理解代码的能力都很强。当然也要说清楚它的局限。接入 DeepSeek 之后你在 Claude Code 里使用的生态插件、Skill 技能包、MCP 工具服务这些功能依然可以正常工作因为这些大多走的是客户端本地逻辑。但是 Claude Code 内置的一些依赖模型特定能力的功能比如部分系统提示词里强依赖 Claude 模型行为的场景实际表现会受模型能力上限影响。我的使用感受是日常开发 80% 的任务它都能处理得不错剩余 20% 需要模型特别强的推理能力时能明显感觉到 DeepSeek 和顶级模型之间的差距。2.3 环境准备Node.js 与系统要求Claude Code 是一个 Node.js 应用所以第一步是确保你的电脑上装了 Node.js。我建议安装 Node.js 18 以上的版本最好是 20 LTS实测下来这个最稳。在终端里输入 node -v如果有版本号输出说明已经装好了如果提示找不到命令就去 Node.js 官网下载 LTS 版本安装包一路下一步装完重启终端再验证一次。系统方面Windows 10/11、macOS、主流 Linux 发行版都支持。Windows 用户需要注意一点Claude Code 的命令行工具在 PowerShell 和 CMD 里都能运行但如果你想用到它全部能力建议装一个 Windows Terminal并且把默认终端策略设置为允许执行脚本否则后面可能遇到执行权限相关的报错。环境这里多说一句Claude Code 在工作时会调用 Git 来做代码版本操作所以电脑上还需要装好 Git并且配置好你的用户名和邮箱。没有 Git 也能跑起来但很多和版本管理相关的功能会失效体验大打折扣。3. 从零安装 Claude Code完整实操记录3.1 安装步骤与版本验证安装过程非常简单核心就一条命令。打开终端Windows 用户打开 PowerShell 或 Windows TerminalmacOS 用户打开 Terminal输入npm install -g anthropic-ai/claude-code这里我用的是全局安装这样在任何目录下都能直接调用 claude 命令。安装过程会从 npm 仓库拉取最新版本根据网络情况一般一两分钟就能完成。装完之后输入claude --version能看到版本号比如 1.0.x 或者更高就说明装成功了。我这次装的时候拿到的是 1.0.87 版本如果你看到类似的版本号说明安装位和当前最新版保持同步。这里有一个小细节要注意如果你以前装过旧版本升级时直接用上面这条命令npm 会覆盖安装到最新版。但如果遇到权限报错常见于 macOS 和 Linux 系统需要在命令前面加 sudo。Windows 下如果提示权限不足则要以管理员身份开 PowerShell 再执行。装完之后建议执行一下 npm list -g anthropic-ai/claude-code 确认安装路径方便后面出问题时排查。3.2 安装中的常见报错处理说实话安装这一步大多数人都很顺利但我也看到不少人在社区里反馈报错这里集中列一下我遇到过和我帮别人排查过的几个高频问题。第一类是 npm 网络超时。npm 默认源在国外国内网络环境经常抽风。解决办法是把 npm 源切换到国内镜像执行npm config set registry https://registry.npmmirror.com然后再装一次就正常了。这个操作只是改了 npm 的下载源不影响任何项目逻辑可以放心做。第二类是安装完成后 claude 命令找不到。这种情况多半是 npm 全局包的安装目录不在系统 PATH 环境变量里。Windows 上可以先找到 npm 全局目录npm prefix -g然后把那个目录加到系统环境变量的 Path 里重开终端即可。macOS 上用 nvm 管理 Node 的话需要检查 nvm 所在 shell 配置文件是否被正确 set比如 ~/.zshrc 里有没有加 nvm 的初始化语句。第三类是 Windows 上 PowerShell 执行策略拦截。Claude Code 安装后第一次启动会加载它自己的初始化脚本如果系统默认禁止执行脚本就会弹一个红字报错。解决方法是以管理员身份运行 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这个操作在当前用户范围内允许运行本地脚本是官方支持的安全配置不会影响系统安全。4. 核心环节配置 DeepSeek 接入并完成认证4.1 获取 DeepSeek API Key这才是这篇教程的重点。要让 Claude Code 真正把请求发到 DeepSeek你首先得有一个 DeepSeek 开放平台的账号以及对应的 API Key。打开 DeepSeek 开放平台的官网注册账号、登录之后在控制台左侧找到“API Keys”菜单点进去创建一个新的 Key。创建的时候可以给 Key 起个名字方便识别比如 claude-code-dev。创建完成之后系统会一次性显示完整的 Key 字符串一定记得复制保存好。这个 Key 只在创建成功那一刻完整展示一次关掉页面就再也看不到了如果丢了你只能删除重建。拿到 Key 之后还需要确认一下账户里有钱。DeepSeek 是预付费模式先充值才能调用 API。充值入口在控制台的“费用”或“钱包”菜单里支持支付宝。我第一次用的时候充了 50 块钱写写脚本、改改 bug用了将近两周才见底开销确实低。4.2 环境变量配置详解Claude Code 在启动时读取以下几个关键环境变量ANTHROPIC_API_KEY 是 API 密钥ANTHROPIC_BASE_URL 是 API 服务地址ANTHROPIC_MODEL 是默认使用的模型名称。把这三个变量都指向 DeepSeek 的信息Claude Code 就会把请求转到 DeepSeek。在 Windows 的 PowerShell 里可以执行$env:ANTHROPIC_API_KEY 你的DeepSeek API Key $env:ANTHROPIC_BASE_URL https://api.deepseek.com/anthropic $env:ANTHROPIC_MODEL deepseek-chat在 macOS 或 Linux 的终端里执行export ANTHROPIC_API_KEY你的DeepSeek API Key export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_MODELdeepseek-chat这里有一个关键点DeepSeek 的 Anthropic 兼容接口的路径是 /anthropic不是根路径。如果你只填了 https://api.deepseek.comClaude Code 会把请求发到接口对应的位置结果就是 404 或者 401。这个坑我亲眼见好几个人踩过实在不放心的话可以在浏览器里直接访问 ANTHROPIC_BASE_URL 拼上接口文档路径验证一下通不通。还要说明一下 ANTHROPIC_MODEL 的参数选择。DeepSeek 目前的通用对话模型一般对应 deepseek-chat新版推理模型对应 deepseek-reasoner。实测下来日常代码任务用 deepseek-chat 响应速度更快深度推理任务换 deepseek-reasoner 效果更好。你在配置里写下其中一个作为默认值后续在 Claude Code 对话中也可以通过 /model 命令临时切换。4.3 首次启动与验证环境变量配置好之后在任意项目目录下执行claude第一次启动会提示你阅读并同意 Anthropic 的使用条款以及确认这个目录下的操作权限。按提示操作完成后就进入了交互界面可以看到输入框直接输入一句“介绍一下当前目录的结构”之类的测试指令。如果环境变量配置正确Claude Code 会直接把请求发到 DeepSeek然后返回一段关于目录结构的分析。我看到很多人在这里直接卡住要么提示 Not logged in要么一直转圈没反应要么报 401 错误。出现这些情况不要急着去改配置文件先检查一下你的环境变量到底有没有生效。在终端里执行echo $env:ANTHROPIC_BASE_URL # Windows PowerShell echo $ANTHROPIC_BASE_URL # macOS / Linux如果输出为空说明环境变量没有正确设置或者终端会话没刷新重新设置再启动 Claude Code 就好。另外再提一句 Claude Code 的官方登录流程如果你不需要接入 DeepSeek坚持用官方 Claude 账号的话启动时会走 /login 的 OAuth 网页登录浏览器里会打开一个登录页面要求你登录 Claude 账号并授权。这个方式的详细操作就不展开了因为国内网络环境下这个页面能不能正常加载、加载后能不能完成授权都取决于你的具体网络条件。我的建议是直接用环境变量这套方案省掉账号页面的麻烦。5. 在 VSCode 里无缝使用 Claude Code5.1 安装 VSCode 扩展命令行里跑通了很多人还会想在 VSCode 里用。毕竟日常开发的主力还是编辑器能在编辑器里直接和 Claude Code 对话效率会高很多。Anthropic 官方提供了一个叫 Claude Code for VSCode 的扩展在 VSCode 的扩展商店里搜索 Claude Code 就能找到认准发布者是 Anthropic 官方的那个别装到山寨的。装好扩展之后VSCode 左侧边栏会出现一个 Claude Code 的图标。点开它扩展会尝试寻找系统中已经安装的 claude 命令行工具。因为我们在上一步已经全局安装过了只要 PATH 环境变量正常扩展会自动识别。这时候有个重要的点VSCode 扩展是继承 VSCode 进程环境的如果你在外部终端里设置了临时环境变量VSCode 里不一定能读到。换句话说你在 PowerShell 里 export 的那些配置直接打开 VSCode 之后扩展可能不认识。解决办法有两种一种是在 VSCode 的设置里把环境变量配到系统的用户环境变量中这样任何进程都能读到另一种是直接在 VSCode 的终端里启动 claude 命令手动验证。5.2 扩展与命令行工具的配合VSCode 扩展的好处是可以直接读取当前打开的文件内容然后基于这些内容生成 diff 建议。你选中一段代码右键选择“Ask Claude Code”扩展的对话面板会自动带上这段代码的上下文。Claude Code 给出的修改方案会以 diff 形式展示你可以逐行确认点击“Accept”应用修改或者“Reject”丢弃。还有一个很舒服的功能在对话面板里可以引用当前工作区里多个文件。比如你选中 A 文件里的函数再引用 B 文件里的调用处直接问 Claude Code “这个函数改完签名之后B 文件哪里需要同步调整”它会跨文件分析并给出修改建议。这个体验比单纯在网页对话框里手贴代码要自然得多。命令行工具和 VSCode 扩展不是二选一的关系。我实际的用法是写代码时开着扩展的对话面板处理局部问题遇到需要跑测试、查日志、批量重构的场景切到终端用命令行完整处理。两者共享同一套配置环境和模型接入切换过程是无感的。5.3 版本兼容问题的处理VSCode 扩展和命令行工具的版本兼容问题我专门拿出来说因为太容易踩了。有人说扩展装好后提示“版本不兼容”或者在点开面板时报错检查之后发现是 claude 命令行工具的版本比扩展要求的版本低。Anthropic 的迭代速度很快几乎每周都有新版本扩展和 CLI 版本相差太大的话确实会出现兼容问题。遇到这种情况最简单的办法是把两边的版本都升级到最新。命令行升级执行之前那条 npm install -g anthropic-ai/claude-code会自动覆盖到最新版。扩展直接在 VSCode 的扩展页面点更新。更新完重启 VSCode再重新加载 Claude Code 面板问题一般就解决了。如果更新完还是报版本不兼容可以考虑换一个思路在 VSCode 设置里找到 Claude Code 相关的扩展配置项确认 claude 可执行文件的路径是否正确指向了全局安装的位置。在 Windows 上特别容易出现路径指向了 npm 缓存目录里的某个临时文件这种情况手动改成 node_modules 下的 claude 命令行入口就行。6. 日常开发中的高频命令与真实工作流6.1 最常用的命令清单Claude Code 的交互界面里除了直接输入自然语言描述需求之外还内置了一批斜杠命令。我把这段时间最常用的整理成一个速查表你拿到就能用命令作用我的使用频率/help查看帮助文档和可用命令列表低/clear清空当前对话历史中/compact压缩对话上下文保留关键信息重新整理高/model查看或切换当前使用的模型中/status查看当前会话的上下文占用和资源情况中/cost查看本次会话累计的 token 消耗和费用估算高/login登录 Claude 账号低/logout退出当前登录状态低/permissions查看和修改工具执行权限策略中/vim切换编辑器键位模式适合 Vim 用户低需要注意/model 命令在接入 DeepSeek 后照样能用因为本质上只是切换模型名称。你可以在 deepseek-chat 和 deepseek-reasoner 之间来回切换来应对不同类型的任务。6.2 一次完整的代码任务实操拿一个真实的小任务演示一下整个工作流。假设我在一个 Python 项目里需要给现有的用户注册接口补充输入校验和单元测试。启动 claude 进入项目根目录后我输入帮我看一下当前项目的注册接口逻辑主要在 auth/routes.py 这个文件里。然后我需要对手机号和邮箱字段增加格式校验并补充对应的单元测试。Claude Code 会先定位文件读取代码同时扫描项目依赖和测试框架。接着它会给出修改计划比如在 auth/routes.py 里增加一个 validate_input 函数、修改注册路由调用它、创建 tests/test_auth_validation.py 并编写测试、在终端运行 pytest 验证。每一步它都会展示将要执行的操作我按 ShiftTab 接受提议或者按 Esc 拒绝某个改动。当所有改动确认完成后它会自己执行 pytest把测试结果反馈给我。如果测试挂了它会自动分析失败原因尝试修复再跑一遍。这个过程里我观察到一个很有价值的行为Claude Code 会把问题拆成一步步可验证的检查点而不是一次性把所有代码改完直接告诉你搞定。这让审计它的工作成果变得容易很多。你可以随时在任务执行中打断它“等一下这个校验逻辑不应该放在这里放到 service 层”它会重新调整方案。6.3 保存对话历史的技巧很多人问 Claude Code 怎么保存对话历史。默认情况下Claude Code 的会话记录会保存在本地路径一般是在用户目录下的 .claude 文件夹里。但如果你在终端直接按 CtrlC 退出会话之前的对话上下文就丢失了下次启动重新开始。我推荐两个做法一个是充分利用 /compact 命令来压缩并保留关键上下文这样会话在超长对话之后还能继续另一个是如果你有某些常用任务和交互流程可以考虑把这些流程写成自定义 Skill 技能包放在 ~/.claude/skills 目录下之后通过指令名直接触发。这个玩法进阶一点但熟悉之后会非常省事相当于给你的 Claude Code 装了一堆可复用的自定义功能。7. 实战中的坑问题排查与经验总结7.1 登录与鉴权相关接下来是我这次实测和过去一段时间收集到的高频问题按类别整理成速查表。先看登录和鉴权相关的问题现象可能原因解决办法启动提示 Not logged in未通过官方 /login 登录使用环境变量方式配置 API Key或执行 /login 完成 OAuth登录页打开后一直转圈官方登录页网络加载异常走环境变量接入 DeepSeek 的方案登录返回 403API Key 无效、过期或权限不足检查 API Key 是否复制完整重新生成 KeyANTHROPIC_API_KEY 已配置但仍提示认证失败环境变量没生效终端里用 echo 检查环境变量值确认指向正确7.2 API 请求和模型调用异常这一块是我收到反馈最多的地方。常见的报错包括“API error: 400 invalid schema for function artifact”、“402 payment required”、“429 rate limit exceeded”。我一个一个说。400 这类报错基本上可以确定是模型兼容问题。它的本质是 Claude Code 向模型发送了带工具调用格式的请求而模型端返回的格式不符合预期。遇到这种情况先切换模型试试比如从 deepseek-chat 切到 deepseek-reasoner或者反过来。如果还不行把上下文压缩一下执行 /clear 清空重新发起任务很多临时性的格式错误就消失了。402 表示账户余额不足。去 DeepSeek 控制台充值就行。这里也提醒一下DeepSeek 的计费是按 token 来的如果你写了一个很长的提示词又让 Claude Code 反复读取大量文件消耗速度会明显加快。建议日常开发时尽量用小步快跑的策略一个任务聚焦一个点别把它当成无限智慧的万能模型不用的时候尽快退出会话。429 是频率限制或者配额用完。DeepSeek 在高峰期的限制比较明显遇到这种报错稍等几秒重试。如果长时间被限流检查一下自己是不是同时开了很多个会话我试过在同一时间开四五个 claude 会话很快就触发了限流。7.3 沙箱与执行权限问题Claude Code 在执行命令时可以用沙箱机制避免某些操作对系统造成过头的影响。但在 Windows 上这个功能时好时坏。有人反馈“沙箱起不来”或者命令执行后没有任何输出。遇到这类问题不要恋战直接把沙箱关掉。启动时用claude --dangerously-skip-permissions这个参数会跳过权限确认让 Claude Code 直接执行命令。要注意的是这个模式下它不再每一步都等你确认所以只建议在信任的项目和环境中使用。别在不认识的开源项目目录里用这个模式万一代码里藏着恶意脚本你会很被动。7.4 Windows 特有问题的补充搜热词的时候看到不少人搜“claude code win10 下载后安装”其实官网并没有提供一个 Windows 上的图形化安装包Claude Code 的安装方式就是 npm 装全局命令行工具。即使官方后来推出了桌面版客户端命令行工具依然是核心。所以 Windows 用户不用到处找安装包回到终端执行 npm install -g anthropic-ai/claude-code 就对了。还有人说“我的 claude code desktop 总是显示 pdf 有密码”。这个我单独说一下Claude Code 在处理带密码的 PDF 时经常无法读取内容会报密码错误。这不是 bug而是它根本没有能力输入密码来解锁 PDF。解决思路很简单先用其他工具把 PDF 转成文本格式或者去掉密码再让 Claude Code 读取。最后给一个小技巧Windows 下用 Claude Code 时如果终端显示中文乱码在启动 claude 之前执行chcp 65001这个命令把终端代码页切到 UTF-8中文显示就正常了。写在最后的一点个人体会因为保密协议的原因我不能展开说太多工作上的项目细节但从去年开始我在日常工具链里全面切换到了 Claude Code到现在它已经成了我每天的标配之一。要问我的真实评价我会说它不是一个“偶尔拿来玩一玩”的新鲜玩意而是那种一旦习惯了就回不去的生产力工具。最明显的改变是以前写单元测试这种事总是能拖就拖现在随手一句指令就能生成大部分测试框架让我更有意愿把测试补齐。重构老代码也不再是一件头疼的事因为有个不知疲倦的搭档愿意先梳理逻辑再动手。当然如果你也决定走 DeepSeek 接入这条路一定要做好心理预期它不是 Claude 官方模型的完全替代品偶尔会在复杂推理上给你一点小失望。但考虑到国内网络环境和成本这已经是目前最务实的选择。最后再留一个建议不要在项目根目录之外的地方随意使用跳过权限的模式也不要在一个会话里塞太多跨项目的工作保持任务聚焦它的表现会稳定地好很多。