环境检查（通用步骤）

在配置任何 CLI 前，先通过本页的检查清单。
如果跳过这一步，后续 80% 的报错都很难快速定位。

一、Node.js 与 npm

node -v
npm -v

通过标准：

• Node.js 建议 >= 20
• npm 能正常输出版本号

不通过时：

• 重新安装 Node.js LTS
• 关闭终端重新打开再执行

二、Shell 与权限

Windows（PowerShell）

$PSVersionTable.PSVersion
whoami

macOS / Linux

echo $SHELL
whoami

通过标准：

• 当前用户不是受限访客用户
• 能在用户目录创建配置文件

快速写权限测试：

mkdir -p ~/.claude ~/.codex ~/.gemini
touch ~/.claude/.perm_test ~/.codex/.perm_test ~/.gemini/.perm_test
rm -f ~/.claude/.perm_test ~/.codex/.perm_test ~/.gemini/.perm_test

三、网络连通性

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

通过标准：

• 返回 200 / 301 / 302 均可

如果超时：

• 检查代理配置
• 检查公司防火墙策略
• 切换网络后重试

四、CLI 安装状态

claude --version
codex --version
gemini --version

未安装时可执行：

npm i -g @anthropic-ai/claude-code@latest
npm i -g @openai/codex@latest
npm i -g @google/gemini-cli@latest

五、旧配置冲突检查

重点检查目录：

• ~/.claude/
• ~/.codex/
• ~/.gemini/

重点检查项：

• 是否残留旧 base_url
• 是否同时存在多份互相冲突的 Key
• 是否把测试令牌写到了生产配置

建议先备份再清理：

cp -r ~/.claude ~/.claude.bak.$(date +%Y%m%d%H%M%S) 2>/dev/null || true
cp -r ~/.codex ~/.codex.bak.$(date +%Y%m%d%H%M%S) 2>/dev/null || true
cp -r ~/.gemini ~/.gemini.bak.$(date +%Y%m%d%H%M%S) 2>/dev/null || true

六、检查结果判定

全部通过后再进入配置页：

• Claude：/docs/cli/2-claude.html
• Codex：/docs/cli/3-codex.html
• Gemini：/docs/cli/4-gemini.html

常见错误速查

现象	根因	处理
command not found	CLI 未安装或 PATH 未生效	重装 CLI 后重开终端
EACCES	目录写权限不足	修复目录权限或切换用户
TLS/SSL 报错	本地网络或证书链问题	更换网络、更新时间、重试
配置改了没生效	终端进程缓存旧环境	关闭终端并重开