---
title: "05 - AGENTS.md 與 config.toml"
type: note
specialty: Programming
tags: [codex-cli從0開始使用教學, 05-設定, agents-md, config-toml]
created: 2026-08-04
updated: "2026"
modified: 2026-08-04
---

# 05 - AGENTS.md 與 config.toml

← [[04-Sandbox與Approval權限模型]] | [[00-Index]] | 下一篇 → [[06-非互動模式codex-exec]]

---

## 兩個檔案，兩件事

| 檔案 | 管什麼 | 格式 |
|---|---|---|
| **`AGENTS.md`** | **告訴 Codex 怎麼做事**（指示、慣例、規矩）| Markdown |
| **`config.toml`** | **Codex 自己的行為設定**（模型、權限、MCP）| TOML |

對應到 Claude Code 就是 `CLAUDE.md` 和 `settings.json`。

---

## AGENTS.md

### 位置與優先序

解析順序（**後面的覆蓋前面的**）：

1. **`~/.codex/AGENTS.override.md`** ← 最高優先的全域覆蓋
   或 `~/.codex/AGENTS.md` ← 標準全域預設
2. **Repository root 和各層子目錄**——**越靠近目前工作目錄，優先序越高**

專案範圍的解析：Codex 從 repo root 往目前目錄走，每一層檢查 `AGENTS.override.md`，再 `AGENTS.md`，然後 fallback，最後把所有檔案合併，**後面的覆蓋前面的**。

檔案大小預設上限 **32 KiB**（可設定）。

> 📌 這個「override 檔」的設計 Claude Code 沒有——`AGENTS.override.md` 讓你可以在不改共享檔案的情況下覆蓋規則。

### 全域 `~/.codex/AGENTS.md`（建議內容）

```markdown
# 全域指示

## 語言
- 回覆用繁體中文，技術與醫學名詞保留英文

## 工作方式
- 動手前先簡短說明你要做什麼
- 做完列出改了哪些檔案、各改了什麼
- 範圍之外的東西不要順手改

## 硬規則
- **不要 git commit、不要 git push**，除非我明確要求
- 不確定的事情**明確說不確定**，不要猜
- 需要事實查證的內容（醫學、財務數字、引用），標記為「待查證」交給我，不要自己編
```

> 🔴 **最後那條對你至關重要。** Codex **沒有 PubMed MCP**，你的 vault `CLAUDE.md` §4 已經規定「沒有 PubMed 的環境不要猜 PMID → 明確告知待查證」。**把這條寫進全域 `AGENTS.md`，等於幫每個 Codex session 預設裝好這個護欄。**

### 兩個 repo 的 AGENTS.md

⚠️ **`Obsidian-med-note` 已經有 `AGENTS.md`**——Codex 會讀它。確認內容適合。

⚠️ **`Taiwan_IM_board` 目前只有 `CLAUDE.md`**——Codex **讀不到**。要讓它遵守那些規則，得建一份 `AGENTS.md`。

不用整份複製，挑 Codex 真的會碰到的：

```markdown
# Taiwan_IM_board — Codex 工作規則

這是台灣內科專科醫師甄審考古題刷題網站（React 19 + Vite 7，純前端）。

## 最高原則
- **零錯誤優先**：醫療內容寧缺勿錯。題目 / 答案必須與來源逐字一致。
- **嚴禁杜撰**：不確定的數字、試驗、PMID 一律標「待查證」交給審核者，**不要編造**。
  （你沒有文獻查證工具，查證是審核者的工作。）
- 詳解 `status` **一律 `draft`**，**永遠不可**自行改成 `reviewed`。
- 正解依「該考試年度當時的標準」判定。

## 資料格式
- 題庫：`src/data/questions.<年>.json`
- 詳解：`src/data/explanations.<年>.json`（以 id 為 key，與題庫解耦）
- 詳解固定五段式：`### 本題觀念 / ### 選項分析 / ### 答案解析 / ### 核心知識點 / ### 參考資料`
- 完整規範見 `docs/詳解撰寫規範.md`

## 驗證
改完題庫或索引後跑：
```bash
python3 tools/validate.py
python3 tools/build_index.py   # 改題號或考點後
```

## 硬規則
- **不要 git commit、不要 git push**
- **不要修 `.github/workflows/deploy.yml`**——它必定失敗是預期行為（private repo + 免費方案 Pages）
- 禁止罐頭字句：「此選項常是相近疾病」「供後續醫師逐題校閱」「以下為 AI 起草」
```

---

## config.toml

位置：**`~/.codex/config.toml`**

### 常用鍵值

```toml
# ── 模型 ──────────────────────────────
model = "gpt-5.6-terra"              # ⚠️ gpt-5.4 於 2026-08-31 退場
model_reasoning_effort = "high"       # minimal / low / medium / high / xhigh（依模型而定）

# ── 權限（兩個獨立旋鈕）────────────────
approval_policy = "on-request"        # untrusted / on-request / never
sandbox_mode = "workspace-write"      # read-only / workspace-write / danger-full-access

[sandbox_workspace_write]
network_access = false                # 沙箱內能不能連網
# writable_roots = ["/tmp/scratch"]   # repo 之外還能寫哪些路徑

# ── 其他 ──────────────────────────────
web_search = "cached"

[features]
multi_agent = true
shell_tool = true
```

### Profiles（一鍵切換安全等級）⭐

```toml
[profiles.paranoid]
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.ci]
approval_policy = "never"
sandbox_mode = "workspace-write"

[profiles.batch]
approval_policy = "never"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"     # 量產不需要最高思考力度
```

```bash
codex --profile paranoid
codex --profile batch
```

> 💡 **Profile 是 Codex 比 Claude Code 好用的地方之一。** 一行 `--profile` 就切換整組安全設定，不用記一堆 flag。

### MCP servers

`config.toml` 也是設定 MCP server 的地方。詳見 [[07-MCP與擴充]]。

---

## 設定的優先序

大致是（由低到高）：

```
config.toml 的頂層預設
    ↓
--profile 選中的 profile 區塊
    ↓
命令列 flag（如 --full-auto、--sandbox）
```

> ⚠️ **確切的優先序規則以官方 configuration reference 為準。** 本教學的鍵值與行為由公開資料交叉比對而來（官方站在本次撰寫環境無法直接抓取），**實際請以 `codex --help` 和你版本的官方文件驗證**。

---

## 給你的建議設定（完整版）

`~/.codex/config.toml`：

```toml
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

# 盤點 / 稽核：物理上不能改檔
[profiles.audit]
approval_policy = "never"
sandbox_mode = "read-only"

# 量產：被 Herdr 編排時用
[profiles.worker]
approval_policy = "never"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"

# 需要連網（裝相依、抓資料）
[profiles.net]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.net.sandbox_workspace_write]
network_access = true
```

搭配 `~/.codex/AGENTS.md` 的「不要 commit / 不要猜」，這組設定讓每個 Codex session 一開始就在正確的護欄裡。

---

## 🔗 相關筆記

- [[04-Sandbox與Approval權限模型]] — 上一步：兩個旋鈕的意思
- [[06-非互動模式codex-exec]] — 下一步
- [[08-實戰-被Claude指揮的雙手]] — profile 在編排時怎麼用
- [[Programming/Claude-Code/Claude-Code-CLI從0開始使用教學/06-CLAUDE-md與記憶系統|Claude Code CLI 06]] — 對照：`CLAUDE.md` 與 `AGENTS.md` 的關係

---

*最後更新：2026-08-04*