Config.toml | Updated Keys

Resolved 💬 19 comments Opened Aug 27, 2025 by Alfredo-Sandoval Closed Oct 28, 2025

💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

What is the type of issue?

Documentation is missing

What is the issue?

# ============================================================================
# Codex CLI — Comprehensive Configuration Template
# Generated: 2025-08-27
#  ~/.codex/config.toml (aka $CODEX_HOME/config.toml)
# ============================================================================

# ----------------------------------------------------------------------------
# NEW ENTRIES (added in this release)
# ----------------------------------------------------------------------------
# 1) [tools].web_search = true   # Added Aug 23, 2025
#    Enables native web search tool. CLI flag is --search (TUI only); TOML key
#    works for both TUI and codex-exec. Alias also accepted: web_search_request.
#
# 2) preferred_auth_method = "apikey" | "chatgpt"   # Added Aug 18, 2025
#    Prefer API key or ChatGPT auth when both are present.
#
# 3) [projects."/abs/path"].trust_level = "trusted"   # Added Aug 7, 2025
#    Mark specific repos trusted to reduce prompts in versioned workspaces.
#
# 4) model_verbosity = "low" | "medium" | "high"   # Added Aug 22, 2025
#    Controls Responses API text verbosity for GPT‑5 family models.
#
# 5) Per-provider network tuning in [model_providers.<id>]   # Added Jul 18, 2025; caps Aug 25, 2025
#    request_max_retries, stream_max_retries, stream_idle_timeout_ms.
#    Note: only valid inside provider blocks; older top‑level keys are ignored.
#
# 6) show_raw_agent_reasoning = true   # Added Aug 5, 2025
#    Surfaces raw chain‑of‑thought events when available.
#
# 7) shell_environment_policy.experimental_use_profile = true   # Added Jul 25, 2025
#    Advanced: run shell commands through a profile (opt‑in).
#
# 8) chatgpt_base_url = "https://chatgpt.com/backend-api/"   # Added Jul 11, 2025
#    Advanced override for ChatGPT backend URL.
#
# 9) responses_originator_header_internal_override = "codex_cli_rs"   # Added Aug 19, 2025
#    Internal/testing only; do not set unless you know why.
# ----------------------------------------------------------------------------

####################################
# Root (top-level) keys
####################################

model = "gpt-5"                                # default model
# model_provider = "openai"                      # key under [model_providers]
# model_context_window = 200000                   # tokens; override when unknown
# model_max_output_tokens = 100000                # tokens; override when unknown
#
approval_policy = "never"                  # "untrusted" | "on-failure" | "on-request" | "never"
sandbox_mode = "danger-full-access"                      # "read-only" | "workspace-write" | "danger-full-access"
# disable_response_storage = false                # set true for ZDR accounts
#
# file_opener = "vscode"                          # "vscode" | "vscode-insiders" | "windsurf" | "cursor" | "none"
# hide_agent_reasoning = false
# show_raw_agent_reasoning = false
#
model_reasoning_effort = "high"               # "minimal" | "low" | "medium" | "high" | "none"
# model_reasoning_summary = "auto"                # "auto" | "concise" | "detailed" | "none"
# model_verbosity = "medium"                      # GPT‑5 family only; "low" | "medium" | "high"
# model_supports_reasoning_summaries = false      # force-enable reasoning block
#
# chatgpt_base_url = "https://chatgpt.com/backend-api/"     # advanced
# experimental_resume = "/abs/path/resume.jsonl"            # advanced
# experimental_instructions_file = "/abs/path/base.txt"     # advanced
# experimental_use_exec_command_tool = false                 # advanced
# responses_originator_header_internal_override = "codex_cli_rs"  # internal/testing
#
# project_doc_max_bytes = 32768                    # bytes to read from AGENTS.md
# preferred_auth_method = "chatgpt"                # or "apikey"
#
# profile = "default"                              # active [profiles] entry
#
# instructions = "You are a helpful assistant."    # extra system instructions (merged with AGENTS.md)
#
# notify = ["notify-send", "Codex"]                 # program argv; Codex appends JSON payload

####################################
# Tools (feature toggles)
####################################

[tools]
# Enable the native Responses web_search tool (same as TUI --search)
web_search = true
# alias for backwards compatibility:
# web_search_request = true

####################################
# Shell environment policy for spawned processes
####################################

[shell_environment_policy]
# inherit = "all"                  # "all" | "core" | "none"
# ignore_default_excludes = false   # when false, drops vars whose NAMES contain KEY/SECRET/TOKEN
# exclude = ["AWS_*", "AZURE_*"]   # case-insensitive globs
# set = { CI = "1" }                # force-set values
# include_only = ["PATH", "HOME"]   # keep-only whitelist (globs)
# experimental_use_profile = false   # advanced

####################################
# Sandbox settings (apply when sandbox_mode = "workspace-write")
####################################

[sandbox_workspace_write]
# writable_roots = ["/additional/writable/path"]
# network_access = false
# exclude_tmpdir_env_var = false
# exclude_slash_tmp = false

####################################
# History persistence
####################################

[history]
persistence = "save-all"          # "save-all" | "none"
# max_bytes = 10485760               # not strictly enforced yet

####################################
# MCP servers (tools via stdio)
####################################

# [mcp_servers.example]
# command = "npx"
# args = ["-y", "mcp-server-example"]
# env = { API_KEY = "value" }

####################################
# Model providers (extend/override built-ins)
####################################

# Built-in OpenAI provider can be customized here.
# [model_providers.openai]
# name = "OpenAI"
# base_url = "https://api.openai.com/v1"          # OPENAI_BASE_URL env var also supported
# wire_api = "responses"                           # "responses" | "chat"
# query_params = {}
# http_headers = { version = "0.0.0" }
# env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }
# request_max_retries = 4
# stream_max_retries = 5
# stream_idle_timeout_ms = 300000
# requires_openai_auth = true

# Chat Completions-compatible provider example
# [model_providers.openai-chat-completions]
# name = "OpenAI using Chat Completions"
# base_url = "https://api.openai.com/v1"
# env_key = "OPENAI_API_KEY"
# wire_api = "chat"
# query_params = {}

# Azure example (requires api-version)
# [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" }

# Local OSS (Ollama) example
# [model_providers.ollama]
# name = "Ollama"
# base_url = "http://localhost:11434/v1"
# wire_api = "chat"

####################################
# Profiles (bundled overrides you can switch with --profile)
####################################

# [profiles.default]
# model = "gpt-5"
# model_provider = "openai"
# approval_policy = "never"
# disable_response_storage = false
# model_reasoning_effort = "high"
# model_reasoning_summary = "auto"
# model_verbosity = "medium"
# chatgpt_base_url = "https://chatgpt.com/backend-api/"
# experimental_instructions_file = "/abs/path/base_instructions.txt"

# [profiles.zdr]
# model = "o3"
# model_provider = "openai"
# approval_policy = "on-failure"
# disable_response_storage = true

####################################
# Projects trust (per-absolute-path)
####################################

# [projects."/absolute/path/to/your/repo"]
# trust_level = "trusted"    # mark as trusted

####################################
# Quick reference: CLI overrides (for sharing/docs)
####################################
# codex -c model="o3"
# codex -c 'tools.web_search=true' "your prompt here"
# codex --sandbox workspace-write --ask-for-approval on-request

# Notes:
# - The TUI flag --search maps to [tools].web_search in TOML.
# - The built-in OpenAI provider also respects env: OPENAI_BASE_URL, OPENAI_ORGANIZATION, OPENAI_PROJECT.
# - OSS provider can be influenced by env: CODEX_OSS_BASE_URL, CODEX_OSS_PORT (envs, not TOML).

# NOTE: network_access is only valid under [sandbox_workspace_write].
# When sandbox_mode="danger-full-access", network is already unrestricted.

Where did you find it?

_No response_

View original on GitHub ↗

19 Comments

skanehira · 10 months ago

Thanks!!

zhlmmc · 10 months ago

I had the file in ~/.codex/config.toml but somehow codex is not reading the file. When I try codex, it still use o4-mini model:

The config.toml has specified to use gpt-5.

avxkim · 10 months ago

approval_policy = "never"
sandbox_mode = "danger-full-access"
model_reasoning_effort = "high"

[tools]
web_search = true

seems like none of these settings work now, still asks for approvals, reasoning is medium by default and web search is disabled, unlike with codex --search

Alfredo-Sandoval · 10 months ago

@avxkim that's odd. Can you try this one?


# =========================
# Codex CLI config.toml
# =========================
# Rule: In each "CHOOSE ONE" block, uncomment EXACTLY ONE line.

# -------------------------
# Model (string)
# -------------------------

# CHOOSE ONE:
model = "gpt-5"
# model = "o3"
# model = "o4-mini"

# -------------------------
# Reasoning effort (string)
# -------------------------

# CHOOSE ONE:
model_reasoning_effort = "high"
# model_reasoning_effort = "medium"
# model_reasoning_effort = "low"
# model_reasoning_effort = "minimal"


# -------------------------
# Approval policy (string)
# -------------------------

# CHOOSE ONE:
# approval_policy = "on-request"
# approval_policy = "untrusted"
# approval_policy = "on-failure"
approval_policy = "never"

# -------------------------
# Sandbox mode (string)
# -------------------------

# CHOOSE ONE:
sandbox_mode = "danger-full-access"   # no sandbox
# sandbox_mode = "workspace-write"     # writes allowed in cwd/tmp only
# sandbox_mode = "read-only"           # default in docs: no writes, no network

network_access = true

# -------------------------
# File opening and UI settings
# -------------------------
file_opener = "vscode"                    # Opens files in VS Code when clicked
#hide_agent_reasoning = false
show_raw_agent_reasoning = true           # Show raw reasoning content (if available)
model_reasoning_summary = "auto"  

# -------------------------
# Shell Environment Policy
# -------------------------

[shell_environment_policy]
# Secure baseline: only essential environment variables
ignore_default_excludes = false   # Extra protection: drops vars with KEY/SECRET/TOKEN
include_only = [
    # Core essentials (always needed)
    "PATH",          # Required for finding executables
    "HOME",          # Home directory reference
    "USER",          # Username
    "SHELL",         # Shell interpreter
    
    # System locale (prevents encoding issues)
    "LANG",          # Primary locale
    "LC_*",          # All locale settings
    
    # Terminal & editor
    "TERM",          # Terminal type for proper display
    "EDITOR",        # Default editor
    "VISUAL",        # Visual editor fallback
    
    # Directories
    "PWD",           # Current working directory
    "OLDPWD",        # Previous directory
    "TMPDIR",        # Temporary directory location
    
    # Linux desktop standards
    "XDG_*",         # XDG Base Directory specs
    
    # Python development
    "PYTHON*",       # Python paths and settings
    "PIP_*",         # Pip configuration
    "VIRTUAL_ENV*",  # Virtual environment paths
    "CONDA_*",       # Conda/Anaconda settings
    "PYENV_*",       # Pyenv version management
    
    # Node.js development
    "NODE_*",        # Node.js settings
    "NPM_*",         # NPM configuration
    "NVM_*",         # Node Version Manager
    "PNPM_*",        # PNPM package manager
    "YARN_*"         # Yarn package manager
]

# NEVER add: "*_KEY", "*_SECRET", "*_TOKEN", "AWS_*", "AZURE_*", "GCP_*"

[tools]

# Enable the native Responses web_search tool (same as `--search`).
web_search = true
# Allow attaching local images to provide visual context.
view_image = true 
# -------------------------
# History persistence
# -------------------------

[history]
persistence = "save-all"          # Keeps conversation history across sessions
# max_bytes = 10485760            # Optional: limit history size

# -------------------------
# Project trust settings
# -------------------------

[projects."/home/YOUR_USER/Documents/GitHub/codex"]
trust_level = "trusted"           # Skip security prompts for this repo


use_experimental_reasoning_summary = true

# Avoid storing responses on disk (set true for ZDR / enterprise keys)
# See: disableResponseStorage issues in CLI + rust implementations
disable_response_storage = false

# Controls model verbosity for supported models (e.g., GPT‑5 family)
# Values: "low" | "medium" | "high"
model_verbosity = "medium"
model_supports_reasoning_summaries = true

# =============================================================

avxkim · 10 months ago

Sadly, no, doesn't work. Are you on MacOS? I installed codex with brew, only command line args work for me:

alias codex='codex -c approval_policy=never \
                   -c model_reasoning_effort=high \
                   --sandbox danger-full-access'

Alfredo-Sandoval · 10 months ago

I'm on linux. I would make sure that $CODEX_HOME is set to the same location as your config.toml. Does the npm install work on MacOS? If the CLI flags work so should those toml keys.

avxkim · 10 months ago

i chose brew because i don't want to mess with node versions, seems like it's really doesn't work on mac, these settings i mean, just tried another mac - same problem

akamalov · 10 months ago

I can confirm that the same issue happening to me.

Environment

OS: Mac M3 - Sequoia - 15.6.1
Codex: codex-cli 0.30.0

Configuration

File: ~/.codex/config.toml

[mcpServers.brave-search]
command = "docker"
args = ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "mcp/brave-search"]

[mcpServers.brave-search.env]
BRAVE_API_KEY = "XXXXXXX"

[mcpServers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/user1"]

[mcpServers.sequential-thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]

[mcpServers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena-mcp-server"]

[mcpServers.mcp-memory-bank]
command = "uvx"
args = ["--from", "git+https://github.com/ipospelov/mcp-memory-bank", "mcp_memory_bank"]

[mcpServers.code-reasoning]
command = "npx"
args = ["-y", "@mettamatt/code-reasoning"]

[mcpServers.consult7]
type = "stdio"
command = "uvx"
args = ["consult7", "google", "XXXXXXX"]

[mcpServers.gemini-cli]
command = "npx"
args = ["-y", "gemini-mcp-tool"]

[mcpServers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

[mcpServers.claude-flow]
command = "npx"
args = ["claude-flow", "mcp", "start"]

[mcpServers.zen]
command = "npx"
args = ["zen-mcp-server-199bio"]

[mcpServers.zen.env]
GEMINI_API_KEY = "XXXXXX"
OPENAI_API_KEY = "sk-proj-7XXXXXXX"
OPENROUTER_API_KEY = "sk-or-v1-XXXXXXXX"

[mcpServers.cascade-thinking]
command = "npx"
args = ["-y", "cascade-thinking-mcp"]

[mcpServers.octocode-mcp]
command = "npx"
args = ["octocode-mcp"]

[mcpServers.octocode-mcp.env]
GITHUB_TOKEN = "github_pat_11AXXXX"

[mcpServers.shadcn-ui]
command = "npx"
args = ["-y", "shadcn-ui-mcp-server"]

[mcpServers.code-index]
command = "uvx"
args = ["code-index-mcp"]

[mcpServers."@21st-dev/magic"]
command = "npx"
args = ["-y", "@21st-dev/magic@latest"]

[mcpServers."@21st-dev/magic".env]
API_KEY = "XXXXXXXXX"

[mcpServers.simple-utcp-client-mcp]
command = "uv"
args = ["run", "--script", "/Users/user1/bin/simple-utcp-client-mcp.py"]

[mcpServers.codex]
type = "stdio"
command = "codex"
args = ["mcp", "-m", "gpt-5", "-c", "model_reasoning_effort=high"]

[mcpServers.codex.env]
OPENAI_API_KEY = "sk-proj-XXXXXXX"

[mcpServers.code-graph-mcp]
command = "code-graph-mcp"

Now, start codex and list MCP servers:

/status
📂 Workspace
  • Path: ~/projects/sfticket
  • Approval Mode: on-request
  • Sandbox: workspace-write
  • AGENTS files: AGENTS.md

👤 Account
  • Signed in with ChatGPT
  • Login: user1@gmail.com
  • Plan: Free

🧠 Model
  • Name: gpt-5
  • Provider: OpenAI
  • Reasoning Effort: Medium
  • Reasoning Summaries: Auto

📊 Token Usage
  • Session ID: a8ba4390-d896-4213-9bcf-80782ebc430e
  • Input: 0
  • Output: 0
  • Total: 0

▌ Improve documentation in @filename
 ⏎ send   ⇧⏎ newline   ⌃T transcript   ⌃C quit

Let's list MCP servers:

/mcp

🔌  MCP Tools

  • No MCP servers configured.
    See the MCP docs to configure them.

▌ Improve documentation in @filename
 ⏎ send   ⇧⏎ newline   ⌃T transcript   ⌃C quit

So, it looks like it's not even looking at ~/.codex/config.toml file

Alfredo-Sandoval · 10 months ago

Does setting it via $CODEX_HOME work? I'm about to get a Mac so very curious about this.

akamalov · 10 months ago

@Alfredo-Sandoval , I did set $CODEX_HOME=~/.codex where config.toml is located (~/.codex/config.toml) with MCP is configured. So far, no dice, no MCPs are showing.

Alfredo-Sandoval · 10 months ago

@codex deep dive into this issue

akamalov · 10 months ago

@Alfredo-Sandoval , it looks like codex is not fully mcp compliant. https://www.reddit.com/r/mcp/comments/1mn6s4h/codex_is_not_fully_mcp_compliant_how_to_work/

https://github.com/openai/codex/issues/3324

MrAshRhodes · 10 months ago

I can confirm that the same issue happening to me. Environment OS: Mac M3 - Sequoia - 15.6.1 Codex: codex-cli 0.30.0 Configuration File: ~/.codex/config.toml `` [mcpServers.brave-search] command = "docker" args = ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "mcp/brave-search"] ``

Your mcp keys are incorrect

config should be like

[mcp_servers.sequential-thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]

the example gives [mcp_servers.servername]

akamalov · 10 months ago

Thanks for replying. However, I am not quite sure what are you referring
to:

Are you saying that docker-based MCPs are not supported and one must use

Node-based MCPs?

Provided key syntax is wrong and one must pass API_KEY variable

differently. In that case what would be correct syntax?

Thank you.

On Wed, Sep 10, 2025, 3:04 AM Focused Instability @.***>
wrote:

MrAshRhodes left a comment (openai/codex#2760) <https://github.com/openai/codex/issues/2760#issuecomment-3273592636> I can confirm that the same issue happening to me. Environment OS: Mac M3 - Sequoia - 15.6.1 Codex: codex-cli 0.30.0 Configuration File: ~/.codex/config.toml [mcpServers.brave-search] command = "docker" args = ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "mcp/brave-search"] Your mcp keys are incorrect config should be like [mcp_servers.sequential-thinking] command = "npx" args = ["-y", @./server-sequential-thinking"] the example gives [mcp_servers.servername] — Reply to this email directly, view it on GitHub <https://github.com/openai/codex/issues/2760#issuecomment-3273592636>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB4FDSLGQ3NZ6TXP4KYMIUD3R7EOJAVCNFSM6AAAAACE5WNLLWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTENZTGU4TENRTGY> . You are receiving this because you commented.Message ID: @.>

MrAshRhodes · 10 months ago

@akamalov not at all, im just saying that the config posted had

[mcpServers.brave-search]

when it should be [mcp_servers.bravesearch]

so it would be

[mcp_servers.brave-search]
command = "docker"
args = ["run", "-i", "--rm", "mcp/brave-search"]

Ive not tested docker, i was just commenting this difference as to why its likely not working.

Edit: I think the config would look like this... looking at the documentation - https://github.com/openai/codex/blob/main/docs/advanced.md#model-context-protocol-mcp

[mcp_servers.brave-search]
command = "docker"
args = args = ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "mcp/brave-search"]
env = { "BRAVE_API_KEY" = "api-value" }

akamalov · 10 months ago

@MrAshRhodes , you're awesome! Thank you very much indeed for your help!!

SMAW · 8 months ago

I've got it working in the past with Azure OpenAI but now since 2 days the sidebar stays blank in vscode, codexcli is working. is this also possible trough remote-ssh with Azure openAI

etraut-openai contributor · 8 months ago

Thanks for reporting the problem. The thread has explored a number of related topics, so it's not clear to me whether there's anything remaining to do with the original documentation issue. I think the docs are now up to date, so I'm going to mark this issue as closed. If you're aware of any config keys that are still missing from the docs, please open a new issue.

antonlvovych · 8 months ago

@etraut-openai docs still not up do date:

Leads to warnings in Codex CLI:

⚠ tools.view_image is deprecated. Use view_image_tool instead.
You can either enable it using the CLI with --enable view_image_tool or through the config.toml file with [features].view_image_tool

⚠ tools.web_search is deprecated. Use web_search_request instead.
You can either enable it using the CLI with --enable web_search_request or through the config.toml file with [features].web_search_request