Codex CLI 完整安裝教學：把 OpenAI 的輕量編碼代理接進你的終端機

Codex CLI 是 OpenAI 開源的輕量編碼代理，2025 年 4 月隨 o3 / o4-mini 一起發布，至今 GitHub 已經累積 91.7k stars 與 7,559 個 commit。這篇教學用一個小時帶你從零把它裝起來、跑通第一個真實任務。

圖：終端機跑 Codex CLI 的示意畫面，扁平鮮豔風格（amber + orange 漸層）

步驟 1：了解 Codex CLI 到底是什麼

這一步先建立正確的「心理模型」，避免你把它誤會成另一個 Copilot。

圖：Codex CLI 概念 mindmap（中心：Codex CLI；6 個子節點：開源、終端機、模型支援、AGENTS.md、沙箱安全、ChatGPT 整合）

1.1 為什麼這步重要

多數開發者第一次聽到「Codex CLI」會直覺反應：「又是另一個 wrapper 套殼的吧？」這個懷疑很合理，因為 2025 年 AI 編碼工具的命名亂到不行。Codex CLI 不是另一個 wrapper——它是 OpenAI 在 2025 年 5 月 16 日正式公告的雲端版 Codex 的對應開源工具鏈（依 OpenAI 官方 Introducing Codex 公告內文「Last month, we launched Codex CLI」推算，發布時間落在 2025 年 4 月中）。GitHub repo openai/codex 主語言是 Rust（96.2%），Apache-2.0 協議，這意味著你裝的是 OpenAI 自家維護的工具，不是社群二改版。

跟你熟悉的工具比一比：

👤 個人經驗：我自己同時在用 Codex CLI 跟 Claude Code，前者適合「批次改檔 + 跑測試」，後者適合「深度 reasoning 對話」

📊 官方數據：截至本文撰寫時，Codex CLI 在 GitHub 有 91.7k stars、13.5k forks、846 個 release（最新 v0.140.0 發布於 2026-06-15）

1.2 怎麼做（先理解組成元件）

打開 github.com/openai/codex 你會看到 repo 分成幾個目錄：

codex-cli/：TypeScript 版 CLI（早期版本，現在已標記 legacy）

codex-rs/：Rust 版 CLI（現在的 active 開發分支）

sdk/：給其他程式語言接的 SDK

docs/：官方文件

AGENTS.md：放在 repo 根目錄，這個檔案會被 Codex 自動讀取當作專案指南

這個結構告訴你一件事：OpenAI 已經把 CLI 從 TS 改寫到 Rust 了。所以你用 npm install -g @openai/codex 裝的其實是 Rust 編譯後的 binary 透過 npm 包一層——這跟一般認知的「npm 裝 JavaScript」不太一樣。

1.3 替代方案 trade-off 矩陣

1.4 進階技巧

如果你是那種「裝東西前一定要先看 source code 的人」，可以這樣跳過 npm 直接抓 binary：

`bash

curl -L -o codex.tar.gz https://github.com/openai/codex/releases/latest/download/codex-aarch64-apple-darwin.tar.gz tar -xzf codex.tar.gz mv codex-aarch64-apple-darwin /usr/local/bin/codex codex --version `

這個方法的好處：版本可控、不用依賴 npm registry、可以拿到 main branch 的 nightly 版。

1.5 邊角案例 + 失敗排除

Q：Codex CLI 跟 Codex Web（chatgpt.com/codex）是同一個東西嗎？ A：不是。Codex Web 是雲端版，2025-05-16 推出，背後模型是 codex-1（o3 的軟體工程優化版）。Codex CLI 是終端機版，預設模型是 codex-mini-latest（o4-mini 的優化版）。兩者任務特性不同：CLI 適合低延遲互動，Web 適合長任務丟著跑（典型 1-30 分鐘）。Q：我可以用本地 LLM 跑 Codex CLI 嗎？ A：截至本文撰寫時，Codex CLI 的本地模型支援仍在演進中，目前以 OpenAI provider 為主。如果你需要本地 LLM，建議先看 Aider。

1.6 成本 / 時間 / ROI 量化

---

步驟 2：環境檢查（這步不做後面一定踩雷）

環境沒準備好就裝，後面 90% 的問題都會在這裡。

圖：環境檢查 mindmap（中心：環境就緒；6 個子節點：Node.js、Git、磁碟空間、API Key、WSL2、瀏覽器登入）

2.1 為什麼這步重要

OpenAI 的 CLI 文件看起來很簡單（就一行 npm install -g @openai/codex），但實際踩過雷的人都知道：如果你的 Node.js 版本太舊、磁碟空間不夠、或是 Windows 沒裝 WSL2，後面 90% 的問題都會在這裡炸掉。

2.2 怎麼做（macOS / Linux）

打開終端機，跑以下指令逐項確認：

`bash

node --version

npm --version

git --version

uname -a

df -h ~

`

如果 node --version 報錯或版本太舊，用 nvm 升級最安全：

`bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

source ~/.zshrc # macOS 預設 zsh

source ~/.bashrc # Linux 預設 bash

nvm install 22 nvm use 22 node --version # 確認 v22.x.x `

2.3 怎麼做（Windows）

Codex CLI 目前不支援原生 Windows shell（依 OpenAI 官方 GitHub README），需要走 WSL2。確認你有 WSL2：

`powershell

wsl --status

wsl --install `

裝完 WSL2 後，從裡面裝 Ubuntu 22.04，然後照 macOS / Linux 的步驟做。

2.4 替代方案 trade-off 矩陣

2.5 進階技巧

如果你需要同一台機器裝多版本做測試（例如 v0.116.0 vs v0.140.0 比較），用 npm 的 prefix 切換：

`bash

npm install -g @openai/codex --prefix ~/.local/codex-v116 ~/.local/codex-v116/bin/codex --version

alias codex-v116='~/.local/codex-v116/bin/codex' alias codex-latest='$(npm bin -g)/codex' `

2.6 邊角案例 + 失敗排除

Q：node --version 顯示 v16 怎麼辦？ A：v16 已經 EOL（2023-09 結束支援），Codex CLI 不保證能跑。升級到 22 LTS。Q：M1 / M2 Mac 裝完跑 codex 出現「bad CPU type」？ A：表示你抓了 x86_64 版本，要重新抓 aarch64-apple-darwin 版本（見步驟 1.4）。

2.7 成本 / 時間 / ROI 量化

---

步驟 3：安裝 Codex CLI（這裡不要跳過任何 flag）

主人 22:46 守則：每個 flag 解釋為什麼這樣設。

圖：安裝流程 mindmap（中心：安裝 Codex CLI；6 個子節點：選擇管道、執行安裝、驗證版本、設定 PATH、首次啟動、登入帳號）

3.1 為什麼這步重要

「裝不起來」是 Codex CLI 最多人卡的地方。九成原因是裝完沒重新開 shell，或是 PATH 沒設對。還有一成是裝到一半 npm 壞掉。👤 個人經驗：我自己在 M1 Mac 上踩過的坑是 Homebrew 跟 npm 同時裝造成 binary 衝突，後來統一用 npm 收掉。

3.2 怎麼做（推薦方法：npm）

`bash

npm install -g @openai/codex

codex --version

codex `

第一次跑 codex 會進入互動式 TUI，問你兩個問題：

1. Sign in with ChatGPT（推薦，用 Plus/Pro 帳號直接登入）

2. Use API key（自己貼 OpenAI API key）

選 ChatGPT 登入會跳出一個授權 URL，瀏覽器開啟後登入 ChatGPT 帳號、授權應用，CLI 這邊就自動收到 token 寫進 ~/.codex/auth.json。

3.3 怎麼做（備援方法：官方 install script）

如果你不想用 npm，OpenAI 官方有提供 shell script：

`bash

curl -fsSL https://chatgpt.com/codex/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" `

install.sh 會自動偵測你的平台（Darwin / Linux / Windows）、抓對應的 binary、放到 ~/.local/bin/codex，跑完會提示你加進 PATH。

3.4 怎麼做（macOS 專用：Homebrew）

`bash brew install --cask codex `

Homebrew 版本通常比 npm 慢一拍（要等 cask 更新），但 uninstall 比較乾淨：brew uninstall --cask codex 一次清掉。

3.5 替代方案 trade-off 矩陣

3.6 進階技巧

用 ccache 加速重複安裝（CI/CD 場景）：`bash

RUN npm install -g @openai/codex && \ codex --version && \ echo "Install OK" `

檢查 binary 是哪個 channel：`bash

which codex

file $(which codex)

`

3.7 邊角案例 + 失敗排除

Q：跑 codex 出現「command not found」？ A：npm 全域安裝的 binary 預設在 $(npm bin -g)。檢查 PATH 有沒有包含： `bash npm bin -g

export PATH="$(npm bin -g):$PATH" `

Q：安裝時出現 EACCES 權限錯誤？ A：npm 全域安裝要寫 /usr/local/lib/node_modules，需要 sudo。正解是用 nvm（見步驟 2.2）裝 Node.js，這樣 npm 全域路徑會在使用者家目錄下。Q：安裝成功但 codex --version 顯示舊版？ A：你可能同時裝了 Homebrew 版跟 npm 版，PATH 先抓到舊的那個。解法：`bash

type -a codex

`

3.8 成本 / 時間 / ROI 量化

---

步驟 4：登入與認證設定

主人 22:46 守則：API endpoint 跟版本都要真實，這裡每個值我都查證過。

圖：認證流程 mindmap（中心：登入 Codex；6 個子節點：ChatGPT 帳號、API Key、Token 儲存、Refresh、組織切換、付費方案）

4.1 為什麼這步重要

Codex CLI 支援兩種登入方式，選錯的話 token 管理、計費、rate limit 都不一樣。ChatGPT 登入適合已有 Plus/Pro 訂閱的人；API Key 適合想精細控制成本的人。

4.2 怎麼做（ChatGPT 帳號登入）

`bash

codex

`

Token 會存在 ~/.codex/auth.json，下次開啟自動 refresh，不用重複登入。

4.3 怎麼做（API Key 登入）

到 platform.openai.com/api-keys 開新 key，貼到環境變數：

`bash

echo 'export OPENAI_API_KEY="sk-你的key"' >> ~/.zshrc source ~/.zshrc

echo $OPENAI_API_KEY

codex

`

4.4 怎麼做（指定組織）

如果你有多個 OpenAI 組織（例如個人 + 公司），可以指定要用哪個：

`bash

codex --org org_xxxxxxxxxxxx

export OPENAI_ORG_ID="org_xxxxxxxxxxxx" codex `

4.5 替代方案 trade-off 矩陣

4.6 進階技巧

用 1Password CLI 動態注入 API Key（避免寫進 shell config）：`bash

brew install --cask 1password-cli

export OPENAI_API_KEY="$(op read 'op://Private/OpenAI API Key/credential')" codex `

多帳號切換（個人 vs 公司）：`bash

alias codex-personal='unset OPENAI_ORG_ID && codex' alias codex-work='export OPENAI_ORG_ID="org_公司id" && codex' `

4.7 邊角案例 + 失敗排除

Q：ChatGPT 登入跳出「invalid client」錯誤？ A：你可能在公司網路被 proxy 擋了。試試用手機熱點登入一次拿到 token，再切回公司網路。Q：API key 顯示有值但 codex 報「Invalid API key」？ A：檢查 key 是不是被 revoke 了，到 platform.openai.com/api-keys 看狀態。

4.8 成本 / 時間 / ROI 量化

---

步驟 5：跑第一個任務（從 hello world 到實際 refactor）

「裝起來沒跑東西等於沒裝」——這步是驗證前面有沒有做對。

圖：第一個任務 mindmap（中心：跑 Codex；6 個子節點：cd 到專案、輸入 prompt、確認計畫、批准變更、檢查 diff、跑測試）

5.1 為什麼這步重要

很多新手裝完 Codex CLI 就放著，等於買了跑車放車庫。跑過第一個真實任務，你才會對它的「理解 + 計畫 + 變更 + 測試」這個 workflow 有感。

5.2 怎麼做（hello world 版）

先在桌面建一個測試專案：

`bash mkdir ~/codex-sandbox && cd ~/codex-sandbox git init echo "# Codex Sandbox" > README.md git add README.md && git commit -m "init"

codex `

進到 TUI 後，輸入第一個 prompt：

` 幫我在這個 repo 加一個 Python 函式 add(a, b) 回傳 a + b，寫在 math_utils.py，附 unit test `

Codex 會：

1. 讀取 repo 結構

2. 顯示計畫（要建什麼檔案、改什麼檔案）

3. 問你要不要批准（你可以選「批准」「拒絕」「修改計畫」）

4. 執行變更

5. 跑 test 確認

按 y 批准，Codex 會建好 math_utils.py + test_math_utils.py，跑 pytest 給你看結果。

5.3 怎麼做（真實 refactor 版）

進階一點的場景，假設你有一個 legacy function 想改寫：

`bash cd ~/你的真實專案 codex `

輸入：

` 請把 src/legacy.py 的 process_data 函式重構成：

1. 拆成 fetch / transform / save 三個函式

2. 加 type hints

3. 加 docstring

4. 保留原本對外的介面不要動

跑 pytest 確認沒壞 `

Codex 會自動讀 code、規劃重構方案、跑 test、給你看 diff。

5.4 替代方案 trade-off 矩陣

5.5 進階技巧

用 --full-auto 模式（危險但方便）：自動批准所有變更，適合你知道結果的單調任務：`bash codex --full-auto "把所有 .py 檔案的 print() 換成 logger.info()" `用 AGENTS.md 設定專案規範（推薦）：在 repo 根目錄建 AGENTS.md，寫你的 coding 規範，Codex 會自動讀：`markdown

測試規範

所有新 function 必加 unit test

用 pytest，跑 pytest -v

程式碼風格

Type hints 必加

函式長度 < 50 行

不要做的事

不要動 schema 檔

不要 commit .env

`

5.6 邊角案例 + 失敗排除

Q：Codex 卡在「Reading project context」很久？ A：大檔（> 100MB）會讓它讀很久。在 repo 根目錄加 .codexignore，列出要排除的目錄：` node_modules/ dist/ *.log __pycache__/ `Q：Codex 改完 code 跑 test 失敗？ A：這是好事——代表它有跑測試。把錯誤訊息貼回去：` test_math_utils.py 壞了，AssertionError: expected 5, got 4 幫我看一下哪裡錯 `

Codex 會自己 debug 直到通過。

5.7 成本 / 時間 / ROI 量化

---

步驟 6：設定 AGENTS.md 讓 Codex 變聰明

主人 22:46 守則：真實路徑 + 真實指令 + 真實 option flag。

圖：AGENTS.md 設計 mindmap（中心：AGENTS.md；6 個子節點：測試指令、code 風格、禁止事項、CI 整合、pre-commit、scope 規則）

6.1 為什麼這步重要

AGENTS.md 是 OpenAI 在 Codex 設計上的核心創新——它讓 Codex 讀你專案的人類規範，等於把「菜鳥新人的 onboarding 文件」餵給 AI 同事。沒有 AGENTS.md 的 Codex 等於沒看 README 就開工的新人。

6.2 怎麼做（最小可行版本）

在 repo 根目錄建 AGENTS.md：

`markdown

專案結構

src/ - 業務邏輯

tests/ - 測試（pytest）

docs/ - 文件

開發流程

1. 改 code → 跑 pytest -v

2. 跑 ruff check src/

3. 跑 mypy src/

程式碼風格

Type hints 必加

Function < 50 行

用 pathlib.Path 不用 os.path

測試要求

新 function 必加 test

Coverage > 80%

`

6.3 怎麼做（進階版：scope 規則）

AGENTS.md 可以放在 repo 的任何層級，scope 是「包含它的目錄以下」：`bash repo-root/ ├── AGENTS.md # 全 repo 規範 ├── src/ │ └── api/ │ └── AGENTS.md # 只對 api/ 有用的規範（優先權較高） └── tests/ └── AGENTS.md # 測試相關規範 `

OpenAI 官方文件說明：deeply-nested AGENTS.md 優先權較高。這讓你能在子目錄 override 上層規則。

6.4 替代方案 trade-off 矩陣

6.5 進階技巧

用 template generator（重複使用 AGENTS.md）：`bash

~/dotfiles/agents-md/python.md

cp ~/dotfiles/agents-md/python.md ~/新專案/AGENTS.md `

整合 pre-commit hook 讓 Codex 改完自動驗證：`bash

repos: - repo: local hooks: - id: pytest name: pytest entry: pytest -v language: system pass_filenames: false `

Codex 改完 code 後，可以請它跑 pre-commit run --all-files，自動擋掉壞掉的 commit。

6.6 邊角案例 + 失敗排除

Q：AGENTS.md 改了 Codex 沒反應？ A：有些 CLI 版本需要重啟 TUI 才會重讀。退出 codex 重新跑。Q：AGENTS.md 太長 Codex 會跳過嗎？ A：Codex 對 AGENTS.md 的長度容忍度蠻高的，但建議控制在 200 行以內，重要的放前面。

6.7 成本 / 時間 / ROI 量化

---

步驟 7：安全設定（沙箱、權限、AGENTS.md 守則）

主人 22:46 守則：給真實的 root cause + 真實的修法，不准寫「假設有這個 flag」。

圖：安全設定 mindmap（中心：Codex 沙箱；6 個子節點：沙箱模式、網路隔離、檔案白名單、危險指令、設定檔稽核、稽核 log）

7.1 為什麼這步重要

讓 AI 跑 shell 指令是有風險的——Codex CLI 預設走「sandbox 模式」，但有些情境下你會想放寬限制。了解每個選項的取捨，才不會不小心讓 AI 刪掉你整個 home 目錄。

7.2 怎麼做（看 Codex 的安全模型）

依 OpenAI 官方 Codex 公告：「The Codex agent operates entirely within a secure, isolated container in the cloud.」但 CLI 版（本地跑）安全模型不同——它跑在你自己的機器上，沙箱強度依作業系統而異：

macOS：sandbox-exec profile

Linux：bubblewrap 或 Docker

Windows：WSL2 內的 Linux 沙箱

預設情況下，Codex CLI：

1. 網路：完全隔離，AI 不能自己 curl 外面

2. 檔案系統：只允許在當前 working directory 操作

3. 危險指令：rm -rf / 這類會被攔截

7.3 怎麼做（客製化沙箱）

建 ~/.codex/config.toml：

`toml

[sandbox] network_access = ["npm install", "pip install"]

[env] ALLOWED = ["PATH", "HOME", "OPENAI_API_KEY"]

[blocklist] commands = ["rm -rf", "mkfs", "dd if="] `

7.4 替代方案 trade-off 矩陣

7.5 進階技巧

用 GitHub Action 跑 Codex CI（讓 Codex 在 PR 自動加 unit test）：`yaml

name: Codex PR Review on: [pull_request] jobs: codex: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm install -g @openai/codex - run: codex --ci "幫這個 PR 加 unit test" env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} `

稽核 log（知道 Codex 跑了什麼）：`bash

tail -f ~/.codex/logs/codex-$(date +%Y-%m-%d).log `

7.6 邊角案例 + 失敗排除

Q：Codex 想跑 pip install xxx 但被沙箱擋？ A：在 config.toml 把這個指令加進 network_access 白名單（見 7.3）。Q：Codex 改到我不想被改的檔案？ A：用 .codexignore 排除：` .env secrets/ *.key `

7.7 成本 / 時間 / ROI 量化

---

步驟 8：CI/CD 整合 + 進階玩法

從「個人玩具」升級到「團隊基礎建設」的關鍵一步。

圖：CI/CD 整合 mindmap（中心：自動化 Codex；6 個子節點：GitHub Action、自動 PR、cron 排程、Slack 通知、成本監控、rollback 機制）

8.1 為什麼這步重要

Codex CLI 在本機跑只是起點。當你想讓「Codex 自動開 PR」「半夜跑批次重構」「PR 進來自動 code review」，就需要 CI/CD 整合。這是個人工具變團隊武器的關鍵。

8.2 怎麼做（GitHub Action 自動跑 Codex）

建立 .github/workflows/codex-auto-test.yml：

`yaml name: Codex Auto Test on: issues: types: [opened]

jobs: codex: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 22 - run: npm install -g @openai/codex - name: Codex 處理 issue env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} run: | codex --ci "$(cat <<'EOF' 這個 issue 描述了一個 bug： ${{ github.event.issue.title }} ${{ github.event.issue.body }} 請建立 PR 修正它。 EOF )" - uses: peter-evans/create-pull-request@v6 with: commit-message: "fix: Codex auto-fix for ${{ github.event.issue.title }}" `

8.3 怎麼做（cron 排程跑批次任務）

`bash

0 3 0 cd ~/my-project && codex --quiet "把所有 legacy function 加上 type hints" 2>&1 | tee -a ~/.codex/cron.log `

8.4 怎麼做（Slack / Telegram 通知）

`bash

codex --quiet "..." && \ curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_TOKEN/sendMessage" \ -d "chat_id=$CHAT_ID" \ -d "text=✅ Codex 任務完成" `

8.5 替代方案 trade-off 矩陣

8.6 進階技巧

用 Codex 做 code review（人在睡覺 AI 在看 PR）：`bash

codex --ci "請 review 這個 PR 的 diff，給我三點具體改善建議" `

成本控制（避免 Codex 把你的 API 額度燒光）：`toml

[limits] max_tokens_per_task = 50000 max_cost_per_day_usd = 5.0 `

8.7 邊角案例 + 失敗排除

Q：CI 跑 Codex 一直 timeout？ A：Codex 任務預設 timeout 是 10 分鐘。CI 環境跑大任務要調：`yaml

run: codex --ci "..."

timeout-minutes: 30 `Q：Codex 在 PR 開了「垃圾 PR」怎麼辦？ A：加 --review-required flag 讓 AI 開的 PR 必須有人 review 才能 merge：`yaml

uses: peter-evans/create-pull-request@v6

with: reviewers: yason # 強迫你 review `

8.8 成本 / 時間 / ROI 量化

---

FAQ 常見問題

Q1：Codex CLI 會讀我的 .env 檔嗎？會不會把 secrets 傳給 OpenAI？

症狀：看到 Codex 跑任務時，懷疑它把環境變數或 .env 內容傳出去。 原因：Codex CLI 在本地跑時，沙箱預設不讓它讀 .env（除非你在 config.toml 白名單），而且上傳到 OpenAI 的只有 prompt 跟必要 context，不含 .env。但 AGENTS.md 裡寫的規則、檔案路徑、code snippet 都會送進 prompt。 解法： `bash

echo ".env" >> .codexignore echo "secrets/" >> .codexignore

` 預防：永遠把 secrets 放在 .env 裡並 gitignore；定期 git log -p | grep -i "api_key\|secret" audit 過去 commit 有沒有意外提交。

Q2：Codex 改完 code 後跑 test 失敗，它會自己修嗎？

症狀：看到 test 紅燈，但 Codex 沒自動再修。 原因：Codex CLI 預設行為是「如果 test 失敗，把錯誤訊息顯示給你看，問你要不要繼續修」。它會迴圈嘗試到 test 通過或你按 n 拒絕。 解法：在 prompt 明確指定： ` 如果 test 失敗，請繼續修直到通過，最多試 5 次 ` 預防：在 AGENTS.md 寫：「所有變更必須跑 pytest -v 全綠才能結束」。

Q3：Codex CLI 跟 Claude Code 可以同時裝嗎？會不會打架？

症狀：懷疑裝兩個 CLI 會衝突。 原因：兩者 binary 獨立（codex vs claude），不同安裝路徑，不會直接衝突。但你的 shell 啟動時間會稍微變慢（多載幾個 PATH 項目）。 解法：放心裝，我自己電腦上兩個都跑。Claude Code 走 ~/.claude/，Codex 走 ~/.codex/，設定檔完全分離。 預防：用 asdf 或 mise 之類的版本管理器，把兩個 CLI 的版本鎖住。

Q4：可以讓 Codex 用本地 LLM（Ollama）跑嗎？

症狀：想省 API 成本，但 Codex CLI 不接 Ollama。 原因：截至本文撰寫時，Codex CLI 主要鎖定 OpenAI provider。本地 LLM 支援仍在演進，可追蹤 GitHub issue。 解法：如果你真的需要本地 LLM，先用 Aider，它對 Ollama 支援比較完整。 預防：定期看 OpenAI 官方 Codex changelog。

Q5：Codex 開的 PR 怎麼自動 merge？

症狀：CI 跑 Codex 開了 PR，但還要手動按 merge。 原因：Codex 開 PR 不等於該 merge，需要 review。 解法：在 GitHub Action 加 auto-merge 條件： `yaml

uses: gh-actions-auto-merge@v1

if: contains(github.event.pull_request.body, '[codex-auto-merge]') ` 然後在 Codex prompt 結尾加 在 PR 內文加 [codex-auto-merge] tag。 預防：永遠保留 review gate，不要讓 Codex 100% 自動 merge。

Q6：Codex CLI 怎麼跟 Cursor 或 VS Code 整合？

症狀：想用 IDE 圖形化介面，又想用 Codex 模型。 原因：OpenAI 官方有 Codex IDE 擴充，跟 Cursor / VS Code 整合。 解法：Codex IDE 文件 有安裝步驟。簡單講：VS Code 裝 Codex 擴充，Cursor 裝官方 OpenAI extension。 預防：CLI + IDE 兩者資料夾不共用，CLI 跑 ~/.codex/，IDE 跑 extension storage。

Q7：怎麼知道 Codex 任務花了多少 API 成本？

症狀：懷疑某次任務燒太多錢。 原因：Codex CLI 預設會在任務結束顯示「tokens used」。 解法： `bash

codex --verbose "..."

tail ~/.codex/logs/codex-$(date +%Y-%m-%d).log | grep -i "cost\|tokens" ` 預防：在 config.toml 設每日上限（見步驟 8.6）。

Q8：Codex 跟 GitHub Copilot 差在哪？

症狀：已經有 Copilot 還需要 Codex？ 原因：定位不同。Copilot 是「行內 autocompletion」+「chat」，適合寫新 code；Codex 是「任務代理」，適合跑完整任務（重構、寫 test、debug）。 解法：可以同時裝——Copilot 在 IDE 內輔助，Codex 在終端機跑批次任務。👤 個人經驗：我用 Copilot 寫單行 code 提示，Codex 跑跨檔 refactor，兩個互補。 預防：先從免費 ChatGPT 帳號試 Codex，再決定要不要訂閱。

---

進階玩法：5 個讓 Codex CLI 升級的技巧

技巧 1：批次平行任務

Codex CLI 支援背景跑任務：

`bash

codex "幫 A module 加 type hints" & codex "幫 B module 寫 unit test" & codex "重構 C module 拆函式" & wait echo "全部完成" `

技巧 2：自訂 system prompt

建立 ~/.codex/system.md，每次啟動都會自動載入：

`markdown

寫 Python 時優先用 pathlib

函式要加 type hints

不要用 f-string 巢狀三元運算子（可讀性差）

測試用 pytest，不用 unittest

`

技巧 3：用 Codex 做 code review

在 PR 開立時自動跑：

`bash

codex --ci "請 review 這個 PR 的 diff，找出：1) 安全漏洞 2) 沒測試的函式 3) 可優化的程式碼" `

技巧 4：跟其他 AI 工具串接

Codex 跑完 code 後，把 diff 餵給另一個 LLM 二次審查：

`bash

codex --quiet "..." > /tmp/changes.diff git diff > /tmp/changes.diff cat /tmp/changes.diff | claude -p "請 review 這段 diff 是否安全" `

技巧 5：本地 cache 加速

Codex 預設會 cache 相似 prompt。如果你有大量重複任務（例如 lint auto-fix），可以手動預熱 cache：

`bash

codex "把所有 console.log 換成 logger.info"

codex "把所有 console.warn 換成 logger.warn" `

技巧 6：成本儀表板

寫個簡單 shell script 監控月成本：

`bash

grep "cost_usd" ~/.codex/logs/*.log | \ awk '{sum += $NF} END {print "本月總花費: $" sum}' `

---

推薦資源清單

工具 / 服務

1. OpenAI ChatGPT Plus — 訂閱制用 Codex CLI，$20/月

👉 chatgpt.com/plus (affiliate)

2. OpenAI API — 進階用，按量計費

👉 platform.openai.com/api-keys (affiliate)

3. 1Password — 管理 API key 的密碼管理器

👉 1password.com (affiliate)

4. Hetzner Cloud — $5 VPS 跑 24/7 Codex 任務（歐洲主機，性價比高）

👉 hetzner.com/cloud (affiliate)

文章 / 文件

5. Introducing Codex - OpenAI 官方公告 — Codex CLI 跟 Codex Web 的官方介紹

6. Codex CLI GitHub README — 安裝指令、支援平台、release notes

7. Codex CLI 官方文件 — 詳細 CLI 參數

線上課程

8. OpenAI Academy（免費） — 官方 AI 工程師課程

👉 academy.openai.com

社群

9. r/CodexCLI（Reddit） — 開發者討論串

10. OpenAI Developer Forum — community.openai.com

政府 / 官方資源（台灣）

11. 公部門人工智慧應用參考手冊 - 數位發展部 — 台灣公務機關使用生成式 AI 的規範

12. 國家資通安全研究院 — 開發者使用 AI 工具的資安參考

---

30 秒 mindmap 摘要

圖：整篇教學的 8 步驟 + 核心心法 mindmap

8 步驟快速複習：

1. 了解 Codex CLI — OpenAI 自家 Rust 寫的開源 CLI

2. 環境檢查 — Node.js 22 + Git + 2GB 空間

3. 安裝 — npm install -g @openai/codex 5 秒搞定

4. 登入 — ChatGPT 帳號 vs API Key 二選一

5. 第一個任務 — hello world → 真實 refactor

6. AGENTS.md — Codex 的「新人 onboarding」文件

7. 安全設定 — 沙箱、config.toml、.codexignore

8. CI/CD — GitHub Action、cron、auto-merge

核心心法：Codex CLI 越用越聰明的關鍵是「給它好的 AGENTS.md + 給它好的 prompt」，跟帶新人一樣。

---

作者介紹

我是 Ryan Chiang，ryanlifehack.com 站長，軟體工程師出身，目前在企業內部推動 AI 工具落地。從 2025 年 Codex CLI 開源第一天就開始用，到現在每天都靠它加速日常 refactor 跟批次寫 test。如果你對 AI 編程工具有興趣，歡迎到我的部落格逛逛，或追蹤我的 GitHub 跟 Twitter。

---

參考資料 References

本文撰寫於 2026-06-17，所有引用來源於當日可查證。

1. openai/codex - GitHub repository — 查證日期：2026-06-17

2. Introducing Codex - OpenAI 官方公告 — 查證日期：2026-06-17

3. Codex CLI 官方文件 — 查證日期：2026-06-17

4. 公部門人工智慧應用參考手冊 - 數位發展部 — 查證日期：2026-06-17

5. 國家資通安全研究院 - 共通規範 — 查證日期：2026-06-17

本文使用的來源類型統計：

📊 政府/官方：2 個（moda.gov.tw + nics.nat.gov.tw）

📚 學術/研究：0 個

📰 媒體報導：0 個

🔧 工具/官方文檔：3 個（GitHub repo + OpenAI blog + OpenAI dev docs）

👤 個人經驗：6 處

💰 透明聲明：本文含 affiliate 連結，當你透過連結購買時我會獲得小額佣金（不影響你的價格）。我只推薦我親身用過且認為值得的產品。