--- 格式版本: 2 标题: "Advanced Configuration – Codex | OpenAI Developers" 原文链接: "https://developers.openai.com/codex/config-file/config-advanced" 发布日期: "2026-08-16" 发布时间校准状态: "found" 发布时间需复核: "否" 发布时间来源: "rule:local:strict_original_body" 发布时间证据: "Published Time: Sun, 16 Aug 2026 07:20:28 GMT" 发布时间校准原因: "规则确认唯一严格发布时间，来源 local:strict_original_body" 发布时间校准置信度: "high" 发布时间候选数量: 4 发布时间严格候选数量: 1 发布时间原页读取状态: "source template page reused from URL open" 发布时间未找到原因: "" 发布时间校准时间: "2026-08-17T00:05:27+08:00" 发布时间仲裁状态: "skipped" 发布时间仲裁尝试次数: 0 发布时间仲裁耗时毫秒: 0 发现时间: "2026-08-16T23:54:06+08:00" 入库时间: "2026-08-16T16:05:27.249Z" 来源平台: "固定入口" 搜索渠道: "fixed_url" 搜索词: "https://developers.openai.com/blog" 匹配关键词: - "deployment" - "performance" - "latency" - "throughput" - "AI" 相关厂家: - "OpenAI" - "Meta" - "Microsoft" - "AWS" - "Google" - "Oracle" 相关专家: [] 内容类型: "网页" 抓取工具: "Jina Reader" 清洗工具: "Jina Reader Markdown + Defuddle/Readability 正文提取" 原始附件: [] AI优质: "否" AI打分: 0 AI分档: "非优质" AI质检状态: "不通过" AI打分理由: "内容为OpenAI Codex开发者配置文档，与超节点/AI Rack/机柜级AI基础设施完全无关，无任何相关技术或商业信息，判定为无关资料。" AI质检模型: "ali-deepseek-v4-flash" AI质检时间: "2026-08-17T00:05:38+08:00" AI主题相关性: 0 AI来源权威性: 0 AI新颖性: 0 AI技术细节: 0 AI商业部署信号: 0 AI完整性: 0 AI摘要: "OpenAI 官方文档介绍了 Codex 的高级配置方法，面向开发者说明如何设置 worktrees、MCP、非交互模式与沙箱等关键选项，以定制编码代理的行为。" AI摘要模型: "ali-deepseek-v4-flash" AI摘要时间: "2026-09-07T03:27:08.140Z" 采集批次: "2026年8月16日20点37分10秒" 采集批次ID: "20260816-203710-016" 去重键: "https://developers.openai.com/codex/config-file/config-advanced" --- Title: Advanced Configuration – Codex | OpenAI Developers URL Source: https://developers.openai.com/codex/config-file/config-advanced Published Time: Sun, 16 Aug 2026 07:20:28 GMT Markdown Content: For the complete documentation index, see [llms.txt](https://developers.openai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL. [![Image 1: OpenAI Developers](https://developers.openai.com/OpenAI_Developers.svg)ChatGPT](https://developers.openai.com/) [Home](https://developers.openai.com/) [API](https://developers.openai.com/api/docs) [Codex](https://learn.chatgpt.com/docs) [Docs Guides, concepts, and product docs for Codex](https://learn.chatgpt.com/docs)[Use cases Example workflows and tasks teams can take on with ChatGPT or Codex](https://learn.chatgpt.com/use-cases) [Docs](https://developers.openai.com/codex) [Use cases](https://learn.chatgpt.com/use-cases) [Resources](https://developers.openai.com/codex/resources) [ChatGPT](https://developers.openai.com/chatgpt) [Plugins Extend ChatGPT and Codex](https://developers.openai.com/plugins)[Workspace Agents Trigger published ChatGPT workspace agents](https://developers.openai.com/workspace-agents)[Commerce Build commerce flows in ChatGPT](https://developers.openai.com/commerce)[Ads Publish and measure ads in ChatGPT](https://developers.openai.com/ads) [Resources](https://developers.openai.com/learn) [Showcase Demo apps to get inspired](https://developers.openai.com/showcase)[Blog Learnings and experiences from developers](https://developers.openai.com/blog)[Cookbook Notebook examples for building with OpenAI models](https://developers.openai.com/cookbook)[Learn Docs, videos, and demo apps for building with OpenAI](https://developers.openai.com/learn)[Community Programs, meetups, and support for builders](https://developers.openai.com/community) Start searching [API Dashboard](https://platform.openai.com/login) [Try ChatGPT](https://chatgpt.com/) [Overview](https://developers.openai.com/codex)[Features](https://developers.openai.com/codex/features)[Configuration](https://developers.openai.com/codex/configuration)[Developers](https://developers.openai.com/codex/developers)[Security](https://developers.openai.com/codex/security-administration)[Administration](https://developers.openai.com/codex/administration)[Use Cases](https://learn.chatgpt.com/use-cases)[Resources](https://developers.openai.com/codex/resources) ## Search the docs Search docs ### Suggested worktrees mcp noninteractive sandbox Primary navigation API Codex ChatGPT Docs Use cases Resources Resources Search docs ### Suggested worktrees mcp noninteractive sandbox Overview Models Agents Tools Voice & Audio Production API reference Docs section Overview * [Home](https://developers.openai.com/api/docs) ### Get started * [Quickstart](https://developers.openai.com/api/docs/quickstart) * [Using GPT-5.6](https://developers.openai.com/api/docs/guides/latest-model) * [Key concepts](https://developers.openai.com/api/docs/concepts) ### Core concepts * [Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses) * [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state) * [Background mode](https://developers.openai.com/api/docs/guides/background) * [Streaming](https://developers.openai.com/api/docs/guides/streaming-responses) * [WebSocket mode](https://developers.openai.com/api/docs/guides/websocket-mode) * [Multi-agent](https://developers.openai.com/api/docs/guides/responses-multi-agent) * [Webhooks](https://developers.openai.com/api/docs/guides/webhooks) * [File inputs](https://developers.openai.com/api/docs/guides/file-inputs) * [Compaction](https://developers.openai.com/api/docs/guides/compaction) * [Counting tokens](https://developers.openai.com/api/docs/guides/token-counting) ### SDKs and CLI * [OpenAI SDK](https://developers.openai.com/api/docs/libraries) * [OpenAI CLI](https://developers.openai.com/api/docs/libraries/openai-cli) ### Resources * [Changelog](https://developers.openai.com/api/docs/changelog) * [Deprecations](https://developers.openai.com/api/docs/deprecations) * [Supported countries](https://developers.openai.com/api/docs/supported-countries) * [OpenAI Crawlers](https://developers.openai.com/api/docs/bots) * [Terms and policies](https://openai.com/policies) ### Legacy APIs * Agent Builder * [Overview](https://developers.openai.com/api/docs/guides/agent-builder) * [Migration guide](https://developers.openai.com/api/docs/guides/agent-builder/migrate-from-agent-builder) * [Node reference](https://developers.openai.com/api/docs/guides/node-reference) * [Safety in building agents](https://developers.openai.com/api/docs/guides/agent-builder-safety) * Evals * [Getting started](https://developers.openai.com/api/docs/guides/evaluation-getting-started) * [Working with evals](https://developers.openai.com/api/docs/guides/evals) * [Prompt optimizer](https://developers.openai.com/api/docs/guides/prompt-optimizer) * [External models](https://developers.openai.com/api/docs/guides/external-models) * [Best practices](https://developers.openai.com/api/docs/guides/evaluation-best-practices) * [Graders](https://developers.openai.com/api/docs/guides/graders) * Fine-tuning * [Optimization cycle](https://developers.openai.com/api/docs/guides/model-optimization) * [Supervised fine-tuning](https://developers.openai.com/api/docs/guides/supervised-fine-tuning) * [Vision fine-tuning](https://developers.openai.com/api/docs/guides/vision-fine-tuning) * [Direct preference optimization](https://developers.openai.com/api/docs/guides/direct-preference-optimization) * [Reinforcement fine-tuning](https://developers.openai.com/api/docs/guides/reinforcement-fine-tuning) * [RFT use cases](https://developers.openai.com/api/docs/guides/rft-use-cases) * [Best practices](https://developers.openai.com/api/docs/guides/fine-tuning-best-practices) * Assistants API * [Migration guide](https://developers.openai.com/api/docs/assistants/migration) * [Deep dive](https://developers.openai.com/api/docs/assistants/deep-dive) * [Tools](https://developers.openai.com/api/docs/assistants/tools) * [Model catalog](https://developers.openai.com/api/docs/models) ### Choose a model * [Pricing](https://developers.openai.com/api/docs/pricing) * [Model selection](https://developers.openai.com/api/docs/guides/model-selection) ### Text and code * [Text generation](https://developers.openai.com/api/docs/guides/text) * [Code generation](https://developers.openai.com/api/docs/guides/code-generation) * [Structured output](https://developers.openai.com/api/docs/guides/structured-outputs) ### Prompting * [Overview](https://developers.openai.com/api/docs/guides/prompting) * [Prompt engineering](https://developers.openai.com/api/docs/guides/prompt-engineering) * [Citation formatting](https://developers.openai.com/api/docs/guides/citation-formatting) * [Migration guide](https://developers.openai.com/api/docs/guides/prompting/migrate-from-prompt-object) * [Prompt generation](https://developers.openai.com/api/docs/guides/prompt-generation) * [Frontend prompting](https://developers.openai.com/api/docs/guides/frontend-prompt) ### Reasoning * [Reasoning models](https://developers.openai.com/api/docs/guides/reasoning) * [Reasoning best practices](https://developers.openai.com/api/docs/guides/reasoning-best-practices) ### Images and video * [Images and vision](https://developers.openai.com/api/docs/guides/images-vision) * [Image generation](https://developers.openai.com/api/docs/guides/image-generation) * [Video generation](https://developers.openai.com/api/docs/guides/video-generation) ### Realtime and audio * [Audio and speech](https://developers.openai.com/api/docs/guides/audio) * [Overview](https://developers.openai.com/api/docs/guides/realtime) * [Voice agents](https://developers.openai.com/api/docs/guides/voice-agents) ### Specialized models * [Deep research](https://developers.openai.com/api/docs/guides/deep-research) * [Embeddings](https://developers.openai.com/api/docs/guides/embeddings) * [Moderation](https://developers.openai.com/api/docs/guides/moderation) * [Overview](https://developers.openai.com/api/docs/guides/agents) ### Agents SDK * [Quickstart](https://developers.openai.com/api/docs/guides/agents/quickstart) * [Agent definitions](https://developers.openai.com/api/docs/guides/agents/define-agents) * [Models and providers](https://developers.openai.com/api/docs/guides/agents/models) * [Running agents](https://developers.openai.com/api/docs/guides/agents/running-agents) * [Sandbox agents](https://developers.openai.com/api/docs/guides/agents/sandboxes) * [Orchestration](https://developers.openai.com/api/docs/guides/agents/orchestration) * [Guardrails](https://developers.openai.com/api/docs/guides/agents/guardrails-approvals) * [Results and state](https://developers.openai.com/api/docs/guides/agents/results) * [Integrations and observability](https://developers.openai.com/api/docs/guides/agents/integrations-observability) * [Evaluate agent workflows](https://developers.openai.com/api/docs/guides/agent-evals) ### ChatKit * [Overview](https://developers.openai.com/api/docs/guides/chatkit) * [Customize](https://developers.openai.com/api/docs/guides/chatkit-themes) * [Widgets](https://developers.openai.com/api/docs/guides/chatkit-widgets) * [Actions](https://developers.openai.com/api/docs/guides/chatkit-actions) * [Advanced integrations](https://developers.openai.com/api/docs/guides/custom-chatkit) * [Overview](https://developers.openai.com/api/docs/guides/tools) * [Function calling](https://developers.openai.com/api/docs/guides/function-calling) ### Search and retrieval * [Web search](https://developers.openai.com/api/docs/guides/tools-web-search) * [File search](https://developers.openai.com/api/docs/guides/tools-file-search) * [Retrieval](https://developers.openai.com/api/docs/guides/retrieval) ### Connect tools and data * [MCP and Connectors](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) * [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) ### Build tool workflows * [Skills](https://developers.openai.com/api/docs/guides/tools-skills) * [Tool search](https://developers.openai.com/api/docs/guides/tools-tool-search) * [Programmatic tool calling](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling) ### Computer and code * [Shell](https://developers.openai.com/api/docs/guides/tools-shell) * [Computer use](https://developers.openai.com/api/docs/guides/tools-computer-use) * [Apply Patch](https://developers.openai.com/api/docs/guides/tools-apply-patch) * [Local shell](https://developers.openai.com/api/docs/guides/tools-local-shell) * [Code interpreter](https://developers.openai.com/api/docs/guides/tools-code-interpreter) ### Media * [Image generation](https://developers.openai.com/api/docs/guides/tools-image-generation) * [Overview](https://developers.openai.com/api/docs/guides/realtime) ### Get started * [Voice agents](https://developers.openai.com/api/docs/guides/voice-agents) * [Live translation](https://developers.openai.com/api/docs/guides/realtime-translation) * [Realtime prompting guide](https://developers.openai.com/api/docs/guides/realtime-models-prompting) ### Audio * [Audio and speech](https://developers.openai.com/api/docs/guides/audio) * [Transcription](https://developers.openai.com/api/docs/guides/transcription) * [File transcription](https://developers.openai.com/api/docs/guides/speech-to-text) * [Realtime transcription](https://developers.openai.com/api/docs/guides/realtime-transcription) * [Speech generation](https://developers.openai.com/api/docs/guides/text-to-speech) ### Connection methods * [WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc) * [WebSocket](https://developers.openai.com/api/docs/guides/realtime-websocket) * [SIP](https://developers.openai.com/api/docs/guides/realtime-sip) ### Sessions and operations * [Managing conversations](https://developers.openai.com/api/docs/guides/realtime-conversations) * [Voice activity detection](https://developers.openai.com/api/docs/guides/realtime-vad) * [Realtime with tools](https://developers.openai.com/api/docs/guides/realtime-mcp) * [Webhooks and server-side controls](https://developers.openai.com/api/docs/guides/realtime-server-controls) * [Managing costs](https://developers.openai.com/api/docs/guides/realtime-costs) ### Go live * [Production best practices](https://developers.openai.com/api/docs/guides/production-best-practices) * [Deployment checklist](https://developers.openai.com/api/docs/guides/deployment-checklist) ### Performance and quality * [Latency optimization](https://developers.openai.com/api/docs/guides/latency-optimization) * [Predicted Outputs](https://developers.openai.com/api/docs/guides/predicted-outputs) * [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) * [Accuracy optimization](https://developers.openai.com/api/docs/guides/optimizing-llm-accuracy) ### Cost and throughput * [Cost optimization](https://developers.openai.com/api/docs/guides/cost-optimization) * [Prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching) * [Batch](https://developers.openai.com/api/docs/guides/batch) * [Flex processing](https://developers.openai.com/api/docs/guides/flex-processing) ### Safety and governance * [Safety best practices](https://developers.openai.com/api/docs/guides/safety-best-practices) * [Red teaming](https://developers.openai.com/api/docs/guides/red-teaming) * [Safety checks](https://developers.openai.com/api/docs/guides/safety-checks) * [Cybersecurity checks](https://developers.openai.com/api/docs/guides/safety-checks/cybersecurity) * [Under 18 API Guidance](https://developers.openai.com/api/docs/guides/safety-checks/under-18-api-guidance) * [Content provenance](https://developers.openai.com/api/docs/guides/content-provenance) * [Your data](https://developers.openai.com/api/docs/guides/your-data) * [Permissions](https://developers.openai.com/api/docs/guides/rbac) ### Infrastructure and access * [Terraform provider](https://developers.openai.com/api/docs/guides/terraform) * [Overview](https://developers.openai.com/api/docs/guides/terraform) * [Projects and access](https://developers.openai.com/api/docs/guides/terraform/projects-and-access) * [Service accounts](https://developers.openai.com/api/docs/guides/terraform/service-accounts) * [Rate limits and spend](https://developers.openai.com/api/docs/guides/terraform/rate-limits-and-spend) * [Model, tool, and data controls](https://developers.openai.com/api/docs/guides/terraform/project-controls) * [Import and reconciliation](https://developers.openai.com/api/docs/guides/terraform/import-and-reconcile) * [Private Link](https://developers.openai.com/api/docs/guides/private-link) * [IP allowlist](https://developers.openai.com/api/docs/guides/ip-allowlist) * [Workload identity federation](https://developers.openai.com/api/docs/guides/workload-identity-federation) * [X.509 certificates (beta)](https://developers.openai.com/api/docs/guides/workload-identity-federation/x509) * [Kubernetes](https://developers.openai.com/api/docs/guides/workload-identity-federation/kubernetes) * [AWS](https://developers.openai.com/api/docs/guides/workload-identity-federation/aws) * [Microsoft Azure](https://developers.openai.com/api/docs/guides/workload-identity-federation/microsoft-azure) * [Google Cloud](https://developers.openai.com/api/docs/guides/workload-identity-federation/google-cloud) * [Oracle Cloud Infrastructure](https://developers.openai.com/api/docs/guides/workload-identity-federation/oracle-cloud) * [GitHub Actions](https://developers.openai.com/api/docs/guides/workload-identity-federation/github-actions) * [SPIFFE](https://developers.openai.com/api/docs/guides/workload-identity-federation/spiffe) * [IP egress ranges](https://developers.openai.com/api/docs/guides/ip-addresses) * [Amazon Bedrock](https://developers.openai.com/api/docs/guides/amazon-bedrock) ### Operations * [Rate limits](https://developers.openai.com/api/docs/guides/rate-limits) * [Spend limits](https://developers.openai.com/api/docs/guides/spend-limits) * [Admin APIs](https://developers.openai.com/api/docs/guides/admin-apis) * [Error codes](https://developers.openai.com/api/docs/guides/error-codes) [Docs](https://learn.chatgpt.com/docs)[Use cases](https://learn.chatgpt.com/use-cases) Docs section Docs Plugins Workspace Agents Commerce Ads Docs section Select... * [Home](https://developers.openai.com/plugins) * [Quickstart](https://developers.openai.com/plugins/quickstart) ### Core concepts * [Plugin architecture](https://developers.openai.com/plugins/concepts/plugins) * [Skills](https://developers.openai.com/plugins/concepts/skills) * [MCP server](https://developers.openai.com/plugins/concepts/mcp-server) ### Plan * [Brainstorm use cases](https://developers.openai.com/plugins/plan/use-case) * [Define tools](https://developers.openai.com/plugins/plan/tools) ### Build * [Build an MCP server](https://developers.openai.com/plugins/build/mcp-server) * [Add UI to your MCP server (optional)](https://developers.openai.com/plugins/build/chatgpt-ui) * [Authenticate users](https://developers.openai.com/plugins/build/auth) * [Build skills](https://developers.openai.com/plugins/build/skills) * [Package your plugin](https://developers.openai.com/plugins/build/plugins) * [Examples](https://developers.openai.com/plugins/build/examples) ### Test and publish * [Connect and test your plugin](https://developers.openai.com/plugins/deploy/connect-chatgpt) * [Submit and publish](https://developers.openai.com/plugins/deploy/submission) * [Submission error reference](https://developers.openai.com/plugins/deploy/submission-errors) ### Conversion specs * [Restaurant reservation spec](https://developers.openai.com/plugins/guides/restaurant-reservation-conversion-spec) * [Get Quote spec](https://developers.openai.com/plugins/guides/local-services-request-quote-conversion-spec) * [Product checkout spec](https://developers.openai.com/plugins/guides/product-checkout-conversion-spec) ### Guides * [UI guidelines](https://developers.openai.com/plugins/concepts/ui-guidelines) * [Optimize Metadata](https://developers.openai.com/plugins/guides/optimize-metadata) * [Submit a Claude Code plugin](https://developers.openai.com/plugins/guides/submit-claude-plugin) * [Security & Privacy](https://developers.openai.com/plugins/guides/security-privacy) * [Troubleshooting](https://developers.openai.com/plugins/deploy/troubleshooting) ### Resources * [Changelog](https://developers.openai.com/plugins/changelog) * [Plugin guidelines](https://developers.openai.com/plugins/app-guidelines) * [MCP server review requirements](https://developers.openai.com/plugins/deploy/app-review) * [Plugin UI reference](https://developers.openai.com/plugins/reference) * [Checkout API reference](https://developers.openai.com/plugins/build/monetization) * [Home](https://developers.openai.com/workspace-agents) ### Get started * [Trigger workspace agent runs](https://developers.openai.com/workspace-agents/trigger-runs) * [Authenticate with Workspace Agent access tokens](https://developers.openai.com/workspace-agents/authentication) * [Home](https://developers.openai.com/commerce) ### Guides * [Get started](https://developers.openai.com/commerce/guides/get-started) * [Best practices](https://developers.openai.com/commerce/guides/best-practices) ### File Upload * [Overview](https://developers.openai.com/commerce/specs/file-upload/overview) * [Products](https://developers.openai.com/commerce/specs/file-upload/products) ### API * [Overview](https://developers.openai.com/commerce/specs/api/overview) * [Feeds](https://developers.openai.com/commerce/specs/api/feeds) * [Products](https://developers.openai.com/commerce/specs/api/products) * [Promotions](https://developers.openai.com/commerce/specs/api/promotions) * [Ads Overview](https://developers.openai.com/ads) ### Measurement * [Measurement Pixel](https://developers.openai.com/ads/measurement-pixel) * [Multiple Pixels (Advanced)](https://developers.openai.com/ads/multiple-pixels) * [Image Tag](https://developers.openai.com/ads/image-tag) * [Conversions API](https://developers.openai.com/ads/conversions-api) * [Supported Events](https://developers.openai.com/ads/supported-events) ### Advertiser API * [Overview](https://developers.openai.com/ads/api-overview) * [API Partner Setup](https://developers.openai.com/ads/api-partner-setup) * [Quickstart](https://developers.openai.com/ads/api-quickstart) * [Bulk API](https://developers.openai.com/ads/bulk-api) * [Product Feeds](https://developers.openai.com/ads/product-feeds) * [Delta Feeds API](https://developers.openai.com/ads/delta-feeds) * [Campaign Targeting](https://developers.openai.com/ads/campaign-targeting) * [Conversion-Optimized Campaigns](https://developers.openai.com/ads/conversion-optimized-campaigns) ### API Reference * [Authentication](https://developers.openai.com/ads/api-reference/authentication) * [Ad Account](https://developers.openai.com/ads/api-reference/ad-account) * [Campaigns](https://developers.openai.com/ads/api-reference/campaigns) * [Ad Groups](https://developers.openai.com/ads/api-reference/ad-groups) * [Ads](https://developers.openai.com/ads/api-reference/ads) * [Insights](https://developers.openai.com/ads/api-reference/insights) * [Files](https://developers.openai.com/ads/api-reference/files) * [Conversion Setup](https://developers.openai.com/ads/api-reference/conversion-setup) Overview Features Configuration Developers Security Administration Use Cases Resources Docs section Configuration * [Home](https://developers.openai.com/codex) ### Get started * [Quickstart](https://developers.openai.com/codex/quickstart) * [Use ChatGPT](https://developers.openai.com/codex/use-chatgpt) * [Get started with Work](https://developers.openai.com/codex/get-started-with-work) * [Import from another agent](https://developers.openai.com/codex/import) ### Foundations * [Prompting](https://developers.openai.com/codex/prompting) * [Personalize ChatGPT](https://developers.openai.com/codex/personalize) * [Skills & Plugins](https://developers.openai.com/codex/skills-and-plugins) * [Permissions](https://developers.openai.com/codex/permission-modes) ### Explore * [What's new](https://developers.openai.com/codex/whats-new) * [Models](https://developers.openai.com/codex/models) * [Pricing](https://developers.openai.com/codex/pricing) * [Glossary](https://developers.openai.com/codex/glossary) ### Available on * [ChatGPT desktop app](https://developers.openai.com/codex/app) * [Remote](https://developers.openai.com/codex/remote) * [ChatGPT on the web](https://developers.openai.com/codex/web) * [Codex CLI](https://developers.openai.com/codex/cli) * [Codex IDE extension](https://developers.openai.com/codex/ide) * [Codex cloud](https://developers.openai.com/codex/cloud) ### Releases * [Changelog](https://developers.openai.com/codex/changelog) * [Feature Maturity](https://developers.openai.com/codex/feature-maturity) * [Open Source](https://developers.openai.com/codex/open-source) * [Overview](https://developers.openai.com/codex/features) ### Workflows * [Projects and chats](https://developers.openai.com/codex/projects) * [Sites](https://developers.openai.com/codex/sites) * [Visualizations](https://developers.openai.com/codex/visualizations) * [Scheduled tasks](https://developers.openai.com/codex/automations) * [Long-running work](https://developers.openai.com/codex/long-running-work) * [Notifications](https://developers.openai.com/codex/notifications) * [Pets](https://developers.openai.com/codex/pets) * [Codex Micro](https://developers.openai.com/codex/features/codex-micro) ### Capabilities * [Browser](https://developers.openai.com/codex/browser) * [Computer use](https://developers.openai.com/codex/computer-use) * [Voice](https://developers.openai.com/codex/features/voice) * [Plugins](https://developers.openai.com/codex/plugins) * [Web search](https://developers.openai.com/codex/web-search) * [Image generation](https://developers.openai.com/codex/image-generation) * [Image inputs](https://developers.openai.com/codex/image-inputs) * [Appshots](https://developers.openai.com/codex/appshots) * [Chrome extension](https://developers.openai.com/codex/chrome-extension) * [Work with files](https://developers.openai.com/codex/artifacts-viewer) ### Reference * [Commands](https://developers.openai.com/codex/reference/commands) * [Slash commands](https://developers.openai.com/codex/reference/slash-commands) * [Settings](https://developers.openai.com/codex/reference/settings) * [Troubleshooting](https://developers.openai.com/codex/reference/troubleshooting) * [Overview](https://developers.openai.com/codex/configuration) ### Customization * [Overview](https://developers.openai.com/codex/customization/overview) * [Memories](https://developers.openai.com/codex/customization/memories) * [Computer History](https://developers.openai.com/codex/customization/computer-history) ### Config file * [Config Basics](https://developers.openai.com/codex/config-file/config-basic) * [Advanced Config](https://developers.openai.com/codex/config-file/config-advanced) * [Config Reference](https://developers.openai.com/codex/config-file/config-reference) * [Environment Variables](https://developers.openai.com/codex/config-file/environment-variables) * [Sample Config](https://developers.openai.com/codex/config-file/config-sample) ### Agent configuration * [AGENTS.md](https://developers.openai.com/codex/agent-configuration/agents-md) * [Subagents](https://developers.openai.com/codex/agent-configuration/subagents) * [Speed](https://developers.openai.com/codex/agent-configuration/speed) * [Rules](https://developers.openai.com/codex/agent-configuration/rules) ### Extend ChatGPT and Codex * [Record & Replay](https://developers.openai.com/codex/extend/record-and-replay) * [MCP](https://developers.openai.com/codex/extend/mcp) ### Linux * [Desktop app](https://developers.openai.com/codex/linux/linux-app) ### Windows * [Desktop app](https://developers.openai.com/codex/windows/windows-app) * [Windows sandbox](https://developers.openai.com/codex/windows/windows-sandbox) * [WSL](https://developers.openai.com/codex/windows/wsl) * [Overview](https://developers.openai.com/codex/developers) ### Development workflows * [Code review](https://developers.openai.com/codex/code-review) * [Integrated terminal](https://developers.openai.com/codex/integrated-terminal) ### Extend and automate * [Build skills](https://developers.openai.com/codex/build-skills) * [Build plugins](https://developers.openai.com/codex/build-plugins) * [Hooks](https://developers.openai.com/codex/hooks) ### Environments * [Modes](https://developers.openai.com/codex/environments/modes) * [Local environments](https://developers.openai.com/codex/environments/local-environment) * [Cloud environment](https://developers.openai.com/codex/environments/cloud-environment) * [Git worktrees](https://developers.openai.com/codex/environments/git-worktrees) ### Build with Codex * [Codex SDK](https://developers.openai.com/codex/codex-sdk) * [App Server](https://developers.openai.com/codex/app-server) * [MCP Server](https://developers.openai.com/codex/mcp-server) * [GitHub Action](https://developers.openai.com/codex/github-action) * [Non-interactive mode](https://developers.openai.com/codex/non-interactive-mode) ### Third-party integrations * [GitHub](https://developers.openai.com/codex/third-party/github) * [Slack](https://developers.openai.com/codex/third-party/slack) * [Linear](https://developers.openai.com/codex/third-party/linear) ### Reference * [CLI customization](https://developers.openai.com/codex/cli-customization) * [Developer commands](https://developers.openai.com/codex/developer-commands) * [Developer settings](https://developers.openai.com/codex/developer-settings) * [Overview](https://developers.openai.com/codex/security-administration) ### Permissions * [Profiles](https://developers.openai.com/codex/permissions) * [Sandboxing](https://developers.openai.com/codex/sandboxing) * [Auto-review](https://developers.openai.com/codex/sandboxing/auto-review) * [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security) * [Internet access](https://developers.openai.com/codex/cloud/internet-access) ### Codex Security * [Overview](https://developers.openai.com/codex/security) * Codex Security plugin * [Quickstart](https://developers.openai.com/codex/security/plugin) * [Run a security scan](https://developers.openai.com/codex/security/plugin/scans) * [Run a deep scan](https://developers.openai.com/codex/security/plugin/deep-scans) * [Review code changes](https://developers.openai.com/codex/security/plugin/code-changes) * [Use the Security workbench](https://developers.openai.com/codex/security/plugin/workbench) * [Triage a backlog](https://developers.openai.com/codex/security/plugin/triage-backlog) * [Fix findings](https://developers.openai.com/codex/security/plugin/fix-findings) * [Propose security hardening](https://developers.openai.com/codex/security/plugin/security-hardening) * [Write vulnerability reports](https://developers.openai.com/codex/security/plugin/vulnerability-reports) * [Export and track findings](https://developers.openai.com/codex/security/plugin/export-findings) * [Changelog](https://developers.openai.com/codex/security/plugin/changelog) * Codex Security CLI * [Quickstart](https://developers.openai.com/codex/security/cli) * [Run bulk scans](https://developers.openai.com/codex/security/cli/bulk-scans) * [Run scans in CI](https://developers.openai.com/codex/security/cli/ci) * [Reference](https://developers.openai.com/codex/security/cli/reference) * [FAQ](https://developers.openai.com/codex/security/cli/faq) * [TypeScript SDK](https://developers.openai.com/codex/security/sdk) * Codex Security cloud * [Setup](https://developers.openai.com/codex/security/setup) * [Security Review](https://developers.openai.com/codex/security/security-review) * [Improving the threat model](https://developers.openai.com/codex/security/threat-model) * [FAQ](https://developers.openai.com/codex/security/faq) ### Cyber safety * [Models & Trusted Access](https://developers.openai.com/codex/cyber-safety) * [Recommended configuration](https://developers.openai.com/codex/cyber-safety/recommended-configuration) * [Overview](https://developers.openai.com/codex/administration) ### Getting started * [Admin rollout guide](https://developers.openai.com/codex/enterprise/admin-setup) * [ChatGPT Work Overview](https://developers.openai.com/codex/enterprise/chatgpt-work-overview) * [ChatGPT Work admin FAQ](https://developers.openai.com/codex/enterprise/work-admin-faq) ### Identity and authentication * [Authentication overview](https://developers.openai.com/codex/auth) * [Personal Access Tokens](https://developers.openai.com/codex/enterprise/access-tokens) * [Service accounts](https://developers.openai.com/codex/enterprise/service-accounts) ### Workspace access, policy, and models * [Groups and provisioning](https://developers.openai.com/codex/enterprise/groups-and-provisioning) * [Roles and workspace permissions](https://developers.openai.com/codex/enterprise/roles-and-workspace-permissions) * [GPTs and Sharing](https://developers.openai.com/codex/enterprise/gpts-and-sharing) * [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) * [Prisma AIRS](https://developers.openai.com/codex/enterprise/prisma-airs) * [HIPAA configuration](https://developers.openai.com/codex/hipaa-configuration) * [Workspace model availability](https://developers.openai.com/codex/enterprise/workspace-model-availability) ### Plugin and connector controls * [Plugin controls](https://developers.openai.com/codex/enterprise/apps-and-connectors) * [Skill controls](https://developers.openai.com/codex/enterprise/skills) ### Usage, governance, and compliance * [Governance](https://developers.openai.com/codex/enterprise/governance) * [Workspace analytics](https://developers.openai.com/codex/enterprise/workspace-analytics) * [Analytics API](https://developers.openai.com/codex/enterprise/analytics-api) * [Compliance API and audit events](https://developers.openai.com/codex/enterprise/compliance-api) ### Deployment and model providers * [Manage app updates](https://developers.openai.com/codex/enterprise/manage-app-updates) * [Windows app deployment](https://developers.openai.com/codex/enterprise/windows-deployment) * [Remote connections](https://developers.openai.com/codex/remote-connections) * [Amazon Bedrock](https://developers.openai.com/codex/amazon-bedrock) * [Explore use cases](https://learn.chatgpt.com/use-cases) * [Collections](https://learn.chatgpt.com/use-cases/collections) * [Home](https://developers.openai.com/codex/resources) * [Videos](https://developers.openai.com/codex/videos) * [Showcase](https://developers.openai.com/showcase) * [OpenAI Academy](https://openai.com/academy/) * [Online trainings](https://academy.openai.com/home/events) ### Community * [Codex Ambassadors](https://developers.openai.com/community/codex-ambassadors) * [Codex for Students](https://developers.openai.com/community/students) * [Codex for Open Source](https://developers.openai.com/community/codex-for-oss) * [Meetups](https://developers.openai.com/community/meetups) ### Blog * [Company blog](https://openai.com/news/) * [Developer blog](https://developers.openai.com/blog) * [Explore use cases](https://learn.chatgpt.com/use-cases) * [Collections](https://learn.chatgpt.com/use-cases/collections) * [Home](https://developers.openai.com/codex/resources) * [Videos](https://developers.openai.com/codex/videos) * [Showcase](https://developers.openai.com/showcase) * [OpenAI Academy](https://openai.com/academy/) * [Online trainings](https://academy.openai.com/home/events) ### Community * [Codex Ambassadors](https://developers.openai.com/community/codex-ambassadors) * [Codex for Students](https://developers.openai.com/community/students) * [Codex for Open Source](https://developers.openai.com/community/codex-for-oss) * [Meetups](https://developers.openai.com/community/meetups) ### Blog * [Company blog](https://openai.com/news/) * [Developer blog](https://developers.openai.com/blog) [Showcase](https://developers.openai.com/showcase) Blog Cookbook Learn Community Docs section Select... * [All posts](https://developers.openai.com/blog) ### Recent * [Custom Code Review rules for Codex](https://developers.openai.com/blog/custom-code-review-rules-for-codex) * [Mastering remote engineering work from your phone](https://developers.openai.com/blog/mastering-codex-remote-for-engineering) * [Making private MCP servers reachable without making them public](https://developers.openai.com/blog/connect-private-mcp-servers-to-openai-products) * [How Perplexity Brought Voice Search to Millions Using the Realtime API](https://developers.openai.com/blog/realtime-perplexity-computer) * [Designing delightful frontends with GPT-5.4](https://developers.openai.com/blog/designing-delightful-frontends-with-gpt-5-4) ### Topics * [General](https://developers.openai.com/blog/topic/general) * [API](https://developers.openai.com/blog/topic/api) * [Apps SDK](https://developers.openai.com/blog/topic/apps-sdk) * [Audio](https://developers.openai.com/blog/topic/audio) * [Codex](https://developers.openai.com/blog/topic/codex) * [Home](https://developers.openai.com/cookbook) ### Topics * [Agents](https://developers.openai.com/cookbook/topic/agents) * [Evals](https://developers.openai.com/cookbook/topic/evals) * [Multimodal](https://developers.openai.com/cookbook/topic/multimodal) * [Text](https://developers.openai.com/cookbook/topic/text) * [Guardrails](https://developers.openai.com/cookbook/topic/guardrails) * [Optimization](https://developers.openai.com/cookbook/topic/optimization) * [ChatGPT](https://developers.openai.com/cookbook/topic/chatgpt) * [Codex](https://developers.openai.com/cookbook/topic/codex) * [gpt-oss](https://developers.openai.com/cookbook/topic/gpt-oss) ### Contribute * [Cookbook on GitHub](https://github.com/openai/openai-cookbook) * [Home](https://developers.openai.com/learn) * [OpenAI Developers plugin](https://developers.openai.com/learn/developers-codex-plugin) * [Docs MCP](https://developers.openai.com/learn/docs-mcp) ### Categories * [Demo apps](https://developers.openai.com/learn/code) * [Videos](https://developers.openai.com/learn/videos) ### Topics * [Agents](https://developers.openai.com/learn/agents) * [Audio & Voice](https://developers.openai.com/learn/audio) * [Computer Use](https://developers.openai.com/learn/cua) * [Codex](https://developers.openai.com/learn/codex) * [Evals](https://developers.openai.com/learn/evals) * [gpt-oss](https://developers.openai.com/learn/gpt-oss) * [Fine-tuning](https://developers.openai.com/learn/fine-tuning) * [Image generation](https://developers.openai.com/learn/imagegen) * [Scaling](https://developers.openai.com/learn/scaling) * [Tools](https://developers.openai.com/learn/tools) * [Video generation](https://developers.openai.com/learn/videogen) * [Community](https://developers.openai.com/community) ### Programs * [Codex Ambassadors](https://developers.openai.com/community/codex-ambassadors) * [Codex for Students](https://developers.openai.com/community/students) * [Codex for Open Source](https://developers.openai.com/community/codex-for-oss) * [OpenAI for Startups](https://openai.com/business/why-openai/startups/) ### Events * [Meetups](https://developers.openai.com/community/meetups) ### Spaces * [Developer Forum](https://community.openai.com/) * [Discord](https://discord.com/invite/openai) * [Reddit](https://www.reddit.com/r/OpenAI/) * [X](https://x.com/OpenAIDevs) [API Dashboard](https://platform.openai.com/login) [Try ChatGPT](https://chatgpt.com/) * [Overview](https://developers.openai.com/codex/configuration) ### Customization * [Overview](https://developers.openai.com/codex/customization/overview) * [Memories](https://developers.openai.com/codex/customization/memories) * [Computer History](https://developers.openai.com/codex/customization/computer-history) ### Config file * [Config Basics](https://developers.openai.com/codex/config-file/config-basic) * [Advanced Config](https://developers.openai.com/codex/config-file/config-advanced) * [Config Reference](https://developers.openai.com/codex/config-file/config-reference) * [Environment Variables](https://developers.openai.com/codex/config-file/environment-variables) * [Sample Config](https://developers.openai.com/codex/config-file/config-sample) ### Agent configuration * [AGENTS.md](https://developers.openai.com/codex/agent-configuration/agents-md) * [Subagents](https://developers.openai.com/codex/agent-configuration/subagents) * [Speed](https://developers.openai.com/codex/agent-configuration/speed) * [Rules](https://developers.openai.com/codex/agent-configuration/rules) ### Extend ChatGPT and Codex * [Record & Replay](https://developers.openai.com/codex/extend/record-and-replay) * [MCP](https://developers.openai.com/codex/extend/mcp) ### Linux * [Desktop app](https://developers.openai.com/codex/linux/linux-app) ### Windows * [Desktop app](https://developers.openai.com/codex/windows/windows-app) * [Windows sandbox](https://developers.openai.com/codex/windows/windows-sandbox) * [WSL](https://developers.openai.com/codex/windows/wsl) * [Profiles](https://developers.openai.com/codex/config-file/config-advanced#profiles) * [One-off overrides from the CLI](https://developers.openai.com/codex/config-file/config-advanced#one-off-overrides-from-the-cli) * [Config and state locations](https://developers.openai.com/codex/config-file/config-advanced#config-and-state-locations) * [Project config files (.codex/config.toml)](https://developers.openai.com/codex/config-file/config-advanced#project-config-files-codexconfigtoml) * [Hooks](https://developers.openai.com/codex/config-file/config-advanced#hooks) * [Agent roles ([agents] in config.toml)](https://developers.openai.com/codex/config-file/config-advanced#agent-roles-agents-in-configtoml) * [Project root detection](https://developers.openai.com/codex/config-file/config-advanced#project-root-detection) * [Custom model providers](https://developers.openai.com/codex/config-file/config-advanced#custom-model-providers) * [OSS mode (local providers)](https://developers.openai.com/codex/config-file/config-advanced#oss-mode-local-providers) * [Azure provider and per-provider tuning](https://developers.openai.com/codex/config-file/config-advanced#azure-provider-and-per-provider-tuning) * [ChatGPT customers using data residency](https://developers.openai.com/codex/config-file/config-advanced#chatgpt-customers-using-data-residency) * [Model reasoning, verbosity, and limits](https://developers.openai.com/codex/config-file/config-advanced#model-reasoning-verbosity-and-limits) * [Approval policies and sandbox modes](https://developers.openai.com/codex/config-file/config-advanced#approval-policies-and-sandbox-modes) * [Shell environment policy](https://developers.openai.com/codex/config-file/config-advanced#shell-environment-policy) * [MCP servers](https://developers.openai.com/codex/config-file/config-advanced#mcp-servers) * [Observability and telemetry](https://developers.openai.com/codex/config-file/config-advanced#observability-and-telemetry) * [Notifications](https://developers.openai.com/codex/config-file/config-advanced#notifications) * [History persistence](https://developers.openai.com/codex/config-file/config-advanced#history-persistence) * [Clickable citations](https://developers.openai.com/codex/config-file/config-advanced#clickable-citations) * [Project instructions discovery](https://developers.openai.com/codex/config-file/config-advanced#project-instructions-discovery) * [Desktop](https://developers.openai.com/codex/config-file/config-advanced#desktop) * [TUI options](https://developers.openai.com/codex/config-file/config-advanced#tui-options) Copy Page # Advanced Configuration More advanced configuration options for Codex local clients Copy Page Use these options when you need more control over providers, policies, and integrations. For a quick start, see [Config basics](https://developers.openai.com/codex/config-file/config-basic). For background on project guidance, reusable capabilities, custom slash commands, subagent workflows, and integrations, see [Customization](https://developers.openai.com/codex/customization/overview). For configuration keys, see [Configuration Reference](https://developers.openai.com/codex/config-file/config-reference). ## Profiles Profiles let you save named configuration layers and switch between them from the CLI. When you pass `--profile profile-name`, Codex loads `~/.codex/config.toml`, then overlays `~/.codex/profile-name.config.toml`. Profile names can contain letters, numbers, hyphens, and underscores. Create a separate TOML file for each profile. Use top-level config keys in the profile file; don’t nest them under `[profiles.profile-name]`. ``` # ~/.codex/deep-review.config.toml model = "gpt-5.5" model_reasoning_effort = "xhigh" approval_policy = "on-request" model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json" ``` ``` codex --profile deep-review codex exec --profile deep-review "review this change" ``` Because the profile file is a layer above your base user config and below project and CLI config, it only needs the values that differ from your base config. Profile files can also override `model_catalog_json`; Codex uses the profile value when both files set it. In Codex 0.134.0 and later, `--profile` no longer reads `[profiles.profile-name]` from `config.toml`, and the top-level `profile = "profile-name"` selector is no longer supported. Move legacy profile settings into `~/.codex/profile-name.config.toml`, then remove the matching `[profiles.profile-name]` table and `profile = "profile-name"` selector from `config.toml`. ## One-off overrides from the CLI In addition to editing `~/.codex/config.toml`, you can override configuration for a single run from the CLI: * Prefer dedicated flags when they exist (for example, `--model`). * Use `-c` / `--config` when you need to override an arbitrary key. Examples: ``` # Dedicated flag codex --model gpt-5.6-terra # Generic key/value override (value is TOML, not JSON) codex --config model='"gpt-5.6-terra"' codex --config sandbox_workspace_write.network_access=true codex --config 'shell_environment_policy.include_only=["PATH","HOME"]' ``` Notes: * Keys can use dot notation to set nested values (for example, `mcp_servers.context7.enabled=false`). * `--config` values are parsed as TOML. When in doubt, quote the value so your shell doesn’t split it on spaces. * If the value can’t be parsed as TOML, Codex treats it as a string. ## Config and state locations Codex stores its local state under `CODEX_HOME` (defaults to `~/.codex`). Common files you may see there: * `config.toml` (your local configuration) * `auth.json` (if you use file-based credential storage) or your OS keychain/keyring * `history.jsonl` (if history persistence is enabled) * Other per-user state such as logs and caches For authentication details (including credential storage modes), see [Authentication](https://developers.openai.com/codex/auth). For the full list of configuration keys, see [Configuration Reference](https://developers.openai.com/codex/config-file/config-reference). For shared defaults, rules, and skills checked into repos or system paths, see [Team Config](https://developers.openai.com/codex/enterprise/admin-setup#step-4-standardize-local-configuration-with-team-config). If you just need to point the built-in OpenAI provider at an LLM proxy, router, or data-residency enabled project, set `openai_base_url` in `config.toml` instead of defining a new provider. This changes the base URL for the built-in `openai` provider without requiring a separate `model_providers.` entry. `openai_base_url = "https://us.api.openai.com/v1"` ## Project config files (`.codex/config.toml`) In addition to your user config, Codex reads project-scoped overrides from `.codex/config.toml` files inside your repo. Codex walks from the project root to your current working directory and loads every `.codex/config.toml` it finds. If multiple files define the same key, the closest file to your working directory wins. For security, Codex loads project-scoped config files only when the project is trusted. If the project is untrusted, Codex ignores project `.codex/` layers, including `.codex/config.toml`, project-local hooks, and project-local rules. User and system layers remain separate and still load. Relative paths inside a project config (for example, `model_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`. Project config files can’t override settings that redirect credentials, alter host-owned app request metadata, change provider auth, select config profiles, or run machine-local notification/telemetry commands. Codex ignores the following keys in project-local `.codex/config.toml` and prints a startup warning when it sees them: `openai_base_url`, `chatgpt_base_url`, `apps_mcp_product_sku`, `model_provider`, `model_providers`, `notify`, `profile`, `profiles`, `experimental_realtime_ws_base_url`, and `otel`. Set provider, notification, and telemetry keys in your user-level `~/.codex/config.toml`; select config profiles with `--profile profile-name` and `~/.codex/profile-name.config.toml`. ## Hooks Codex can also load lifecycle hooks from either `hooks.json` files or inline `[hooks]` tables in `config.toml` files that sit next to active config layers. In practice, the four most useful locations are: * `~/.codex/hooks.json` * `~/.codex/config.toml` * `/.codex/hooks.json` * `/.codex/config.toml` Project-local hooks load only when the project `.codex/` layer is trusted. User-level hooks remain independent of project trust. Inline TOML hooks use the same event structure as `hooks.json`: ``` [[hooks.PreToolUse]] matcher = "^Bash$" [[hooks.PreToolUse.hooks]] type = "command" command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"' timeout = 30 statusMessage = "Checking Bash command" ``` If a single layer contains both `hooks.json` and inline `[hooks]`, Codex loads both and warns. Prefer one representation per layer. For the current event list, input fields, output behavior, and limitations, see [Hooks](https://developers.openai.com/codex/hooks). ## Agent roles (`[agents]` in `config.toml`) For subagent role configuration (`[agents]` in `config.toml`), see [Subagents](https://developers.openai.com/codex/agent-configuration/subagents). ## Project root detection Codex discovers project configuration (for example, `.codex/` layers and `AGENTS.md`) by walking up from the working directory until it reaches a project root. By default, Codex treats a directory containing `.git` as the project root. To customize this behavior, set `project_root_markers` in `config.toml`: ``` # Treat a directory as the project root when it contains any of these markers. project_root_markers = [".git", ".hg", ".sl"] ``` Set `project_root_markers = []` to skip searching parent directories and treat the current working directory as the project root. ## Custom model providers A model provider defines how Codex connects to a model (base URL, wire API, authentication, and optional HTTP headers). Custom providers can’t reuse the reserved built-in provider IDs: `openai`, `ollama`, and `lmstudio`. Define additional providers and point `model_provider` at them: ``` model = "gpt-5.6-terra" 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" ``` If a custom provider supports the standalone web search endpoint, advertise that capability in its provider configuration: ``` [model_providers.proxy] name = "OpenAI using LLM proxy" base_url = "https://proxy.example.com/v1" env_key = "OPENAI_API_KEY" supports_standalone_web_search = true ``` The setting defaults to `false` for custom providers. Standalone web search is under development and off by default. Setting the provider capability to `true` doesn’t enable it: the provider must support a compatible endpoint, and the selected model and runtime must support standalone search. The configured [`web_search` mode](https://developers.openai.com/codex/web-search) and managed search restrictions still apply. Add request headers when needed: ``` [model_providers.example] http_headers = { "X-Example-Header" = "example-value" } env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" } ``` Use command-backed authentication when a provider needs Codex to fetch bearer tokens from an external credential helper: ``` [model_providers.proxy] name = "OpenAI using LLM proxy" base_url = "https://proxy.example.com/v1" wire_api = "responses" [model_providers.proxy.auth] command = "/usr/local/bin/fetch-codex-token" args = ["--audience", "codex"] timeout_ms = 5000 refresh_interval_ms = 300000 ``` The auth command receives no `stdin` and must print the token to stdout. Codex trims surrounding whitespace, treats an empty token as an error, and refreshes proactively at `refresh_interval_ms`; set `refresh_interval_ms = 0` to refresh only after an authentication retry. Don’t combine `[model_providers..auth]` with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`. ### Amazon Bedrock provider Codex includes a built-in `amazon-bedrock` model provider. Set it directly as `model_provider`; unlike custom providers, this built-in provider supports only the nested AWS profile and region overrides. ``` model_provider = "amazon-bedrock" model = "" [model_providers.amazon-bedrock.aws] profile = "default" region = "eu-central-1" ``` If you omit `profile`, Codex uses the standard AWS credential chain. Set `region` to the supported Bedrock region that should handle requests. For the full setup flow, authentication options, supported models, and feature availability, see [Use ChatGPT Work and Codex with Amazon Bedrock](https://developers.openai.com/codex/amazon-bedrock). ## OSS mode (local providers) Codex can run against a local “open source” provider such as Ollama or LM Studio when you pass `--oss`. Choose one for a single run with `--local-provider`, or set `oss_provider` as the default. If neither is set, the interactive CLI prompts you to choose; `codex exec` exits with an error. ``` # Default local provider used with `--oss` oss_provider = "ollama" # or "lmstudio" ``` ## Azure provider and per-provider tuning ``` [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 ``` To change the base URL for the built-in OpenAI provider, use `openai_base_url`; don’t create `[model_providers.openai]`, because you can’t override built-in provider IDs. ## ChatGPT customers using data residency Projects created with [data residency](https://help.openai.com/en/articles/9903489-data-residency-and-inference-residency-for-chatgpt) enabled can create a model provider to update the base_url with the [correct prefix](https://platform.openai.com/docs/guides/your-data#which-models-and-features-are-eligible-for-data-residency). ``` model_provider = "openaidr" [model_providers.openaidr] name = "OpenAI Data Residency" base_url = "https://us.api.openai.com/v1" # Replace 'us' with domain prefix ``` ## Model reasoning, verbosity, and limits ``` model_reasoning_summary = "none" # Disable summaries model_verbosity = "low" # Shorten responses model_supports_reasoning_summaries = true # Force reasoning model_context_window = 128000 # Context window size ``` `model_verbosity` applies only to providers using the Responses API. Chat Completions providers will ignore the setting. ## Approval policies and sandbox modes Pick approval strictness (affects when Codex pauses) and sandbox level (affects file/network access). For operational details to keep in mind while editing `config.toml`, see [Common sandbox and approval combinations](https://developers.openai.com/codex/agent-approvals-security#common-sandbox-and-approval-combinations), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access). For beta permission profiles that configure filesystem and network access together, see [Permissions](https://developers.openai.com/codex/permissions). You can also use a granular approval policy (`approval_policy = { granular = { ... } }`) to allow or auto-reject individual prompt categories. This is useful when you want normal interactive approvals for some cases but want others, such as `request_permissions` or skill-script prompts, to fail closed automatically. Set `approvals_reviewer = "auto_review"` to route eligible interactive approval requests through automatic review. This changes the reviewer, not the sandbox boundary. Use `[auto_review].policy` for local reviewer policy instructions. Managed `guardian_policy_config` takes precedence. ``` approval_policy = "untrusted" # Other options: on-request, never, or { granular = { ... } } approvals_reviewer = "user" # Or "auto_review" for automatic review sandbox_mode = "workspace-write" allow_login_shell = false # Optional hardening: disallow login shells for shell tools # Example granular approval policy: # 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 # Allow $TMPDIR exclude_slash_tmp = false # Allow /tmp writable_roots = ["/Users/YOU/.pyenv/shims"] network_access = false # Opt in to outbound network [auto_review] policy = """ Use your organization's automatic review policy. """ ``` ### Named permission profiles For built-in profiles, custom profile syntax, and the full filesystem and network configuration model, see [Permissions](https://developers.openai.com/codex/permissions). For the complete key list and requirements constraints, see [Configuration Reference](https://developers.openai.com/codex/config-file/config-reference) and [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration). In workspace-write mode, some environments keep `.git/` and `.codex/` read-only even when the rest of the workspace is writable. This is why commands like `git commit` may still require approval to run outside the sandbox. If you want Codex to skip specific commands (for example, block `git commit` outside the sandbox), use [rules](https://developers.openai.com/codex/agent-configuration/rules). Disable sandboxing entirely (use only if your environment already isolates processes): `sandbox_mode = "danger-full-access"` ## Shell environment policy `shell_environment_policy` controls which environment variables Codex passes to spawned commands. Start with an empty environment using `inherit = "none"`, or inherit a trimmed set using `inherit = "core"`. Add explicit values and keyed filters to avoid passing unnecessary secrets to spawned commands. ``` [shell_environment_policy] inherit = "core" set = { MY_FLAG = "1" } ignore_default_excludes = false [shell_environment_policy.filters] "AWS_*" = "exclude" "AZURE_*" = "exclude" ``` Filter patterns are case-insensitive and support `*` and `?`. Use `"exclude"` to remove matching variables. When any pattern uses `"include"`, Codex keeps only variables matching an include pattern. Includes don’t restore variables that were already excluded. Filter keys merge case-insensitively across configuration layers. `ignore_default_excludes` defaults to `true`, so Codex doesn’t automatically remove variable names containing `KEY`, `SECRET`, or `TOKEN`. Set it to `false` to apply those automatic exclusions before your explicit filters run. Codex applies automatic exclusions first, then custom exclusions, values from `set`, and finally the include-pattern allowlist. Because `set` runs after exclusions, it can restore an excluded variable. An include-pattern allowlist can still remove that restored value. The older `exclude` and `include_only` arrays remain supported for existing configurations. Don’t combine either array with `[shell_environment_policy.filters]` in the same configuration layer; Codex rejects that combination. ## MCP servers See the dedicated [MCP documentation](https://developers.openai.com/codex/extend/mcp) for configuration details. ## Observability and telemetry Enable OpenTelemetry (OTel) log export to track Codex runs (API requests, SSE/events, prompts, tool approvals/results). Disabled by default; opt in via `[otel]`: ``` [otel] environment = "staging" # defaults to "dev" exporter = "none" # set to otlp-http or otlp-grpc to send events log_user_prompt = false # redact user prompts unless explicitly enabled ``` Choose an exporter: ``` [otel] exporter = { otlp-http = { endpoint = "https://otel.example.com/v1/logs", protocol = "binary", headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" } }} ``` ``` [otel] exporter = { otlp-grpc = { endpoint = "https://otel.example.com:4317", headers = { "x-otlp-meta" = "abc123" } }} ``` If `exporter = "none"` Codex records events but sends nothing. Exporters batch asynchronously and flush on shutdown. Event metadata includes service name, CLI version, env tag, conversation id, model, sandbox/approval settings, and per-event fields (see [Config Reference](https://developers.openai.com/codex/config-file/config-reference)). ### What gets emitted Codex emits structured log events for runs and tool usage. Representative event types include: * `codex.conversation_starts` (model, reasoning settings, sandbox/approval policy) * `codex.api_request` (attempt, status/success, duration, and error details) * `codex.sse_event` (stream event kind, success/failure, duration, plus token counts on `response.completed`) * `codex.websocket_request` and `codex.websocket_event` (request duration plus per-message kind/success/error) * `codex.user_prompt` (length; content redacted unless explicitly enabled) * `codex.tool_decision` (approved/denied and whether the decision came from config vs user) * `codex.tool_result` (duration, success, output snippet) ### OTel metrics emitted When the OTel metrics pipeline is enabled, Codex emits counters and duration histograms for API, stream, and tool activity. Each metric below also includes default metadata tags: `auth_mode`, `originator`, `session_source`, `model`, and `app.version`. | Metric | Type | Fields | Description | | --- | --- | --- | --- | | `codex.api_request` | counter | `status`, `success` | API request count by HTTP status and success/failure. | | `codex.api_request.duration_ms` | histogram | `status`, `success` | API request duration in milliseconds. | | `codex.sse_event` | counter | `kind`, `success` | SSE event count by event kind and success/failure. | | `codex.sse_event.duration_ms` | histogram | `kind`, `success` | SSE event processing duration in milliseconds. | | `codex.websocket.request` | counter | `success` | WebSocket request count by success/failure. | | `codex.websocket.request.duration_ms` | histogram | `success` | WebSocket request duration in milliseconds. | | `codex.websocket.event` | counter | `kind`, `success` | WebSocket message/event count by type and success/failure. | | `codex.websocket.event.duration_ms` | histogram | `kind`, `success` | WebSocket message/event processing duration in milliseconds. | | `codex.tool.call` | counter | `tool`, `success` | Tool invocation count by tool name and success/failure. | | `codex.tool.call.duration_ms` | histogram | `tool`, `success` | Tool execution duration in milliseconds by tool name and outcome. | For more security and privacy guidance around telemetry, see [Security](https://developers.openai.com/codex/agent-approvals-security#monitoring-and-telemetry). ### Metrics By default, Codex periodically sends a small amount of anonymous usage and health data back to OpenAI. This helps detect when Codex isn’t working correctly and shows what features and configuration options are being used, so the Codex team can focus on what matters most. These metrics don’t contain any personally identifiable information (PII). Metrics collection is independent of OTel log/trace export. If you want to disable metrics collection entirely across the ChatGPT desktop app, Codex CLI, and IDE extension on a machine, set the analytics flag in your config: ``` [analytics] enabled = false ``` Each metric includes its own fields plus the default context fields below. #### Default context fields (applies to every event/metric) * `auth_mode`: `swic` | `api` | `unknown`. * `model`: name of the model used. * `app.version`: Codex version. #### Metrics catalog Each metric includes the required fields plus the default context fields above. Metric names below omit the `codex.` prefix. Most metric names are centralized in `codex-rs/otel/src/metrics/names.rs`; feature-specific metrics emitted outside that file are included here too. If a metric includes the `tool` field, it reflects the internal tool used (for example, `apply_patch` or `shell`) and doesn’t contain the actual shell command or patch `codex` is trying to apply. #### Runtime and model transport | Metric | Type | Fields | Description | | --- | --- | --- | --- | | `api_request` | counter | `status`, `success` | API request count by HTTP status and success/failure. | | `api_request.duration_ms` | histogram | `status`, `success` | API request duration in milliseconds. | | `sse_event` | counter | `kind`, `success` | SSE event count by event kind and success/failure. | | `sse_event.duration_ms` | histogram | `kind`, `success` | SSE event processing duration in milliseconds. | | `websocket.request` | counter | `success` | WebSocket request count by success/failure. | | `websocket.request.duration_ms` | histogram | `success` | WebSocket request duration in milliseconds. | | `websocket.event` | counter | `kind`, `success` | WebSocket message/event count by type and success/failure. | | `websocket.event.duration_ms` | histogram | `kind`, `success` | WebSocket message/event processing duration in milliseconds. | | `responses_api_overhead.duration_ms` | histogram | | Responses API overhead timing from WebSocket responses. | | `responses_api_inference_time.duration_ms` | histogram | | Responses API inference timing from WebSocket responses. | | `responses_api_engine_iapi_ttft.duration_ms` | histogram | | Responses API engine IAPI time-to-first-token timing. | | `responses_api_engine_service_ttft.duration_ms` | histogram | | Responses API engine service time-to-first-token timing. | | `responses_api_engine_iapi_tbt.duration_ms` | histogram | | Responses API engine IAPI time-between-token timing. | | `responses_api_engine_service_tbt.duration_ms` | histogram | | Responses API engine service time-between-token timing. | | `transport.fallback_to_http` | counter | `from_wire_api` | WebSocket-to-HTTP fallback count. | | `remote_models.fetch_update.duration_ms` | histogram | | Time to fetch remote model definitions. | | `remote_models.load_cache.duration_ms` | histogram | | Time to load the remote model cache. | | `startup_prewarm.duration_ms` | histogram | `status` | Startup prewarm duration by outcome. | | `startup_prewarm.age_at_first_turn_ms` | histogram | `status` | Startup prewarm age when the first real turn resolves it. | | `cloud_requirements.fetch.duration_ms` | histogram | | Workspace-managed cloud requirements fetch duration. | | `cloud_requirements.fetch_attempt` | counter | See note | Workspace-managed cloud requirements fetch attempts. | | `cloud_requirements.fetch_final` | counter | See note | Final workspace-managed cloud requirements fetch outcome. | | `cloud_requirements.load` | counter | `trigger`, `outcome` | Workspace-managed cloud requirements load outcome. | The `cloud_requirements.fetch_attempt` metric includes `trigger`, `attempt`, `outcome`, and `status_code` fields. The `cloud_requirements.fetch_final` metric includes `trigger`, `outcome`, `reason`, `attempt_count`, and `status_code` fields. #### Turn and tool activity | Metric | Type | Fields | Description | | --- | --- | --- | --- | | `turn.e2e_duration_ms` | histogram | | End-to-end time for a full turn. | | `turn.ttft.duration_ms` | histogram | | Time to first token for a turn. | | `turn.ttfm.duration_ms` | histogram | | Time to first model output item for a turn. | | `turn.network_proxy` | counter | `active`, `tmp_mem_enabled` | Whether the managed network proxy was active for the turn. | | `turn.memory` | counter | `read_allowed`, `feature_enabled`, `config_use_memories`, `has_citations` | Per-turn memory read availability and memory citation usage. | | `turn.tool.call` | histogram | `tmp_mem_enabled` | Number of tool calls in the turn. | | `turn.token_usage` | histogram | `token_type`, `tmp_mem_enabled` | Per-turn token usage by token type (`total`, `input`, `cached_input`, `output`, or `reasoning_output`). | | `tool.call` | counter | `tool`, `success` | Tool invocation count by tool name and success/failure. | | `tool.call.duration_ms` | histogram | `tool`, `success` | Tool execution duration in milliseconds by tool name and outcome. | | `tool.unified_exec` | counter | `tty` | Unified exec tool calls by TTY mode. | | `approval.requested` | counter | `tool`, `approved` | Tool approval request result (`approved`, `approved_with_amendment`, `approved_for_session`, `denied`, `abort`). | | `mcp.call` | counter | See note | MCP tool invocation result. | | `mcp.call.duration_ms` | histogram | See note | MCP tool invocation duration. | | `mcp.tools.list.duration_ms` | histogram | `cache` | MCP tool-list duration, including cache hit/miss state. | | `mcp.tools.fetch_uncached.duration_ms` | histogram | | Duration of MCP tool fetches that miss the cache. | | `mcp.tools.cache_write.duration_ms` | histogram | | Duration of Codex Apps MCP tool-cache writes. | | `hooks.run` | counter | `hook_name`, `source`, `status` | Hook run count by hook name, source, and status. | | `hooks.run.duration_ms` | histogram | `hook_name`, `source`, `status` | Hook run duration in milliseconds. | The `mcp.call` and `mcp.call.duration_ms` metrics include `status`; normal tool-call emissions also include `tool`, plus `connector_id` and `connector_name` when available. Blocked Codex Apps MCP calls may emit `mcp.call` with only `status`. #### Threads, tasks, and features | Metric | Type | Fields | Description | | --- | --- | --- | --- | | `feature.state` | counter | `feature`, `value` | Feature values that differ from defaults (emit one row per non-default). | | `status_line` | counter | | Session started with a configured status line. | | `model_warning` | counter | | Warning sent to the model. | | `thread.started` | counter | `is_git` | New thread created, tagged by whether the working directory is in a Git repo. | | `conversation.turn.count` | counter | | User/assistant turns per thread, recorded at the end of the thread. | | `thread.fork` | counter | `source` | New thread created by forking an existing thread. | | `thread.rename` | counter | | Thread renamed. | | `thread.side` | counter | `source` | Side conversation created. | | `thread.skills.enabled_total` | histogram | | Number of skills enabled for a new thread. | | `thread.skills.kept_total` | histogram | | Number of enabled skills kept after prompt rendering. | | `thread.skills.truncated` | histogram | | Whether skill rendering truncated the enabled skills list (`1` or `0`). | | `task.compact` | counter | `type` | Number of compactions per type (`remote` or `local`), including manual and auto. | | `task.review` | counter | | Number of reviews triggered. | | `task.undo` | counter | | Number of undo actions triggered. | | `task.user_shell` | counter | | Number of user shell actions (`!` in the TUI for example). | | `shell_snapshot` | counter | See note | Whether taking a shell snapshot succeeded. | | `shell_snapshot.duration_ms` | histogram | `success` | Time to take a shell snapshot. | | `skill.injected` | counter | `status`, `skill` | Skill injection outcomes by skill. | | `plugins.startup_sync` | counter | `transport`, `status` | Curated plugin startup sync attempts. | | `plugins.startup_sync.final` | counter | `transport`, `status` | Final curated plugin startup sync outcome. | | `multi_agent.spawn` | counter | `role` | Agent spawns by role. | | `multi_agent.resume` | counter | | Agent resumes. | | `multi_agent.nickname_pool_reset` | counter | | Agent nickname pool resets. | The `shell_snapshot` metric includes `success` and, on failures, `failure_reason`. #### Memory and local state | Metric | Type | Fields | Description | | --- | --- | --- | --- | | `memory.phase1` | counter | `status` | Memory phase 1 job counts by status. | | `memory.phase1.e2e_ms` | histogram | | End-to-end duration for memory phase 1. | | `memory.phase1.output` | counter | | Memory phase 1 outputs written. | | `memory.phase1.token_usage` | histogram | `token_type` | Memory phase 1 token usage by token type. | | `memory.phase2` | counter | `status` | Memory phase 2 job counts by status. | | `memory.phase2.e2e_ms` | histogram | | End-to-end duration for memory phase 2. | | `memory.phase2.input` | counter | | Memory phase 2 input count. | | `memory.phase2.token_usage` | histogram | `token_type` | Memory phase 2 token usage by token type. | | `memories.usage` | counter | `kind`, `tool`, `success` | Memory usage by kind, tool, and success/failure. | | `external_agent_config.detect` | counter | See note | External agent config detections by migration item type. | | `external_agent_config.import` | counter | See note | External agent config imports by migration item type. | | `db.backfill` | counter | `status` | Initial state DB backfill results (`upserted`, `failed`). | | `db.backfill.duration_ms` | histogram | `status` | Duration of the initial state DB backfill. | | `db.error` | counter | `stage` | Errors during state DB operations. | The `external_agent_config.detect` and `external_agent_config.import` metrics include `migration_type`; skills migrations also include `skills_count`. #### Windows sandbox | Metric | Type | Fields | Description | | --- | --- | --- | --- | | `windows_sandbox.setup_success` | counter | `originator`, `mode` | Windows sandbox setup successes. | | `windows_sandbox.setup_failure` | counter | `originator`, `mode` | Windows sandbox setup failures. | | `windows_sandbox.setup_duration_ms` | histogram | `result`, `originator`, `mode` | Windows sandbox setup duration. | | `windows_sandbox.elevated_setup_success` | counter | | Elevated Windows sandbox setup successes. | | `windows_sandbox.elevated_setup_failure` | counter | See note | Elevated Windows sandbox setup failures. | | `windows_sandbox.elevated_setup_canceled` | counter | See note | Canceled elevated Windows sandbox setup attempts. | | `windows_sandbox.elevated_setup_duration_ms` | histogram | `result` | Elevated Windows sandbox setup duration. | | `windows_sandbox.elevated_prompt_shown` | counter | | Elevated sandbox setup prompt shown. | | `windows_sandbox.elevated_prompt_accept` | counter | | Elevated sandbox setup prompt accepted. | | `windows_sandbox.elevated_prompt_use_legacy` | counter | | User chose legacy sandbox from the elevated prompt. | | `windows_sandbox.elevated_prompt_quit` | counter | | User quit from the elevated prompt. | | `windows_sandbox.fallback_prompt_shown` | counter | | Fallback sandbox prompt shown. | | `windows_sandbox.fallback_retry_elevated` | counter | | User retried elevated setup from the fallback prompt. | | `windows_sandbox.fallback_use_legacy` | counter | | User chose legacy sandbox from the fallback prompt. | | `windows_sandbox.fallback_prompt_quit` | counter | | User quit from the fallback prompt. | | `windows_sandbox.legacy_setup_preflight_failed` | counter | See note | Legacy Windows sandbox setup preflight failure. | | `windows_sandbox.setup_elevated_sandbox_command` | counter | | Elevated sandbox setup command invoked. | | `windows_sandbox.createprocessasuserw_failed` | counter | `error_code`, `path_kind`, `exe`, `level` | Windows `CreateProcessAsUserW` failures. | The elevated setup failure metrics include `code` and `message` when Windows setup failure details are available, and may include `originator` when emitted from the shared setup path. The `windows_sandbox.legacy_setup_preflight_failed` metric includes `originator` when emitted from the shared setup path, but fallback-prompt preflight failures may not include any fields. ### Feedback controls By default, local clients let users send feedback from `/feedback`. To disable feedback collection across the ChatGPT desktop app, Codex CLI, and IDE extension on a machine, update your config: ``` [feedback] enabled = false ``` When disabled, `/feedback` shows a disabled message and Codex rejects feedback submissions. ### Hide or surface reasoning events If you want to reduce noisy “reasoning” output (for example in CI logs), you can suppress it: `hide_agent_reasoning = true` If you want to surface raw reasoning content when a model emits it: `show_raw_agent_reasoning = true` Enable raw reasoning only if it’s acceptable for your workflow. Some models/providers (like `gpt-oss`) don’t emit raw reasoning; in that case, this setting has no visible effect. ## Notifications Use `notify` to trigger an external program whenever Codex emits supported events (currently only `agent-turn-complete`). This is handy for desktop toasts, chat webhooks, CI updates, or any side-channel alerting that the built-in TUI notifications don’t cover. `notify = ["python3", "/path/to/notify.py"]` Example `notify.py` (truncated) that reacts to `agent-turn-complete`: ``` #!/usr/bin/env python3 import json, subprocess, sys def main() -> int: notification = json.loads(sys.argv[1]) if notification.get("type") != "agent-turn-complete": return 0 title = f"Codex: {notification.get('last-assistant-message', 'Turn Complete!')}" message = " ".join(notification.get("input-messages", [])) subprocess.check_output([ "terminal-notifier", "-title", title, "-message", message, "-group", "codex-" + notification.get("thread-id", ""), "-activate", "com.googlecode.iterm2", ]) return 0 if __name__ == "__main__": sys.exit(main()) ``` The script receives a single JSON argument. Common fields include: * `type` (currently `agent-turn-complete`) * `thread-id` (session identifier) * `turn-id` (turn identifier) * `cwd` (working directory) * `input-messages` (user messages that led to the turn) * `last-assistant-message` (last assistant message text) Place the script somewhere on disk and point `notify` to it. #### `notify` vs `tui.notifications` * `notify` runs an external program (good for webhooks, desktop notifiers, CI hooks). * `tui.notifications` is built in to the TUI and can optionally filter by event type (for example, `agent-turn-complete` and `approval-requested`). * `tui.notification_method` controls how the TUI emits terminal notifications (`auto`, `osc9`, or `bel`). * `tui.notification_condition` controls whether TUI notifications fire only when the terminal is `unfocused` or `always`. In `auto` mode, Codex prefers OSC 9 notifications (a terminal escape sequence some terminals interpret as a desktop notification) and falls back to BEL (`\x07`) otherwise. See [Configuration Reference](https://developers.openai.com/codex/config-file/config-reference) for the exact keys. ## History persistence By default, Codex saves local session transcripts under `CODEX_HOME` (for example, `~/.codex/history.jsonl`). To disable local history persistence: ``` [history] persistence = "none" ``` To cap the history file size, set `history.max_bytes`. When the file exceeds the cap, Codex drops the oldest entries and compacts the file while keeping the newest records. ``` [history] max_bytes = 104857600 # 100 MiB ``` ## Clickable citations If you use a terminal/editor integration that supports it, Codex can render file citations as clickable links. Configure `file_opener` to pick the URI scheme Codex uses: `file_opener = "vscode" # or cursor, windsurf, vscode-insiders, none` Example: a citation like `/home/user/project/main.py:42` can be rewritten into a clickable `vscode://file/...:42` link. ## Project instructions discovery Codex reads `AGENTS.md` (and related files) and includes a limited amount of project guidance in the first turn of a session. Two knobs control how this works: * `project_doc_max_bytes`: how much to read from each `AGENTS.md` file * `project_doc_fallback_filenames`: additional filenames to try when `AGENTS.md` is missing at a directory level For a detailed walkthrough, see [Custom instructions with AGENTS.md](https://developers.openai.com/codex/agent-configuration/agents-md). ## Desktop Options in this section apply only to the ChatGPT desktop app. ### Add custom file handlers In your user-level `~/.codex/config.toml`, add entries under `desktop.custom_file_handlers` to open files in editors or internal launchers that the ChatGPT desktop app doesn’t support by default. Each entry adds an editor target to the app’s **Open in** menus. The app lists the target when `command` is an existing absolute path or resolves from the app’s `PATH`. The following example shows three ways to pass a file to a handler: ``` # Append the opened path directly after the command. [desktop.custom_file_handlers.vscodium] label = "VSCodium" icon = "/Users/you/.codex/icons/vscodium.png" command = "codium" # Place fixed arguments before the opened path. [desktop.custom_file_handlers.textedit] label = "TextEdit" icon = "/Users/you/.codex/icons/textedit.png" command = "/usr/bin/open" args = ["-a", "TextEdit"] # Append one JSON argument with the path and editor context. [desktop.custom_file_handlers.company_editor] label = "Company Editor" icon = "/opt/company/editor/icon.png" command = "/opt/company/bin/editor" input = "json_argument" ``` Save `config.toml`, then restart the ChatGPT desktop app. The handler ID is the final segment of the TOML table header. It must contain 1–64 characters, start with an ASCII letter or number, and otherwise contain only ASCII letters, numbers, periods, underscores, or hyphens. The app exposes the ID with a `custom:` prefix; for example, `company_editor` becomes `custom:company_editor`. Quote an ID that contains a period so TOML doesn’t interpret it as a nested table. For example: ``` [desktop.custom_file_handlers."company.editor"] label = "Company Editor" icon = "/opt/company/editor/icon.png" command = "/opt/company/bin/editor" ``` Each handler supports these fields: | Field | Required | Description | | --- | --- | --- | | `label` | Yes | Display name in the app. | | `icon` | Yes | Bundled app icon such as `apps/vscode.png`, base64 `data:image/...` URL, `file:` URI, or absolute local image path. An unsupported source uses the default VS Code icon. | | `command` | Yes | Executable path or command name to detect and launch. | | `args` | No | String array inserted between `command` and the file input. Defaults to `[]`. | | `input` | No | How the app sends file input: `path`, `json_argument`, or `json_stdin`. Defaults to `path`. | | `supports_ssh` | No | Whether to offer the handler for files in SSH workspaces. Defaults to `false`. Use `json_stdin` when the handler needs remote host and path details. | The `input` value controls what follows `args`: * `path` appends the path as the final command argument. * `json_argument` appends a JSON object with `target`, `path`, `appPath`, and `location`. The `location` value is an object with 1-based `line` and `column` values, or `null`. * `json_stdin` writes the JSON object to standard input instead of adding an argument. It also includes `hostConfig`, `remoteWorkspaceRoot`, and `remotePath`; these fields are `null` when they don’t apply. For example, `company_editor` can receive this argument when the user opens a specific source location: ``` { "target": "custom:company_editor", "path": "/repo/src/index.ts", "appPath": null, "location": { "line": 12, "column": 3 } } ``` Selecting a custom handler as the preferred editor persists the choice the same way as selecting a built-in editor, including per-project preferences. ## TUI options Running `codex` with no subcommand launches the interactive terminal UI (TUI). Codex exposes some TUI-specific configuration under `[tui]`, including: * `tui.notifications`: enable/disable notifications (or restrict to specific types) * `tui.notification_method`: choose `auto`, `osc9`, or `bel` for terminal notifications * `tui.notification_condition`: choose `unfocused` or `always` for when notifications fire * `tui.animations`: enable/disable ASCII animations and shimmer effects * `tui.alternate_screen`: control alternate screen usage (set to `never` to keep terminal scrollback) * `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen `tui.notification_method` defaults to `auto`. In `auto` mode, Codex prefers OSC 9 notifications (a terminal escape sequence some terminals interpret as a desktop notification) when the terminal appears to support them, and falls back to BEL (`\x07`) otherwise. See [Configuration Reference](https://developers.openai.com/codex/config-file/config-reference) for the full key list. [Previous Config Basics](https://developers.openai.com/codex/config-file/config-basic)[Next Config Reference](https://developers.openai.com/codex/config-file/config-reference) Ask AI ## Docs agent Loading docs agent...