Claude Code 是 Anthropic 推出的终端 AI 编程助手核心使用方式是命令行但它能做的远不止“帮你在终端里回答问题”。它可以直接读取项目文件、分析代码结构、修改文件、执行命令并且能感知 Git 状态和会话上下文因此在写脚本、修 bug、重构代码、生成项目文档这些场景里比在网页对话框里复制粘贴代码要高效得多。下面的内容会围绕 Claude Code 的安装、VS Code 集成、模型接入、Skill 配置和常见报错排查展开目标是让读者从零开始独立完成工具安装、接入第三方模型、配置自定义 Skill并在遇到报错时能按照明确的排查链路定位问题。实际使用中很多开发者的卡点并不在“会不会输入提示词”而在环境配置。比如claude命令装好后找不到或者按网上的教程在项目里新建了settings.json第三方模型还是接不进去。这些问题大部分不是 Claude Code 本身坏了而是运行入口、配置文件位置和环境变量优先级没有理清。所以这里会先把运行机制讲清楚再一步步给出可复现的配置过程。1. 先理解 Claude Code 的工作方式再动手安装1.1 它解决什么问题Claude Code 解决的核心问题是“AI 编程助手如何进入真实项目上下文”。网页端的 AI 工具一次只能看到你粘贴进去的代码片段无法了解项目的目录结构、依赖关系、Git 变更和运行环境。Claude Code 直接运行在项目根目录启动时会读取当前仓库内容调用模型接口并根据模型返回的指令执行文件修改或终端命令。它把“你复制代码、去对话框提问、再把结果贴回来”这个过程变成了“你在终端里描述需求它直接操作项目”。这里要强调它不是自动在后台乱跑的进程。模型每次需要执行工具操作都会先产生一个计划Claude Code 再在终端里展示出来。用户可以确认、修改或拒绝。这个交互模型很重要因为这是它能够安全应用于真实项目的前提。1.2 CLI、插件和桌面端的关系从软件架构上看Claude Code 的底层是一个命令行工具官方以 npm 包方式发布。VS Code 插件和桌面版都是在 CLI 能力之上做的集成。VS Code 插件会让 CLI 运行在编辑器侧边栏或面板中便于查看代码 diff 和文件树桌面版则提供独立的图形界面。三者读写底层配置时不一定完全相同尤其在使用社区配置工具时常见的问题是把配置写到了其中一个入口的路径而另一个入口启动时读不到。因此在开始安装之前先确认自己主要会从哪个入口使用。如果你想在 VS Code 里用仍然建议先装好 CLI因为插件需要调用本机的claude命令。如果你只用桌面版也需要知道桌面版最终读取的还是同一套用户级配置目录~/.claude。1.3 模型从哪里来Claude Code 本身不生产模型能力。它把本地项目文件、命令输出和提示词一起发送给模型服务模型返回结果再由客户端执行。通常的模型来源有两种Anthropic 官方服务以及兼容 Anthropic Messages API 的第三方模型服务。许多团队没有官方 API 访问条件会通过网关或兼容层接入其他模型供应商比如 DeepSeek、国产模型服务或自建模型推理服务。接入时的核心要求是 API 协议兼容不是随便填一个模型名称就能用。如果模型服务只是提供了 OpenAI 风格的接口而没有 Anthropic Messages API 兼容端点就需要一个协议转换网关。直接把ANTHROPIC_BASE_URL指向一个不支持 Anthropic 协议的地址Claude Code 会发出格式不匹配的请求进而表现为连接失败或响应异常。1.4 常见的误解有一个很大的误解是“只要装好 Claude Code官方模型随便用”。实际上只有登录了有权限的账号或者配置了有效的 API Key请求才能被模型服务接受。另一个误解是“settings.json 写一次就能全局生效”实际上配置有作用域用户目录、项目目录和系统环境变量之间还有优先级关系。后面排查部分会专门处理这个问题。还有一个常见误区是把“模型名”和“模型服务商”混为一谈。比如别人截图里写deepseek-v4-pro你就直接抄到配置里。如果该名称不是当前服务端真正支持的模型 ID就会得到来源不明的报错。正确做法是始终以服务商文档里的模型 ID 为准。2. 安装 Claude Code环境检查、安装命令与卸载2.1 环境要求在安装前先确认系统满足基本条件。Claude Code 官方提供了 macOS、Linux 和 Windows 支持但 Windows 下有几种使用方式直接在 PowerShell 中使用也可以在 WSL 中使用更贴近大多数教程中的终端行为。Node.js 版本要求需要以官方文档为准通常建议 18 或更高版本太低会导致执行时报语法错误。检查项最低要求建议值说明操作系统Windows 10 / macOS / Linux64 位系统Windows 下建议同时准备 WSLNode.js18.x20.x LTS使用node -v确认npm随 Node 安装10.x使用npm -v确认终端支持 UTF-8Git Bash / WSL / PowerShell中文项目路径要留意编码网络能访问模型服务端点稳定网络第三方网关也要能连通2.2 检查 Node.js 和 npm打开终端依次执行node -v npm -v如果系统提示找不到命令说明 Node.js 尚未安装或没有加入 PATH。macOS 上可以通过 Homebrew 安装Windows 可以安装官方安装包Linux 发行版可以用各自的包管理器或 nvm。安装完成后重新打开终端确保 PATH 生效。推荐使用 nvm 管理 Node.js 版本因为 Claude Code 更新频繁Node 版本升级和回退都比较方便。示例命令nvm install 20 nvm use 202.3 全局安装 CLI确认 Node 环境正常后全局安装 Claude Codenpm install -g anthropic-ai/claude-code-g表示全局安装安装后的claude命令会被放到 npm 的全局 bin 目录。安装完成后执行claude --version如果能看到版本号说明 CLI 安装成功。如果提示command not found执行npm config get prefix找到全局目录然后把对应的bin目录加入 PATH。在 Windows PowerShell 中如果执行claude时提示脚本无法运行通常需要调整 PowerShell 执行策略可以在管理员终端中执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser执行后重试即可。这里调整的是当前用户的执行策略目的是允许本机安装的 npm 全局脚本运行不影响系统安全配置。2.4 在项目目录中启动安装好后进入需要处理的项目目录执行cd /path/to/your-project claude首次运行会进入登录或身份认证流程。使用官方订阅账号可以直接登录使用 API Key 时可以通过设置环境变量或在配置文件中写入认证信息不需要走网页登录。启动后 Claude Code 会扫描当前目录如果项目很大第一次生成上下文可能会稍慢。2.5 安装 VS Code 插件在 VS Code 扩展市场搜索“Claude Code for VS Code”安装后重启编辑器。插件通常会自动查找本机claude命令。如果本机没有安装 CLI或者 PATH 里找不到插件会报could not locate the claude cli on path。所以无论你用不用 CLI建议先完成 2.3 的全局安装。2.6 卸载和清理如果不需要使用卸载命令是npm uninstall -g anthropic-ai/claude-code卸载之后建议清理残留的配置和缓存目录。CLI 主要配置在~/.claude项目目录下还可能出现.claude目录。如果这些目录里有自定义 Skill 或 settings.json需要单独备份。删除这些目录后再检查 shell 的 PATH 配置里是否还有指向旧claude路径的内容。这样才能做到“卸载干净”。3. 桌面端、CLI 和 VS Code 插件怎么选3.1 三个入口的差异入口运行方式适合场景注意事项CLI终端直接运行claude日常开发、脚本执行、CI 调试启动快资源占用低适合熟练使用终端的人VS Code 插件编辑器面板中运行查看代码 diff、配合编辑器操作依赖本机 CLI 已经安装桌面版独立图形窗口不想使用终端的人配置路径可能与 CLI 有差异3.2 桌面版和 CLI 的配置差异Claude Code 桌面版虽然提供 GUI但核心能力仍然来自 CLI。桌面版启动时也会读取用户目录下的~/.claude配置但项目路径的感知可能与 CLI 不一样。用户在桌面版里打开一个文件夹该文件夹会被当作当前项目目录。因此如果 CLI 方式下配置好了settings.json但桌面版仍然无法接入模型先检查桌面版打开的项目目录是否正确再看桌面版是否有独立的认证状态。社区常说的“桌面版免登录配置”本质上不是绕过登录而是通过 API Key 方式完成身份认证让启动时不再进入网页登录流程。也就是在配置文件里写入环境变量并在启动时选择 API Key 模式。这个过程与 CLI 的 API Key 配置是一致的。3.3 选型建议日常开发中CLI 是最高效的方式。它可以在任意终端会话中启动不需要打开编辑器适合配合 tmux、远程开发等场景。如果你在做前端或重构需要在编辑器中频繁查看文件VS Code 插件更适合。如果你只希望有一个独立聊天窗口不关心终端输出桌面版可以满足。但要注意多个入口同时连接同一个项目时文件写入可能互相干扰建议同一时间只使用一种方式。4. 模型接入API Key、环境变量与第三方模型4.1 原生模型和第三方模型有什么区别Claude Code 默认请求的是 Anthropic 官方 API。请求需要认证信息并且模型名称必须被服务端支持。第三方模型服务要接入 Claude Code通常需要满足两个条件之一一是服务商实现了 Anthropic Messages API 兼容接口二是存在一个协议转换网关把 Claude Code 发来的请求改写成下游模型服务能识别的格式。如果你只是把ANTHROPIC_MODEL改成某个第三方模型名称但没有把ANTHROPIC_BASE_URL指向兼容服务仍然会请求官方 API自然报错。4.2 设置 API 认证信息最直接的方式是设置环境变量export ANTHROPIC_API_KEYsk-xxxx export ANTHROPIC_BASE_URLhttps://your-gateway.example.com export ANTHROPIC_MODELyour-model-id在 PowerShell 中$env:ANTHROPIC_API_KEYsk-xxxx $env:ANTHROPIC_BASE_URLhttps://your-gateway.example.com $env:ANTHROPIC_MODELyour-model-id设置后在当前终端启动claude它就会使用这些变量。注意环境变量是进程级别的关闭终端后失效。不要把真实 Key 写进代码仓库也不要在公开博客里贴自己的 Key。4.3 使用 settings.json 持久化配置如果希望每次启动都自动使用第三方模型可以在用户级或项目级配置文件中写入环境变量。用户级配置路径是~/.claude/settings.json示例{ env: { ANTHROPIC_BASE_URL: https://your-gateway.example.com, ANTHROPIC_API_KEY: sk-xxxx, ANTHROPIC_MODEL: your-model-id } }项目级配置放在项目根目录的.claude/settings.json只对该项目生效。建议 API Key 放在用户级配置文件并用文件权限控制访问项目级配置只放端点和模型名避免 Key 被提交到 Git。4.4 用 ccswitch 管理多套模型配置
Claude Code 安装配置全攻略：模型接入与报错排查
Claude Code 是 Anthropic 推出的终端 AI 编程助手核心使用方式是命令行但它能做的远不止“帮你在终端里回答问题”。它可以直接读取项目文件、分析代码结构、修改文件、执行命令并且能感知 Git 状态和会话上下文因此在写脚本、修 bug、重构代码、生成项目文档这些场景里比在网页对话框里复制粘贴代码要高效得多。下面的内容会围绕 Claude Code 的安装、VS Code 集成、模型接入、Skill 配置和常见报错排查展开目标是让读者从零开始独立完成工具安装、接入第三方模型、配置自定义 Skill并在遇到报错时能按照明确的排查链路定位问题。实际使用中很多开发者的卡点并不在“会不会输入提示词”而在环境配置。比如claude命令装好后找不到或者按网上的教程在项目里新建了settings.json第三方模型还是接不进去。这些问题大部分不是 Claude Code 本身坏了而是运行入口、配置文件位置和环境变量优先级没有理清。所以这里会先把运行机制讲清楚再一步步给出可复现的配置过程。1. 先理解 Claude Code 的工作方式再动手安装1.1 它解决什么问题Claude Code 解决的核心问题是“AI 编程助手如何进入真实项目上下文”。网页端的 AI 工具一次只能看到你粘贴进去的代码片段无法了解项目的目录结构、依赖关系、Git 变更和运行环境。Claude Code 直接运行在项目根目录启动时会读取当前仓库内容调用模型接口并根据模型返回的指令执行文件修改或终端命令。它把“你复制代码、去对话框提问、再把结果贴回来”这个过程变成了“你在终端里描述需求它直接操作项目”。这里要强调它不是自动在后台乱跑的进程。模型每次需要执行工具操作都会先产生一个计划Claude Code 再在终端里展示出来。用户可以确认、修改或拒绝。这个交互模型很重要因为这是它能够安全应用于真实项目的前提。1.2 CLI、插件和桌面端的关系从软件架构上看Claude Code 的底层是一个命令行工具官方以 npm 包方式发布。VS Code 插件和桌面版都是在 CLI 能力之上做的集成。VS Code 插件会让 CLI 运行在编辑器侧边栏或面板中便于查看代码 diff 和文件树桌面版则提供独立的图形界面。三者读写底层配置时不一定完全相同尤其在使用社区配置工具时常见的问题是把配置写到了其中一个入口的路径而另一个入口启动时读不到。因此在开始安装之前先确认自己主要会从哪个入口使用。如果你想在 VS Code 里用仍然建议先装好 CLI因为插件需要调用本机的claude命令。如果你只用桌面版也需要知道桌面版最终读取的还是同一套用户级配置目录~/.claude。1.3 模型从哪里来Claude Code 本身不生产模型能力。它把本地项目文件、命令输出和提示词一起发送给模型服务模型返回结果再由客户端执行。通常的模型来源有两种Anthropic 官方服务以及兼容 Anthropic Messages API 的第三方模型服务。许多团队没有官方 API 访问条件会通过网关或兼容层接入其他模型供应商比如 DeepSeek、国产模型服务或自建模型推理服务。接入时的核心要求是 API 协议兼容不是随便填一个模型名称就能用。如果模型服务只是提供了 OpenAI 风格的接口而没有 Anthropic Messages API 兼容端点就需要一个协议转换网关。直接把ANTHROPIC_BASE_URL指向一个不支持 Anthropic 协议的地址Claude Code 会发出格式不匹配的请求进而表现为连接失败或响应异常。1.4 常见的误解有一个很大的误解是“只要装好 Claude Code官方模型随便用”。实际上只有登录了有权限的账号或者配置了有效的 API Key请求才能被模型服务接受。另一个误解是“settings.json 写一次就能全局生效”实际上配置有作用域用户目录、项目目录和系统环境变量之间还有优先级关系。后面排查部分会专门处理这个问题。还有一个常见误区是把“模型名”和“模型服务商”混为一谈。比如别人截图里写deepseek-v4-pro你就直接抄到配置里。如果该名称不是当前服务端真正支持的模型 ID就会得到来源不明的报错。正确做法是始终以服务商文档里的模型 ID 为准。2. 安装 Claude Code环境检查、安装命令与卸载2.1 环境要求在安装前先确认系统满足基本条件。Claude Code 官方提供了 macOS、Linux 和 Windows 支持但 Windows 下有几种使用方式直接在 PowerShell 中使用也可以在 WSL 中使用更贴近大多数教程中的终端行为。Node.js 版本要求需要以官方文档为准通常建议 18 或更高版本太低会导致执行时报语法错误。检查项最低要求建议值说明操作系统Windows 10 / macOS / Linux64 位系统Windows 下建议同时准备 WSLNode.js18.x20.x LTS使用node -v确认npm随 Node 安装10.x使用npm -v确认终端支持 UTF-8Git Bash / WSL / PowerShell中文项目路径要留意编码网络能访问模型服务端点稳定网络第三方网关也要能连通2.2 检查 Node.js 和 npm打开终端依次执行node -v npm -v如果系统提示找不到命令说明 Node.js 尚未安装或没有加入 PATH。macOS 上可以通过 Homebrew 安装Windows 可以安装官方安装包Linux 发行版可以用各自的包管理器或 nvm。安装完成后重新打开终端确保 PATH 生效。推荐使用 nvm 管理 Node.js 版本因为 Claude Code 更新频繁Node 版本升级和回退都比较方便。示例命令nvm install 20 nvm use 202.3 全局安装 CLI确认 Node 环境正常后全局安装 Claude Codenpm install -g anthropic-ai/claude-code-g表示全局安装安装后的claude命令会被放到 npm 的全局 bin 目录。安装完成后执行claude --version如果能看到版本号说明 CLI 安装成功。如果提示command not found执行npm config get prefix找到全局目录然后把对应的bin目录加入 PATH。在 Windows PowerShell 中如果执行claude时提示脚本无法运行通常需要调整 PowerShell 执行策略可以在管理员终端中执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser执行后重试即可。这里调整的是当前用户的执行策略目的是允许本机安装的 npm 全局脚本运行不影响系统安全配置。2.4 在项目目录中启动安装好后进入需要处理的项目目录执行cd /path/to/your-project claude首次运行会进入登录或身份认证流程。使用官方订阅账号可以直接登录使用 API Key 时可以通过设置环境变量或在配置文件中写入认证信息不需要走网页登录。启动后 Claude Code 会扫描当前目录如果项目很大第一次生成上下文可能会稍慢。2.5 安装 VS Code 插件在 VS Code 扩展市场搜索“Claude Code for VS Code”安装后重启编辑器。插件通常会自动查找本机claude命令。如果本机没有安装 CLI或者 PATH 里找不到插件会报could not locate the claude cli on path。所以无论你用不用 CLI建议先完成 2.3 的全局安装。2.6 卸载和清理如果不需要使用卸载命令是npm uninstall -g anthropic-ai/claude-code卸载之后建议清理残留的配置和缓存目录。CLI 主要配置在~/.claude项目目录下还可能出现.claude目录。如果这些目录里有自定义 Skill 或 settings.json需要单独备份。删除这些目录后再检查 shell 的 PATH 配置里是否还有指向旧claude路径的内容。这样才能做到“卸载干净”。3. 桌面端、CLI 和 VS Code 插件怎么选3.1 三个入口的差异入口运行方式适合场景注意事项CLI终端直接运行claude日常开发、脚本执行、CI 调试启动快资源占用低适合熟练使用终端的人VS Code 插件编辑器面板中运行查看代码 diff、配合编辑器操作依赖本机 CLI 已经安装桌面版独立图形窗口不想使用终端的人配置路径可能与 CLI 有差异3.2 桌面版和 CLI 的配置差异Claude Code 桌面版虽然提供 GUI但核心能力仍然来自 CLI。桌面版启动时也会读取用户目录下的~/.claude配置但项目路径的感知可能与 CLI 不一样。用户在桌面版里打开一个文件夹该文件夹会被当作当前项目目录。因此如果 CLI 方式下配置好了settings.json但桌面版仍然无法接入模型先检查桌面版打开的项目目录是否正确再看桌面版是否有独立的认证状态。社区常说的“桌面版免登录配置”本质上不是绕过登录而是通过 API Key 方式完成身份认证让启动时不再进入网页登录流程。也就是在配置文件里写入环境变量并在启动时选择 API Key 模式。这个过程与 CLI 的 API Key 配置是一致的。3.3 选型建议日常开发中CLI 是最高效的方式。它可以在任意终端会话中启动不需要打开编辑器适合配合 tmux、远程开发等场景。如果你在做前端或重构需要在编辑器中频繁查看文件VS Code 插件更适合。如果你只希望有一个独立聊天窗口不关心终端输出桌面版可以满足。但要注意多个入口同时连接同一个项目时文件写入可能互相干扰建议同一时间只使用一种方式。4. 模型接入API Key、环境变量与第三方模型4.1 原生模型和第三方模型有什么区别Claude Code 默认请求的是 Anthropic 官方 API。请求需要认证信息并且模型名称必须被服务端支持。第三方模型服务要接入 Claude Code通常需要满足两个条件之一一是服务商实现了 Anthropic Messages API 兼容接口二是存在一个协议转换网关把 Claude Code 发来的请求改写成下游模型服务能识别的格式。如果你只是把ANTHROPIC_MODEL改成某个第三方模型名称但没有把ANTHROPIC_BASE_URL指向兼容服务仍然会请求官方 API自然报错。4.2 设置 API 认证信息最直接的方式是设置环境变量export ANTHROPIC_API_KEYsk-xxxx export ANTHROPIC_BASE_URLhttps://your-gateway.example.com export ANTHROPIC_MODELyour-model-id在 PowerShell 中$env:ANTHROPIC_API_KEYsk-xxxx $env:ANTHROPIC_BASE_URLhttps://your-gateway.example.com $env:ANTHROPIC_MODELyour-model-id设置后在当前终端启动claude它就会使用这些变量。注意环境变量是进程级别的关闭终端后失效。不要把真实 Key 写进代码仓库也不要在公开博客里贴自己的 Key。4.3 使用 settings.json 持久化配置如果希望每次启动都自动使用第三方模型可以在用户级或项目级配置文件中写入环境变量。用户级配置路径是~/.claude/settings.json示例{ env: { ANTHROPIC_BASE_URL: https://your-gateway.example.com, ANTHROPIC_API_KEY: sk-xxxx, ANTHROPIC_MODEL: your-model-id } }项目级配置放在项目根目录的.claude/settings.json只对该项目生效。建议 API Key 放在用户级配置文件并用文件权限控制访问项目级配置只放端点和模型名避免 Key 被提交到 Git。4.4 用 ccswitch 管理多套模型配置
