Tutorial · OpenAI Codex App 大師班

How-to Tutorial · OpenAI Codex App · April 2026

Codex 大師班 — Tenten 教學文件把 Codex 變成你的
第二位開發者。
App、IDE、CLI、Web 四個入口，一個 agent。

OpenAI Codex 不再只是補完工具 — 它是一個跨 macOS App、IDE 擴充套件、終端機 CLI 與 chatgpt.com/codex 雲端的共用 agent。本教學把官方文件、社群評測、與 Tenten 內部使用習慣整合成一份可執行清單：你會學到 4 個入口、5 種安裝路徑、AGENTS.md 客製化、Agent Skills 自動觸發、以及 Cloud Tasks 平行卸載。讀完即可投入正式專案。

入口數

4 Surfaces

App（macOS / Win）· IDE 擴充（VS Code / Cursor / Windsurf）· CLI · Web。

推薦模型

GPT-5.5

CLI / IDE / App 共享同一個 agent 與設定；可以 /model 切換推理深度。

登入方式

ChatGPT

推薦使用 Plus / Pro / Business / Enterprise 訂閱登入；亦可改用 OpenAI API Key。

驗證時間

Apr. 2026

指令、計費、IDE 列表截至 2026 年 4 月；以 developers.openai.com/codex 為準。

01 / 編者手記 FROM THE EDITOR · APRIL 2026

Codex 不是另一個 Copilot — 而是一個跨入口的工程師。

編者手記 EDITOR'S NOTE

本教學以官方 developers.openai.com/codex 為主幹，補上 Tenten 內部交付的實戰心得。重點不是把所有功能講一遍，而是挑出真正會改變你工作節奏的入口、旗標、與檔案 — 一份能讓你今晚部署、明天就跑得起來的清單。

「同一個 agent，四個入口」是它與其他工具最大的差異。

App、IDE 擴充、CLI、Web — 全部共用一份 ~/.codex/config.toml 設定、同一份 AGENTS.md 規則、同一個帳號狀態。這代表你可以早上在 IDE 對著開檔下指令，下午在 CLI 裡 codex resume --last 接著聊，晚上在手機 Web 介面看雲端任務的進度。

把 AGENTS.md 寫好，比換一個更貴的模型還有效。

Codex 每次啟動都會從 git root 往下合併所有 AGENTS.md 檔案，越靠近你工作目錄的規則優先級越高。把「跑哪個測試指令、用哪個 lint、PR 要怎麼描述」寫進去，等於用 32 KiB 的成本買到永久一致的 agent 行為。

Cloud Tasks 是「平行開發」的關鍵 — 不是噱頭。

本地 IDE 跑緊急 bug，同時把三個重構任務丟到 codex cloud exec，每一個任務都在獨立沙箱運行，1–30 分鐘後回傳 PR diff。對於有 ChatGPT Pro 訂閱的工程師，這是把「等待時間」變成「平行進度」的最直接方式。

02 / 四個入口 APP · IDE · CLI · WEB · ONE AGENT

入口 Surfaces

同一個 Codex agent，4 個操作介面。先選定你的主入口（90% 的工程師選 IDE 或 CLI），其餘的當作支援角色使用。

4 Entries
App · IDE · CLI · Web
Shared Config

01^/04

CLI · 終端機原生 Agent（推薦主入口）

90% 日常工作都從這裡開始

Rust 寫的開源 agent；macOS / Windows / Linux 通吃

執行 codex 進入互動式 TUI；直接帶 prompt 也行：codex "Explain this codebase to me"。可用 codex exec "fix the CI failure" 串進 shell pipe 自動化。建議從這裡開始學 Codex — 因為 IDE 擴充與 App 都共用 CLI 的設定檔（~/.codex/config.toml）。Apache-2.0 授權，原始碼在 github.com/openai/codex。

✓ 推薦主入口 Rust · 開源 Apache-2.0 codex / codex exec / resume

Surface CLI OS macOS / Win / Linux Lang Rust

IDE Extension · VS Code / Cursor / Windsurf

把 @filename 當 prompt 上下文

Chat / Agent / Agent Full Access 三種權限模式

支援 VS Code、Cursor、Windsurf 與相容編輯器。重點功能：@filename 引用讓 prompt 自動帶上開檔內容；Cloud Delegation 把長任務丟到雲端但留在 IDE 看進度；Image input 直接拖圖進對話框。與 CLI 共享同一份設定，AGENTS.md 完全相容。

VS Code Cursor Windsurf @filename

Surface IDE Modes Chat / Agent / Full

Web · chatgpt.com/codex（雲端）

每個任務跑在獨立沙箱，1–30 分鐘

寫功能、修 bug、答問、產出 PR，全在雲端 sandbox

雲端 Codex 的特色是長時間執行 + 完全隔離。每個任務在獨立 sandbox 載入你的 repo，1 到 30 分鐘後產出 PR 草稿。Plus 與 Pro 訂閱即可使用，Pro 有 6× local task 限額提升。對於不想讓 agent 動到本地檔案的場景特別合適 — 像是 prototype 重構、文件批改、長時間測試。

Cloud Sandbox PR 草稿 1–30 min

Surface Web URL chatgpt.com/codex

App · macOS（2026/2 上線，Win 規劃中）

多任務的指揮中心

原生桌面 App，平行管理多個雲端 + 本地 agent

2026 年 2 月推出的 macOS 原生 App，定位是「同時管理多個 Codex agent」的指揮中心 — 一個視窗裡看所有 cloud tasks 的進度、PR 狀態、本地 session。Windows 版規劃中但尚未確定日期。對代理商、SaaS 團隊、CTO / Tech Lead 角色特別合適。

macOS Native Multi-task Dashboard Win 規劃中

Surface Desktop App Launch Feb 2026

03 / 安裝與設定 NPM · BREW · CHATGPT LOGIN · API KEY

安裝 Install & Sign-In

五個步驟把 Codex 從零裝到第一次跑出 PR。先選 npm 或 brew、登入 ChatGPT 訂閱、寫 AGENTS.md、配 git checkpoint，最後做第一次 dry-run。

5 Entries
~10 分鐘
Plus / Pro / API Key

01^/05

Step 01 · 安裝 CLI · npm 或 brew

最短安裝 — 一行指令裝完

兩種包管理器皆可，CLI 是其他入口的設定基礎

打開終端機，二擇一：
npm install -g @openai/codex
brew install codex
裝完後執行 codex --version 確認；CLI 在 macOS、Windows、Linux 三平台都支援。即使主要用 IDE 擴充或 App，也建議先裝 CLI — 因為共用同一份設定檔，先把 CLI 跑通最簡單。

✓ 必裝步驟 npm install -g @openai/codex brew install codex ~30 秒

Pkg @openai/codex OS 3 平台 Time ~30s

Step 02 · 第一次執行 + 登入

輸入 `codex` → 瀏覽器登入 ChatGPT

推薦用訂閱登入；API Key 是備援選項

執行 codex，第一次會跳出登入流程。推薦選 ChatGPT 帳號（Plus / Pro / Business / Enterprise），這樣可以用訂閱配額，並且解鎖 Cloud Threads（API Key 登入時這個功能會被禁用）。Plus US$20/月、Pro US$200/月（含 6× 本地任務限額）。2026/4/2 起改為依 token 計費，符合 API 使用模式。

✓ 推薦 ChatGPT 登入 Plus / Pro Cloud Threads

Auth OAuth / API Key Tier Plus / Pro

Step 03 · 在 repo 根目錄寫 AGENTS.md

把團隊規矩寫成檔案

Codex 會自動從 git root 往下合併所有 AGENTS.md

在 repo 根目錄建立 AGENTS.md，寫進測試指令（"Always run npm test after JS edits"）、套件管理偏好（"Prefer pnpm"）、PR 描述格式、特定服務的特殊規則。Codex 啟動時會把 ~/.codex/AGENTS.md → repo root → 當前目錄全部按順序合併，越靠近的優先級越高（32 KiB 上限）。

AGENTS.md 階層合併 32 KiB

Path ~/.codex + repo Limit 32 KiB

Step 04 · Git checkpoint 安全網

給 Codex 一個能回滾的環境

官方建議：每次任務前後都做 git checkpoint

因為 Codex 直接修改你的 codebase，每次重要任務前先 git commit -am "checkpoint"（或開新 branch）；任務結束如果不滿意就 git reset。Tenten 在客戶交付時會把這變成 alias：alias codexp='git commit -am "pre-codex" && codex'。

git checkpoint 回滾安全網每次任務必做

Pattern Pre-task commit

Step 05 · 第一次跑：三個試水題

用三個 prompt感受 agent 行為

官方 quickstart 推薦的三個入門指令

進入專案目錄，依序試：
codex "Tell me about this project"（讓 agent 讀懂程式庫）
codex "Build a classic Snake game in this repo"（觀察 Agent mode 改檔行為）
codex "Find and fix bugs in my codebase with minimal, high-confidence changes"（測 Surgical Changes 風格）。三題跑完，你就有了直覺：哪些任務該本地、哪些該丟雲端。

三題試水 Agent mode 手感建立

Time ~15 min Goal 建立直覺

04 / 進階用法 /MODEL · /REVIEW · MCP · SUBAGENTS · IMAGE

六個讓你看起來像老手的旗標

Tip 01 · /model 切換推理深度

不是越強越好 — 配對任務難度

啟動時 codex --model gpt-5.5；session 中 /model

官方推薦：「For most tasks in Codex, gpt-5.5 is the recommended model when it is available.」啟動時帶 codex --model gpt-5.5；過程中切換用 /model。簡單重構 / 文件改寫用較淺的推理深度即可，省 token 又快。

/model GPT-5.5 Reasoning level

Cmd /model

Tip 02 · /permissions 三段權限

Read-only / Auto / Full 三種模式

Auto 是預設；網路存取需要額外確認

/permissions 切換：Read-only（只能讀，所有寫入需確認）；Auto（讀寫工作目錄無需確認，網路 / 外部存取需確認，預設）；Full Access（不限制，慎用）。Tenten 內部規定：客戶 repo 一律從 Read-only 開始，確認任務範圍後再升級。

/permissions Auto 預設客戶 repo 用 RO

Default Auto

Tip 03 · /review 本地程式碼審查

不送外網就能審 PR

分析 base branch / 未提交變更 / 特定 commit

在 session 內輸入 /review，Codex 會分析當前 diff 對 base branch 的差異，提出風險、可改善之處、與 commit message 建議。對於不能把程式碼送上 GitHub Copilot Review 的客戶 repo 特別有用 — 全程本地。

/review 本地審查隱私敏感場景

Cmd /review

Tip 04 · MCP server 接外部工具

在 `~/.codex/config.toml` 加 MCP servers

Codex 啟動時自動拉起，工具與內建並列可用

把 GitHub、Linear、Slack、Vercel、PostgreSQL 等 MCP server 寫進 ~/.codex/config.toml，Codex 啟動時會自動拉起並把它們的 tools 跟內建混合。這是把 Codex 變成「真正了解你工作環境」的關鍵 — 不只是改 code，能幫你開 PR、查 issue、跑 SQL。

MCP config.toml 外部工具

File ~/.codex/config.toml

Tip 05 · 圖片輸入解 bug

把 screenshot 直接餵給 Codex

codex -i screenshot.png "Explain this error"

codex -i screenshot.png "Explain this error"，或多張 codex --image img1.png,img2.jpg "Summarize these diagrams"。對於設計稿轉 React、錯誤訊息截圖求救、UI bug 重現特別有效。IDE 擴充也支援拖放圖片進對話框。

codex -i / --image 設計稿轉 code 截圖 debug

Flag -i / --image

Tip 06 · 終端快捷鍵 4 連發

不開 IDE，純終端也能爽用

Tab / Ctrl+O / Ctrl+R / Ctrl+G / @ / !

Tab：Codex 在跑時排隊下一個 prompt。Ctrl+O：複製最新輸出。Ctrl+R：搜尋 prompt 歷史。Ctrl+G：開外部編輯器寫長 prompt。@ 開頭：模糊搜尋檔案。! 開頭：執行 shell 指令。Tab 排隊功能特別重要 — 不用等 agent 跑完就能堆積後續任務。

Tab 排隊 @ 檔案搜尋 ! shell

Mode Interactive TUI

05 / 實戰場景 CLOUD TASKS · AGENTS.MD · SKILLS · CI · TENTEN WAY

實戰 Workflows

五個真正在 Tenten 與 OpenAI 社群被反覆驗證的工作場景 — 從本地 / 雲端切換、自製 Skill、CI 自動化、到客戶交付的會前準備。

5 Entries
Cloud · Skill · CI
Field-tested

01^/05

Workflow 01 · 本地 IDE × 雲端 Cloud Tasks 平行

把等待時間變成平行進度

IDE 修緊急 bug 時，Cloud 跑三個重構任務

最高頻使用模式：本地 IDE 跑緊急 bug、同時用 codex cloud exec --env ENV_ID "Refactor utils/ to TypeScript" 把三個重構丟雲端。每個 cloud task 在獨立 sandbox 載入 repo，1–30 分鐘後回傳 PR diff，IDE 不離開即可審核。Pro 訂閱用戶（US$200/月）有 6× 本地任務限額 — 對全職工程師才划算。

✓ 高頻使用 codex cloud exec 獨立 sandbox PR diff 回傳

User Pro Cmd codex cloud exec Time 1–30 min

Workflow 02 · 寫一個 Agent Skill

把團隊SOP 變成 SKILL.md

.agents/skills/<name>/SKILL.md，含 frontmatter

在 repo 建立 .agents/skills/release-notes/SKILL.md，frontmatter 寫 name 與 description，本文寫流程指令。Codex 偵測到後可隱式觸發（描述匹配時）或顯式呼叫（/skills 或 $skill-name）。建議從一個小 Skill 開始 — 例如「寫 release notes」、「跑特定測試」、「產出 PR 描述」。

.agents/skills SKILL.md $skill-name

Path .agents/skills/ Trigger /skills · $name

Workflow 03 · CI 自動修 build

用 `codex exec` 把 Codex 寫進 CI

Pipeline 裡跑 codex exec，stdout 拿 diff 自動 PR

在 GitHub Actions / GitLab CI 加一個 step：codex exec "Look at the failing test and propose a minimal fix"，stdout 直接拿到變更 patch，讓 CI 失敗時自動產出修復 PR。Tenten 把這個用在客戶交付前的「nightly self-heal」— 半夜跑、白天評審。

codex exec CI 自動化 Self-heal PR

Cmd codex exec Mode Non-interactive

Workflow 04 · monorepo 的階層 AGENTS.md

不同子目錄不同規則

payments/ 用 Java、frontend/ 用 pnpm — 各自有 AGENTS.md

monorepo 場景：repo root 寫通用規則，payments/AGENTS.md 寫 Java + Maven 特殊指令，frontend/AGENTS.md 寫 pnpm + Vitest。Codex 進入子目錄時會自動合併、靠近的優先。對混合技術棧的客戶交付特別省事 — 不用每次都改 prompt。

monorepo 階層覆寫混合技術棧

Pattern Per-dir AGENTS.md

Workflow 05 · resume 接續上次對話

用 `codex resume --last` 無痛接力

不用每次都重新解釋 context

codex resume 會跳出歷史 session 選單；codex resume --last 直接接上一次；codex resume <SESSION_ID> 指定特定 session。把 Codex 當成一位有記憶的同事 — 早上的 plan 對話，晚上回家可以接著用同一份 context 繼續實作。

codex resume --last SESSION_ID

Cmd codex resume

06 / 社群觀察 REVIEWS · PRICING ANALYSIS · OFFICIAL SKILLS REPO

第三方怎麼看這個 App

官方文件外的四個第一手訊號 — 評測、計費分析、官方 Skills 倉庫、與 GitHub 開源 CLI 的成長曲線。

Almcorp · macOS App 完整指南 · 2026

「指揮中心」這個定位是社群共識

2026 年最受引用的第三方 Codex App 評測之一

Almcorp 的長文評測把 Codex App 描述為「command center for software development teams」，強調平行管理多個 agent 與長時間自主執行的能力是與 Copilot / Cursor 最大的差異化。也是少數同時涵蓋安全模型與企業部署細節的中文友善資源。

第三方評測 macOS 重點企業安全

Source Almcorp Year 2026

eesel AI · Codex 計費分析 · 2026

Plus 與 Pro 之間的分水嶺

「Pro 6× 本地任務限額」是分水嶺，不是模型差異

eesel 的計費分析指出：Plus 與 Pro 的差異不是模型品質，而是配額 — Pro 在本地任務的限額是 Plus 的 6 倍。對偶爾用的副業者，Plus US$20/月足夠；對全職工程師、每天跑超過 20 個任務的人，Pro US$200/月才不會被卡 quota。2026/4/2 起改為 token 計費後，這個分界更明顯。

Plus vs Pro 配額分析 Token 計費

Source eesel AI Tier Plus / Pro

github.com/openai/codex · 官方 CLI 開源

CLI 開源、Apache-2.0

Rust 寫的 lightweight coding agent

Codex CLI 的原始碼公開在 GitHub，Apache-2.0 授權，96.2% Rust。對於企業客戶評估「會不會明天就消失」與「能不能稽核」是強訊號 — 至少 CLI 端可以自行 build、自行驗證沙箱行為。對 Tenten 客戶內的 security-sensitive 場景特別重要。

Apache-2.0 Rust 96% 官方開源

License Apache-2.0 Lang Rust

github.com/openai/skills · 社群 Skills 倉庫

官方維護的 Skills 範例庫

build on the open agent skills standard

OpenAI 維護的官方 Skills 倉庫，採用「open agent skills」標準 — 同一份 SKILL.md 結構在 Codex、Claude、其他相容 agent 都能跑（理論上）。對於想把 Tenten 內部 SOP 寫成跨 agent 可攜資產的團隊，這是最直接的學習對象。

openai/skills open standard Skill 範例

Type Examples Repo Std Open Agent Skills

想把 Codex 接進團隊的正式交付流程？

Codex 已經是
第二位開發者。
把它接上產線，是 Tenten 在做的事。

Tenten 是 AI-First 設計與技術顧問公司。我們把 Codex、Claude、MCP、Agentic Commerce 接進 Headless CMS、Webflow、Shopify Plus 的企業級交付 — 從 AGENTS.md 規範、Skills 倉庫、Cloud Tasks 工作流、到 CI 自動修復 — 讓 Codex 真正跑在你的正式產線上。

預約 30 分鐘諮詢 → Tenten Awesome List

Tenten 如何部署這些 Skills

Skills 架構諮詢

依團隊與堆疊選出適配 skills，建立 OpenClaw 路由與 CI/CD 部署流程。

Claude Design System Sprint

兩週固定價格，接上 frontend-design + brand-guidelines 到 production。

Agentic Commerce Build

Shopify Plus / Webflow / Headless 遷移，搭配 Claude + MCP 營運層。