Claude Code 速查手册：安装、命令、接入DeepSeek与排雷全指南

说句可能要被不少人反驳的话：Claude Code 能火，不是因为它是个“更好用的终端工具”，而是因为它把“在终端里和AI协作”这件事的交互方式彻底重做了一遍。但我也见过太多人装完两天就吃灰——倒不是工具不行，而是这货的命令体系、配置路径、权限模型跟传统 CLI 完全不是一个套路，不靠一张靠谱的速查表硬啃，上手体验就是灾难。

这篇就是干这个的。把 Claude Code 从安装、命令、模型接入、Skill、报错排雷到桌面版/CLI/VSCode 插件的选择，一次性摊开写成速查表。如果你是刚接触 Claude Code，照着走一遍就能跑起来；如果你已经装了但经常被各种报错卡住，直接跳到第五章对号入座。

1. 装错地方全白搭：三种安装方式怎么选

1.1 npm、原生脚本、桌面版到底有什么区别

Claude Code 的安装方式目前主流的就三条路：npm 全局安装、官方原生安装脚本、桌面版应用。很多人第一步就栽在“到底该用哪个”上，其实判断标准很简单。

如果你机器上已经有 Node.js 环境，直接用 npm 装是最省事的：

bash复制npm install -g @anthropic-ai/claude-code

装完验证一下版本：

bash复制claude --version

能正常输出版本号就说明装好了。这是我最推荐的方式，因为后续升级只需要一条 npm update -g @anthropic-ai/claude-code，不用记第二套命令。

如果你不想碰 npm，或者机器上没有 Node.js，可以用官方原生安装脚本：

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

这个脚本会检测系统架构，自动把二进制装到合适的位置。Linux 和 macOS 都适用，Windows 下建议走 npm 或者用 WSL，原生脚本在 Windows PowerShell 里的表现比较折腾。

桌面版是另一条线，它本质上是一个带图形界面的壳，底层还是调同一套 CLI 核心。桌面版的优势是文件树、预览、会话管理更直观，适合不习惯纯黑窗口的人；但如果你是自动化脚本的重度用户，桌面版反而多余，后面第六章我会详细对比。

1.2 Node.js 版本这个隐藏门槛

很多“装了半天用不了”的案例，问题根本不在 Claude Code 本身，而在 Node.js 版本。Claude Code 对 Node.js 的要求是 18 以上，建议直接上 20 LTS。

检查版本：

bash复制node -v

如果版本过低，在 Ubuntu 上我建议用 nvm 装，而不是直接 apt 装 Node：

bash复制curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20

用 nvm 的好处是版本切换灵活，不会因为系统包管理器的 Node 版本太老导致 Claude Code 各种莫名其妙的问题。我之前在一台 Ubuntu 服务器上就是被系统自带 Node 12 给坑了，装完 claude 一运行就报语法错误，查了半天才反应过来是 Node 版本问题。

1.3 升级和版本锁定策略

Claude Code 更新频率非常快，有时候一周能发好几个版本。我见过两种极端：一种是一直不升级，结果新功能用不了，模型报错也不认识；另一种是天天追新，结果某个版本引入新 bug 反而更难受。

我的做法是：日常使用遇到“模型不识别”或者“命令行为变化”这类问题，先升级再排查。升级命令：

bash复制npm update -g @anthropic-ai/claude-code

如果想锁定某个版本，可以这样装：

bash复制npm install -g @anthropic-ai/claude-code@2.1.245

比如热搜里提到的 claude code for vs code v2.1.245，这种带版本号的安装方式在团队统一环境时特别有用——大家版本一致，问题复现和沟通都方便很多。

2. 一页纸看懂核心命令：会话启动、继续、非交互模式

2.1 四种启动方式对应四种场景

Claude Code 最基础但也最容易搞混的就是启动命令。先记住一个结论：不同启动方式对应不同使用场景，不是随便选的。

直接进入交互模式：

bash复制claude

这是最常用的方式，进入后是一个 REPL 式的对话界面，你可以连续提问、让它改代码、跑命令，所有上下文都在会话里。

带提示词一次性启动：

bash复制claude "帮我看看当前目录下的 main.py 有什么问题"

这种适合你已经明确知道要干什么，不想再输入一遍交互式命令的情况。它会直接进入交互模式，并且把这句话当作第一轮提问。

继续上一次会话：

bash复制claude -c

这个命令太重要了。Claude Code 的会话上下文会保留在本地，你关掉终端再打开，用 -c 就能接着上一轮的对话继续聊。比如你让它改了个函数，中途去喝了杯咖啡，回来继续让它接着改另一个文件，直接 claude -c，不用重新描述一遍背景。

非交互模式，适合脚本调用：

bash复制claude -p "总结一下 README.md 的内容"

-p 是 print 模式，它不会进入交互式界面，而是直接把 AI 的回答打印到标准输出然后退出。这是写自动化脚本、接入 CI/CD 管道的核心参数。比如我写过一个脚本，批量对目录下所有 Python 文件做静态审查，就是靠 claude -p 逐文件调用再收集输出。

2.2 会话内斜杠命令速查

进入交互模式后，所有管理类操作都通过斜杠命令完成。下面这张表是日常最高频的几个：

一个容易忽略的细节：/clear 和 /compact 有本质区别。/clear 是彻底清空，AI 会忘掉所有上下文；/compact 是把历史对话压缩成摘要保留关键信息。长时间会话变慢或者 AI 开始“答非所问”，先用 /compact，如果还不行再 /clear。别一上来就清空，相当于自己把上下文扔了。

2.3 权限模式：别被弹窗烦死，也别随便放开

Claude Code 为了安全，默认情况下执行写文件、运行命令这类操作前会弹确认框。新手会觉得烦，老手会直接设置权限。

在会话里输入 /permissions 可以查看当前权限模式，有几种常见配置：

json复制{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(npm run lint)",
      "Read(~/myproject/**)"
    ]
  }
}

defaultMode 设置为 acceptEdits 表示自动接受文件编辑，但执行命令还是需要确认；你也可以添加具体的 allow 规则让特定命令免确认。

我的建议是：本地开发可以把 Read 和 Edit 放宽松，但 Bash 权限务必保留确认机制，尤其是 rm、sudo、git push 这类高危操作。等用到危险命令的时候，你会感谢这个权限设计的。

3. 让 Claude Code 用上任意模型：settings.json 与 DeepSeek 接入

3.1 官方登录 vs 第三方 API，先理清楚

Claude Code 最原生的用法是登录官方账号。在交互模式里输入 /login，浏览器会弹出授权窗口，登录后就能直接用订阅账号调用 Claude 模型。

但很多人没有官方订阅，或者想对比不同模型的效果，这时候就需要把 Claude Code 指向第三方 API。Claude Code 支持通过环境变量覆盖 API 地址和模型名称，这个机制让它变成了一个“通用 AI 终端”，你可以把 DeepSeek、通义等兼容 Anthropic API 格式的服务接进来用。

网上搜得最凶的 claude code 接入 deepseek、claude code + ccswitch + deepseek 都是在做这件事。

3.2 环境变量接入 DeepSeek 的完整配置

最基础的方式是通过环境变量指定 API 地址和密钥：

bash复制export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=你的DeepSeek密钥
export ANTHROPIC_MODEL=deepseek-chat

然后启动：

bash复制claude

这样所有请求就会发到 DeepSeek 的 Anthropic 兼容接口上。ANTHROPIC_BASE_URL 是接口地址，ANTHROPIC_AUTH_TOKEN 是密钥，ANTHROPIC_MODEL 是你要用的模型名。

但请注意：环境变量的方式是临时的，新开一个终端就失效了。如果每次启动都要手动 export 一遍，效率太低。这时候就需要写进 settings.json。

找到或创建配置文件：

bash复制mkdir -p ~/.claude
nano ~/.claude/settings.json

写入：

json复制{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "你的DeepSeek密钥",
    "ANTHROPIC_MODEL": "deepseek-chat"
  },
  "model": "deepseek-chat"
}

保存后重启 Claude Code，它就自动走 DeepSeek 的接口了。env 字段里的变量会在每次启动时自动注入，相当于替你执行了 export。

这里要特别提醒一个常见误区：很多人只在 env 里配了 ANTHROPIC_MODEL，却忘了加顶层的 model 字段。结果启动后报错“模型不识别”，或者进入会话后它仍然试图用默认的 Claude 模型。两个 model 字段最好都写上，保持一致。

3.3 模型名报错的根因：版本和模型 ID 对不上

搜热词里有一条典型报错：deepseek-v4-pro is not a model this version of claude code recognizes。

这种报错的根因有三类，按出现频率排：

• 模型名写错了。DeepSeek 的官方模型 ID 是 deepseek-chat 和 deepseek-reasoner，不是网上流传的 deepseek-v4-pro、deepseek-v4-flash 这种名字。先到服务商官网文档里查正确的模型 ID，别信二手消息。
• Claude Code 版本太老。老版本自带的模型列表里没有新模型，它无法识别就会直接拒绝。解决办法是先升级：

bash复制npm update -g @anthropic-ai/claude-code

• API 地址指向不对。如果 ANTHROPIC_BASE_URL 指向的不是兼容 Anthropic 格式的接口，服务端返回的模型列表和 Claude Code 预期不一致，也会出现这种提示。

排查顺序我建议是：先核对模型名，再升级 Claude Code，最后检查 API 地址。90% 的情况都出在前两步。

3.4 CC Switch：多配置切换神器

如果只是接一个 DeepSeek，环境变量就够了。但真实使用中，我经常要在“官方 Claude”和“DeepSeek”之间来回切换——日常问答用 DeepSeek，跑复杂代码任务用官方 Claude。手动改环境变量太累，这时候就需要 CC Switch。

CC Switch 是一个专门管理 Claude Code 配置切换的小工具，它把不同的 provider 配置存成独立配置项，一键切换。安装方式看项目的 GitHub 说明，不同系统略有差异。基本使用逻辑是：

bash复制ccswitch add my-deepseek   # 添加一组配置
# 按照交互提示填写 base_url、token、model
ccswitch switch my-deepseek  # 切换到这组配置
ccswitch list               # 查看所有配置

用上这个工具之后，我的日常工作流变成了：默认用 DeepSeek 做快速问答，遇到复杂项目重构切换到官方 Claude。切换过程不超过五秒，不用记任何环境变量，体验提升非常明显。

4. 把 CLI 调教成自己的：Skill、CLAUDE.md 与语言偏好

4.1 全局 CLAUDE.md 和项目级 CLAUDE.md 各管什么

Claude Code 的记忆机制靠 Markdown 文件，有两个层级：

• 全局记忆：~/.claude/CLAUDE.md，对所有项目生效
• 项目记忆：项目根目录/CLAUDE.md，只对当前项目生效

这个文件里写什么，AI 就会在每次进入项目时自动读取并遵循。我自己的做法是在全局 CLAUDE.md 里写通用偏好：

markdown复制# 全局使用规范
- 所有回答默认使用中文
- 代码改动必须解释影响范围
- 生成代码时优先考虑可读性

在项目级 CLAUDE.md 里写项目特有规范：

markdown复制# 本项目说明
- Python 3.11 + FastAPI
- 数据库用 PostgreSQL，ORM 用 SQLAlchemy 2.0
- 新增接口必须写 OpenAPI 注释
- 测试文件放 tests/ 目录

相当于你给 AI 发了一份“员工手册”，它干活前先熟读这份手册，很多约定俗成的规范就不用每次重复叮嘱了。

有两个细节值得注意：第一，CLAUDE.md 不宜写太长，AI 的上下文窗口是有限的，塞一堆废话反而挤占正经任务的空间；第二，/init 命令可以自动扫描项目生成一份 CLAUDE.md，但生成的内容比较模板化，我建议把它当草稿，再手动补充自己的规范。

4.2 Skill：让 Claude Code 学会特定技能

Skill 是 Claude Code 近期最重要的能力之一。你可以在 ~/.claude/skills/ 目录下创建技能包，每个技能是一个目录，里面放一个 SKILL.md 文件作为技能定义。

目录结构：

text复制~/.claude/skills/
└── code-reviewer/
    └── SKILL.md

SKILL.md 的格式类似这样：

markdown复制---
name: code-reviewer
description: 对项目代码进行系统化的代码审查，发现潜在 bug、安全漏洞和风格问题。
---

# 代码审查技能

当你需要对代码进行审查时，按以下步骤执行：
1. 先读取目标文件的完整内容
2. 检查明显的 bug 和逻辑错误
3. 检查安全隐患（SQL 注入、路径穿越等）
4. 检查代码风格是否符合项目规范
5. 输出审查报告，按严重程度分级

name 是技能名，description 是触发条件描述——Claude Code 会读取这个描述来决定什么时候调用该技能。正文则是具体的执行指令。

Skill 的价值在于它把“重复告诉 AI 怎么做”的过程变成了“注册一次，永久可用”。比如我做前端项目时加载一个 Vue 组件审查技能，做 Python 项目时加载另一个后端审查技能，切换项目只需要换技能目录的引用即可，非常灵活。搜热词里的 claude code skills、claude code skill 就是在问这个功能。

4.3 回答语言、声音提示与通知设置

很多刚接触 Claude Code 的人会发现：默认情况下它用英文回答，有点劝退。改语言的办法很简单，在 ~/.claude/CLAUDE.md 里加一行：

markdown复制# 语言偏好
请始终使用简体中文回答用户的问题。

或者在项目级 CLAUDE.md 里加同样内容。这样新会话就会用中文回答，不用每次手动叮嘱。

关于“询问的时候发出声音提示”，这个需求来源于长时间跑任务时盯着屏幕太累。Claude Code 在异步完成任务后可以触发系统通知，配置位置在 settings.json：

json复制{
  "notifications": {
    "enable": true,
    "sound": true
  }
}

设置后，当长时间运行的任务结束时，系统会发出声音提醒。如果你用的是 Linux 桌面或者 macOS，系统通知中心也能收到推送。这个配置对“挂着让它跑任务，自己去做别的事”的场景非常实用。

5. 报错急救清单：对症下药，别动不动就重装

5.1 模型不识别：先查名字、再升级、最后查地址

报错长这样：

text复制Error: "deepseek-v4-pro" is not a model this version of claude code recognizes

排查链路：

bash复制claude --version                 # 第一步：确认版本
npm update -g @anthropic-ai/claude-code   # 第二步：升到最新

升级完再看 settings.json 里的 model 字段和 env.ANTHROPIC_MODEL 是不是服务商提供的标准模型 ID。DeepSeek 目前官方模型名就是 deepseek-chat 和 deepseek-reasoner。如果确认都没问题，再看 ANTHROPIC_BASE_URL 是否填成了 https://api.deepseek.com（这是兼容 OpenAI 格式的接口）而不是 https://api.deepseek.com/anthropic（这是兼容 Anthropic 格式的接口）。这个细节非常容易踩，我第一次接的时候就在这里卡了半小时。

5.2 529 和速率限制：不是你的问题，但也不是只能干等

529 是 Claude 官方服务过载时返回的状态码。看到它别慌，这通常意味着服务器端负载过高，不是你配置的问题。

处理方法：

• 等 30 秒到 1 分钟，claude -c 继续刚才的会话重试
• 高峰期（北美白天）更容易触发，错峰使用能减少概率
• 如果用的是第三方 API，比如 DeepSeek，看看它们的状态页是否也有过载公告，顺带检查一下账户余额和速率限制

常用操作里有一种说法是把超时时间调大。在 settings.json 里可以加：

json复制{
  "env": {
    "CLAUDE_CODE_MAX_RETRIES": 5
  }
}

这个变量控制请求重试次数，适当调大能提高成功率，但注意它不解决根本的过载问题，只是一个缓解手段。

5.3 组织禁用订阅访问：账号权限问题

报错长这样：

text复制Your organization has disabled Claude subscription access for Claude Code

这个报错说明当前登录的账号被组织策略限制，无法使用 Claude 订阅访问 Claude Code。如果你是个人用户，多半是登录了公司统一管理的账号；如果确实需要在本机使用，换成自己的个人账号登录就行：

bash复制claude
# 会话里执行 /logout，然后 /login 重新登录个人账号

如果不想用官方订阅，也可以直接配置第三方 API 方式跳过这个限制。这就回到了第三章的内容，用 DeepSeek 等兼容接口来驱动，完全绕开订阅权限体系。

5.4 卸载要卸干净：不然重装还带病

网上搜“claude code 卸载”“claude code 如何卸载干净”的人不少，因为这个工具删除不彻底的话，重装后依然会读旧配置，各种诡异问题照样复现。

在 Windows 和 Linux/macOS 上卸载逻辑不太一样。npm 方式安装的，先卸载全局包：

bash复制npm uninstall -g @anthropic-ai/claude-code

然后删除配置目录。Linux/macOS 是：

bash复制rm -rf ~/.claude

Windows 上除了 npm 卸载，还要检查用户目录下的 .claude 文件夹，通常在：

text复制C:\Users\你的用户名\.claude

把它整个删掉。另外如果装过桌面版，桌面版的数据目录可能单独存放，需要到系统的应用数据目录里找 Claude 相关文件夹清理。我踩过的坑是：只执行了 npm 卸载，结果 .claude 目录里残留的 settings.json 里还指向一个已经失效的 API key，重装后一启动就报认证错误，排查了半天才发现是残留配置在捣乱。

VSCode 插件同理，卸载插件不会自动清除 ~/.claude 配置，想彻底重置还是一样的步骤：删插件、卸全局包、删配置目录，三步缺一不可。

6. 桌面版、CLI、VSCode 插件到底怎么选

6.1 三端能力对比

现在 Claude Code 能跑的形态主要有三种：纯 CLI、VSCode 插件、桌面桌面应用版。很多人纠结装哪个，我先直接给结论：它们不是替代关系，是协作关系。

CLI 的优势是轻量、可脚本化、SSH 到服务器上也能用。VSCode 插件的优势是和编辑器深度融合，选中代码右键就能让 AI 处理，diff 视图非常直观。桌面版的优势是有完整的图形界面，适合对终端有心理障碍的新手。

6.2 我的日常组合方案

我目前的主力配置是：CLI 做主力 + VSCode 插件做代码审查 + 桌面版偶尔用来看复杂项目结构。

日常工作流是这样的：在终端里用 claude 进入会话，让它实现某个函数或排查 bug；写完代码后在 VSCode 里选中改动区域，让插件做一轮代码 review；涉及整个项目的架构分析时，打开桌面版看文件树和全局上下文。

如果你是在 Windows 上开发，桌面版和 VSCode 插件的体验比纯 CLI 友好得多。Windows 下终端处理 PATH 环境和权限问题比较折腾，但 VSCode 插件装完就能用，桌面版也无需额外配置。网上搜的 windows安装claude code、vscode配置claude code 基本都是在解决这些环境问题。

有一个 Windows 专属技巧：想把 Claude Code 设成快捷方式，可以直接创建一个指向终端命令的快捷方式，目标写：

text复制C:\Windows\System32\cmd.exe /k claude

双击就能打开一个直接进入 Claude Code 的窗口，省去每次手动敲命令的步骤。

6.3 和 Codex 的差异：不是谁替代谁

经常有人把 Claude Code 和 Codex 放在一起比。我的使用感受是：Codex 更强调“用自然语言让 AI 自主完成任务”，背后有完整的任务规划和工具调用机制；Claude Code 则更强调“人在回路”，你随时可以看到它在做什么、每一步都可以干预。

这个差异决定了它们适合不同的用法。Codex 适合“丢一个大目标让它自己跑”，比如“重构整个模块”；Claude Code 适合“逐步引导的结对编程”，比如“先改这个函数，再改那个测试”。我会在按部就班修 bug 时用 Claude Code，在探索性重构时用 Codex，两者配合比只押注一个更高效。

另外有搜热词提到 idea集成claude code。IDEA 用户不用羡慕 VSCode，Claude Code 提供了外部工具集成能力，你可以在 IDEA 的 Terminal 面板里直接跑 claude 命令，享受和终端一样的体验；插件生态上可能没有 VSCode 那么完善，但核心能力不缺失。如果你是 Java/Spring 技术栈，直接在 IDEA 底部 Terminal 用 CLI 方式就够了。

最后再分享一个小技巧：无论你选哪一端，~/.claude/CLAUDE.md 里的全局偏好都是共享的。在 CLI 里设置过一次中文回答、代码规范、权限偏好，VSCode 插件和桌面版打开也同样生效。所以第一次使用别急着干活，花十分钟把 CLAUDE.md 和 settings.json 打磨好，后面的使用体验会顺滑很多。这个习惯养成之后，你会觉得 Claude Code 比刚装上的时候好用十倍——工具还是那个工具，但你已经把它调教成自己的形状了。