引言

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

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

適用環(huán)境

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

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

安裝前需要知道什么

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

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

新手遇到最多的問題通常不是 Codex 本身，而是：

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

下面按步驟處理。

一、安裝 Node.js

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

https://nodejs.org/

下載 LTS 版本安裝包。

安裝時建議保持默認選項。安裝完成后，關(guān)閉當前 PowerShell 或 Windows Terminal，再重新打開一個新窗口。

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

二、檢查 Node.js 和 npm

在 PowerShell 中執(zhí)行：

node -v

如果安裝成功，會輸出類似：

v20.x.x

繼續(xù)檢查 npm：

npm -v

正常會輸出類似：

10.x.x

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

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

三、檢查 npm 全局安裝目錄

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

查看 npm 全局目錄：

npm config get prefix

常見輸出：

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

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

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

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

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

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

添加下面目錄：

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

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

四、配置 npm 鏡像

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

npm config get registry

默認通常是：

https://registry.npmjs.org/

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

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

再確認一次：

npm config get registry

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

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

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

五、安裝 Codex CLI

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

npm install -g @openai/codex

安裝完成后，檢查版本：

codex --version

正常情況下會輸出 Codex CLI 的版本號。

繼續(xù)查看幫助：

codex --help

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

六、首次運行

執(zhí)行：

codex

如果終端提示登錄或認證，按提示操作即可。

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

codex login

登錄完成后，再次運行：

codex

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

七、運行本地診斷

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

codex doctor

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

八、常用命令速查

查看版本：

codex --version

查看幫助：

codex --help

啟動交互模式：

codex

登錄：

codex login

退出登錄：

codex logout

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

codex doctor

更新 Codex CLI：

codex update

在指定目錄啟動：

codex -C "D:\your-project"

九、常見問題

1. node 命令找不到

現(xiàn)象：

無法將“node”項識別為 cmdlet、函數(shù)、腳本文件或可運行程序的名稱

處理方式：

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

2. npm 命令找不到

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

安裝完成后重新打開 PowerShell，再檢查：

node -v
npm -v

3. npm install -g 下載失敗

先檢查當前 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)象：

無法將“codex”項識別為 cmdlet、函數(shù)、腳本文件或可運行程序的名稱

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

npm config get prefix
where.exe codex

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

把下面目錄加入用戶 Path：

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

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

codex --version

5. 安裝后版本沒有變化

先查看當前命令位置：

where.exe codex

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

可以嘗試重新安裝：

npm install -g @openai/codex

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

codex update

6. PowerShell 重啟后配置才生效

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

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

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

十、建議的新手檢查清單

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

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

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

十一、寫在最后

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

Node.js 可用
npm 可用
Codex CLI 可用
可以正常登錄或通過終端提示完成認證

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

遇到問題時，優(yōu)先運行：

codex doctor

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

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

最新評論