---
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="/docs/codex/official/02-config-security/06-basic-config" />
  <Card title="审批与安全" description="再理解 sandbox、approval、network 和高风险组合。" href="/docs/codex/official/02-config-security/07-approval-security" />
  <Card title="高级配置" description="需要分层、扩展和团队约束时，再进入高级配置。" href="/docs/codex/official/02-config-security/29-advanced-config" />
  <Card title="配置示例" description="按场景看可复制的最小片段，而不是复制完整字段表。" href="/docs/codex/official/02-config-security/31-config-samples" />
</Cards>
