---
title: "查詢完整配置項"
description: "用官方 Configuration Reference 和 JSON schema 查詢 Codex 配置項，不把高頻變化的長表硬搬進教程。"
verifiedAt: "2026-05-06"
---

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

> [!NOTE]
> 這篇不是配置欄位大全的複製件。Codex 配置項變化很快，完整欄位以官方 Configuration Reference 和 `config-schema.json` 為準；本頁只講怎麼查、怎麼分層、哪些配置改錯會直接影響安全。

Codex 的配置入口主要圍繞兩個檔案：使用者級 `~/.codex/config.toml` 和受信任專案裡的 `.codex/config.toml`。官方說明裡有一個關鍵前提：專案級配置只會在你信任該專案後載入。也就是說，配置不是“哪裡有檔案就一定生效”，而是和專案信任狀態繫結。

```mermaid
flowchart TB
  Need[你要改行為] --> Scope{先判斷作用域}
  Scope --> User[使用者級<br/>~/.codex/config.toml]
  Scope --> Project[專案級<br/>.codex/config.toml]
  Project --> Trust[只在 trusted project 後載入]
  User --> Risk{是否影響安全}
  Trust --> Risk
  Risk --> Safe[普通偏好<br/>主題 / 通知 / file_opener]
  Risk --> Guard[安全邊界<br/>sandbox / approval / network / permissions]
  Guard --> Docs[先查官方安全頁和 schema]
  Safe --> Schema[查 config-schema.json]
```

## 先查這三個官方入口

<Cards>
  <Card title="Configuration Reference" description="完整欄位、型別和說明以官方配置參考為準。" href="https://developers.openai.com/codex/config-reference" />
  <Card title="Config basics" description="先看配置檔案放哪裡、如何生效、如何寫最小配置。" href="https://developers.openai.com/codex/config-basic" />
  <Card title="Advanced Config" description="再看 profile、project-scoped config、sandbox、approval 和高階覆蓋。" href="https://developers.openai.com/codex/config-advanced" />
  <Card title="config-schema.json" description="編輯器補全和機器校驗用官方 JSON schema，不手抄欄位表。" href="https://developers.openai.com/codex/config-schema.json" />
</Cards>

## 配置項應該按職責查

不要從長表第一行掃到最後一行。先判斷你要改的是哪一類行為：

- 模型和 provider：`model`、`review_model`、`model_provider`、`model_providers.*`、`openai_base_url`。
- 沙箱和審批：`sandbox_mode`、`approval_policy`、`sandbox_workspace_write.*`、`default_permissions`、`permissions.*`。
- 專案規則：`project_root_markers`、`project_doc_max_bytes`、`project_doc_fallback_filenames`。
- MCP：`mcp_servers.*`、OAuth、headers、tool allow / deny list、timeout。
- Skills、apps、connectors：`skills.config`、`apps.*`、`tool_suggest.*`。
- TUI 和體驗：`tui.*`、`file_opener`、`notify`、`personality`、`service_tier`。
- 記憶、subagents、後臺狀態：`memories.*`、`agents.*`、`sqlite_home`、`history.*`。
- 監控：`otel.*`、`analytics.enabled`、`feedback.enabled`。
- 企業約束：`requirements.toml` 和 managed configuration。

## 安全相關配置不要孤立看

`approval_policy`、`sandbox_mode`、`sandbox_workspace_write.network_access` 不能只看欄位說明。它們共同決定 Codex 能不能寫檔案、能不能訪問網路、什麼時候停下來讓你確認。

官方安全頁把這條線拆成兩層：

- `sandbox_mode` 決定 Codex 技術上能做什麼，例如能寫哪裡、能不能訪問網路。
- `approval_policy` 決定 Codex 什麼時候必須先問你，例如越過 sandbox、訪問網路或執行不受信任命令。

預設更穩的理解是：本地 CLI / IDE extension 依賴 OS sandbox；Cloud 執行在 OpenAI 管理的隔離容器裡；網路預設關閉，除非你顯式啟用。

```toml
# 保守本地自动化基线：能在工作区内执行，但越界要问
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# 只有明确需要联网命令时才开启
[sandbox_workspace_write]
network_access = false
```

> [!WARNING]
> `danger-full-access` 或 `--yolo` 不是“高階模式”，而是取消 sandbox 和 approval 的高風險模式。只有在你信任儲存庫、任務和執行環境時才考慮，並且要先準備好 Git 回復點。

## 編輯器補全怎麼配

官方提供 `config-schema.json`。在 VS Code、Cursor 或支援 TOML schema 的編輯器裡，可以把下面這行放到 `config.toml` 頂部，讓編輯器直接按官方 schema 做補全和診斷：

```toml
#:schema https://developers.openai.com/codex/config-schema.json
```

這比複製教程裡的欄位表更可靠。欄位新增、棄用、改名時，schema 和官方參考頁才是事實源。

## 改配置前的檢查清單

1. 先判斷作用域：這是個人預設行為，還是隻應該屬於當前專案。
2. 先查官方 reference：確認欄位名、型別、預設值和是否棄用。
3. 安全欄位必須同時查 Agent approvals & security。
4. 不把 API key、token、workspace id 等敏感資訊硬寫進配置示例。
5. 改完執行 `/status` 或 `/debug-config`，確認實際生效層級。
6. 團隊環境優先用 managed configuration 或 `requirements.toml` 約束風險欄位。

## 官方資料

- Configuration Reference：[https://developers.openai.com/codex/config-reference](https://developers.openai.com/codex/config-reference)
- Config basics：[https://developers.openai.com/codex/config-basic](https://developers.openai.com/codex/config-basic)
- Advanced Config：[https://developers.openai.com/codex/config-advanced](https://developers.openai.com/codex/config-advanced)
- Agent approvals & security：[https://developers.openai.com/codex/agent-approvals-security](https://developers.openai.com/codex/agent-approvals-security)
- Managed configuration：[https://developers.openai.com/codex/enterprise/managed-configuration](https://developers.openai.com/codex/enterprise/managed-configuration)

## 接下來去哪

<Cards>
  <Card title="基礎配置" description="先看最小配置、profile 和常見路徑。" href="/zh-Hant/docs/codex/official/02-config-security/06-basic-config" />
  <Card title="審批與安全" description="再理解 sandbox、approval、network 和高風險組合。" href="/zh-Hant/docs/codex/official/02-config-security/07-approval-security" />
  <Card title="高階配置" description="需要分層、擴充套件和團隊約束時，再進入高階配置。" href="/zh-Hant/docs/codex/official/02-config-security/29-advanced-config" />
  <Card title="配置示例" description="按場景看可複製的最小片段，而不是複製完整欄位表。" href="/zh-Hant/docs/codex/official/02-config-security/31-config-samples" />
</Cards>
