---
# System prepended metadata

title: Codex CLI：實務操作與常見問題排查
tags: [speaker, testing, compact context, Plan mode, slash command, experimental features, deterministic scripts, status line, interactive TUI, goals, Git, conversation fork, pull request, Git branch, plugin browser, terminal workflow, code review, sandbox, Model Context Protocol, Codex, auto-review, Auto, IDE integration, format, Read Only, hooks, workspace, plugin, developer tools, session, prevent sleep while running, Graphical User Interface, permission management, feedback, PR workflow, OpenAI Codex, thread, OpenAI, CLI slash command, MCP, Terminal User Interface, TUI, config.toml, npm, saved session, SKILL.md, lint, AI, Git diff, Codex CLI, Agent, GUI, writable roots, MCP tools, terminal resize reflow, Fast mode, skills, logs, config layer, reasoning effort, code modification, app mention, approval policy, software development, diagnostics, open-source TUI, memories, agentic loop, Codex slash command, token usage, connector, Vim mode, sudo, OpenAI Developers, GitHub, realtime voice, '@openai/codex', elevated agent sandbox, debugging, PostToolUse, codebase analysis, conversation, context, AI coding assistant, CLI, Command Line Interface, AI / OpenAI / Codex /, theme, subagents, PreToolUse, yolo mode, model selection, context management, syntax highlighting, apps, approval denial, background terminal, troubleshooting, keymap, working tree, migration plan, lifecycle hooks, terminal title, untracked files, side conversation, MCP server, refactoring, dangerous full access, Windows native sandbox, codex-cli, Agentic AI, Smart Approvals, raw scrollback, microphone, memory, security]

---

Codex CLI：實務操作與常見問題排查
===
###### tags: `AI / OpenAI / Codex /`
###### tags: `AI`, `OpenAI`, `Codex`, `OpenAI Codex`, `Codex CLI`, `codex-cli`, `@openai/codex`, `CLI`, `TUI`, `GUI`, `Terminal User Interface`, `Command Line Interface`, `Graphical User Interface`, `Codex slash command`, `CLI slash command`, `slash command`, `interactive TUI`, `terminal workflow`, `AI coding assistant`, `Agent`, `Agentic AI`, `agentic loop`, `developer tools`, `software development`, `codebase analysis`, `code modification`, `code review`, `debugging`, `troubleshooting`, `refactoring`, `migration plan`, `PR workflow`, `pull request`, `testing`, `lint`, `format`, `workspace`, `writable roots`, `working tree`, `untracked files`, `Git`, `Git diff`, `Git branch`, `context`, `context management`, `token usage`, `conversation`, `session`, `thread`, `saved session`, `conversation fork`, `side conversation`, `compact context`, `model selection`, `reasoning effort`, `Fast mode`, `Plan mode`, `Read Only`, `Auto`, `permission management`, `approval policy`, `auto-review`, `approval denial`, `sandbox`, `Windows native sandbox`, `elevated agent sandbox`, `security`, `dangerous full access`, `yolo mode`, `config layer`, `config.toml`, `diagnostics`, `MCP`, `Model Context Protocol`, `MCP tools`, `MCP server`, `connector`, `apps`, `app mention`, `plugin`, `plugin browser`, `skills`, `SKILL.md`, `memory`, `memories`, `hooks`, `lifecycle hooks`, `deterministic scripts`, `PreToolUse`, `PostToolUse`, `subagents`, `background terminal`, `IDE integration`, `Vim mode`, `keymap`, `status line`, `terminal title`, `syntax highlighting`, `theme`, `raw scrollback`, `realtime voice`, `microphone`, `speaker`, `feedback`, `logs`, `npm`, `sudo`, `OpenAI Developers`, `GitHub`, `open-source TUI`, `experimental features`, `goals`, `Smart Approvals`, `terminal resize reflow`, `prevent sleep while running`

<br>

[TOC]

<br>

> [!Note]
>
> * 內容結構版本：v1.0
> * Author: gpt-5.5-thinking (2026/05/16)

> [!Note]
> **以下順序是依「日常開發重要性」排序**

> [!Tip]
> Codex CLI slash command 是在互動 TUI 裡輸入 `/` 使用

> [!Tip]
> 官方也說任務正在跑時，可以輸入 slash command 後按 `Tab` 先排到下一輪執行。([OpenAI 開發者][20260514-A-1])
> 
> 底下是終端機出現的類似訊息：
> ```
> ...
> • Working (50s • esc to interrupt
> • Messages to be submitted after next tool call
>   (press esc to interrupt and send immediately)
> ```

> [!Warning]
> **版本提醒**：
> 官方文件列的是比較穩定的公開指令；open-source TUI source 裡還看得到 `/ide`、`/vim`、`/memories`、`/skills`、`/hooks`、`/approve`、`/theme`、`/pets`、`/realtime` 等較新或實驗性指令。你本機實際可用清單，仍以 Codex 裡輸入 `/` 跳出的 popup 為準。([OpenAI 開發者][20260514-A-1])
> 
> > **TUI**：Terminal User Interface，終端機使用者介面

> [!Tip] **CLI** vs **TUI** vs **GUI**
> | 類型  | 全稱 | 操作方式 | 例子 |
> | ---- | --- | ------- | ---- |
> | **CLI** | Command Line Interface | 一行一行輸入指令 | `git status`、`kubectl get pods` |
> | **TUI** | **Terminal User Interface** | 在終端機裡用選單、快捷鍵、游標操作 | `htop`、`nmtui`、Codex CLI 畫面 |
> | **GUI** | Graphical User Interface | 視窗、滑鼠、按鈕 | VS Code、Chrome、Windows 設定頁 |
>
> - **TUI**：在終端機裡用選單、快捷鍵、游標操作
>   ![image](https://hackmd.io/_uploads/HkYso8Q1ze.png)

<br>

---
---

<br>


## P0：每天都會用，最重要

### 1. `/permissions`
> 相關指令：[`/status`](#2-status)、[`/approve`](#19-approve-或你版本顯示的-autoreview)、[`/debug-config`](#22-debug-config)

用來設定 Codex 可以自己做什麼、哪些動作要先問你。這是最重要的指令，因為 Codex 可以**讀檔**、**改檔**、**執行命令**；權限設錯，輕則一直卡 approval，重則讓 agent 對 repo 做出你還沒準備好接受的改動。官方說 Codex CLI 可以在你選定目錄讀取、修改、執行程式碼；`/permissions` 可以在 session 中切換 approval preset，例如 `Auto` 或 `Read Only`。([OpenAI 開發者][20260514-A-2])

常見**用法**：

```text
/permissions
```
![image](https://hackmd.io/_uploads/BJzzGfIyGl.png)

常見情境：

| 情境 | 用途 |
| ----- | ----- |
| 只是請 Codex 解釋 codebase | 用 `Read Only` |
| 要讓 Codex 修改目前 repo | 用 `Auto` 或 workspace-write 類型 |
| repo 不在 Git 管理下 | 建議保守，先 Read Only |
| 要讓 Codex 跑測試、lint、format | 允許 workspace 內命令，但外部網路或跨目錄仍要問 |

**注意事項**：不要一開始就開過寬權限。官方文件也特別列出 dangerous full access / yolo 這類無 sandbox、無 approval 的模式，明確標成高風險，不建議一般使用。([OpenAI 開發者][20260514-A-3])

---

### 2. `/status`
> 相關指令：[`/permissions`](#1-permissions)、[`/model`](#3-model)、[`/debug-config`](#22-debug-config)

查看目前 session 狀態：model、approval policy、writable roots、token/context 使用量。這是排錯時第一個該看的指令。官方說 `/status` 可用來確認 active model、approval policy、writable roots、current token usage。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/status
```
![image](https://hackmd.io/_uploads/HJGlzzU1fg.png)

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| Codex 為何不能改檔？ | 看是不是 Read Only |
| Codex 為何看不到某目錄？ | 看 workspace / writable roots |
| 長對話快爆 context？ | 看 token / context |
| 懷疑 model 沒切成功 | 用 `/status` 確認 |

**注意事項**：遇到奇怪行為時，不要先猜，先 `/status`。

---

### 3. `/model`
> 相關指令：[`/status`](#2-status)、[`/fast`](#17-fast)、[`/personality`](#18-personality)

切換模型與 reasoning effort。適合在「小任務」與「複雜架構／除錯任務」間切換。官方文件說 `/model` 可選 active model 與可用時的 reasoning effort；選完後可用 `/status` 確認。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/model
```
![image](https://hackmd.io/_uploads/S1L560Hkze.png)

使用情境：

| 情境 | 用途 |
| ----- | ----- |
| 修 typo、改小段 README | 選較快、成本較低的 model |
| 分析大型 bug、重構、多檔案修改 | 選推理能力較強的 model |
| 產生 migration plan | 選較強 reasoning |
| 跑很多小互動 | 可搭配 `/fast` |

**注意事項**：不要所有任務都用最高推理。小任務用太強 model，通常只是浪費時間與用量。

---

### 4. `/plan`
> 相關指令：[`/model`](#3-model)、[`/diff`](#6-diff)、[`/review`](#7-review)、[`/goal`](#25-goal)

切到 Plan mode，讓 Codex 先提出計畫，不要直接改檔。官方說可以直接 `/plan`，也可以帶 inline prompt，例如 `/plan Propose a migration plan for this service`；但任務正在跑時 `/plan` 暫時不可用。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/plan
/plan Propose a safe migration plan for this Helm chart change
```
![image](https://hackmd.io/_uploads/SkZVkJ8kGx.png)
> [!Tip]
> - 按 `[shift]` + `[tab]` 退出 **plan mode**
> - 模型會降級：`gpt-5.5 default` -> `gpt-5.5 medium`？
> - 不要用：
>   - `/exit`
>   - `/quit`
>   (這是離開整個 Codex CLI，不是退出 plan mode。)

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| **重構前** | 先看影響範圍 |
| **不確定怎麼改** | 讓 Codex 提方案 |
| **PR 前要拆 steps** | 先產生執行順序 |
| **高風險修改** | 避免 Codex 直接動手 |

**注意事項**：
- `/plan` 不是保證不會出錯，而是把「**先想清楚**」變成 **workflow**。
- 你的 prompt 仍要明確定義限制，例如：
    - 「不要修改 API」
    - 「先列出檔案影響」
    - 「不要執行 destructive command」。

---

### 5. `/mention`
> 相關指令：[`/ide`](#32-ide)、[`/apps`](#30-apps)、[`/compact`](#8-compact)、[`/init`](#9-init)

把特定檔案或資料夾加入對話 context。官方說 `/mention src/lib/api.ts` 這類用法可讓 Codex 在後續回合直接參照該檔案。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/mention src/lib/api.ts
/mention helm/slurm/templates/_helpers.tpl
```

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| **Codex 一直看錯檔** | 直接 mention 正確檔 |
| **要解釋某段 code** | 指定檔案 |
| **要比較兩個檔案** | mention 兩者 |
| **要修 Helm template** | mention template 與 values |

**注意事項**：不要一次 mention 太多檔。context 會被吃掉，反而讓重點變模糊。

---

### 6. `/diff`
> 相關指令：[`/review`](#7-review)、[`/status`](#2-status)、[`/copy`](#15-copy)

顯示 Git diff，包含 untracked files。官方說 `/diff` 會顯示 staged、unstaged、Git 尚未追蹤的檔案，讓你決定要保留哪些修改。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/diff
```

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| **Codex 改完檔** | 立刻檢查 |
| **PR 前** | 看完整改動 |
| **懷疑 Codex 多改了東西** | 找 unintended changes |
| **要請 Codex 自我修正** | 先 `/diff` 再說「只保留 X」 |

**注意事項**：不要只看 Codex 的自然語言摘要，一定要看 diff。尤其是 Helm/YAML/CI 類修改，很容易小縮排造成大問題。

---

### 7. `/review`
> 相關指令：[`/diff`](#6-diff)、[`/approve`](#19-approve-或你版本顯示的-autoreview)、[`/copy`](#15-copy)

請 Codex review 目前 working tree。官方說 `/review` 會檢查目前修改，重點放在 behavior changes 與 missing tests，也可接著 `/diff` 看細節。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/review
```
![image](https://hackmd.io/_uploads/Sky5WM8kMe.png)

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| Codex 寫完 patch | 請另一輪 review |
| PR 前 | 找 bug、漏測試 |
| 不確定設計是否合理 | 找風險 |
| 修改 webhook / permission / auth | 特別適合 |

**注意事項**：`/review` 不是正式 code review 的替代品。它適合抓常見問題、風險、漏測，但不要把它當成唯一 gate。

---

### 8. `/compact`
> 相關指令：[`/status`](#2-status)、[`/resume`](#12-resume)、[`/new`](#10-new)

把長對話摘要，釋放 context。官方說 `/compact` 會把早期對話替換成摘要，保留關鍵資訊、釋放 context。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/compact
```

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| **長時間 debug** | 避免 context 爆掉 |
| **Codex 開始忘記前文** | 壓縮歷史 |
| **任務已完成一階段** | 保留結論、丟掉細節 |
| **準備進入下一階段** | 讓 context 更乾淨 |

**注意事項**：compact 後細節可能被摘要化。重要的檔名、commit、錯誤訊息、決策原因，最好先要求 Codex 明確寫進摘要再 compact。

---

### 9. `/init`
> 相關指令：[`/skills`](#26-skills)、[`/memories`](#27-memories)、[`/hooks`](#28-hooks)

產生 `AGENTS.md` scaffold。這很重要，因為 `AGENTS.md` 是讓 Codex 記住 repo 慣例、測試方式、commit 規範、禁止事項的地方。官方說 Codex 會在工作前讀取 `AGENTS.md`，也支援 global 與 project-specific layering。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/init
```

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| **repo 有固定測試方式** | `make test`、`helm unittest` |
| **commit 有規範** | Conventional Commits、Signed-off-by |
| **有禁止事項** | 不要改 generated files |
| **有專案術語** | Slinky、NodeSet、LoginSet 等 |

**注意事項**：`AGENTS.md` 適合放「團隊規範」與「穩定規則」；個人偏好或臨時 context 不一定適合放進 repo。

<br>

---
---

<br>


## P1：高頻工作流，很常用

### 10. `/new`
> 相關指令：[`/clear`](#11-clear)、[`/resume`](#12-resume)、[`/fork`](#13-fork)

在同一個 CLI session 裡開新對話。官方說 `/new` 會開始 fresh conversation (全新的對話)，但不會像 `/clear` ([見下一個指令](#11-clear)) 那樣先清掉目前 terminal view。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/new
```
![image](https://hackmd.io/_uploads/BJoXOx8yGl.png)

**適合情境**：同一個 repo 裡切換到另一個完全不同任務。

**注意事項**：新對話不等於離開 Codex；但前一個 chat context 不會自然帶入。

---

### 11. `/clear`
> 相關指令：[`/new`](#10-new)、[`/compact`](#8-compact)、[`/resume`](#12-resume)

清空 terminal 並開始新 chat。官方特別說 `/clear` 不同於 `Ctrl+L`：`Ctrl+L` 只清畫面，`/clear` 會開始新 conversation。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/clear
```
![image](https://hackmd.io/_uploads/HkxuOlL1zl.png)


**適合情境**：畫面太亂、想重新開始，而且不需要保留目前對話 context。

**注意事項**：如果只是畫面髒，不要用 `/clear`；用 `Ctrl+L` 即可。

---

### 12. `/resume`
> 相關指令：[`/new`](#10-new)、[`/fork`](#13-fork)、[`/rename`](#40-rename)

恢復之前儲存的 conversation。官方說 `/resume` 會從 saved-session picker 選擇 session，重新載入 transcript，讓你接續原本工作。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/resume
```
![image](https://hackmd.io/_uploads/Bk25NGIyGl.png)
(自動切回先前的對話；先前的對話不用刻意紀錄，即保有過去的歷史紀錄，如同 ChatGPT)

**適合情境**：昨天做到一半，今天繼續同一個 repo 任務。

**注意事項**：恢復的是當時的 conversation；但 repo 實際檔案可能已經變了，最好先讓 Codex 檢查目前 Git 狀態。

**案例**：[[案例] Codex CLI：保存並恢復Codex狀態](https://hackmd.io/ULosYtnPTsWbh_6BxzeKwQ)

---

### 13. `/fork`
> 相關指令：[`/side`](#14-side)、[`/resume`](#12-resume)、[`/rename`](#40-rename)

從目前 conversation 分支出新 thread。官方說 `/fork` 會複製目前對話到新 thread，保留原 transcript 不動，方便探索替代方案。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/fork
```

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| **想試另一種實作方式** | fork 出分支 |
| **不想污染主討論** | fork |
| **方案 A/B 比較** | 各 fork 一條 |
| **review 後想大改** | 先 fork |

**注意事項**：conversation fork 不等於 Git branch。檔案層面的分支仍要靠 Git。

---

### 14. `/side`
> 相關指令：[`/fork`](#13-fork)、[`/plan`](#4-plan)、[`/agent`](#33-agent-與-subagents)

開一個 ephemeral side conversation (短暫的閒聊)。官方說 `/side` 會從目前對話開一個短暫分支，適合問聚焦問題，++**不干擾主 thread**++；但不能在另一個 side conversation 或 review mode 裡使用。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/side Check whether this plan has an obvious risk
```

**適合情境**：主任務正在做，你想旁邊問「這個 webhook 設計會不會有風險？」但不想打斷主線。

**注意事項**：side conversation 適合短問答，不適合長期主任務。

---

### 15. `/copy`
> 相關指令：[`/raw`](#16-raw)、[`/diff`](#6-diff)、[`/review`](#7-review)

複製最近一次 Codex 完成的輸出。官方說 `/copy` 會複製 latest completed Codex output；若目前 turn 還在跑，會複製上一個 completed output。也可按 `Ctrl+O`。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/copy
```

**適合情境**：複製 commit message、PR description、troubleshooting 文件、patch summary。

**注意事項**：它複製的是「最近完成的 Codex 輸出」，不是你螢幕上任意選取區塊。

---

### 16. `/raw`
> 相關指令：[`/copy`](#15-copy)、[`/theme`](#38-theme)

切換 raw scrollback mode，方便在 terminal 裡選取與複製。這個指令在 open-source TUI source 裡的描述是「toggle raw scrollback mode for copy-friendly terminal selection」。([GitHub][20260514-A-4])

**用法**：

```text
/raw
```
- **TUI 模式**
    ![image](https://hackmd.io/_uploads/ByDjjgIkGe.png)
- **純文字模式** (`/raw`)
    ![image](https://hackmd.io/_uploads/Hk-1nl8yGx.png)
    如何退回到 TUI 模式？再輸入一次 `/raw` 即可從純文字模式切回 TUI 模式


**適合情境**：你要從 terminal 複製長段輸出、Markdown、diff、錯誤訊息。

**注意事項**：這偏 UI/複製輔助，不會改變 Codex 的推理或權限。

---

### 17. `/fast`
> 相關指令：[`/model`](#3-model)、[`/status`](#2-status)、[`/personality`](#18-personality)

切換 Fast mode。官方說可用 `/fast on`、`/fast off`、`/fast status`，也可以選擇是否持久保存設定。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/fast on
/fast off
/fast status
```

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| **問小問題** | 開 fast |
| **改 typo** | 開 fast |
| **複雜 bug** | 關 fast |
| **架構設計** | 關 fast |

**注意事項**：Fast mode 不是越快越好。要做多檔案重構、權限設計、K8s webhook、Helm chart 修改時，通常不要貪快。

---

### 18. `/personality`
> 相關指令：[`/model`](#3-model)、[`/fast`](#17-fast)、[`/status`](#2-status)

設定 Codex 溝通風格。官方說 `/personality` 可改變回覆風格，不必重寫 prompt；支援 `friendly`、`pragmatic`、`none`，若 active model 不支援則會隱藏。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/personality
```
![image](https://hackmd.io/_uploads/S1OXZz8JMx.png)

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| **想要直接、少廢話** | pragmatic |
| **想要協作感** | friendly |
| **不想被 style 影響** | none |

**注意事項**：它只影響溝通風格，不是能力開關。

<br>

---
---

<br>

## P2：安全、權限、長任務管理

### 19. `/approve` 或你版本顯示的 `/autoreview`
> 相關指令：[`/permissions`](#1-permissions)、[`/debug-config`](#22-debug-config)、[`/test-approval`](#48-test-approval)

用於批准最近一次 auto-review denial 的一次 retry。官方 auto-review 文件寫的是 `/approve`：它會開啟 Auto-review Denials picker，讓你挑一個最近被拒絕的 action 批准重試一次；而且這個批准很窄，只適用於該 exact denied action，不代表相似動作未來都放行。([OpenAI 開發者][20260514-A-5])

**用法**：

```text
/approve
```

你的版本如果顯示：

```text
/autoreview
```

概念上就是處理 recent auto-review denial。

**適合情境**：你確認某個被 auto-review 擋下的命令其實安全，例如 repo 內合法測試或 build command。

**注意事項**：這不是「永久允許」。而且 retry 仍可能再次被 auto-review deny。([OpenAI 開發者][20260514-A-5])

---

### 20. `/sandbox-add-read-dir`
> 相關指令：[`/permissions`](#1-permissions)、[`/debug-config`](#22-debug-config)、[`/setup-default-sandbox`](#21-setup-default-sandbox)

讓 Windows native sandbox 額外讀取某個絕對路徑。官方明確說這個指令只在 Windows native CLI 可用。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/sandbox-add-read-dir C:\absolute\directory\path
```

**適合情境**：Codex 需要讀 workspace 外的 SDK、shared config、另一個 repo，但你只想給 read access。

**注意事項**：
- 這是 read access，不是 write access。
- Linux/macOS 通常不是用這條路徑解法。

---

### 21. `/setup-default-sandbox`
> 相關指令：[`/permissions`](#1-permissions)、[`/sandbox-add-read-dir`](#20-sandbox-add-read-dir)、[`/debug-config`](#22-debug-config)

設定 elevated agent sandbox。這個指令在 open-source TUI source 裡可見，描述是「set up elevated agent sandbox」。([GitHub][20260514-A-4])

**用法**：

```text
/setup-default-sandbox
```

**適合情境**：需要設定更高權限的 agent sandbox profile。

**注意事項**：這屬於安全邊界設定，不熟不要亂調。優先用 `/permissions`、`--add-dir`、writable roots 這種較明確的方式處理。

---

### 22. `/debug-config`
> 相關指令：[`/status`](#2-status)、[`/permissions`](#1-permissions)、[`/mcp`](#29-mcp)、[`/experimental`](#46-experimental)

顯示 config layer 與 requirement diagnostics。官方說它會顯示 config layer order、policy details、`allowed_approval_policies`、`allowed_sandbox_modes`、`mcp_servers`、`rules`、`experimental_network` 等，用來 debug 為何實際設定和 `config.toml` 不一致。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/debug-config
```
![image](https://hackmd.io/_uploads/r1Or6lUkGl.png)
```
Config layer stack (lowest precedence first):
  1. system (/etc/codex/config.toml) (enabled)
  2. user (/home/tj/.codex/config.toml) (enabled)
```

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| **config.toml 設了但沒生效** | 看 precedence |
| **公司 managed config 蓋掉本機設定** | 查 requirement sources |
| **MCP 沒出現** | 看 mcp_servers |
| **sandbox policy 奇怪** | 看 allowed policies |

**注意事項**：這是排錯用，不是日常操作。輸出可能包含環境與路徑資訊，貼給別人前要檢查敏感資料。

---

### 23. `/ps`
> 相關指令：[`/stop`](#24-stop)、[`/goal`](#25-goal)

列出 background terminals。官方說 `/ps` 會列出每個 background terminal 的 command 與最多三行最近非空輸出；如果沒有啟用對應 execution 模式，清單可能是空的。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/ps
```

**適合情境**：Codex 啟動了長時間測試、server、watch command，你想看它還在不在。

**注意事項**：這不是系統全域 `ps`，而是 Codex session 相關的 background terminals。

---

### 24. `/stop`
> 相關指令：[`/ps`](#23-ps)、[`/goal`](#25-goal)

停止目前 session 的所有 background terminals。官方說 `/stop` 會停止 current session 的 background terminals；`/clean` 仍可作為 alias。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/stop
```

**適合情境**：測試卡住、dev server 跑太久、watch command 不需要了。

**注意事項**：它是「全部停止」，不是挑一個停止。停止前先 `/ps` 看清楚。

---

### 25. `/goal`
> 相關指令：[`/experimental`](#46-experimental)、[`/ps`](#23-ps)、[`/stop`](#24-stop)、[`/plan`](#4-plan)

設定或查看 long-running task 的目標。官方說 `/goal` 是 experimental，需要 `features.goals`；可用 `/goal <objective>`、`/goal`、`/goal pause`、`/goal resume`、`/goal clear`。([OpenAI 開發者][20260514-A-1])


**(我理解的) 運作方式**：
```bash
while ( goal: 目標是否滿足 ):
    codex 繼續做事
```

**用法**：

```text
/goal Finish the migration and keep tests green
/goal
/goal pause
/goal resume
/goal clear
```
- #### 啟用 & 測試
    1. **輸入 `/experimental`**
        ![image](https://hackmd.io/_uploads/SJwBD-8kzl.png)
    2. **重新啟動 Codex CLI**
        -> `/exit` 或 `/quit` -> `codex`
        如果沒有重啟，會遇到錯誤：
        ```
        /goal
        ■ Failed to rea`d thread goal: thread/goal/get failed in TU
        ```
    3. **輸入 `/goals`**
        ![image](https://hackmd.io/_uploads/HknbjZ8kzx.png)
        ```
        /goal 開發任何一套軟體，幫我賺大錢
        ```
        ![image](https://hackmd.io/_uploads/Sypuob8kGl.png)
        ![image](https://hackmd.io/_uploads/HkvQCb8Jfg.png)
        (...more...)
        ![image](https://hackmd.io/_uploads/BJYtAbUyzl.png)
        - **查看目標**
            ```
            /goal
            ```
            ![image](https://hackmd.io/_uploads/H1Gas-I1fl.png)
        - **其他指令**
            | 指令 | 說明 |
            | ---- | ---- |
            | `/goal pause` | 暫停目前目標的追蹤 |
            | `/goal resume` | 恢復目前目標的追蹤 |
            | `/goal clear` | 清除目前目標 |
            - Codex 會在後續工作中持續參考這個 goal；
            - pause/resume/clear 是管理這個 goal 的狀態。
            - `/goal clear` 執行前，如果已經執行下去，至少會執行一個 task(或一輪)，接著若發現 goal 已經被清除，就不再做。


**適合情境**：大型任務，例如「完成 Helm chart migration 並保持 tests green」。

**注意事項**：它是實驗性功能。不要把 `/goal` 當成專案管理系統；仍要用 Git、issue、測試結果確認完成度。

<br>

---
---

<br>

## P3：整合、擴充、團隊流程

### 26. `/skills`
> 相關指令：[`/init`](#9-init)、[`/memories`](#27-memories)、[`/hooks`](#28-hooks)、[`/plugins`](#31-plugins)

使用 skills 來改善 Codex 做特定任務的方式。官方說 skill 是一個含 `SKILL.md` 的目錄，可加 scripts、references、assets；CLI/IDE 可用 `/skills` 或輸入 `$` 明確呼叫 skill，也可由 Codex 依描述自動選用。([OpenAI 開發者][20260514-A-6])

**用法**：

```text
/skills
```
![image](https://hackmd.io/_uploads/ByQeRxIkGg.png)

或在 prompt 裡：

```text
Use $my-skill to update this release checklist
```

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| **重複工作流程** | 發版 checklist |
| **固定 repo 維運流程** | PR review 規範 |
| **特定工具流程** | Helm chart update |
| **團隊專用規範** | Conventional Commit + tests |

**注意事項**：skill 的 `description` 很重要，因為 Codex 會用它判斷何時啟用。描述太模糊會誤觸發或不觸發。([OpenAI 開發者][20260514-A-6])

---

### 27. `/memories`
> 相關指令：[`/init`](#9-init)、[`/skills`](#26-skills)、[`/experimental`](#46-experimental)

設定 memory 使用與生成。官方說 memories 可讓 Codex 從過去 thread 帶入穩定偏好、常用 workflow、tech stack、project conventions、known pitfalls；但團隊必要規範仍應放在 `AGENTS.md` 或 repo 文件，不要只靠 memory。([OpenAI 開發者][20260514-A-7])

**用法**：

```text
/memories
```

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| **你常用 pnpm** | 可以 |
| **某 repo 一定要跑 make test** | 更適合 `AGENTS.md` |
| **臨時 bug context** | 不適合 |
| **個人偏好輸出格式** | 可以 |

**注意事項**：memory 是輔助回憶層，不是強制規則。團隊規範、CI 要求、禁止事項，優先寫進 `AGENTS.md`。([OpenAI 開發者][20260514-A-7])

---

### 28. `/hooks`
> 相關指令：[`/skills`](#26-skills)、[`/debug-config`](#22-debug-config)、[`/experimental`](#46-experimental)

檢視與管理 lifecycle hooks (生命週期鉤子)。官方說 hooks 是 Codex 的 extensibility framework，可在 agentic loop 中注入 deterministic scripts (確定性腳本)；進階設定可從 `hooks.json` 或 `config.toml` 載入，並需開啟 `codex_hooks` feature。([OpenAI 開發者][20260514-A-8])

**用法**：

```text
/hooks
```

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| **工具執行前檢查** | 禁止危險 shell command |
| **修改後自動驗證** | 跑 formatter / policy check |
| **團隊安全控管** | 檢查 secret、路徑、network |
| **工作流自動化** | PreToolUse / PostToolUse 類流程 |

**注意事項**：hooks 會影響 agent 行為，寫錯可能讓 Codex 一直被擋或卡住。建議先在小 repo 測試。

---

### 29. `/mcp`
> 相關指令：[`/apps`](#30-apps)、[`/plugins`](#31-plugins)、[`/debug-config`](#22-debug-config)

列出 configured MCP tools。官方說 `/mcp` 可查看此 session 中 Codex 可呼叫哪些 Model Context Protocol tools；`/mcp verbose` 可看詳細 server diagnostics。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/mcp
/mcp verbose
```
![image](https://hackmd.io/_uploads/H1qxZ-Uyzl.png)
...(more)

**適合情境**：

| 情境 | 用途 |
| ----- | ----- |
| ****GitHub / Slack / docs server 沒作用**** | 看 MCP 有沒有載入 |
| ****工具權限不對**** | 用 verbose 查 |
| ****外部 context 需要工具化**** | 確認 tool 是否可用 |

**注意事項**：MCP 連外部系統時，要注意權限、token、prompt injection。不要把不需要的工具全部接上。

---

### 30. `/apps`
> 相關指令：[`/mcp`](#29-mcp)、[`/plugins`](#31-plugins)、[`/mention`](#5-mention)

管理或瀏覽 apps/connectors，並插入 prompt。官方 CLI slash 文件說 `/apps` 會把 app mention 插入 composer，例如 `$app-slug`，讓你馬上要求 Codex 使用它。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/apps
```
![image](https://hackmd.io/_uploads/H1WwZbIkfe.png)

**適合情境**：要讓 Codex 使用 GitHub、Slack、Google Drive 等 connector context。

**注意事項**：app connector 牽涉外部資料與權限，使用前先確認資料來源是否可信。

---

### 31. `/plugins`
> 相關指令：[`/apps`](#30-apps)、[`/skills`](#26-skills)、[`/mcp`](#29-mcp)

瀏覽 plugins。官方說 `/plugins` 可開 plugin browser，查看 installed plugins、discoverable plugins 與狀態；已安裝 plugin 可用 `Space` toggle enabled state。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/plugins
```
![image](https://hackmd.io/_uploads/H1FpWZL1Gx.png)

**適合情境**：要找可重用工具、skill、app、MCP 相關擴充。

**注意事項**：不要為了「看起來強」裝一堆 plugin。外掛越多，工具面越大，排錯與安全風險也越高。

---

### 32. `/ide`
> 相關指令：[`/mention`](#5-mention)、[`/apps`](#30-apps)

帶入 IDE 目前選取內容、開啟檔案與其他 context。這個指令在 open-source TUI source 裡可見，描述是 include current selection, open files, and other context from your IDE。([GitHub][20260514-A-4])

**用法**：

```text
/ide
```

**適合情境**：你在 IDE 選了一段程式碼，要讓 Codex 直接理解目前焦點。

**注意事項**：它依 IDE integration 支援度而定。若沒有 IDE context，可能效果有限。

---

### 33. `/agent` 與 `/subagents`
> 相關指令：[`/goal`](#25-goal)、[`/ps`](#23-ps)、[`/stop`](#24-stop)、[`/side`](#14-side)

切換 active agent thread。官方 slash 文件列 `/agent`，open-source source 也顯示 `/subagents` 是切換 active agent thread 的 alias/相關命令。([OpenAI 開發者][20260514-A-1])

**用法**：

```bash
/agent
/subagents
# 兩個指令等效
```
![image](https://hackmd.io/_uploads/SkfHfWIJfx.png)

**適合情境**：Codex 啟用 subagents 平行處理複雜任務後，你想查看某個 agent 的進度或接續它的工作。

**注意事項**：subagents 適合複雜任務拆解；小任務開 subagents 反而增加雜訊。

<br>

---
---

<br>

## P4：介面、個人偏好、輔助操作

### 34. `/keymap`
> 相關指令：[`/vim`](#35-vim)、[`/statusline`](#36-statusline)

重設 TUI shortcuts。官方說 `/keymap` 可 inspect、update、persist keyboard shortcut bindings，寫入 `tui.keymap`。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/keymap
```
![image](https://hackmd.io/_uploads/H1dRG-Lkze.png)

**適合情境**：你常用 Vim/terminal，想改快捷鍵避免衝突。

**注意事項**：改壞快捷鍵會很煩。建議只改真的衝突的 key。

---

### 35. `/vim`
> 相關指令：[`/keymap`](#34-keymap)

切換 composer 的 Vim mode。這個指令在 open-source TUI source 裡可見，描述是 toggle Vim mode for the composer。([GitHub][20260514-A-4])

**用法**：

```text
/vim
```
![image](https://hackmd.io/_uploads/rkx47-Uyfg.png)

**適合情境**：習慣 Vim keybindings，在 prompt composer 裡想用類 Vim 編輯。

**注意事項**：只影響 composer 編輯體驗，不影響 Codex 修改 code 的方式。

---

### 36. `/statusline`
> 相關指令：[`/status`](#2-status)、[`/title`](#37-title)

設定 TUI footer/status line 顯示項目。官方說可選 model、model+reasoning、context stats、rate limits、git branch、token counters、session id、current directory、Codex version 等，並持久化到 `config.toml`。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/statusline
```
![image](https://hackmd.io/_uploads/S1LP7-IJMe.png)

**適合情境**：你想在 footer 永遠看到 model、context、git branch、rate limit。

**注意事項**：顯示太多會干擾閱讀。保留真正會用到的項目即可。

---

### 37. `/title`
> 相關指令：[`/statusline`](#36-statusline)、[`/rename`](#40-rename)

設定 terminal window/tab title。官方說可顯示 app name、project、spinner、status、thread、git branch、model、task progress 等。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/title
```
![image](https://hackmd.io/_uploads/SJdGV-UyMe.png)

**適合情境**：同時開很多 terminal / repo，希望 tab title 可辨識目前專案與任務。

**注意事項**：這只是 UI 顯示，不影響任務。

---

### 38. `/theme`
> 相關指令：[`/raw`](#16-raw)、[`/statusline`](#36-statusline)

選擇 syntax highlighting theme。open-source TUI source 裡列出 `/theme`，描述是 choose a syntax highlighting theme。([GitHub][20260514-A-4])

**用法**：

```text
/theme
```
![image](https://hackmd.io/_uploads/HyEBVWUJGl.png)

**適合情境**：diff、code block 顏色不清楚，想換主題。

**注意事項**：純顯示設定。

---

### 39. `/pets` 或 `/pet`
> 相關指令：[`/theme`](#38-theme)

選擇或隱藏 terminal pet。source 顯示 canonical 是 `/pets`，並支援 `/pet` alias。([GitHub][20260514-A-4])

**用法**：

```text
/pets
/pet
```

**適合情境**：個人化 TUI。

**注意事項**：完全非必要，屬於趣味/介面偏好。

---

### 40. `/rename`
> 相關指令：[`/resume`](#12-resume)、[`/fork`](#13-fork)、[`/title`](#37-title)

重新命名目前 thread。source 裡 `/rename` 的描述是 rename the current thread，且支援 inline args。([GitHub][20260514-A-4])

**用法**：

```text
/rename Helm namespace label adoption discussion
```

**適合情境**：你會用 `/resume` 找舊 session，想讓 thread 名稱更容易辨識。

**注意事項**：只影響 session 管理，不影響 Git branch 或檔案。

---

### 41. `/realtime`
> 相關指令：[`/settings`](#42-settings)、[`/experimental`](#46-experimental)

切換 realtime voice mode。source 裡描述為 experimental。([GitHub][20260514-A-4])

**用法**：

```text
/realtime
```

**適合情境**：想用語音與 Codex 互動。

**注意事項**：實驗性功能；在 coding 工作中不一定比文字精準。

---

### 42. `/settings`

設定 realtime microphone/speaker。source 描述是 configure realtime microphone/speaker。([GitHub][20260514-A-4])

**用法**：

```text
/settings
```

**適合情境**：使用 `/realtime` 前後調整音訊裝置。

**注意事項**：主要跟 realtime voice 相關；一般 coding session 幾乎用不到。

<br>

---
---

<br>

## P5：帳號、支援、離開

### 43. `/logout`

登出 Codex。官方說 `/logout` 會清除目前 user session 的 local credentials。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/logout
```

**適合情境**：共用電腦、臨時機器、離職交接、測試不同帳號。

**注意事項**：登出前確認沒有任務正在跑、沒有重要 context 只存在目前 session。

---

### 44. `/feedback`

傳送 logs / diagnostics 給 maintainers。官方說 `/feedback` 會依提示收集 logs 或 diagnostics 並提交。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/feedback
```
![image](https://hackmd.io/_uploads/BJpLBZUJfx.png)

**適合情境**：Codex CLI bug、TUI 異常、approval/sandbox 行為怪異。

**注意事項**：送出前注意 logs 是否包含敏感路徑、專案名稱、錯誤訊息、環境資訊。

---

### 45. `/quit` 與 `/exit`

離開 Codex CLI。官方說兩者都會 exit；也提醒離開前要先保存或 commit 重要工作。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/quit
/exit
```

**適合情境**：結束 session。

**注意事項**：離開 Codex 不代表幫你 commit。先自己確認：

```text
/diff
/status
```

必要時再 `git status`、`git diff`、commit。

<br>

---
---

<br>

## P6：實驗性、除錯、一般人少用

### 46. `/experimental`

開關 experimental features。官方說 `/experimental` 可切換 Apps、Smart Approvals 等實驗功能，必要時重啟 Codex 才會套用。([OpenAI 開發者][20260514-A-1])

**用法**：

```text
/experimental
```
![image](https://hackmd.io/_uploads/BJcELZLyzg.png)


目前畫面中可見的功能：

| 功能 | 狀態 | 說明 |
|---|---:|---|
| Terminal resize reflow | 已啟用 | 當 terminal 寬度改變時，重建 Codex 管理的 transcript scrollback，讓畫面重新排版 |
| Memories | 未啟用 | 允許 Codex 從對話建立新 memories，並在新對話中帶入相關 memories |
| External migration | 未啟用 | 當 Codex 偵測到此機器或專案有可遷移的外部 agent config 時，啟動時顯示提示 |
| Goals | 已啟用 | 設定一個 Codex 可長期持續追蹤的 persistent goal |
| Prevent sleep while running | 未啟用 | Codex 執行 thread 時，避免電腦進入睡眠 |

**適合情境**：

| 情境 | 為何適合 |
|---|---|
| 想啟用 `/goal` | `/goal` 是 experimental feature，需要先開啟 Goals |
| 想測試新功能 | 實驗功能通常先放在這裡讓使用者選擇是否啟用 |
| 想調整本機 TUI 行為 | 例如 terminal resize reflow |
| 想管理長期工作目標 | 可啟用 Goals，讓 Codex 持續記住目前目標 |

**注意事項**：

- Experimental features 可能尚未完全穩定。
- 變更會寫入 `config.toml`。
    ```toml
    $ cat ~/.codex/config.toml
    [projects."/tmp"]
    trust_level = "trusted"

    [tui.model_availability_nux]
    "gpt-5.5" = 2

    [features]
    terminal_resize_reflow = true
    goals = true
    ```
- `/goal` 需要啟用 `features.goals` 後才可使用；官方文件也說可以透過 `/experimental` 啟用，或手動在 `[features]` 加上 `goals = true`。


**適合情境**：你要啟用 subagents、goals、apps、smart approvals 等新功能。

**注意事項**：實驗功能可能改名、消失或行為變動。工作環境穩定性比新功能重要。

---

### 47. `/rollout`

列印 rollout file path。source 裡可見，但這偏 debug/internal。([GitHub][20260514-A-4])

**用法**：

```text
/rollout
```

**適合情境**：除錯 Codex 自身 rollout/config 狀態。

**注意事項**：一般使用者幾乎不需要。

---

### 48. `/test-approval`

測試 approval request。source 裡可見，描述是 test approval request。([GitHub][20260514-A-4])

**用法**：

```text
/test-approval
```

**適合情境**：開發或除錯 Codex approval UI / policy。

**注意事項**：一般使用者不需要。不要把它當成真正權限設定工具。

---

### 49. `/debug-m-drop`、`/debug-m-update`

source 裡明確標示 description 為 `DO NOT USE`。([GitHub][20260514-A-4])

**用法**：不建議使用。

**適合情境**：只有 Codex 開發者或非常明確的除錯場景。

**注意事項**：看到 `DO NOT USE` 就不要用。這類指令可能破壞 memory 狀態或造成難以理解的行為。

---

## 建議你的實際使用順序

日常工作可以記這組就好：

```text
/status
/permissions
/model
/plan
/mention
/diff
/review
/compact
/init
```

進階工作再加：

```text
/resume
/fork
/side
/skills
/memories
/hooks
/mcp
/agent
/ps
/stop
```

最核心觀念是：**先控權限，再控 context，再控 diff/review**。Codex 最容易出問題的不是「不會寫 code」，而是「看錯檔案、權限太寬、context 太長、改完沒 review」。

[20260514-A-1]: https://developers.openai.com/codex/cli/slash-commands "Slash commands in Codex CLI | OpenAI Developers"
[20260514-A-2]: https://developers.openai.com/codex/cli "CLI – Codex | OpenAI Developers"
[20260514-A-3]: https://developers.openai.com/codex/agent-approvals-security?utm_source=chatgpt.com "Agent approvals & security – Codex"
[20260514-A-4]: https://raw.githubusercontent.com/openai/codex/main/codex-rs/tui/src/slash_command.rs "raw.githubusercontent.com"
[20260514-A-5]: https://developers.openai.com/codex/concepts/sandboxing/auto-review?utm_source=chatgpt.com "Auto-review – Codex"
[20260514-A-6]: https://developers.openai.com/codex/skills?utm_source=chatgpt.com "Agent Skills – Codex"
[20260514-A-7]: https://developers.openai.com/codex/memories?utm_source=chatgpt.com "Memories – Codex"
[20260514-A-8]: https://developers.openai.com/codex/hooks?utm_source=chatgpt.com "Hooks – Codex"


<br>

## 後記

### codex 指令常常會跳出提示，要求更新
```sudo
# 需要 root 權限才能更新套件
sudo npm install -g @openai/codex
sudo npm install -g npm@11.14.1
```

### 查看 codex 所在與版本
```
$ which codex
/usr/bin/codex

$ codex --version
codex-cli 0.130.0

$ npm list -g @openai/codex
/usr/lib
└── @openai/codex@0.130.0
```

<br>

---

## Troubleshooting
### Codex bubblewrap 安裝問題
- ### Question
    執行 `codex` 時，terminal 最上方出現警告訊息：
    > ⚠ Codex could not find bubblewrap on PATH. Install bubblewrap with your OS package manager. See the sandbox prerequisites: https://developers.openai.com/codex/concepts/sandboxing#prerequisites. Codex will use the bundled bubblewrap in the meantime.

    ![image](https://hackmd.io/_uploads/HyizTYIJze.png)
    codex 為何需要 bubblewrap？
- ### gpt-5.5 (2026/05/17)
    `bubblewrap`（執行檔通常叫 `bwrap`）的用途可以簡化成一句話：

    > **在 Linux 上替某個程式包一層沙盒，限制它看得到哪些檔案、能不能碰網路、能不能看到其他程序、能不能使用某些系統呼叫。**

    Codex 需要它，是因為 Codex 會替你在本機跑指令，例如 `git`、`npm test`、`pytest`、`go test`、`sed`、`python script.py`。這些指令如果完全用你的使用者權限直接跑，++理論上就能讀寫你帳號可碰到的很多東西++。Codex 的 sandbox 是為了讓這些本機指令在「**受限制的環境**」裡執行，而不是預設擁有整台機器的完整存取權。OpenAI 官方文件也說，Codex 的 sandbox 是讓 Codex 能自主行動但不給它不受限制的機器存取權；當 Codex 執行本機命令時，命令會在受限環境中執行。([OpenAI 開發者][20260517-A-1])

    ### bubblewrap 實際限制什麼？

    它主要利用 Linux kernel 的 namespace / seccomp 等機制：

    | 機制 | 效果 | 對 Codex 的意義 |
    | -------------------- | --------------------- | --------------------------- |
    | mount namespace | 決定 sandbox 裡看得到哪些目錄 | 只讓 Codex 看到 workspace 或必要路徑 |
    | read-only bind mount | 把某些路徑掛成唯讀 | 可以讀工具或系統檔，但不能亂改 |
    | user namespace | sandbox 內外 UID/GID 隔離 | 降低權限擴張風險 |
    | PID namespace | 看不到 sandbox 外的程序 | 避免影響或觀察其他程序 |
    | network namespace | 可以限制網路 | 讓預設工作不隨便連外 |
    | seccomp | 限制可用的 system call | 降低危險系統呼叫的攻擊面 |

    bubblewrap 官方 README 說它會建立新的 mount namespace，使用者可以指定 sandbox 內哪些檔案系統路徑可見，也可以讓掛載目錄唯讀；它也支援 user / IPC / PID / network / UTS namespace 與 seccomp filters。([GitHub][20260517-A-2])

    ### Codex 為何不是直接用 Docker？

    因為 Codex CLI 是在你的本機工作目錄旁邊執行，不一定需要完整 container runtime。`bubblewrap` 比 Docker 輕量很多，不需要 Docker daemon，也比較適合「臨時把一個指令包進受限環境」這種用途。

    可以這樣理解：

    ```text
    Docker / Podman:
     比較像啟動一個完整 container 執行環境

    bubblewrap:
     比較像替單一 process 臨時建立一個受限制的 Linux 執行空間
    ```

    bubblewrap 專案本身也說，Docker、systemd-nspawn 這類工具偏向給系統管理員與 orchestration 使用；bubblewrap 則使用 Linux user namespaces 來讓一般非 root 使用者也能建立 sandbox。([GitHub][20260517-A-2])

    ### Codex 的流程大概是這樣

    ```text
    你下指令給 Codex
     ↓
    Codex 判斷要跑本機命令
     ↓
    Codex 用 bwrap 建立 sandbox
     ↓
    在 sandbox 裡執行 git / npm / python / test runner
     ↓
    如果要超出權限，例如讀 workspace 外的檔案或連網
     ↓
    依照 approval policy 決定是否詢問你
    ```

    官方文件說 Codex 的 sandbox 不只套在內建檔案操作，也會套用到它 spawn 出來的命令，例如 `git`、package managers、test runners。([OpenAI 開發者][20260517-A-1])

    ### 所以你看到的 warning 代表什麼？

    你的訊息：

    ```text
    Codex could not find bubblewrap on PATH.
    Codex will use the bundled bubblewrap in the meantime.
    ```

    意思是：

    ```text
    Codex 想找系統上的 bwrap
     ↓
    PATH 裡找不到
     ↓
    先改用 Codex 內建的 bwrap helper
     ↓
    但官方仍建議安裝 OS 套件提供的 bubblewrap
    ```

    OpenAI 文件寫得很明確：Linux / WSL2 要先用套件管理器安裝 `bubblewrap`；Codex 會使用 `PATH` 上第一個找到的 `bwrap`，如果找不到就 fallback 到 bundled helper，但安裝發行版套件會讓這個設定更可靠。([OpenAI 開發者][20260517-A-1])

    ### 直覺比喻

    可以把 Codex 想成一個會幫你操作終端機的助理。

    沒有 sandbox：

    ```text
    助理直接坐在你的帳號裡操作
    能碰到你帳號能碰到的大部分東西
    ```

    有 bubblewrap sandbox：

    ```text
    先把助理放進一個透明隔離房
    房間裡只放這次專案需要的資料夾與工具
    需要出房間做事時，要照規則問你
    ```

    ### 重點結論

    `bubblewrap` 不是 Codex 的 AI 核心，也不是編譯工具。它是 **Linux 上的安全隔離工具**。

    Codex 需要它，主要是為了：

    1. 限制 Codex 執行的本機指令能看到 / 修改哪些檔案。
    2. 限制網路、程序、系統資源等存取範圍。
    3. 讓 Codex 可以在低風險範圍內自動跑測試、改檔、查 git，而不是每一步都問你。
    4. 當 Codex 想超出 sandbox 邊界時，才交給 approval flow。

    所以安裝它是合理的，尤其你如果是在 Linux / WSL2 上使用 Codex CLI，建議直接：

    ```bash
    sudo apt update
    sudo apt install -y bubblewrap
    which bwrap
    bwrap --version
    # bubblewrap 0.9.0 (2026/05/17)
    ```

    [20260517-A-1]: https://developers.openai.com/codex/concepts/sandboxing "Sandbox – Codex | OpenAI Developers"
    [20260517-A-2]: https://github.com/containers/bubblewrap "GitHub - containers/bubblewrap: Low-level unprivileged sandboxing tool used by Flatpak and similar projects · GitHub"


<br>

---

## 其他參考資料
→ OpenAI Developers：Codex CLI
[https://developers.openai.com/codex/cli](https://developers.openai.com/codex/cli)

→ OpenAI Developers：Codex Quickstart
[https://developers.openai.com/codex/quickstart](https://developers.openai.com/codex/quickstart)

→ OpenAI Developers：Codex Authentication
[https://developers.openai.com/codex/auth](https://developers.openai.com/codex/auth)

<br>

{%hackmd vaaMgNRPS4KGJDSFG0ZE0w %}