config.toml 高级配置

8.1 Profiles 多环境配置

Profiles 让你为不同场景维护不同配置(如工作项目、个人项目、CI 环境)。Profile 文件放在:

$CODEX_HOME/profile-name.config.toml

例如:

~/.codex/work.config.toml

model = "gpt-5.3-codex"
model_reasoning_effort = "high"
approval_policy = "on-request"

~/.codex/ci.config.toml

model = "gpt-5.4-mini"
approval_policy = "never"
hide_agent_reasoning = true

通过 CLI 切换 Profile

codex --profile work "重构 auth 模块"
codex --profile ci "跑通 pytest"

8.2 CLI 单次覆盖

除了改 config.toml,也可以用命令行参数单次覆盖(不影响配置文件):

# 覆盖模型
codex --model gpt-5-codex "你的 prompt"

# 覆盖沙箱模式
codex --sandbox workspace-write "你的 prompt"

# 覆盖审批策略(-a 或 --ask-for-approval)
codex -a on-request "你的 prompt"

# 简写
codex -s read-only "审查这段代码"

全局标志与命令概览

CSDN《完整指南(四)》整理的 CLI 命令体系:

命令	作用
codex	进入交互式 REPL
codex "prompt"	直接执行一次性任务
codex exec "prompt"	非交互执行(适合 CI)
codex apply	应用补丁
codex resume	恢复会话
codex login / codex logout	登录 / 登出
codex mcp	管理 MCP 服务器
codex mcp-server	启动 MCP 服务器
codex sandbox	沙箱相关操作
codex cloud	云端 Agent 相关
codex completion	生成 shell 补全
codex execpolicy	执行策略管理
codex app-server	App 模式服务器

8.3 自定义模型提供方

接入第三方 API 聚合平台(如 laozhang.ai 等)或自建网关时,需要覆盖 base_url:

~/.codex/config.toml

[model_providers.custom]
name = "custom-provider"
base_url = "https://your-proxy.example.com/v1"
env_key = "OPENAI_API_KEY"

然后设置环境变量:

export OPENAI_API_KEY="sk-..."

8.4 OpenAI 基础 URL 覆盖

简单场景下直接覆盖 OpenAI 的 base_url:

# 指向自建网关或镜像
[model_providers.openai]
base_url = "https://your-mirror.example.com/v1"

8.5 OSS 模式:接入本地开源模型

Codex 支持接入本地开源模型(如 Qwen、DeepSeek、Ollama 上的模型):

~/.codex/config.toml

[model_providers.oss]
name = "oss"
base_url = "http://localhost:11434/v1"  # 以 Ollama 为例
env_key = "OSS_API_KEY"

# 设为默认
model = "qwen3-coder"
model_provider = "oss"
model_reasoning_effort = "medium"
approval_policy = "never"

掘金教程提到接入智谱、Ollama 本地模型时,approval_policy 可设为 never,model_reasoning_effort 建议 medium。

8.6 Azure OpenAI 提供方

企业用 Azure OpenAI 时:

[model_providers.azure]
name = "azure"
base_url = "https://your-resource.openai.azure.com"
env_key = "AZURE_OPENAI_API_KEY"

8.7 模型推理参数

# 推理强度:影响速度与质量
model_reasoning_effort = "medium"  # low / medium / high / extra high

# 输出冗长度
model_verbose_outputs = false

# Token 限制(按需调整)
# max_tokens = 4096

reasoning_effort 选择建议(来自官方 best practices)

等级	适合场景
low	快速、范围明确的任务
medium	一般任务(默认)
high	复杂变更、调试
extra high	长时间 agentic、推理密集型任务

8.8 Shell 环境变量策略

Codex 执行命令时继承的 shell 环境可在 config.toml 中控制,用于限制或注入特定环境变量(详见官方 config 文档)。

8.9 可观测性与遥测

config.toml 支持遥测配置,用于监控 Codex 的调用、性能、错误(具体字段以官方文档为准)。

8.10 项目指令发现

Codex 会从当前目录向上查找 AGENTS.md(见第 10 章),找到的最近一份会被加载进上下文。

8.11 TUI options

终端 UI 相关选项,如主题(theme 可通过 /theme 切换)、UI 行为等。

8.12 完整配置参考

更完整的字段列表建议直接查看:

• 官方文档:developers.openai.com/codex/config-sample
• 本地 codex --help 与 /experimental 输出

⚠️ Codex 迭代极快,配置字段会随版本变化。本章节列出的是 2026 年中公开资料中确认存在的主干字段,完整字段以官方 sample 配置为准。

8.13 requirements.toml

项目可放一份 requirements.toml 声明依赖(如需要的 Node 版本、必需的工具),Codex 启动时会校验。具体格式以官方文档为准。

资料来源

• CSDN《Codex 完整指南(五):config.toml 配置详解》——Profiles、CLI 覆盖、自定义提供方、Azure、遥测
• CSDN《Codex 完整指南(四):多端使用全景图》——CLI 命令体系
• 掘金《Codex 接哪个模型效果最好》——Profile 配置示例
• 掘金《在 Codex 中配置使用智谱、Ollama 本地模型》——OSS 模式
• 官方文档 developers.openai.com/codex/config-sample