---
title: "參考配置樣例"
description: "用少量 config.toml 配置讓 Codex 行為穩定，而不是複製一整份巨型配置。"
verifiedAt: "2026-05-06"
---

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

`config.toml` 是 Codex 的長期偏好檔案。它適合放模型預設值、沙箱、審批、MCP、profile 和少量 UI 行為。

> [!IMPORTANT]
> 配置樣例不是推薦你照抄。模型名、provider、feature flags 和許可權策略都應按當前官方文件、組織要求和專案風險決定。

<Cards>
  <Card title="Config basics" href="/zh-Hant/docs/codex/official/02-config-security/06-basic-config">
    先理解配置載入位置、優先順序和 trust 邊界。
  </Card>
  <Card title="Config reference" href="/zh-Hant/docs/codex/official/02-config-security/30-all-config-options">
    完整 key 去參考頁查，不要複製巨型配置。
  </Card>
  <Card title="Sandbox boundaries" href="/zh-Hant/docs/codex/official/02-config-security/49-sandbox-boundaries">
    配置最重要的是許可權邊界，而不是功能堆疊。
  </Card>
</Cards>

## 解決什麼

```mermaid
flowchart LR
    Need["repeated behavior"] --> Config["config.toml"]
    Config --> Session["consistent sessions"]
    Session --> Verify["status / small task"]
```

配置檔案解決的是“每次開啟 Codex 都希望行為一致”的問題：

- 預設用哪個模型。
- 預設是否能改檔案。
- 什麼時候需要批准命令。
- 專案級規則和個人習慣如何分開。
- 哪些 MCP 或工具預設可用。

不要把配置檔案當成“功能大全”。配置越多，排查越難。

## 最小起點

先從最小可解釋配置開始：

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

含義：

- `model`：預設模型。寫入前查官方 Models 或組織模型策略。
- `approval_policy = "on-request"`：越過邊界時詢問。
- `sandbox_mode = "workspace-write"`：允許在工作區內讀寫，仍保留邊界。

這比 `danger-full-access` 更適合真實專案，也比純 `read-only` 更適合日常開發。

## 配置放哪裡

使用者級 `~/.codex/config.toml`：

- 個人預設模型。
- 個人 UI 偏好。
- 個人常用 MCP。
- 不依賴某個儲存庫的習慣。

專案級 `.codex/config.toml`：

- 當前儲存庫的預設 sandbox。
- 當前儲存庫需要的 MCP。
- 當前儲存庫特定 profile。
- 團隊希望共享的行為。

命令列引數和 `--config` 只適合一次性覆蓋，不適合長期偏好。

## 先管安全邊界

配置裡最重要的是兩類：

- `sandbox_mode`：Codex 能訪問和修改哪裡。
- `approval_policy`：Codex 什麼時候停下來問你。

常見組合：

- 保守分析：`read-only` + `on-request`。
- 日常開發：`workspace-write` + `on-request`。
- 高風險全開：`danger-full-access` + `never`。

新手不要把高風險全開寫進預設配置。只有在一次性、可信、可回復的自動化環境中，才考慮這種組合。

## Profile 切場景

如果有多個固定場景，用 profile，不要反覆改同一份配置。

```toml
[profiles.review]
sandbox_mode = "read-only"
approval_policy = "on-request"

[profiles.build]
sandbox_mode = "workspace-write"
approval_policy = "on-request"
```

這樣可以把只讀審查和動手開發分開。最常見的問題就是在該只讀的時候用了動手模式。

## 不急著配置的項

這些配置官方支援，但新手不必急著寫：

- 自定義 model provider。
- 複雜網路許可權 profile。
- OTEL / telemetry。
- hooks。
- 自動審批 reviewer。
- 大量 MCP server。
- 自定義 compaction prompt。

等遇到真實問題，再加對應配置。配置應該來自痛點，不應該來自“看起來專業”。

## 怎麼判斷生效

改完配置後，用 `/status` 或啟動後的狀態資訊確認：

- 當前模型是否符合預期。
- sandbox 是否是你想要的模式。
- approval policy 是否生效。
- 專案級配置是否被載入。

再用小任務驗證：讀檔案、改一個測試檔案、執行 `git status`。看它是否在該問你的時候問你，在不該越界時保持邊界。

## 常見坑

- 整份複製配置樣例，結果不知道哪個鍵影響行為。
- 把個人偏好寫進專案級配置，汙染團隊儲存庫。
- 專案級配置寫好後忘記 trust project，導致它沒載入。
- 預設使用 `danger-full-access`。
- 配了 MCP 或 provider，卻沒有配置憑據來源。
- 把金鑰、token 或 auth 檔案路徑寫進可提交配置。

## 官方資料

- [Config Reference](https://developers.openai.com/codex/config-reference)
- [Best practices](https://developers.openai.com/codex/learn/best-practices)
- [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals)
