1. 为什么第一次装 Claude Code 总卡在环境这一步
Claude Code 是 Anthropic 推出的终端 AI 编程助手，能直接在命令行里读写项目文件、跑测试、改代码，适合习惯用终端干活的开发者。但它不像普通 npm 包那样install完就能跑，前置依赖没配好，后面每一步都会报错。我见过最多的三类翻车：Node.js 版本太低导致claude命令直接闪退、Git 没装导致项目记忆功能失效、npm 全局目录没权限导致安装报 EACCES。
这篇教程面向第一次在本地搭 Claude Code 的人，从 Node.js、Git、npm 三件套开始，一路走到配置文件骨架和一次最小对话验证。全程命令可直接复制，配置文件给完整示例，接入部分用统一 Key/API 通道完成，避免你在多个平台之间反复注册。
你需要准备的东西：一台能联网的电脑（Windows/macOS/Linux 都行）、一个终端、大约 15 分钟。不需要提前懂 Node.js，跟着敲就行。
2. 前置环境：Node.js、Git、npm 一次配到位
2.1 Node.js 选 LTS 版，别追最新
Claude Code 要求 Node.js 18 以上，官方推荐 LTS（长期支持）版本。去 Node.js 官网下载页选标着 LTS 的那个，Windows 下.msi一路下一步即可，macOS 可以用.pkg或 Homebrew。
装完打开终端验证：
node -v npm -v正常会输出类似v20.11.1和10.2.4。如果提示command not found，说明 PATH 没配好，Windows 用户重开一个终端窗口通常就能解决，macOS/Linux 检查一下 shell 配置文件里有没有把 Node 的 bin 目录加进去。
注意：如果你之前用 nvm 装过多个 Node 版本，确认当前
node -v是 18 以上。版本不够时 Claude Code 会在启动阶段就报错，而不是给你友好提示。
2.2 Git 不只是版本控制，Claude Code 依赖它做项目记忆
Git 官网下载对应系统安装包，Windows 安装时保持默认选项即可。装完验证：
git --version输出git version 2.43.0之类就对了。Claude Code 的/init命令会生成CLAUDE.md项目记忆文件，部分功能依赖 Git 仓库上下文，所以这一步别跳过。
2.3 npm 全局安装权限，Windows 和 macOS 处理方式不同
npm 随 Node.js 一起装好了，但全局安装包时可能遇到权限问题。先看全局目录在哪：
npm config get prefixWindows 下如果这个路径在C:\Program Files里，普通用户没写权限。解决办法是改到一个用户目录：
npm config set prefix "C:\Users\你的用户名\npm-global"然后把C:\Users\你的用户名\npm-global加进系统 PATH 环境变量。macOS/Linux 用户如果遇到 EACCES，同样可以改 prefix 到~/.npm-global，或者用 nvm 管理 Node 就天然没这问题。
改完 prefix 后重开终端，跑npm config get prefix确认生效。
3. 安装 Claude Code 并接入 TaoToken 通道
3.1 全局安装与版本验证
环境就绪后，一条命令装 Claude Code：
npm install -g @anthropic-ai/claude-code装完验证：
claude --version出现版本号说明安装成功。如果报EACCES或permission denied，回到 2.3 检查 npm prefix。如果报网络超时，换一个 npm 镜像源再试：
npm config set registry https://registry.npmmirror.com3.2 为什么走统一 Key/API 通道
Claude Code 默认走 Anthropic 官方接口，国内直连经常超时，而且计费方式对个人开发者不太友好。用统一 Key/API 通道的好处是：一个 Key 管多个模型、按量计费透明、接口地址固定不用来回改配置。TaoToken 就是做这件事的，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。
先去控制台创建一个 API Key：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，在 API Keys 页面点创建，复制生成的 Key（形如sk-xxxxxxxx）。Key 只显示一次，存到安全的地方。
3.3 settings.json 与 config.toml 配置骨架
Claude Code 的配置分两层：全局配置放在用户目录，项目级配置放在项目根目录。先建全局配置目录：
mkdir -p ~/.claude然后创建~/.claude/settings.json：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key" }, "model": "claude-sonnet-4-20250514", "permissions": { "allow": ["Read", "Write", "Bash(git *)"], "deny": ["Bash(rm -rf *)"] } }如果你用的工具链支持config.toml格式（部分第三方客户端或代理层会读这个），可以这样写：
[api] base_url = "https://taotoken.net/api" api_key = "sk-你的Key" model = "claude-sonnet-4-20250514" [permissions] allow = ["Read", "Write", "Bash(git *)"] deny = ["Bash(rm -rf *)"]两个文件选一个用就行，不要同时配，否则可能互相覆盖。permissions里allow是白名单，deny是黑名单，建议至少把rm -rf加进 deny，防止 AI 误操作。
注意：
ANTHROPIC_BASE_URL结尾不要带斜杠，写https://taotoken.net/api而不是https://taotoken.net/api/，否则部分版本会拼出双斜杠导致 404。
3.4 模型选择与 Coding Plan
如果你主要做长期编码或 Agent 类任务，可以看看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，按套餐走比按量计费更划算。想先试试模型对话效果，用模型对话入口：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
4. 验证请求：一次最小对话跑通全链路
配置写好后，进一个空目录测试：
mkdir ~/claude-test && cd ~/claude-test claude第一次启动会提示你确认配置，如果 settings.json 写对了，它会直接进入交互界面。输入一句最简单的：
你好，帮我创建一个 hello.py，打印 Hello Claude Code正常的话你会看到它调用 Write 工具创建文件，然后你可以验证：
cat hello.py python hello.py输出Hello Claude Code就说明整条链路通了：终端 → Claude Code → TaoToken API → 模型返回 → 工具执行。
如果卡在Connecting...不动，按Ctrl+C退出，用/doctor命令诊断：
/doctor它会检查 Node 版本、Git、API 连通性、配置文件路径。常见输出和对应处理：
| 报错信息 | 原因 | 处理 |
|---|---|---|
ANTHROPIC_API_KEY not set | 环境变量没读到 | 检查 settings.json 路径和 JSON 格式 |
401 Unauthorized | Key 无效或过期 | 去控制台重新生成 |
ECONNREFUSED | base_url 写错 | 确认是https://taotoken.net/api |
Model not found | 模型名拼错 | 用/model切换可用模型 |
验证通过后，你可以在项目里跑/init生成CLAUDE.md，让 Claude Code 记住项目结构。常用命令速查：/help看帮助、/clear清历史、/compact压缩上下文、/cost看 Token 用量、/review请求代码审查。
5. 本篇常见错误与排障清单
装完之后最容易踩的坑集中在三个地方。第一是 Node 版本，claude --version能出版本号但一进交互就崩，多半是 Node 低于 18，用node -v确认后升级。第二是配置文件位置，Windows 下~/.claude实际是C:\Users\你的用户名\.claude，别建到别的地方去了。第三是 Key 泄露，settings.json 如果提交到 Git 仓库，Key 就暴露了，记得把.claude/加进.gitignore。
还有一个隐蔽问题：如果你之前配过ANTHROPIC_API_KEY系统环境变量，它会覆盖 settings.json 里的值。用echo $ANTHROPIC_API_KEY（Windows 用echo %ANTHROPIC_API_KEY%）检查一下，有的话清掉再重启终端。
权限配置别偷懒。permissions.allow里放常用的只读和 git 命令，deny里放危险操作。Claude Code 执行 Bash 命令前会问你，但配好白名单能减少打断。实测下来，把Bash(git *)加进 allow 之后，日常提交代码顺畅很多。
6. 接下来怎么用：从验证到日常编码
最小对话跑通只是起点。日常使用建议每个项目根目录放一份CLAUDE.md，用/init生成后手动补充项目约定，比如代码风格、测试命令、目录结构说明。这样每次启动 Claude Code 它都能快速进入上下文，不用你重复解释。
需要管理多个 Key 或查看用量，去控制台：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。API Keys 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。如果你用 Claude Code 的 Anthropic 兼容模式，接入文档参考：https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
最后提醒一句：配置文件里的 Key 别硬编码在项目里，用环境变量或全局配置。项目级的.claude/settings.json只放权限和模型偏好，Key 放全局那份。这样换项目不用改配置，也不会误提交。