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
# 基础设置
[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
codex --no-alt-screen
技能配置
技能（Skills）是 Codex 的扩展机制，允许你自定义工作流程：
| 配置项 | 类型 | 说明 |
|---|---|---|
skills.enabled | boolean | 是否启用技能系统 |
skills.directory | string | 技能文件目录 |
自定义技能目录
配置技能目录
[skills]
enabled = true
directory = "~/my-codex-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"
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
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
日志配置
Codex 使用 Rust 的 env_logger，你可以配置日志级别：
配置日志输出
# 查看日志
tail -f ~/.codex/log/codex-tui.log
# 设置日志级别
RUST_LOG=codex_core=info,codex_tui=info,codex_rmcp_client=info codex
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"
# 可选值：low/medium/high/none
plan_mode_reasoning_effort = "medium"
常见配置示例
基本配置
最小配置
# 使用默认设置
# Codex 已经提供了合理的默认值
# Codex 已经提供了合理的默认值
高性能配置
性能优化配置
[model]
default = "o4-mini"
[tui]
alternate_screen = "always"
[features]
js_repl = true
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"
default = "o4-mini"
reasoning_effort = "high"
[tui]
alternate_screen = "never"
[skills]
enabled = true
directory = "~/codex-skills"
点我分享笔记