今天講一下 Codex CLI 怎么安裝和配置。

內(nèi)容包括 Windows、macOS、Linux 的安裝方法，API 配置、第一次啟動(dòng)、常用命令和報(bào)錯(cuò)排查。想自己把 Codex 跑起來(lái)，按下面的順序操作就可以。

本文整理于 2026 年 7 月 20 日。模型列表更新較快，模型 ID 請(qǐng)以后臺(tái)實(shí)際顯示為準(zhǔn)。

一、安裝前準(zhǔn)備

Codex 常見(jiàn)的使用方式有 CLI、IDE 擴(kuò)展、云端和桌面客戶端。本文主要講 Codex CLI，它可以直接進(jìn)入項(xiàng)目讀取文件、修改代碼和運(yùn)行測(cè)試。

安裝前需要準(zhǔn)備：

• Windows 10/11、macOS 或主流 Linux；
• Node.js LTS 版本；
• npm，安裝 Node.js 時(shí)會(huì)一并安裝；
• 一個(gè)用于測(cè)試的項(xiàng)目目錄。

二、安裝 Codex CLI

Windows

先從 Node.js 官網(wǎng)安裝 LTS 版本：

https://nodejs.org/

安裝后重新打開(kāi) PowerShell，檢查環(huán)境：

node -v
npm -v

然后安裝 Codex：

npm install -g @openai/codex@latest
codex --version

能正常返回版本號(hào)，就說(shuō)明安裝成功。

macOS / Linux

先安裝當(dāng)前 Node.js LTS 版本，再執(zhí)行：

node -v
npm -v
npm install -g @openai/codex@latest
codex --version

macOS 也可以使用 Homebrew 安裝 Node.js：

brew install node

如果安裝完成后提示找不到 codex，先關(guān)閉舊終端重新打開(kāi)，再檢查 npm 全局目錄是否已經(jīng)加入 PATH。

三、安裝完成后為什么還要配置 API

codex --version 成功，只代表本地程序裝好了。真正調(diào)用模型還需要 Base URL、API Key、模型名和接口協(xié)議。

如果官方鏈路使用不便，也可以選擇支持 Responses API 的 OpenAI 兼容接口。下面使用 https://kkflow.org 提供的接口作為配置示例，先在后臺(tái)創(chuàng)建 API Key，并確認(rèn)當(dāng)前可用的模型 ID。

文章、截圖和 Git 倉(cāng)庫(kù)中不要出現(xiàn)真實(shí) Key，本文統(tǒng)一使用 sk-你的API密鑰 代替。

四、配置 Codex

Codex 配置目錄：

需要準(zhǔn)備兩個(gè)文件：

.codex/
├── config.toml
└── auth.json

1. 配置 config.toml

Windows 用戶執(zhí)行：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null
notepad "$env:USERPROFILE\.codex\config.toml"

macOS / Linux 用戶執(zhí)行：

mkdir -p ~/.codex
nano ~/.codex/config.toml

寫(xiě)入下面的配置：

model_provider = "kkflow"
model = "gpt-5.6-sol"
review_model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"

disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true

model_context_window = 400000
model_auto_compact_token_limit = 360000

[model_providers.kkflow]
name = "KKFlow"
base_url = "https://kkflow.org/v1"
wire_api = "responses"
requires_openai_auth = true

gpt-5.6-sol 是示例模型。如果出現(xiàn) model not found，請(qǐng)根據(jù)接口后臺(tái)的實(shí)際模型 ID，同時(shí)修改 model 和 review_model。

上下文窗口和自動(dòng)壓縮閾值也要與模型實(shí)際能力匹配。如果實(shí)際上下文不足 400000 Token，需要相應(yīng)調(diào)低這兩個(gè)數(shù)值。

還要注意：model_provider 必須和下面的 Provider 配置名稱對(duì)應(yīng)，base_url 末尾不要漏掉 /v1。

2. 配置 auth.json

Windows 打開(kāi)文件：

notepad "$env:USERPROFILE\.codex\auth.json"

macOS / Linux：

nano ~/.codex/auth.json

寫(xiě)入：

{
  "OPENAI_API_KEY": "sk-你的API密鑰"
}

保存后不要把 auth.json 上傳到 Git，也不要在教程截圖中展示真實(shí)內(nèi)容。

五、啟動(dòng)并驗(yàn)證

先進(jìn)入項(xiàng)目目錄：

cd your-project-folder
codex

第一次建議先發(fā)一條只讀任務(wù)：

先不要修改文件，請(qǐng)分析當(dāng)前項(xiàng)目的目錄結(jié)構(gòu)、技術(shù)棧和主要模塊。

如果 Codex 能讀取項(xiàng)目并正?；卮?，說(shuō)明安裝、API Key、Base URL 和模型已經(jīng)跑通。

接著再讓它執(zhí)行一個(gè)小任務(wù)：

先給出修改計(jì)劃，等我確認(rèn)后再動(dòng)手。修改完成后運(yùn)行現(xiàn)有測(cè)試，并匯總實(shí)際結(jié)果。

不要第一次使用就讓它重構(gòu)整個(gè)項(xiàng)目。先分析、再計(jì)劃、確認(rèn)后修改，會(huì)更容易控制結(jié)果。

六、常用命令

進(jìn)入 Codex 后輸入 /，可以查看當(dāng)前版本支持的命令。常用的有：

AGENTS.md 可以記錄項(xiàng)目技術(shù)棧、啟動(dòng)命令、測(cè)試命令和修改邊界。比如：

# AGENTS.md

## 常用命令

- 安裝依賴：pnpm install
- 本地啟動(dòng)：pnpm dev
- 運(yùn)行測(cè)試：pnpm test

## 修改要求

- 不要修改 node_modules 和構(gòu)建產(chǎn)物。
- 新增業(yè)務(wù)邏輯時(shí)補(bǔ)充測(cè)試。
- 修改完成后運(yùn)行測(cè)試和類(lèi)型檢查。

說(shuō)明越具體，Codex 越容易按項(xiàng)目真實(shí)規(guī)則執(zhí)行。

七、常見(jiàn)報(bào)錯(cuò)排查

如果不確定模型名稱，直接回到接口后臺(tái)核對(duì)模型列表，再檢查 config.toml 中的模型 ID 是否存在。

八、最后幾個(gè)使用建議

正式修改項(xiàng)目前，先執(zhí)行：

git status

確認(rèn)當(dāng)前工作區(qū)狀態(tài)，重要修改先創(chuàng)建 Git 檢查點(diǎn)。Codex 完成任務(wù)后，還要查看：

git diff

最后確認(rèn)測(cè)試、類(lèi)型檢查或構(gòu)建命令是否真的執(zhí)行成功。AI 的總結(jié)不能代替實(shí)際驗(yàn)證結(jié)果。

整個(gè)配置流程可以壓縮成一句話：安裝 Node.js 和 Codex CLI，配置 config.toml 與 auth.json，重開(kāi)終端，再進(jìn)入項(xiàng)目運(yùn)行 codex。

先把最小配置跑通，再逐步增加復(fù)雜任務(wù)。遇到問(wèn)題時(shí)按 Node.js、Codex 版本、Base URL、API Key、模型 ID 的順序排查，通常很快就能找到原因。

到此這篇關(guān)于Codex配置使用教程：安裝、國(guó)內(nèi)API接入與常見(jiàn)報(bào)錯(cuò)的文章就介紹到這了,更多相關(guān)Codex安裝、國(guó)內(nèi)API接入配置內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評(píng)論