Codex 教學：安裝、設定檔與沙箱權限完整指南

Codex 教學完整版：安裝、第一個任務、四個常用子指令、config.toml 的 approval_policy 與 sandbox_mode 怎麼設，以及如何換成自選的模型供應商。指令皆實測。

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

這篇從零開始，涵蓋安裝、第一個任務、四種常用模式、config.toml 每一個你真的會改到的欄位、沙箱怎麼設才不會誤刪東西，最後是怎麼把它接到自己選的模型供應商。本文所有指令都在 codex-cli 0.146 上實跑過；Codex 改版很快，開始前先跑 codex --version 對一下。

版本落差提醒：Codex 的設定欄位有汰換史。你在網路上找到的舊教學若叫你在設定檔寫 wire_api = "chat"，那份設定在現行版本會直接開不起來——本文後面會講正確寫法。

安裝 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 可以逐層放：家目錄一份放個人偏好，專案根目錄一份放團隊規範，子目錄再放一份放該模組的特殊規則。越靠近檔案的優先。

讓它跑在你自己選的模型上

Codex 預設連 OpenAI，但它的模型供應商是可設定的——config.toml 裡加一個 [model_providers.<名稱>] 區塊，指到任何相容的端點就好。實務上會這樣做的理由通常是三個：想拿同一套工作流去跑別家模型、想讓多台機器共用一個計費出口、或是需要台灣的付款與憑證條件。

BazaarLink 是 OpenAI 相容的模型中繼站，所以只要改設定檔、不用改 Codex 本身：

model = "anthropic/claude-opus-4.6"
model_provider = "bazaarlink"

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

然後把金鑰放進環境變數（env_key 指的就是這個變數名稱，Codex 不會把金鑰存進設定檔）：

# macOS / Linux
export BAZAARLINK_API_KEY=sk-bl-你的金鑰

# Windows PowerShell
$env:BAZAARLINK_API_KEY = "sk-bl-你的金鑰"

驗證：

codex exec "回覆兩個字：可以"

三個實測後才知道的坑：

1. wire_api 一定要寫 "responses"。 現行 Codex 已經移除 "chat"，寫了會在啟動時直接噴 wire_api = "chat" is no longer supported 而不是執行到一半才失敗。
2. model 要填供應商目錄裡的完整 id，例如 anthropic/claude-opus-4.6、openai/gpt-5.3-codex、qwen/qwen3-coder-next。填錯會拿到 404。
3. 會看到 warning: Model metadata for ... not found。 這是 Codex 本地的模型參數查表沒命中非 OpenAI 的 id，屬正常現象，任務照跑。

金鑰到 bazaarlink.ai/free 開，免費層可以先把整套流程跑通再決定要不要加值；實際的頻率上限以該頁面標示為準。想知道有哪些模型 id 可以填，看 模型列表。

想切回原本的設定，把 model_provider 那行註解掉就好——[model_providers.*] 區塊留著不會有副作用。

常見問題排除

「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