Codex CLI：權威技術參考

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                        │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │ │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │   MCP   │  │ Skills  │  │  Apps   │  │  Search │   │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘   │
│  External tools, reusable expertise, ChatGPT            │
│  connectors, web search (cached + live)                  │
├─────────────────────────────────────────────────────────┤
│  SECURITY LAYER                                          │
│  ┌─────────────────────────────────────────────────┐    │
│  │    Sandbox (Seatbelt / Landlock / seccomp)      │    │
│  │    + Approval Policy (untrusted → never)        │    │
│  └─────────────────────────────────────────────────┘    │
│  OS-level filesystem + network restrictions              │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         GPT-5.x-Codex Intelligence              │    │
│  │   Tools: Shell, Patch, Read, Web Search         │    │
│  │   (legacy artifact, read_file, grep_files       │    │
│  │    removed in v0.117.0)                          │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens          │
└─────────────────────────────────────────────────────────┘

# npm (recommended)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

# Upgrade to latest
npm install -g @openai/codex@latest

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh

codex login                  # Interactive OAuth (recommended)
codex login --device-auth    # OAuth device code flow (headless)
codex login --with-api-key   # API key from stdin
codex login status           # Check auth state (exit 0 = logged in)
codex logout                 # Clear stored credentials

# Generate completions for your shell
codex completion bash > /etc/bash_completion.d/codex
codex completion zsh > ~/.zsh/completions/_codex
codex completion fish > ~/.config/fish/completions/codex.fish

codex --version
# codex-cli 0.133.0

npm i -g @openai/codex          # Install
codex login                      # Log in with your OpenAI account

cd ~/my-project                  # Any git repo works

codex

> What does this project do? Summarize the architecture.

> Add input validation to the login endpoint

> /plan Refactor the database layer to use connection pooling

> /diff

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-5.5            # Specify model
codex --sandbox workspace-write --ask-for-approval on-request

codex app                    # Launch desktop app (auto-installs if missing)

codex cloud list             # List recent cloud tasks
codex apply <TASK_ID>        # Apply diff from a specific cloud task

# ~/.codex/config.toml — annotated reference

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.5"                      # Recommended model when available
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 400000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-5.5"               # Optional model for /review command
service_tier = "fast"                  # Preferred service tier for new turns
oss_provider = "lmstudio"              # lmstudio|ollama (used with --oss)

# ─── Sandbox & Approval ───────────────────────────────
sandbox_mode = "workspace-write"        # read-only|workspace-write|danger-full-access
approval_policy = "on-request"          # untrusted|on-request|never

[sandbox_workspace_write]
writable_roots = []                     # Additional writable paths
network_access = false                  # Allow outbound network
exclude_tmpdir_env_var = false          # Exclude $TMPDIR from sandbox
exclude_slash_tmp = false               # Exclude /tmp from sandbox

# ─── Web Search ────────────────────────────────────────
web_search = "live"                     # Web search mode (constrained by allowed modes)

# ─── Instructions ──────────────────────────────────────
developer_instructions = ""             # Additional injected instructions
model_instructions_file = ""            # Custom instructions file path
compact_prompt = ""                     # Custom history compaction prompt

# ─── Shell Environment ─────────────────────────────────
allow_login_shell = false               # Allow login shell semantics (loads .profile/.zprofile)

[shell_environment_policy]
inherit = "all"                         # all|core|none
ignore_default_excludes = false         # Set true to keep KEY/SECRET/TOKEN vars
exclude = []                            # Glob patterns to exclude
set = {}                                # Explicit overrides
include_only = []                       # Whitelist patterns

# ─── Authentication ────────────────────────────────────
cli_auth_credentials_store = "file"     # file|keyring|auto
forced_login_method = "chatgpt"         # chatgpt|api
mcp_oauth_callback_port = 0            # Fixed port for MCP OAuth callback (0 = random)
mcp_oauth_credentials_store = "auto"   # auto|file|keyring

# ─── History & Storage ─────────────────────────────────
[history]
persistence = "save-all"                # save-all|none
max_bytes = 0                           # Cap size (0 = unlimited)

tool_output_token_limit = 10000         # Max tokens per tool output
log_dir = ""                            # Custom log directory
sqlite_home = ""                        # Override SQLite-backed resumable state location

# ─── UI & Display ──────────────────────────────────────
file_opener = "vscode"                  # vscode|vscode-insiders|windsurf|cursor|none
hide_agent_reasoning = false
show_raw_agent_reasoning = false
check_for_update_on_startup = true

[tui]
notifications = false                   # Enable notifications
notification_method = "auto"            # auto|osc9|bel
animations = true
show_tooltips = true
alternate_screen = "auto"               # auto|always|never
status_line = ["model", "context-remaining", "git-branch"]

# ─── Project Trust ─────────────────────────────────────
project_doc_max_bytes = 32768           # Max AGENTS.md size (32 KiB)
project_doc_fallback_filenames = []     # Alternative instruction filenames
project_root_markers = [".git"]         # Project root detection

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
enable_request_compression = true       # zstd request compression where supported (stable)
fast_mode = true                        # Service-tier selection and Fast-tier commands (stable)
goals = true                            # Goal mode; stable and on by default in v0.133.0+
hooks = true                            # Lifecycle hooks (stable)
multi_agent = true                      # Enable multi-agent collaboration tools (stable)
personality = true                      # Personality selection (stable)
plugins = true                          # Plugin system (stable)
plugin_hooks = true                     # Plugin-bundled hooks (stable)
plugin_sharing = true                   # Workspace plugin sharing (stable)
browser_use = true                      # In-app browser automation (stable)
browser_use_external = true             # Chrome extension browser use (stable)
computer_use = true                     # macOS Computer Use (stable, plan/region gated)
in_app_browser = true                   # Shared rendered-page preview (stable)
image_generation = true                 # Image-generation tool (stable)
guardian_approval = true                # Auto-review approval path (stable)
skill_mcp_dependency_install = true     # Prompt/install missing skill MCP deps (stable)
tool_suggest = true                     # Tool/plugin suggestion surface (stable)
workspace_dependencies = true           # Workspace dependency discovery (stable)
memories = true                         # Memories (experimental)
network_proxy = false                   # Sandboxed networking proxy (experimental)
prevent_idle_sleep = true               # Keep machine awake during active turns (experimental)
terminal_resize_reflow = true           # Terminal reflow improvements (experimental)

# Removed or deprecated feature names still appear in `codex features list`
# for migration diagnostics. Do not set removed flags such as
# `collaboration_modes`, `request_rule`, `codex_git_commit`,
# `apply_patch_freeform`, `search_tool`, or `js_repl` in new configs.

# ─── Multi-Agent Roles (v0.102.0+) ───────────────────
[agents]
max_threads = 4                         # Maximum concurrent agent threads

[agents.explorer]
description = "Read-only codebase navigator"
config_file = "~/.codex/profiles/explorer.toml"

# ─── Notifications ────────────────────────────────────
notify = ["terminal-notifier", "-title", "Codex"]  # Command for notifications

# ─── Per-Project Overrides ────────────────────────────
[projects."/absolute/path/to/repo"]
trust_level = "trusted"                 # Per-project trust override

# Define profiles in ~/.codex/config.toml

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

[profiles.careful]
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.auto]
model = "gpt-5.4"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

codex --profile fast "quick refactor"
codex --profile careful "security audit"
codex -p auto "fix CI"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"

# Built-in amazon-bedrock provider (v0.123.0+, first-class in v0.124.0+)
# AWS SigV4 signing + credential-based auth; AWS profile selectable via the
# nested `aws.profile` field (NOT a top-level `aws_profile` key).
# v0.130.0+ also accepts credentials from `aws login` (the AWS console-login
# flow) — Codex resolves the cached console-login session for the chosen
# profile if static keys are absent.
# v0.140.0+ adds managed Amazon Bedrock API-key authentication, and stores
# CLI and MCP OAuth credentials in encrypted local storage.[^184]
[model_providers.amazon-bedrock]
name = "Amazon Bedrock"

[model_providers.amazon-bedrock.aws]
profile = "default"                   # any profile from ~/.aws/credentials
# Region/credential resolution otherwise follows the standard AWS chain;
# v0.130.0 added support for `aws login` console-login profiles in addition
# to static access keys and IAM role assumption.[^168]

[model_providers.ollama]
name = "Ollama (Local)"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

codex --oss "explain this function"               # Uses default OSS provider
codex --oss --local-provider lmstudio "explain"   # Explicit LM Studio
codex --oss --local-provider ollama "explain"      # Explicit Ollama

model_provider = "oss"
oss_provider = "lmstudio"   # or "ollama"

codex -c model="gpt-5.5" "refactor the API"
codex -c 'sandbox_workspace_write.network_access=true' "install dependencies"
codex -c model_reasoning_effort="xhigh" "debug the race condition"

Is this a quick fix or simple question?
├─ Yes → gpt-5.1-codex-mini (fastest, cheapest)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (near-instant, Pro only)
   │  └─ No
   │     ├─ Subagent or parallel subtask (search, review, processing)?
   │     │  ├─ Yes → gpt-5.4-mini (30% of GPT-5.4 quota, 2x faster)
   │     │  └─ No
   │     │     ├─ Pure coding task (refactor, migration, feature build)?
   │     │     │  ├─ Yes → gpt-5.3-codex (coding specialist, 272K context)
   │     │     │  └─ No → gpt-5.5 (new flagship: 400K context in Codex / 1M in API, 82.7% Terminal-Bench 2.0 SOTA)
   └─ Still unsure? → gpt-5.5

codex -c model_reasoning_effort="xhigh" "find the race condition"

codex -m gpt-5.3-codex-spark "pair with me on this component"

## Codex 的費用是多少？

另請參閱[模型選擇](#which-model-should-i-choose)了解各模型能力，以及[決策框架](#decision-frameworks)了解如何依任務挑選合適的模型。

### 透過 ChatGPT 方案存取

Codex 的可用性取決於您的 ChatGPT 方案與組織設定：[^61]

| 方案 | 價格 | Codex 存取權 | 速率限制（5 小時區間） |
|------|-------|-------------|----------------------------|
| **Free / Go** | $0 / $5 | 限時推廣存取 | 低 |
| **Plus** | $20/月 | 本機 CLI + 雲端任務（2 倍速率限制） | 本機 45-225 則訊息、雲端 10-60 個任務 |
| **Pro** | $200/月 | 優先處理、GPT-5.3-Codex-Spark（2 倍速率限制） | 本機 300-1500 則訊息、雲端 50-400 個任務 |
| **Business** | $25/使用者/月（年繳 $20） | 標準席次包含 Codex 與 ChatGPT、SAML SSO | 依方案限制速率 |
| **Business（僅 Codex 席次）** | 用多少付多少 | 以 Token 計費，無固定席次費用，無速率限制 | 以 Token 計費 |
| **Enterprise / Edu** | 聯絡業務 | 自訂配額、管理員控制、稽核日誌，提供僅 Codex 席次 | 隨合約規模調整 |
| **API Key** | 依用量計費 | CLI、SDK、僅限 IDE（無雲端功能） | 以 Token 計費 |

> **2026 年 4 月定價更新：** Business 年繳價格由 $25 調降為每席次每月 $20。Business 與 Enterprise 工作空間現可選用「僅 Codex 席次」並採用多少付多少的計費方式——無固定席次費用，依 Token 用量計費。[^84] 付費方案的 2 倍速率限制推廣（自 2026 年 2 月 Desktop App 推出時開始）持續有效。[^17]
>
> **2026 年 5 月用量上限提升（至 2026 年 5 月 31 日止）：** Plus 方案上的 Codex 以 **25 倍 5 小時上限**運作（標準提升為 20 倍），且**每月 $100 級距加倍**，皆適用於同一期間。請善用這段期間執行更長的雲端任務批次，或進行更高吞吐量的 Agent 執行，而不會撞上平常的 5 小時上限。[^166]

### 點數費用

Codex 操作會從方案配額中扣除點數：

| 操作 | 約略點數 | 備註 |
|-----------|----------------|-------|
| 本機訊息（GPT-5.3-Codex） | ~5 | 標準旗艦模型 |
| 本機訊息（GPT-5.1-Codex-Mini） | ~1 | 相同點數預算下訊息量為 4 倍 |
| 雲端任務 | ~25 | 在 OpenAI 託管環境中執行 |
| 程式碼審查（每個 PR） | ~25 | 透過 `/review` 或雲端審查 |

> Enterprise 與 Edu 方案的點數隨合約配額而定。請於 TUI 中執行 `/status` 查看目前用量。

### API 計費

透過 API 使用 Codex 時，OpenAI 會依所選模型套用標準 OpenAI API 定價，按 Token 計費（並適用任何相關的 prompt 快取折扣）。最新費率請參閱[官方 API 定價頁面](https://openai.com/api/pricing/)。[^21]

### 成本最佳化策略

1. **善用 profiles**：為例行任務建立 `fast` profile，搭配 `gpt-5.1-codex-mini` 與 `model_reasoning_effort = "low"`
2. **保留高推理層級**：僅在面對真正困難的問題時才使用 `xhigh`，因其消耗的 Token 是 3-5 倍
3. **使用 `--ephemeral`**：在 CI/CD 中跳過 session 持久化以降低額外負擔
4. **盡量精簡推理摘要**：當不需要解釋時，將 `model_reasoning_summary` 設為 `"none"`
5. **以 exec 模式批次執行**：`codex exec` 可避免 TUI 在自動化流程中產生的負擔
6. **監控用量**：於 TUI 中執行 `/status` 並查看組織計費儀表板

### 實際成本範例

常見任務的代表性 API 成本（gpt-5.3-codex 採標準定價、中等推理層級）：

| 任務 | 輸入 Token | 輸出 Token | 約略費用 |
|------|-------------|---------------|-------------|
| 解釋一個 500 行的模組 | ~15K | ~2K | ~$0.25 |
| 修復失敗的測試（1-2 個檔案） | ~30K | ~5K | ~$0.50 |
| 新增一個附帶測試的 API endpoint | ~60K | ~15K | ~$1.10 |
| 重構驗證模組（10 個檔案） | ~120K | ~30K | ~$2.25 |
| 透過 `codex exec` 進行完整 repo 稽核 | ~200K | ~20K | ~$3.00 |
| 雲端任務：分類 20 個開放議題 | ~250K | ~40K | ~$4.50 |

> 費用會因推理層級、快取與對話長度而有所不同。例行任務使用 `gpt-5.1-codex-mini` 可降低約 40-60% 的成本。已快取的輸入 Token 將以折扣價計費。

### 隱性 Token 負擔

每次工具呼叫都會在您可見的 prompt 之外增加額外 Token：

| 負擔來源 | 約略成本 |
|-----------------|-------------|
| 系統 prompt + AGENTS.md | 每輪 ~2-5K Token（首次載入後即會被快取） |
| 工具定義 | 每個已註冊工具 ~500 Token |
| 檔案讀取（`@file`） | 完整檔案內容的 Token 數 |
| MCP 工具定義 | 每個已連線的 server ~200-500 Token |
| 推理軌跡 | 不固定；`xhigh` 可能增加 3-5 倍負擔 |

> **專家提示：** 透過 TUI 的 `/status` 監控實際用量。Token 計數涵蓋所有額外負擔，而非僅是您可見的訊息。若費用出乎意料，請檢查連接了多少個 MCP servers——每一個都會在每次 API 呼叫中加入工具定義。

### 團隊成本管理

| 團隊規模 | 建議設定 | 預期每月成本 |
|-----------|-------------------|----------------------|
| 獨立開發者 | 預設模型、`medium` 推理層級 | $20-80 |
| 小型團隊（3-5 人） | 使用 profiles（`fast`／`careful`）、透過 `codex exec` 進行程式碼審查 | $200-500 |
| 中型團隊（10-20 人） | Enterprise 方案、`requirements.toml` 限制、CI 整合 | $1,000-3,000 |
| 大型組織（50 人以上） | 含管理員控制、稽核日誌與配置預算的 Enterprise | 客製化定價 |

團隊成本控制策略：
- **設定 `requirements.toml`** 以在組織內全面強制模型與推理層級上限
- **CI/CD 採用 `gpt-5.1-codex-mini`**——自動化管線鮮少需要最高推理層級
- **以 profile 為基礎進行預算控管**——分別定義 `ci`、`review` 與 `dev` profiles，並設定合適的成本上限
- **透過 OpenTelemetry 監控**——企業部署可將用量遙測資料匯出至既有的可觀測性平台

## 決策框架

### 何時使用各介面

| 情境 | 最佳介面 | 原因 |
|----------|-------------|-----|
| 快速修復 bug | CLI | 快速、聚焦、可指令稿化 |
| 多檔案重構 | CLI 或 App | CLI 提供確定性的 patch；App 提供視覺化 diff 檢視 |
| 探索陌生程式碼 | CLI | 終端機可組合性、grep/find 整合 |
| 平行工作流 | Desktop App | Worktree 隔離、多任務管理 |
| 主動編輯檔案 | IDE Extension | 行內編輯、緊湊的編譯測試循環 |
| 長時間執行的遷移 | Cloud | 獨立執行,完成後建立 PR |
| CI/CD 自動化 | `codex exec` | 非互動式、JSON 輸出、可指令稿化 |
| 程式碼審查 | CLI 或 App | `/review` 指令搭配預設組態 |
| 團隊上手 | Desktop App | 視覺化、引導式、較少需要終端機知識 |

### 何時使用各 Sandbox 模式

| 情境 | 模式 | 核准 | 原因 |
|----------|------|----------|-----|
| 探索未知程式碼 | `read-only` | `untrusted` | 最高安全性,不會破壞任何東西 |
| 日常開發 | `workspace-write` | `on-request` | 速度與安全性的良好平衡 |
| 受信任的自動化 | `workspace-write` | `never` | 快速、不中斷、有 sandbox 隔離 |
| 系統管理 | `danger-full-access` | `on-request` | 需要完整存取權但仍需人工核准 |
| CI/CD 流程 | `workspace-write` | `never` | 自動化,並隔離至工作區範圍 |

### 何時使用各推理層級

| 任務類型 | 推理層級 | 模型 | Profile |
|-----------|-----------|-------|---------|
| 格式化、lint | `low` | `gpt-5.1-codex-mini` | `fast` |
| 標準編碼 | `low`-`medium` | `gpt-5.3-codex` | 預設 |
| 複雜除錯 | `high` | `gpt-5.3-codex` | `careful` |
| 安全稽核 | `xhigh` | `gpt-5.3-codex` | `careful` |
| 快速原型開發 | `low` | `gpt-5.3-codex-spark` | `fast` |
| 遷移/重構 | `medium`-`high` | `gpt-5.5` 或 `gpt-5.4` | 預設 |

### Plan Mode 與直接執行

```text
Will Codex need to change more than 3 files?
│
├── YES → Use Plan Mode (/plan)
│         Codex designs the approach BEFORE making changes.
│         You review and approve the plan.
│         Best for: refactors, new features, migrations
│
└── NO → Is the change well-defined?
         │
         ├── YES → Direct execution
         │         Just describe the task. Codex executes immediately.
         │         Best for: bug fixes, small features, test additions
         │
         └── NO → Use Plan Mode (/plan)
                  Let Codex explore and propose an approach first.
                  Best for: unfamiliar codebases, ambiguous requirements

How do you prefer to work?
│
├── Terminal-first → Use CLI
│   │
│   ├── Single focused task → codex (interactive TUI)
│   ├── Scripted automation → codex exec (non-interactive)
│   └── Quick one-shot → codex exec "prompt" -o result.txt
│
└── Visual/multi-project → Use Desktop App
    │
    ├── Multiple parallel tasks → Multi-thread with worktree isolation
    ├── Visual diff review → Built-in Git diff viewer
    ├── Scheduled automation → Automations tab
    └── Voice-driven → Ctrl+M for voice dictation

# Default profile
profile = "default"

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"

[profiles.careful]
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"

[profiles.pair]
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

[profiles.ci]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
read_only_access = ["/etc", "/usr/local/share"]  # Only these paths readable outside workspace

default_permissions = "project-safe"

[permissions.project-safe.filesystem]
"/usr/local" = "read"
glob_scan_max_depth = 3

[permissions.project-safe.filesystem.":project_roots"]
"." = "write"
"**/*.env" = "none"

[permissions.project-safe.network]
enabled = true
mode = "limited"

[permissions.project-safe.network.domains]
"api.github.com" = "allow"
"registry.npmjs.org" = "allow"

codex --sandbox workspace-write --ask-for-approval on-request

sandbox_mode = "workspace-write"
approval_policy = "on-request"

sandbox_mode = "danger-full-access"
approval_policy = "untrusted"

sandbox_mode = "workspace-write"
approval_policy = "never"

approvals_reviewer = "guardian_subagent"   # "user" (default) or "guardian_subagent"

# Per-run
codex -c 'sandbox_workspace_write.network_access=true' "install the packages"

# In config.toml
[sandbox_workspace_write]
network_access = true
writable_roots = ["/path/to/extra/dir"]   # Additional writable directories
exclude_slash_tmp = false                  # Prevent /tmp from being writable
exclude_tmpdir_env_var = false             # Prevent $TMPDIR from being writable

export WSS_PROXY="https://proxy.corp.example.com:8443"
codex "update the README"

codex sandbox macos --permissions-profile :workspace -- ls /etc/passwd   # macOS test
codex sandbox linux --permissions-profile :workspace -- cat /etc/shadow  # Linux test

~/.codex/AGENTS.md                     ← Global defaults
  └─ /repo/AGENTS.md                   ← Project-wide rules
      └─ /repo/services/AGENTS.md      ← Service-specific rules
          └─ /repo/services/payments/
               AGENTS.override.md      ← Overrides everything above for this dir

# Repository Guidelines

## Build, Test, and Development Commands
- Run API (dev): `python3 -m uvicorn main:app --reload`
- Install deps: `pip install -r requirements.txt`
- Lint: `python3 -m ruff check .` (auto-fix: `--fix`)
- Format: `python3 -m ruff format .`
- Tests: `python3 -m pytest -v`
- Coverage: `python3 -m pytest --cov=app --cov-report=term-missing`

## Coding Style & Naming Conventions
- Python 3.11+. Type hints on all functions.
- Ruff enforced: 88-char lines, double quotes, spaces for indent.
- Naming: modules `snake_case.py`, classes `PascalCase`, functions `snake_case`.

## Commit & Pull Request Guidelines
- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`
- Commits should be small and focused.
- PRs must include: description, test plan, and screenshots for UI changes.

## Security
- Never commit secrets. Use `.env` for local config.
- Validate all external API calls with proper error handling.

# Custom fallback filenames (in addition to AGENTS.md)
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# Increase max size for large instruction files
project_doc_max_bytes = 65536    # 64 KiB (default: 32 KiB)

codex                           # Launch TUI
/init                           # Generate AGENTS.md scaffold

codex --ask-for-approval never "Summarize your current instructions"

[[hooks]]
event = "AfterToolUse"
command = "echo 'Tool completed' >> /tmp/codex-log.txt"

[[hooks]]
event = "SessionStart"
command = "echo 'Current date: $(date +%Y-%m-%d)'"

# In ~/.codex/config.toml or .codex/config.toml

[mcp_servers.context7]
enabled = true
required = true                         # Fail startup if unavailable
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "MY_VAR" = "value" }            # Static env vars
env_vars = ["PATH", "HOME"]             # Forward host env vars
cwd = "/path/to/project"                # Optional working directory
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["search", "summarize"]  # Tool allowlist
disabled_tools = ["slow-tool"]           # Tool denylist

[mcp_servers.figma]
enabled = true
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
env_http_headers = { "X-Org-Id" = "FIGMA_ORG_ID" }  # Headers from env vars
startup_timeout_sec = 10
tool_timeout_sec = 60

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add context7 --env API_KEY=... -- npx -y @upstash/context7-mcp   # With env vars
codex mcp add figma --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN
codex mcp list                          # List all configured servers
codex mcp list --json                   # JSON output
codex mcp get context7                  # Show server config
codex mcp get context7 --json           # JSON output
codex mcp login <server>                # OAuth flow for HTTP servers
codex mcp logout <server>               # Remove OAuth credentials
codex mcp remove <server>               # Delete server definition

codex mcp-server                        # Start as MCP server (stdio transport)

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "codex", "mcp-server"]},
    client_session_timeout_seconds=360000,
) as codex_mcp_server:
    agent = Agent(name="Developer", mcp_servers=[codex_mcp_server])
    result = await Runner.run(agent, "Fix the failing tests")

[mcp_servers.context7]
enabled = true
required = true
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

# In /etc/codex/requirements.toml — only approved servers allowed
[mcp_servers.approved-internal]
identity = { command = "npx @company/internal-mcp" }

my-skill/
  SKILL.md           (required: instructions)
  scripts/           (optional: executable scripts)
  references/        (optional: reference docs)
  assets/            (optional: images, icons)
  agents/openai.yaml (optional: metadata, UI, dependencies)

---
name: security-audit
description: Run a thorough security audit on the codebase.
---

## Security Audit Procedure

1. Scan for hardcoded secrets using `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Check for SQL injection: look for string interpolation in queries
3. Verify input validation on all API endpoints
4. Check dependency vulnerabilities: `pip audit` or `npm audit`
5. Review authentication and authorization patterns
6. Report findings with severity levels (Critical/High/Medium/Low)

interface:
  display_name: "Security Audit"
  short_description: "Full codebase security review"
  icon_small: "./assets/shield.svg"
  brand_color: "#DC2626"
  default_prompt: "Run a security audit on this repository"

policy:
  allow_implicit_invocation: false    # Require explicit $skill

dependencies:
  tools:
    - type: "mcp"
      value: "snyk"
      transport: "streamable_http"
      url: "https://mcp.snyk.io/mcp"

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

deploy-skill/
  SKILL.md
  references/
    runbook.md
    rollback-checklist.md
  scripts/
    pre-deploy-check.sh
    smoke-test.sh
  agents/openai.yaml

---
name: deploy
description: Deploy the application to staging or production. Runs pre-flight checks, executes deployment, and verifies with smoke tests.
---

## Deployment Procedure

### Pre-flight
1. Run `scripts/pre-deploy-check.sh` to verify:
   - All tests pass
   - No uncommitted changes
   - Branch is up to date with remote
2. Review the runbook at `references/runbook.md` for environment-specific steps.

### Deploy
3. Execute the deployment command for the target environment.
4. Monitor logs for errors during rollout.

### Verify
5. Run `scripts/smoke-test.sh <environment-url>` to confirm critical paths.
6. If smoke tests fail, follow `references/rollback-checklist.md`.

@deploy push this branch to staging with canary rollout
@linter check for unused imports in src/

# GitHub repository (shorthand)
codex plugin marketplace add owner/repo

# Arbitrary git URL
codex plugin marketplace add https://git.example.com/team/plugins.git

# SSH Git URL
codex plugin marketplace add [email protected]:team/plugins.git

# Local directory
codex plugin marketplace add /path/to/local/marketplace

# Upgrade or remove a configured marketplace
codex plugin marketplace upgrade <marketplace-name>
codex plugin marketplace remove <marketplace-name>

codex plugin marketplace add <src>       # Add a marketplace source
codex plugin marketplace upgrade [name]  # Upgrade one marketplace or all
codex plugin marketplace remove <name>   # Remove a configured marketplace

/plan                              # Switch to plan mode
/plan "redesign the API layer"     # Plan mode with initial prompt

# Codex is refactoring the auth module...

[Enter] "Use bcrypt instead of argon2 — we already have it as a dependency"
→ Codex adjusts immediately, mid-turn

[Tab] "Once auth is done, update the migration script too"
→ Codex finishes auth refactor, then starts the migration

codex resume                          # Interactive picker (sorted by recency)
codex resume <SESSION_ID>             # Resume a specific session
codex exec resume --last "continue"   # Non-interactive: resume most recent

/fork                              # Fork current conversation
/fork "try a different approach"   # Fork with new prompt

/status                            # Current session info and token usage
/ps                                # Show background terminals in session

codex exec "summarize the repository structure"
codex exec --sandbox workspace-write --ask-for-approval on-request "fix the CI failure"
codex exec --json "triage open bugs" -o result.txt

codex archive <session-id>     # archive a session
codex unarchive <session-id>   # restore it

codex exec --json "fix the tests" | jq

{"type":"thread.started","thread_id":"019c5c94-..."}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

codex exec resume --last "continue where you left off"
codex exec resume <SESSION_ID> "fix the remaining issues"
codex exec review --base main           # Code review against a branch

# Start a headless, remotely controllable app-server
codex remote-control

# Same lifecycle as a TUI session: thread store, hooks, plugins, MCP, sandbox
# all initialize from your normal config.toml.

Allowed domains: pypi.org, npmjs.com, github.com
Allowed methods: GET, HEAD, OPTIONS

codex cloud exec --env <ENV_ID> "Fix failing tests"  # Start a cloud task
codex cloud status <TASK_ID>                          # Check task progress
codex cloud diff <TASK_ID>                            # View task diff
codex cloud list                                      # List recent tasks
codex cloud list --json                               # JSON output
codex cloud apply <TASK_ID>                           # Apply from cloud subcommand
codex apply <TASK_ID>                                 # Apply diff (top-level shortcut)

codex app                      # Auto-downloads and installs on first run

# .github/workflows/codex.yml
name: Codex
on:
  pull_request:
    types: [opened]

jobs:
  codex:
    runs-on: ubuntu-latest
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          sandbox: workspace-write
          safety-strategy: drop-sudo

with:
  allow-users: "admin,maintainer"     # Limit who can trigger
  allow-bots: false                   # Block bot-triggered runs

npm install @openai/codex-sdk

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();

// Multi-turn conversation
const turn1 = await thread.run("Diagnose CI failures and propose a fix");
console.log(turn1.finalResponse);

const turn2 = await thread.run("Implement the fix and add tests");
console.log(turn2.items);

// Resume a previous session
const resumed = codex.resumeThread("<thread-id>");
await resumed.run("Continue from previous work");

// Custom working directory, skip git check
const thread = codex.startThread({
  workingDirectory: "/path/to/project",
  skipGitRepoCheck: true,
});

// Custom environment and config overrides
const codex = new Codex({
  env: { CODEX_API_KEY: process.env.MY_KEY },
  config: { model: "gpt-5.5" },
});

codex --version                        # Check CLI version
codex login status                     # Verify authentication
codex mcp list                         # Check MCP server status
codex debug app-server --help          # Debug app server issues

/status                                # Token/session overview
/config                                # Inspect effective config values and sources
/compact                               # Summarize history to reclaim context

npm uninstall -g @openai/codex && npm install -g @openai/codex@latest

codex debug app-server send-message-v2  # Test app-server client

/feedback                              # Send logs to Codex maintainers (in TUI)

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["untrusted", "on-request", "never"]

# Limit available sandbox modes
allowed_sandbox_modes = ["read-only", "workspace-write"]

# Control web search capabilities
allowed_web_search_modes = ["cached"]

# Allowlist MCP servers by identity (both name and identity must match)
[mcp_servers.approved-server]
identity = { command = "npx approved-mcp-server" }

# Admin-enforced command restrictions
[[rules.prefix_rules]]
pattern = [{ token = "rm" }, { any_of = ["-rf", "-fr"] }]
decision = "forbidden"
justification = "Recursive force-delete is prohibited by IT policy"

[[rules.prefix_rules]]
pattern = [{ token = "sudo" }]
decision = "prompt"
justification = "Elevated commands require explicit approval"

# Point Codex at your OTel collector
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.internal:4318"
export OTEL_SERVICE_NAME="codex-cli"
export OTEL_RESOURCE_ATTRIBUTES="team=platform,env=production"

# Launch Codex — trace context propagates to all OpenAI API calls
codex

mkdir my-app && cd my-app && git init
codex

> Create a FastAPI project with: main.py, requirements.txt, Dockerfile,
  basic health endpoint, and a README. Use async throughout.

> /init

> Run the health endpoint test and confirm it passes

cd ~/project && git checkout -b feature/user-auth
codex

> @src/models/user.py @src/api/auth.py
  Add password reset functionality. Requirements:
  1. POST /api/auth/reset-request (email → sends token)
  2. POST /api/auth/reset-confirm (token + new password)
  3. Tests for both endpoints
  Run tests when done.

codex

> /plan Migrate the database layer from raw SQL to SQLAlchemy ORM.
  Constraints: don't change any API contracts, keep all existing tests passing.

[Tab] Also add a migration script using Alembic

> Run the full test suite and report results
> /diff

codex exec --model gpt-5.1-codex-mini \
  "Review the changes in this branch against main. \
   Flag security issues, missed edge cases, and style violations. \
   Format as a markdown checklist." \
  -o review.md

codex cloud exec --env my-env "Diagnose why the /api/orders endpoint returns 500 \
  for orders with > 100 line items. Check the serializer, database query, \
  and pagination logic. Propose a fix with tests."

codex cloud status <TASK_ID>
codex cloud diff <TASK_ID>

codex apply <TASK_ID>

╔═══════════════════════════════════════════════════════════════╗
║                    CODEX CLI QUICK REFERENCE                  ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  LAUNCH                                                       ║
║  codex                      Interactive TUI                   ║
║  codex "prompt"             TUI with initial prompt           ║
║  codex exec "prompt"        Non-interactive mode              ║
║  codex app                  Desktop app                       ║
║  codex resume               Resume previous session           ║
║  codex fork                 Fork a session                    ║
║                                                               ║
║  FLAGS                                                        ║
║  -m, --model <model>        Select model                      ║
║  -p, --profile <name>       Load config profile               ║
║  -s, --sandbox <mode>       Sandbox mode                      ║
║  -C, --cd <dir>             Working directory                 ║
║  -i, --image <file>         Attach image(s)                   ║
║  -c, --config <key=value>   Override config                   ║
║  --ask-for-approval <p>     Approval policy                   ║
║  --oss                      Use local models (Ollama)         ║
║  --search                   Enable live web search            ║
║                                                               ║
║  SLASH COMMANDS (in TUI)                                      ║
║  /compact      Free tokens   /diff        Git diff            ║
║  /review       Code review   /plan        Plan mode           ║
║  /model        Switch model  /status      Session info        ║
║  /fork         Fork thread   /goal        Persisted goal      ║
║  /vim          Modal Vim     /hooks       Browse/toggle hooks ║
║  /init         AGENTS.md scaffold                             ║
║  /mcp          MCP tools     /skills      Invoke skills       ║
║  /ps           Background    /personality Style               ║
║  /permissions  Approval mode /statusline  Footer config       ║
║  /fast         Toggle fast mode (default: on)                ║
║  /copy         Copy last response to clipboard                ║
║  /clear        Clear screen  /theme       Syntax highlighting ║
║                                                               ║
║  TUI SHORTCUTS                                                ║
║  @              Fuzzy file search                             ║
║  !command       Run shell command                             ║
║  Ctrl+G         External editor                               ║
║  Ctrl+L         Clear screen                                  ║
║  Enter          Inject instructions (while running)           ║
║  Esc Esc        Edit previous messages                        ║
║                                                               ║
║  EXEC MODE (CI/CD)                                            ║
║  codex exec --sandbox workspace-write "task" Sandboxed auto   ║
║  codex exec --json -o out.txt "task"    JSON + file output    ║
║  codex exec --output-schema s.json      Structured output     ║
║  codex exec resume --last "continue"    Resume session        ║
║                                                               ║
║  MCP MANAGEMENT [EXPERIMENTAL]                                ║
║  codex mcp add <name> -- <cmd>    Add STDIO server            ║
║  codex mcp add <name> --url <u>   Add HTTP server             ║
║  codex mcp list                    List servers                ║
║  codex mcp login <name>           OAuth flow                  ║
║  codex mcp remove <name>          Delete server               ║
║                                                               ║
║  PLUGINS                                                      ║
║  codex plugin marketplace add <src>     Add marketplace       ║
║  codex plugin marketplace upgrade       Upgrade marketplaces  ║
║                                                               ║
║  CLOUD [EXPERIMENTAL]                                         ║
║  codex cloud exec --env <ID> Start cloud task                 ║
║  codex cloud status <ID>     Check task progress              ║
║  codex cloud diff <ID>       View task diff                   ║
║  codex cloud list            List tasks                       ║
║  codex apply <TASK_ID>       Apply cloud diff locally         ║
║                                                               ║
║  CONFIG FILES                                                 ║
║  ~/.codex/config.toml        User config                      ║
║  .codex/config.toml          Project config                   ║
║  ~/.codex/AGENTS.md          Global instructions              ║
║  AGENTS.md                   Project instructions             ║
║  requirements.toml           Enterprise policy constraints    ║
║                                                               ║
║  SANDBOX MODES                                                ║
║  read-only          Read files only, no mutations             ║
║  workspace-write    Read/write in workspace + /tmp            ║
║  danger-full-access Full machine access                       ║
║                                                               ║
║  APPROVAL POLICIES                                            ║
║  untrusted     Prompt for all mutations                       ║
║  on-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (April 2026)                                          ║
║  gpt-5.5               Recommended default (400K in Codex)   ║
║  gpt-5.5-pro           Highest-effort GPT-5.5 tier            ║
║  gpt-5.4               Prior flagship / fallback              ║
║  gpt-5.4-mini          Subagent work, 2x faster (400K)        ║
║  gpt-5.3-codex         Legacy coding specialist               ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝