Codex 是什麼、怎麼開始:住在你終端機裡的 AI 工程師

如果你用過 ChatGPT 寫程式,一定經歷過這種來回:把檔案內容複製貼上進對話框、它給你一段程式碼、你再貼回編輯器、跑起來發現少改了另一個檔案、又把那個檔案貼過去……一個小功能來回十幾趟,人比 AI 還累。問題不在 AI 不夠聰明,而在它根本看不到你的專案——它只看得到你當下貼進去的那幾行字。

Codex 就是來拆掉這道牆的。它是 OpenAI 出的 AI 編程助手,直接跑在你的終端機裡,能看到你的整個專案、自己開檔案、自己改程式、自己跑指令與測試,做完再回報給你 review。你不再是那個負責搬運程式碼的中間人,而是動口不動手的那個人:講清楚要什麼,剩下的它去做。這堂課帶你認識它、裝好它、跑出第一個任務,並把最重要的安全觀念先建立起來。

這堂課適合誰適合:想用 AI 直接改自己電腦上的專案、但不知道從哪開始的人(本課程屬工程師應用專區)。需要基礎:會開終端機、大概知道 cd 是切換資料夾就夠,零命令列經驗也能跟。前置課:無,這是《Codex 指南》第 1 課。

這堂課學什麼

分清楚 ChatGPT 網頁版與 Codex CLI 各自該用在什麼場合,不再拿錯工具
用 npm 或 brew 把 Codex 裝好,用 ChatGPT 帳號登入(不一定要 API key)
搞懂 Codex 的一個「工作循環」:它怎麼讀專案、提計畫、動手、回報
跑出你的第一個任務,並認識 codex、codex exec、codex resume、codex review 四個子指令
先建立沙箱權限的安全觀念:read-only、workspace-write、danger-full-access 差在哪
知道背後跑的是哪個模型(GPT-5.5 系列),以及怎麼用 /model 切換

觀念一:ChatGPT 網頁版和 Codex,不是同一個東西

很多人第一個誤會,是以為 Codex 只是「ChatGPT 的另一個入口」。其實它們解決的是兩件不同的事。

ChatGPT 網頁版 vs Codex CLI:一個在瀏覽器聊天、一個在終端機動手

ChatGPT 網頁版活在瀏覽器裡,它很會聊天、解釋觀念、寫出一段範例程式碼——但它看不到你電腦裡的檔案,也沒辦法幫你把改動寫回去。你得自己當快遞:把檔案搬給它看、再把結果搬回來。

Codex CLI 則活在你的終端機裡,啟動時它就站在你的專案資料夾中,能直接讀整包程式碼、跨多個檔案一起改、跑測試確認沒改壞。簡單的判斷法:只是想問問題、學觀念,開 ChatGPT 網頁版;想叫 AI 實際動手改你電腦上的專案,才用 Codex(或 Claude Code,第 6 課會拿它們正面比較)。

一個好用的心智模型把 Codex 當成一位剛到職的工程師:他技術很好、打字很快,但不認識你的專案、也不知道你的規矩。你的工作不是自己寫扣,而是把需求講清楚、給足背景,等他做完再 review 放行。這個心態會貫穿整個《Codex 指南》。

觀念二:Codex 的一個工作循環

你下一句話之後,Codex 到底在後台做什麼?與其把它當黑盒子,不如把它拆成一個固定的循環看懂。

Codex 工作循環:你下指令、它讀專案、提計畫、你核准、它動手改並跑測試

整個過程是:你用中文講清楚要做什麼 → 它自己開相關檔案、搞懂結構 → 提出它想怎麼改、要跑哪些指令 → 停下來等你核准 → 通過後才真的動手改檔、執行、回報結果。重點在那個「停下來等你核准」的環節:預設情況下,Codex 動手改檔或執行指令前會先問過你,不會在你沒看到的地方偷偷亂改。這個核准機制怎麼調鬆調緊,是下一課的主題;這堂課你只要記得它預設是保守的、會先問你就好。

也因為有這個循環,你會發現跟 Codex 合作的節奏,跟指揮一個人幾乎一樣:講需求、看它的計畫、放行、驗收。清楚的指令永遠是最關鍵的一環——你講得含糊,它就猜;你講得精準,它就準。

手把手實戰:裝好、登入、跑第一個任務

理論夠了,來實際跑一次。整個安裝到跑出第一個任務,大概十分鐘。

安裝 Codex 的四步:安裝、進到專案、啟動並登入、下第一個指令

安裝 Codex

最通用的方式是用 npm(需要先裝好 Node.js):

npm install -g @openai/codex

如果你是 macOS 而且習慣用 Homebrew,也可以:

brew install --cask codex

裝好後確認一下版本,確定裝成功:

codex --version

會印出類似 codex-cli 0.142.5 的字樣(版本數字會隨你安裝的時間不同,只要跑得出來就對了)。

進到你的專案資料夾

Codex 是「站在哪個資料夾就管哪個專案」,所以要先 cd 進去:

cd ~/my-project

把 ~/my-project 換成你自己的專案路徑。還沒有專案也沒關係,隨便開一個空資料夾練習都可以。

啟動並登入

直接輸入:

codex

第一次啟動會請你登入,有兩條路:一是用 ChatGPT 帳號登入(有 Plus、Pro、Business、Edu、Enterprise 訂閱都能直接用,這是最省事的方式,不用另外處理 API key);二是用 OpenAI API key(適合已經有 API 帳單、想走用量計費的人)。新手選第一條,用瀏覽器點一下授權就完成。

下第一個指令

登入後你會進到互動介面,直接用中文打你要它做什麼,不用背任何特殊語法。三個適合當第一次的安全任務:

這個專案在做什麼?幫我看一下整體架構,用幾句話說明

幫我在 README 補一段「安裝步驟」,照現有的格式寫

src/utils.js 裡的日期格式化在跨月時會算錯,幫我找出來並修好

Codex 會自己去讀相關檔案、提出修改計畫,等你點頭才動手。你的第一個任務建議挑「讀懂與解釋」這種不會改壞東西的,先熟悉它的節奏。

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

codex 只是入口。真正在日常會反覆用到的,是下面這四個子指令,先認得它們,後面幾課會逐一深入。

Codex 四個常用子指令:codex、codex exec、codex resume --last、codex review

codex:開互動模式(TUI),用中文邊聊邊改,是最常用的入口。
codex exec "...":非互動模式,給一句指令、跑完就回,不進對話介面。適合寫進腳本自動化,例如「每天自動整理某份報告」。這課的圖其實就是我用 codex exec 產的。
codex resume --last:接續你上一次的對話。關掉終端機後想繼續昨天的任務,用它就不必從頭再講一次背景。也可以用 codex resume 叫出清單挑一個舊 session。
codex review:叫另一個 Codex 專門幫你審這次改動的程式碼,在 commit 或 push 前先抓一輪 bug。等於請它自己當自己的 code reviewer。

互動 vs 非互動剛開始你幾乎都會用互動模式 codex,因為看得到它每一步、可以隨時插話糾正。等你熟了、開始想把重複性工作自動化,再把穩定的流程搬到 codex exec 寫成腳本。先學會走,再學會跑。

觀念三:它能動到哪裡?先搞懂沙箱權限

這是新手最容易忽略、卻最該先建立的觀念:Codex 能碰你電腦到什麼程度,是你自己設定的。 這個設定叫「沙箱(sandbox)」,用 --sandbox 參數控制,有三個等級。

Codex 三種沙箱權限:read-only 唯讀、workspace-write 可改工作區、danger-full-access 完全放行

read-only(唯讀):只能看、不能改任何檔案,也不能亂跑指令。最安全,適合你只是想讓它「讀懂並解釋」一個陌生專案時用。
```
codex --sandbox read-only
```
workspace-write(可改工作區,實務上的常用檔位):能改你專案資料夾裡的檔案、跑指令,但要碰網路、或動到專案資料夾以外的東西,會停下來問你。日常開發大多用這一檔——放得夠開能做事,又不會失控。
```
codex --sandbox workspace-write
```
danger-full-access(完全放行):不設限,可以碰整台電腦與網路。名字裡有 danger 不是嚇你的——只在你完全清楚自己在做什麼、且環境可拋棄(例如乾淨的容器)時才用,風險自負。
```
codex --sandbox danger-full-access
```

沙箱管的是「能動到多大範圍」,而前面講的核准機制(要不要每一步都問你)是另一個獨立的旋鈕,用 --ask-for-approval 控制,值有 untrusted、on-request、never。這兩個旋鈕怎麼搭配出安全又順手的組合,是下一課的完整主題,這課先記住一句話:破壞性操作(刪檔、改資料庫、推線上)一定自己 review,不確定時就把沙箱調到最保守的那一檔。

舊教學可能過時如果你在網路上看到 --full-auto 這個參數,它現在已被官方標為 deprecated(不建議再用),對應的做法改成直接指定 --sandbox workspace-write。同樣地,核准模式裡的 on-failure 也已被 on-request 取代。Codex 迭代很快,永遠以官方 docs 與你機器上 codex --help 印出來的為準。

觀念四:背後跑的是哪個模型

Codex 不是單一模型,而是跑在 GPT-5 系列上,而且你可以隨時切換。

Codex 的模型:GPT-5.5 推薦預設、GPT-5.4 穩定、GPT-5.4 mini 輕量,用 /model 切換

GPT-5.5:最新的旗艦模型,也是官方推薦、Codex 的預設。大多數任務用它就對了。
GPT-5.4:前一代,速度與品質的平衡選擇。
GPT-5.4 mini:輕量快速,適合小任務、或想追求速度、省用量的場合。

不確定選哪個時,維持預設的 GPT-5.5 就好。想換的時候,在互動模式裡輸入 /model 就能切換模型與推理強度;另外輸入 /usage 可以查你目前的用量(每日、每週、累計的 token 活動),避免不小心用超額度。

關於費用一句話帶過(這課不深入):訂閱制的 ChatGPT Plus 每月約 20 美元、Pro 約 100 至 200 美元,都含 Codex 用量;另外還有更入門的 Go 方案。2026 年 4 月起,Codex 的計費從「按訊息數」改成「按 token 用量」對齊 API,所以 /usage 這個查用量的習慣愈來愈重要。實際額度與價格請以 OpenAI 官方頁面為準,方案偶爾會調整。

常見坑

坑 1:codex: command not found

裝完打 codex 卻說找不到指令,九成是兩種情況。一是根本沒裝成功——用 npm 裝時如果看到一堆 EACCES 權限錯誤,代表全域安裝被系統擋了,別急著用 sudo 硬灌(那會製造更多權限問題),比較乾淨的做法是改用 brew install --cask codex,或先把 Node 換成用 nvm 管理再重裝。二是裝好了但 PATH 沒吃到:關掉終端機重開一個新視窗,或跑 source ~/.zshrc 讓設定生效,通常就好了。

坑 2:登入卡在瀏覽器授權那一步

點了「用 ChatGPT 帳號登入」後瀏覽器開了頁面,授權完卻一直轉、終端機沒反應。多半是你在遠端主機或容器裡跑 Codex,那台機器開不了你本機的瀏覽器。解法:改用 API key 登入,或依官方指示做裝置授權(把網址複製到自己電腦的瀏覽器完成)。另外也確認一下,你登入的 ChatGPT 帳號確實有可用的方案——免費帳號能用的額度非常有限,常見的卡關其實是額度問題偽裝成登入問題。

坑 3:它一直停下來問我核准,好煩

第一次用很多人會嫌它「每改一個字都要問」。這不是 bug,是預設的保守沙箱在保護你。真正該做的不是直接切到 danger-full-access 把所有防護關掉(這是新手最危險的一步),而是理解「沙箱 × 核准」兩個旋鈕怎麼搭——例如信任的專案用 workspace-write 搭上比較寬鬆的核准,就會順很多。這正是下一課要專門講的,先忍一下,別為了省事把安全網整個拆了。

坑 4:它改壞了我沒備份的檔案

Codex 很強,但它會犯錯——這是所有 AI 編程工具的共同前提。如果你在一個沒有用 git 版本控制的資料夾裡讓它大改,改壞了就很難救。務必先讓專案進 git(哪怕只是 git init 加一次 git commit),這樣任何改動都能一鍵還原。搭配前面說的 codex review,在放行大改動前先審一輪,雙保險。

坑 5:找不到某個舊教學裡的指令或選單

Codex 的版本迭代非常快(這課寫作時是 0.14x),半年前的截圖和指令名稱可能就對不上了。遇到「教學裡有、我這邊沒有」的狀況,別懷疑自己——先跑 codex --help 看你這版實際支援什麼,或查官方 changelog。這也是為什麼這門課會不斷提醒你以官方 docs 為準。

作業

把 Codex 裝起來(npm install -g @openai/codex 或 brew install --cask codex),跑 codex --version 確認裝成功,記下你的版本號。
找一個你看不太懂的開源專案(或你自己的舊專案),cd 進去、用 codex --sandbox read-only 啟動,問它「這個專案在做什麼?幫我畫出整體架構」。體會「唯讀」模式下它能讀不能改的感覺。
換到一個有 git 的練習專案,用 workspace-write 啟動,叫它幫你在 README 補一段文字。觀察它「提計畫 → 等你核准 → 才動手」的完整循環,並在放行前真的看一下它要改什麼。
在互動模式裡輸入 /model 看看有哪些模型可選、輸入 /usage 看看你的用量,熟悉這兩個查詢指令。

下一課預告

這堂課你已經讓 Codex 跑起來,也知道它預設會「先問你再動手」。但你很快會遇到一個張力:每一步都核准太慢,全部放行又不安全——到底該讓它自己動到什麼程度? 第 2 課就專門解決這件事,把「沙箱權限」和「核准模式」這兩個旋鈕拆開講透,教你針對不同任務(讀程式、改小功能、大重構)配出既安全又順手的組合,讓 Codex 從「綁手綁腳」變成「放得開又不失控」的好幫手。