π—π€πˆ 𝐂𝐨𝐧𝐭𝐫𝐨π₯

OpenAI Codex App Installation and Configuration Quickstart (macOS / Windows)

Posted March 4, 2026 by XAI Tech Team ‐ 5Β min read

This guide is based on official OpenAI documentation and is designed to help general users install and configure Codex App as quickly as possible. All information was verified against official docs on 2026-03-05.

Quick Summary (1 Minute)

  1. macOS: Download the .dmg package and follow this guide's configuration steps to start using Codex App quickly.
  2. Windows: Install from Microsoft Store. PowerShell works by default; if your workflow depends on Linux tooling, switch the Agent to WSL.
  3. Config file: The core setup is in ~/.codex/config.toml, with optional project overrides in .codex/config.toml.
  4. Recommended flow: Configure ~/.codex/config.toml and XAI_API_KEY first, then open your project and start. Use in-app sign-in only when a custom provider/key is not configured.

Official Support and Plans

According to the official Codex App docs:

  1. Codex App supports macOS (Apple Silicon) and Windows.
  2. ChatGPT Plus / Pro / Business / Edu / Enterprise plans include Codex capabilities.

1) macOS Installation and First Use

1. Download and Install

Official macOS download link:

Open the downloaded file and drag Codex to Applications.

If you have already configured ~/.codex/config.toml and set XAI_API_KEY, you can usually open a project and start directly without choosing an extra sign-in flow in the app.

If a custom provider/key is not configured, follow the official login flow with a ChatGPT account or an OpenAI API key.

3. Select a Project Folder

After launch, choose the code repository folder you want Codex to work on.

4. Send Your First Prompt

Keep the target in Local mode and start with tasks like:

  • "Explain this repository structure."
  • "Find likely issues and suggest fixes."
  • "Add tests for this function."

2) Windows Installation and First Use

1. Install from Microsoft Store

Official Windows entry:

2. Update Method

The official recommendation is to update through Microsoft Store:

  1. Open Microsoft Store.
  2. Go to Downloads.
  3. Click Check for updates.

3. Default Runtime Mode

On Windows, Codex App uses Windows Native Agent by default:

  1. Commands run in PowerShell by default.
  2. The app uses Windows sandboxing.

If your development setup relies on Linux tooling (for example bash, GNU tools, Linux Node/Python ecosystems), switch the Agent to WSL.

Path in the app (per official docs):

  1. Open Settings.
  2. Find the Agent runtime mode.
  3. Switch from Windows Native to WSL.
  4. Restart the app to apply changes.

Note: Agent runtime and integrated shell can be configured independently. You can run the Agent in WSL while keeping the shell in PowerShell, or vice versa.

3) Understand config.toml in 1 Minute

Official configuration basics:

  1. User-level config: ~/.codex/config.toml
  2. Project-level config: <project>/.codex/config.toml
  3. Priority (high to low): CLI args > Profile > Project config > User config > System config > Built-in defaults

In practice: keep global defaults in ~/.codex/config.toml, and override per project when needed.

4) Example Configuration (Ready to Reuse)

Here is a practical example configuration:

model_provider = "xai"
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
model_reasoning_summary = "detailed"
model_verbosity = "high"
approval_policy = "never"
sandbox_mode = "danger-full-access"

[model_providers.xai]
name = "xai"
base_url = "https://api.xairouter.com"
wire_api = "responses"
requires_openai_auth = false
env_key = "XAI_API_KEY"

Key Fields Explained

  1. model_provider / model: Choose provider and default model.
  2. approval_policy: Whether high-risk operations require your confirmation.
  3. sandbox_mode: Permission boundary for local command execution.
  4. base_url: Provider API endpoint.
  5. env_key: The environment variable name used for your API key.

Security Recommendation (For General Users)

This example uses high-permission settings:

  • approval_policy = "never"
  • sandbox_mode = "danger-full-access"

For safer defaults, use:

approval_policy = "on-request"
sandbox_mode = "workspace-write"

5) Environment Variable Setup (XAI_API_KEY)

Because the example uses:

env_key = "XAI_API_KEY"

Your system needs XAI_API_KEY.

macOS / Linux

macOS uses zsh by default, so write to ~/.zshrc first:

echo 'export XAI_API_KEY="your_key"' >> ~/.zshrc
source ~/.zshrc

If you are on Linux with bash, use ~/.bashrc:

echo 'export XAI_API_KEY="your_key"' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell)

Current session:

$env:XAI_API_KEY = "your_key"

Persist it for your user:

setx XAI_API_KEY "your_key"

Reopen terminal/app after setting it.

6) Common GUI Settings

1. Default Open-In Editor

You can set a default editor in settings (VS Code / Visual Studio / others).

2. Integrated Shell

Common options on Windows: PowerShell, Command Prompt, Git Bash, WSL.

Note: Shell changes usually apply to new sessions. Restart the app if needed.

7) Quick Troubleshooting

1. PowerShell Execution Policy Error

A common fix from official docs:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

2. Git Not Available on Windows

Install native Git first:

winget install Git.Git

3. Fast Environment Validation

Run these tasks in the app to confirm things are working:

  1. "Explain this repository structure."
  2. "Run a safe command and explain output (for example git status)."
  3. "Modify a small function and summarize the changes."
  1. Codex App overview: https://developers.openai.com/codex/app/
  2. Windows page: https://developers.openai.com/codex/app/windows/
  3. App settings: https://developers.openai.com/codex/app/settings/
  4. Configuration basics: https://developers.openai.com/codex/config-basic
  5. Authentication and sign-in: https://developers.openai.com/codex/auth
  6. macOS download (official): https://persistent.oaistatic.com/codex-app-prod/Codex.dmg
  7. Windows download (official store): https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US