Codex CLI 安裝

Codex CLI 安裝 === ###### tags: `AI / OpenAI / Codex /` ###### tags: `AI`, `OpenAI`, `Codex`, `CLI`, `安裝` [TOC] ## 安裝 Codex CLI - ### [[Quickstart] Start using Codex in your IDE, CLI, or the cloud](https://developers.openai.com/codex/quickstart/) ``` sudo npm install -g @openai/codex ``` - **需要使用 sudo，否則會遇到底錯誤** ``` $ npm install -g @openai/codex npm error code EACCES npm error syscall mkdir npm error path /usr/lib/node_modules/@openai npm error errno -13 npm error Error: EACCES: permission denied, mkdir '/usr/lib/node_modules/@openai' npm error at async mkdir (node:internal/fs/promises:855:10) npm error at async /usr/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:624:20 npm error at async Promise.allSettled (index 0) npm error at async [reifyPackages] (/usr/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:325:11) npm error at async Arborist.reify (/usr/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:142:5) npm error at async Install.exec (/usr/lib/node_modules/npm/lib/commands/install.js:150:5) npm error at async Npm.exec (/usr/lib/node_modules/npm/lib/npm.js:207:9) npm error at async module.exports (/usr/lib/node_modules/npm/lib/cli/entry.js:74:5) { npm error errno: -13, npm error code: 'EACCES', npm error syscall: 'mkdir', npm error path: '/usr/lib/node_modules/@openai' npm error } npm error npm error The operation was rejected by your operating system. npm error It is likely you do not have the permissions to access this file as the current user npm error npm error If you believe this might be a permissions issue, please double-check the npm error permissions of the file and its containing directories, or try running npm error the command again as root/Administrator. npm error A complete log of this run can be found in: /home/tj/.npm/_logs/2026-02-02T08_01_51_375Z-debug-0.log ``` - **正常執行結果** ``` $ sudo npm install -g @openai/codex added 1 package in 15s npm notice npm notice New major version of npm available! 10.9.4 -> 11.8.0 npm notice Changelog: https://github.com/npm/cli/releases/tag/v11.8.0 npm notice To update run: npm install -g npm@11.8.0 npm notice ``` - **當前 npm 版本** ``` $ node -v v22.22.0 $ npm -v 10.9.4 $ npx -v 10.9.4 ``` - **更新 npm** ``` $ sudo npm install -g npm@11.8.0 removed 56 packages, and changed 100 packages in 3s 15 packages are looking for funding run `npm fund` for details $ npm -v 11.8.0 ``` - ### [Codex CLI](https://developers.openai.com/codex/cli) - ### 要先準備 Node.js & npm - **如何在 Ubuntu 上安裝/更新 node.js** - [[HackMD] JavaScript Runtime: Node.js / npm / npx / nvm](https://hackmd.io/dl4NJ7ZDRUOX6MAz6oVB7Q#Ubuntu-%E5%AE%89%E8%A3%9D-Nodejs-%E2%89%A5-20) - ### Install ``` sudo npm i -g @openai/codex ``` - ### Run ``` codex ``` - ### Upgrade ``` sudo npm i -g @openai/codex@latest ``` --- ## `codex` ### 登入並授權 ``` $ codex Welcome to Codex, OpenAI's command-line coding agent Sign in with ChatGPT to use Codex as part of your paid plan or connect an API key for usage-based billing > 1. Sign in with ChatGPT Usage included with Plus, Pro, Team, and Enterprise plans 2. Sign in with Device Code Sign in from another device with a one-time code 3. Provide your own API key Pay for what you use Press Enter to continue ``` > - 選項 1:適合本地端，可以開瀏覽器那種 > - 選項 2:適合伺服端，無法開瀏覽器那種 - ### 若輸入 1 (適合本地端，可以開瀏覽器那種) - 自動導向到：https://auth.openai.com/log-in - 輸入帳密 - 輸入二階段驗證 Verify your identity Check your preferred one-time password application for a code - 允許授權 ![image](https://hackmd.io/_uploads/BywFnRTUbe.png) --- ![image](https://hackmd.io/_uploads/HkTs2CpLZx.png) - ### 若輸入 2 (適合伺服端，無法開瀏覽器那種) ``` Welcome to Codex, OpenAI's command-line coding agent Finish signing in via your browser 1. Open this link in your browser and sign in https://auth.openai.com/codex/device 2. Enter this one-time code after you are signed in (expires in 15 minutes) XXXX-XXXXX Device codes are a common phishing target. Never share this code. Press esc to cancel ``` - https://auth.openai.com/codex/device - 輸入帳密 - 輸入二階段驗證 Verify your identity Check your preferred one-time password application for a code - 使用 ChatGPT 登入 Codex ![image](https://hackmd.io/_uploads/Hy5EraHkzg.png) - **啟用 Codex 裝置代碼授權** > https://chatgpt.com/#settings/Security ![image](https://hackmd.io/_uploads/S1px8THyGx.png) --- ### 變更時，需要詢問？或自動執行？ ``` Welcome to Codex, OpenAI's command-line coding agent ✓ Signed in with your ChatGPT account > You are running Codex in /home/tj/workspace/k8s/slinky/iam-to-slurm-sync-service Since this folder is version controlled, you may wish to allow Codex to work in this folder without asking for approval. 1. Yes, allow Codex to work in this folder without asking for approval › 2. No, ask me to approve edits and commands Press enter to continue ``` --- ### sub-command ``` ╭─────────────────────────────────────────────────────╮ │ >_ OpenAI Codex (v0.93.0) │ │ │ │ model: gpt-5.2-codex /model to change │ │ directory: ~/…/k8s/slinky/iam-to-slurm-sync-service │ ╰─────────────────────────────────────────────────────╯ To get started, describe a task or try one of these commands: /init - create an AGENTS.md file with instructions for Codex /status - show current session configuration /permissions - choose what Codex is allowed to do /model - choose what model and reasoning effort to use /review - review any changes and find issues › Run /review on my current changes ? for shortcuts ``` ![image](https://hackmd.io/_uploads/B1QPaAT8bl.png) --- ### 如何執行請求？例如：請更新 `.gitignore` ，把 python cache 檔案忽略 > 直接在提示符號 › 後面打自然語言。 ``` › 請更新 .gitignore ，把 python cache 檔案忽略 • Preparing to read the file contents with cat to plan necessary edits. • Explored └ List ls List ls -a Read .gitignore • I'm adding common Python cache patterns like __pycache__/, *.pyo, and .pytest_cache/ to the ignore list to cover typical cache artifacts as requested. • Edited .gitignore (+3 -1) 3 *.pyc 4 - 4 +*.pyo 5 +*.pyd 6 +.pytest_cache/ Would you like to make the following edits? .gitignore (+3 -1) 3 *.pyc 4 - 4 +*.pyo 5 +*.pyd 6 +.pytest_cache/ › 1. Yes, proceed (y) 2. Yes, and don't ask again for these files (a) 3. No, and tell Codex what to do differently (esc) Press enter to confirm or esc to cancel ``` ![image](https://hackmd.io/_uploads/SkD9GkC8bl.png) - ### gpt-5.2 (2026/02/02) 「下指令」其實有兩種： 1. **自然語言任務**（最常用） 2. **斜線命令**（像 `/review`、`/permissions` 這種）你要做的是更新 `.gitignore` 忽略 Python cache，最簡單就是直接在提示符號 `›` 後面打自然語言。 --- ### ✅ 最簡單寫法（自然語言）在 `›` 後貼這句就好： > Update .gitignore to ignore Python cache files (e.g., **pycache**/, *.pyc, *.pyo, *.pyd, .pytest_cache/, .mypy_cache/, .ruff_cache/). Keep existing rules intact. （你也可以用中文） > 請更新 .gitignore：加入 Python 的 cache / 編譯產物忽略規則（**pycache**/、*.pyc、*.pyo、*.pyd、.pytest_cache/、.mypy_cache/、.ruff_cache/），不要動到原本已存在的規則。 Codex 會去改檔，改完你再跑 `/review` 檢查 diff。 --- ## ✅ 更「保守」的寫法（先提案再修改）如果你想先看它打算加哪些行、你確認後再寫入： > Propose the minimal .gitignore additions needed to ignore Python cache files, then apply them to .gitignore. --- ## ✅ 只忽略你指定的那一種（最小變更）你如果只想忽略 `__pycache__` 和 `*.pyc`（極小變更）： > Add rules to .gitignore to ignore **pycache**/ and *.pyc. Do not add other patterns. --- ## 建議流程（不會踩雷） 1. 先設定權限（第一次用建議） * `/permissions` → 先選「允許修改檔案，但執行指令要詢問」之類的模式 2. 下自然語言任務（上面任一種） 3. `/review` 看它改了哪些 4. `git diff` / `git status` 再自己確認 --- ## 你會想要的「標準 Python .gitignore」通常包含哪些？通常最常見的一組是： * `__pycache__/` * `*.py[cod]` * `.pytest_cache/` * `.mypy_cache/` * `.ruff_cache/` * `.coverage` / `htmlcov/`（如果你有測試覆蓋率）如果你回我一句：你專案有沒有用 pytest / mypy / ruff，我可以幫你把「最剛好、不多不少」的忽略清單寫成一段，直接貼進 Codex 的任務指令。 - ### 執行結果 ![image](https://hackmd.io/_uploads/HkqJIkALWx.png) --- ### 查看剩餘可用請求 ``` /status ╭────────────────────────────────────────────────────────────────────────────╮ │ >_ OpenAI Codex (v0.93.0) │ │ │ │ Visit https://chatgpt.com/codex/settings/usage for up-to-date │ │ information on rate limits and credits │ │ │ │ Model: gpt-5.2-codex (reasoning none, summaries auto) │ │ Directory: ~/workspace/k8s/slinky/iam-to-slurm-sync-service │ │ Approval: on-request │ │ Sandbox: read-only │ │ Agents.md: <none> │ │ Account: tsungjung411@gmail.com (Plus) │ │ Session: 019c1d6b-c8fc-7c82-baf6-a5b0c95e7100 │ │ │ │ Context window: 100% left (9.11K used / 258K) │ │ 5h limit: [████████████████████] 98% left (resets 21:37) │ │ Weekly limit: [████████████████████] 99% left (resets 16:37 on 9 Feb) │ ╰────────────────────────────────────────────────────────────────────────────╯ ``` ![image](https://hackmd.io/_uploads/HkV1PJRU-x.png) ## 討論 ### 什麼時候 codex 需要 API key？ - ### gpt-5.5 (2026/04/24) Codex **不一定需要 API key**，要看你怎麼登入／怎麼用。 | 使用情境 | 是否需要 API key | 說明 | | -------- | ----------------: | ----- | | **Codex 網頁版 / Codex Cloud** | 不需要 | 官方說 Codex cloud 需要用 **ChatGPT 登入**。 | | **Codex CLI / IDE Extension / Codex app，用 ChatGPT 帳號登入** | 不需要 | Plus、Pro、Business、Enterprise/Edu 等 ChatGPT 方案可直接登入使用；CLI/IDE 也支援 ChatGPT 登入。([OpenAI Help Center][20260424-A-1]) | | **Codex CLI / IDE Extension / Codex app，選擇 API key 登入** | 需要 | Codex 支援用 API key 登入，這時會走 OpenAI Platform 帳戶計費。([OpenAI 開發者][20260424-A-2]) | | **CI/CD、server、headless、自動化流程** | 通常需要 | 官方建議「程式化的 Codex CLI workflow，例如 CI/CD」使用 API key 驗證。([OpenAI 開發者][20260424-A-2]) | | **自己寫程式直接呼叫 OpenAI API** | 需要 | 這不是用 ChatGPT 方案額度，而是走 Platform API key 與 API 計費。 | | **想用 ChatGPT 方案的 Codex fast mode / ChatGPT credits** | 不要用 API key | 官方說 fast mode 這類依賴 ChatGPT credits 的功能，只有用 ChatGPT 登入時可用；用 API key 則改走標準 API pricing。([OpenAI 開發者][20260424-A-2]) | 核心判斷： ```text 你是「用 Codex 工具」並且「用 ChatGPT 登入」 => 不需要 API key 你是「用 Codex 工具」但「選 API key 登入」 => 需要 API key，且走 API 計費你是「自己寫程式呼叫 OpenAI API」 => 需要 API key ``` 補充：官方發行說明也提到，Codex 的 CLI 與 IDE 已可使用 ChatGPT 登入，「無須設定 API 金鑰，直接透過現有 ChatGPT 方案即可存取」。([OpenAI Help Center][20260424-A-3]) [20260424-A-1]: https://help.openai.com/zh-hant/articles/11369540-using-codex-with-your-chatgpt-plan "在你的 ChatGPT 方案中使用 Codex | OpenAI Help Center" [20260424-A-2]: https://developers.openai.com/codex/auth "Authentication – Codex | OpenAI Developers" [20260424-A-3]: https://help.openai.com/zh-hant/articles/6825453-chatgpt-%E7%99%BC%E8%A1%8C%E8%AA%AA%E6%98%8E "ChatGPT — 發行說明 | OpenAI Help Center" --- ### 在 docker 容器裡啟動 codex ，可以不要用 API key？ - ### gpt-5.5 (2026/04/24) 可以，**Docker 容器裡啟動 Codex CLI 可以不要用 API key**，前提是你改用 **ChatGPT 帳號登入**。官方目前說法是：Codex CLI / IDE extension 支援兩種登入方式：**ChatGPT 登入**或 **API key 登入**；而且 CLI 在沒有有效 session 時，預設會走 ChatGPT 登入流程。([OpenAI 開發者][20260424-B-1]) ### 最常見做法 #### 方式 1：容器內直接 `codex login` ```bash docker run -it --rm \ -v "$PWD:/workspace" \ -v "$HOME/.codex:/root/.codex" \ -w /workspace \ your-codex-image \ bash ``` 進入容器後： ```bash codex login codex ``` 這樣是 **ChatGPT login**，不是 API key。重點是這個 volume： ```bash -v "$HOME/.codex:/root/.codex" ``` 因為 Codex CLI 會把登入資訊快取在本機，官方文件提到 CLI/IDE 會重用快取的登入資訊，位置可能是 `~/.codex/auth.json` 或 OS credential store；在容器裡通常要把 `~/.codex` 掛出來，否則容器刪掉後下次又要重新登入。([OpenAI 開發者][20260424-B-1]) --- ### 方式 2：先在主機登入，再掛進容器在 host 上： ```bash codex login ``` 確認可用後，Docker 掛入： ```bash docker run -it --rm \ -v "$PWD:/workspace" \ -v "$HOME/.codex:/root/.codex:ro" \ -w /workspace \ your-codex-image \ codex ``` 這樣容器裡可以沿用 host 的 ChatGPT 登入狀態。 --- ### 什麼情況還是建議用 API key？如果你是在 **CI/CD、server、headless、自動化流程** 裡跑 Codex，官方建議一般情況用 API key；若你特別需要用 ChatGPT-managed Codex auth，也有進階做法是先建立 `auth.json`，放到 trusted runner 上，讓 Codex 自行 refresh session，但官方也明確說 API key 仍是多數 CI/CD 工作的建議方式。([OpenAI 開發者][20260424-B-2]) ### 判斷表 | Docker 使用情境 | 可不可以不用 API key | 建議 | | -------------- | --------------------: | ---- | | 本機互動式容器 | 可以 | 用 `codex login` + 掛載 `~/.codex` | | 遠端容器，但你能完成瀏覽器登入 | 可以 | 需要處理 OAuth callback / port forwarding | | 每次臨時開發容器 | 可以 | 掛載 `~/.codex`，避免重登 | | CI/CD pipeline | 技術上可，但不首選 | 官方較建議 API key | | 不想用 Platform 計費，只想用 ChatGPT 方案額度 | 可以 | 必須用 ChatGPT 登入，不要用 API key | ### 注意不要把 `~/.codex/auth.json` bake 進 Docker image，也不要 commit 到 Git。官方文件提到登入資訊可能以 plaintext file 形式存在 `~/.codex/auth.json`，所以它應該被當成憑證處理。([OpenAI 開發者][20260424-B-1]) [20260424-B-1]: https://developers.openai.com/codex/auth?utm_source=chatgpt.com "Authentication – Codex | OpenAI Developers" [20260424-B-2]: https://developers.openai.com/codex/auth/ci-cd-auth?utm_source=chatgpt.com "Maintain Codex account auth in CI/CD (advanced)" --- ### 登入後，可以讓 codex 自動化處理嗎？比如一個需求，第一步先執行 plan，後續再依 plan 所產生的步驟，再依序執行？ - ### gpt-5.5 (2026/04/24) 可以。登入後，Codex 可以做「先規劃，再依規劃執行」這類 agentic workflow。大致有三種層級： ### 1. 互動式：先 `/plan`，確認後再做在容器裡進入 repo 後： ```bash codex ``` 然後在 Codex TUI 裡輸入： ```text /plan 幫我規劃：將這個專案的 Bootstrap UI 遷移成 Tailwind，先不要修改檔案，只產生步驟、風險、驗證方式。 ``` 官方文件提到 Plan mode 適合複雜或模糊任務，會先蒐集上下文、問問題、建立較完整的 implementation plan；CLI 可用 `/plan` 或 `Shift + Tab` 切換。([OpenAI 開發者][20260424-C-1]) 確認 plan 後，你可以接著說： ```text 依照剛剛的 plan 執行。每完成一個步驟就跑相關測試，失敗就修正，最後整理變更摘要。 ``` 這是最安全的做法，因為你可以先審 plan，再允許它動手。 --- ### 2. 半自動：一個 prompt 內要求「先 plan，再執行」例如： ```bash codex --full-auto " 請完成以下需求：需求： - 將登入頁面改成 React-Bootstrap - 保留現有功能 - 補上必要測試流程： 1. 先檢查專案結構與現有實作 2. 先輸出 implementation plan 3. 依 plan 逐步修改 4. 每完成一階段就執行測試或 lint 5. 若測試失敗，先修正 6. 最後輸出：修改檔案、測試結果、風險與後續建議 " ``` `--full-auto` 是低摩擦模式，官方說它會設定成 `workspace-write` sandbox 與 `on-request` approval；也就是 Codex 可以在工作目錄內改檔、執行例行命令，但遇到超出權限的事仍會要求確認。([OpenAI 開發者][20260424-C-2]) 這種適合你在 Docker 裡跑本機 repo 開發。 --- ### 3. 非互動式自動化：用 `codex exec` 如果你想包成 script、CI job、Makefile，可以用： ```bash codex exec --full-auto " 請根據需求建立 PLAN.md，然後依 PLAN.md 逐步實作。完成後請執行測試，並把結果寫入 CODEX_RESULT.md。需求： - 新增 FastAPI file upload token expiration 功能 - token 過期後不可上傳 - 加上單元測試 " ``` 官方建議 `codex exec` 用在 pipeline、CI、pre-merge checks、scheduled jobs，或需要把結果 pipe 給其他工具的情境。([OpenAI 開發者][20260424-C-3]) 你也可以拆成兩段，比較可控： ```bash codex exec --sandbox read-only \ --output-last-message PLAN.md \ "只讀取專案，不要修改檔案。請針對以下需求產生可執行的 PLAN.md：新增 token expiration 功能。" ``` 再執行： ```bash codex exec --full-auto " 請讀取 PLAN.md，依照其中步驟逐步實作。每完成一項就更新 PLAN.md 的狀態。最後執行測試並輸出結果。 " ``` `codex exec` 也支援把最後訊息輸出到檔案，以及用 JSON event stream 讓外部程式追蹤狀態。([OpenAI 開發者][20260424-C-2]) --- ### Docker 裡的典型跑法 ```bash docker run -it --rm \ -v "$PWD:/workspace" \ -v "$HOME/.codex:/root/.codex" \ -w /workspace \ your-codex-image \ codex exec --full-auto " 請先產生 PLAN.md，再依 PLAN.md 實作需求。需求：<你的需求> " ``` 如果你是用 ChatGPT 登入而不是 API key，重點是掛載： ```bash -v "$HOME/.codex:/root/.codex" ``` Codex CLI 會快取登入資訊；官方文件提到 CLI 支援 ChatGPT login 與 API key，且沒有有效 session 時，ChatGPT login 是 CLI 的預設路徑。登入資訊會存在 `~/.codex/auth.json` 或系統 credential store，所以要把它當成密碼保護。([OpenAI 開發者][20260424-C-4]) --- ### 建議設定 | 目的 | 建議 | | ------------------ | ---------------------------------------------------------------------------- | | 本機 Docker 自動改 code | `codex exec --full-auto` | | 先看計畫再動手 | 互動式 `codex` + `/plan` | | 完全 script 化 | `codex exec` | | 只允許先讀不改 | `--sandbox read-only` | | 允許改工作目錄 | `--sandbox workspace-write` | | 非互動式不想卡 approval | `--ask-for-approval never`，但要搭配 Docker / VM 隔離 | | 千萬小心 | 不建議裸機使用 `--yolo`；官方也標示這會繞過 approvals 和 sandbox，只適合外部已強隔離環境。([OpenAI 開發者][20260424-C-2]) | 核心答案： ```text 可以。 Codex 可以： 1. 先 plan 2. 產生 PLAN.md 3. 依 PLAN.md 逐步修改 4. 執行 test / lint 5. 失敗後自動修正 6. 最後輸出變更摘要但建議用 sandbox + approval 控制權限。 ``` 我會建議你的 Docker workflow 採用： ```text 第一次：read-only 產生 PLAN.md 第二次：workspace-write 依 PLAN.md 實作第三次：/review 或 codex exec 做驗證與摘要 ``` [20260424-C-1]: https://developers.openai.com/codex/learn/best-practices "Best practices – Codex | OpenAI Developers" [20260424-C-2]: https://developers.openai.com/codex/cli/reference "Command line options – Codex CLI | OpenAI Developers" [20260424-C-3]: https://developers.openai.com/codex/noninteractive "Non-interactive mode – Codex | OpenAI Developers" [20260424-C-4]: https://developers.openai.com/codex/auth?utm_source=chatgpt.com "Authentication – Codex | OpenAI Developers" ## Blogs - [Awesome Codex Skills：快速擴展 Codex 能力的 Agent Skills 清單大全](https://tools.wingzero.tw/article/sn/3899) ## 其他參考資料 → OpenAI Developers：Codex CLI [https://developers.openai.com/codex/cli](https://developers.openai.com/codex/cli) → OpenAI Developers：Codex Quickstart [https://developers.openai.com/codex/quickstart](https://developers.openai.com/codex/quickstart) → OpenAI Developers：Codex Authentication [https://developers.openai.com/codex/auth](https://developers.openai.com/codex/auth) {%hackmd vaaMgNRPS4KGJDSFG0ZE0w %}

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.