Codex 高级配置教程：全面解析与配置指南
Codex 高级配置教程：全面解析与配置指南
Codex 基础配置可满足日常开发，而高级配置则面向多环境切换、企业安全管控、私有化部署、多模型厂商接入、全链路可观测等复杂场景。本文基于 OpenAI 官方高级配置文档，系统讲解配置优先级、配置档案（Profiles）、自定义模型提供商、精细审批沙箱、OpenTelemetry 监控、TUI 优化等核心能力，提供可直接复制的配置模板，帮助开发者实现安全、灵活、可管控的 Codex 私有化与企业级落地。
一、配置体系进阶：优先级、临时覆盖与配置档案
Codex 采用多层级覆盖的配置体系，高级用法可实现单任务临时覆盖、多环境快速切换、全局 / 项目 / 命令行三级管控。
1. 完整配置优先级（从高到低）
高优先级配置会覆盖低优先级，明确规则可避免冲突：
CLI 标志 /
--config单次覆盖Profile 配置（
--profile <name>）项目配置（
.codex/config.toml，仅信任项目，就近目录优先）用户全局配置（
~/.codex/config.toml）系统配置（Unix：
/etc/codex/config.toml）内置默认值
2. CLI 单次临时覆盖（-c/--config）
无需修改配置文件，单次运行指定参数，支持点表示法嵌套赋值：
# 专用参数
codex --model gpt-5.4
# 通用覆盖（值为 TOML 格式）
codex --config model='"gpt-5.4"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'3. 配置档案 Profiles（实验特性）
Profiles 用于保存多套命名配置，一键切换环境，暂不支持 IDE 扩展。
定义：在
config.toml中添加[profiles.<name>]切换：
codex --profile <name>设为默认：顶层添加
profile = "deep-review"
示例：
# 全局默认
model = "gpt-5.4"
approval_policy = "on-request"
# 深度评审 profile
[profiles.deep-review]
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "never"
# 轻量任务 profile
[profiles.lightweight]
model = "gpt-4.1"
approval_policy = "untrusted"二、项目级高级配置：根目录、项目配置与 Hooks
1. 自定义项目根目录识别
Codex 默认以含 .git 的目录为项目根，可自定义标记：
# 包含任一标记即视为根目录
project_root_markers = [".git", ".hg", ".sl"]
# 禁用向上查找，当前目录为根
project_root_markers = []2. 项目级配置（.codex/config.toml）
从项目根到当前目录，就近目录配置优先
仅信任项目加载，未信任项目跳过，保障安全
项目内相对路径以
.codex/为基准解析
3. 生命周期 Hooks（实验特性）
Hooks 可绑定任务生命周期事件，实现前置 / 后置处理：
存放位置：
~/.codex/hooks.json或<repo>/.codex/hooks.json启用：
[features]
codex_hooks = true三、自定义模型提供商：多厂商、代理、Azure 与私有化
Codex 支持接入 OpenAI 官方、Azure、Ollama、Mistral 等任意兼容 OpenAI 协议的模型服务，实现多模型调度与私有化部署。
1. 核心规则
不可覆盖内置 ID：
openai/ollama/lmstudio快速代理官方服务：直接配置
openai_base_url
openai_base_url = "https://us.api.openai.com/v1"2. 自定义提供商示例
model = "gpt-5.4"
model_provider = "proxy"
# LLM 代理
[model_providers.proxy]
name = "OpenAI Proxy"
base_url = "http://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"
# 本地 Ollama
[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
# Mistral
[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"3. 自定义请求头与命令认证
# 自定义请求头
[model_providers.example]
http_headers = { "X-Example" = "value" }
env_http_headers = { "X-Feature" = "FEATURE_FLAG" }
# 外部命令获取 Token（无 stdin，输出 token）
[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 3000004. Azure 与数据驻留配置
# Azure OpenAI
[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
# 数据驻留（Data Residency）
[model_providers.openaidr]
name = "OpenAI DR"
base_url = "https://us.api.openai.com/v1"5. OSS 开源模型模式
对接本地开源模型（Ollama/LM Studio）：
# --oss 默认使用的提供商
oss_provider = "ollama"
# 运行：codex --oss四、安全与权限：精细审批、沙箱与环境变量管控
1. 精细审批策略
支持粒度控制与自动审核，满足企业合规：
# 基础策略：untrusted/on-request/never/granular
approval_policy = "on-request"
# 自动审核
approvals_reviewer = "auto_review"
# 精细审批示例
approval_policy = { granular = {
sandbox_approval = true,
rules = true,
mcp_elicitations = true,
request_permissions = false,
skill_approval = false
} }
[sandbox_workspace_write]
writable_roots = ["/Users/you/.pyenv/shims"]
network_access = false # 禁用网络2. 沙箱模式
workspace-write：仅工作区可写，.git/.codex只读（推荐）danger-full-access：完全访问（仅隔离环境使用）
sandbox_mode = "workspace-write"
# Windows 沙箱权限
[windows]
sandbox = "elevated" # 管理员权限（推荐）3. Shell 环境变量策略
严控环境变量转发，防止密钥泄露：
[shell_environment_policy]
inherit = "none" # 清空继承
include_only = ["PATH", "HOME"]
exclude = ["AWS_*", "AZURE_*"] # 通配符屏蔽敏感变量
set = { MY_FLAG = "1" }五、模型推理高级调优
# 推理力度：high/medium/low
model_reasoning_effort = "high"
# 推理摘要：none/simple/full
model_reasoning_summary = "none"
# 响应简洁度：low/medium/high（仅 Responses API）
model_verbosity = "low"
# 上下文窗口
model_context_window = 128000
# 隐藏/显示原始推理
hide_agent_reasoning = true
show_raw_agent_reasoning = false六、可观测性：监控、日志、通知与历史
1. OpenTelemetry（OTel）链路追踪
[otel]
environment = "prod"
exporter = { otlp-http = {
endpoint = "https://otel.example.com/v1/logs",
headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}
log_user_prompt = false # 脱敏用户提示2. 关闭匿名指标采集
[analytics]
enabled = false3. 外部通知（任务完成触发）
# 执行外部脚本
notify = ["python3", "/path/to/notify.py"]4. 历史记录与文件打开器
# 历史持久化：none/jsonl
[history]
persistence = "jsonl"
max_bytes = 104857600 # 100MB 上限
# 可点击文件链接：vscode/cursor/windsurf/none
file_opener = "vscode"七、TUI 终端界面高级配置
[tui]
notifications = ["agent-turn-complete", "approval-requested"]
notification_method = "auto" # auto/osc9/bel
notification_condition = "unfocused" # unfocused/always
animations = false
alternate_screen = "never" # 保留终端回滚
show_tooltips = false八、企业级完整高级配置模板
# 全局基础
model = "gpt-5.4"
openai_base_url = "https://us.api.openai.com/v1"
profile = "default"
# 项目根
project_root_markers = [".git"]
# 安全基线
approval_policy = "on-request"
sandbox_mode = "workspace-write"
allow_login_shell = false
# 环境变量管控
[shell_environment_policy]
include_only = ["PATH", "HOME"]
exclude = ["AWS_*", "AZURE_*", "GITHUB_TOKEN"]
# 模型调优
model_reasoning_effort = "high"
model_verbosity = "low"
# 自定义提供商
[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
oss_provider = "ollama"
# 可观测性
[otel]
environment = "prod"
exporter = "none"
[analytics]
enabled = false
# TUI
[tui]
animations = false
notification_condition = "unfocused"
# 功能开关
[features]
codex_hooks = true
multi_agent = true
undo = true九、高级配置最佳实践
多环境隔离：用 Profiles 区分开发 / 评审 / 生产环境，避免手动改配置
安全底线：生产环境禁用
danger-full-access，启用approval_policy=on-request密钥防护：用
shell_environment_policy屏蔽敏感环境变量，禁止转发密钥可观测必开：企业部署启用 OTel，监控 API 调用、工具执行、审批记录
项目信任：敏感仓库不标记信任，禁用项目级配置，防止恶意配置篡改
临时覆盖优先：单任务调试用
--config，不污染全局配置
十、总结
Codex 高级配置构建了多模型接入、全维度安全、可观测监控、灵活环境切换的企业级能力。通过配置分层、自定义提供商、精细沙箱审批、OTel 监控，可实现从个人开发到团队协作、从公有云到私有化部署的全场景适配。建议团队统一维护全局配置模板，结合 Profiles 与项目配置，实现安全、高效、标准化的 AI 编程工作流。