Hub Codex CLI 完整教學

第 1 篇 入門 · 第 1 章

踏出第一步：打開終端機

終端機是一個用「打字」跟電腦對話的小視窗，而 Codex CLI 就住在這個視窗裡。

想像一下：平常你用滑鼠點來點去操作電腦，就像跟店員比手畫腳點餐。終端機則是另一個櫃台——你直接「打字」告訴電腦要做什麼，它照做。Codex CLI 這位 AI 工程師，工作的地方就在這個打字櫃台。所以在認識它之前，我們得先學會怎麼打開這個視窗、怎麼在裡面走動。

別怕！這一章不寫任何程式，只是帶你熟悉「環境」。就像搬進新家前先認門牌、認房間。你會學到三件事：

  • 終端機是什麼，以及在你的電腦上怎麼打開它；
  • 三個最基本的走動指令（cd / ls / pwd），還有「工作目錄」這個關鍵概念；
  • 為什麼在叫 Codex 動手之前，最好先用 Git 存個檔。

這章的定位

Codex CLI 怎麼安裝、怎麼登入，是下一章（第 2 章）和第 3 章的事。這一章只負責把「家門」打開，讓你之後跟得上。

1.1 終端機是什麼、三平台怎麼打開

終端機（Terminal）有很多別名：命令列（Command Line）、終端、console、shell 視窗……指的都是同一個東西：一個你打指令、電腦回你結果的純文字視窗。

它長得樸素，通常黑底白字，沒有按鈕、沒有圖示。第一次看到會有點陌生，但這正是 Codex CLI 運作的舞台——因為它是「跑在你終端裡的輕量編碼 agent」（Lightweight coding agent that runs in your terminal），不打開終端機，就見不到它。

為什麼工程師愛用終端機？

因為打字下指令比點滑鼠快、可以精準重複、還能寫成腳本自動化。你現在不用懂這些好處，先學會打開它就好。

每個作業系統打開終端機的方式不太一樣，下面分平台帶你做。

🍎 macOS：打開「終端機」App

Mac 內建一個叫「終端機」（Terminal）的程式，不用另外安裝。

  1. 按鍵盤的 Command + 空白鍵，打開 Spotlight 搜尋。
  2. 輸入「終端機」或「Terminal」。
  3. 按 Enter，終端機視窗就跳出來了。

你也可以從「應用程式 → 工具程式 → 終端機」找到它。

進階選擇 iTerm2

很多 Mac 開發者改用免費的 iTerm2 取代內建終端機，功能更多、更好用。新手用內建的「終端機」就完全夠了，等熟了再換不遲。

🐧 Linux：各家發行版略有不同

Linux 幾乎一定內建終端機，只是不同發行版（Ubuntu、Fedora、Debian……）入口名稱略有差異。最通用的兩招：

  • 快捷鍵：大多數桌面環境按 Ctrl + Alt + T 就能直接開啟終端機。
  • 從選單找：在應用程式選單搜尋「Terminal」「終端」或「Console」。

🪟 Windows：新手先用 Windows Terminal 裡的 PowerShell

Windows 的情況稍微多一層，因為它有好幾種命令列環境。對 Codex CLI 來說，你會用到的是這兩個：

環境 怎麼打開 新手建議
PowerShell 按 Windows 鍵，開「Windows Terminal」；若分頁不是 PowerShell，從下拉選單選它 ✅ 第一次請選這個；之後所有 Windows 指令都在同一個 PowerShell 視窗跑
WSL2（Windows 內的 Linux） 只在你主動要 Linux 環境時，先依官方流程安裝，再開「Ubuntu」之類的 Linux 終端 可選的另一條路；不要和 PowerShell 混著安裝／找指令

不要先為了 Codex 裝 WSL

WSL2（Windows Subsystem for Linux 2）是在 Windows 裡新增一套獨立 Linux，不是 Windows Terminal 的必要設定。完全新手先在 PowerShell 做完第 1–3 章；只有你明確想用 Linux、或團隊文件指定 WSL 時才選它。兩邊的 Node、Git、Codex、PATH 與專案位置互不共用，所以選定後請固定在同一邊繼續。

PowerShell 其實有兩支，先分清楚

「PowerShell」這個名字背後藏著兩支不同的程式：電腦內建、比較舊的 Windows PowerShell 5.1（執行檔 powershell.exe），和另外獨立推出、可跨平台的PowerShell 7（執行檔 pwsh.exe）。開始選單搜尋「PowerShell」，你可能會同時看到兩個很像的圖示，這是正常的。想確認自己打開的是哪一支，在視窗裡打一行：

$PSVersionTable.PSVersion

Major 那一欄顯示 7 就是新版；顯示 5 就是系統內建的舊版。兩者在文字編碼上不完全一致，舊版偶爾會讓中文字元或某些指令輸出跑出亂碼。現在只要有個印象即可，之後貼書裡的指令碰到顯示怪怪的，回頭檢查版本會是排除故障的第一步。

只有選 WSL 時才做：先完成它自己的首次設定

依 Microsoft 官方步驟以系統管理員開 PowerShell 執行 wsl --install，並依提示重新啟動。第一次開 Ubuntu 時要建立 Linux 使用者名稱與密碼；密碼輸入時畫面不顯示字元是正常的。完成後，後續 Linux 指令都在 Ubuntu／WSL 視窗執行，不要回到 PowerShell 期待看到同一份安裝。

WSL2 使用者的效能陷阱：專案別放在 /mnt/c/ 底下

WSL2 裡可以直接看到 Windows 的 C 槽，路徑長得像 /mnt/c/Users/你的名字/...，不少人會貪方便直接把專案放在這種「跨系統掛載」的路徑下工作。盡量別這樣做——這類路徑的讀寫速度比 WSL2 自己的 Linux 檔案系統慢上不少，資料夾裡的檔案越多，落差越明顯。正確做法是把專案搬進 cd ~ 之後看到的那個 Linux 家目錄裡，例如整理成 ~/projects/我的網站 這樣的結構。這條「工作目錄放哪裡」的判斷，下一節就會正式介紹，記住了對之後帶 Codex 處理較大的專案會特別有感。

不同終端機之後會有差別

你選哪個終端機軟體（內建 Terminal、iTerm2、Ghostty、Alacritty、Warp……），在「貼圖片給 Codex」這種進階操作時會踩到不同的雷——有些終端機只能貼文字、貼不了圖。現在你完全不用管，先把終端機打開就好；到第 4 章談「丟截圖給它」時，我們會回頭提醒這件事。

高手小撇步（先預告，現在不用做）

Codex CLI 的畫面預設會切到終端機的「全螢幕替代畫面」（alternate screen），好處是介面乾淨，但缺點是你用 tmux、想螢幕錄製、或想事後往上捲看 log 時不太方便。官方提供一個旗標 --no-alt-screen（官方逐字描述為「Disable alternate screen mode for the TUI」），讓輸出留在主捲動緩衝區、方便事後翻閱與錄製。這是進階用法，等你熟練後在第 4 章／第 7 章會用到，現在先有個印象就好。

⚠️ 旗標名稱以你實機跑 codex --help 看到的為準（Codex CLI 數天一版）。

1.2 基本指令熱身（cd / ls / pwd）與「工作目錄」

終端機打開了，你會看到一個閃爍的游標，在等你打字。我們先學三個最基本、也最安全的指令來熱身——它們只是「看」和「走動」，不會改壞任何東西。

這三個指令在 🍎 macOS、🐧 Linux 上完全一樣；🪟 Windows 的 PowerShell 也都認得（PowerShell 貼心地把這些常用名字都做了對應），所以你照著打就行。

pwd：我現在站在哪個資料夾？

pwd 是 print working directory 的縮寫，意思是「印出我目前所在的資料夾」。

pwd

✅ 預期會看到類似這樣的一行路徑（代表你目前站在哪）：

/Users/你的名字

「絕對路徑」與「相對路徑」

pwd 印出來這種從最頂層寫到底的完整路徑，叫絕對路徑——不管你現在人站在哪裡，這條路徑永遠指向同一個地方（🍎 macOS／🐧 Linux 一定以 / 開頭；🪟 Windows 則是磁碟機代號，例如 C:\Users\你的名字）。等一下你會看到 cd Desktop 這種只寫「相對於目前位置」的寫法，叫相對路徑——同一句 cd Desktop，站在不同資料夾打，會走進完全不同的地方。之後不管是跟 Codex 說話、還是在設定檔裡填路徑，分不清這兩者常常是踩雷的起點，現在有個印象就好。

ls：這個資料夾裡有什麼？

ls（list）會把目前資料夾裡的檔案和子資料夾列出來。

ls

✅ 預期會看到一排檔名和資料夾名，例如：

Desktop    Documents    Downloads    Pictures

PowerShell 小提醒

在 Windows PowerShell 裡，ls 和 pwd 都可以用（它幫你對應到內建指令）。如果你看到的是 WSL2 的 Linux 終端機，那就跟 Mac/Linux 完全一樣。

剛剛看到的都是「一般」檔案和資料夾。但還有一種以小數點 . 開頭的資料夾——最典型的例子，就是等一下 1.3 節會提到的 .git（藏著 Git 每一次「存檔」歷史的地方）——ls 預設不會顯示，目的是讓平常的清單不要太雜亂。想連這些隱藏項目也一起看到，多打兩個字母：

ls -la

-la 其實是兩個旗標疊在一起

-a（all）代表連隱藏項目都列出來；-l（long）代表用「長格式」顯示，每一項多印出權限、擁有者、大小、修改時間。兩個疊著寫成 -la 或 -al 效果一樣。之後安裝好 Codex CLI，你的電腦也會多出一個類似的隱藏資料夾放設定資料，想確認它在不在，ls -la 就是你的第一個偵查動作。

cd：走進另一個資料夾

cd（change directory，切換目錄）讓你「走進」某個資料夾。例如走進桌面：

cd Desktop

打完後再 pwd 一次，就會看到你的位置變了。想回到家目錄（你的個人主資料夾），不管在哪，打：

cd ~

~（波浪號）是「我的家目錄」的簡寫。

超實用小技巧

不想手打一長串資料夾路徑？在終端機輸入 cd （記得後面留一個空格），然後把資料夾直接用滑鼠拖進終端機視窗，路徑就會自動補上，按 Enter 即可。迷路了就 cd ~ 回家，永遠不會卡死。

資料夾名稱不用整個打完，按 Tab 讓它幫你補

打 cd Doc 之後按一下鍵盤的 Tab 鍵，終端機會自動幫你補完成 cd Documents（符合的候選不只一個時，多按幾次 Tab 會依序列出或循環）。🍎 macOS、🐧 Linux、🪟 PowerShell 都吃這招，是最省時間的打字習慣之一，之後路徑越打越長，會越有感。

還有一個好用的捷徑：cd -（減號）會帶你回到上一個待過的資料夾。例如你從 Documents 走去 Desktop，這時打 cd - 就會跳回 Documents，方便你在兩個地方來回切換而不用重打完整路徑。這招在 🍎 macOS、🐧 Linux（含 WSL2 裡的 Linux 終端機）都能直接用；🪟 PowerShell 沒有內建一模一樣的「減號」寫法，它是用 Push-Location / Pop-Location 這對指令做類似的事，現在不用特別去記，先在 Mac／Linux 環境用順手就好。

「工作目錄」：你帶 Codex 進的那個房間

把上面三個指令串起來，你會發現一件事：終端機永遠「站」在某一個資料夾裡，這個你當下所在的資料夾，就叫工作目錄（working directory，也叫當前目錄）。pwd 印的就是它，ls 列的就是它裡面的東西，cd 就是換到另一個工作目錄。

這個概念對 Codex 超級重要，因為：

關鍵心法

Codex CLI 啟動後，就在你當下的「工作目錄」裡讀檔、改檔、執行程式。你可以把工作目錄想成「你帶這位 AI 工程師走進的那個房間」——它只會動這個房間裡的東西。所以開工前，先用 cd 走進你要它處理的專案資料夾，是基本動作。

實際操作起來，通常是這樣的順序（這裡先看流程，指令第 4 章會詳細教）：

cd ~/projects/我的網站     # 1. 先走進專案資料夾（這就是工作目錄）
codex                      # 2. 在這裡啟動 Codex，它就在這個房間工作

不想先 cd 也行

Codex 提供一個旗標 -C（也可寫成 --cd），可以在啟動時直接指定工作目錄，例如 codex -C ~/projects/我的網站，效果等於「先走進那個房間再啟動」。這個旗標第 4 章會正式介紹，這裡先讓你知道「工作目錄」是 Codex 的核心觀念，有兩種指定方式。

先預告：Codex 第一次進某個資料夾，會先問你「信任嗎？」

因為 Codex 會在工作目錄裡自動讀檔、甚至執行裡面的程式，第一次在一個新資料夾啟動時，官方介面會先跳出「Do you trust this folder?」（信任這個資料夾嗎？）的提示才讓它繼續。這其實就是「工作目錄」這個概念在保護你：Codex 只承諾動你當下站的這個房間，但進房間前，還是會先敲門問一聲。這個提示、以及背後「安全圍欄（sandbox）」怎麼分級，是第 6 章的主題，這裡你只要知道：1.1～1.2 節學的「先想清楚自己站在哪個資料夾」，到了實際用 Codex 時會直接變成一個保護你的安全機制。

官方參考：Codex CLI 總覽、Quickstart、Sandbox 概念、Agent 核可與安全

1.3 為什麼開工前先 git commit 存檔

學會了走進房間，我們講最後一件、也是最重要的習慣：在叫 Codex 動手之前，先用 Git 存一個檔。

先講為什麼：Codex 會「直接改你的檔案」

這點一定要先記住：Codex CLI 不是只給你建議，它會在你的工作目錄裡真的去新增、修改、執行程式碼。這正是它強大的地方——它是會自己動手的 AI 工程師，不是只會出一張嘴的顧問。

但「會自己動手」也代表：萬一它改錯了、或你不滿意它的改法，你需要一個「回到改動前」的後路。這個後路，就是 Git。

把 Git 想成電玩存檔

Git 是工程師用的「版本控制」工具，最白話的比喻就是電玩的存檔點。你存了檔，之後不管打怪打到多慘，都能讀檔回到存檔那一刻。git commit 就是「存檔」這個動作。

還有一個技術理由：Codex 會自動偵測你有沒有版控

Codex 啟動時，會自動判斷你當下的工作目錄是不是 Git 版控資料夾，並依此建議不同的預設安全等級。已經是 Git 專案的資料夾，Codex 傾向建議比較順手的「Auto」模式（技術說法是 workspace-write，可以自由讀寫這個資料夾，只在真的需要動用範圍外資源時才停下來問你）；不是 Git 專案的資料夾，Codex 對你的信任預設會保守一些。換句話說，養成「先 git init、先 commit」的習慣，不只是幫自己留退路，還會讓 Codex 一開始跟你合作得更順手。完整的安全分級邏輯，第 6 章會詳細拆解。

怎麼做：開工前先存一個乾淨的檔

在你要交給 Codex 的專案資料夾裡（也就是你的工作目錄），動工前先跑這兩行——🍎 macOS、🐧 Linux、🪟 Windows 都一樣。先跑 git --version 確認 Git 存在；若這是你第一次 commit，先看下面的身份設定，再回來做 checkpoint。

git add -A
git commit -m "checkpoint before codex"
  • 第一行 git add -A：把目前所有的檔案變動「打包準備存檔」。
  • 第二行 git commit -m "..."：正式存檔，引號裡是你給這次存檔的備註（這裡寫「進 codex 前的檢查點」）。

第一次 commit 出現 Author identity unknown？這不是 Codex 登入失敗。

Git 還不知道要在 commit 上標什麼名字與 email。選你願意寫進 commit 紀錄的顯示名稱與 email，先在自己的練習資料夾外也可執行下面兩行；在意 email 隱私時，先依 GitHub 或你使用的 Git 服務官方說明選 noreply email。這是範本，先把兩組引號內文字改成自己的值，不能原樣複製。

git config --global user.name "先改成你的公開顯示名稱"
git config --global user.email "先改成你要寫入 commit 的 email"

之後 Codex 不管怎麼改，你都能用 Git 比對它改了哪些地方，不滿意就還原回這個檢查點。

重要提醒

官方文件明確指出 Codex 會直接改動你的 codebase（程式碼庫），因此在啟動 Codex 前先做一次 Git checkpoint / commit 是公認的安全作法。這不是可有可無的潔癖，是保護你心血的安全網。

想知道原理：真的要「還原」的時候，具體打哪些指令？

「用 Git 比對、還原」不是抽象的說法，實際上就是這幾個指令：

  • git status：看 Codex 動過哪些檔案（新增、修改、刪除，一眼列表）。
  • git diff：看每個被改的檔案裡，具體哪幾行變了、變成什麼樣子。
  • git restore .：把還沒 add 的改動全部丟掉，退回上一次存檔的樣子（比較溫和的還原，只清「尚未存檔」的部分）。
  • git reset --hard HEAD：更徹底的還原，連已經 add 過的改動一起丟掉，整個資料夾強制退回最近一次 commit。這個指令會真的丟掉東西、沒有回收桶，下手前務必先用 git status／git diff 確認自己真的不要那些改動。

新手現在不用背這些，先知道「這幾招存在、Git 真的能救你」就夠了。等哪天 Codex 真的改壞東西，回來翻這一段照著打即可。

還沒用 Git 怎麼辦？

如果你的專案還沒有 Git（跑 git add -A 時報錯說「not a git repository」），別擔心，那是因為這個資料夾還沒「開始版本控制」。你可以先在資料夾裡跑一次：

git init

這會幫這個資料夾建立 Git 版本控制，之後就能正常 git add / git commit 了。但空資料夾沒有東西可 commit：先建立一個 README.md，或先跳過這次 commit 練習，不要把「沒有可提交的檔案」誤認為 Git 壞掉。

沒裝 Git 的話

如果連 git 指令都找不到，代表你的電腦還沒裝 Git。請從 Git 官方下載頁選你的系統版本；Windows 會走 Git for Windows，Mac 與 Linux 也有各自的官方入口。不要因為別人的 Linux 指令有 sudo 就照貼，先確認自己用的是哪個發行版與官方安裝方式。Git 的完整用法不在本書範圍，但「開工前 commit 一下」這個習慣，會在後面的章節一再幫你救命。

裝好之後，養成先確認版本的習慣：

git --version

Codex 官方列出的建議環境門檻之一是 Git 2.23 以上——這是 Codex 用來輔助建立 Pull Request 的功能所需要的版本。大部分近幾年裝的 Git 都遠超過這個門檻，不用特別擔心；真的是舊電腦、版本明顯偏舊，藉這個機會更新一下也好。

Git 的安全網不是萬能

Git 只能還原「被 Git 追蹤的檔案」。如果 Codex 改了 Git 範圍外的東西（例如系統設定、資料庫），Git 救不回來。所以越是放手讓 AI 動手，越要搭配後面章節會教的「權限與沙箱」觀念（第 6 章），雙重保險。

官方參考：Codex CLI 總覽、Quickstart

本章小結

走到這裡，你已經把「家門」打開了：你會在自己的作業系統上打開終端機、會用 cd / ls / pwd 在資料夾間走動、懂了「工作目錄就是你帶 Codex 進的房間」，也養成了「開工前先 git commit 存檔」的安全習慣。這些都還沒碰到 Codex 本體，但每一項都是它跑起來的地基。

動手試試

  1. 用你平台的方法打開終端機，依序打 pwd → ls → cd ~ → pwd，觀察位置怎麼變化。
  2. 練習「拖曳補路徑」：輸入 cd （留空格），把任一個資料夾拖進終端機視窗，按 Enter，再 pwd 確認你走進去了。
  3. 練習 Tab 補全：打 cd 加某個資料夾名稱的前兩三個字母，按 Tab 讓它幫你補完，感受一下跟手打完整名稱的差異。
  4. 在任一個資料夾打 ls -la，找找看有沒有 .git 這種以點開頭的隱藏資料夾。
  5. （有 Git 的話）挑一個練習用的資料夾，跑 git add -A 和 git commit -m "checkpoint before codex"；接著隨便改一個檔案內容，再打 git status 和 git diff，看看 Git 怎麼「看見」你剛剛的改動——這就是之後檢查 Codex 改了什麼的方式。

時效提醒

Codex CLI 更新很快（數天一版），書中提到的旗標（如 -C）與指令，最終都以你實機跑 codex --help 看到的為準。本章對照版本為 Codex CLI 0.140.0（2026-06-15）。

本章官方文件參考