---
title: "配置 Codex 基礎選項"
description: "梳理 Codex config.toml 的載入順序、許可權邊界和新手最該先改的基礎項。"
verifiedAt: "2026-05-06"
---

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

Codex 配置不是“偏好設定合集”，而是模型、許可權、工具、網路和團隊治理的控制面。新手只需要先掌握載入順序和安全邊界。

> [!IMPORTANT]
> 不要複製一整份別人機器上的 `config.toml`。先寫最小配置，再按任務增加模型、許可權、MCP、環境變數和 profile。

<Cards>
  <Card title="Config basics" href="https://developers.openai.com/codex/config-basic">
    官方基礎配置入口，確認載入位置和優先順序。
  </Card>
  <Card title="Advanced config" href="/zh-Hant/docs/codex/official/02-config-security/29-advanced-config">
    需要 profile、`-c` 覆蓋和 provider 時再讀高階配置。
  </Card>
  <Card title="Config reference" href="/zh-Hant/docs/codex/official/02-config-security/30-all-config-options">
    查完整 key 時看參考頁，不把完整表格塞進基礎教程。
  </Card>
</Cards>

## 配置從哪裡來

使用者級配置位於：

```text
~/.codex/config.toml
```

專案級配置位於：

```text
.codex/config.toml
```

CLI 和 IDE extension 共享同一套配置層。IDE 裡可以從設定入口開啟 `config.toml`，CLI 則直接讀 `CODEX_HOME` 下的配置。

專案級 `.codex/` 只有在你 trust the project 後才載入。未信任專案會跳過專案本地 config、hooks 和 rules，但使用者級、系統級配置仍會載入。

## 優先順序怎麼理解

```mermaid
flowchart TD
    Flags["CLI flags / --config"] --> Profile["--profile values"]
    Profile --> Project["trusted .codex/config.toml"]
    Project --> User["~/.codex/config.toml"]
    User --> System["/etc/codex/config.toml"]
    System --> BuiltIn["built-in defaults"]
```

越上層優先順序越高：

1. CLI flags 和 `--config` 覆蓋項。
2. `--profile <name>` 選中的 profile 值。
3. 受信任專案裡的 `.codex/config.toml`，越靠近當前目錄越優先。
4. 使用者配置 `~/.codex/config.toml`。
5. 系統配置，例如 Unix 上的 `/etc/codex/config.toml`。
6. 內建預設值。

這個順序決定了配置寫在哪裡：

- 個人長期偏好寫使用者級。
- 專案約定寫專案級。
- 臨時實驗用 CLI flag 或 `--config`。
- 團隊受控機器用系統級或 managed configuration。

## 新手先改哪些項

先改穩定、低風險、影響清楚的項。

### 模型

模型名變化快，不要把教程裡的示例當成長期推薦。寫配置前查官方 Models 或組織內部模型目錄。

```toml
model = "your-current-codex-model"
```

如果團隊有統一模型策略，把預設值放在使用者級或系統級，不要在每個專案裡散落一份。

### 審批策略

`approval_policy` 決定 Codex 什麼時候暫停並向你請求確認。

```toml
approval_policy = "on-request"
```

新手預設保留可審批路徑。只有隔離 CI、一次性審查或受管理環境裡，才考慮更激進的策略。

### 沙箱

`sandbox_mode` 控制檔案系統和網路訪問。

```toml
sandbox_mode = "workspace-write"
```

基礎原則：

- 讀程式碼、審查 diff、寫報告：只讀。
- 修改儲存庫內檔案：workspace-write。
- 訪問網路或系統路徑：明確任務、明確驗證、明確隔離。
- 全許可權：只放在你能重建的臨時環境裡。

### MCP 和外部工具

MCP server 是外部上下文和外部動作入口。先啟用必要工具，再逐個驗證：

- server 能啟動。
- 超時合理。
- token 不進儲存庫。
- 工具輸出被當作不可信輸入。
- 寫入型工具有審批或環境隔離。

### 命令環境

用 `shell_environment_policy` 控制命令能拿到哪些環境變數。

```toml
[shell_environment_policy]
include_only = ["PATH", "HOME"]
```

不要預設把所有環境變數轉發給模型生成的命令，尤其是雲服務 key、資料庫地址和私有 token。

## Profile 怎麼用

Profile 適合儲存“同一個人不同任務”的配置組合。例如：

- 只讀審查。
- 本地小修復。
- 深度 review。
- 隔離 CI 自動化。

不要為每篇教程、每個目錄都建 profile。profile 數量越多，越難判斷當前會話到底用了什麼策略。

示意寫法：

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

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

臨時執行：

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

## 一次性覆蓋

短期實驗優先用 CLI flag。沒有專門 flag 時，用 `-c` 或 `--config` 覆蓋任意 key：

```bash
codex --config sandbox_workspace_write.network_access=true
```

注意 `--config` 的值按 TOML 解析，不是 JSON。字串和陣列需要正確引用；寫不準時先在一次性命令裡驗證，不要直接寫進全域性配置。

## 基礎配置驗收

- 當前會話能說清用了哪一層配置。
- 專案未信任時不會載入專案 `.codex/`。
- sandbox 和 approval 符合任務風險。
- 模型名來自官方或組織當前策略，不來自舊教程複製。
- MCP token、API key、訪問權杖沒有寫進儲存庫。
- 命令環境沒有預設洩露全部環境變數。
- 臨時 `--config` 覆蓋沒有汙染長期配置。

配置越基礎，越要少寫。最小配置跑穩後，再把真實重複需求沉澱進去。
