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目录中。常见文件文件作用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-reviewreview this change这样就不需要频繁修改主配置文件。三、CLI临时覆盖配置有时候只想临时修改参数。例如codex--modelgpt-5.4或者codex--configmodelgpt-5.4修改网络权限codex--configsandbox_workspace_write.network_accesstrue修改环境变量白名单codex--configshell_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配置 ↓ 用户配置 ↓ 默认配置离当前工作目录最近的配置优先级最高。五、生命周期HooksHooks类似 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 ]支持GitMercurialSapling甚至project_root_markers []关闭自动查找。七、自定义模型提供方很多用户会接入OpenAI ProxyOneAPINewAPIFastGPTSiliconFlowDeepSeek 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支持ClaudeNovaLlamaTitan等 Bedrock 模型。九、本地大模型模式OSSCodex 可以直接连接OllamaLM 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。可接入Context7Browser MCPGitHub MCPPostgreSQL MCPNotion MCPFigma 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会调用notificationjson.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 TerminalWindows 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 才是真正能提升生产力和安全性的核心功能。