Config File Locator

Codex config file locations

Commands use a POSIX shell (macOS, Linux, or WSL). Install the named editor or CLI first. Before using an environment-variable path, check that the variable is set to a non-empty, intended path. When using vi or Notepad, ensure the parent directory exists and is writable. A missing file is created when you save it; Notepad may ask to create it.

This page covers user and project configuration. CLI overrides take precedence, followed by trusted project files (closest to the working directory wins), a selected profile, user configuration, and system defaults. Project files cannot override some user-only settings, such as provider configuration. Managed requirements can restrict allowed values.

  1. Project level

    Project overrides

    Loaded only for trusted projects. Run commands from the project or subfolder containing this .codex directory.

    Config file location
    <project>/.codex/config.toml
    The file or its parent directory may not exist until you create project settings.
    Commands
    vi "./.codex/config.toml"

  2. User level

    User defaults

    Applies across projects. CODEX_HOME changes the user configuration directory.

    Config file location
    ~/.codex/config.toml
    Default when CODEX_HOME is unset. The first command edits this file.
    $CODEX_HOME/config.toml
    Used instead when CODEX_HOME is set. Use the second command only when this variable points to your configuration location. These are alternative paths for the same user settings.
    Commands
    vi "$HOME/.codex/config.toml"
    vi "$CODEX_HOME/config.toml"
Official Codex documentation