Tutorial · OpenAI Codex App 使用指南

How-to Tutorial · OpenAI Codex App · April 2026

OpenAI Codex App 使用指南 · Tenten 教學文件 OpenAI 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 是一個跨入口共用的 coding agent，與 Copilot 架構不同。

編者手記 EDITOR'S NOTE

本教學以官方 developers.openai.com/codex 為主幹，補充 Tenten 內部交付記錄。內容聚焦在影響工作節奏的入口、旗標與設定檔，提供可直接執行的步驟，完成後即可在正式專案中使用 Codex。

App、IDE、CLI、Web 四個入口共用同一份設定與帳號狀態。

App、IDE 擴充、CLI、Web 全部共用 ~/.codex/config.toml 設定、同一份 AGENTS.md 規則與同一個帳號狀態。可以在 IDE 開始任務，之後在 CLI 用 codex resume --last 接續，在 Web 介面查看雲端任務進度，設定不需要重複配置。

正確配置 AGENTS.md 對 agent 行為一致性的影響，大於切換較高價模型。

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

Cloud Tasks 讓本地 IDE 與雲端重構任務同時執行，每個任務在獨立沙箱運行。

本地 IDE 處理緊急 bug，同時以 codex cloud exec 把三個重構任務送至雲端，1–30 分鐘後各自回傳 PR diff。ChatGPT Pro 訂閱用戶（US$200/月）有 6× 本地任務限額，適合全職工程師日常使用。

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

入口 Surfaces

同一個 Codex agent 提供 4 個操作介面。先選定主入口，大多數工程師選擇 IDE 或 CLI，其餘介面按需配合使用。

4 Entries
App · IDE · CLI · Web
Shared Config

01^/04

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

終端機原生 coding agent，建議作為主入口

Rust 開源實作，支援 macOS、Windows、Linux

執行 codex 進入互動式 TUI；帶 prompt 直接執行：codex "Explain this codebase to me"。可用 codex exec "fix the CI failure" 串入 shell pipe 自動化。建議從 CLI 開始配置 Codex，因為 IDE 擴充與 App 都共用同一份 ~/.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 分鐘後產出 PR 草稿

可執行功能開發、bug 修復、問答與 PR 草稿產出，全程在雲端 sandbox

雲端 Codex 的主要特性是長時間執行與完全隔離。每個任務在獨立 sandbox 載入 repo，1–30 分鐘後產出 PR 草稿。Plus 與 Pro 訂閱均可使用，Pro 的本地任務限額為 Plus 的 6 倍。適合不需要 agent 修改本地檔案的場景，例如 prototype 重構、文件批改與長時間測試。

Cloud Sandbox PR 草稿 1–30 min

Surface Web URL chatgpt.com/codex

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

在單一視窗管理多個 cloud tasks 與本地 session

macOS 原生桌面 App，同時顯示所有 agent 的進度與 PR 狀態

2026 年 2 月推出的 macOS 原生 App，提供單一視窗檢視所有 cloud tasks 進度、PR 狀態與本地 session。定位為多 agent 管理介面，適合需要同時追蹤多個任務的工程師、代理商與 SaaS 團隊。Windows 版規劃中，尚未確定日期。

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，最後執行初次試跑。

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

01^/05

Step 01 · 安裝 CLI · npm 或 brew

選擇 npm 或 brew 安裝 CLI

兩種套件管理器皆可，CLI 是所有入口的設定基礎

開啟終端機，二擇一：
npm install -g @openai/codex
brew install codex
安裝後執行 codex --version 確認版本；支援 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 帳號

ChatGPT 訂閱登入為主要方式；API Key 為備援選項

執行 codex，首次執行時跳出登入流程。建議選 ChatGPT 帳號（Plus / Pro / Business / Enterprise），使用訂閱配額並啟用 Cloud Threads（API Key 登入時此功能停用）。Plus US$20/月、Pro US$200/月（含 6× 本地任務限額）。2026/4/2 起改為依 token 計費。

✓ 推薦 ChatGPT 登入 Plus / Pro Cloud Threads

Auth OAuth / API Key Tier Plus / Pro

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

將團隊規範寫入 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 安全網

在每次任務前建立 git checkpoint

官方建議每次任務前後各做一次 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

六個值得配置的 CLI 旗標與指令

Tip 01 · /model 切換推理深度

依任務難度選擇推理深度，減少不必要的 token 消耗

啟動時 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 Access

預設為 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 與內建功能合併。配置 MCP 後，Codex 可讀取工作環境的外部狀態，開 PR、查 issue、執行 SQL 皆可在同一 session 完成。

MCP config.toml 外部工具

File ~/.codex/config.toml

Tip 05 · 圖片輸入解 bug

以 -i 旗標傳入截圖或圖片至 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 連發

互動式 TUI 的六個常用快捷鍵

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

Tab：agent 執行中時排隊下一個 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 與雲端重構任務同時執行

本地 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 供 Codex 觸發

.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

在 CI 步驟中呼叫 `codex exec`，自動產出修復 PR

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 用於客戶交付前的夜間自動修復流程，次日白天再行評審。

codex exec CI 自動化 Self-heal PR

Cmd codex exec Mode Non-interactive

Workflow 04 · monorepo 的階層 AGENTS.md

各子目錄設置獨立的 AGENTS.md 覆蓋通用規則

payments/ 用 Java 規則、frontend/ 用 pnpm 規則，各自維護

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` 接續上次 session

無需重新提供上下文，直接繼承前次 session 的狀態

codex resume 顯示歷史 session 選單；codex resume --last 直接接續上次；codex resume <SESSION_ID> 指定特定 session。早上在同一 session 完成規劃，下午或晚上可接續同份 context 繼續實作，無需重新說明背景。

codex resume --last SESSION_ID

Cmd codex resume

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

四個第三方資源：評測、計費分析、開源 CLI 與官方 Skills 倉庫

官方文件以外的第一手資料，涵蓋第三方評測、計費結構分析、Apache-2.0 開源 CLI，以及官方 Skills 範例倉庫。

Almcorp · macOS App 完整指南 · 2026

Almcorp 評測：Codex App 定位為軟體開發團隊指揮中心

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 本地任務限額為 Plus 的 6 倍；token 計費後差距更明顯

eesel 計費分析指出：Plus 與 Pro 的差異在配額，Pro 本地任務限額為 Plus 的 6 倍。偶爾使用的副業開發者選 Plus（US$20/月）即可；每天執行超過 20 個任務的全職工程師需要 Pro（US$200/月）。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。企業客戶可自行 fork、build 並稽核沙箱行為，評估長期可靠性時提供直接依據。Tenten 在資安敏感場景中以此作為導入前的驗證方式。

Apache-2.0 Rust 96% 官方開源

License Apache-2.0 Lang Rust

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

OpenAI 官方維護的 Skills 範例倉庫

採用 open agent skills 標準，SKILL.md 結構可跨 agent 使用

OpenAI 官方 Skills 倉庫採用「open agent skills」標準，同一份 SKILL.md 結構設計為在 Codex、Claude 及其他相容 agent 上可執行。需要將內部 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 營運層。