Appearance
本文是 Codex 配置进阶指南，适合需要精细控制行为的场景：用 Profiles 在多套配置间切换、用 -c 做单次覆盖、接入自定义 LLM Provider（代理、Azure、Mistral、Ollama）、配置 OTel 遥测导出、控制 shell 环境变量、管理历史记录持久化，以及 TUI 和通知选项。
Codex 高级配置
基础配置（模型、审批策略、沙箱）见配置基础。本文覆盖需要更多控制的高级场景。
Profiles：命名配置集
Profiles 让你在 config.toml 里预定义多套配置，运行时用 --profile <name> 切换。
Profiles 目前是实验性功能，未来可能变动。IDE 扩展暂不支持 Profiles。
在 config.toml 里定义：
toml
model = "gpt-5.4"
approval_policy = "on-request"
[profiles.deep-review]
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "never"
[profiles.lightweight]
model = "gpt-4.1"
approval_policy = "untrusted"使用时：
bash
codex --profile deep-review设置默认 Profile：
toml
profile = "deep-review" # 顶层设置，不传 --profile 时使用这个Profiles 也可以覆盖 model_catalog_json，Profile 里的值优先于顶层值。
CLI 一次性覆盖
不想改 config.toml 时，用 -c / --config 做单次运行覆盖：
bash
# 用专用 flag
codex --model gpt-5.4
# 用 key/value 覆盖任意配置项（值是 TOML 格式）
codex --config model='"gpt-5.4"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'- key 支持点号路径访问嵌套值：
mcp_servers.context7.enabled=false - 值按 TOML 解析，字符串要加引号，字符串里有空格时整体加 shell 引号
- 无法解析为 TOML 时当作字符串处理
配置和状态文件位置
Codex 把本地状态存在 CODEX_HOME（默认 ~/.codex）：
config.toml— 用户配置auth.json— 文件型凭据（或操作系统密钥链）history.jsonl— 会话历史（如启用）
项目配置文件
仓库里放 .codex/config.toml 可以覆盖用户级配置。Codex 从项目根到当前工作目录逐层读取，靠近工作目录的文件优先级更高。
- 仅受信任的项目会加载项目配置
- 配置文件里的相对路径（如
model_instructions_file）相对.codex/目录解析
指向 OpenAI 代理或数据驻留项目时，直接设置 openai_base_url，不需要新建 provider：
toml
openai_base_url = "https://us.api.openai.com/v1"自定义模型 Provider
除了内置的 openai、ollama、lmstudio，你可以接入任意兼容 API 的模型服务：
toml
model = "gpt-5.4"
model_provider = "proxy"
[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"
[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"需要自定义请求头时：
toml
[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }命令认证（让 Codex 从外部 credential helper 获取 token）：
toml
[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000认证命令不接收 stdin，必须把 token 打印到 stdout。设置 refresh_interval_ms = 0 表示只在认证失败时重新获取。不能与 env_key、experimental_bearer_token、requires_openai_auth 同时使用。
Azure Provider
toml
[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000修改内置 OpenAI provider 的 base URL 用 openai_base_url，不要创建 [model_providers.openai]（内置 ID 不可覆盖）。
ChatGPT 数据驻留
启用了数据驻留的 project：
toml
model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1" # 替换 'us' 为对应区域前缀OSS 本地模式
使用 --oss 接入本地模型：
toml
oss_provider = "ollama" # 或 "lmstudio"模型推理和详细程度
toml
model_reasoning_summary = "none" # 关闭推理摘要
model_verbosity = "low" # 缩短回复（仅 Responses API）
model_supports_reasoning_summaries = true # 强制启用推理
model_context_window = 128000 # 上下文窗口大小审批策略和沙箱（进阶）
支持细粒度审批策略，针对不同操作类型分别设置自动通过或自动拒绝：
toml
approval_policy = "untrusted"
sandbox_mode = "workspace-write"
allow_login_shell = false # 禁止 login shell
# 细粒度审批示例：
# approval_policy = { granular = {
# sandbox_approval = true,
# rules = true,
# mcp_elicitations = true,
# request_permissions = false,
# skill_approval = false
# } }
[sandbox_workspace_write]
exclude_tmpdir_env_var = false # 允许 $TMPDIR
exclude_slash_tmp = false # 允许 /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = falseShell 环境变量策略
shell_environment_policy 控制 Codex 向子进程传递哪些环境变量，防止泄露密钥：
toml
[shell_environment_policy]
inherit = "none" # 从干净环境开始；或 "core" 保留基础变量
set = { PATH = "/usr/bin", MY_FLAG = "1" }
ignore_default_excludes = false # 保留 KEY/SECRET/TOKEN 自动过滤
exclude = ["AWS_*", "AZURE_*"]
include_only = ["PATH", "HOME"]Pattern 是大小写不敏感的 glob（*、?、[A-Z]）。
OTel 遥测导出
启用 OpenTelemetry 日志导出，追踪 API 请求、工具调用和审批决策：
toml
[otel]
environment = "staging"
exporter = "none" # 设为 otlp-http 或 otlp-grpc 发送事件
log_user_prompt = false # 默认不记录用户 prompt 内容HTTP 导出示例：
toml
[otel]
exporter = { otlp-http = {
endpoint = "https://otel.example.com/v1/logs",
protocol = "binary",
headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}主要事件类型：codex.conversation_starts、codex.api_request、codex.sse_event、codex.tool_decision、codex.tool_result 等。
关闭匿名遥测
Codex 默认向 OpenAI 发送少量匿名使用和健康数据。要关闭：
toml
[analytics]
enabled = false推理输出控制
toml
hide_agent_reasoning = true # 隐藏推理输出（适合 CI 日志）
show_raw_agent_reasoning = true # 显示原始推理内容通知
Codex 支持在 Agent 完成 turn 时触发外部程序（适合桌面通知、Webhook、CI 通知）：
toml
notify = ["python3", "/path/to/notify.py"]脚本通过单个 JSON 参数接收通知，常用字段：type、thread-id、cwd、input-messages、last-assistant-message。
与 TUI 内置通知的区别：
notify：执行外部程序（适合 Webhook、桌面通知器）tui.notifications：TUI 内置，可按事件类型过滤
历史记录持久化
Codex 默认在 CODEX_HOME（如 ~/.codex/history.jsonl）保存会话记录：
toml
[history]
persistence = "none" # 关闭本地历史
# 限制历史文件大小（超出时自动清理最旧记录）
# max_bytes = 104857600 # 100 MiB项目 root 检测
Codex 向上查找包含特定 marker 文件的目录作为项目根：
toml
project_root_markers = [".git", ".hg", ".sl"]
# 设为 [] 则把当前目录当作项目根，不向上查找TUI 选项
toml
[tui]
# notifications = true
# notification_method = "auto" # 或 osc9、bel
# animations = true
# alternate_screen = true # 设为 never 保留终端滚动缓冲
# show_tooltips = true常见问题
Q: 我有多套模型/审批策略组合（日常开发、深度 review、CI 无人值守），怎么管理？
A: 用 Profiles——在 config.toml 里分别定义 [profiles.daily]、[profiles.deep-review]、[profiles.ci]，运行时 codex --profile ci 切换。Profile 里只写和顶层不同的值，其他继承全局设置。
Q: 团队里有成员没有 OpenAI 账号，想接入公司内部 LLM 代理，怎么做？
A: 在 config.toml 里配置 [model_providers.proxy]，设置内部代理的 base_url 和认证方式。如果需要动态 token，用 [model_providers.proxy.auth] 配置命令认证。项目级 .codex/config.toml 里配好后团队成员 clone 仓库就能用，不需要每人单独配。
Q: OTel 导出会记录用户的 prompt 内容吗？
A: 默认不记录。log_user_prompt 默认为 false，需要明确设置为 true 才会记录 prompt 文本内容。其他遥测数据（请求数量、耗时、工具调用结果）不含业务内容。