1. 从零搭建 Claude CLI：本地开发环境安装配置全流程
Claude CLI 是 Anthropic 官方推出的命令行编程助手，能直接在终端里读写项目文件、执行命令、生成代码，适合习惯键盘流操作的开发者。它和网页版最大的区别在于：CLI 能感知你当前目录的完整代码结构，不需要手动复制粘贴上下文。这篇手册聚焦本地开发环境的完整落地流程，覆盖 Node.js 版本要求、npm 全局安装、API Key 与 Base URL 设置、连通性验证，以及几个高频报错的排查方法。如果你之前只在网页里用过 Claude，想把它接进日常开发工作流，跟着下面的步骤走一遍就能跑通。
我试过在一台全新的 Windows 机器上从零配置，中间踩了几个坑，比如 Node 版本过低导致安装失败、Base URL 没配对一直提示连接超时。所以这篇会把每个环节的验证方法都写清楚，避免你装完了却不知道哪一步出了问题。
先明确一下整体链路：Node.js 提供运行时 → npm 全局安装 Claude CLI → 配置 API Key 和 Base URL 指向可用的模型服务 → 启动 CLI 完成初始化 → 在终端里发起第一次对话验证。每一步都有对应的检查命令，做完一步验一步，比一口气装完再排查要省时间。
适合谁看：有基本命令行操作经验的开发者，本地已经装了 Git，想用 CLI 方式把 Claude 接入编码流程。不需要你提前了解 Anthropic 的 API 细节，配置模板会直接给出来。
2. 安装前的环境准备：Node.js 版本要求与 npm 全局路径配置
Claude CLI 依赖 Node.js 运行，官方要求 Node 18 及以上版本。版本太低会在安装阶段直接报 engine 不兼容的错误。先在终端确认当前版本：
node -v npm -v如果 node 版本低于 18，去 Node.js 官网下载 LTS 安装包，安装时保持默认选项即可，安装器会自动把 node 和 npm 加入 PATH。装完重新打开终端再执行一次node -v确认。
Windows 用户注意一个高频坑：npm 全局安装的包默认放在用户目录下的 AppData 里，如果这个路径没进 PATH，装完之后claude命令会提示「不是内部或外部命令」。先查一下全局路径：
npm config get prefix把这个路径加到系统环境变量 PATH 里。Windows 下操作路径是：此电脑右键 → 属性 → 高级系统设置 → 环境变量 → 在用户变量的 Path 里新增一条，填入上面命令输出的路径。改完要重开终端才生效。
macOS 和 Linux 用户一般不会有这个问题，但如果用的是 nvm 管理 Node 版本，确认一下全局包路径是否在当前 shell 的 PATH 中：
echo $PATH | grep -o "$(npm config get prefix)"有输出说明配置正确。另外 Git 也要提前装好，Claude CLI 在部分操作里会调用 git 命令，没装的话启动时会报错。验证：
git --version环境准备这一步看起来简单，但后面 80% 的「命令找不到」问题都出在这里，建议先确认清楚再往下走。
3. 安装 Claude CLI 并配置 API Key 与 Base URL
环境确认无误后，执行全局安装：
npm i -g @anthropic-ai/claude-code@latest安装完成后直接输入claude启动。首次启动会进入引导流程，要求你完成登录或配置。这里有两种接入方式：一种是官方账号登录，另一种是配置 API Key 和 Base URL 指向兼容的模型服务。国内开发者通常用第二种，配置更灵活。
配置文件位于用户目录下的.claude.json（Windows 是%USERPROFILE%\.claude.json，macOS/Linux 是~/.claude.json）。首次启动如果卡在引导页无法继续，可以手动写入初始化标记：
powershell -Command "$f='%USERPROFILE%\.claude.json';$j=Get-Content $f|ConvertFrom-Json;$j|Add-Member -NotePropertyName 'hasCompletedOnboarding' -NotePropertyValue $true -Force;$j|ConvertTo-Json|Set-Content $f"接下来配置模型接入。推荐用环境变量方式，清晰且不容易出错。在项目根目录或用户目录下创建配置文件，以 JSON 格式写入：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "你的API Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }三个字段的作用分别是：Base URL 指定请求发往哪个服务地址，API Key 是身份凭证，Model ID 指定默认调用的模型。这三件套缺一不可，配错任何一个都会导致请求失败。
如果你用 CC Switch 这类配置切换工具，操作逻辑是一样的：在工具里填入 Base URL、API Key、Model ID 三个值，选择绑定后它会自动写入 Claude 的配置文件。手动配置和工具配置二选一即可，不要同时改同一个文件，容易冲突。
配置完成后重新启动claude，引导页选择 yes 进入主界面。此时 CLI 已经能读取到你的配置，可以开始对话了。
4. 验证请求：发起第一次对话并确认连通性
配置写完后不要急着写代码，先做一次最小连通性验证。在终端进入任意项目目录，启动：
claude进入交互界面后，输入一句简单的测试指令，比如：
帮我看看当前目录下有哪些文件，并说明这个项目的技术栈如果配置正确，CLI 会读取当前目录结构并返回分析结果。这一步能同时验证三件事：API Key 是否有效、Base URL 是否可达、模型是否正常响应。
想更直接地验证接口连通性，可以用 curl 单独测一次：
curl https://taotoken.net/api/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: 你的API Key" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 100, "messages": [{"role": "user", "content": "回复 ok"}] }'返回内容里包含content字段和正常的文本回复，说明链路完全打通。如果返回 401，说明 Key 有问题；返回连接超时，说明 Base URL 不对或网络不可达。
验证通过后，你可以在项目里实际用起来。比如让它读某个文件并重构：
读取 src/utils/request.js，把里面的回调写法改成 async/awaitCLI 会展示修改前后的 diff，确认后写入文件。这就是 CLI 相比网页版的核心优势：它能直接操作你的本地文件，不需要手动复制粘贴。
5. 常见报错排查：401、连接失败与 OAuth 问题对照
配置过程中最容易遇到几类报错，这里逐个对照排查。
401 Unauthorized：API Key 无效或格式不对。检查配置文件里的 Key 是否有多余空格、是否复制完整。用上面的 curl 命令单独测一次，能快速定位是 Key 的问题还是 CLI 的问题。
local proxy failed / 连接超时：Base URL 配置错误或服务地址不可达。确认ANTHROPIC_BASE_URL填的是https://taotoken.net/api，不要多加路径或斜杠。改完配置后必须重启 CLI 才生效。
reading choices 报错：这类错误通常出现在响应格式不符合预期时，多半是 Model ID 写错了。确认模型名称拼写正确，比如claude-sonnet-4-20250514不要写成claude-sonnet-4。Model ID 必须和实际可用的模型完全一致。
OAuth 相关报错：如果你之前用官方账号登录过，配置文件里可能残留了 OAuth token，和 API Key 方式冲突。解决方法是清空.claude.json里的登录态字段，只保留 env 配置，或者直接删掉配置文件重新走一遍引导。
命令找不到：回到第 2 节检查 npm 全局路径是否在 PATH 里。这是 Windows 上最高频的问题，重装一遍不如先把路径配对。
排查的核心思路是分层验证：先确认 Node 和 npm 正常，再确认 CLI 安装成功，然后单独测 API 连通性，最后才排查 CLI 层面的配置。一层层往下，问题范围会快速缩小。
6. 长期使用建议与 Coding Plan 接入
跑通基础配置后，如果你打算把 Claude CLI 作为日常编码助手长期使用，建议关注几个实践点。
第一，把配置和项目分离。全局配置放在用户目录的.claude.json里，项目级的特殊配置放在项目根目录，避免不同项目之间互相干扰。第二，Model ID 按场景选择：日常补全和重构用响应快的模型，复杂架构设计用推理能力强的模型，在配置里可以随时切换。
第三，如果你需要更稳定的调用额度和更完整的 Agent 能力，可以了解 Coding Plan 方案，它针对长期编码场景做了优化，适合把 CLI 深度接入工作流的开发者。配置方式同样是填入 Base URL、API Key、Model ID 三件套，替换掉原来的值即可。
对于需要频繁切换模型或管理多个 Key 的场景，用配置切换工具会比手动改文件高效很多。核心还是那三个字段，理解了这个逻辑，任何工具都能快速上手。
最后提醒一点：CLI 能直接读写你的项目文件，首次在重要仓库里使用时，建议先在一个分支上测试，确认行为符合预期后再放开使用。配置文件和 API Key 不要提交到 Git 仓库，加到.gitignore里。
