环境检查

大约 8 分钟

环境检查

手动配置路线的必做前置步骤

不检查就跳进去配？后面出问题你会怀疑人生。在你装任何命令行 AI 工具之前，先跑完这页的检查清单。5 分钟搞定，能省你 2 小时的排查时间。

完全不会 cmd / 终端？建议跳过本页

本页假设你能打开终端、能敲简单命令。如果你看到"终端"两个字就头大，直接走一键安装包，不需要任何命令行操作。

这篇文档适合谁

适合：手动配置 Claude Code / Codex CLI / Gemini CLI 之前要做体检的开发者
不适合：完全不会终端的小白——直接走一键安装包

这篇文档适合做什么

一次性确认 Node.js / npm 是否够新、是否能用
一次性确认网络能否访问平台
一次性确认 CLI 工具是否已安装、是否有残留旧配置

为什么要检查环境？

很多用户装好工具之后一运行就报错，到处找原因，最后发现：Node.js 没装，或者版本太旧，或者网络压根连不上。

这些问题如果没在最开始排掉，后面每换一个配置就得重新猜一遍，非常折磨人。

所以：先检查，后配置，省时间省头发。

第一步：检查 Node.js 有没有装

Node.js 是什么？

Node.js 是一个运行环境，Claude Code / Codex CLI / Gemini CLI 这些工具都需要它才能跑起来。就好比你要打开 Word 文件，得先有 Office 一样。

怎么打开终端？

Windows

方法一（推荐）：按键盘 Win + R，弹出小窗口，输入 powershell，按回车。

方法二：点左下角开始菜单，搜索 "PowerShell"，点击打开。

方法三：按 Win + X，选 "Windows PowerShell" 或 "终端"。

Mac

按 Command + 空格，打开 Spotlight 搜索，输入 terminal，按回车。

也可以：打开 Finder → 应用程序 → 实用工具 → 终端。

Linux

直接打开你的终端应用，或者按 Ctrl + Alt + T。

输命令检查 Node.js

终端打开之后，会看到一个黑色（或蓝色）窗口，里面有个闪烁的光标，这就对了。

把下面这行命令 一字不差 地输进去，然后按回车：

node -v

结果 1：成功了

显示类似这样的内容：

v22.3.0

只要开头是 v，后面第一个数字 ≥ 20，就没问题，继续下一步。

结果 2：版本太旧了

如果显示 v18.x.x 或更低，说明版本太旧，需要升级。

去 https://nodejs.org 下载最新的 LTS 版本（左边那个，标着 LTS 的），安装完之后 关掉终端重新打开，再检查一遍。

结果 3：command not found 或 'node' 不是内部或外部命令

说明根本没装 Node.js。同样去 https://nodejs.org 下载 LTS 版本安装，装完重开终端再试。

安装 Node.js 小提示

一路点"下一步"就行，不用改任何选项。装完记得 重新打开终端，因为旧的终端不会自动刷新环境变量。

顺便检查一下 npm

Node.js 安装好之后，npm 一般会跟着自动装好。输入这个命令确认一下：

npm -v

正常情况会显示一个版本号，比如 10.5.0。只要能显示出来就 OK。

第二步：检查网络能不能访问平台

工具装好了，但是连不上平台，一样没用。先测试一下网络通不通。

方法一：用浏览器直接访问（最简单）

打开你常用的浏览器（Chrome、Edge、Safari 都行），在地址栏输入：

https://www.yuzhixiaolongxia.com

按回车。如果页面正常加载出来，说明网络没问题。

如果显示"无法访问此网站"或者一直转圈，试试：

换个网络（手机热点试试）
检查有没有开代理（有些公司代理会拦截特定域名）

方法二：用终端命令检查

在终端里输入：

curl -I https://www.yuzhixiaolongxia.com

正常结果：显示 HTTP/2 200 或 HTTP/1.1 301 之类的，有数字就说明连上了。

失败结果：显示 Could not resolve host 或超时没响应，说明网络不通，先解决网络问题再继续。

Windows 用户

如果提示 curl 不认识，改用：

Invoke-WebRequest -Uri "https://www.yuzhixiaolongxia.com" -UseBasicParsing

显示状态码 200 就是通的。

第三步：检查 AI 工具有没有装好

这里检查三个工具：Claude Code、Codex CLI、Gemini CLI。

在终端里分别输入下面三条命令，每输一条按一次回车：

claude --version

codex --version

gemini --version

正常结果：每条命令都显示一个版本号，比如 1.0.7 之类的。

命令没找到：显示 command not found（Mac / Linux）或 'claude' 不是内部或外部命令（Windows），说明这个工具还没装，继续看下一步。

第四步：没装的话，现在装上

安装命令

安装 Claude Code：

npm install -g @anthropic-ai/claude-code@latest

安装 Codex CLI：

npm install -g @openai/codex@latest

安装 Gemini CLI：

npm install -g @google/gemini-cli@latest

-g 是什么意思

-g 是"全局安装"的意思，装完之后在任何地方都能用，必须加。

安装过程中会出现一堆滚动的文字，这是正常的，耐心等它跑完。如果中间出现 npm warn 开头的警告，不用管，这不是错误。

装完必须重开终端

安装完之后，关掉终端，重新打开一个新终端，再回到第三步检查一遍，确认版本号能显示出来。

安装报错了怎么办？

Windows 出现 EACCES 权限错误：

用管理员身份打开 PowerShell。方法：右键开始菜单 → 选 "Windows PowerShell（管理员）" 或 "终端（管理员）"，然后再运行安装命令。

Mac 出现权限错误：

在命令前面加 sudo：

sudo npm install -g @anthropic-ai/claude-code@latest

输入后会让你输电脑密码（输入时不显示字符，这是正常的），输完按回车。

第五步：检查有没有残留旧配置

如果你以前折腾过这些工具，可能留下了一些旧的配置文件，会和新配置打架，导致各种奇怪的问题。趁现在检查一下。

旧配置藏在哪？

这些工具的配置文件夹位置：

工具	Windows 路径	Mac / Linux 路径
Claude Code	`C:\Users\你的用户名\.claude\`	`~/.claude/`
Codex CLI	`C:\Users\你的用户名\.codex\`	`~/.codex/`
Gemini CLI	`C:\Users\你的用户名\.gemini\`	`~/.gemini/`

什么是"隐藏文件夹"

这些文件夹名字以点（.）开头，系统默认是不显示的。

Windows：在文件资源管理器里勾选"显示隐藏的项目"
Mac：在 Finder 里按 Command + Shift + 句号 可以切换显示

检查什么？

进入这些文件夹（如果存在的话），检查里面的配置文件，重点关注：

有没有旧的接口地址？ 比如指向别的中转站的地址，要清掉换成本平台地址。
有没有多个令牌互相冲突？ 同一个工具配了好几个令牌，可能会出问题。
有没有把测试令牌写进了正式配置？ 测试令牌额度有限，别浪费了。

备份旧配置（推荐）

操作之前，先把旧配置备份一下，万一配错了还能还原。

Mac / Linux

在终端里执行：

cp -r ~/.claude ~/.claude.bak 2>/dev/null && echo "已备份 .claude" || echo ".claude 不存在，跳过"
cp -r ~/.codex ~/.codex.bak 2>/dev/null && echo "已备份 .codex" || echo ".codex 不存在，跳过"
cp -r ~/.gemini ~/.gemini.bak 2>/dev/null && echo "已备份 .gemini" || echo ".gemini 不存在，跳过"

Windows

在 PowerShell 里执行：

Copy-Item -Recurse "$env:USERPROFILE\.claude" "$env:USERPROFILE\.claude.bak" -ErrorAction SilentlyContinue
Copy-Item -Recurse "$env:USERPROFILE\.codex" "$env:USERPROFILE\.codex.bak" -ErrorAction SilentlyContinue
Copy-Item -Recurse "$env:USERPROFILE\.gemini" "$env:USERPROFILE\.gemini.bak" -ErrorAction SilentlyContinue

没有报错就说明备份完成了。

检查结果汇总

把下面这个表格过一遍，全部打勾就可以进入配置步骤了：

检查项	状态
Node.js 版本 ≥ 20	☐
npm 能正常显示版本号	☐
浏览器能访问平台网址	☐
目标 CLI 工具已安装且能显示版本号	☐
旧配置已检查 / 备份	☐

全部 OK 之后，选择你要配置的工具：

常见坑速查（base URL / 模型 ID / 分组）

坑	现象	怎么修
`command not found: node`	Node.js 没装	去 `nodejs.org` 装 LTS 版，装完重开终端
`command not found: claude`	Claude Code 没装	`npm install -g @anthropic-ai/claude-code@latest`
`EACCES` 权限错误	没用管理员 / sudo	Windows 用管理员打开终端，Mac 加 `sudo`
`curl` 超时没响应	网络不通	换网络，或检查代理设置
装了但还是 `command not found`	终端没重开	关掉终端，重新打开一个新的再试
`npm install` 下载很慢	国内访问 npm 慢	等一会儿，或配置 npm 镜像源
Claude Code 地址加了 `/v1`	404	Claude Code 地址不带 /v1
Codex CLI 地址少了 `/v1`	404	Codex CLI 地址必须带 /v1
Gemini 地址末尾少了 `/`	拼接错	末尾必须留 `/`
令牌选错分组	401	Claude / Codex / Gemini 各用各家族令牌分组

上一步：一键安装包｜下一步：Claude Code 手动配置