1. Claude Code 本地安装从 npm 报错到终端跑通全流程Claude Code 是 Anthropic 推出的终端 AI 编程助手能直接在命令行里读写项目文件、执行命令、跑测试适合习惯在终端里干活的开发者。它和网页版对话最大的区别是它能真正“动手”改你的代码而不是只给你一段建议。这篇教程聚焦本地安装全流程覆盖 node.js 与 npm 环境准备、API Key 写入 settings.json、首次运行验证每一步都给可复制的命令和配置片段照着做就能在终端完成一次可复现的安装与调用测试。很多人卡住的地方其实不在 Claude Code 本身而在前置环境。npm 全局安装报错、命令找不到、settings.json 路径不对、API Key 写错位置这几个坑我基本都踩过。下面按顺序来先解决环境再装工具最后配 Key 验证。1.1 先确认 node.js 和 npm 是否就绪Claude Code 通过 npm 分发所以第一步是确认 node.js 和 npm 都在。打开终端Windows 用 PowerShell 或 CMDmacOS/Linux 用默认终端运行node -v npm -v正常会输出类似v20.11.0和10.2.4的版本号。如果提示command not found或不是内部或外部命令说明 node.js 没装或没进 PATH。去 node.js 官网下载 LTS 版本安装包安装时勾选“Add to PATH”装完重开终端再验证。node.js 版本建议 18 以上Claude Code 对低版本兼容性不好。如果版本太老用 nvm 切换nvm install 20 nvm use 20macOS 用户如果用 Homebrew也可以brew install node。这一步的目标只有一个node -v和npm -v都能正常输出。1.2 npm 全局安装 Claude Code 及环境变量修复环境就绪后执行全局安装npm install -g anthropic-ai/claude-code如果这一步顺利直接跳到验证。但很多人会遇到权限报错macOS/Linux 的 EACCES或 Windows 下装完claude命令找不到。先查 npm 全局路径npm config get prefix这个命令会输出一个目录比如 Windows 下是C:\Users\你的用户名\AppData\Roaming\npmmacOS 下可能是/usr/local。全局安装的可执行文件就在这个目录的bin子目录里。如果这个路径不在系统 PATH 中claude命令自然找不到。Windows 下把这个路径加进环境变量系统设置 → 环境变量 → 用户变量 Path → 新建 → 粘贴路径 → 保存 → 重开终端。macOS/Linux 下在~/.zshrc或~/.bashrc里加一行export PATH$(npm config get prefix)/bin:$PATH然后source ~/.zshrc生效。装完验证版本claude --version能输出类似1.x.x的版本号就说明安装成功。如果还是找不到重启终端再试PATH 修改需要新会话才生效。2. TaoToken 前置准备拿到 API Key 和 Base URLClaude Code 本身是客户端真正干活的是背后的模型服务。你需要一个兼容 Anthropic 接口的服务地址和对应的 API Key。这里用 TaoToken 作为接入示例它提供 Anthropic 兼容的接口配置方式和官方一致。2.1 注册并创建 API Key打开 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台。在控制台里找到 API Keys 管理页面点创建新 Key。创建时给它起个名字方便区分比如claude-code-local。创建完成后会显示一串以sk-开头的 Key。这串 Key 只显示一次务必立刻复制保存到安全的地方。如果关掉页面忘了复制只能删掉重建。这个 Key 就是后面写进 settings.json 的ANTHROPIC_AUTH_TOKEN。2.2 确认 Base URL 和模型 IDTaoToken 的 API 地址是 https://taotoken.net/api 这是 Anthropic 兼容接口的根地址。在 Claude Code 的配置里ANTHROPIC_BASE_URL填这个值。模型 ID 方面Claude Code 默认会请求 Claude 系列模型。你可以在 TaoToken 的模型列表里确认当前可用的模型名比如claude-opus-4-6这类。配置里通过ANTHROPIC_MODEL指定不指定的话客户端会用默认值但显式写清楚更稳妥。这里有个关键点Base URL 和 Key 必须配套。用 TaoToken 的 Key 就配 TaoToken 的地址不要混用。混用最常见的表现就是 401 认证失败。3. 可复制配置settings.json 完整片段Claude Code 读取用户目录下的.claude/settings.json作为全局配置。Windows 路径是C:\Users\你的用户名\.claude\settings.jsonmacOS/Linux 是~/.claude/settings.json。如果.claude目录不存在手动创建。3.1 创建目录并写入配置先建目录mkdir -p ~/.claudeWindows PowerShell 下New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.claude然后用编辑器打开settings.json写入以下内容。把sk-XXXXXXXXXXXXXXXXXX替换成你在 TaoToken 创建的真实 Key{ env: { ANTHROPIC_AUTH_TOKEN: sk-XXXXXXXXXXXXXXXXXX, ANTHROPIC_BASE_URL: https://taotoken.net/api, API_TIMEOUT_MS: 300000, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 0, ANTHROPIC_MODEL: claude-opus-4-6, CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: 1, DISABLE_PROMPT_CACHING: 1, CLAUDE_CODE_SKIP_BETA_HEADER: 1 }, language: 简体中文 }几个字段说明一下。ANTHROPIC_AUTH_TOKEN是认证令牌就是你的 API Key。ANTHROPIC_BASE_URL指向 TaoToken 的接口地址。API_TIMEOUT_MS设成 300000 毫秒5 分钟避免长任务超时。ANTHROPIC_MODEL指定默认模型。language设成简体中文让交互界面用中文。3.2 配置项对照表字段作用建议值ANTHROPIC_AUTH_TOKENAPI Key 认证你的 sk- 开头 KeyANTHROPIC_BASE_URL接口根地址https://taotoken.net/apiAPI_TIMEOUT_MS请求超时毫秒300000ANTHROPIC_MODEL默认模型 IDclaude-opus-4-6CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC关闭非必要流量0DISABLE_PROMPT_CACHING关闭提示缓存1language界面语言简体中文注意JSON 里不能有注释也不能有多余逗号否则解析失败会导致配置不生效。写完后可以用cat ~/.claude/settings.json检查格式。如果你想把配置放到 D 盘或其他位置节省 C 盘空间可以在目标盘新建文件夹然后在该目录下运行claudeClaude Code 会在当前工作目录初始化项目级配置。全局配置仍在用户目录但项目文件不会占 C 盘。4. 验证请求首次运行与成功结果配置写好后进入一个测试项目目录运行claude第一次启动会做一些初始化可能会问你是否信任当前目录。确认后进入交互界面。如果配置正确你会看到 Claude Code 的欢迎信息和输入提示符。4.1 用一条简单指令验证连通性在交互界面里输入帮我看看当前目录下有哪些文件并解释 package.json 的作用如果模型正常响应会列出文件并给出解释。这说明 Base URL、Key、模型 ID 三者都配对了。如果卡住不动多半是网络或超时问题检查API_TIMEOUT_MS和 Base URL。也可以不进交互模式直接用一次性命令验证claude -p 用一句话说明什么是递归-p参数表示打印模式执行完直接输出结果退出。这个命令适合脚本化测试能快速确认接口通不通。4.2 成功结果的判断标准一次成功的调用会满足这几点命令不报错退出、有模型生成的文本返回、返回内容与提问相关。如果返回的是空内容或报错信息说明配置有问题进入下一节排查。实测下来最容易出问题的是 Key 复制时带了空格或者 Base URL 末尾多了斜杠。这两个细节检查一下能省很多时间。5. 常见报错排查401、local proxy failed、reading choices配置过程中会遇到几类典型报错逐个对照解决。5.1 401 认证失败报错长这样API Error: 401 {error:{message:Invalid API key}}原因通常是 Key 写错、Key 已失效、或者 Key 和 Base URL 不匹配。排查步骤打开settings.json确认ANTHROPIC_AUTH_TOKEN是完整的sk-开头字符串没有多余空格或换行确认ANTHROPIC_BASE_URL是https://taotoken.net/api去 TaoToken 控制台确认这个 Key 还在、额度没用完。如果 Key 泄露过删掉重建一个。5.2 local proxy failed 或连接超时报错类似Error: connect ETIMEDOUT local proxy failed这通常是网络层问题。先确认本机网络能访问 TaoToken 的接口用 curl 测一下curl -I https://taotoken.net/api如果返回 HTTP 状态码说明网络通。如果超时检查本地网络设置。注意不要使用任何非正规的网络工具保持直连即可。另外API_TIMEOUT_MS设太小也会导致长任务被中断保持 300000。5.3 reading choices 或响应解析错误报错类似Error: reading choices of undefined这类错误说明客户端收到了非预期的响应格式。常见原因是 Base URL 指向了不兼容的接口或者模型 ID 写错导致服务端返回错误结构。确认ANTHROPIC_BASE_URL是 Anthropic 兼容地址ANTHROPIC_MODEL是服务端真实存在的模型名。改完配置后重启claude让新配置生效。5.4 OAuth 相关报错如果看到提示要求 OAuth 登录或 token 过期OAuth token expired, please re-authenticate说明客户端在尝试走官方 OAuth 流程而不是用你配置的 Key。检查settings.json里ANTHROPIC_AUTH_TOKEN是否正确写入以及有没有其他环境变量覆盖了配置。有时候系统里存在ANTHROPIC_API_KEY环境变量会干扰可以临时清掉unset ANTHROPIC_API_KEYWindows 下用set ANTHROPIC_API_KEY清除。清完重开终端再运行。提示每次改完 settings.json 都要重启 claude 进程配置不会热加载。6. 继续深入模型对话、接入文档与长期编码方案装好只是开始接下来怎么用起来更顺手。如果你只是想验证模型能不能通可以直接用模型对话页面快速测试不用每次都开终端。地址是 https://taotoken.net/api 登录后就能对话。需要查接口细节、参数说明、错误码含义看接入文档https://taotoken.net/api 。文档里有完整的请求示例和字段解释配置遇到不确定的地方对照一下。如果你是长期用 Claude Code 写代码、跑 Agent 任务建议了解 Coding Plan它针对高频编码场景做了额度优化比按量调用更划算。入口在控制台的 Coding Plan 页面。API Key 管理和新建都在控制台的 API Keys 页面Key 丢了或要换随时去那里操作。整个流程走下来核心就三件事环境装对、Key 配对、配置写对。这三步稳了后面就是正常用工具干活了。