Claude Code 安装使用指南（6.26 最新版）：国内用户专属教程 + TaoToken 配置-育师

1. 为什么国内开发者装完 Claude Code 总是卡在第一步

Claude Code 是 Anthropic 推出的终端级 AI 编程助手，它和网页版聊天最大的区别在于：它能直接读写你项目里的文件、执行终端命令、跑 Git 操作，相当于把一个能动手的结对程序员塞进了命令行。适合谁？适合已经会用 Node.js 生态、日常在终端里干活的后端、全栈和运维同学，也适合想从「复制粘贴问 AI」升级到「让 AI 直接改代码」的前端。

但国内用户从零装它，通常会连续踩三个坑。第一个坑是 Node.js 版本不对，Claude Code 要求 Node 18 以上，很多人机器上还是 16，npm 装到一半报 engine 不匹配。第二个坑是装完之后启动卡在 onboarding 界面，因为默认引导流程要连官方服务，网络不通就一直转圈。第三个坑是配置散落在settings.json、环境变量、.claude.json好几个地方，改错一个就 401 或者 fetch failed。

这篇教程按「先装环境 → 再装 Claude Code → 用 CC-Switch 管多套配置 → 接入 TaoToken 统一通道 → curl 验证 → 排错」的顺序走一遍，Windows 和 macOS 都覆盖。所有配置骨架都能直接复制，改掉 Key 就能用。我试过在一台全新的 Windows 11 和一台 macOS 14 上各跑一遍，全程大概 15 分钟。

2. 前置准备：Node.js、npm 镜像与 TaoToken 通道

2.1 装 Node.js 18+ 并验证

Windows 直接去 Node.js 官网下 LTS 安装包，一路 Next。macOS 建议用 Homebrew：

brew install node@20 node --version npm --version

Linux（Debian/Ubuntu 系）：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash - sudo apt-get install -y nodejs node --version

只要node --version显示 v18.x 或更高就行。低于 18 的话，Claude Code 的 npm 包会直接拒绝安装。

2.2 换国内 npm 镜像

国内直连 npm 官方源装全局包经常超时，先换镜像：

npm config set registry https://registry.npmmirror.com npm config get registry

第二条命令应该回显https://registry.npmmirror.com，说明生效了。

2.3 TaoToken 是什么、为什么需要它

TaoToken 是一个面向国内开发者的统一 API 通道，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。它的作用是：你不需要单独去每个模型厂商开账号、绑卡、记多套 Key，而是在 TaoToken 后台生成一个统一 Key，把 Claude Code 的ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址 https://taotoken.net/api ，就能跑通模型调用。

对 Claude Code 来说，它只认ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL这两个环境变量（或写进 settings.json 的 env 段）。TaoToken 提供的正是这两个值。你可以在控制台创建 Key：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，具体 Key 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。

注意：TaoToken 是合规的 API 聚合通道，不是所谓「中转站」的灰色玩法。你拿到的 Key 就是正常调用凭证，配置方式和官方一致。

3. 安装 Claude Code 并写可复制的 settings.json

3.1 安装 Claude Code

Windows 用管理员 PowerShell：

npm install -g @anthropic-ai/claude-code claude --version

macOS / Linux：

npm install -g @anthropic-ai/claude-code claude --version

如果claude命令找不到，说明 npm 全局 bin 目录没进 PATH。查一下路径：

npm config get prefix

Windows 一般是C:\Users\你的用户名\AppData\Roaming\npm，把这个路径加进系统环境变量 Path，重启终端即可。

3.2 跳过 onboarding 卡死

首次启动前，先写.claude.json，否则会卡在初始化界面。

Windows 路径C:\Users\你的用户名\.claude.json，macOS/Linux 路径~/.claude.json：

{ "hasCompletedOnboarding": true, "autoUpdaterStatus": "disabled" }

autoUpdaterStatus设为 disabled 可以避免它启动时尝试自动更新导致超时。

3.3 settings.json 骨架（核心）

这是 Claude Code 读取配置的主文件。Windows 在C:\Users\你的用户名\.claude\settings.json，macOS/Linux 在~/.claude/settings.json：

{ "env": { "ANTHROPIC_API_KEY": "sk-你的TaoToken密钥", "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "API_TIMEOUT_MS": "3000000", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1" }, "model": "claude-sonnet-4-6", "permissions": { "allow": [ "Bash(*)", "Edit", "Write", "Read", "Glob", "Grep", "WebFetch(*)", "WebSearch(*)", "NotebookEdit", "Agent" ] } }

几个参数说明：

参数	作用	建议值
ANTHROPIC_API_KEY	调用凭证	TaoToken 控制台生成的 Key
ANTHROPIC_BASE_URL	API 通道地址	https://taotoken.net/api
API_TIMEOUT_MS	单次请求超时	3000000（50 分钟）
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	关闭非必要外联	1
model	默认模型	按 TaoToken 支持的型号填

3.4 用环境变量兜底（可选）

如果你不想写文件，也可以直接设环境变量。Windows PowerShell（管理员）：

[System.Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://taotoken.net/api', 'User') [System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-你的TaoToken密钥', 'User') [System.Environment]::SetEnvironmentVariable('CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC', '1', 'User')

设完重启 PowerShell。macOS/Linux 写进~/.zshrc或~/.bashrc：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的TaoToken密钥" export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

然后source ~/.zshrc。

4. 用 CC-Switch 管理多套配置

4.1 CC-Switch 解决什么问题

当你同时要切官方模型、TaoToken 通道、其他厂商时，手动改 settings.json 很容易改乱。CC-Switch 是个图形化配置切换器，点一下就能换一套 env，不用手改文件。

4.2 安装

macOS：

brew tap farion1231/ccswitch brew install --cask cc-switch

Windows 去 GitHub Releases 下CC-Switch-*-Windows.msi，双击一路 Next。

4.3 配置 TaoToken 通道

打开 CC-Switch，点右上角「+」新建配置。选「自定义配置」，填：

名称：TaoToken
API Key：你的 TaoToken Key
Base URL：https://taotoken.net/api

保存后点「启用」。CC-Switch 会自动把对应值写进 Claude Code 的配置文件。之后想切回别的通道，再点另一套配置的「启用」即可。

提示：CC-Switch 只是帮你管理配置文件，实际调用还是走你填的 Base URL。所以填 TaoToken 的地址，流量就走 TaoToken。

5. 验证通道连通：一条 curl 命令

配置完别急着启动 Claude Code，先用 curl 确认通道通。这一步能提前暴露 Key 错误、地址错误、网络问题。

curl -X POST 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-6", "max_tokens": 64, "messages": [{"role": "user", "content": "ping"}] }'

成功的话会返回一段 JSON，里面有content字段和模型回复。如果返回 401，说明 Key 不对；返回 404，检查 Base URL 是不是多了或少了/v1；连接超时，检查本机网络。

确认 curl 通了，再启动 Claude Code：

cd 你的项目目录 claude

首次会问是否信任该文件夹，选 Yes。然后就能在终端里用自然语言让它改代码了。想先单独验证模型对话是否正常，可以走模型对话入口：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。

6. 本篇常见错排查

Q1：claude命令找不到。npm 全局 bin 没进 PATH。用npm config get prefix查路径，加进系统环境变量，重启终端。

Q2：启动卡在 onboarding。.claude.json没写hasCompletedOnboarding: true，或者写错了位置。确认文件在用户主目录下。

Q3：401 Invalid API key。Key 前后有空格、引号，或者 Key 已失效。去 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 重新生成一个，粘贴时注意别带多余字符。

Q4：fetch failed。多半是 Base URL 写错或网络抖动。先用第 5 节的 curl 命令单独测通道，排除是 Claude Code 本身的问题还是通道问题。

Q5：Node 版本过低。报 engine 错误就是 Node < 18。macOS 用brew upgrade node，Linux 用 nvm 装 20。

Q6：npm 装包超时。镜像没换。执行npm config set registry https://registry.npmmirror.com后重装。

Q7：显示 offline。Claude Code 用连 Google 判断网络状态，显示 offline 不影响实际调用，忽略即可。

如果你打算长期用 Claude Code 做编码和 Agent 任务，可以了解 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。接入细节和参数说明在接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。Claude Code 相关的专项配置可以参考 ClaudeCodeAnthropic 页面：https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode-anthropic&utm_campaign=rewrite 。

最后留一个实操建议：把settings.json和.claude.json两个文件用 Git 或笔记备份一份。以后换机器、重装系统，直接复制过去改个 Key 就能用，比重新走一遍引导快得多。