Config.toml | Updated Keys

[Alfredo-Sandoval]

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

[skanehira]

Thanks!!

[zhlmmc]

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]

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]

@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]

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]

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]

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]

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]

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

[akamalov]

@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]

@codex deep dive into this issue

[akamalov]

@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/

#3324

[MrAshRhodes]

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]

Thanks for replying. However, I am not quite sure what are you referring to: 1. Are you saying that docker-based MCPs are not supported and one must use Node-based MCPs? Or 2. 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) <#2760 (comment)> 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 <#2760 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB4FDSLGQ3NZ6TXP4KYMIUD3R7EOJAVCNFSM6AAAAACE5WNLLWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTENZTGU4TENRTGY> . You are receiving this because you commented.Message ID: ***@***.***>