OpenAI 出品的終端 AI 編程智能體，讓 AI 助手在你的電腦本地運(yùn)行

前言

Codex 是 OpenAI 推出的開(kāi)源 AI 編程智能體，用 Rust 編寫，速度快、效率高，能夠讀取并修改代碼文件、執(zhí)行終端命令，并在終端中完成多步驟的自主開(kāi)發(fā)任務(wù)。官方 GitHub 倉(cāng)庫(kù)已獲得超過(guò) 83,200 星標(biāo)，與 Claude Code 并列為當(dāng)前最熱門的終端 AI 編程工具。

本文將手把手帶你完成 Codex 的本地安裝與配置，涵蓋 Windows（含 WSL2）、macOS、Linux 三大平臺(tái)，并深入講解核心功能、安全配置和高效使用技巧。全文配以 Mermaid 流程圖 和架構(gòu)圖，讓復(fù)雜概念一目了然。

一、Codex 是什么？核心架構(gòu)一圖看懂

下圖展示了 Codex CLI 的核心架構(gòu)與工作流程，后續(xù)內(nèi)容將圍繞這個(gè)框架展開(kāi)：

核心要點(diǎn)：

• 本地運(yùn)行：Codex CLI 完全運(yùn)行在你的電腦上，不需要將代碼上傳到云端。
• 多后端支持：可以通過(guò) openai_base_url 配置指向任意兼容 OpenAI 協(xié)議的 API 端點(diǎn)，包括第三方網(wǎng)關(guān)或本地部署的 LLM。
• 安全沙盒：默認(rèn)啟用的沙盒機(jī)制嚴(yán)格控制文件寫入范圍、命令執(zhí)行權(quán)限和網(wǎng)絡(luò)訪問(wèn)。

二、安裝前的環(huán)境準(zhǔn)備

2.1 系統(tǒng)要求

重要：Node.js 版本要求 22 或更高，這是官方明確的最低版本要求。

2.2 安裝 Node.js（Windows）

方式一：官網(wǎng)下載（推薦）

1. 打開(kāi)瀏覽器訪問(wèn) https://nodejs.org/
2. 點(diǎn)擊“LTS”版本下載（版本號(hào)大于 22，推薦長(zhǎng)期支持版本）
3. 雙擊 .msi 文件按向?qū)瓿砂惭b

方式二：使用包管理器

# 使用 Chocolatey
choco install nodejs
# 或使用 Scoop
scoop install nodejs

驗(yàn)證安裝

打開(kāi) PowerShell 或 CMD，輸入：

node --version   # 應(yīng)顯示 v22.x.x 或更高
npm --version

如果顯示版本號(hào)，說(shuō)明安裝成功。

三、安裝 Codex CLI

3.1 Windows 平臺(tái)安裝

Windows 上有兩種安裝方式，推薦使用 WSL2 獲得最佳體驗(yàn)。

方式一：WSL2（強(qiáng)烈推薦）

Codex 官方明確表示 Windows 支持仍為實(shí)驗(yàn)性，WSL2 是目前最穩(wěn)定、兼容性最好的方案。

第一步：安裝 WSL2

以管理員身份打開(kāi) PowerShell，執(zhí)行：

wsl --install

安裝完成后重啟電腦，系統(tǒng)會(huì)自動(dòng)進(jìn)入 Ubuntu 初始化，設(shè)置用戶名和密碼即可。

第二步：在 WSL2 中安裝 Node.js

# 安裝 nvm（Node 版本管理工具）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加載配置
source ~/.bashrc

# 安裝 Node.js 22
nvm install 22

# 驗(yàn)證安裝
node -v   # 應(yīng)顯示 v22.x.x
npm -v

為什么不用 apt install nodejs？Ubuntu 自帶倉(cāng)庫(kù)的 Node.js 版本通常較舊，低于官方要求的 22，使用 nvm 可以精確安裝所需版本。

第三步：安裝 Codex CLI

npm install -g @openai/codex
codex --version   # 驗(yàn)證安裝

重要：項(xiàng)目目錄放置位置

項(xiàng)目文件必須放在 Linux 文件系統(tǒng)中，不要放在 /mnt/c/ 路徑下?？缥募到y(tǒng)訪問(wèn)會(huì)嚴(yán)重影響性能，Git、測(cè)試等操作都會(huì)變慢：

# ? 正確：放在 Linux home 目錄下
mkdir -p ~/code && cd ~/code
git clone your-repo

# ? 錯(cuò)誤：放在 Windows 盤符中
cd /mnt/c/Users/xxx/project   # 性能極差！

VS Code + WSL 擴(kuò)展配置：

安裝 VS Code 的 WSL 擴(kuò)展，然后在 WSL 終端中直接運(yùn)行：

cd ~/code/my-project
code .   # 自動(dòng)以 WSL 模式打開(kāi) VS Code

這樣 VS Code 的內(nèi)置終端也是 WSL 環(huán)境，Codex 可以直接使用。

方式二：原生 Windows（PowerShell）

如果不想使用 WSL，也可以在 PowerShell 中直接安裝：

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

原生 Windows 版本使用實(shí)驗(yàn)性的 Windows 沙盒機(jī)制（通過(guò) Restricted Token + 文件系統(tǒng) ACL 限制寫入范圍），實(shí)際使用中偶爾會(huì)出現(xiàn)權(quán)限問(wèn)題，Win10 比 Win11 更容易出問(wèn)題。

3.2 macOS 平臺(tái)安裝

# 方式一：npm（通用）
npm install -g @openai/codex

# 方式二：Homebrew（推薦）
brew install --cask codex

# 驗(yàn)證安裝
codex --version

3.3 Linux 平臺(tái)安裝

# npm 安裝
npm install -g @openai/codex

# 或直接從 GitHub 下載二進(jìn)制包（網(wǎng)絡(luò)受限時(shí)推薦）
curl -L https://github.com/openai/codex/releases/download/rust-v0.131.0/codex-x86_64-unknown-linux-musl.tar.gz | tar -xz
sudo mv codex /usr/local/bin/

# 驗(yàn)證安裝
codex --version

推薦使用 musl 靜態(tài)鏈接版本，不依賴系統(tǒng) glibc，兼容性最佳。

3.4 安裝流程圖

四、基礎(chǔ)操作：從第一條指令開(kāi)始

4.1 啟動(dòng) Codex

進(jìn)入你的項(xiàng)目目錄，直接運(yùn)行：

cd your-project-folder
codex

這將啟動(dòng)交互式對(duì)話環(huán)境，你可以直接輸入自然語(yǔ)言指令讓 Codex 執(zhí)行任務(wù)。

4.2 第一個(gè)任務(wù)：生成代碼

在 Codex 交互環(huán)境中輸入：

用 Python 寫一個(gè)快速的冒泡排序算法

你會(huì)看到 Codex 生成完整代碼并附帶解釋。

4.3 常用命令速查

4.4 斜杠命令速查

4.5 Codex 基礎(chǔ)操作流程圖

五、核心模式：按場(chǎng)景切換，效率拉滿

51 交互式 TUI 模式（推薦日常使用）

啟動(dòng)帶有 UI 界面的交互模式：

codex tui

在此模式下，你可以進(jìn)行多輪對(duì)話，Codex 會(huì)記住上下文。例如：

> 生成一個(gè) Python 快速排序?qū)崿F(xiàn)
[生成代碼]
> 優(yōu)化為遞歸版本并添加類型注解
[優(yōu)化代碼]
> 生成對(duì)應(yīng)的單元測(cè)試用例
[生成測(cè)試代碼]

5.2 非交互式批量執(zhí)行模式

適合批量處理固定任務(wù)。創(chuàng)建 tasks.toml 文件：

[[tasks]]
name = "生成用戶模型"
prompt = "使用 TypeScript 編寫一個(gè)包含 CRUD 方法的 User 模型"
output = "models/user.ts"

[[tasks]]
name = "優(yōu)化 SQL 查詢"
prompt = "優(yōu)化以下慢查詢：SELECT * FROM orders WHERE status='pending'"
output = "queries/optimized.sql"

然后執(zhí)行：

codex exec --file tasks.toml --output results/

5.3 項(xiàng)目分析模式

在項(xiàng)目根目錄運(yùn)行：

codex /analyze

Codex 會(huì)掃描整個(gè)代碼庫(kù)并建立索引，之后你可以提問(wèn)：“這個(gè)項(xiàng)目中哪些函數(shù)缺少錯(cuò)誤處理？”

5.4 三種核心模式對(duì)比

六、安全沙盒：讓 Codex 更“可控”

6.1 沙盒模式詳解

Codex 內(nèi)置了安全沙盒機(jī)制，嚴(yán)格限制 Codex 對(duì)系統(tǒng)的訪問(wèn)權(quán)限：

配置方式（在 ~/.codex/config.toml 中）：

sandbox_mode = "workspace-write"

6.2 審批策略

控制哪些操作需要用戶手動(dòng)確認(rèn)：

approval_policy = "on-request"

6.3 沙盒決策流程圖

七、AGENTS.md：讓 Codex 記住你的項(xiàng)目

7.1 什么是 AGENTS.md？

Codex 在項(xiàng)目根目錄中使用 AGENTS.md 作為項(xiàng)目級(jí)記憶文件，類似 Claude Code 的 CLAUDE.md。Codex 會(huì)在每次會(huì)話開(kāi)始時(shí)自動(dòng)讀取該文件，從而獲得項(xiàng)目特定的指令和約定。

7.2 文件示例

在項(xiàng)目根目錄創(chuàng)建 AGENTS.md：

# AGENTS.md - 項(xiàng)目全局指令
## 項(xiàng)目概述
- 項(xiàng)目名稱：MyWebApp
- 技術(shù)棧：TypeScript + React + Node.js
- 代碼風(fēng)格：ESLint + Prettier，2 空格縮進(jìn)
## 常用命令
- 啟動(dòng)開(kāi)發(fā)服務(wù)器：`npm run dev`
- 運(yùn)行測(cè)試：`npm test`
- 類型檢查：`npm run type-check`
## Codex 行為約定
- 所有組件文件必須包含 PropTypes 或 TypeScript 類型定義
- API 調(diào)用必須包含錯(cuò)誤處理
- CSS 使用 Tailwind，不要寫內(nèi)聯(lián)樣式
## 禁止事項(xiàng)
- 不要在代碼中使用 `any` 類型
- 不要直接修改 `node_modules` 中的文件

7.3 多級(jí)配置優(yōu)先級(jí)

Codex 會(huì)按以下順序合并配置（后者覆蓋前者）：

1. ~/.codex/AGENTS.md（全局）
2. <項(xiàng)目根目錄>/AGENTS.md（項(xiàng)目級(jí)，最優(yōu)先）

八、MCP 擴(kuò)展：無(wú)限可能

Codex 支持 MCP（Model Context Protocol） 協(xié)議，可以集成第三方工具擴(kuò)展功能，例如：

• Context7：獲取最新技術(shù)文檔上下文
• Fetch：從網(wǎng)頁(yè)抓取內(nèi)容
• Sequential Thinking：復(fù)雜任務(wù)的分步推理

配置示例（在 config.toml 中添加）：

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp", "--api-key", "你的_API_Key"]

配置后，Codex 可以主動(dòng)查詢最新文檔，回答基于實(shí)時(shí)文檔的問(wèn)題。

九、資源監(jiān)控與預(yù)算控制

9.1 查看使用情況

codex usage                 # 顯示總用量
codex usage --today         # 今日用量
codex usage --session       # 當(dāng)前會(huì)話用量

9.2 設(shè)置預(yù)算限制

在 ~/.codex/config.toml 中添加：

budget_limit = 10.0
budget_alert_threshold = 0.8

當(dāng)費(fèi)用超過(guò) 8 美元時(shí)給出警告，超過(guò) 10 美元?jiǎng)t自動(dòng)拒絕新請(qǐng)求。

十、常見(jiàn)問(wèn)題與避坑指南

10.1 平臺(tái)相關(guān)問(wèn)題

10.2 使用與安全問(wèn)題

十一、進(jìn)階技巧

11.1 Codex vs Claude Code 對(duì)比

11.2 集成到 CI/CD

在 GitHub Actions 中使用 Codex：

- name: Run Codex quality check
  run: |
    npm install -g @openai/codex
    codex exec --file ci-tasks.toml

11.3 提升 Codex “聽(tīng)話”程度的提示工程

• 明確約束：“只給出代碼，不要解釋” / “給出三種方案并排序”
• 提供示例：在 AGENTS.md 中放入期望的輸入/輸出對(duì)
• 分步要求：“先分析問(wèn)題，再給出解決方案，最后寫代碼”
• 要求驗(yàn)證：“完成后運(yùn)行測(cè)試驗(yàn)證正確性”

總結(jié)

本文從零開(kāi)始，帶你完成了 Codex 在多平臺(tái)（Windows/WSL2、macOS、Linux）的安裝與配置，詳細(xì)講解了核心功能、安全沙盒、AGENTS.md 項(xiàng)目記憶、三種工作模式以及常見(jiàn)問(wèn)題的避坑指南。

快速上手指南：

1. 安裝 Node.js ≥ 22
2. Windows 用戶優(yōu)先安裝 WSL2
3. npm install -g @openai/codex
4. 配置 ~/.codex/config.toml（國(guó)內(nèi)用戶需要指向兼容端點(diǎn)）
5. cd your-project && codex
6. 輸入第一條指令，開(kāi)始使用

以上就是從零到高效開(kāi)發(fā)詳解Codex本地安裝與使用的完全指南的詳細(xì)內(nèi)容，更多關(guān)于Codex安裝與使用教學(xué)的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！

最新評(píng)論