蓝盐泳池1983经常在社区里看到同一类问题——Claude Code 装好了，试运行也通了，但一打开配置文件就卡住了：settings.json 和 CLAUDE.md 到底分头管什么？Skill 和插件是一回事吗？CLI、桌面版、VSCode 插件三个到底选哪个？为什么别人说加个 deepseek-v4-pro 就能换模型，我照着写就报 "is not a model this version of claude code recognizes"？
这些问题的根源，绝大多数不是操作问题，而是名词问题。Claude Code 这个工具本身不难，难的是它背后的名词体系。model、API Key、Base URL、Token、上下文窗口、Skill、MCP、CLAUDE.md、CC Switch……每一个词背后都是一套机制，新手没搞懂就硬上，于是反复踩坑。
这篇就当一份扫盲笔记，我把日常高频出现的名词按"形态、核心概念、扩展机制、配置文件、第三方工具、报错术语"六个维度拆开讲，尽量用大白话，附带我实测过的配置经验和踩坑记录。适用对象是刚接触 Claude Code、或者已经跑通但被各种名词绕晕的同学。
1. 先分清三兄弟：CLI、桌面版、VSCode 插件到底啥关系
Claude Code 最常见的三个入口，经常让新手犯迷糊：明明装了一个，教程讲的却是另一个，照着敲命令根本找不到地方。
1.1 CLI 版：终端里的老大哥
CLI 全称是 Command Line Interface，命令行界面。这是 Claude Code 最早、功能最全的形态，安装方式通常是用 npm 全局安装，装完在终端里敲 claude 就进入交互界面。社区里绝大多数教程、配置示例、报错讨论都是围绕这个版本展开的，所以你会看到热搜里有大量的"安装 claude code"、"claude code 使用教程"，默认指的都是这个 CLI 版。
CLI 版的优势是干净、直接、脚本友好，适合日常在终端里跑项目的开发者。跨平台支持也最稳，Windows、macOS、Ubuntu 都有对应的安装路径。热搜里 "ubuntu claude code"、"mac claude code安装"、"windows安装claude code" 就是在说这个事。它的配置文件集中在用户目录下的 .claude 文件夹里，后面讲配置时会反复提到。
1.2 桌面版：给不想碰终端的人准备的
桌面版（通常叫 Claude Code Desktop）是后来推出的图形界面形态。它把 CLI 的能力包了一层 GUI，界面里有对话框、文件树、设置面板，不用记命令。热搜词 "claude code desktop"、"claude code 桌面版"、"claude code 桌面应用的下载地址" 都是冲着这个来的。
桌面版适合两种人：一种是不习惯终端操作的新手，另一种是希望在独立窗口里长时间挂着会话、方便查看上下文的用户。但我得提醒一句：桌面版的配置方式和 CLI 版不完全一样，有些配置项在图形界面里看不到，还是得去改配置文件。所以哪怕你用桌面版，下面关于 settings.json 和 CLAUDE.md 的内容也值得看。
1.3 VSCode 插件：编辑器里长出来的助手
如果你日常工作基本都在 VSCode 里，插件版体验最顺。它本质上是把 Claude Code 的能力嵌进编辑器，边写代码边对话，能自动感知当前打开的文件和项目结构。热搜里 "vscode 配置 claude code"、"claude code for VS Code v2.1.245"、"vscode 如何使用 claude code" 指的都是这个。
插件版的模型配置、API Key 设置和 CLI 版基本通用，但界面入口藏在 VSCode 的设置面板里，所以很多人会遇到"插件装了但不知道在哪填 Key"的尴尬。
1.4 三兄弟怎么选
| 形态 | 适合人群 | 安装方式 | 配置复杂度 | 典型场景 |
|---|---|---|---|---|
| CLI | 熟悉终端、写脚本的开发者 | npm 全局安装 | 较低，纯配置文件 | 日常项目、自动化 |
| 桌面版 | 新手、GUI 偏好者 | 官网下载安装包 | 中等，GUI+配置文件 | 对话式编程 |
| VSCode 插件 | 编辑器重度用户 | VSCode 扩展市场 | 中等，入口在编辑器 | 边写边改 |
我的建议是：先在 CLI 版上把核心概念跑通，因为它最贴近底层，教程覆盖最全。跑通了以后，桌面版和插件版对你来说就只是换了个壳。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心术语拆解：模型、上下文、Token、API Key 到底在说什么
这一节是名词扫盲的重头戏。很多报错和困惑，本质上都是这几个概念没理清。
2.1 模型（Model）：Claude Code 的大脑不止一个
Claude Code 本身不是一个"AI 大脑"，它只是一个外壳。真正做推理的是背后的大模型。默认情况下，它调用的是 Anthropic 官方的 Claude 系列模型。但 Claude Code 的设计允许你通过配置切换到其他兼容模型。
这就引出了最常见的坑：model 这个配置项填什么。很多人会照着网上教程把 model 改成 deepseek-v4-pro 之类的大模型名字，然后启动时报错：
code复制"deepseek-v4-pro" is not a model this version of claude code recognizes
这句英文翻译过来是"这个版本的 Claude Code 不认识这个模型名"。新手看到这个报错就懵了，实际上原因无非几种：
- 模型名写错了，少了前缀或版本号。
- 当前 Claude Code 版本太旧，还不支持你填的那个模型标识。
- 你只改了
model，但对应的 API 接口地址（Base URL）没改，Claude Code 还在拿这个模型名去请求官方接口，官方当然不认识。
所以请记住一个概念：模型名必须和接口地址配套使用。你用什么服务的模型，就要把 ANTHROPIC_BASE_URL 或配置里的 apiBaseUrl 指到对应服务商的接口，同时把 API Key 换成那个服务商给你的 Key。这三点是一个组合，缺一不可。
2.2 Token 和上下文窗口：为什么聊着聊着它就"失忆"
Token 是大模型处理文本的最小单位，可以粗略理解为"半个词"或"一个汉字"。你发给模型的每一句话、模型回复的每一句话，以及它读取的代码文件，都要换算成 Token。模型计费、上下文长度限制都基于 Token。
上下文窗口（Context Window）是模型单次对话最多能放下的 Token 数量。Claude 系列模型的窗口上限很大，但再大也有边界。当你的对话历史加上项目文件超过这个限制时，模型就不得不丢弃最早的内容——表现就是"它好像忘了我们一开始说过什么"。
这种情况下，解决方案不是重新开一个会话，而是学会用 /compact（压缩上下文）。这个命令会把对话历史智能压缩成一份摘要，腾出空间。我在实际使用中，跑长任务时每过一段时间就主动 /compact 一次，比硬撑到报错再处理要稳得多。
2.3 API Key：入场券，也是计费钥匙
API Key 是你调用模型服务时需要出示的身份凭证。它决定了三件事：你是谁、你能用哪些模型、谁来为这次调用付费。
比如你配置了 ANTHROPIC_API_KEY，就用它去请求 Anthropic 官方接口。如果你配置了某个第三方兼容服务的 Key，请求就会发往那个服务的接口，由该服务商计费。
这里有个新手容易犯的错误：多个 Key 混用。比如 settings.json 里填了 A 服务的 Key，但环境变量里还残留着 B 服务的 Key，最后请求到底发到哪，取决于优先级。后面讲配置顺序时我再细说。
2.4 API Base URL：通往大模型的路由地址
Base URL 是 API 接口的基础地址。Claude Code 默认指向 Anthropic 官方接口，但如果你要用第三方兼容服务，就得把地址改成服务商提供的那个。
你可以把模型服务想象成餐厅。API Key 是会员卡，模型名是菜品名，Base URL 是餐厅地址。会员卡是 A 餐厅的，地址却写成 B 餐厅，那 B 餐厅自然不认识 A 餐厅的菜品名——这就是 2.1 里那个报错的本质。
3. Skill 不是技能点：Claude Code 的扩展机制到底怎么玩
热搜里 "claude code skill"、"claude code 技能"、"claude code skills" 排得很靠前，但很多人对 Skill 的理解还停留在"一个插件包"的层面。这里我把它的原理和玩法讲清楚。
3.1 Skill 到底是什么
Skill（技能）是 Claude Code 的一种扩展机制，用来给模型补充特定领域的知识和操作流程。它不是一个普通插件，而是一个组合包：一个 SKILL.md 说明文件，加上若干脚本、模板、参考文档。
核心思路是：当你在对话中触发某个场景（例如"帮我做个 PPT"），模型会去找有没有对应的 Skill，如果有，就读取其中的 SKILL.md，按里面写的步骤一步步执行。你可以把 Skill 理解成给模型的一份"工作时用的操作手册"。
3.2 一个 Skill 在文件系统里长什么样
一个典型的 Skill 目录结构大致是：
code复制my-skill/
├── SKILL.md
├── scripts/
│ └── build_ppt.py
└── references/
└── template.pptx
SKILL.md 是灵魂，它里面有这个 Skill 的名称、适用场景、执行步骤、注意事项。模型不是靠读代码来理解 Skill 的，而是靠读这份 Markdown 文档。所以写 Skill 时，重点不是代码写得多漂亮，而是说明文档写得够不够清楚。
3.3 安装 Skill 的几种路径
Skill 的安装本质上是把文件夹放到指定目录。常见位置有两种：
- 用户级：
~/.claude/skills/，对所有项目生效。 - 项目级：
.claude/skills/，只对当前项目生效。
我建议优先用项目级，因为 Skill 通常和项目场景强相关，放到用户级容易造成"这个项目用不上但模型却总想调用它"的困扰。有个例外：如果你自己积累了跨项目通用的 Skill，比如代码规范检查、日报生成，放用户级更省事。
3.4 为什么 Skill 这么重要
对模型来说，通用知识它已经有，但特定操作流程它是不知道的。比如"这个公司的代码规范要求变量命名前缀"、"产品部周报要用固定模板"这些信息，模型不可能预置，但 Skill 可以补齐。
我个人的体会是，用 Claude Code 从"能聊天"到"能干活"的转折点，就是开始写自己的 Skill。别贪多，从你最常做的一件事入手，把流程写清楚，让模型照着跑。跑通了再扩展下一个。
3.5 顺手把 MCP 和 Plugin 也说清楚
与 Skill 一起经常被提及的还有两个名词：MCP 和 Plugin。
MCP（Model Context Protocol）是一种更底层的协议，用来让模型连接外部工具和数据源，比如读取本地数据库、调外部 API。Skill 偏"给模型加知识和流程"，MCP 偏"给模型加手脚"。
Plugin 则是 Claude Code 后来推出的一套插件体系，用来统一管理预构建的扩展能力，和 Skill 概念有重叠，但现在最主流、资料最多的还是 Skill。新手阶段不需要深挖三者的边界，记住一件事：Skill 改的是"模型怎么做一件事"，MCP 改的是"模型能碰到什么"，就够用了。
4. 配置名词课：settings.json、CLAUDE.md、环境变量，新手最容易懵的三个文件
这一节会集中解决一个热搜问题：新建了 settings.json 却还是接不上模型，到底怎么回事。
4.1 settings.json：全局设置和项目设置的层级关系
settings.json 是 Claude Code 的主配置文件，里面主要配置模型、API 地址、行为开关等。它有层级关系：
- 用户级配置：
~/.claude/settings.json，作用于该用户所有项目。 - 项目级配置：
项目根目录/.claude/settings.json，只作用于当前项目，优先级高于用户级。
具体配置内容各家服务商给的模板不一样，但核心字段不外乎：
- model：模型名
- apiKey 或 ANTHROPIC_API_KEY：API 密钥
- apiBaseUrl 或 ANTHROPIC_BASE_URL：接口地址
如果你改了 settings.json 还是没生效，第一件事是检查两个东西：一是文件路径对不对，是不是放在了项目根目录下并且目录名确实叫 .claude；二是 JSON 格式有没有写错，少个逗号或者多了个注释都可能导致整个文件被忽略。注意，settings.json 是标准 JSON，不支持注释，有些人从网上复制配置时把注释也粘进去，结果解析失败。
4.2 CLAUDE.md：比提示词更硬的"项目说明书"
CLAUDE.md 是 Claude Code 的记忆文件。每次启动会话时，模型会自动读取这个文件，把它当作对项目背景和规则的说明。
它和 settings.json 的分工很明确：settings.json 管"连接参数"（接哪个模型、用什么 Key），CLAUDE.md 管"工作规则"（项目结构、代码风格、禁止做什么）。
比如你可以在 CLAUDE.md 里写：
- 本项目使用 TypeScript，不要生成 JavaScript 文件。
- 后端接口统一走
src/api/目录。 - 修改代码后必须补测试。
模型每次都会带着这些规则工作，效果比你在对话里反复强调要稳定得多。还有一个小技巧：如果你想强制模型用中文回答，也可以把"始终用简体中文回答"写进 CLAUDE.md，比每次对话都嘱咐一句要省事。
4.3 环境变量：改代码不如改环境
settings.json 之外，环境变量是另外一种配置途径。Claude Code 在启动时会读取一些环境变量，比如 ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL。
环境变量和 settings.json 同时存在时，谁优先？不同版本行为略有差异，但通常原则是：更具体的配置优先。为了避免脑子转不过来，我的建议是选一条路走到底。如果你用 settings.json，就把环境变量里相关的旧值清掉，尤其是 ANTHROPIC_API_KEY，因为环境变量残留是导致"我改了配置但没变"的高发原因。
4.4 "改完 settings.json 还没生效"排查清单
我把自己踩过的坑整理成一个固定排查顺序：
- 确认文件路径正确：项目级配置必须放在项目根目录的
.claude文件夹里，文件名必须是settings.json。 - 确认 JSON 合法：可以在线上 JSON 校验工具里把内容贴一下，格式错了配置会被静默忽略。
- 确认环境变量没抢优先级：检查终端里有没有残留的
ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL，有就unset掉。 - 确认重启了会话：Claude Code 是在启动时读配置的，改完不重启，会话里还是旧配置。
- 确认版本支持：老版本可能不支持某些新配置项，顺手升级到最新版再试。
这套流程能解决九成"配置不生效"的问题。剩下的一成，基本都是模型名或接口地址本身写错了，那就回到第 2 节的报错排查思路。
5. 绕不开的第三方工具：CC Switch 这类"切换器"在切什么
热搜里 "claude code + cc switch + deepseek" 出现频率很高，CC Switch 已经是 Claude Code 生态里绕不开的一个工具，这里单独讲。
5.1 为什么会有 CC Switch 这种东西
CC Switch（全称 Claude Code Switch）是社区开发者做的一个配置切换工具，主要解决一个痛点：你的 Claude Code 不想只用一套官方默认配置，而是要在多套"模型服务组合"之间来回切换。
比如你同时持有多个服务商提供的 API：A 服务商排队多，B 服务商便宜，C 服务商在自己写 Agent 时用。每次手动改 settings.json 和换环境变量太痛苦，于是有人写了个图形化工具，让你一键切换整套配置。
5.2 model、provider、baseUrl：切换工具到底在切什么
CC Switch 表面上是"切换配置"，实际上切换的是三个东西的组合：model、provider、baseUrl（以及对应的 API Key）。
provider（服务提供商）组合决定了你去哪个服务商买 Token 套餐；model 决定你买哪个菜品；baseUrl 决定你去哪个地方取餐。三者必须一致，否则就像拿着 B 店的会员卡在 A 店点菜，系统不认识。
所以当你看到社区里有人分享"CC Switch 接入 DeepSeek"的实操时，他实际上做的三件事是：
- 在 CC Switch 里新建一个配置，填上 DeepSeek 的模型名。
- 把 Base URL 指到 DeepSeek 兼容接口。
- 填上 DeepSeek 的 API Key。
本质上和手改 settings.json 没区别，只是CC Switch 帮你把这几套文本组合保存下来，下次一键切换。
5.3 使用第三方配置工具的三个注意事项
第一，改配置前记得备份。CC Switch 切换时可能会覆盖你的 settings.json，建议把原始文件复制一份。
第二，确认工具本身是最新版。CC Switch 这类工具跟随 Claude Code 版本迭代很快，版本太旧可能无法识别新版配置结构，甚至反过来把已有的合法的配置重写掉。
第三，不要把密钥写在明文配置里再分享给别人。CC Switch 生成的配置会包含 API Key，截图或粘贴配置时千万打码。
另外说一句，工具只能说帮你在不同服务商之间切换省时间，它不能帮你解决"服务商本身不稳"的问题。如果某个服务商频繁 529、429，再怎么切换配置也没用，换一家或者调整调用频率才是正解。
6. 报错信息里的高频名词：把"红字"翻译成人话
最后一个大块，是热搜里出现最多的报错类名词。我把几个高频的拿出来逐一解释，不是为了让你背答案，而是让你下次看到红字时知道该往哪个方向查。
6.1 "xxx is not a model this version of claude code recognizes"
这是配置第三方模型时最经典的报错。完整的报错长这样：
code复制"deepseek-v4-flash" is not a model this version of claude code recognizes, so
重点在 "not a model this version recognizes"，意思是"当前这个版本的 Claude Code 没在你指定的接口里找到这个模型"。
排查思路上面已经讲过，这里再强调最常见的三个原因：
- 模型名拼写有误，或者把"服务商的模型名"和"Claude Code 内部的模型名"搞混了。
- Base URL 没指向正确的接口。
- 当前 Claude Code 版本太旧，模型列表是写死在程序里的，需要升级版本才能认识新模型。
有个简单自测法：你填的那个模型名，能不能在你配置的 API 服务商官网上查到？查不到，那基本就是名字错了。
6.2 529 和 429：限流与过载
529 是 Claude 官方接口常见的过载错误码，意思是服务端太忙，暂时处理不了你的请求。它不是你配置的问题，而是上游用的人太多，通常等几秒或几分钟就好。
429 是"请求过多"限流错误，意思是你在短时间内发了太多请求，触发了速率限制。解决方法是降低请求频率、减少并发，或者稍等片刻再试。
遇到这类错误，我不建议立刻重装或改配置。先看清楚错误码，如果是 529/429，直接休息一下，或者用 /compact 缩短对话长度少占点资源。
6.3 输出乱码：编码问题
热搜里有 "claude code 输出乱码"，这个在 Windows 终端里特别常见。原因主要是终端默认编码和程序输出编码不一致。Shell 或 Windows Terminal 设置为 UTF-8 编码后，乱码基本能解决。
如果你在 VSCode 插件里遇到乱码，检查右下角编码格式，切到 UTF-8。千万别一乱码就去改模型配置，那是编码问题，不是模型问题。
6.4 语言问题：怎么让它固定用中文回答
Claude Code 默认回复语言会跟随你的提问语言，但很多人希望它稳定输出中文。最有效的办法是写在 CLAUDE.md 里，加上一行"始终使用简体中文回复"，模型每次启动都会读到。比在对话里反复强调要可靠得多。
6.5 卸载重置：配置残留怎么清干净
这个虽然不算"报错术语"，但排查问题时经常需要。很多诡异问题其实都是旧配置残留导致的，特别是在你反复折腾过多个服务商之后。卸载 Claude Code 时，除了卸载程序本身，还要把用户目录下的 .claude 配置文件夹清理掉，否则重装后配置还会"阴魂不散"。动手删之前记得备份你辛苦积累的 Skill 和 CLAUDE.md，这些是无价的。
最后再分享一个小技巧：名词背不齐没关系，关键是遇到任何报错时，先冷静把它翻译成"某个名词配置不对"，而不是急着重装工具。我见过太多人因为一个 model 拼写反复重装三次，最后发现只是少了个连字符。先在社区搜一下错误信息里的关键词，九成问题都有人趟过路了。如果你正准备入坑 Claude Code，我建议把这篇名词表当成脚手架，先跑通最小闭环，再一个个啃细节——名词只是用来描述事情的，真正值钱的是你拿它干成了什么事。