Codex CLI 配置

Codex CLI 通过配置文件进行定制。本节介绍配置文件的结构、各类配置选项以及如何根据你的需求进行调整。

---

配置文件位置

Codex 的配置文件位于用户主目录下的 ~/.codex/config.toml：

~/.codex/config.toml

如果文件不存在，你需要手动创建。Codex 首次启动时会创建一个默认配置文件。

修改配置后，需要重启 Codex 才能生效。

---

配置文件结构

一个完整的配置文件可能包含以下部分：

完整配置示例

# ~/.codex/config.toml
# 基础设置
[model]
default = "o4-mini"  # 默认使用的模型
# TUI 设置
[tui]
alternate_screen = "auto"  # 替代屏幕模式：auto/always/never
# 技能配置
[skills]
enabled = true
# 特性开关
[features]
js_repl = false  # 是否启用 JavaScript REPL
# MCP 服务器配置
[mcp_servers]
# 通知设置
[notify]
enabled = false

---

模型配置

Codex 支持多种模型，你可以根据任务需求选择：

配置项	类型	说明
model.default	string	默认使用的模型
model.reasoning_effort	string	推理强度：low/medium/high

可用模型

Codex CLI 可用的模型包括：

• o4-mini - 快速高效，适合简单任务
• o4-mini-high - o4-mini 的高推理版本
• o3 - 强大的推理能力
• o3-pro - o3 的专业版本

不同的模型有不同的速度和价格，选择合适的模型可以优化使用体验和成本。

---

TUI 配置

终端用户界面的相关设置：

配置项	类型	说明	默认值
tui.alternate_screen	string	替代屏幕模式：auto/always/never	auto
tui.width	number	终端宽度	0（自动）
tui.height	number	终端高度	0（自动）

替代屏幕模式说明

• auto - 自动检测，在 Zellij 等终端多路复用器中自动禁用
• always - 始终使用替代屏幕（默认体验）
• never - 从不使用替代屏幕（保留滚动历史）

运行时覆盖

你可以在运行时通过命令行参数覆盖这些设置：

命令行覆盖配置

# 禁用替代屏幕模式
codex --no-alt-screen

---

技能配置

技能（Skills）是 Codex 的扩展机制，允许你自定义工作流程：

配置项	类型	说明
skills.enabled	boolean	是否启用技能系统
skills.directory	string	技能文件目录

自定义技能目录

配置技能目录

[skills]
enabled = true
directory = "~/my-codex-skills"

---

MCP 服务器配置

MCP（Model Context Protocol）服务器允许 Codex 与外部工具和服务集成：

配置 MCP 服务器

[mcp_servers.docs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "./docs"]
# 工具权限配置
[mcp_servers.docs.tools.search]
approval_mode = "approve"

MCP 工具权限

你可以为每个 MCP 服务器的工具单独设置权限：

• approve - 自动批准，无需询问
• deny - 自动拒绝
• ask - 每次执行前询问（默认）

配置 MCP 服务器时要小心，确保只启用你信任的工具。

---

特性开关

启用或禁用 Codex 的特定功能：

配置项	类型	说明
features.js_repl	boolean	启用 JavaScript REPL
features.js_repl_tools_only	boolean	限制为仅 js_repl 工具

JavaScript REPL 配置

启用 JavaScript REPL

[features]
js_repl = true

你还可以指定 Node.js 路径：

指定 Node.js 路径

js_repl_node_path = "/usr/local/bin/node"

---

通知配置

Codex 可以在任务完成时发送通知：

配置项	类型	说明
notify.enabled	boolean	启用通知

配置通知钩子

你可以通过环境变量配置自定义的通知脚本：

CODEX_NOTIFY_HOOK=/path/to/your/notify-script.sh

---

SQLite 状态数据库

Codex 使用 SQLite 存储内部状态：

环境变量	说明	默认值
CODEX_SQLITE_HOME	SQLite 数据库目录	与 CODEX_HOME 相同

配置 SQLite 目录

export CODEX_SQLITE_HOME=/path/to/sqlite
codex

---

日志配置

Codex 使用 Rust 的 env_logger，你可以配置日志级别：

配置日志输出

# 查看日志
tail -f ~/.codex/log/codex-tui.log
# 设置日志级别
RUST_LOG=codex_core=info,codex_tui=info,codex_rmcp_client=info codex

日志级别	说明
error	只显示错误
warn	显示警告和错误
info	显示一般信息、警告和错误
debug	显示调试信息
trace	显示详细跟踪信息

默认情况下，TUI 模式的日志级别是 info，非交互模式（exec）的默认级别是 error。

---

计划模式配置

配置 Codex 在计划模式下的行为：

配置计划模式

# 设置计划模式的默认推理强度
# 可选值：low/medium/high/none
plan_mode_reasoning_effort = "medium"

---

常见配置示例

基本配置

最小配置

# 使用默认设置
# Codex 已经提供了合理的默认值

高性能配置

性能优化配置

[model]
default = "o4-mini"
[tui]
alternate_screen = "always"
[features]
js_repl = true

开发者配置

[model]
default = "o4-mini"
reasoning_effort = "high"
[tui]
alternate_screen = "never"
[skills]
enabled = true
directory = "~/codex-skills"