OpenAI Codex CLI Engine

OpenAI's official coding CLI agent, powered by GPT-4o. Codex CLI brings sandboxed code execution, three approval modes, and direct OPENAI_API_KEY integration to your QuantumReef workspace.

Last updated: 2025-01-15

Overview

OpenAI Codex CLI is a terminal-based AI coding agent that uses your OPENAI_API_KEY to access GPT-4o and related models. It can read files, write code, execute shell commands, and explain existing code — all from the command line. QuantumReef wraps Codex CLI via its JSON output mode, streaming results into the unified session UI.

A key differentiator is Codex CLI's sandbox execution mode, which runs shell commands inside an isolated environment (via macOS Seatbelt or Docker). This makes it safe to let the agent execute generated code during development without risk to the host system.

OpenAI API key required

Codex CLI requires a valid OPENAI_API_KEY. Usage is billed directly to your OpenAI account at standard API rates. GPT-4o is the recommended model for coding tasks.

Installation

Install Codex CLI

bash

# Install globally via npm
npm install -g @openai/codex

# Verify installation
codex --version

Set your API key

bash

# Set for the current session
export OPENAI_API_KEY=sk-proj-...

# Persist in your shell profile
echo 'export OPENAI_API_KEY=sk-proj-...' >> ~/.zshrc

# Optional: use a project-scoped .env file
echo 'OPENAI_API_KEY=sk-proj-...' > .env
# QuantumReef will load .env files automatically

Enable in QuantumReef

Navigate to Settings → Engines → Codex CLI and toggle on. QuantumReef will locate the codex binary in your PATH and validate your API key on first use.

Approval Modes

Codex CLI operates in one of three approval modes, which control how much autonomy the agent has to execute actions. QuantumReef lets you switch modes per session from the engine toolbar.

Codex CLI approval modes
Mode	Flag	Behaviour	Best for
Full-auto	--approval-mode full-auto	Executes all actions without prompting. Network and write access granted.	Trusted, well-scoped tasks in isolated environments
Suggest	--approval-mode suggest	Proposes actions and waits for approval before executing each one.	Default — good balance of autonomy and oversight
Manual	--approval-mode manual	Shows all planned actions upfront; user approves the entire plan before execution.	Sensitive codebases; when you want full review before any changes

Start with suggest mode

The suggest mode is the best default. It gives Codex autonomy for reads and lightweight writes while prompting before destructive operations like file deletion or network requests.

Sandbox Execution

Codex CLI's sandbox runs generated shell commands in an isolated environment, preventing accidental damage to the host filesystem or network. QuantumReef shows the sandbox status in the session header.

Platform	Sandbox Technology	Notes
macOS	Seatbelt (sandbox-exec)	Built-in, no Docker required. Fastest.
Linux	Docker container	Requires Docker Desktop or Engine installed
Windows (WSL2)	Docker container via WSL2	Requires Docker Desktop with WSL2 backend

bash

# Run Codex with sandbox enabled (default on macOS)
codex --sandbox "Write a script to process CSV files and run it"

# Disable sandbox (use with caution)
codex --no-sandbox "..."

# Specify a custom Docker image for the sandbox
codex --sandbox-image ubuntu:22.04 "..."

Configuration

Setting	Default	Description
Model	gpt-4o	OpenAI model. gpt-4o-mini is faster and cheaper for simple tasks.
Approval Mode	suggest	How much autonomy Codex has: full-auto, suggest, manual
Sandbox	true	Run shell commands in an isolated sandbox environment
Max Tokens	8192	Maximum output tokens per turn
Working Directory	Workspace root	Directory Codex operates within
Quiet Mode	false	Suppress intermediate output; show only final result

Example usage

bash

# Code generation
codex "Implement a debounce hook for SolidJS with TypeScript types"

# Code explanation
codex "Explain what this function does" --file src/lib/clawtopus-bridge.ts

# Full-auto refactoring task
codex --approval-mode full-auto   "Refactor all components in src/components/ to use named exports instead of default exports"

# Run with a specific model
codex --model gpt-4o-mini "Generate a .gitignore for a Next.js + Tauri project"

When to Choose Codex CLI

Use Case	Why Codex CLI Excels
OpenAI ecosystem teams	Direct GPT-4o access with no translation layer
Safe experimentation	Sandbox mode lets agents run generated code without risk
Code explanation	Strong natural-language explanations of complex logic
Quick one-off tasks	Minimal setup — just an API key and npm install
Windows/Linux environments	Docker sandbox works cross-platform unlike some alternatives