開發工具2026年9月23日

Codex CLI 實戰教學：讓 OpenAI 在你的終端機裡幫你寫程式

AI 觀察家

專欄作者 · 3151 字

如果你最近在 Twitter 或 Hacker News 上看到有人貼出一堆終端機截圖，說自己用 Codex CLI 直接在命令列叫 AI 幫忙寫、改、解釋程式碼——那個東西真的沒你想的那麼複雜。這篇就是要讓你從零跑起來，順便把幾個常見坑先繞掉。

做完這篇你會得到：一個可以在任何專案目錄下呼叫、真正整合進開發流程的 AI 編程助手，不是另一個開著沒在用的網頁 tab。

你需要準備什麼

先把前置條件清掉，省得到一半卡住：

Node.js 18+（node -v 確認）
OpenAI API Key（帳號要有餘額，Codex CLI 吃的是 codex-1 或 o4-mini 等模型）
熟悉基本終端機操作就夠，不需要特別的 Python 環境
macOS / Linux 最順，Windows 用 WSL2 也可以跑

如果你還不確定自己該用 API 直接串還是走 RAG 架構，可以先看看這篇 Fine-tuning vs RAG 的比較，搞清楚自己的需求再繼續。

步驟一：安裝 Codex CLI

npm install -g @openai/codex

裝完用 codex --version 確認有沒有吐出版本號。如果出現 command not found，通常是 npm global bin 路徑沒加進 PATH，檢查一下 ~/.bashrc 或 ~/.zshrc。

截至 2026 年 Q3，Codex CLI 的版本在 0.1.x 系列，還在快速迭代，建議偶爾跑一次 npm update -g @openai/codex 保持最新。

步驟二：設定 API Key

最簡單的方式是設環境變數：

export OPENAI_API_KEY="sk-proj-..."

想要永久生效就把這行加進 shell 的 rc 檔，或是在專案根目錄建一個 .env（記得加進 .gitignore，不然你懂的）。

Codex CLI 也支援直接跑 codex 後用互動模式輸入 key，但這個方式每次重開 session 都要重輸，適合一次性測試用。

步驟三：跑第一個指令，感受一下

codex "幫我解釋這個 repo 的結構"

白話講就是：你在哪個目錄下執行，Codex CLI 就會把那個目錄的檔案結構餵給模型，然後給你一段說明。

幾個常用的使用模式：

解釋現有程式碼：codex "explain src/index.ts"
生成新功能：codex "新增一個 rate limiter middleware，用 express"
除錯：把錯誤訊息直接貼進去，codex "這個錯誤怎麼修：[error message]"
寫測試：codex "幫 utils/parser.ts 寫 Jest unit tests"

Codex CLI 預設會在 Suggest 模式下跑，只給建議不直接動你的檔案。想讓它真的寫入，要加 --approval-mode auto-edit 或在互動模式裡手動確認。

步驟四：調整模型與細節設定

Codex CLI 預設用 codex-1，但你可以用 --model 切換：

codex --model o4-mini "快速幫我 review 這段 SQL"

o4-mini 比較快也便宜，適合不需要很深度推理的任務。codex-1 對 coding 任務有針對性優化，複雜重構或多檔案修改時效果明顯好一截。

如果想控制 context 範圍，可以用 --context 指定要餵給模型的路徑：

codex --context src/api/ "這些 route handler 有沒有明顯的安全問題"

這樣就不會把整個 repo 都丟進去，既省 token 又讓回答更精準。順帶一提，OpenAI API 的定價邏輯有幾個坑之前整理過，用 Codex CLI 之前最好先看一下，免得帳單暴衝。

步驟五：把 Codex CLI 真正整合進工作流

光是會用指令還不夠，讓它變成你 daily workflow 的一部分才是重點。幾個我覺得實際有用的整合方式：

Git pre-commit hook：在 commit 前自動跑一次 codex "review 這次 diff 有沒有明顯 bug" 當作最後一道防線。

Makefile 或 package.json scripts：

"scripts": {
  "ai:review": "codex 'review the latest changes in src/'",
  "ai:test": "codex 'generate missing tests for changed files'"
}

VS Code terminal 快捷鍵：把常用的 codex 指令綁成 task，不用每次手動打。

如果你的專案有用到 AI agent 架構，可以搭配看看 Claude Code AI Agent 的實作方式，兩個工具思路不太一樣，但可以互補。

常見錯誤與怎麼避開

「Rate limit exceeded」：Codex CLI 對話式的連續呼叫很容易打到速率限制，尤其是 free tier。建議在 .codex/config.json 設 "delayBetweenRequests": 1000（單位毫秒）。

Context 太大，回答品質下降：如果你直接在一個幾百個檔案的 monorepo 根目錄跑，模型容易迷失方向。解法就是前面說的 --context 限縮範圍，或是用 .codexignore（格式跟 .gitignore 一樣）排掉 node_modules、build 產物這些廢話。

生成的程式碼直接跑起來不對：Codex CLI 建議永遠用 Suggest 模式先看過，不要第一次就開 auto-edit，尤其是在有資料庫操作或 infra 相關的任務上。

Windows PowerShell 環境變數設不起來：改用 WSL2 是最乾淨的解法，或是用 cross-env 套件包一層。

進階技巧：用 `.codex/instructions.md` 鎖定上下文

這個不是每個人都知道的功能：你可以在專案根目錄建一個 .codex/instructions.md，寫進這個 repo 的背景資訊、coding style、不能動的禁區——Codex CLI 每次執行都會自動把這個檔案的內容加進 system prompt。

舉個例子，你可以寫：

# 專案說明
這是一個 NestJS + TypeScript 的後端服務，部署在 AWS Lambda。
- 所有 API response 格式統一用 `ApiResponse<T>` wrapper
- 不要動 src/legacy/ 目錄下的任何東西
- 測試框架用 Jest，不要改成 Vitest

這樣模型就不會每次都搞不清楚你用什麼 stack，或是突然給你一個 Python 解法。

跑完之後：確認你真的整合成功

幾個檢查點：

codex --version 有版本號輸出
codex "hello" 有正常回應（代表 API key 設定正確）
在你實際的專案目錄下跑過一次真實任務（不是測試用的空資料夾）
.codexignore 有排掉 node_modules 和 build 目錄
已經把 OPENAI_API_KEY 加進 .gitignore 保護的地方，沒有硬寫在程式碼裡

下一步可以考慮的方向：設定 CI pipeline 裡的自動 code review、或是研究 Codex CLI 的 --format json 輸出模式，把它的回應接進自己的工具鏈做進一步處理。這東西還在快速演化，2026 年底之前估計 API 還會有不少變動，訂一下 OpenAI changelog 是個好習慣。

常見問題

Codex CLI 和直接用 ChatGPT 問問題有什麼差別？

最大差別是 Codex CLI 直接在你的終端機環境裡跑，可以自動讀取當前目錄的檔案結構和程式碼內容作為 context，不需要你手動貼程式碼進去。它也可以直接寫入檔案，比較像一個整合在開發環境裡的 coding agent，而不只是聊天視窗。

Codex CLI 使用費用怎麼計算？會不會很貴？

費用走的是你 OpenAI 帳號的 API 用量，依你選的模型計費。用 o4-mini 跑一般的 code review 或解釋任務成本很低，但如果你開了 auto-edit 模式讓它連續修改多個檔案，context 累積下來 token 消耗會明顯上升。建議先設一個 API 用量上限警示，避免帳單暴衝。

Codex CLI 在 Windows 上可以用嗎？

可以，但建議走 WSL2（Windows Subsystem for Linux）而不是直接在 PowerShell 或 CMD 跑。原生 Windows 環境下環境變數設定比較麻煩，而且部分 shell 整合功能在 PowerShell 底下行為不穩定。WSL2 + Ubuntu 是目前最少坑的 Windows 使用

.codexignore 是必要的嗎？

嚴格說不是必要，但強烈建議加。如果沒有 .codexignore，Codex CLI 在有 node_modules 的目錄下執行時會試圖把那幾萬個檔案都納入 context，不只讓回應速度變慢，還會大量消耗 token 且讓模型的回答焦點分散。格式跟 .gitignore 一樣，直接複製過來用就行。