第 1 篇 入門 · 第 0 章
先搞懂 Codex CLI 是什麼
篇導讀（第 1 篇 入門篇）
適合對象：第一次接觸終端機或 AI 編碼工具的人；不需要先會寫程式。
閱讀方式：第 0 章先把「它是什麼、能幹嘛」講清楚，不用打任何指令、不用安裝；真正動手從第 1 章開始。
第一次閱讀：先讀 0.1 與 0.6，再前往第 1 章。0.2～0.5 是避免看錯舊教學、理解不同入口與產品背景的補充；遇到模型、Rust、cloud、IDE 等名詞時，不必停下來查，真的碰到再回來看即可。
本篇做完你會什麼：知道 Codex CLI 是什麼、它跟「網頁版 / 編輯器版」差在哪；會打開終端機、會切資料夾；在你的電腦（Mac / Windows / Linux）裝好 Codex CLI 並完成登入。
跨工具先讀：〈為什麼要用 AI CLI？〉會先比較聊天網頁、IDE、CLI 與雲端代理，並帶你看第一次安全任務和跨 session 長開發；本章再專心拆 Codex。
別怕！這一章完全不用你動手打指令。我們先花幾分鐘把「Codex CLI 到底是什麼」這件事弄懂，後面安裝、使用才會踏實。
0.1 一句話 + 一個比喻
先給你最濃縮的一句話：
Codex CLI 是一個住在你終端機裡、會自己讀檔、改檔、跑程式的 AI 工程師。
官方（developers.openai.com/codex/cli）是這樣定義它的：
"Codex CLI is OpenAI's coding agent that you can run locally from your terminal. It can read, change, and run code on your machine in the selected directory."
（Codex CLI 是 OpenAI 的編碼代理，你可以在自己的終端機本機執行它。它能在你指定的資料夾裡，讀取、修改、執行你電腦上的程式碼。）"open source and built in Rust for speed and efficiency."
（開源，並以 Rust 打造，追求速度與效率。）
比喻：想像你請了一位不會累、不會抱怨的工程師助手。你不用幫他開編輯器、不用教他怎麼按按鈕——你只要對著終端機（就是那個黑底白字的視窗）用「人話」交辦，他就會自己進到你指定的資料夾，把檔案翻出來看、動手改、甚至跑指令驗證結果。
這裡有幾個新手最容易搞混的詞，先用白話解釋：
- CLI（Command-Line Interface，命令列介面）：就是「用打字指令操作」的程式，跟用滑鼠點按鈕的軟體相反。
- agent / 代理：能「自己決定下一步」的 AI，不是問一句答一句，而是會連續行動（讀檔 → 想 → 改 → 跑測試）。
- terminal / 終端機：你電腦裡那個可以打指令的黑視窗。第 1 章會教你怎麼打開，現在知道有這東西就好。
它實際能幫你做什麼？ 這些都是你會直接對它說的白話需求：
- 「幫我把這個錯誤（bug）修好。」
- 「幫我讀一下這個專案，跟我說它在做什麼。」
- 「幫這個函式補上測試。」
- 「把這份程式碼重構得乾淨一點。」
- 「照這張設計稿，把頁面切出來。」
官方參考
0.2 名字用過兩次：先分清楚「這個 Codex」是誰
在往下看之前，有一個「認錯對象」的陷阱要先提醒你：OpenAI 把「Codex」這個名字用過兩次，而且兩次講的是完全不同的東西。等一下你自己上網查資料時，很可能會不小心翻到舊的那一次，看得一頭霧水。
先講舊的那個。2021 年 8 月，OpenAI 發表過一個叫「Codex」的模型，是拿 GPT-3 微調（fine-tune，用既有模型再加訓練調整成專門用途）出來、專門生成程式碼的模型，也是最早期 GitHub Copilot 背後所用的引擎。這個舊 Codex 後來停止發展，OpenAI 已經在 2023 年 3 月 23 日正式把它從 API 裡下架棄用。
2025 年 5 月，OpenAI 把「Codex」這個名字重新拿出來用——但這一次指的是完全不同的產品：一個能在雲端與終端機裡自主運作的編碼代理（也就是本書從頭到尾在教的這個），早期用的模型代號叫 codex-1、codex-mini，後續模型也一直在換代。
兩者的關係，一句話講清楚：除了共用「Codex」這三個字，新舊兩個 Codex 在技術上完全無關。新的不是舊的「升級版」，是隔了快四年，重新啟用同一個品牌名稱，套在一個性質完全不同的產品線上。
| 比一比 | 舊 Codex（2021） | 新 Codex（2025 起，本書教的） |
|---|---|---|
| 推出時間 | 2021 年 8 月 | 2025 年 5 月 |
| 本質是什麼 | 以 GPT-3 微調出來的程式碼生成模型 | 能自主讀檔、改檔、跑指令的編碼代理（agent） |
| 有沒有「終端機」用法 | 沒有，只能透過 API 呼叫 | 有，本機終端機是它的主要前端之一 |
| 現況 | 已於 2023 年 3 月 23 日從 OpenAI API 正式棄用 | 積極開發中，更新極快 |
重要提醒
網路上搜尋「Codex」，很容易翻到 2021～2023 年之間的舊文章——內容多半在講那個已經棄用的程式碼生成模型，或它跟早期 GitHub Copilot 的關係，跟本書教的終端機工具完全對不上號。一個簡單的判斷法：先看發布時間。2025 年 5 月之前的「Codex」文章或影片，十之八九講的是舊產品；另外，舊 Codex 從沒有「在終端機裡自主行動、讀檔改檔跑指令」這種用法，如果一篇文章對「agent」「終端機」「sandbox（安全圍欄）」這些詞完全沒提，也是一個線索。
這種「同一個名字、指過不同東西」的陷阱，你到第 2 章安裝時還會再遇到一次同類型的坑——連 npm 上的套件名稱都曾經被搞混過，屆時我們會告訴你怎麼避開。
0.3 五個「座位」：CLI 只是其中一個
你可能聽過別人說「我用 Codex」，但講的不一定是同一個東西。因為 Codex 是一整條產品線，同一個 AI 代理，有五個不同的「使用入口」。
比喻：把 Codex 想成「同一位員工」，他有五個工作座位。員工是同一個人（用的是同一套大腦、同一個帳號），差別只在「他坐在哪裡幫你做事」。
| 型態 | 它是什麼 | 在哪裡幫你做事 | 入口 | 平台 |
|---|---|---|---|---|
| Codex CLI（本書主角） | 終端機裡的指令列代理 | 你的本機電腦 | codex 指令 |
macOS / Windows / Linux |
| Codex cloud | 瀏覽器/ChatGPT 內的雲端代理 | OpenAI 的雲端 | chatgpt.com/codex | 瀏覽器 |
| IDE 擴充 | 編輯器側邊欄面板 | 你的本機（透過編輯器） | VS Code / Cursor / Windsurf / JetBrains | 三平台 |
| 桌面 app | 獨立的桌面應用程式 | 你的本機 | codex app 啟動 |
macOS / Windows |
| GitHub @codex | 在 GitHub 上 tag @codex 觸發 |
OpenAI 的雲端 | PR / issue 留言 | GitHub |
（以上五前端為官方資料，共用同一代理與帳號授權，差別在執行位置。）
最關鍵、新手最該記住的一條差別，就是 CLI 跟 cloud「在哪裡執行工作」不一樣：
| 比一比 | Codex CLI（本書） | Codex cloud |
|---|---|---|
| 程式在哪裡跑 | 你自己的電腦 | OpenAI 的雲端容器 |
| 操作介面 | 終端機（打指令） | 網頁瀏覽器 |
| 改的是誰的檔案 | 你本機資料夾裡的檔 | 雲端複製的一份專案 |
| 適合場景 | 不想離開終端機、要動本機檔案 | 把任務丟到背景長跑、自動開 PR |
CLI 與 cloud 的一句話差別
CLI 在「你的電腦」上動你本機的檔案；cloud 在「OpenAI 的雲端」幫你跑。兩者用同一個帳號，但動的不是同一份檔案。
有趣的是，CLI 也能「呼叫」cloud：在終端機裡可以用 codex cloud（挑選雲端任務）、codex cloud exec --env <ENV_ID> "任務"（直接從終端啟動雲端任務），再用 codex apply 把雲端改好的結果拉回本機。所以 CLI 也是進入 cloud 的一個入口——但這屬於進階用法，本書第 11 章才會碰，現在知道有這回事就好。
重要提醒
網路上很多教學會把這五個入口的功能混在一起講。本書從頭到尾只教 Codex CLI（終端機那個）。當某個功能其實是 cloud 或 IDE 才有的，我們會明白標出來，不會讓你拿著「網頁版的招式」對終端機亂打，結果一直失敗還不知道為什麼。
高手小撇步：這五個座位本身也在持續搬家
光是最近，「桌面 app」這一列就經歷過一次改版：2026 年 7 月 9 日起，原本獨立的桌面應用程式被併入了全新改版的 ChatGPT 桌面應用程式裡，跟「Chat」「Work」並列成其中一個分頁，介面上多了 git worktrees（讓你同時開好幾份工作副本並存）與雲端環境、diff（改動差異）審閱畫面。如果你打開電腦上的 ChatGPT 桌面版，卻找不到一個獨立的「Codex app」，不是你裝錯了，是它搬家了。
另外你可能也聽過「手機也能用 Codex」——嚴格說這不算獨立的第六個座位，比較像是幫某個座位加裝了一支遙控器。2026 年 5 月 14 日起，Codex 直接內嵌進大家原本就有的 ChatGPT 手機 App 裡（不是另外一個新 App）：先在 Mac 主機上開啟遠端連線設定，畫面會產生一組 QR code，用手機裡的 ChatGPT App 掃描配對後，就能在手機上看 diff、核准指令、切換模型、發起新任務——實際運算、程式碼本體與登入憑證都還留在你的電腦上，手機只是多一個遠端操控畫面。這個配對功能目前主機端只支援 macOS。
⚠️ 這幾項都屬於介面／產品線的變動，跟 CLI 本身的指令沒有直接關係，本書不會深入教；提到它們純粹是讓你知道 Codex 產品家族比表格看起來還更動態一些，之後你看到的官方畫面如果跟書上不完全一樣，別懷疑是自己裝錯。
官方參考
0.4 開源、Rust、Apache-2.0：這幾個詞跟你有什麼關係
官方介紹 Codex CLI 時，反覆出現三個詞：開源、Rust、Apache-2.0。聽起來很硬，但對你這個使用者其實有很實際的意義。我們一個一個拆。
開源（open source）：程式碼是公開的，任何人都能上 GitHub 看、下載、檢查。Codex CLI 的原始碼放在 github.com/openai/codex。
- 對你的好處：遇到問題時，全世界的人都能一起看程式碼、回報、修正，issue 與討論都公開。
常見誤解：不是整個 Codex 都開源
「開源」這頂帽子，嚴格來說只戴在核心 CLI（原始碼庫裡叫 codex-rs）頭上，也就是本書在教的這個終端機程式。VS Code / IDE 擴充套件、還有0.3 節提到的 ChatGPT 桌面應用程式，並沒有隨附開源原始碼——GitHub 上甚至有讀者專門開 issue 要求官方把 IDE 擴充套件也開源，這反過來證實了「目前還沒有」。如果你想「翻一下 IDE 擴充套件的原始碼研究看看」，會發現根本找不到，不是你找錯地方，是那部分真的沒開放。
Apache-2.0：這是它採用的「開源授權條款」，屬於相當寬鬆的一種，個人與公司都能自由使用。
- 對你的好處：不必擔心「能不能用」的法律問題，放心裝來用就好。
Rust：這是寫這個程式所用的程式語言。Codex CLI 早期是用 Node / TypeScript 寫的，後來整個改寫成原生 Rust，主打「速度與效率」。
- 對你的好處：跑起來輕快；而且現在連用
npm安裝，本質上也是「把預先編好的 Rust 程式打包成 npm 套件」，第 2 章安裝時你會再看到這點。
這個「改寫成 Rust」不是一次到位的事：Codex CLI 在 2025 年 4、5 月剛開源、第一次公開亮相時，其實是一個 Node.js + TypeScript 專案，執行時需要你的電腦另外裝好 Node.js（22 版以上）。2025 年下半年開始，團隊才逐步把核心邏輯搬到原生 Rust；根據第三方在 2026 年初的觀察，程式庫裡 Rust 程式碼的比例已經來到大約九成五，Node.js 版本可以說已經功成身退。
為什麼要花力氣重寫一次？幾個常被提到的理由：擺脫 Node.js 執行環境依賴，使用者不用另外裝一套 Node 才能跑；降低記憶體佔用與 GC 停頓——GC（garbage collection，記憶體回收）是程式語言自動清理不用記憶體的機制，運作時偶爾會讓程式明顯「卡一下」，Rust 沒有這個包袱；以及能不透過 FFI 直接呼叫作業系統原生的 sandbox（安全圍欄）API——FFI 是跨程式語言彼此呼叫時搭的橋接層，少一層橋接，第 6 章會談到的權限管控就能做得更直接。
新手不用記語言名
你完全不需要懂 Rust 才能用 Codex CLI。就像你不需要懂引擎原理也能開車。「Rust」這個詞，知道代表「跑得快、是新版重寫的」就夠了。
但「開源 + 更新極快」帶來一個你一定要養成的習慣，這也是本書最重要的觀念之一：
重要提醒（本書貫穿全程的鐵則）
Codex CLI 更新非常快，常常數天就一個新版（本書對照的是 0.140.0，2026-06-15 釋出）。這代表：指令、旗標、模型名稱、預設值都可能隨版本改變。所以本書每次提到逐字的指令或模型名時，都會請你「以你電腦上實機跑 codex --help 或 /model 的結果、以及官方頁面為準」。不要把任何教學（包括本書）裡的逐字細節當成永遠不變的真理——這不是本書不負責，而是這個工具的本質就是高速演進。這不是誇飾：根據第三方對這個原始碼庫的一次觀察，光是開源至今就已經累積超過 5,000 次 commit、400 多位貢獻者、9,000 多個 fork，release 節奏接近每天一次——你讀到這段的當下，這些數字肯定又更新了。
如果你剛好維護開源專案
「開源」除了讓你安心使用，也代表你能參與：想貢獻程式碼，需要先簽一份 CLA（Contributor License Agreement，貢獻者授權合約）；發現安全性問題，官方提供專用信箱 security@openai.com 回報，不建議直接開公開 issue。另外官方還設了一個「Codex Open Source Fund」，號稱規模上看百萬美元，符合資格的開源專案最高可以申請到 25,000 美元的 API 額度，採滾動式審核（沒有固定的申請截止日，隨到隨審）。這幾項跟一般讀者裝來用的日常操作無關，但如果你本來就有維護中的開源專案，是個值得知道的資源。
0.5 網路上看到的評測數字，能不能信？
認識完 Codex CLI 是什麼之後，你大概會很自然地想問下一個問題：它跟 Claude Code、跟其他同類工具比起來，誰比較強？網路上確實找得到不少「誰贏誰」的評測文章與影片，但在被任何一個排行榜說服之前，有件事值得先弄清楚：這些數字通常不是你想像的那麼「客觀」。
舉一組真實出現過的例子：某篇第三方部落格引用一個叫 Terminal-Bench 2.0 的測試基準，說 Codex CLI 拿下大約 77.3% 的分數、Claude Code 只有 65.4%，看起來 Codex CLI 大勝。但同一篇文章往下讀，另外還引用了一組「盲測」資料——蒙住工具名稱，只讓開發者評審實際產出的程式碼品質——結果卻反過來，67% 的評審比較喜歡 Claude Code 寫出來的程式碼，只有 25% 選 Codex CLI。同一篇文章，兩組數字彼此打架。第三個例子是 Reddit 上一份非正式調查，500 多位開發者投票，65.3% 說自己比較常用 Codex CLI、34.7% 比較常用 Claude Code。
| 資料來源 | 測的是什麼 | 結果 |
|---|---|---|
| Terminal-Bench 2.0（第三方引用） | 自動化基準測試分數 | Codex CLI 勝（約 77.3% vs 65.4%） |
| 同一批文章的盲測評審 | 人工評審實際程式碼品質、不知道是哪個工具寫的 | Claude Code 勝（67% vs 25% 偏好） |
| Reddit 開發者調查（非正式） | 500+ 開發者自陳使用偏好 | Codex CLI 勝（65.3% vs 34.7%） |
三組數字，方法論、樣本數、測試的時間點通通不一樣，甚至同一篇文章裡的兩組數字都能互相矛盾——分數贏了，人工評審卻輸了。這不是哪一組數字造假，而是「哪個工具比較強」這種問題，本來就沒有一個放諸四海皆準、永遠不變的答案：模型本身還在以接近每天的節奏更新，這個月測出來的名次，很可能下個月就洗牌。
比排行榜更準的方法
與其等別人幫你排名，不如拿你手上真正要做的任務，兩邊都實際跑跑看，比較改出來的結果在你自己的專案裡好不好用、順不順手——這比任何網路排行榜都更貼近你會遇到的真實情況。等你跟著本書練到後面幾章、親自動手比較過，會比記住任何一組百分比都更有底氣。
看到任何「A 打贏 B」的標題時，養成先問三個問題的習慣：誰測的（官方、獨立第三方，還是有商業立場的一方）、用什麼任務測的（跟你自己要做的事像不像）、什麼時候測的（兩邊工具是不是都還在用測試當下的舊版本）。三個答案都經得起檢驗，這組數字才值得參考。
0.6 本書範圍與「實機為準」的時效鐵則
最後，把本書的「玩法說明書」交給你，讓你讀起來心裡有底。
本書只教 Codex CLI（終端機版）。 前面說過，Codex 有五個前端。本書聚焦在你本機終端機裡的那個 codex 指令。雲端版、IDE 版、桌面版只有在「跟 CLI 交接」時才會順帶一提，而且會明講「這是 cloud/IDE 的功能」。
下面這張表先讓你心裡有個地圖——接下來幾章我們會去哪、學什麼：
| 我想… | 對應章節 |
|---|---|
| 搞懂它是什麼（就是這章） | 第 0 章 |
| 打開終端機、學會切資料夾 | 第 1 章 |
| 在我的電腦上裝好 Codex CLI | 第 2 章 |
| 第一次啟動並登入 | 第 3 章 |
| 用「說人話」叫它寫程式 | 第 4 章（第 2 篇） |
給它一本「專案守則手冊」（AGENTS.md） |
第 5 章 |
| 安全地讓它動手改檔、搭配 Git | 第 6 章 |
三條「讀本書的心態」，記住了能少踩很多坑：
- 逐字細節以實機為準。 看到指令、旗標（像
--model、-m這種附帶選項）、模型名稱時，如果跟你電腦上看到的不一樣，以你實機codex --help、/model的結果與官方頁面為準。本書已盡量對齊官方，但工具更新比書快。 - 別跟舊教學的指令。 網路上有些舊文章的安裝、登入方式已經過時（例如 Homebrew 的正確寫法、API key 的正確登入旗標，本書第 2、3 章會特別點出常見誤傳）。優先信官方文件與本書。
- 不分 CLI / cloud 的招式不要亂套。 一個指令到底是 CLI、還是 cloud/IDE 的功能，差很多。本書會幫你標清楚，你自己看別的資料時也要留意這條界線。
怎麼隨時查到最新真相？
任何時候想確認某個指令還在不在、某個旗標叫什麼，在終端機打 codex --help（看全部指令）或在互動畫面裡打 /model（看可用模型清單）就行。這兩招會在後面章節反覆用到。
上面這些進階指令名稱同樣可能隨版本微調；codex doctor 的細部旗標、features 子命令的行為，一律以實機 codex doctor --help / codex features --help 與官方頁為最終真相。
本書版本對照
本書內容對照 Codex CLI 0.140.0（2026-06-15 釋出）。CLI 的版本號真相在 GitHub releases（tag 形如 rust-v0.140.0）。你看到的版本若比這個新，屬正常，部分細節可能已微調。
本章小結
一句話收束：Codex CLI 是一個跑在你本機終端機、開源（Apache-2.0）、用 Rust 打造的 AI 編碼代理；它是「Codex 五個前端」中專屬終端機的那一個，本書只教這一個，而且所有逐字細節都以你實機跑出來的結果為準。順帶一提：它跟 2021 年那個同名的舊模型完全是兩回事，網路上「誰比較強」的排行榜也只能參考、不必盡信——真正準的答案，永遠是你自己動手比出來的。
動手試試（不用安裝，純認識）
- 打開瀏覽器，逛一下官方總覽頁 developers.openai.com/codex/cli，找找看那句 "run locally from your terminal" 的原文，跟 0.1 節對照。
- 在 0.3 節的「五個座位」表格裡，用一句話跟自己說明：CLI 跟 cloud 最大的差別是什麼？（提示：程式在「哪裡」跑。）
- 假如你自己在網路上翻到一篇標題寫「Codex」、卻完全沒提到終端機或 agent 自主行動的舊文章，練習用 0.2 節教的判斷法，猜猜看它講的是不是本書在教的這一個。
- 下次看到「A 工具打贏 B 工具」這種標題，練習先問自己一句：這是誰測的？用什麼任務測的？什麼時候測的？（0.5 節的三個提問。）
- 記住一個本書會反覆出現的口訣：「逐字細節，實機
codex --help//model為準。」 下一章我們就要真的打開終端機了。