引言

本文面向第一次在 Windows 上安裝 Codex CLI 的用戶，目標(biāo)是把安裝過(guò)程、環(huán)境變量檢查和常見(jiàn)問(wèn)題排查講清楚。

本文只討論本地開(kāi)發(fā)環(huán)境配置，不涉及外部接入配置、付費(fèi)服務(wù)或推廣信息。

適用環(huán)境

• Windows 10 或 Windows 11
• PowerShell 或 Windows Terminal
• Node.js LTS
• npm

如果你已經(jīng)安裝過(guò) Node.js，也建議先按本文的檢查命令確認(rèn)環(huán)境是否正常。

安裝前需要知道什么

Codex CLI 是一個(gè)命令行工具。它依賴 Node.js 和 npm 安裝，所以安裝順序是：

安裝 Node.js
檢查 node 命令
檢查 npm 命令
安裝 Codex CLI
檢查 codex 命令
登錄或按終端提示完成認(rèn)證
運(yùn)行一次基礎(chǔ)檢查

新手遇到最多的問(wèn)題通常不是 Codex 本身，而是：

• Node.js 沒(méi)有安裝成功
• npm 全局目錄沒(méi)有加入 Path
• 終端沒(méi)有重新打開(kāi)，環(huán)境變量未刷新
• 網(wǎng)絡(luò)環(huán)境導(dǎo)致 npm 包下載失敗
• codex 命令安裝了但系統(tǒng)找不到

下面按步驟處理。

一、安裝 Node.js

打開(kāi) Node.js 官網(wǎng)：

https://nodejs.org/

下載 LTS 版本安裝包。

安裝時(shí)建議保持默認(rèn)選項(xiàng)。安裝完成后，關(guān)閉當(dāng)前 PowerShell 或 Windows Terminal，再重新打開(kāi)一個(gè)新窗口。

重新打開(kāi)終端是必要的，因?yàn)?Windows 環(huán)境變量通常需要新終端窗口才會(huì)生效。

二、檢查 Node.js 和 npm

在 PowerShell 中執(zhí)行：

node -v

如果安裝成功，會(huì)輸出類似：

v20.x.x

繼續(xù)檢查 npm：

npm -v

正常會(huì)輸出類似：

10.x.x

只要這兩個(gè)命令都能輸出版本號(hào)，說(shuō)明 Node.js 和 npm 的基礎(chǔ)環(huán)境已經(jīng)可用。

如果提示無(wú)法識(shí)別 node 或 npm，通常是 Node.js 沒(méi)有安裝成功，或者安裝后沒(méi)有重新打開(kāi)終端?？梢韵戎貑?PowerShell；如果仍然無(wú)效，重新安裝 Node.js LTS。

三、檢查 npm 全局安裝目錄

Codex CLI 是通過(guò) npm 全局安裝的。全局安裝后，Windows 需要能在 Path 中找到對(duì)應(yīng)命令。

查看 npm 全局目錄：

npm config get prefix

常見(jiàn)輸出：

C:\Users\你的用戶名\AppData\Roaming\npm

檢查 Path 中是否包含 npm 目錄：

$env:Path -split ';' | Select-String 'npm'

如果能看到 npm 全局目錄，說(shuō)明 Path 基本正常。

如果沒(méi)有輸出，可以手動(dòng)添加用戶環(huán)境變量：

Windows 設(shè)置
系統(tǒng)
關(guān)于
高級(jí)系統(tǒng)設(shè)置
環(huán)境變量
用戶變量
Path
編輯
新建

添加下面目錄：

C:\Users\你的用戶名\AppData\Roaming\npm

保存后，關(guān)閉所有 PowerShell 窗口，再重新打開(kāi)。

四、配置 npm 鏡像

如果你執(zhí)行 npm 安裝時(shí)速度很慢，或者經(jīng)常下載失敗，可以先查看當(dāng)前 npm 源：

npm config get registry

默認(rèn)通常是：

https://registry.npmjs.org/

如果訪問(wèn)官方源不穩(wěn)定，可以切換到鏡像源：

npm config set registry https://registry.npmmirror.com

再確認(rèn)一次：

npm config get registry

如果后續(xù)需要切回官方源：

npm config set registry https://registry.npmjs.org/

這一步不是必須的。如果你的網(wǎng)絡(luò)可以正常訪問(wèn) npm 官方源，可以保持默認(rèn)配置。

五、安裝 Codex CLI

執(zhí)行全局安裝命令：

npm install -g @openai/codex

安裝完成后，檢查版本：

codex --version

正常情況下會(huì)輸出 Codex CLI 的版本號(hào)。

繼續(xù)查看幫助：

codex --help

如果能看到命令幫助，說(shuō)明 Codex CLI 已經(jīng)安裝成功。

六、首次運(yùn)行

執(zhí)行：

codex

如果終端提示登錄或認(rèn)證，按提示操作即可。

也可以顯式執(zhí)行登錄命令：

codex login

登錄完成后，再次運(yùn)行：

codex

如果能進(jìn)入交互界面，說(shuō)明基礎(chǔ)安裝流程已經(jīng)完成。

七、運(yùn)行本地診斷

Codex CLI 提供了診斷命令，可以用來(lái)檢查本地安裝、配置和認(rèn)證狀態(tài)：

codex doctor

如果后續(xù)使用中遇到異常，可以優(yōu)先運(yùn)行這個(gè)命令，看終端給出的提示。

八、常用命令速查

查看版本：

codex --version

查看幫助：

codex --help

啟動(dòng)交互模式：

codex

登錄：

codex login

退出登錄：

codex logout

檢查本地環(huán)境：

codex doctor

更新 Codex CLI：

codex update

在指定目錄啟動(dòng)：

codex -C "D:\your-project"

九、常見(jiàn)問(wèn)題

1. node 命令找不到

現(xiàn)象：

無(wú)法將“node”項(xiàng)識(shí)別為 cmdlet、函數(shù)、腳本文件或可運(yùn)行程序的名稱

處理方式：

0. 關(guān)閉并重新打開(kāi) PowerShell。
1. 重新執(zhí)行 node -v。
2. 如果仍然無(wú)效，重新安裝 Node.js LTS。
3. 檢查 Node.js 安裝目錄是否加入 Path。

2. npm 命令找不到

Node.js 正常安裝時(shí)會(huì)自帶 npm。如果 node -v 正常，但 npm -v 不正常，建議重新安裝 Node.js LTS。

安裝完成后重新打開(kāi) PowerShell，再檢查：

node -v
npm -v

3. npm install -g 下載失敗

先檢查當(dāng)前 npm 源：

npm config get registry

如果下載失敗，可以切換鏡像源：

npm config set registry https://registry.npmmirror.com

清理緩存后重試：

npm cache clean --force
npm install -g @openai/codex

如果公司網(wǎng)絡(luò)、校園網(wǎng)或代理環(huán)境有限制，需要根據(jù)自己的網(wǎng)絡(luò)環(huán)境處理。

4. codex 命令找不到

現(xiàn)象：

無(wú)法將“codex”項(xiàng)識(shí)別為 cmdlet、函數(shù)、腳本文件或可運(yùn)行程序的名稱

先檢查 Codex 是否安裝到了 npm 全局目錄：

npm config get prefix
where.exe codex

如果 where.exe codex 沒(méi)有結(jié)果，通常是 npm 全局目錄沒(méi)有加入 Path。

把下面目錄加入用戶 Path：

C:\Users\你的用戶名\AppData\Roaming\npm

然后關(guān)閉 PowerShell，重新打開(kāi)，再執(zhí)行：

codex --version

5. 安裝后版本沒(méi)有變化

先查看當(dāng)前命令位置：

where.exe codex

如果系統(tǒng)里存在多個(gè) codex 命令，可能會(huì)優(yōu)先執(zhí)行舊路徑下的版本。

可以嘗試重新安裝：

npm install -g @openai/codex

也可以執(zhí)行更新命令：

codex update

6. PowerShell 重啟后配置才生效

這是 Windows 環(huán)境變量的常見(jiàn)行為。

如果剛剛安裝 Node.js、修改 Path、安裝全局命令，建議關(guān)閉所有 PowerShell 窗口，再重新打開(kāi)。

不要在舊窗口里反復(fù)測(cè)試，否則可能一直讀到舊環(huán)境變量。

十、建議的新手檢查清單

安裝完成后，按順序執(zhí)行：

node -v
npm -v
npm config get prefix
codex --version
codex --help
codex doctor

如果這些命令都能正常執(zhí)行，說(shuō)明 Codex CLI 的本地安裝已經(jīng)基本完成。

十一、寫在最后

新手安裝 Codex CLI 時(shí)，不建議一上來(lái)就修改復(fù)雜配置。先把最基礎(chǔ)的鏈路跑通：

Node.js 可用
npm 可用
Codex CLI 可用
可以正常登錄或通過(guò)終端提示完成認(rèn)證

基礎(chǔ)環(huán)境穩(wěn)定后，再根據(jù)自己的開(kāi)發(fā)習(xí)慣配置工作目錄、模型參數(shù)或其他高級(jí)選項(xiàng)。

遇到問(wèn)題時(shí)，優(yōu)先運(yùn)行：

codex doctor

再根據(jù)提示處理，比反復(fù)卸載重裝更有效。

以上就是在Windows上安裝Codex CLI的新手教程的詳細(xì)內(nèi)容，更多關(guān)于Codex CLI Windows新手安裝的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！

最新評(píng)論