OpenAI Codex高级配置教程：Profiles、沙箱权限、MCP、OTel遥测全解析
文章标签：
OpenAI CodexCodex配置教程config.tomlMCP ServerAI编程助手OllamaAzure OpenAIOpenTelemetryAI Agent开发效率工具
codex客户端下载：https://codexdown.cn/
对于很多开发者来说，安装好 OpenAI Codex 后就已经可以正常使用了。但如果你希望在团队协作、企业开发、本地模型接入、多环境切换、安全控制等场景下发挥 Codex 的全部能力，那么高级配置是必须掌握的内容。
本文将系统讲解 Codex 高级配置文件config.toml的核心能力，包括：
- 配置档案（Profiles）
- 模型与提供方管理
- 项目级配置
- MCP Server 接入
- 生命周期 Hooks
- 沙箱与审批策略
- Shell 环境隔离
- OpenTelemetry 遥测
- 通知系统
- 历史记录管理
让你真正把 Codex 打造成符合自己工作流的 AI 开发助手。
一、Codex配置文件位置
默认情况下，Codex 会把所有配置存放在：
~/.codex目录中。
常见文件：
| 文件 | 作用 |
|---|---|
| config.toml | 主配置文件 |
| auth.json | 认证信息 |
| history.jsonl | 历史会话 |
| logs | 日志目录 |
| cache | 缓存目录 |
目录结构：
~/.codex ├── config.toml ├── auth.json ├── history.jsonl ├── logs └── cache二、Profiles配置档案
如果你有多个开发场景：
- 日常开发
- 代码审查
- AI测试
- 本地模型
可以使用 Profiles。
例如：
# ~/.codex/deep-review.config.toml model = "gpt-5.5" model_reasoning_effort = "xhigh" approval_policy = "on-request"启动：
codex--profiledeep-review执行：
codexexec--profiledeep-review"review this change"这样就不需要频繁修改主配置文件。
三、CLI临时覆盖配置
有时候只想临时修改参数。
例如：
codex--modelgpt-5.4或者：
codex--configmodel='"gpt-5.4"'修改网络权限：
codex--configsandbox_workspace_write.network_access=true修改环境变量白名单：
codex--config'shell_environment_policy.include_only=["PATH","HOME"]'说明：
–config 使用 TOML 语法，不是 JSON。
四、项目级配置
除了全局配置：
~/.codex/config.tomlCodex 还支持项目配置：
project/ └── .codex/ └── config.toml例如：
model = "gpt-5.5" approval_policy = "on-request"这样进入项目后自动生效。
配置优先级
CLI参数 ↓ 项目配置 ↓ Profile配置 ↓ 用户配置 ↓ 默认配置离当前工作目录最近的配置优先级最高。
五、生命周期Hooks
Hooks类似 Git Hook。
可在工具执行前后运行脚本。
例如：
[[hooks.PreToolUse]] matcher = "^Bash$" [[hooks.PreToolUse.hooks]] type = "command" command = ''' python3 pre_tool_use_policy.py '''执行 Bash 前：
Codex ↓ Hook检查 ↓ 允许执行用途：
- 安全审计
- 命令过滤
- 自动日志记录
- CI检查
六、自定义项目根目录
默认情况下：
.git会被视为项目根目录。
可以修改：
project_root_markers = [ ".git", ".hg", ".sl" ]支持：
- Git
- Mercurial
- Sapling
甚至：
project_root_markers = []关闭自动查找。
七、自定义模型提供方
很多用户会接入：
- OpenAI Proxy
- OneAPI
- NewAPI
- FastGPT
- SiliconFlow
- DeepSeek Gateway
配置方式：
model = "gpt-5.5" model_provider = "proxy" [model_providers.proxy] name = "LLM Proxy" base_url = "https://proxy.example.com/v1" env_key = "OPENAI_API_KEY"添加请求头
[model_providers.proxy] http_headers = { "X-Source" = "Codex" }命令式认证
适用于企业SSO。
[model_providers.proxy.auth] command = "/usr/local/bin/get-token" timeout_ms = 5000 refresh_interval_ms = 300000每隔5分钟自动刷新Token。
八、Amazon Bedrock接入
配置：
model_provider = "amazon-bedrock" model = "anthropic.claude" [model_providers.amazon-bedrock.aws] profile = "default" region = "eu-central-1"支持：
- Claude
- Nova
- Llama
- Titan
等 Bedrock 模型。
九、本地大模型模式（OSS）
Codex 可以直接连接：
- Ollama
- LM Studio
配置：
oss_provider = "ollama"启动：
codex--oss即可使用本地模型。
十、Azure OpenAI配置
Azure用户：
[model_providers.azure] name = "Azure" base_url = "https://xxx.openai.azure.com/openai" env_key = "AZURE_OPENAI_API_KEY" query_params = { api-version = "2025-04-01-preview" } wire_api = "responses"十一、模型推理参数
控制推理强度
model_reasoning_effort = "high"可选：
low medium high xhigh控制回答长度
model_verbosity = "low"可选：
low medium high上下文长度
model_context_window = 128000128K上下文。
十二、审批与沙箱
这是企业环境最重要的配置之一。
例如：
approval_policy = "untrusted" sandbox_mode = "workspace-write"含义：
| 配置 | 说明 |
|---|---|
| never | 不审批 |
| on-request | 请求审批 |
| untrusted | 未信任环境审批 |
工作区写权限
[sandbox_workspace_write] writable_roots = [ "/Users/me/project" ] network_access = false禁止联网：
network_access = false允许联网：
network_access = true危险模式
sandbox_mode = "danger-full-access"此模式拥有全部权限。
建议仅在：
- Docker
- 虚拟机
- 隔离环境
中使用。
十三、Shell环境变量隔离
很多公司会在环境变量中存储：
AWS_KEY TOKEN SECRET可以限制传递：
[shell_environment_policy] inherit = "none" include_only = [ "PATH", "HOME" ]进一步屏蔽：
exclude = [ "AWS_*", "AZURE_*" ]提高安全性。
十四、MCP Server支持
Codex 已完整支持 MCP。
可接入：
- Context7
- Browser MCP
- GitHub MCP
- PostgreSQL MCP
- Notion MCP
- Figma MCP
统一配置：
[mcp_servers.xxx]实现：
Codex ↓ MCP ↓ 外部工具让 AI 直接访问业务系统。
十五、OpenTelemetry监控
企业环境非常实用。
开启：
[otel] environment = "production" exporter = "otlp-http"上传到：
Grafana Jaeger Datadog Elastic监控内容
包括：
- API请求
- Token消耗
- Tool调用
- 审批记录
- SSE事件
- WebSocket事件
例如：
codex.api_request codex.tool.call codex.websocket.event codex.turn.token_usage十六、关闭匿名统计
如果你不希望上传匿名指标：
[analytics] enabled = false即可关闭。
十七、通知系统
当任务完成时：
notify = [ "python3", "/path/notify.py" ]Codex会调用：
notification=json.loads(sys.argv[1])可用于：
- 企业微信通知
- 钉钉通知
- 飞书通知
- Webhook通知
十八、历史记录管理
默认：
~/.codex/history.jsonl保存所有会话。
关闭：
[history] persistence = "none"限制大小：
[history] max_bytes = 104857600即：
100MB十九、VSCode可点击文件链接
配置：
file_opener = "vscode"支持：
vscode cursor windsurf vscode-insiders例如：
src/main.py:42自动变成：
vscode://file/src/main.py:42点击即可跳转。
二十、TUI终端界面配置
Codex TUI支持：
[tui]常见配置：
[tui] notifications = true notification_method = "auto" notification_condition = "unfocused" animations = false alternate_screen = "never" show_tooltips = false适合：
- SSH服务器
- Linux终端
- Mac Terminal
- Windows Terminal
推荐配置模板
个人开发者：
model = "gpt-5.5" approval_policy = "on-request" sandbox_mode = "workspace-write" file_opener = "vscode" hide_agent_reasoning = true团队开发：
model = "gpt-5.5" approval_policy = "untrusted" approvals_reviewer = "auto_review" sandbox_mode = "workspace-write" network_access = false analytics.enabled = false企业环境：
approval_policy = "untrusted" sandbox_mode = "workspace-write" network_access = false otel.exporter = "otlp-http" shell_environment_policy.inherit = "none"总结
Codex 的高级配置远不只是切换模型那么简单，它已经具备了企业级 AI Agent 平台所需要的大部分能力：
- Profiles 多环境切换
- 项目级配置管理
- 自定义模型提供方
- MCP Server 集成
- 生命周期 Hooks
- 沙箱权限控制
- OpenTelemetry 监控
- 企业通知系统
- 历史记录管理
对于个人开发者来说，掌握 Profile、沙箱和模型配置即可覆盖大部分场景；而对于团队和企业用户，MCP、OTel、审批策略以及 Hooks 才是真正能提升生产力和安全性的核心功能。
