Mr.Nine 的技术笔记

Appearance

常用配置 ​

⚠️ 前置条件 ​

在进行配置之前，请确保：

  • 已安装 Codex CLI（未安装？请先查看 安装与准备）
  • 已完成账号认证
  • 了解基本的 TOML 格式

配置文件位置

配置文件位于 ~/.codex/config.toml，使用 TOML 格式，可以直接编辑此文件。

配置文件位置 ​

文件说明
~/.codex/config.toml全局用户配置
~/.codex/auth.json认证信息（OAuth Token 或 API Key）
项目目录/.codex/config.toml项目级配置（仅在信任该项目后加载）
~/.codex/AGENTS.md全局指令
项目目录/AGENTS.md项目级指令

配置优先级 ​

Codex CLI 的配置采用分层合并，优先级从高到低：

优先级来源说明
1（最高）命令行 -c key=value 覆盖仅对本次运行生效
2项目级 .codex/config.toml仅对当前项目生效
3--profile 指定的配置档案按需启用的配置组合
4全局 ~/.codex/config.toml对所有项目生效
5（最低）内置默认值未配置时的兜底

项目级配置的限制

项目级 .codex/config.toml 不能覆盖供应商、认证、通知等机器本地配置（如 model_provider、model_providers、notify、profile 等），这些键只在全局配置中生效。

AGENTS.md 指令优先级 ​

AGENTS.md 用于存放给模型的持久指令（类似编码规范、项目约定）：

  • Codex 从项目根目录到当前目录逐级收集所有 AGENTS.md 并拼接
  • 嵌套越深的 AGENTS.md 优先级越高
  • 全局 ~/.codex/AGENTS.md 在项目级文档之前加载
  • 在会话中运行 /init 可自动生成 AGENTS.md 骨架

最小可用配置 ​

刚安装完成？只需配置以下几项即可开始使用：

toml
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
字段说明
model默认使用的模型
approval_policy命令执行的审批策略
sandbox_mode沙箱权限模式

完整配置示例 ​

toml
# ~/.codex/config.toml

# 模型与推理
model = "gpt-5.5"
model_reasoning_effort = "high"
model_reasoning_summary = "auto"

# 审批与沙箱
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

# 网络搜索：live（实时）/ cached（缓存，默认）/ disabled（关闭）
web_search = "live"

# 引用文件的打开方式
file_opener = "vscode"

# 历史记录
[history]
persistence = "save-all"

# 记忆功能（跨会话记住偏好与经验）
[features]
memories = true

[memories]
generate_memories = true
use_memories = true

# Windows 原生沙箱（仅 Windows 生效）
[windows]
sandbox = "elevated"

# 配置档案：codex --profile readonly 启用
[profiles.readonly]
approval_policy = "never"
sandbox_mode = "read-only"

配置项详解 ​

model - 模型 ​

toml
model = "gpt-5.5"
model_reasoning_effort = "high"
model_reasoning_summary = "auto"
字段可选值说明
modelgpt-5.5 等默认模型，可在会话中用 /model 切换
review_model模型名/review 代码审查专用模型，不设置则使用当前会话模型
model_reasoning_effortminimal / low / medium / high / xhigh推理强度，越高越深入但越慢
model_reasoning_summaryauto / concise / detailed / none推理摘要的详细程度

approval_policy - 审批策略 ​

控制何时需要用户确认命令执行：

值说明
untrusted仅自动批准已知安全的只读命令，其余全部询问
on-request模型自行决定何时请求确认（推荐）
on-failure命令在沙箱中失败时才升级询问
never从不询问，失败直接返回给模型

会话中可随时用 /permissions 切换审批预设（Read Only / Auto / Full Access）。

sandbox_mode - 沙箱模式 ​

控制命令执行的文件与网络权限：

值说明
read-only只读磁盘，禁止写入和联网
workspace-write可写工作区与临时目录，网络可选开启（推荐）
danger-full-access无限制，全盘读写 + 联网（谨慎使用）

workspace-write 模式可进一步细化：

toml
[sandbox_workspace_write]
network_access = true                  # 沙箱内允许联网
writable_roots = ["D:/other-project"]  # 额外的可写目录

profiles - 配置档案 ​

将一组配置打包，按需切换：

toml
[profiles.readonly]
approval_policy = "never"
sandbox_mode = "read-only"

[profiles.yolo]
approval_policy = "never"
sandbox_mode = "danger-full-access"
bash
# 启用指定档案
codex --profile readonly

model_providers - 自定义供应商 ​

使用第三方 API 中转时配置：

toml
model_provider = "custom"

[model_providers.custom]
name = "某中转站"
base_url = "https://api.example.com/v1"
env_key = "CUSTOM_API_KEY"      # 从该环境变量读取 API Key
wire_api = "responses"
字段说明
name供应商显示名称
base_urlAPI 端点地址
env_key提供 API Key 的环境变量名
wire_api通信协议，目前仅支持 responses（可省略）

web_search - 网络搜索 ​

toml
web_search = "live"
值说明
cached默认值，从 OpenAI 维护的缓存索引返回结果，降低提示注入风险
live实时抓取最新结果（等效于命令行 --search）
disabled关闭网络搜索

history - 历史记录 ​

toml
[history]
persistence = "save-all"   # save-all（默认）/ none（不落盘）
max_bytes = 10485760       # 可选，超出后丢弃最旧条目

file_opener - 文件打开方式 ​

控制输出中的文件引用以哪种 URI 打开：

toml
file_opener = "vscode"

可选值：vscode（默认）、vscode-insiders、windsurf、cursor、none。

memories - 记忆功能 ​

让 Codex 跨会话记住你的偏好和项目经验，下次自动注入相关记忆。默认关闭，需通过功能开关启用：

toml
[features]
memories = true

[memories]
generate_memories = true   # 允许将新任务作为记忆生成的输入
use_memories = true        # 将已有记忆注入后续会话
字段说明
features.memories集中式功能开关，启用记忆子系统的总开关
memories.generate_memories是否允许从任务中生成新记忆，默认 true
memories.use_memories是否将已有记忆注入后续会话，默认 true
memories.disable_on_external_context设为 true 时，使用了 MCP、网络搜索等外部上下文的任务不参与记忆生成

桌面端开关

ChatGPT 桌面应用中也可在 设置 > 个性化 > Enable memories 直接开启，无需手动编辑配置。

windows - Windows 原生沙箱 ​

在 Windows 上原生运行 Codex 时的沙箱模式（仅 Windows 生效）：

toml
[windows]
sandbox = "elevated"   # elevated（首选）/ unelevated（降级兜底）
值说明
elevated首选模式，使用独立低权限沙箱用户、文件系统权限边界和防火墙规则，隔离最强
unelevated降级兜底，基于当前用户派生受限令牌 + ACL 边界，隔离较弱；当企业策略禁止管理员级设置时可用

首次启用需管理员授权

elevated 模式初次设置需要创建本地沙箱用户和防火墙规则，会弹出 UAC 提示。若公司设备的企业策略拦截了该流程，可临时使用 unelevated 继续工作。

命令行临时覆盖 ​

任何配置项都可以用 -c 在单次运行时覆盖，无需修改文件：

bash
# 临时切换模型与推理强度
codex -c model="gpt-5.5" -c model_reasoning_effort="low"

# 临时关闭网络搜索
codex -c web_search="disabled"

下一步 ​

配置完成后，可以继续了解更多功能：

相关链接 ​