很多接触 Claude Code 的开发者第一次打开终端时都会被一连串陌生的词汇挡住CLI、MCP、Subagents、Skills、settings.json、allowedTools、/compact……这些词单个拆开都能理解组合在一起却让人摸不着头脑。我自己在最初上手时也踩了不少坑明明安装成功却因为PATH问题报claude 不是内部或外部命令也会因为模型名写错被 Claude Code 提示is not a model this version of claude code recognizes。市面上介绍 Claude Code 的文章很多但多数只给安装命令缺少对“核心词汇”的成体系解释。这篇教程就把 Claude Code 里的高频命令、配置项、术语和提示词关键词完整梳理一遍并配合可复制的命令、配置片段和典型报错排查方案。无论你是刚接触 Claude Code 的新手还是已经用了几天但被各种配置折腾过的开发者都可以把这篇文章当作一份按图索骥的词汇手册。1. 背景Show HN 与 Claude Code 是什么Show HN是 Hacker News 上的一个经典标签开发者用它发布自己做的产品、开源项目或实验性工具。标题里出现Show HN: 克劳德的核心词汇本质上是把一个开源项目或技术工具的核心概念整理成公开文档让社区快速了解这个工具“到底是什么、怎么用”。这里的“克劳德”对应 Claude也就是 Anthropic 推出的大语言模型系列。而 Claude Code 则是围绕 Claude 模型打造的命令行编程工具可以直接在终端里通过对话方式完成代码编写、文件修改、命令执行、测试运行等任务算是终端里的“AI 结对编程助手”。Claude Code 解决的痛点是过去使用 AI 编程需要在网页和 IDE 之间来回切换把代码复制给模型再把模型生成的结果粘回来。Claude Code 把模型直接嵌入终端模型能读取项目目录中的文件、执行命令并观察输出结果。它不是一个简单的聊天前端而是一个具备“读取环境—理解上下文—执行操作—反馈结果”闭环能力的编程代理。理解 Claude Code 的核心词汇本质上就是在理解一套相对轻量的 AI 编程工作流。当你看到CLI时要意识到这是在终端里使用的命令行工具当你配置MCP时是在给 Claude Code 挂载外部工具当你编写Skills时是在教会 Claude Code 按固定流程处理任务。掌握这些词才能真正读懂报错、写对配置、跑通流程。2. 环境准备与基础安装在拆解核心词汇之前先把环境准备好。Claude Code 目前的常见形式是 npm 发布的命令行包通过 Node.js 环境安装和运行。无论你用的是 Windows、macOS 还是 Linux思路基本一致。2.1 需要准备的工具Node.js 环境建议使用 18.0 及以上版本。npm 包管理器Node.js 安装后会自动带。Git Bash、PowerShell、CMD 或任意 Linux 终端。一个可用的 Claude 账号或 API Key认证方式根据官方要求调整。VS Code可选用于配合编辑器使用。版本方面Node.js 和 Claude Code 都在快速迭代本文演示的方法是通用的重点讲流程和排错思路。你不一定需要固定使用某个特殊版本只要保证 Node.js 能正常支持 npm 全局安装即可。2.2 安装与验证在终端执行全局安装命令npm install -g anthropic-ai/claude-code安装完成后验证命令是否可用claude --version正常情况下会输出对应的版本号。如果出现以下报错claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这通常说明 npm 的全局安装目录没有加入系统PATH或者是安装过程没有真正成功。可以执行npm config get prefix查看全局安装目录把输出的路径比如C:\Users\你的用户名\AppData\Roaming\npm加到系统环境变量PATH中然后重新打开终端再试。2.3 初次启动在项目目录下执行claude第一次启动时Claude Code 会引导完成登录、组织选择或 API Key 配置。出现提示unfortunately, claude is not available to new users right now时表示当前认证方式或账号状态不允许继续访问需要检查账号权限和 API 配置而不是本地安装出了问题。3. Claude Code 的核心词汇分类Claude Code 的“词汇”可以从四个维度理解启动运行类、斜杠命令类、配置文件类、提示词术语类。下面把这四类逐一拆开。3.1 启动运行类词汇CLICommand Line Interface命令行界面。Claude Code 的本质是一个 CLI 程序。session会话。一次claude启动到退出的完整对话过程。workspace工作区。Claude Code 当前所在项目目录的范围模型只读取工作区内的文件。context上下文。当前会话中模型能看到的全部信息包括命令历史、文件内容、用户输入。cost费用。AI 编程按 token 计费会话过程中会累计消耗。这些词在运行过程中会不断出现。比如会话过长时Claude Code 会提示需要压缩上下文调试时你会关注cost消耗项目目录混乱时你会用.claudeignore控制workspace范围。3.2 斜杠命令类词汇进入交互界面后输入/可以看到命令列表。常用命令如下命令作用典型场景/help查看帮助文档记不清命令时/init初始化项目生成 CLAUDE.md首次进入已有项目/clear清空当前会话上下文切换任务时/compact压缩历史上下文但保留关键信息上下文太长、token 花销大时/model切换模型需要换更强的模型或省钱时/cost查看本次会话费用估算花销/review让模型检查已有代码提交前自查/permissions查看和修改权限配置控制命令执行范围这两类词是“入口词汇”就像 IDE 里的菜单按钮。了解它们才能避免把 Claude Code 当成一个普通聊天框。3.3 配置文件类词汇Claude Code 的配置文件散落在项目目录和用户主目录中文件/目录作用settings.json主要的配置文件控制权限、环境变量、模型行为CLAUDE.md项目说明文件用于告诉 Claude Code 项目背景、编码规范、关键命令.claude/存放项目级配置、Skills、Subagents 的目录.claudeignore类似.gitignore指定哪些文件不让模型读取allowedTools允许模型调用的工具列表permissions权限规则比如是否允许自动读写文件很多新手踩坑都发生在settings.json上。比如在 VS Code 里改了配置却发现模型不生效多半是因为配置文件放错位置或者格式不对。官方文档对配置项更新很快写配置时最重要的不是背字段而是理解结构顶层是权限、中间是环境变量、下面是模型行为。3.4 提示词术语类词汇system prompt系统提示词是模型行为的总纲由 Claude Code 自动注入。user prompt你的输入。skill技能。一种让 Claude Code 按固定流程执行复杂任务的方式通常包含一个SKILL.md和配套脚本。subagent子代理。用于拆分子任务让模型并行或按流程处理复杂问题。MCPModel Context Protocol模型上下文协议。通过 MCP 服务器给 Claude Code 挂载额外工具比如访问数据库、调用内部 API。token词元。模型计算文本长度的最小单位也是计费单位。理解提示词术语是提升 Claude Code 使用效率的关键一步。同样是写代码直接说“帮我写一个登录接口”和“用 FastAPI 写一个登录接口使用 JWT 认证参考auth.py的注释规范”所得到的结果完全不同。4. 常见命令与配置的详细说明下面把几个最容易出错的命令和配置展开讲清楚。4.1/init命令与 CLAUDE.md在已有项目里第一次打开 Claude Code建议先执行claude进入会话后输入/initClaude Code 会读取项目中的代码、README 和配置文件生成CLAUDE.md。这个文件是项目级说明书模型在每次会话中都会读取它用来理解项目背景。如果项目文档写得好AI 生成代码的质量会明显提高。如果项目里已经有比较完整的设计文档你不需要让 Claude Code 从头生成而是手动写一份精简版CLAUDE.md例如# 项目说明 这是一个基于 Spring Boot 3 的用户管理服务。 - 使用 Java 17 - 使用 Maven 构建 - 数据库为 MySQL 8 - 业务代码在 service 包中 - 接口返回统一使用 ResultT 结构 - 新增接口需要补充单元测试这样写可以在不暴露真实业务的前提下把项目的“规矩”告诉模型。4.2/model命令与模型切换Claude Code 支持通过/model命令切换不同模型。这里的模型名称必须与当前 Claude Code 版本支持的名称一致。如果填错例如is not a model this version of claude code recognizes表示当前版本不认识你输入的模型名。解决办法是执行/model查看当前可用的模型列表选择正确的名称而不是盲目输入网上流传的名字。这种情况在接入第三方兼容模型时特别容易碰到比如自定义配置里写着deepseek-v4-pro但当前 Claude Code 版本对应模型列表里没有这个名字就会直接报错。如果要在settings.json里通过env指定模型也要仔细核对模型名。模型切换的常见误区是“以为名字写对就能用”实际上还要看 API 地址和认证方式是否匹配。4.3 settings.json 的常见配置settings.json是 Claude Code 中的核心配置文件通常位于用户目录下的.claude目录中。Windows 示例路径C:\Users\你的用户名\.claude\settings.jsonmacOS/Linux 示例路径~/.claude/settings.json项目级别的配置则放在项目根目录的.claude/settings.json中。一个典型的配置示例{ permissions: { allow: [ Read, Edit, Bash(npm run *), Bash(git *) ], deny: [ Bash(rm -rf *), Bash(pkill *) ] }, model: claude-sonnet-4-20250514, env: { ANTHROPIC_API_KEY: 你的密钥或 key 助手读取方式, API_TIMEOUT_MS: 600000 } }字段解析permissions.allow允许 Claude Code 自动执行的工具。这里使用最小权限原则只允许读取、编辑和执行 npm/git 相关命令。permissions.deny禁止执行的危险命令。model指定默认模型需要填写当前版本支持的模型名。env.ANTHROPIC_API_KEYAPI 密钥。生产中更推荐在系统环境变量中配置或通过apiKeyHelper动态读取密钥。env.API_TIMEOUT_MS请求超时时间。新建settings.json后如果模型还是不生效先确认文件位置对不对再看 JSON 格式有没有错误最后重启 Claude Code。4.4 env 区域与 apiKeyHelperenv区域用于向 Claude Code 注入环境变量。比较典型的是把 API Key 的读取方式抽离不把密钥直接写在配置里{ env: { ANTHROPIC_API_KEY: 可以在这里写一个固定的 key, apiKeyHelper: node /path/to/helper.js } }在实际生产环境中apiKeyHelper可以连接密钥管理服务动态获取临时密钥降低密钥泄露风险。设置好之后Claude Code 启动时会自动执行 helper 脚本获取密钥。这类配置的完整能力取决于你的团队和部署方式核心思路就是“密钥不落盘、动态获取”。4.5 Skills 与 SubagentsSkills是 Claude Code 中用于定义特定技能的机制。一个 Skill 通常放在.claude/skills/目录下内部包含一个SKILL.md文件和必要脚本。比如做一个代码审查技能.claude/skills/review/ └── SKILL.mdSKILL.md内容如下--- name: code-review description: 检查代码中可能存在的性能、安全和可维护性问题并输出修改建议 --- 当用户要求代码审查时 1. 先分析文件整体结构。 2. 找出可能的安全隐患例如 SQL 注入、路径遍历。 3. 检查异常处理是否完备。 4. 给出修改建议并解释原因。 5. 不要直接修改代码除非用户要求。Subagents则是把复杂任务拆给子代理处理。比如一个负责测试用例生成的子代理一个负责数据库迁移脚本的子代理。子代理拥有自己的上下文可以让主代理避免被琐碎信息塞满。4.6 MCP 与外部工具MCPModel Context Protocol是 Claude Code 连接外部工具的标准方式。通过配置 MCP 服务器可以让 Claude Code 查询数据库、操作浏览器、调用内部 HTTP 接口等。在settings.json的mcpServers字段中配置 MCP 服务器例如{ mcpServers: { my-db-server: { command: npx, args: [-y, some/mcp-server-package], env: { MCP_SERVER_API_KEY: 你的 key } } } }配置完成后重启 Claude Code模型就能调用my-db-server提供的工具。5. 实战在终端里跑通一套 Claude Code 工作流理论部分讲清楚后下面用一个完整的案例把流程串起来。假设我们要在本地项目中使用 Claude Code 完成一次代码审查和单元测试补充。5.1 创建测试项目在终端中执行mkdir claude-demo cd claude-demo git init npm init -y再手动创建一个简单的add.js文件function add(a, b) { return a b; } if (require.main module) { const a Number(process.argv[2]); const b Number(process.argv[3]); console.log(add(a, b)); } module.exports { add };5.2 初始化 Claude Code 环境在项目目录下执行claude进入交互界面后输入/init等待 Claude Code 读取项目内容并生成CLAUDE.md。如果它生成的说明不够准确可以自己补充。5.3 请求代码审查在会话里输入请审查 add.js检查是否存在边界问题、安全隐患并输出改进建议。正常情况下 Claude Code 会读取代码并给出分析。这里可以看到一个关键点模型具备读取文件的能力所以不需要手动把代码复制到输入框。5.4 请求生成测试文件继续输入请基于 Node 内置 test runner 为 add.js 编写测试文件 test/add.test.js并运行测试。Claude Code 会创建测试文件并尝试运行npm test或node --test相关命令。如果测试通过结果会显示在终端里。这个流程演示了 Claude Code 最核心的工作方式理解项目文件 → 生成代码 → 调用终端命令 → 反馈结果。5.5 查看上下文与费用输入/cost查看累计消耗情况。输入/clear可以清空当前上下文开始新任务。5.6 用 settings.json 控制权限为了安全可以在项目根目录的.claude/settings.json中写入{ permissions: { allow: [ Read, Edit, Bash(node *), Bash(npm *) ], deny: [ Bash(rm *) ] } }重启 Claude Code 后它只会自动执行白名单里的命令。这样做的好处是即使模型被复杂提示词带偏也难以直接破坏本地文件。6. 常见问题与排查思路下面把 Claude Code 使用中最常见的报错和问题做一次汇总。问题现象常见原因解决思路claude不是内部或外部命令npm 全局安装目录未加入 PATH执行npm config get prefix把对应目录加入 PATH重开终端unfortunately, claude is not available to new users right now账号权限不足或认证方式受限检查账号状态、登录方式和 API Key 配置而不是检查安装is not a model this version of claude code recognizes模型名填写错误或当前版本不支持该模型执行/model查看可用列表选择当前支持的模型名API Error/ 连接超时网络问题、API Key 失效、超时时间太短检查 API 地址、key 是否正确适当增加API_TIMEOUT_MSClaude Code 不读取项目文件workspace 路径不对或.claudeignore配置太宽确认启动目录是否为项目根目录检查.claudeignore内容Claude Code 执行了危险命令权限配置过于宽松在settings.json中收紧permissions.allow增加deny规则failed to start claude’s workspaceNode 版本不兼容、工作目录损坏、缓存冲突更新 Node 版本检查项目目录权限清空 Claude 相关缓存后重试VS Code 配置 Claude Code 后不生效插件未加载最新配置、settings.json 路径错误检查 VS Code 扩展安装情况重启 VS Code 和 Claude Code确认 settings.json 是当前启用文件Claude Code 上下文过长、费用暴涨会话积累太多历史内容尽使用/compact压缩上下文或直接/clear开启新会话claude code 529相关错误服务器过载或限流稍后重试降低请求频率检查 API 配额卸载不走干净npm 卸载残留或安装源混乱执行npm uninstall -g anthropic-ai/claude-code手动删除.claude目录中不用的缓存遇到报错时我的建议是先看报错前两行很多问题本质上是同一个要么路径找不到要么配置格式不对要么模型认证失败。不要一慌就重装重装解决不了配置错误。7. 最佳实践与工程建议结合我自己的使用经验在使用 Claude Code 时下面几点最重要。7.1 权限最小化Claude Code 在终端里有很高的权限能读文件、改文件、执行命令。因此权限配置是安全底线。不建议直接允许所有工具也不建议在会话中轻易允许高危命令删除操作。推荐在项目级settings.json中把允许列表写成最小集比如只允许读取、编辑、运行测试和 Git 操作。{ permissions: { allow: [ Read, Edit, Bash(git *), Bash(npm test *) ] } }涉及删除数据、修改生产环境配置的命令一律走人工确认不要让 Claude Code 自动执行。7.2 使用 CLAUDE.md 管理项目上下文一份好的CLAUDE.md能显著提升生成代码的质量。建议高频更新内容包含项目技术栈和运行方式。目录结构说明。代码风格约定。测试命令。关键业务规则。Claude Code 每次会话都会读取这份文件算是“给 AI 的项目说明书”。7.3 密钥管理不要把密钥直接写进普通配置文件或推到 Git 里。优先使用系统环境变量配合apiKeyHelper动态读取。.gitignore中要加入.claude/settings.local.json这类可能包含敏感信息的文件。7.4 会话卫生一个会话只做一件事。如果项目需求比较复杂可以拆成多个子任务分别在不同会话中完成。上下文太长时不要硬撑使用/compact压缩或直接/clear。这既保护费用也能降低模型被历史信息干扰的概率。7.5 模型名与版本无论安装 Claude Code 还是切换模型都不要从网络资料里直接抄写模型名。模型名会随版本更新变化在不同版本之间不一定通用。如果报错is not a model this version of claude code recognizes优先在当前环境中查询可用列表而不是去搜索一条“永久有效”的配置。7.6 使用 Skills 沉淀工作流如果团队里多次使用相同的审查、重构、部署流程可以把这些流程写成Skills让 Claude Code 按标准流程执行。这不仅是提高效率也是把工程经验固化到 AI 工具里的一种方式。8. 总结从核心词汇到独立使用回头看 Claude Code 里那些让人困惑的“核心词汇”其实每一组词都对应一个真实使用场景CLI、workspace、session是理解它运行方式的基础词。/init、/clear、/compact、/model是控制会话的操作词。settings.json、permissions、env、apiKeyHelper是配置与安全词。Skills、Subagents、MCP、CLAUDE.md是让它更智能的进阶词。各种报错里的模型名、路径名、命令名则是定位问题的关键线索。当你把这些词全部弄懂时Claude Code 不再是“一个会自动写代码的黑盒”而是一套有边界的开发工具。你能告诉它读哪些文件、执行哪些命令、走哪套流程也能在它越界时通过权限配置及时拦停。建议你从一个小型 demo 项目开始先跑通/init、/review、/model、/cost这几个基础命令再逐步尝试配置settings.json、编写SKILL.md、接入 MCP。等这一套流程都滚过一遍之后再回到自己的正式项目里去使用就不会被那些表面上的术语吓住了。