本教程面向初次接触 AI 编程助手的开发者涵盖安装、认证配置、多种使用方式、终端技巧、Skills 自定义以及常见问题解答。Wiki 风格编写可按章节跳转。本文适合谁第一次听说 Claude Code想从零跑通已安装但卡在 API Key、Base URL、401/404 报错想系统了解终端斜杠命令、/唤醒 Skill、CC Switch 多 Provider 切换你将学到什么如何安装 Claude Code 并做健康检查三种认证方式如何选择官方登录 / CC Switch / 手动 settings.json终端、VS Code 插件、Desktop 等多种用法斜杠命令与 Skills 的入门与自定义常见报错的排查步骤目录章节内容1. 简介Claude Code 是什么、典型场景2. 安装与环境检查npm 安装、验证、Windows 排错3. 认证方式对比三种方式选型与新手推荐路径4. 方式 A官方登录/login订阅用户5. 方式 BCC Switch可视化 Provider 管理推荐6. 方式 C手动 settings.json手写 API Key 与 Base URL7. 多种使用方式终端、VS Code、IDE、Desktop8. 终端入门项目目录、CLI 参数、权限提示9. 终端技巧与斜杠命令/菜单、Skill、快捷键10. 项目级配置CLAUDE.md、.claude 目录11. Skills 自定义创建与调用自定义 Skill12. 常见问题 FAQ401、404、配置不生效等13. 学习路径Level 14 进阶路线14. 参考链接官方文档与延伸阅读1. 简介本章目标理解 Claude Code 的定位知道它适合解决什么问题。Claude Code 是什么Claude Code 是 Anthropic 推出的AI 编程助手运行在本地终端或 VS Code 等 IDE中。与普通网页聊天不同它会在当前项目目录下工作读取文件结构、分析代码、修改 Bug、生成页面、写测试、产出文档。一句话对比工具特点网页版 Claude通用对话不自动读本地项目GitHub Copilot编辑器内补全为主CursorIDE 一体化 AI 编辑Claude CodeCLI 项目上下文 斜杠命令 / Skill 工作流典型使用场景分析陌生项目的目录结构和技术栈阅读并解释某段代码的逻辑生成前端页面或 API 接口代码定位并修复 Bug重构函数或组件编写 README、测试用例提交前做代码审查/code-review官方文档最新安装方式、环境变量、命令列表以官方为准文档首页Overview - Claude Code Docs设置说明Claude Code settings - Claude Code Docs环境变量Environment variables - Claude Code Docs命令参考Commands - Claude Code Docs2. 安装与环境检查本章目标在本机安装 Claude Code确认claude命令可用。前置条件Claude Code 通过 npm 全局安装需要先安装Node.js自带 npm。检查版本node -v npm -v若能正常输出版本号建议 Node.js 18即可继续。安装npm install -g anthropic-ai/claude-code验证安装claude --version进入交互界面claude成功标志出现 Claude Code 的输入提示符可输入自然语言或/命令。健康检查安装后第一件事在交互界面输入/doctor或在终端直接运行claude doctor/doctor会检查安装、配置、网络等项并按状态图标列出结果。有问题时可按f让 Claude 尝试自动修复。Windows 用户注意若提示claude 不是内部或外部命令确认 Node.js 和 npm 已安装查看 npm 全局路径npm config get prefix将该路径下的bin或 Windows 下的根目录加入系统PATH关闭并重新打开PowerShell 或终端若经常做开发也可考虑在WSL中安装行为更接近 Linux/macOS 环境。更新到最新版npm update -g anthropic-ai/claude-code更新后可在会话内运行/release-notes查看变更再运行/help确认新命令是否可用。3. 认证方式对比本章目标选择适合自己的登录/接入方式避免在 Key 和 Base URL 上反复踩坑。Claude Code 需要能访问 Anthropic 模型服务。国内用户常见三种配置方式方式适合谁优点注意官方/login有 Claude Pro/Max 订阅零配置、最省心需能访问 Anthropic 账号体系CC Switch推荐新手多模型/多平台、第三方 API可视化、Claude Code热切换Provider、统一管理 MCP/Skills需额外安装桌面应用手动 settings.json想完全掌控配置透明、可脚本化、便于团队文档化易填错 Base URL 或 Key新手推荐路径建议按此顺序操作15 分钟内可完成首次跑通完成 第 2 章 安装运行/doctor有 Claude 订阅→ 进入 第 4 章 使用/login无订阅、使用第三方 API→ 进入 第 5 章 安装 CC Switch 添加 Provider熟悉后如需细调再阅读 第 6 章 了解底层配置文件4. 方式 A官方登录本章目标使用 Anthropic 官方账号订阅无需手写 API 配置。操作步骤在终端进入任意目录运行claude输入/login或在启动引导中选择登录按提示在浏览器中完成 Anthropic 账号授权返回终端发送测试消息请用一句话回复Claude Code 已正常工作。成功标志收到正常回复且/doctor无认证相关报错。相关命令命令用途/login登录 Anthropic 账号/logout退出当前账号/upgrade查看或升级 Pro/Max 计划视账号显示说明官方登录不需要配置ANTHROPIC_BASE_URL或ANTHROPIC_AUTH_TOKEN若同时使用 CC Switch 或 settings.json注意避免 env 变量冲突一般选一种主认证方式即可5. 方式 BCC Switch本章目标用 CC Switch 可视化管理 API Provider适合第三方 API 与多模型切换。CC Switch 是什么CC Switch 是一款开源桌面应用统一管理 Claude Code、Codex、Gemini CLI、OpenCode 等 AI 编程 CLI 的 Provider 配置。源码https://github.com/farion1231/cc-switch为什么值得学不用手改 JSON降低填错 Base URL 的概率内置 50 Provider 预设也可自定义Claude Code 支持热切换切换 Provider 后通常无需重启终端其他 CLI 多数需重启可统一管理 MCP、Skills、Prompts、会话与用量统计安装打开官网CC Switch 官方网站 - AI 编程 CLI 统一管理工具进入 Releases 下载对应系统安装包Windows / macOS / Linux按安装向导完成安装macOS 推荐.dmg已签名公证首次使用流程启动 CC Switch在 Claude Code 工具页点击「添加 Provider」选择内置预设如你的 API 中转平台或「自定义」填入API Key如sk-xxxxxxxx勿泄露真实 KeyBase URL以 Provider 文档为准见 Base URL 陷阱模型名称从平台后台复制完整 ID不要猜claude或sonnet保存后将该 Provider设为当前生效打开终端进入测试目录运行claude发送一句话测试成功标志Claude Code 正常回复CC Switch 中可见请求/用量若已开启统计。[待补图CC Switch 添加 Provider 界面]进阶功能入口即可功能说明系统托盘右键快速切换 ProviderLocal Routing本地代理、格式转换、失败自动 failover共享配置片段切换 Provider 时保留 MCP/插件等公共配置编辑 Provider → 共享配置面板 →「从当前 Provider 提取」MCP / Skills在 CC Switch 中集中管理写入 Claude Code 配置与手动 settings.json 的关系CC Switch 会将 Provider 信息写入 Claude Code 使用的配置如~/.claude/settings.json或相关 env。若你曾手改文件可在 CC Switch 中「从当前 Provider 提取」同步回来避免两套配置不一致。CC Switch 常见问题切换 Provider 后 Claude Code 仍用旧配置确认 CC Switch 中已将该 Provider 设为当前Claude Code 会话若已打开可新开终端再试多数情况支持热切换切换 Provider 后插件/MCP 配置丢失使用「共享配置片段」功能创建新 Provider 时勾选「写入共享配置」6. 方式 C手动 settings.json本章目标理解底层配置文件适合进阶用户或无法使用 CC Switch 的环境。配置文件路径系统路径macOS / Linux~/.claude/settings.jsonWindows%USERPROFILE%\.claude\settings.json如C:\Users\你的用户名\.claude\settings.json若.claude目录不存在可手动创建# macOS / Linux mkdir -p ~/.claude # Windows PowerShell New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.claude通用配置模板将下列内容写入settings.json替换为你的真实 Key 和网关地址{ env: { ANTHROPIC_BASE_URL: https://你的-api-网关地址, ANTHROPIC_AUTH_TOKEN: sk-你的密钥, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1, CLAUDE_CODE_ATTRIBUTION_HEADER: 0 } }示例第三方平台仅供参考部分教程如 CSDN 国内使用指南使用 TransAI 平台Base URL 为https://transitai.chat。你的平台请以官方说明为准不要照搬。字段说明字段含义ANTHROPIC_BASE_URLAPI 请求地址填错易出现 404ANTHROPIC_AUTH_TOKENAPI Key等同于 Bearer TokenCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC设为1可关闭部分非必要流量CLAUDE_CODE_ATTRIBUTION_HEADER设为0可关闭 attribution 头部分中转平台需要Base URL 陷阱不同平台对 Base URL 要求不同有的填根路径https://api.example.com有的要加/v1https://api.example.com/v1以你使用的 Provider 文档为准。填错常见现象404、接口路径错误、连接失败。验证配置保存settings.json确认 JSON 格式正确注意逗号、引号关闭已打开的 Claude Code 会话重新打开终端运行mkdir claude-code-test cd claude-code-test claude输入请用一句话回复Claude Code 已经可以正常工作。成功标志收到正常回复。安全提示不要把真实 API Key 提交到 Git、发到群聊或截图公开。泄露后立即在平台后台删除并重建 Key。7. 多种使用方式本章目标了解 Claude Code 在不同界面下的入口按习惯选择终端或编辑器。方式怎么进入适合场景终端交互项目目录执行claude全功能、斜杠命令、长时间任务一次性 CLIclaude 帮我分析目录结构快速问答不进交互VS Code 插件扩展市场安装 Claude Code编辑器内对话、结合当前文件IDE 集成会话内/ide查看与 VS Code / Cursor 等联动状态Desktop 应用/desktop或/appmacOS/Windows 订阅图形界面继续会话远程继续/remote-control、/teleport跨设备继续同一会话7.1 终端交互最完整cd /path/to/your-project claude在提示符下直接输入自然语言或以/开头输入命令见 第 9 章。7.2 一次性命令claude 列出当前目录下的 Markdown 文件并说明各自主题 claude -p 只输出项目使用的框架名称一行即可适合脚本、CI 或快速查询。-p/--print用于非交互输出具体选项以claude --help为准。7.3 VS Code 插件安装打开 VS CodeCtrl Shift X打开扩展市场搜索Claude Code安装 Anthropic 官方扩展安装后可在侧边栏或命令面板Ctrl Shift P中找到 Claude Code 入口配置第三方 API 时在设置 → 扩展 → Claude Code或命令面板搜索 Claude Code 设置中填写配置项说明API Key如sk-xxxxxxxxBase URL / API Endpoint与 settings.json 中ANTHROPIC_BASE_URL一致Model从平台后台复制完整模型 ID成功标志在 VS Code 中打开项目文件夹发送「请用一句话确认已连接」收到正常回复。重要VS Code 插件配置独立于终端~/.claude/settings.json。若终端能用、插件不能用请分别检查插件内的 Key、Base URL、Model。使用 CC Switch 时确认当前 Provider 已生效后再测插件。7.4 IDE 集成与 Desktop在 Claude Code 会话中输入/ide查看当前 IDE 连接状态已订阅且系统为 macOS/Windows 时可用/desktop在 Claude Code Desktop 应用中继续当前会话7.5 远程与会话迁移命令用途/remote-control从其他设备继续本地会话/teleport将 Web 端会话拉入当前终端/resume恢复历史会话8. 终端入门本章目标在真实项目中安全、高效地使用 Claude Code。在项目目录中启动Claude Code 依赖当前工作目录的上下文。请cd到项目根目录再运行cd my-project claude若需额外只读目录会话内可用/add-dir 路径添加配置发现仍以主项目.claude为准。新手推荐测试流程不要第一次在大型生产项目上直接改代码。第一步空目录冒烟测试mkdir claude-smoke-test cd claude-smoke-test claude帮我创建一个简单的 index.html包含标题、输入框和按钮。第二步真实项目 — 先分析后修改cd my-real-project claude先不要修改任何代码。请分析当前项目结构并告诉我主要技术栈和入口文件在哪里。确认分析准确后再逐步授权修改请说明你将如何优化登录页表单布局先给方案不要改文件。方案可以请开始修改改完后告诉我改了哪些文件。常用 CLI 参数参数用途claude --help查看所有 CLI 选项claude --continue继续上一次会话同项目claude --model name指定模型启动claude doctor安装与配置诊断会话内换模型可用/modelCLI 与斜杠命令等价关系以/help为准。权限提示Allow / Deny首次让 Claude 读文件、跑命令、改代码时终端会询问是否允许。这是正常的安全机制Allow允许本次或按规则记住Deny拒绝该操作可在会话内用/permissions管理 allow/ask/deny 规则项目级规则写在.claude/settings.json。警示在未经审核的生产仓库上不要一次性 Allow 所有危险命令。大改动前先用/plan或「只分析不改文件」确认方案。9. 终端技巧与斜杠命令本章目标掌握/命令菜单与 Skill提升日常效率。核心概念概念说明/菜单在输入框输入/弹出当前版本可用的全部命令可继续输入字母过滤内置命令由 Claude Code 实现的固定逻辑如/clear、/modelSkill以SKILL.md定义的指令包你可/skill-name手动调用Claude 也会在相关时自动选用版本差异命令随版本变化以本机/help输出为准命令必须出现在消息开头。/code-review 只看 src/中/code-review后的文字会作为参数传入。按场景常用命令场景代表命令一句话用途会话管理/clear、/compact、/resume清空上下文 / 压缩历史 / 恢复旧会话模型与模式/model、/plan、/effort切换模型 / 先规划再实施 / 调节推理强度项目初始化/init、/memory生成CLAUDE.md/ 编辑记忆文件代码质量/code-review、/diff、/review审查本地 diff / 交互看改动 / 审查 GitHub PRSkills/skills、/reload-skills列出 Skill磁盘新增 Skill 后热加载诊断/doctor、/debug安装检查 / 开启调试日志上下文/context、/cost查看上下文占用 / 用量/cost为/usage别名输入/help可查看当前安装版本的完整列表更新后先/release-notes再/help。Skill 与/的关系bundled Skill 示例/code-review、/batch、/debug、/loop等用法与自定义 Skill 相同输入/skills列出所有 Skill按t按 token 排序Space可隐藏不在菜单中显示的 Skill新增或修改~/.claude/skills/或.claude/skills/后运行/reload-skills无需重启Claude Code快捷键因终端而异快捷键用途Shift Tab切换 Normal / Plan 等模式版本相关Option PmacOS/Alt PWindows不清空输入的情况下切换模型Shift Enter多行输入若无效运行/terminal-setup配置终端在 VS Code、Cursor 内置终端中建议运行一次/terminal-setup以绑定 ShiftEnter。工作流示例新项目第一天/init /memory /mcp大功能开发/plan 实现用户导出 CSV 功能提交前/diff /code-review --fix对话太长/compact 保留与认证模块相关的讨论10. 项目级配置本章目标让 Claude 长期「理解」你的项目规则与权限。CLAUDE.md项目根目录下的项目说明书。Claude 在新会话中会读取用于约定技术栈与目录结构编码规范、测试命令禁止事项如不要改哪些目录生成起点在项目根运行/init会创建 starterCLAUDE.md再用/memory细化。用户级 vs 项目级配置位置作用域典型内容~/.claude/settings.json本机所有项目envAPI Key、个人默认权限.claude/settings.json当前仓库项目 permissions、hooks、团队 env~/.claude/skills/全局 Skill个人常用工作流.claude/skills/当前仓库项目专属 Skill可随 Git 共享项目级 permissions 示例仅示意{ permissions: { allow: [Read(src/**), Edit(src/**)], deny: [Edit(.env*)] } }具体 schema 以官方 Settings 文档为准。.claude 目录结构常见my-project/ ├── CLAUDE.md └── .claude/ ├── settings.json └── skills/ └── my-team-skill/ └── SKILL.md11. Skills 自定义本章目标创建可复用的/my-skill工作流。什么是 SkillSkill 是一个文件夹 SKILL.md文件内含告诉 Claude如何完成某类任务的说明。与内置/code-review类似你可以手动输入/my-skill调用让 Claude 在相关场景下自动加载除非设置了disable-model-invocation: true官方说明Extend Claude with skills - Claude Code Docs存放位置路径作用域~/.claude/skills/skill-name/SKILL.md本机所有项目.claude/skills/skill-name/SKILL.md仅当前仓库可提交 Git文件夹名建议小写 连字符如release-checklist。最小示例创建~/.claude/skills/hello-skill/SKILL.md--- name: hello-skill description: 用中文打个招呼并列出当前 git 分支 --- 当用户调用此 Skill 时 1. 用中文简短问候 2. 运行 git branch --show-current 并告知当前分支 3. 不要修改任何文件在 Claude Code 中/reload-skills /hello-skill常用 frontmatter字段说明nameSkill 名称对应/namedescription描述Claude 据此判断是否自动 invokedisable-model-invocation: true仅用户可手动调用如 deploy、commitallowed-tools限制 Skill 激活时可用的工具排错 checklistSkill 未出现在/菜单时路径是否在skills/下且文件名为SKILL.md文件夹名是否与/命令名一致小写、连字符是否运行了/reload-skills运行/context查看是否有 Skill 被排除描述过长等12. 常见问题 FAQ本章目标按现象快速定位认证、配置与使用问题。以下每题结构现象 → 原因 → 操作清单 → 仍不行时401 Unauthorized现象请求失败提示未授权。原因API Key 错误、不完整、含空格、已删除或写入了错误配置项。操作清单在 CC Switch 或~/.claude/settings.json中确认ANTHROPIC_AUTH_TOKEN或插件中的 API Key重新从平台后台完整复制Key粘贴后检查首尾无空格保存配置关闭 Claude Code重开终端再试若 Key 曾泄露在平台删除并新建仍不行运行/doctor和/debug 401 问题检查是否同时存在官方/login与 env Token 冲突。404 或接口路径错误现象连接失败、404、path not found。原因ANTHROPIC_BASE_URL填错多/少/v1、协议错误或域名拼写错误。操作清单对照 Provider 文档确认 Base URL 格式CC Switch 或 settings.json 中修正后切换/保存 Provider新开终端测试一句话回复仍不行用 curl 或平台提供的测试工具验证 Key URL 是否在本机可达。model not found现象提示找不到模型。原因模型 ID 与平台不一致账号无该模型权限。操作清单登录 API 平台从模型列表复制完整 ID不要猜claude-sonnet简写在 CC Switch Provider 或 VS Code 插件 Model 字段中粘贴确认账户余额与模型权限配置不生效现象改了 settings.json 但行为不变。原因路径错误、JSON 语法错误、未重启、或被 CC Switch 覆盖。操作清单确认路径~/.claude/settings.jsonWindows 见 第 6 章用 JSON 校验器检查逗号、引号关闭所有claude会话重开终端若使用 CC Switch在应用中确认当前 Provider并避免与手改文件冲突终端能用VS Code 插件不能用现象终端claude正常插件无响应或报错。原因插件使用独立配置未读取终端 settings.json。操作清单VS Code 设置中单独填写 API Key、Base URL、Model保存后重载窗口Developer: Reload Window在插件中发送一句话测试CC Switch 切换 Provider 无效现象已切换 ProviderClaude Code 仍连旧服务。操作清单确认 CC Switch 中该 Provider 为当前生效新开终端运行claudeClaude Code 多数情况支持热切换检查共享配置是否写入成功找不到某个斜杠命令现象文档里有/xxx本机/help没有。原因Claude Code 版本过旧或该命令仅特定计划/平台可用。操作清单npm update -g anthropic-ai/claude-code会话内/release-notes→/help请求很慢或超时现象简单问题也等待很久。原因大型仓库上下文过多、网络延迟、模型繁忙。操作清单先用小目录冒烟测试排除配置问题会话内/compact压缩历史用/context查看上下文占用复杂任务改用/plan分步执行余额不足现象平台返回额度不足。操作清单登录 API 平台查看余额与调用记录新手先用小任务验证避免一上来分析超大 monorepo。13. 从入门到精通学习路径本章目标按阶段系统提升避免一次啃完所有高级功能。Level 1 — 入门第 1 天[ ] 安装 Claude Codeclaude --version与/doctor通过[ ] 完成一种认证方式/login或 CC Switch / settings.json[ ] 空目录生成简单 HTML/clear开始新会话[ ] 阅读 第 8 章「先分析后修改」流程Level 2 — 日常第 1 周[ ] 在真实仓库中只分析、不改代码验证技术栈判断正确[ ] 大改动前使用/plan[ ] 提交前/diff/code-review[ ] 配置项目CLAUDE.md/init/memoryLevel 3 — 进阶第 24 周[ ] CC Switch 配置 2 个以上 Provider 并熟练切换[ ] 编写 1 个个人 Skill如发布检查清单/reload-skills验证[ ] 在项目.claude/settings.json中设置 permissions[ ] 尝试/mcp连接一个 MCP 服务器Level 4 — 精通[ ]/batch或 subagent 并行处理大范围重构[ ] 团队共享.claude/skills/与 CLAUDE.md 规范[ ] 配置 Hooks 自动化如保存后 lint[ ]/insights回顾使用习惯并优化工作流14. 参考链接资源链接Claude Code 官方文档Overview - Claude Code Docs设置SettingsClaude Code settings - Claude Code Docs环境变量Environment variables - Claude Code Docs命令参考Commands - Claude Code DocsSkills 扩展Extend Claude with skills - Claude Code DocsCC Switch 官网中文文档CC Switch 官方网站 - AI 编程 CLI 统一管理工具CC Switch GitHubhttps://github.com/farion1231/cc-switchCSDN 参考国内 API 配置向Claude Code 国内使用教程终端和 VS Code 插件配置完整流程-CSDN博客