1. 从零跑通 Claude CodeNode.js 环境与 claude -v 验证的完整安装链路Claude Code 是 Anthropic 官方推出的命令行编程助手它不是一个网页聊天窗口而是直接跑在你终端里的 AI 编程搭档。你可以在项目根目录敲一句自然语言它就去读文件、改代码、跑测试、提交 git整个过程不用离开命令行。对于第一次接触它的开发者来说最劝退的往往不是怎么用而是第一步装不上Node.js 版本不对、npm 全局目录没权限、装完敲claude -v报 command not found或者卡在登录环节连不上服务。这篇教程就聚焦 Windows 和 macOS 两条链路把 Node.js 与 npm 环境准备、全局安装、claude -v版本校验以及通过ANTHROPIC_BASE_URL指向 TaoToken 统一 Key/API 通道完成首次对话一步步拆开讲清楚。适合谁适合已经会一点命令行、想给自己的开发流加一个 AI 搭档但还没成功跑通第一个任务的开发者。目标很明确10 分钟内确认安装成功并跑通第一个真实任务。先说清楚 Claude Code 能做什么避免你装完不知道拿它干嘛。它最典型的用法有三类一是代码理解比如你接手一个陌生仓库直接问它「这个项目的入口在哪、鉴权逻辑怎么走的」它会自己 grep、读文件再回答二是代码修改比如「把 utils 里的日期格式化函数改成 dayjs 实现并更新所有调用点」它会定位、改、再告诉你改了哪些文件三是任务执行比如「跑一遍测试把失败的用例修到通过」它会执行命令、看报错、迭代修改。这三类都建立在同一个前提上终端里能正常调用到模型服务。所以安装链路的核心其实是两件事——本地 CLI 装好以及模型通道配通。我试过在干净的 Windows 11 和 macOS 上各走一遍踩过的坑集中在三处Node 版本低于 18 导致安装脚本报 engine 不兼容Windows 上 npm 全局 bin 目录不在 PATH 里装完敲claude提示找不到命令以及环境变量只在一个终端窗口里 export换个窗口就失效。下面按顺序解决。1.1 先确认 Node.js 与 npm 版本是否达标Claude Code 依赖 Node.js 18.0 或更高版本。先开一个终端Windows 用 PowerShell 或 Windows TerminalmacOS 用系统自带 Terminal 或 iTerm2敲node -v npm -v正常会输出类似v20.11.1和10.2.4。如果提示command not found或不是内部或外部命令说明没装 Node.js去 Node.js 官网下载 LTS 版本安装包即可安装时 Windows 记得勾选「Add to PATH」。如果版本低于 18比如v16.x建议直接升级别硬扛后面大概率报错。macOS 用户如果装了 Homebrew一条命令更省事brew install node装完再node -v确认一次。这里有个细节如果你机器上同时有 nvm 或多个 Node 版本确认当前 shell 用的是哪个which nodemacOS或where nodeWindows能告诉你路径。版本对了再往下走能省掉一半排障时间。1.2 全局安装 Claude Code 并处理权限问题环境达标后全局安装命令就一行npm install -g anthropic-ai/claude-codemacOS 或 Linux 上如果报EACCES: permission denied说明 npm 全局目录没写权限。不要习惯性加sudo那会把文件属主搞乱后续升级更麻烦。更稳的做法是给当前用户配一个全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后把~/.npm-global/bin加进 PATH。以 zsh 为例编辑~/.zshrc追加export PATH$HOME/.npm-global/bin:$PATH保存后source ~/.zshrc生效再重新执行安装命令。Windows 上一般不会遇到权限问题但可能遇到全局 bin 不在 PATH。用npm config get prefix看全局目录通常是C:\Users\你的用户名\AppData\Roaming\npm把这个路径加进系统环境变量 Path 即可。加完记得重开终端环境变量不会在已开的窗口里自动刷新。1.3 用 claude -v 做第一次版本校验安装完成后第一件事不是急着用而是验证命令是否真的可用claude -v如果输出类似1.x.x (Claude Code)的版本号恭喜CLI 本体装好了。如果提示claude: command not found回到上一步检查 PATH如果提示版本号但后面接一堆报错多半是 Node 版本问题回 1.1 确认。这一步的意义在于把「安装」和「配置」两件事分开。很多人装完直接跑claude进交互界面结果卡在登录或连接报错分不清是装坏了还是没配通道。先让claude -v干净地输出你就有了一个确定的基线。2. TaoToken 前置准备拿到统一 Key 与 API 通道地址CLI 装好只是有了壳真正让它干活的是背后的模型服务。Claude Code 默认走 Anthropic 官方通道需要账号和网络条件。对国内开发者更顺手的做法是通过 TaoToken 的统一 Key/API 通道接入把ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址再用一个 Key 完成认证。这样你不用折腾账号体系配置一次就能在终端里稳定调用。TaoToken 在这里扮演的角色是「统一入口」你拿一个 Key配一个 Base URLClaude Code 就把它当成模型服务端点来请求。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注意这两个别混Base URL 填的是 API 那个不带多余路径。2.1 注册并创建 API Key打开官网完成注册登录后进入控制台。在控制台里找到 API Keys 页面deep linkhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-installutm_campaignrewrite 点创建新 Key。生成的 Key 通常以sk-开头复制下来先存到安全的地方页面刷新后一般不再完整显示。这里提醒一句Key 等同于你的调用凭证别提交到 git 仓库别贴到公开聊天里。本地配置建议放环境变量或独立的配置文件不要硬编码进项目源码。2.2 确认 Base URL 与模型 IDClaude Code 走的是 Anthropic 兼容协议所以配置项是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个。Base URL 填https://taotoken.net/api注意结尾不要多加/v1之类Claude Code 会自己拼接路径。模型 ID 方面Claude Code 默认会请求 Claude 系列模型你不需要在环境变量里额外指定除非你想换别的模型那可以在配置里显式写 Model ID。如果你用的是 Cline、CC Switch 这类工具配置三件套是固定的Base URL、API Key、Model ID。三者缺一不可尤其 Model ID 写错会直接报模型不存在。Claude Code 本身对模型有默认值所以最简配置只需要前两个。2.3 理解环境变量在 Claude Code 里的作用Claude Code 启动时会读取几个关键环境变量ANTHROPIC_BASE_URL决定请求发往哪里ANTHROPIC_AUTH_TOKEN决定用什么凭证。两者都配好它就不会去走默认的官方通道而是直接请求你指定的地址。这也是为什么配置完要「重启 claude」——环境变量是在进程启动时读取的已经开着的会话不会自动感知新变量。理解这一点后面遇到「配了但没生效」就有排查方向了先确认变量在当前 shell 里echo得出来再确认是不是在同一个窗口里启动的 claude。3. 可复制配置环境变量与 settings 片段这一节给你可以直接抄的配置。分 macOS/Linux 和 Windows 两套再补一个 Claude Code 的 settings 文件写法方便你按习惯选。3.1 macOS / Linux 环境变量配置如果你用 zshmacOS 默认编辑~/.zshrc用 bash 就编辑~/.bashrc。追加以下内容export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的实际Key保存后执行source ~/.zshrc或对应文件让配置生效。验证一下echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_AUTH_TOKEN两条都能正确输出说明变量已进当前 shell。注意ANTHROPIC_AUTH_TOKEN的值要替换成你自己的 Key别把示例里的占位符原样抄进去。3.2 Windows 环境变量配置PowerShell 里临时设置只对当前窗口有效$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_AUTH_TOKENsk-你的实际Key想永久生效用系统「环境变量」设置界面新建两个用户变量或者用命令行setx ANTHROPIC_BASE_URL https://taotoken.net/api setx ANTHROPIC_AUTH_TOKEN sk-你的实际Keysetx写入后需要重开终端才生效。这也是很多人「明明设了却没反应」的原因——旧窗口读的还是旧环境。3.3 用 settings.json 固化配置可选除了环境变量Claude Code 也支持通过 settings 文件配置。在用户目录下创建~/.claude/settings.jsonWindows 是C:\Users\你的用户名\.claude\settings.json写入{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的实际Key } }这种写法的好处是配置跟着 Claude Code 走不依赖 shell 的启动文件换终端也不丢。缺点是 Key 明文存在文件里注意别把这个文件同步到公开仓库。两种方式选一种即可别同时配导致互相覆盖排查起来更乱。配置完成后关掉所有 claude 进程重新开一个终端再启动。4. 验证请求跑通第一次对话与第一个任务配置到位后进入验证环节。这一步要看到真实的模型返回才算真正跑通。4.1 启动 Claude Code 并确认连接在任意项目目录下敲claude首次启动它会做一些初始化然后进入交互界面。如果配置正确你会看到欢迎信息和输入提示符。此时随便问一句用一句话解释这个目录大概是做什么的它会读取当前目录的文件结构再回答。如果它能基于你的实际文件给出回答说明请求已经打到 TaoToken 通道并正常返回了。这一步成功安装链路就通了。4.2 用非交互模式做一次快速验证不想进交互界面也可以用一次性命令验证claude -p 输出当前目录下所有文件名-p是 print 模式执行完直接输出结果退出。这种方式适合脚本化验证也方便你确认环境变量在非交互场景下同样生效。如果这条命令能返回文件列表说明 CLI、环境变量、模型通道三者都正常。4.3 跑一个真实小任务验证通过后试一个稍微真实的任务感受一下工作流。比如在一个 git 仓库里claude -p 看一下 git status告诉我有哪些未提交的改动用中文总结它会执行git status、读取输出、再用中文归纳给你。这就是 Claude Code 和普通聊天工具的区别——它能自己调工具、看真实状态。到这一步你已经完成了从安装到首次任务的全链路。5. 本篇常见错排查401、local proxy failed 与 reading choices装和配的过程中报错基本集中在几个固定位置。下面按真实报错对照排查。5.1 401 认证失败报错长这样401 Unauthorized或authentication_error。原因通常是ANTHROPIC_AUTH_TOKEN没配、配错或者 Key 已失效。排查顺序先echo $ANTHROPIC_AUTH_TOKEN确认变量在当前 shell 有值再确认 Key 没有多余空格或换行复制时容易带上最后去控制台确认这个 Key 还在有效状态。如果用的是 settings.json检查 JSON 格式有没有写错比如少了逗号或引号格式错误会导致整个配置被忽略。5.2 local proxy failed 连接失败报错类似local proxy failed或connection refused。这类多半是 Base URL 写错或者本机网络到目标地址不通。先确认ANTHROPIC_BASE_URL是https://taotoken.net/api没有多余路径、没有拼写错误。然后确认当前网络能正常访问该地址。注意别把 Base URL 和官网地址搞混官网是给人看的页面API 才是给程序请求的端点。5.3 reading choices 解析异常报错里出现reading choices或类似字段读取失败通常是返回体格式和客户端预期不一致。常见诱因是 Base URL 指向了不兼容的端点或者中间被别的服务改写了响应。确认你用的是 Anthropic 兼容通道Base URL 填的是 API 地址。如果之前配过别的中转地址先清掉旧变量再配新的避免多个来源冲突。5.4 OAuth 登录卡住如果你没配环境变量直接启动 claude它会走 OAuth 登录流程可能卡在浏览器跳转或回调。既然我们走的是 Key 通道就不需要走 OAuth。确认ANTHROPIC_AUTH_TOKEN已配置Claude Code 检测到 Token 后会跳过登录流程。如果它仍然弹登录说明变量没被读到回 3.1 或 3.2 检查配置是否在当前 shell 生效。5.5 命令找不到与版本不兼容claude: command not found回 1.2 检查 PATHengine unsupported或安装时报 Node 版本错误回 1.1 升级 Node 到 18 以上。这两个是最基础的先解决它们再谈配置。6. 配好之后把 Claude Code 用进日常开发流安装只是起点。跑通之后你可以把它嵌进日常流程接手新仓库先让它梳理结构改需求前让它定位相关文件提交前让它 review diff。想长期用于编码和 Agent 类任务可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-installutm_campaignrewrite 想先在对话里试模型效果用模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-installutm_campaignrewrite Key 管理和新建在 API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-installutm_campaignrewrite 接入细节看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-installutm_campaignrewrite 。如果你用 Claude Code 的 Anthropic 兼容模式参考 ClaudeCodeAnthropic 说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-installutm_campaignrewrite 。一个实用技巧把常用的一次性任务写成claude -p ...的 shell 别名或脚本比如「总结今天的 git log」比每次进交互界面更快。另一个是给不同项目配不同的 settings把项目相关的约定写进配置减少每次重复交代背景。装好、配通、用顺这三步走完Claude Code 才算真正成为你的编程搭档。