Skip to main content

​
Overview

The Codex agent wraps the OpenAI Codex CLI via CodexAgentApi. Configure it through Spring properties under agent-client.codex.*. 
agent-client:
  codex:
    model: gpt-5-codex
    timeout: PT5M
    full-auto: true

​
Configuration Properties

Prefix: agent-client.codex
PropertyTypeDefaultDescription
modeAgentClientMode—Controls default permissiveness. Inherits from agent-client.mode if not set (default: LOOSE).
modelStringgpt-5-codexModel to use for Codex execution
timeoutDuration5mTimeout for agent task execution
full-autobooleantrueEnable full-auto mode (workspace-write sandbox + never approval)
skip-git-checkBoolean—Skip git repository check. When not explicitly set, derived from mode (see below).
reasoning-effortString—Model reasoning effort (model_reasoning_effort config override): minimal, low, medium, high, xhigh. Overrides the portable effort when both are set
executable-pathString—Path to the Codex CLI executable (auto-discovered if not set)

​
skipGitCheck and Mode Interaction

The skip-git-check property has special behavior — its effective value depends on AgentClientMode when not explicitly set:
skip-git-checkmodeEffective ValueBehavior
true (explicit)anytrueWorks in any directory
false (explicit)anyfalseRequires git repository
not setLOOSE (default)trueWorks in any directory
not setSTRICTfalseRequires git repository
Explicit always wins. Setting skip-git-check directly always overrides the mode-derived value. See Defaults Philosophy for the precedence rationale.

​
Why This Matters

Codex is the only provider that blocks execution in non-git directories by default. Without skipGitCheck=true, attempting to create a file in a temporary directory fails: 
Error: Not a git repository (or any of the parent directories)
The LOOSE mode (default) automatically resolves this, so users can start with Codex without hitting this wall.
Migration note (pre-0.14.0): Before the mode system, Codex required skip-git-check: true explicitly for non-git directories. With LOOSE mode (now the default), this is automatic. To restore the old behavior, set mode: strict or skip-git-check: false.

​
Full-Auto Mode

When full-auto=true (default), Codex runs with:
  • Workspace-write sandbox — can write files in the working directory
  • Never asks for approval — autonomous execution
agent-client:
  codex:
    full-auto: true   # Default — autonomous execution
The Codex CLI exec subcommand does not support --ask-for-approval. Only --full-auto and --sandbox control execution behavior.

​
Authentication

export OPENAI_API_KEY=sk-...
The Codex CLI requires an OpenAI API key via the OPENAI_API_KEY environment variable.