OpenAI Codex高级配置教程：Profiles、沙箱权限、MCP、OTel遥测全解析

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

目录中。

常见文件：

目录结构：

~/.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.toml

Codex 还支持项目配置：

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 = 128000

128K上下文。

十二、审批与沙箱

这是企业环境最重要的配置之一。

例如：

approval_policy = "untrusted" sandbox_mode = "workspace-write"

含义：

工作区写权限

[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 才是真正能提升生产力和安全性的核心功能。