第一次啟動與登入

Codex CLI 的「登入」就是出示一張識別證，讓 OpenAI 知道「該由誰來付這趟差事的帳」。

想像你請了一位很厲害的工程師到家裡幫忙寫程式。他到門口時會先問：「你是哪位？這趟工要記在誰頭上？」——你得出示一張識別證，他才會開工。Codex CLI 第一次跑也一樣：它會先請你登入，確認身分，之後才願意動手讀檔、改檔、跑指令。

而且這張識別證有兩種：

• 一種是「訂閱證」（用你的 ChatGPT 方案登入）——像月票，刷一下就走，額度算在你的 ChatGPT 方案裡。
• 一種是「計次票」（用 API key 登入）——像跳表計程車，跑多少算多少，按用量計費。

別怕！這一章我們會帶你把識別證辦好。你只要跟著做，大部分人只需要一個指令、點兩下瀏覽器就完成，剩下的交給它就好。本章你會學到：

• 第一次打開 Codex 會看到什麼、它在問你什麼；
• 兩種登入方式怎麼選（訂閱 vs 計次）；
• codex login 這一家子指令逐一怎麼用，連沒有瀏覽器的遠端機器都能登；
• 你的「識別證」存在哪、怎麼保護它、怎麼登出與換帳號。

3.1 首次啟動會發生什麼

裝好 Codex CLI 後（安裝步驟見第 2 章），啟動它只要一個指令。打開終端機（不知道終端機在哪？複習第 1 章），輸入：

codex

按下 Enter。如果你還沒登入過，Codex 不會直接開工，而是先停下來請你登入。

官方的說法很直接：在終端機跑 codex 就能啟動工具；當「沒有有效的登入 session」時，CLI 預設會走「用 ChatGPT 登入」這條路（這是查核過的官方行為）。

實際畫面大概是這樣（以下為示意，實機文字可能略有不同）：

  Sign in with ChatGPT   ← 預設選項（用你的 ChatGPT 方案）
  Sign in with an API key

你用方向鍵上下選、按 Enter 確認。新手直接選第一個「Sign in with ChatGPT」就好——它會自動幫你打開瀏覽器完成登入，流程最少。

登入完成之後，歡迎畫面在跟你說什麼

登入成功（或這台電腦本來就登入過、直接跳過登入畫面）之後，Codex 不會馬上把游標丟給你打字，而是先印出一小段「開場白」。這段話值得花五秒鐘讀一下，因為它一次告訴你四件事：目前用哪個模型、你現在的工作目錄在哪、目前的沙箱與可寫入範圍是什麼、以及幾個新手最該先打的指令。

大致的資訊分佈長這樣（實際排版與文字以你電腦上看到的為準）：

model:      gpt-5.x
directory:  ~/projects/我的網站
sandbox:    workspace-write（可寫入目前資料夾）
approval:   on-request

建議指令：/init  /status  /permissions  /model  /review

這五個建議指令，你不用現在全部搞懂，但先知道各自負責什麼、之後哪一章會細講，能讓你少走不少冤枉路：

工作目錄是不是 Git 專案，決定了它一開始有多信任你

剛剛開場白裡的 sandbox 那一欄不是隨機給的，背後有一個簡單的判斷邏輯：Codex 啟動時會先看一眼你目前的工作目錄是不是 Git 版控資料夾，再決定用哪種預設安全等級招呼你。

• 如果是 Git 版控資料夾——Codex 傾向給你比較好用的「Auto」預設：可以自由讀寫這個資料夾（技術說法是 workspace-write），只有真的需要動用範圍外的資源時，才停下來問你一聲（on-request）。
• 如果不是 Git 版控資料夾——Codex 對你的信任預設會保守很多，傾向從唯讀開始，直到你自己用 /permissions 明確放寬。

這裡有兩個容易混在一起、但其實各自獨立的概念，先分清楚，之後看第 6 章會輕鬆很多：

這兩軸任何時候都能用 /permissions 當場調整，不需要重開。第一次啟動看到的只是「預設值」，不是永久設定。

3.2 用 ChatGPT 登入 vs 用 API key（怎麼選）

這是本章最重要的一個岔路：你要用哪一種「識別證」？先用一句話記住差別——

• 用 ChatGPT 登入：額度算在你的 ChatGPT 訂閱方案裡（像月票）。
• 用 API key 登入：按 token 用量向你的 OpenAI Platform 帳號計費（像跳表）。

下面這張表幫你一眼選對：

官方對這兩條路的定義是這樣（查核確認）：

• Sign in with ChatGPT = 訂閱制存取（subscription access）：用 ChatGPT 方案內含的 Codex 額度，並沿用你 ChatGPT workspace 的權限、企業資料保留與在地化設定。
• Sign in with an API key = 用量計費存取（usage-based access）：官方原文「OpenAI bills API key usage through your OpenAI Platform account at standard API rates.」（OpenAI 以標準 API 費率，透過你的 OpenAI Platform 帳號對 API key 用量計費。）

哪些 ChatGPT 方案內含 Codex？

如果你打算走「ChatGPT 登入」，先確認你的方案有 Codex 額度。官方 Help Center 說明 Codex 內含於下列方案（查核確認）：

Free、Go、Plus、Pro、Business、Edu、Enterprise

各方案的月費與定位（官方 Codex 定價頁逐字，2026-06-17 fetch）：

用 ChatGPT 登入的隱藏好處（限時）

官方曾推出限時優惠：Plus / Pro 使用者用 ChatGPT 登入 Codex CLI 後，可在接下來 30 天內兌換免費 API credits（Plus 約 $5、Pro 約 $50）。

3.3 codex login 家族逐字與 headless/SSH 登入

第 3.1 節我們是「跑 codex 順便登入」。但你也可以單獨叫出登入流程，或在腳本裡精準控制要用哪種識別證。這就要靠 codex login 這一家子指令。

三個基本指令

最常用的就是直接：

codex login

跑下去會打開瀏覽器，你在瀏覽器裡用 ChatGPT 帳號登入，完成後瀏覽器會把識別證送回 CLI，終端機就會顯示登入成功。

想確認自己現在是誰、用哪種方式登入：

codex login status

codex login 的三個旗標

codex login 後面可以接旗標，指定不同的登入方式。官方目前列出這三個（查核確認，逐字）：

用 API key 登入的正確姿勢：從 stdin 餵，不要寫在指令裡

如果你要走 API key，正確做法是把 key 從 stdin「餵」進去，像這樣。這兩行的前提是你已經依官方平台／公司流程把 OPENAI_API_KEY 安全地放進目前終端機的環境變數；本章不教新手建立或永久寫入 key，因為那會牽涉帳務、共享電腦與秘密管理。尚未有這個前提就回到一般 ChatGPT 登入。

🍎 Mac / 🐧 Linux：

printenv OPENAI_API_KEY | codex login --with-api-key

🪟 Windows (PowerShell)：

$env:OPENAI_API_KEY | codex login --with-api-key

這裡 printenv OPENAI_API_KEY（Windows 是 $env:OPENAI_API_KEY）的意思是「把名為 OPENAI_API_KEY 的環境變數的值印出來」，再用管線 | 把它送進 codex login --with-api-key。

為什麼要這麼麻煩，不直接打 --api-key 你的key？ 因為直接把 key 打在指令裡，它會留在你的指令歷史（shell history）、也可能被別人用 ps 看到正在跑的指令參數——等於把密碼貼在公布欄。從 stdin 餵就避開這個風險，這是刻意的安全設計。

沒有瀏覽器怎麼辦？headless / SSH 登入

有時候你是 SSH 連到一台遠端伺服器，或在一台沒有圖形桌面的機器上工作——根本沒有瀏覽器可以開。這時候普通的 codex login 會卡住，因為它想開瀏覽器卻開不了。

解法是加 --device-auth，改用「裝置碼」流程：

codex login --device-auth

它的運作方式像智慧電視登入串流平台：CLI 會給你一組裝置碼和一個網址，你在另一台有瀏覽器的裝置（例如你自己的手機或筆電）打開那個網址、輸入裝置碼完成授權，遠端那台機器就登入成功了。

登入卡住？搞懂瀏覽器背後在跟哪個埠號說話

前面說 codex login 會「自動幫你打開瀏覽器完成登入」，但它實際的運作方式值得拆開來看一次——搞懂這個機制，遠端／SSH 環境常見的卡關，你會一眼看穿原因，不用照著網路上的偏方亂試。

流程是這樣：CLI 啟動時，會在你這台機器上悄悄開一個只監聽本機的小型伺服器（位址約為 127.0.0.1:1455，精確埠號以你實機登入畫面顯示的網址為準），然後打開瀏覽器帶你完成 ChatGPT 的 OAuth 登入。瀏覽器這邊登入成功後，會把拿到的識別證（access token）送回這個本機小伺服器，CLI 收到後才存進 auth.json、顯示登入成功。整個交手都是「瀏覽器 → 你自己這台機器的那個埠號」，沒有例外。

ssh -L 1455:localhost:1455 user@remote-host
# 連進去之後，在這個 session 裡再跑
codex login

還有一種常見狀況，是埠號根本沒被誰佔用，卻被錯誤回報成「被佔用」：

Port 127.0.0.1:1455 is already in use
Failed to cancel previous login server: connection timed out

這幾種狀況的共通點很清楚：只要本機回呼路徑跟你的網路環境（SSH、WSL2、企業防火牆……）打架超過一次，別跟它耗，直接切 --device-auth——它完全不依賴本機埠號，用另一台裝置開網址輸入裝置碼就能完成，一次繞過這整類問題。更多 Windows / WSL 專屬的登入怪問題，第 16 章有更完整的疑難排解清單。

3.4 憑證存哪、安全注意、登出與切換

登入成功後，你的「識別證」會被存進電腦裡。這一節講它存在哪、怎麼保護、要登出或換帳號怎麼做。

憑證存在哪裡

預設情況下，你的登入憑證會被存成一個檔案 auth.json，位置如下（查核確認）：

這裡的 ~/.codex（Windows 是 %USERPROFILE%\.codex）是 Codex 放所有設定與狀態的「家目錄」。它由環境變數 CODEX_HOME 控制，預設值就是 $HOME/.codex。

auth.json 等同密碼——別外流

auth.json 裡面裝的是 access token（存取權杖），它等同你的密碼。官方的安全警語逐字是：

Treat ~/.codex/auth.json like a password: it contains access tokens. Don't commit it, paste it into tickets, or share it in chat.

翻成白話就是：把 ~/.codex/auth.json 當密碼看待，裡面有 access token。不要 commit 進 Git、不要貼進工單、不要貼進聊天視窗。

進階：憑證存檔案還是存系統鑰匙圈

預設 auth.json 是一個純檔案。如果你想讓系統用更安全的「作業系統憑證庫」（像 macOS Keychain）來保管，可以在 ~/.codex/config.toml 設定鍵 cli_auth_credentials_store（查核確認）：

cli_auth_credentials_store = "auto"   # 可選 "file" | "keyring" | "auto"

登出與切換帳號

想登出？跑：

codex logout

它會把 API key 與 ChatGPT 兩種憑證都一起清掉（這個指令沒有旗標）。

想換帳號或換登入方式（例如從 ChatGPT 登入切到 API key）最簡單可靠的做法就是：先 codex logout，再用你要的方式重新 codex login。

如果你想在兩種憑證並存時「釘住」偏好哪一個，社群間流傳一個設定鍵 preferred_auth_method：

preferred_auth_method = "apikey"   # 或 "chatgpt"

補充：CLI 和 IDE 共用同一份登入

如果你之後會在編輯器（VS Code / JetBrains）裝 Codex 的 IDE 擴充，好消息是：IDE 擴充和 CLI 共用同一份登入與設定，在 CLI 登入一次，IDE 那邊通常也認得你，不必再登一次。IDE 整合的細節留到第 12 章。

3.5 🎓 高手進階

前面四節已經夠新手把識別證辦好、用得安全。這一節是給「要在沒有人坐在螢幕前的機器上登入」「要把憑證硬化到企業級」的進階讀者——CI runner、cron 排程、SSH 上的遠端伺服器、跑自動化腳本的容器。重點只有三個：無人值守怎麼餵憑證（三條路）、明文 token 怎麼搬進系統鑰匙圈、怎麼避免 token 在 ps / shell history 裡裸奔。

一、headless（無人值守）的三條認證路

在 CI / cron / Docker / SSH 這種沒有互動式 TTY（沒有人能在終端機按 Y/n、也沒有瀏覽器可開）的環境，普通的 codex login 會卡住或失敗。Codex CLI 提供三條路讓自動化拿到身分（查核確認）：

export CODEX_API_KEY="$(cat /etc/codex/key)"   # 只有 codex exec 認 CODEX_API_KEY
codex exec --sandbox workspace-write "run npm audit; fix only critical vulns"

二、別讓 auth.json 的明文 token 躺在硬碟上——搬進系統鑰匙圈

3.4 節說過，當 cli_auth_credentials_store = "file" 時，~/.codex/auth.json 裡裝的是明文 access token（沒加密的純文字）。對個人單機這還能接受；但對「多人共用的伺服器」「會被備份/快照的機器」「合規要求高的環境」，明文 token 躺在硬碟上就是風險。

進階做法是把儲存切到作業系統的憑證庫（在 ~/.codex/config.toml，鍵就是 3.4 節那個 cli_auth_credentials_store）：

cli_auth_credentials_store = "keyring"   # 存進 OS 憑證庫（如 macOS Keychain），不落明文檔

三、用環境變數，避免 token 被 ps / history 看光

3.3 節已經教過「API key 從 stdin 餵、不要打在指令裡」。這裡把背後的原則講透，因為自動化腳本最容易在這裡漏 key：

• ps 風險： 你正在跑的指令，它的完整參數（包含你打進去的 key）會被同機器上任何人用 ps aux 看到。所以 codex login --api-key sk-xxx 這種寫法，等於把密碼貼在公布欄（這也是為什麼舊的 --api-key 旗標已棄用、要改用 --with-api-key 從 stdin 餵）。
• history 風險： 直接打進去的 key 會留在 shell history（~/.bash_history / ~/.zsh_history），日後翻歷史紀錄就洩漏。
• 正確姿勢： key 從環境變數或秘密管理來，經 stdin 進 Codex，全程不出現在「指令字串」裡：

🍎 Mac / 🐧 Linux：

printenv OPENAI_API_KEY | codex login --with-api-key

🪟 Windows (PowerShell)：

$env:OPENAI_API_KEY | codex login --with-api-key

四、企業受管環境：鎖定登入方式，跨過內網 TLS 攔截代理

最後這一條，是給 IT 部門要幫全公司統一管理 Codex 登入行為、或是身處內網有 TLS 攔截代理的讀者。這兩件事都跟「登入」直接相關，但都不是個人使用者日常會碰到的鍵，先知道有這回事、需要時回來查即可。

先講鎖定登入方式與工作區。3.4 節提過，preferred_auth_method 這個鍵其實沒有官方背書。但官方真的有收錄一組類似、語意卻不同的鍵——差別在於一個是「偏好」，一個是「強制」。在 config.toml 裡（查核確認）：

forced_login_method = "chatgpt"   # 或 "api"
forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

forced_login_method 會強制這台機器（或這份受管設定套用到的所有機器）只能用指定的方式登入，使用者自己選不了；forced_chatgpt_workspace_id 則更進一步，把 ChatGPT 登入鎖定在某個特定的工作區 ID，避免員工不小心（或刻意）用個人帳號的工作區登入公司環境。這組鍵典型的使用情境，是企業用 MDM（行動裝置管理）或設定管理工具，把這段 config.toml 統一推送到所有員工電腦上。

再講內網 TLS 攔截代理。如果你的公司網路會攔截並檢查所有 HTTPS 連線（用公司自己的根憑證做「中間人」式檢查），Codex 第一次 codex login 走 OAuth 交握時很容易被卡住——很多人這時候會誤以為「登入功能壞了」，其實只是瀏覽器／CLI 不認得公司那張自簽憑證。這是 IT 已提供憑證檔的企業進階情境；未知路徑、受管理電腦或 Windows PowerShell 不要猜著套用 Bash 範例。解法是在第一次登入之前，先依公司正式文件告訴 Codex 要信任哪張憑證：

export CODEX_CA_CERTIFICATE=/path/to/corp-ca.pem
codex login

/path/to/corp-ca.pem 是示意字，不能原樣複製；憑證檔與對應設定要由公司 IT／資安提供。順序很重要：先設好憑證環境變數，再登入，不要反過來。這個環境變數與代理、ZDR（零資料保留）相關設定的完整組合技，第 16 章有更完整的表格與案例，這裡你只要記得：企業內網第一次登入卡住，先檢查是不是憑證信任的問題，不要急著回報「登入壞了」。

本章小結

走到這裡，你已經幫 Codex 辦好了「識別證」：你會跑 codex 觸發首次登入、懂得在「ChatGPT 訂閱」與「API key 計次」之間做選擇、會用 codex login 一家子指令（含 SSH/headless 的 --device-auth），也知道憑證 auth.json 存在哪、要當密碼一樣保護。

動手試試

1. 在終端機跑 codex，完成你的第一次登入（新手選「Sign in with ChatGPT」）。
2. 登入完成後別急著打字，先讀一遍開場白，對照第 3.1 節說的欄位，找出你目前的模型、工作目錄、沙箱模式分別是什麼。
3. 跑 codex login status，再跑一次 /status（在 Codex 對話裡打，不是在終端機），比較兩者印出的資訊有什麼不同。
4. （進階，選做）找一個還沒 git init 的空資料夾，跟一個已經是 Git 專案的資料夾，各自跑一次 codex，比較兩邊 sandbox 欄位的預設值有什麼不同。
5. （進階，選做）找到你電腦上的憑證檔位置：🍎/🐧 是 ~/.codex/auth.json，🪟 是 %USERPROFILE%\.codex\auth.json，確認它存在——但別打開貼給任何人。