OpenAI Codex CLI · 2026 實戰指南

Codex /goal 與自主執行
完全 Best Practice 手冊

涵蓋 /goal 長時工作流程、--dangerously-bypass-approvals-and-sandbox 安全模式、 24 小時無人值守部署策略，以及所有相關 GitHub 資源。

📋 目錄

Codex CLI 概述與安裝
三層控制模型：Sandbox × Approval × Network
--dangerously-bypass-approvals-and-sandbox 完全解析
/goal 持久化工作流程教學
24 小時無人值守執行策略
config.toml 推薦設定範本
相關 GitHub Repo 彙整
與 Claude Code 比較

1. Codex CLI 概述與安裝

Codex CLI 是 OpenAI 的開源終端 AI 程式碼代理人，以 Rust 撰寫，在本機執行。它能讀取你的 repository、編輯檔案、執行指令，並透過 MCP 連接外部工具。

4M+

每週活躍使用者

0.128+

最新版本線（含 /goal）

GPT-5.5

安裝方式

# npm 全域安裝
npm i -g @openai/codex

# macOS Homebrew
brew install --cask codex

# 自行更新
codex update

# 首次啟動 → 會要求登入 ChatGPT 帳號或 API Key
codex

2. 三層控制模型

Codex 的行為由三個獨立設定共同決定，而非單一開關。這是新手最容易搞混的地方——只調 approval policy 而忘了 sandbox 或 network，會導致指令仍被阻擋。

層級	控制項	作用	選項
Sandbox	`--sandbox`	限制檔案系統與網路的技術邊界	`read-only`、`workspace-write`（預設）、`danger-full-access`
Approval	`--ask-for-approval` / `-a`	何時暫停詢問使用者	`on-request`（預設）、`untrusted`、`never`
Network	`sandbox_workspace_write.network_access`	是否允許對外網路	`true` / `false`（預設 false）

⚠️ 常見陷阱

--full-auto（已棄用）等同 -a on-request -s workspace-write，網路預設仍是關閉的。如果你的任務需要 npm install 或 git push，必須額外開啟 network。

3. --dangerously-bypass-approvals-and-sandbox

這是 Codex 的「核彈開關」，一次移除所有 sandbox 限制與 approval 確認。別名是 --yolo。使用它之後，Codex 不會在寫檔案、執行 shell 指令、存取網路時暫停詢問。

互動模式

# 完全自主 — 不問任何確認
codex --dangerously-bypass-approvals-and-sandbox "重構 auth module 並跑測試"

# 簡寫別名（效果相同）
codex --yolo "重構 auth module 並跑測試"

非互動 / CI 模式（codex exec）

codex exec --dangerously-bypass-approvals-and-sandbox \
  --cd /workspace \
  -m gpt-5.4 \
  "套用 migration 並 commit"

安全等級比較表

使用情境	指令組合	風險
安全唯讀瀏覽	`--sandbox read-only -a on-request`	LOW
自動編輯、問可疑指令	`--sandbox workspace-write -a untrusted`	MED
全自動 workspace（無網路）	`-a never -s workspace-write`	MED
全自動 + 網路	`-a never -s workspace-write` + `network_access = true`	HIGH
完全跳過一切	`--dangerously-bypass-approvals-and-sandbox`	EXTREME

🚨 安全原則

只在以下環境使用 --dangerously-bypass-approvals-and-sandbox：隔離的 Docker 容器、一次性 VM、CI runner、或專用的 devcontainer。在容器中執行時，惡意專案仍能取得容器內所有可及資源，包括 Codex 憑證。

4. /goal 持久化工作流程

/goal 是 Codex CLI 0.128.0 版（2026 年 4～5 月）引入的核心功能—— 它不只是一個 slash command，而是一套完整的目標生命週期管理系統。你給 Codex 一個高層次目標，它會自動進入「Plan → Act → Test → Review → Iterate」的持續循環，直到任務完成或 token 預算耗盡。狀態可以跨 session 保存。

🎯 /goal 設定

→

📋 Plan

→

⚙️ Act

→

🧪 Test

→

🔍 Review

→

↻ Iterate

基本用法

# 在 Codex TUI 中輸入
/goal "將此 Python 專案從 Pydantic v1 遷移到 v2，確保所有測試通過"

# 暫停當前目標
/goal pause

# 恢復目標（可跨 session）
/goal resume

# 清除目標
/goal clear

/goal 的核心特性

特性	說明
狀態持久化	關閉終端機、合上筆電都不會終止工作。目標狀態儲存在 app-server 層
自動暫停與恢復	遇到不可恢復錯誤時自動暫停，並在終端標題顯示提示
預算記帳	追蹤 token 消耗，但目前沒有硬性 $ 上限控制
Runtime Continuation	模型可以在多個 turn 之間持續追蹤同一個目標
環境切換	同一 release 加入了 turn-scoped environment，可在 dev/staging 間切換

最佳實踐：設定 /goal 前的檢查清單

# 1. 確認版本 ≥ 0.128.0
codex --version

# 2. 確保在乾淨的 feature branch 上
git checkout -b feat/codex-migration
git status  # 確認 working tree 乾淨

# 3. 建立清晰的 AGENTS.md（或 spec 檔）
cat > AGENTS.md << 'EOF'
## 目標
將專案從 Express.js 遷移到 Fastify，保持所有 API 端點向後相容。

## 驗收條件
- 所有現有測試通過
- API 回應格式不變
- 效能基準 ≥ 現有水平

## 約束
- 不修改資料庫 schema
- 不新增外部依賴超過 3 個
EOF

# 4. 啟動 Codex 並設定 goal
codex -a never -s workspace-write
# 進入 TUI 後：
/goal "按照 AGENTS.md 的規格完成 Express → Fastify 遷移"

💡 關鍵心法

/goal 不是萬能許願池。給它「具體到可以驗證」的目標效果最好：有明確的交付物、有測試可以跑、有停止規則。模糊的目標（如「改善程式碼品質」）容易讓 agent 漫無目的。

5. 24 小時無人值守執行策略

要讓 Codex 長時間自主運行（如過夜、24 小時以上），需要組合多個工具和策略。以下是經過實戰驗證的完整方案。

方案 A：tmux + /goal（推薦）

# 1. 建立 tmux session
tmux new -s codex-agent

# 2. 在 tmux 內啟動 Codex
codex -a never -s workspace-write \
  -m gpt-5.4 \
  --cd /path/to/project

# 3. 設定持久化目標
/goal "完成整個 v2 API 遷移，包含測試、文件更新、changelog"

# 4. 脫離 tmux（Codex 繼續跑）
# 按 Ctrl+B, D

# 5. 隔天回來
tmux attach -t codex-agent

方案 B：Docker 容器 + codex exec（CI 風格）

# Dockerfile
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y nodejs npm git bubblewrap
RUN npm i -g @openai/codex
WORKDIR /workspace
COPY . .

# 執行指令
docker run -d \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  --name codex-runner \
  my-codex-image \
  codex exec --sandbox danger-full-access \
    -m gpt-5.4 \
    --cd /workspace \
    "按照 spec.md 完成所有 milestone，每個 milestone 完成後 commit"

方案 C：Codex Cloud（最簡單）

# 直接在雲端啟動任務，不需本機保持開啟
codex cloud exec --env ENV_ID "完成 bug triage 並產出報告"

# 加 --attempts 做 best-of-N
codex cloud exec --env ENV_ID --attempts 3 "重構 payment module"

長時執行的防護措施

風險	對策
Token 失控消耗	在 AGENTS.md 中設定 token budget 上限提示；使用 API workspace 層級的額度限制
無限迴圈	設定明確的停止條件（如「所有測試通過即停止」）；/goal 會在不可恢復錯誤時自動暫停
tmux 記憶體洩漏	舊版 Codex 的 TUI 閃爍 dot 會造成 tmux scrollback 暴增。升級到最新版本可緩解
網路中斷	使用 /goal 的持久化：中斷後 resume 即可繼續
Git 衝突	在獨立的 feature branch 上工作；頻繁 commit；Codex 的 worktree 功能可隔離任務
假完成	永遠在接受結果前跑完成審計：檢查 diff、跑測試、驗證文件更新

⚠️ OpenAI 實測數據

OpenAI 工程師曾讓 Codex 搭配 GPT-5.3-Codex（Extra High reasoning）連續跑約 25 小時，消耗約 1,300 萬 tokens，產出約 30,000 行程式碼（從空 repo 建構一個設計工具）。關鍵成功因素：清晰的 spec 檔、milestone-based plan、以及明確的 AGENTS.md。

6. config.toml 推薦設定範本

~/.codex/config.toml
# ── 預設（日常互動開發）──
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

# ── Profile：需要網路但保持 sandbox ──
[profiles.networked]
approval_policy = "never"
sandbox_mode = "workspace-write"

[profiles.networked.sandbox_workspace_write]
network_access = true

# ── Profile：完全自主（僅限容器內）──
[profiles.yolo]
approval_policy = "never"
sandbox_mode = "danger-full-access"

# ── Auto Review（自動審查代替人工確認）──
[auto_review]
policy = """
只允許：workspace 內的檔案修改、git 操作、測試執行。
拒絕：任何涉及 .env 的操作、刪除超過 10 個檔案的批次操作。
"""

# 使用 profile 啟動
codex -p networked "更新所有依賴並跑 migrate"
codex -p yolo "Non-interactive build"

# TUI 內切換權限（不用重啟）
/permissions  # 選擇 Read-only / Auto / Full Access

7. 相關 GitHub Repo 彙整

🔧 openai/codex

Codex CLI 官方 repo（Rust）。所有核心程式碼、release notes、devcontainer 範例都在這裡。

github.com/openai/codex

🧝 aigorahub/elves

自主多批次開發 skill，支援 Claude Code 和 Codex。tmux 多 worker 平行執行，帶 survival guide 和自動 recovery。

github.com/aigorahub/elves

⚡ Oh My Codex (OMX)

Codex 的 orchestration layer，如同 oh-my-zsh。提供 33 個 agent prompt、tmux 平行 worker、persistent memory、autopilot 模式。

github.com/nicholasxuu/oh-my-codex

📖 Codex Secure Devcontainer

官方的安全容器範例，包含 bubblewrap、firewall 規則、環境隔離最佳實踐。

github.com/openai/codex/.devcontainer

📝 OpenAI 長時任務教學

官方 blog：如何讓 Codex 跑長時間任務（含 25 小時實測案例、spec 檔案範本、AGENTS.md 模板）。

developers.openai.com/blog/run-long-horizon-tasks-with-codex

📚 Codex 完整文件

官方 LLM-friendly 全文文件（可供 agent 消費的純文字版）。

developers.openai.com/codex/llms-full.txt

8. 與 Claude Code 比較

面向	Codex CLI	Claude Code
跳過確認	`--dangerously-bypass-approvals-and-sandbox` 或 `--yolo`	`--dangerously-skip-permissions`
長時目標持久化	`/goal`（跨 session 保存，0.128.0+）	無原生等效（需外部 orchestration）
背景執行	需 tmux/screen 或 Codex Cloud	原生支援 background terminal
多環境	turn-scoped environment selection	無原生等效
Cloud 任務	`codex cloud exec`	無（僅本機 CLI）
Sandbox 機制	OS-native（Seatbelt/bwrap/Windows sandbox）	容器化隔離
Auto Review	`approvals_reviewer = "auto_review"`	無
開源	✅ Rust，Apache 2.0	❌ 閉源

🏆 總結建議

日常開發：使用 -a never -s workspace-write profile 即可涵蓋 90% 場景。
長時自主任務：用 /goal + tmux，搭配乾淨 branch 和明確的 AGENTS.md。
CI/CD：用 codex exec + Docker + --sandbox danger-full-access。
真正的 YOLO：只在一次性容器內使用 --dangerously-bypass-approvals-and-sandbox。

Codex /goal 與自主執行完全 Best Practice 手冊