Codex 安裝教學：登入、開啟專案、權限與第一個任務

Codex 安裝教學：登入、開啟專案、權限與第一個任務

Codex 最快的開始方式，是使用 Codex App；習慣終端機則可以安裝 Codex CLI。

但安裝不是最重要的一步。新手真正容易翻車的地方，是一進 repo 就叫 Codex 大改程式，卻還沒確認工作目錄、權限、測試與回復方式。

這篇會帶你完成一條完整路線：安裝、登入、開啟專案、理解權限、執行第一個任務、驗收結果。完整系列入口在 Codex 完整教學。

Codex App 和 CLI 要選哪個？

第一次接觸 coding agent，App 的全貌比較清楚；已經每天使用 terminal，CLI 會更直接。

Codex CLI 怎麼安裝？

官方 Codex CLI 套件可透過 npm 安裝：

npm install -g @openai/codex

確認版本：

codex --version

如果全域安裝出現權限問題，不要直接用 sudo 硬解。先確認 Node / npm 安裝方式與 global prefix，避免之後更新時留下 root-owned 檔案。

Codex 怎麼登入？

Codex 支援 ChatGPT 登入，也能使用 OpenAI API key。

codex login

無法在目前機器開瀏覽器時，可以嘗試 device auth：

codex login --device-auth

登入方式怎麼選：

不要把 API key 寫進 repo、AGENTS.md 或文章範例。金鑰應放在環境變數或 Codex 的安全認證儲存。

怎麼開啟第一個專案？

CLI 使用方式：

cd your-project
codex

App 則用 Add new project 或開啟資料夾，選到真正的 repo root。通常 repo root 會有 .git、package.json、pyproject.toml 或其他專案標記。

開錯層級會造成兩個問題：

1. Codex 看不到完整設定與 AGENTS.md
2. 搜尋範圍太大或太小，判斷容易失準

第一個任務不要直接改檔

先貼這段：

先不要修改任何檔案。

請讀取目前專案並整理：
1. 專案入口與主要技術棧
2. 目錄責任分工
3. 開發、測試、build 指令
4. 目前 git 工作區是否有未提交變更
5. 修改前應注意的風險

你要先確認 Codex 讀到的是正確專案，而且沒有把你正在做的修改當成它可以隨便整理的東西。

第二個任務：做一個最小修改

挑一個容易驗收的工作，例如：

• 修正一個文案錯字
• 補一個缺少的 loading state
• 修一個單元測試
• 補 README 指令
• 找出某個錯誤的來源但先不修改

範例：

修正登入頁在 API 失敗時沒有顯示錯誤訊息的問題。

限制：
- 只修改登入頁與既有錯誤元件
- 不改 API contract
- 不新增依賴
- 保留目前未提交修改

驗收：
- 補一個 regression test
- 執行相關測試與型別檢查
- 最後列出修改檔案與剩餘風險

權限模式怎麼選？

Codex 需要權限才能真正工作，但權限越大不代表效率越高。

把「一直問很煩」當成理由關掉所有保護，後面很容易花更多時間復原。

AGENTS.md 要寫什麼？

AGENTS.md 是專案給 Codex 的長期說明。先寫最有用的四件事：

# Project Guidance

## Commands
- Test: `npm test`
- Typecheck: `npm run typecheck`
- Build: `npm run build`

## Boundaries
- 不修改 `migrations/`，除非任務明確要求
- 不覆蓋未提交變更

## Style
- 沿用現有元件與 helper
- 新功能需補 regression test

不要把 AGENTS.md 寫成公司百科全書。只放會改變執行結果的規則。

怎麼驗收 Codex 的修改？

固定看四件事：

1. git diff 是否只包含任務範圍
2. 測試是否真的有執行
3. build / typecheck 是否通過
4. 使用者流程是否實測

如果是前端，不要只看測試綠燈。打開桌面與手機 viewport，確認沒有文字溢出、按鈕遮擋、空白畫面。

下一步：模型與 Provider

預設模型能處理多數工作。需要接 Ollama、LM Studio、Azure 或自訂 API 時，再看 Codex 自訂模型教學。

常見問題

Codex CLI 安裝後找不到指令怎麼辦？

先確認 npm global bin 是否在 PATH，再執行 npm prefix -g 與 codex --version 排查。

可以直接在有未提交修改的 repo 使用嗎？

可以，但一定要先看 git status，並明確要求保留既有修改。Codex 不應替你清掉不相關變更。

第一個任務適合做大型重構嗎？

不適合。先用小型、可測試、可回復任務確認環境、權限與工作方式。

官方資料

• Codex CLI
• Codex Authentication
• Codex Best practices
• OpenAI Codex GitHub