---
title: "高階配置怎麼讀"
description: "把 Codex 高階配置按使用場景和風險邊界拆開，而不是複製一整張會隨版本變化的配置表。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Codex 的高階配置不是“把所有 key 背下來”。更可靠的做法是先分清三件事：

1. 哪些配置影響當前會話的行為。
2. 哪些配置會進入專案或團隊層。
3. 哪些配置會放大安全風險。

完整 key、預設值和實驗狀態以官方 Configuration Reference 為準。本頁只負責建立閱讀順序和落地邊界。

> [!IMPORTANT]
> 不要把高階配置頁當成靜態手冊長期複製。模型名、feature flag、provider 引數、hook 事件和團隊配置都可能變化；教程裡只保留穩定判斷方法，具體欄位回到官方參考頁核驗。

<Cards>
  <Card title="配置參考" href="https://developers.openai.com/codex/config-reference">
    檢視 Codex `config.toml` 的完整欄位、型別和預設行為。
  </Card>
  <Card title="高階配置" href="https://developers.openai.com/codex/config-advanced">
    檢視 profiles、project config、hooks、providers 等高階能力的官方說明。
  </Card>
  <Card title="自定義能力" href="https://developers.openai.com/codex/concepts/customization">
    理解 instructions、rules、skills、subagents 和 hooks 的分工。
  </Card>
</Cards>

## 高階配置的四層

先按“作用範圍”讀配置，比按字母順序讀 key 更穩。

```mermaid
flowchart TB
    User["User 層<br/>CODEX_HOME/config.toml"]
    Project["Project 層<br/>repo 內 .codex/config.toml"]
    Runtime["Runtime 覆蓋<br/>CLI flags / -c overrides"]
    Team["Team / System 層<br/>組織預設值、共享規則、skills"]
    Session["本次 Codex session"]

    Team --> Session
    User --> Session
    Project --> Session
    Runtime --> Session

    Project -. "只在 trusted project 載入" .-> Session
    Runtime -. "隻影響本次 invocation" .-> Session
```

這四層的判斷方式：

- User 層適合個人長期偏好，例如預設審批策略、常用 provider、歷史記錄策略。
- Project 層適合專案規則，例如 repo 內的 instructions、hooks、project-scoped defaults。
- Runtime 覆蓋適合臨時實驗，例如本次換模型、本次改 sandbox、本次停用某個 feature。
- Team / System 層適合組織統一規則，例如共享預設配置、團隊 skills、企業管理要求。

配置越靠近當前任務，越適合表達“本次怎麼跑”；配置越靠近團隊層，越應該表達“所有人都必須遵守什麼”。

## 用 profiles 管“工作模式”

Profiles 是命名配置組，適合把常用工作模式固化下來，例如輕量問答、深度審查、只讀診斷、自動化執行。

```toml
model = "your-default-model"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.readonly]
approval_policy = "on-request"
sandbox_mode = "read-only"

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

啟動時選擇：

```bash
codex --profile readonly
```

Profile 的價值不是省幾行配置，而是降低誤操作機率。比如“只讀診斷”和“可改檔案執行”不應該靠臨場記憶區分，應該變成兩個明確的 profile。

## 用 `-c` 做一次性覆蓋

命令列的 `-c` / `--config` 適合臨時覆蓋配置。它不應該替代長期配置檔案。

```bash
codex -c approval_policy='"on-request"'
codex -c sandbox_mode='"read-only"'
codex -c model_reasoning_effort='"high"'
```

使用時注意三點：

- 值按 TOML 解析，字串通常需要顯式引號。
- Nested key 可以用點號寫法。
- 臨時覆蓋適合實驗，不適合團隊規則。

把 `-c` 當成“本次調參”，把 `config.toml` 當成“長期預設值”，把專案 `.codex/` 當成“這個 repo 的約束”。

## Project config 要先看 trust

Codex 可以讀取專案內的 `.codex/config.toml`。這讓專案可以宣告自己的規則，但也帶來安全邊界問題。

```text
repo/
  .codex/
    config.toml
    hooks.json
  AGENTS.md
```

Project config 的關鍵原則：

- 只在專案受信任時載入 project-scoped config。
- 越靠近當前目錄的 project config 越具體。
- 相對路徑會相對包含該配置的 `.codex/` 目錄解析。
- 不要在公開儲存庫寫入個人 token、私有 endpoint、機器路徑。

專案層適合放團隊共同約束，不適合放個人偏好。個人偏好應留在 `CODEX_HOME/config.toml`。

## Providers 先區分“改 OpenAI endpoint”還是“新增 provider”

很多人把 provider 配置寫複雜，是因為沒有先區分目標。

如果只是讓內建 OpenAI provider 走代理、router 或特定區域 endpoint，通常優先配置 OpenAI base URL，而不是新建 provider。

```toml
openai_base_url = "https://example.internal/v1"
```

如果你確實要接入額外模型服務，再定義 `model_providers.<id>`：

```toml
model_provider = "proxy"

[model_providers.proxy]
name = "Internal OpenAI-compatible proxy"
base_url = "https://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"
```

Provider 配置的風險點：

- `base_url` 會改變請求去向，必須確認資料邊界。
- `env_key` 只引用環境變數名，不要把金鑰寫進配置。
- 自定義 header 可能洩露內部資訊，公開儲存庫要避擴音交。
- 企業或團隊環境應優先使用組織批准的 endpoint。

## Hooks 是自動化，不是裝飾

Hooks 會在 Codex 生命週期的特定事件上執行命令。它們適合做檢查、記錄、策略判斷，但不適合塞入不透明的大型流程。

```toml
[features]
codex_hooks = true

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "/usr/local/bin/check-codex-command"
timeout = 30
```

寫 hooks 前先問四個問題：

- 這個 hook 是否必須自動執行。
- 失敗時是否會阻斷關鍵流程。
- 輸出是否會暴露敏感路徑、token 或使用者資料。
- 團隊成員是否能快速理解它為什麼存在。

Hooks 一旦進入 project 層，就會影響所有使用該 repo 的人。規則越強，說明文件越要清楚。

## Rules、instructions、skills、subagents 的分工

高階配置經常和自定義能力混在一起。可以用下面這張圖判斷職責：

```mermaid
flowchart LR
    Goal["任務目標"] --> Instructions["Instructions / AGENTS.md<br/>告訴 Codex 怎麼做"]
    Instructions --> Tools["Tools / MCP / shell<br/>讓 Codex 能行動"]
    Instructions --> Skills["Skills<br/>複用穩定流程"]
    Instructions --> Subagents["Subagents<br/>拆分角色或並行任務"]
    Tools --> Verification["驗證結果"]
    Skills --> Verification
    Subagents --> Verification
```

選擇方式：

- 穩定規則寫進 instructions。
- 高頻流程沉澱為 skill。
- 需要不同角色或並行處理時使用 subagents。
- 涉及工具呼叫前後的硬性策略時考慮 hooks。
- 隻影響一次任務的偏好用命令列覆蓋。

不要把所有東西都塞進一個配置檔案。可維護性來自邊界清楚，而不是欄位數量多。

## 安全檢查清單

改高階配置前，至少檢查這些點：

1. 是否把金鑰、token、內部 URL 寫進了 repo。
2. 是否把 sandbox 或 approval 調得過鬆。
3. 是否讓 project hooks 在未充分說明的情況下自動執行。
4. 是否把個人機器路徑寫成團隊預設值。
5. 是否複製了會隨版本變化的模型、價格、限制或 feature flag 列表。
6. 是否能用官方 Configuration Reference 解釋每個關鍵欄位。

## 推薦落地順序

第一次做高階配置，不要從完整欄位表開始。按這個順序更穩：

1. 先在 User 層配置個人預設 sandbox 和 approval。
2. 為常用工作模式建立 2-3 個 profiles。
3. 對單次實驗使用 `-c`，確認有效後再固化。
4. 對專案規則使用 `.codex/`，並只提交可公開、可解釋的內容。
5. 再考慮 providers、hooks、subagents、team config。

高階配置的目標不是“可調項最多”，而是讓 Codex 在正確許可權、正確上下文、正確驗證方式下工作。

## 配置變更的驗收方式

高階配置改完以後，不要只看 Codex 能不能啟動。商業專案要驗證三件事：只讀模式是否真的不能寫檔案，常規實現模式是否只能修改預期 workspace，自動化模式是否不會請求人工輸入。只要這三件事沒有驗過，配置就還停留在“看起來能用”的階段。

團隊還應保留一份最小回復路徑。配置變更如果影響 provider、hooks、sandbox、approval 或 project config，必須知道怎樣退回上一版預設值。這樣即使某個 hook 寫錯、某個 provider endpoint 不通，團隊也能快速恢復工作，而不是讓所有 agent 會話同時失敗。
