Codex CLI 教學：安裝、doctor 與 sandbox_mode 權限設定

Codex CLI 安裝、登入與第一個任務

Codex CLI 是在終端機中讀取與修改專案檔案的 OpenAI coding agent。先安裝 CLI、在專案目錄啟動並登入，再從小任務開始；你可以選 ChatGPT 登入或以 OpenAI API key 使用量計費。官方文件核對日：2026-09-24。

安裝與登入

1. 依官方 Codex CLI 安裝頁選擇作業系統；npm 安裝可用 npm install -g @openai/codex@latest。
2. 進入 Git 專案資料夾執行 codex，首次啟動選擇 ChatGPT 登入或其他可用方式。
3. 如選 API key，先在 OpenAI Platform 專案建立 key，存入 OPENAI_API_KEY，並依官方登入方式執行 printenv OPENAI_API_KEY | codex login --with-api-key。PowerShell 可用 $env:OPENAI_API_KEY | codex login --with-api-key。
4. 執行 codex login status 確認目前登入方式；接著先請它說明專案，再交代範圍明確的小任務。

Codex CLI 安裝與認證文件：官方 CLI quickstart、Codex Authentication、OpenAI project key 管理。核對日：2026-09-24。ChatGPT 訂閱登入和 API key 登入採不同計費方式；API key 使用按 OpenAI API 價格計費。OpenAI 官方將 ChatGPT 和 API Platform 帳務分開管理，核對日：2026-09-24：ChatGPT 與 API Platform 帳務說明。

第一個 API 請求與相容端點

若要在終端直接呼叫 OpenAI API，Responses API 使用 OPENAI_API_KEY：

export OPENAI_API_KEY="你的 OpenAI project key"
curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-sol","input":"用一句繁體中文說明 Codex CLI。"}'

若使用 BazaarLink 的 OpenAI 相容 Responses API，model ID 以公開目錄為準：

export BAZAARLINK_API_KEY="你的 BazaarLink 金鑰"
curl https://api.bazaarlink.ai/v1/responses \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-sol","input":"用一句繁體中文說明 Codex CLI。"}'

Codex CLI 的自訂模型設定依 OpenAI 官方 config reference 使用 Responses protocol；不要把 API 呼叫範例與 Codex 的 ChatGPT 登入混為一談。需查看本機模型選擇與用量限制，接著讀Codex 額度與用量上限；安裝細節另見英文 Codex CLI 安裝指南。模型資訊核對日：2026-09-24：Codex CLI config reference、OpenAI GPT-6 Sol 定價、BazaarLink GPT-6 Sol 頁。

OpenAI API key 申請與台灣付款憑證整理在OpenAI API 台灣採購指南；要比較 Claude Code，可看Claude CLI 教學。

Codex 是 OpenAI 的終端機編碼代理：你在專案資料夾裡打一句話，它自己讀檔案、改程式、跑測試，做完把 diff 攤在你面前。和把程式碼複製貼進聊天視窗最大的差別是——它真的動得到你的檔案系統，所以「權限」跟「沙箱」才是這篇教學的重點，而不是怎麼下 prompt。

本文涵蓋安裝、第一個任務、常用模式、config.toml、沙箱與自訂模型設定；Codex CLI 更新較快，操作前請先執行 codex --version，並以官方文件核對目前選項。用量與方案差異另見Codex 額度與用量上限與AI API 價格比較。

Codex CLI 的自訂 provider 設定依安裝版本為準；官方 config reference 列出 base_url、env_key 與 wire_api 欄位，並使用 Responses protocol。核對日：2026-09-24。

安裝 Codex CLI

Codex 以 npm 套件發布：

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

macOS 使用者也可以走 Homebrew（注意是 cask，不是 formula）：

brew install --cask codex

Windows 直接用上面的 npm 指令即可，不需要 WSL。

裝完先在任意專案裡跑 codex doctor，它會檢查安裝、設定檔、認證與執行環境，比自己猜哪裡壞掉快得多。

第一個任務：讓它改一支檔案

cd 到一個有 git 的專案（Codex 預設要求 git repo，因為它靠 git 幫你保留反悔的餘地），然後：

codex

進入互動介面後，直接用中文描述你要什麼：

把 src/utils/date.ts 裡的 formatDate 改成支援 timezone 參數，並補上對應的單元測試

它會開始讀檔、提出要執行的指令、等你核准，改完後印出 diff。這時候你有三個選擇：接受、要求它修正、或直接 git checkout . 全部丟掉。養成「先 commit 再叫 Codex 動手」的習慣，你就永遠有一條退路。

想跳過互動介面、把它塞進腳本裡，用 exec：

codex exec "修掉 eslint 現在報的所有 no-unused-vars"

四個你真的會用到的子指令

codex resume 特別值得記——Codex 的 session 是可以續的，改到一半被會議打斷不用重新交代脈絡。想從某個時間點分岔出另一條路線，用 codex fork。

設定檔：~/.codex/config.toml

這是整個工具的控制面板。Windows 在 C:\Users\<你>\.codex\config.toml。最小可用的設定長這樣：

model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

三個欄位的意思：

model — 要用哪個模型。也可以每次啟動臨時覆蓋：codex -m gpt-5.3-codex。

approval_policy — 什麼時候要問你。三個值：

• untrusted：只有 ls、cat 這類安全指令自己跑，其他一律問你。最保守。
• on-request：模型自己判斷什麼時候該問。日常平衡點，建議從這個開始。
• never：完全不問。只在你已經確定沙箱夠緊的情況下用。

sandbox_mode — 它能碰到什麼。三個值：

• read-only：只能讀，不能寫、不能連網。拿來做程式碼導讀最安全。
• workspace-write：可以改目前工作目錄底下的檔案。九成情境用這個。
• danger-full-access：整台機器隨便它動。除非你人在容器或 VM 裡，否則不要。

還有一個沙箱預設會咬人的地方：workspace-write 底下對外網路預設是關的。所以它跑 npm install 或任何要連線的指令會失敗，而且失敗訊息不一定講清楚是網路被擋。要開就明講：

[sandbox_workspace_write]
network_access = true

approval_policy 和 sandbox_mode 是兩個獨立的閘門，很多人以為設了其中一個就安全了。實務上最舒服的組合是 on-request + workspace-write：它可以自由改專案內的檔案，但要跑 rm -rf 或裝東西時會停下來問你。

想讓它多寫一個目錄，啟動時加 --add-dir：

codex --add-dir ../shared-types

用 AGENTS.md 教它你的專案規矩

在專案根目錄放一個 AGENTS.md，Codex 每次開工都會讀。這是投報率最高的一步——與其每次都在 prompt 裡重講一次「我們用 pnpm 不是 npm」，不如寫進去一次：

# AGENTS.md

- 套件管理用 pnpm，不要用 npm 或 yarn。
- 所有 API 回應型別放在 `src/types/api.ts`，不要就地定義 interface。
- 改完一定要跑 `pnpm test -- --run` 確認綠燈才回報。
- commit message 用繁體中文，格式 `type(scope): 說明`。

AGENTS.md 可以逐層放：家目錄一份放個人偏好，專案根目錄一份放團隊規範，子目錄再放一份放該模組的特殊規則。越靠近檔案的優先。

自訂 OpenAI 相容 Responses 端點

Codex CLI 的自訂 provider 以 Responses API 通訊。以下欄位依 OpenAI 官方 config reference；BazaarLink model ID 取自公開目錄。環境變數保存金鑰，設定檔只放變數名稱。

model = "gpt-6-sol"
model_provider = "bazaarlink"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.bazaarlink]
name = "BazaarLink"
base_url = "https://api.bazaarlink.ai/v1"
wire_api = "responses"
env_key = "BAZAARLINK_API_KEY"

macOS／Linux 可設定 export BAZAARLINK_API_KEY="你的 key"；Windows PowerShell 使用 $env:BAZAARLINK_API_KEY = "你的 key"。之後在專案目錄啟動 codex，先讓它說明目前工作目錄，再交付小範圍任務。模型 ID 和價格先看 公開目錄與 GPT-6 Sol 模型頁。

官方設定欄位核對日：2026-09-24：Codex config reference。此處 Codex 設定使用 Responses API；前面的 Chat Completions 範例是給採用 OpenAI SDK 格式的一般應用使用。

CLI 錯誤排查

若看到 Model metadata for ... not found，先核對 model ID、provider 與 CLI 版本；官方 issue tracker 討論了模型 metadata fallback 可能影響功能的情況：Codex CLI issue #34739。核對日：2026-09-24。

「not a git repository」開不起來 — Codex 預設要求 git repo。臨時測試可以加 --skip-git-repo-check，但正式工作請乖乖用 git，不然你沒有反悔的手段。

它一直問我要不要執行指令 — approval_policy 設得太保守。從 untrusted 調到 on-request。

它說沒有權限寫檔案 — sandbox_mode 是 read-only，改成 workspace-write。若要寫的檔案在工作目錄外，用 --add-dir 加進來。

改壞了想全部還原 — git checkout .（未 commit 的變更）或 git reset --hard HEAD（含已 stage 的）。這就是為什麼要先 commit。

設定改了沒生效 — 加 --strict-config 啟動，它會對設定檔裡不認得的欄位直接報錯，而不是安靜忽略。打錯字時特別有用。

小結

Codex 的學習曲線不在 prompt，在於搞清楚 approval_policy × sandbox_mode 這個二維表格，以及願不願意花十分鐘寫 AGENTS.md。這兩件事做完，它從「有趣的玩具」變成「可以交付工作的同事」。

自訂模型端點可依官方設定欄位調整，所以你不必為了試別家模型重學一套工具——改四行設定就好。

台幣計費・統一發票・主流 AI 模型・OpenAI 相容 API