Documentation 2026-05-29 18:58 UTC to 2026-05-30 07:08 UTC

21| | Clear the terminal | `Ctrl` + `L` |21| | Clear the terminal | `Ctrl` + `L` |

22| **Thread** | | |22| **Thread** | | |

23| | New thread | `Cmd` + `N` or `Cmd` + `Shift` + `O` |23| | New thread | `Cmd` + `N` or `Cmd` + `Shift` + `O` |

24| | Search threads | `Cmd` + `G` |

24| | Find in thread | `Cmd` + `F` |25| | Find in thread | `Cmd` + `F` |

25| | Previous thread | `Cmd` + `Shift` + `[` |26| | Previous thread | `Cmd` + `Shift` + `[` |

26| | Next thread | `Cmd` + `Shift` + `]` |27| | Next thread | `Cmd` + `Shift` + `]` |

30You can search by command name or switch the search field into keystroke mode31You can search by command name or switch the search field into keystroke mode

31and press the shortcut you want to find.32and press the shortcut you want to find.

32 33 

34## Search past threads and find in a thread

35 

36Use thread search (`Cmd`/`Ctrl` + `G`) to reopen a

37past conversation. When expanded matching is available in your Codex desktop

38app, it can also match conversation content and Git branch names, so you can

39search for a phrase from the thread or a branch such as `fix/login-redirect`.

40 

41Use **Find in thread** (`Cmd` + `F`) after opening a thread

42to find text within that current conversation. It does not search across other

43threads.

44 

33## Slash commands45## Slash commands

34 46 

35Slash commands let you control Codex without leaving the thread composer. Available commands vary based on your environment and access.47Slash commands let you control Codex without leaving the thread composer. Available commands vary based on your environment and access.

13Use one Codex app window to run tasks across projects. Add a project for each13Use one Codex app window to run tasks across projects. Add a project for each

14codebase and switch between them as needed.14codebase and switch between them as needed.

15 15 

16When available in your Codex desktop app, you can ask Codex to manage threads

17in your local projects or worktrees. For example, ask it to find a related

18thread, continue an existing thread, or pin or archive a thread. To create a

19separate background thread, make that request explicit: `Create a separate background thread in a worktree for this project to update the tests.`

20 

16If you’ve used the [Codex CLI](https://developers.openai.com/codex/cli), a project is like starting a21If you’ve used the [Codex CLI](https://developers.openai.com/codex/cli), a project is like starting a

17session in a specific directory.22session in a specific directory.

18 23 

20 macOS/Linux install command20 macOS/Linux install command

21 21 

22 curl -fsSL https://chatgpt.com/codex/install.sh | shCopy22 curl -fsSL https://chatgpt.com/codex/install.sh | shCopy

23 

24 For unattended installs, set `CODEX_NON_INTERACTIVE=1` on the shell that runs the downloaded installer. See [Environment variables](https://developers.openai.com/codex/environment-variables#installer-variables) for details.

25 

26 macOS/Linux unattended install command

27 

28 curl -fsSL https://chatgpt.com/codex/install.sh | CODEX\_NON\_INTERACTIVE=1 shCopy

232. 2292. 2

24 30 

25 ### Run31 ### Run

141 141 

142#### Log directory142#### Log directory

143 143 

144Override where Codex writes local log files such as `codex-tui.log`.144Override where Codex writes local log files. Setting `log_dir` explicitly also

145enables the opt-in plaintext TUI log, `codex-tui.log`, in that directory.

145 146 

146```147```

147log_dir = "/absolute/path/to/codex-logs"148log_dir = "/absolute/path/to/codex-logs"

99| `hooks.<Event>[].hooks` | `array<table>` | Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped. |99| `hooks.<Event>[].hooks` | `array<table>` | Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped. |

100| `hooks.<Event>[].hooks[].commandWindows` | `string` | Windows-only command override for command hooks. The TOML alias `command_windows` is also accepted. |100| `hooks.<Event>[].hooks[].commandWindows` | `string` | Windows-only command override for command hooks. The TOML alias `command_windows` is also accepted. |

101| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |101| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

102| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |102| `log_dir` | `string (path)` | Directory where Codex writes log files; defaults to `$CODEX_HOME/log`. Setting this explicitly also enables the opt-in plaintext TUI log, `codex-tui.log`, in that directory. |

103| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |103| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |

104| `mcp_oauth_callback_url` | `string` | Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port. |104| `mcp_oauth_callback_url` | `string` | Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port. |

105| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |105| `mcp_oauth_credentials_store` | `auto | file | keyring` | Preferred store for MCP OAuth credentials. |

1217 1217 

1218Details1218Details

1219 1219 

1220Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.1220Directory where Codex writes log files; defaults to `$CODEX_HOME/log`. Setting this explicitly also enables the opt-in plaintext TUI log, `codex-tui.log`, in that directory.

1221 1221 

1222Key1222Key

1223 1223 

1138 1138 

1139# background_terminal_max_timeout = 300000 # ms; max empty write_stdin poll window (default 5m)1139# background_terminal_max_timeout = 300000 # ms; max empty write_stdin poll window (default 5m)

1140 1140 

1141# log_dir = "/absolute/path/to/codex-logs" # directory for Codex logs; default: "$CODEX_HOME/log"1141# log_dir = "/absolute/path/to/codex-logs" # log directory; setting explicitly enables codex-tui.log; default: "$CODEX_HOME/log"

1142 1142 

1143# sqlite_home = "/absolute/path/to/codex-state" # optional SQLite-backed runtime state directory1143# sqlite_home = "/absolute/path/to/codex-state" # optional SQLite-backed runtime state directory

1144 1144 

1# Environment variables – Codex

2 

3Codex uses `config.toml` for durable settings. Use environment variables for

4shell-scoped overrides, automation secrets, installer behavior, or diagnostics.

5 

6This page lists stable public environment variables that Codex reads directly.

7It does not list internal development variables, test variables, or

8provider-specific secret names you choose yourself with

9[`env_key`](https://developers.openai.com/codex/config-advanced#custom-model-providers).

10 

11## Core locations

12 

13| Variable | Used by | Default | Description |

14| --- | --- | --- | --- |

15| `CODEX_HOME` | CLI, IDE extension, app-server, installers | `~/.codex` | Sets the root for Codex state, including config, auth, logs, sessions, skills, and standalone package metadata. If you set it, the directory must already exist. |

16| `CODEX_SQLITE_HOME` | CLI and app-server state | `CODEX_HOME` | Sets where SQLite-backed state is stored. The `sqlite_home` config option takes precedence. Relative paths resolve from the current working directory. |

17 

18For more about the files stored under `CODEX_HOME`, see

19[Config and state locations](https://developers.openai.com/codex/config-advanced#config-and-state-locations).

20 

21## Installer variables

22 

23These variables apply to the standalone install scripts served from

24`https://chatgpt.com/codex/install.sh` and

25`https://chatgpt.com/codex/install.ps1`.

26 

27| Variable | Default | Description |

28| --- | --- | --- |

29| `CODEX_NON_INTERACTIVE` | `false` | Set to `1`, `true`, or `yes` to skip installer prompts. Prompts use their default response, so use this for scripted installs and updates, not first-run setup. |

30| `CODEX_INSTALL_DIR` | `~/.local/bin` on macOS/Linux; `%LOCALAPPDATA%\Programs\OpenAI\Codex\bin` on Windows | Changes where the visible `codex` command is installed. The standalone package cache still lives under `CODEX_HOME/packages/standalone`. |

31 

32For unattended installs, set `CODEX_NON_INTERACTIVE=1` on the shell that runs

33the downloaded installer:

34 

35```

36curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

37```

38 

39```

40$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

41```

42 

43## Authentication and network

44 

45| Variable | Used by | Description |

46| --- | --- | --- |

47| `CODEX_API_KEY` | `codex exec` | Provides an API key for a single non-interactive run. This is only supported in `codex exec`; set it inline rather than job-wide when running repository-controlled code. |

48| `CODEX_ACCESS_TOKEN` | CLI, app-server, trusted automation | Provides a ChatGPT or Codex access token for trusted automation. For persisted login, pipe it to `codex login --with-access-token`. |

49| `CODEX_CA_CERTIFICATE` | HTTPS, login, and WebSocket clients | Points to a PEM CA bundle for environments with corporate TLS interception or private root CAs. Takes precedence over `SSL_CERT_FILE`. |

50| `SSL_CERT_FILE` | HTTPS, login, and WebSocket clients | Fallback PEM CA bundle path when `CODEX_CA_CERTIFICATE` is unset. |

51 

52For provider API keys, set

53[`env_key`](https://developers.openai.com/codex/config-advanced#custom-model-providers) in the model provider

54configuration. Codex reads the variable named by that config, so the variable

55name itself is not a fixed Codex environment variable.

56 

57For automation secret handling, see

58[Use API key auth](https://developers.openai.com/codex/noninteractive#use-api-key-auth).

59For access token setup, see [Access tokens](https://developers.openai.com/codex/enterprise/access-tokens).

60 

61## Diagnostics

62 

63| Variable | Used by | Description |

64| --- | --- | --- |

65| `RUST_LOG` | CLI and app-server | Controls Rust log filtering and verbosity. `codex exec` defaults to `error` output unless you set a more verbose value. |

66 

67`RUST_LOG` accepts values such as `error`, `warn`, `info`, `debug`, and

68`trace`. It also accepts more targeted Rust logging filters, such as

69`codex_core=debug,codex_tui=debug`.

70 

71The interactive CLI records diagnostics in bounded local stores by default, but

72the plaintext `codex-tui.log` file is opt-in. Set `log_dir` explicitly when you

73need a plaintext log for troubleshooting:

74 

75```

76RUST_LOG=debug codex -c log_dir=./.codex-log

77tail -F ./.codex-log/codex-tui.log

78```

79 

80In non-interactive mode, `codex exec` prints messages inline instead of writing

81to a separate TUI log file.

82 

129 129 

130- Run `codex --ask-for-approval never "Summarize the current instructions."` from a repository root. Codex should echo guidance from global and project files in precedence order.130- Run `codex --ask-for-approval never "Summarize the current instructions."` from a repository root. Codex should echo guidance from global and project files in precedence order.

131- Use `codex --cd subdir --ask-for-approval never "Show which instruction files are active."` to confirm nested overrides replace broader rules.131- Use `codex --cd subdir --ask-for-approval never "Show which instruction files are active."` to confirm nested overrides replace broader rules.

132- Check `~/.codex/log/codex-tui.log` (or the most recent `session-*.jsonl` file if you enabled session logging) after a session if you need to audit which instruction files Codex loaded.132- To audit which instruction files Codex loaded, opt into a plaintext TUI log with `codex -c log_dir=./.codex-log` and check `./.codex-log/codex-tui.log`, or inspect the most recent `session-*.jsonl` file if you enabled session logging.

133- If instructions look stale, restart Codex in the target directory. Codex rebuilds the instruction chain on every run (and at the start of each TUI session), so there is no cache to clear manually.133- If instructions look stale, restart Codex in the target directory. Codex rebuilds the instruction chain on every run (and at the start of each TUI session), so there is no cache to clear manually.

134 134 

135## Troubleshoot discovery issues135## Troubleshoot discovery issues

90 powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"90 powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

91 ```91 ```

92 92 

93 For unattended installs, set `CODEX_NON_INTERACTIVE=1` on the shell that

94 runs the downloaded installer. See

95 [Environment variables](https://developers.openai.com/codex/environment-variables#installer-variables)

96 for details.

97 

98 ```

99 curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

100 ```

101 

102 ```

103 $env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

104 ```

105 

93 You can also install Codex CLI with npm or Homebrew:106 You can also install Codex CLI with npm or Homebrew:

94 107 

95 ```108 ```