1. 为什么第一次装 Claude Code 总卡在环境这一步Claude Code 是 Anthropic 推出的终端 AI 编程工具能直接在命令行里读写项目文件、跑测试、改代码。它适合已经习惯终端操作的开发者尤其是想让 AI 帮忙处理多文件重构、批量改配置、写脚本这类活儿的人。但它不像普通 npm 包那样装完就能用第一次上手最容易卡在三个地方Node.js 版本不对、npm 全局安装权限报错、以及启动后连不上服务。我见过太多人在这三步里反复折腾。有人 node -v 显示 v14装完 claude 直接报语法错误有人在 Windows 的 system32 目录下跑 claude被提示信任文件夹时手一抖点了 yes结果 AI 差点去改系统文件还有人装完启动屏幕上跳出Unable to connect to Anthropic services然后就不知道下一步该干嘛了。这篇教程就按真实操作顺序走一遍先把 Node.js 和 npm 环境弄干净再装 Claude Code 本体然后用 cc-switch 这个配置管理工具把 API Key 管起来最后用 taotoken.net 的统一 Key 通道发一次对话请求确认整条链路通了。全程命令可复制配置文件给完整片段报错对照着排查。cc-switch 在这里的角色很关键。它是一款跨平台的 Claude Code 配置切换器你可以把它理解成 AI 编程工具的“遥控器”——不用手动去改.claude.json或者环境变量点几下就能在不同模型服务商之间切换。对于需要同时用多个模型、或者想统一管理 Key 的开发者来说它省掉了大量手改配置的麻烦。下面从环境准备开始一步步来。2. Node.js 与 npm 环境准备版本、镜像与全局安装权限Claude Code 对 Node.js 版本有要求官方建议 18 以上。我实测下来Node 20 LTS 最稳Node 22 也能跑。先去 nodejs.org 下载对应系统的安装包Windows 选.msimacOS 选.pkg装完打开终端验证。node -v npm -v如果输出类似v20.11.1和10.2.4说明基础环境 OK。如果 node 命令找不到检查安装时有没有勾选“Add to PATH”。接下来处理 npm 下载源。默认的registry.npmjs.org在国内访问经常超时装全局包时容易卡住。切换成 npmmirror 镜像npm config set registry https://registry.npmmirror.com npm config get registry第二条命令应该返回https://registry.npmmirror.com/确认生效。然后是全局安装权限问题。Linux 和 macOS 下直接npm install -g可能报EACCES权限错误。两种解法一是用 nvm 管理 Node全局包会装到用户目录下不碰系统目录二是改 npm 全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATHWindows 下如果用管理员 CMD 装全局包一般不会报权限错但要注意别在C:\Windows\system32里操作。装完 Claude Code 后第一次启动会让你选一个工作目录这时候一定要切到自己的项目文件夹比如D:\projects\test-claude别在系统目录里点信任。环境准备好之后装 Claude Code 本体npm install -g anthropic-ai/claude-code claude -vclaude -v能输出版本号就说明安装成功。如果报command not found检查 npm 全局 bin 目录有没有加到 PATH 里。这一步做完Node.js、npm、Claude Code 三件套就齐了。接下来是配置管理也是很多人第一次启动后卡住的地方。3. cc-switch 配置 API Key完整 settings 片段与三件套写法Claude Code 第一次启动会走一个引导流程要求登录 Anthropic 账号。如果你没有官方账号或者想用其他模型服务就会卡在登录页。这时候有两个选择一是手动改.claude.json跳过引导二是用 cc-switch 来管理配置。手动改.claude.json的方式是在用户目录下找到这个文件Windows 是C:\Users\你的用户名\.claude.jsonmacOS/Linux 是~/.claude.json加上{ hasCompletedOnboarding: true }这个字段的作用是标记首次引导已完成下次启动直接进主界面。但光跳过引导还不够你还得告诉 Claude Code 用哪个 API 端点、哪个 Key、哪个模型。这些信息如果全塞在.claude.json里切换服务商时就得反复手改很容易出错。cc-switch 就是来解决这个问题的。去 GitHub 的 releases 页面下载对应系统的安装包Windows 推荐.msi安装版macOS 用.dmgLinux 有.deb和.AppImage。装完之后打开界面里可以添加多个供应商配置。这里以 taotoken.net 的统一 Key 通道为例写一份完整的配置。在 cc-switch 里添加新供应商时需要填三件套Base URL、API Key、Model ID。{ provider: taotoken, baseUrl: https://taotoken.net/api, apiKey: sk-你的taotoken密钥, model: claude-sonnet-4-20250514, settings: { env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的taotoken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } } }如果你习惯直接改 Claude Code 的 settings 文件路径在~/.claude/settings.json内容写成{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的taotoken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }注意 Base URL 这里写的是https://taotoken.net/api不要多加路径后缀。API Key 去 taotoken.net 的 console 里生成模型 ID 按你实际要用的填。cc-switch 的好处是这些配置可以在界面里保存成多个方案点一下就能切换不用每次手改 JSON。配置保存后回到终端启动 claude它就不会再要求登录而是直接读取环境变量里的 Base URL 和 Key。你可以用/model命令查看当前生效的模型确认是不是你配置的那个。这一步的关键是三件套必须写全Base URL 指向 taotoken.net/apiAPI Key 用 taotoken 生成的Model ID 写清楚。少任何一个启动后都会报连接错误。4. 验证请求用一次对话确认环境可用配置写完启动 claude 进到交互界面先别急着让它改代码。用最简单的对话测试一下链路通不通。启动命令claude进去之后输入一句测试你好请用一句话说明你当前使用的模型名称。如果配置正确它会正常回复。如果报错对照下一节的排查表处理。更严谨的验证方式是直接用 curl 打一次 API确认 Key 和端点都没问题curl https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的taotoken密钥 \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [ {role: user, content: 回复 OK 两个字母即可} ] }如果返回 JSON 里content字段有内容说明 Key 和端点都正常。这一步能排除掉 Claude Code 客户端本身的问题把故障范围缩小到配置层。在 Claude Code 里还可以用/model命令确认当前模型/model它会列出当前生效的模型 ID。如果显示的不是你配置的那个说明环境变量没被正确读取检查 settings.json 的路径和 JSON 格式。实测下来只要 Base URL、Key、Model 三件套写对第一次对话基本都能通。如果卡住大概率是下面几种报错之一。5. 常见报错排查401、local proxy failed 与 OAuth 问题这一节按真实报错来对照。你遇到哪个直接找对应条目。报错一401 UnauthorizedAPI Error: 401 - {error:{type:authentication_error,message:invalid x-api-key}}原因通常是 Key 写错、Key 过期、或者 Base URL 和 Key 不匹配。排查步骤先去 taotoken.net 的 console 确认 Key 还在有效期内然后检查 settings.json 里ANTHROPIC_API_KEY的值有没有多余空格或换行。如果 Key 是从网页复制的注意别把前后空白带进去。报错二local proxy failedError: local proxy failed to start这个多半是端口被占用或者 cc-switch 的代理进程没起来。先检查有没有其他程序占了 Claude Code 默认的本地端口关掉冲突进程再试。如果用 cc-switch 切换供应商后出现这个错重启一下 cc-switch让它重新写入配置。报错三reading choices 相关错误TypeError: Cannot read properties of undefined (reading choices)这是响应格式不匹配导致的。常见于 Base URL 写成了 OpenAI 兼容格式的端点但 Claude Code 期望的是 Anthropic 格式的响应。确认 Base URL 是https://taotoken.net/api不要自己加/v1/chat/completions这类后缀。taotoken 的 API 端点已经做了格式适配按文档给的地址写就行。报错四OAuth 登录循环启动后一直跳登录页或者提示OAuth token expired。这是因为.claude.json里的hasCompletedOnboarding没生效或者环境变量没覆盖掉默认的登录逻辑。检查两点一是.claude.json里确实有hasCompletedOnboarding: true二是 settings.json 里的ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY都写对了。两个都确认后重启终端。报错五Unable to connect to Anthropic services这个在原文里也出现过。本质是客户端尝试连默认的 Anthropic 端点失败。如果你已经配了 taotoken 的 Base URL还报这个错说明环境变量没被读取。检查 settings.json 的路径是不是~/.claude/settings.jsonWindows 下是C:\Users\你的用户名\.claude\settings.json。路径不对配置就不生效。排查顺序建议先 curl 测 API 通不通再检查 settings.json 格式最后看 cc-switch 有没有正确写入。三步走完基本能定位到问题。6. 配置完成后怎么用模型切换与长期使用建议环境通了之后日常使用就简单了。在 Claude Code 里用/model切换模型cc-switch 里保存的多个供应商方案可以随时切换。如果你需要长期跑编码任务或者 Agent 流程建议把常用配置固定下来别每次临时改。taotoken.net 的 API Key 可以在 console 里管理生成多个 Key 分配给不同项目方便追踪用量。接入文档里有完整的端点说明和参数列表遇到格式问题先翻文档。对于需要频繁切换模型的场景cc-switch 的方案管理比手改 JSON 高效得多。你可以给每个项目建一个配置方案点一下切换不用记那些环境变量名。最后提醒一点Claude Code 第一次启动时选工作目录一定选自己的项目文件夹别在系统目录里点信任。这个坑我踩过AI 拿到系统目录的写权限后改起文件来是真的不客气。 
长河君 · 2026/10/17 17:25:31 · 阅读 1.2k Claude Code安装教程：用cc-switch管理API Key与Node.js环境
1. 为什么第一次装 Claude Code 总卡在环境这一步Claude Code 是 Anthropic 推出的终端 AI 编程工具能直接在命令行里读写项目文件、跑测试、改代码。它适合已经习惯终端操作的开发者尤其是想让 AI 帮忙处理多文件重构、批量改配置、写脚本这类活儿的人。但它不像普通 npm 包那样装完就能用第一次上手最容易卡在三个地方Node.js 版本不对、npm 全局安装权限报错、以及启动后连不上服务。我见过太多人在这三步里反复折腾。有人 node -v 显示 v14装完 claude 直接报语法错误有人在 Windows 的 system32 目录下跑 claude被提示信任文件夹时手一抖点了 yes结果 AI 差点去改系统文件还有人装完启动屏幕上跳出Unable to connect to Anthropic services然后就不知道下一步该干嘛了。这篇教程就按真实操作顺序走一遍先把 Node.js 和 npm 环境弄干净再装 Claude Code 本体然后用 cc-switch 这个配置管理工具把 API Key 管起来最后用 taotoken.net 的统一 Key 通道发一次对话请求确认整条链路通了。全程命令可复制配置文件给完整片段报错对照着排查。cc-switch 在这里的角色很关键。它是一款跨平台的 Claude Code 配置切换器你可以把它理解成 AI 编程工具的“遥控器”——不用手动去改.claude.json或者环境变量点几下就能在不同模型服务商之间切换。对于需要同时用多个模型、或者想统一管理 Key 的开发者来说它省掉了大量手改配置的麻烦。下面从环境准备开始一步步来。2. Node.js 与 npm 环境准备版本、镜像与全局安装权限Claude Code 对 Node.js 版本有要求官方建议 18 以上。我实测下来Node 20 LTS 最稳Node 22 也能跑。先去 nodejs.org 下载对应系统的安装包Windows 选.msimacOS 选.pkg装完打开终端验证。node -v npm -v如果输出类似v20.11.1和10.2.4说明基础环境 OK。如果 node 命令找不到检查安装时有没有勾选“Add to PATH”。接下来处理 npm 下载源。默认的registry.npmjs.org在国内访问经常超时装全局包时容易卡住。切换成 npmmirror 镜像npm config set registry https://registry.npmmirror.com npm config get registry第二条命令应该返回https://registry.npmmirror.com/确认生效。然后是全局安装权限问题。Linux 和 macOS 下直接npm install -g可能报EACCES权限错误。两种解法一是用 nvm 管理 Node全局包会装到用户目录下不碰系统目录二是改 npm 全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATHWindows 下如果用管理员 CMD 装全局包一般不会报权限错但要注意别在C:\Windows\system32里操作。装完 Claude Code 后第一次启动会让你选一个工作目录这时候一定要切到自己的项目文件夹比如D:\projects\test-claude别在系统目录里点信任。环境准备好之后装 Claude Code 本体npm install -g anthropic-ai/claude-code claude -vclaude -v能输出版本号就说明安装成功。如果报command not found检查 npm 全局 bin 目录有没有加到 PATH 里。这一步做完Node.js、npm、Claude Code 三件套就齐了。接下来是配置管理也是很多人第一次启动后卡住的地方。3. cc-switch 配置 API Key完整 settings 片段与三件套写法Claude Code 第一次启动会走一个引导流程要求登录 Anthropic 账号。如果你没有官方账号或者想用其他模型服务就会卡在登录页。这时候有两个选择一是手动改.claude.json跳过引导二是用 cc-switch 来管理配置。手动改.claude.json的方式是在用户目录下找到这个文件Windows 是C:\Users\你的用户名\.claude.jsonmacOS/Linux 是~/.claude.json加上{ hasCompletedOnboarding: true }这个字段的作用是标记首次引导已完成下次启动直接进主界面。但光跳过引导还不够你还得告诉 Claude Code 用哪个 API 端点、哪个 Key、哪个模型。这些信息如果全塞在.claude.json里切换服务商时就得反复手改很容易出错。cc-switch 就是来解决这个问题的。去 GitHub 的 releases 页面下载对应系统的安装包Windows 推荐.msi安装版macOS 用.dmgLinux 有.deb和.AppImage。装完之后打开界面里可以添加多个供应商配置。这里以 taotoken.net 的统一 Key 通道为例写一份完整的配置。在 cc-switch 里添加新供应商时需要填三件套Base URL、API Key、Model ID。{ provider: taotoken, baseUrl: https://taotoken.net/api, apiKey: sk-你的taotoken密钥, model: claude-sonnet-4-20250514, settings: { env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的taotoken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } } }如果你习惯直接改 Claude Code 的 settings 文件路径在~/.claude/settings.json内容写成{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的taotoken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }注意 Base URL 这里写的是https://taotoken.net/api不要多加路径后缀。API Key 去 taotoken.net 的 console 里生成模型 ID 按你实际要用的填。cc-switch 的好处是这些配置可以在界面里保存成多个方案点一下就能切换不用每次手改 JSON。配置保存后回到终端启动 claude它就不会再要求登录而是直接读取环境变量里的 Base URL 和 Key。你可以用/model命令查看当前生效的模型确认是不是你配置的那个。这一步的关键是三件套必须写全Base URL 指向 taotoken.net/apiAPI Key 用 taotoken 生成的Model ID 写清楚。少任何一个启动后都会报连接错误。4. 验证请求用一次对话确认环境可用配置写完启动 claude 进到交互界面先别急着让它改代码。用最简单的对话测试一下链路通不通。启动命令claude进去之后输入一句测试你好请用一句话说明你当前使用的模型名称。如果配置正确它会正常回复。如果报错对照下一节的排查表处理。更严谨的验证方式是直接用 curl 打一次 API确认 Key 和端点都没问题curl https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的taotoken密钥 \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [ {role: user, content: 回复 OK 两个字母即可} ] }如果返回 JSON 里content字段有内容说明 Key 和端点都正常。这一步能排除掉 Claude Code 客户端本身的问题把故障范围缩小到配置层。在 Claude Code 里还可以用/model命令确认当前模型/model它会列出当前生效的模型 ID。如果显示的不是你配置的那个说明环境变量没被正确读取检查 settings.json 的路径和 JSON 格式。实测下来只要 Base URL、Key、Model 三件套写对第一次对话基本都能通。如果卡住大概率是下面几种报错之一。5. 常见报错排查401、local proxy failed 与 OAuth 问题这一节按真实报错来对照。你遇到哪个直接找对应条目。报错一401 UnauthorizedAPI Error: 401 - {error:{type:authentication_error,message:invalid x-api-key}}原因通常是 Key 写错、Key 过期、或者 Base URL 和 Key 不匹配。排查步骤先去 taotoken.net 的 console 确认 Key 还在有效期内然后检查 settings.json 里ANTHROPIC_API_KEY的值有没有多余空格或换行。如果 Key 是从网页复制的注意别把前后空白带进去。报错二local proxy failedError: local proxy failed to start这个多半是端口被占用或者 cc-switch 的代理进程没起来。先检查有没有其他程序占了 Claude Code 默认的本地端口关掉冲突进程再试。如果用 cc-switch 切换供应商后出现这个错重启一下 cc-switch让它重新写入配置。报错三reading choices 相关错误TypeError: Cannot read properties of undefined (reading choices)这是响应格式不匹配导致的。常见于 Base URL 写成了 OpenAI 兼容格式的端点但 Claude Code 期望的是 Anthropic 格式的响应。确认 Base URL 是https://taotoken.net/api不要自己加/v1/chat/completions这类后缀。taotoken 的 API 端点已经做了格式适配按文档给的地址写就行。报错四OAuth 登录循环启动后一直跳登录页或者提示OAuth token expired。这是因为.claude.json里的hasCompletedOnboarding没生效或者环境变量没覆盖掉默认的登录逻辑。检查两点一是.claude.json里确实有hasCompletedOnboarding: true二是 settings.json 里的ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY都写对了。两个都确认后重启终端。报错五Unable to connect to Anthropic services这个在原文里也出现过。本质是客户端尝试连默认的 Anthropic 端点失败。如果你已经配了 taotoken 的 Base URL还报这个错说明环境变量没被读取。检查 settings.json 的路径是不是~/.claude/settings.jsonWindows 下是C:\Users\你的用户名\.claude\settings.json。路径不对配置就不生效。排查顺序建议先 curl 测 API 通不通再检查 settings.json 格式最后看 cc-switch 有没有正确写入。三步走完基本能定位到问题。6. 配置完成后怎么用模型切换与长期使用建议环境通了之后日常使用就简单了。在 Claude Code 里用/model切换模型cc-switch 里保存的多个供应商方案可以随时切换。如果你需要长期跑编码任务或者 Agent 流程建议把常用配置固定下来别每次临时改。taotoken.net 的 API Key 可以在 console 里管理生成多个 Key 分配给不同项目方便追踪用量。接入文档里有完整的端点说明和参数列表遇到格式问题先翻文档。对于需要频繁切换模型的场景cc-switch 的方案管理比手改 JSON 高效得多。你可以给每个项目建一个配置方案点一下切换不用记那些环境变量名。最后提醒一点Claude Code 第一次启动时选工作目录一定选自己的项目文件夹别在系统目录里点信任。这个坑我踩过AI 拿到系统目录的写权限后改起文件来是真的不客气。