OpenAI Codex OAuth¶
Universal Agents can use llm.provider: openai-codex to call the Codex
Responses backend with ChatGPT/Codex OAuth credentials instead of an OpenAI API
key. The runtime does not need the codex binary for normal LLM calls; it needs
valid Codex OAuth auth material.
The Codex subscription backend supports llm.reasoning_effort and the optional
provider-generated llm.reasoning_summary (auto, concise, or detailed).
Universal Agents sends them as reasoning.effort and reasoning.summary.
For GPT-5 and o-series models, it also preserves the provider's complete
Responses output items between tool-loop turns, including encrypted reasoning
content. This keeps reasoning continuity without exposing reasoning text and
avoids Strands' unsupported reasoningContent replay path.
The backend does not accept the public Responses API's max_output_tokens or
temperature request parameters, so Universal Agents omits those two settings
for openai-codex and logs a warning naming them. The backend's model/server
output limit applies instead. If one exact Codex model explicitly rejects
reasoning.summary, the runtime records a model-scoped
reasoning_summary: null constraint in LLM_OVERRIDES.yaml, notifies the user,
rebuilds the model, and retries once; unrelated request failures never trigger
that repair.
Preferred credential flow:
- Create a dedicated file-backed Codex CLI home on the host.
- Sign in with
codex login --device-auth. - Mount that Codex home read-only into the container, or import it into the Universal Agents-owned auth store.
Treat auth.json as a secret. It contains access and refresh tokens.
macOS¶
Create a dedicated Codex CLI home:
export UA_CODEX_HOME="$PWD/.ua-codex-bootstrap"
mkdir -p "$UA_CODEX_HOME"
CODEX_HOME="$UA_CODEX_HOME" codex login --device-auth -c 'cli_auth_credentials_store="file"'
test -f "$UA_CODEX_HOME/auth.json"
Run with the file-backed Codex home mounted read-only:
export HOST_ROOT="$PWD/docker-instance"
export INSTANCE_ROOT="/data"
export BUILD_VER="team-assistant:latest"
docker run -it \
-v "$HOST_ROOT:$INSTANCE_ROOT" \
-v "$UA_CODEX_HOME:/codex-home:ro" \
--name ua \
--rm \
-p 18090:18090 \
-p 18600:18600 \
-e NETWORK_PUBLIC_ORIGIN="http://localhost" \
-e INTERNAL_WEBSITE_PUBLIC_PORT=18090 \
-e SECURE_TOOL_BROKER_PUBLIC_PORT=8766 \
-e LLM_PROVIDER=openai-codex \
-e LLM_MODEL_ID=gpt-5.5 \
-e OPENAI_CODEX_SHARED_HOME=/codex-home \
"$BUILD_VER" run
For long-running agents, import the host Codex auth into the instance-owned auth store:
./.venv/bin/python assistant_cli.py openai-codex-import \
--config "$HOST_ROOT/instance_config.yaml" \
--codex-home "$UA_CODEX_HOME" \
--host-data-root "$HOST_ROOT" \
--container-data-root "$INSTANCE_ROOT"
Linux¶
Create a dedicated Codex CLI home:
export UA_CODEX_HOME="$PWD/.ua-codex-bootstrap"
mkdir -p "$UA_CODEX_HOME"
CODEX_HOME="$UA_CODEX_HOME" codex login --device-auth -c 'cli_auth_credentials_store="file"'
test -f "$UA_CODEX_HOME/auth.json"
Run with the file-backed Codex home mounted read-only:
export HOST_ROOT="$PWD/docker-instance"
export INSTANCE_ROOT="/data"
export BUILD_VER="team-assistant:latest"
docker run -it \
-v "$HOST_ROOT:$INSTANCE_ROOT" \
-v "$UA_CODEX_HOME:/codex-home:ro" \
--name ua \
--rm \
-p 18090:18090 \
-p 18600:18600 \
-e NETWORK_PUBLIC_ORIGIN="http://localhost" \
-e INTERNAL_WEBSITE_PUBLIC_PORT=18090 \
-e SECURE_TOOL_BROKER_PUBLIC_PORT=8766 \
-e LLM_PROVIDER=openai-codex \
-e LLM_MODEL_ID=gpt-5.5 \
-e OPENAI_CODEX_SHARED_HOME=/codex-home \
"$BUILD_VER" run
Import for durable refresh inside the Universal Agents instance:
./.venv/bin/python assistant_cli.py openai-codex-import \
--config "$HOST_ROOT/instance_config.yaml" \
--codex-home "$UA_CODEX_HOME" \
--host-data-root "$HOST_ROOT" \
--container-data-root "$INSTANCE_ROOT"
Windows PowerShell¶
Create a dedicated Codex CLI home:
$UaCodexHome = Join-Path (Get-Location) ".ua-codex-bootstrap"
New-Item -ItemType Directory -Force -Path $UaCodexHome | Out-Null
$env:CODEX_HOME = $UaCodexHome
codex login --device-auth -c 'cli_auth_credentials_store="file"'
Test-Path (Join-Path $UaCodexHome "auth.json")
Remove-Item Env:\CODEX_HOME
Run with the file-backed Codex home mounted read-only:
$HostRoot = Join-Path (Get-Location) "docker-instance"
$InstanceRoot = "/data"
$BuildVer = "team-assistant:latest"
docker run -it `
-v "${HostRoot}:${InstanceRoot}" `
-v "${UaCodexHome}:/codex-home:ro" `
--name ua `
--rm `
-p 18090:18090 `
-p 18600:18600 `
-e NETWORK_PUBLIC_ORIGIN="http://localhost" `
-e INTERNAL_WEBSITE_PUBLIC_PORT=18090 `
-e SECURE_TOOL_BROKER_PUBLIC_PORT=8766 `
-e LLM_PROVIDER=openai-codex `
-e LLM_MODEL_ID=gpt-5.5 `
-e OPENAI_CODEX_SHARED_HOME=/codex-home `
"$BuildVer" run
Import for durable refresh inside the Universal Agents instance:
.\.venv\Scripts\python.exe assistant_cli.py openai-codex-import `
--config (Join-Path $HostRoot "instance_config.yaml") `
--codex-home $UaCodexHome `
--host-data-root $HostRoot `
--container-data-root $InstanceRoot
Auth Store Choices¶
Read-only mount:
- Use
OPENAI_CODEX_SHARED_HOME=/codex-home. - Mount the host Codex home read-only.
- Universal Agents reads
/codex-home/auth.json. - Universal Agents never refreshes or rewrites that shared Codex CLI auth file.
- Refresh the file by running Codex CLI on the host again.
Instance-owned import:
- Use
assistant_cli.py openai-codex-import. - The imported store defaults to
<instance_root>/auth/openai_codex_auth.jsoninside the container. - When importing from the host for a Docker instance, pass
--host-data-rootand--container-data-rootso/data/auth/openai_codex_auth.jsonmaps back to the host-mounted directory. - Universal Agents can refresh this copied store without racing the desktop Codex CLI.
- A Codex refresh token works only once, so agents, onboarding and
assistant_cli.pyrefresh or import this store only while holding its lock (openai_codex_auth.json.lockbeside it). If the lock cannot be taken, the request stops with an error that names the lock file instead of refreshing unlocked.
Access token:
- Use
OPENAI_CODEX_ACCESS_TOKENorOPENAI_CODEX_ACCESS_TOKEN_FILEfor short-lived automation. CODEX_ACCESS_TOKENandCODEX_ACCESS_TOKEN_FILEare accepted as Codex CLI compatibility aliases for this provider.- Prefer secret files over inline environment variables for persistent Docker deployments.
- Codex access tokens are created from the ChatGPT workspace Access tokens page when your Business or Enterprise workspace allows Codex access-token creation. Copy the generated token once, store it as a secret, and rotate it on the same schedule as other automation credentials.
Docker secret-file example:
docker run -it \
-v "$HOST_ROOT:$INSTANCE_ROOT" \
-v "$PWD/secrets/codex_access_token:/run/secrets/codex_access_token:ro" \
-e OPENAI_CODEX_ACCESS_TOKEN_FILE=/run/secrets/codex_access_token \
-e LLM_PROVIDER=openai-codex \
-e LLM_MODEL_ID=gpt-5.5 \
"$BUILD_VER" run
Verify¶
From the host:
./.venv/bin/python assistant_cli.py openai-codex-status \
--config "$HOST_ROOT/instance_config.yaml" \
--host-data-root "$HOST_ROOT" \
--container-data-root "$INSTANCE_ROOT"
Inside a running container:
docker exec ua python -m assistant_cli openai-codex-status --config /data/instance_config.yaml
Common Problems¶
Unsupported parameter: max_output_tokensortemperature: upgrade to a Universal Agents version that filters unsupportedopenai-codexrequest settings. Removing the configured values is an immediate workaround, but the provider-specific filter is the durable fix because generic defaults can otherwise restore them.auth.jsonis missing: the Codex CLI probably used the OS keychain. Run the login command withCODEX_HOME=<dedicated-dir>and-c 'cli_auth_credentials_store="file"'.- Import writes to
/data/...on the host: pass--host-data-rootand--container-data-root, or pass a host--auth-store-path. - Mounted shared auth expires: refresh it with the host Codex CLI, or import into the Universal Agents-owned auth store for long-running agents.
- "The OpenAI Codex sign-in store could not be locked" (code
openai_codex_auth_store_lock_unavailable): the store's folder must be writable and on a file system that supports file locks; a local disk does, some network and synced folders do not. Nothing was refreshed or imported. Signing in again will not help until the folder is fixed. - Windows volume paths fail: use PowerShell
${Variable}syntax before the colon in-v "${HostRoot}:${InstanceRoot}".