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 Codenpm 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。先去控制台创建一个 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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 Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 按套餐走比按量计费更划算。想先试试模型对话效果用模型对话入口https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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...不动按CtrlC退出用/doctor命令诊断/doctor它会检查 Node 版本、Git、API 连通性、配置文件路径。常见输出和对应处理报错信息原因处理ANTHROPIC_API_KEY not set环境变量没读到检查 settings.json 路径和 JSON 格式401 UnauthorizedKey 无效或过期去控制台重新生成ECONNREFUSEDbase_url 写错确认是https://taotoken.net/apiModel 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_KEYWindows 用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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你用 Claude Code 的 Anthropic 兼容模式接入文档参考https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后提醒一句配置文件里的 Key 别硬编码在项目里用环境变量或全局配置。项目级的.claude/settings.json只放权限和模型偏好Key 放全局那份。这样换项目不用改配置也不会误提交。