OpenAI Codex Provider

Setup

Appam's Codex provider uses ChatGPT OAuth credentials against the Codex backend. You can either provide a bearer token explicitly or let Appam read and refresh credentials from its local auth cache.

export OPENAI_CODEX_MODEL="gpt-5.5"                    # optional
export OPENAI_CODEX_ACCESS_TOKEN="eyJ..."              # optional explicit token
export OPENAI_CODEX_AUTH_FILES="$HOME/.appam/one.json:$HOME/.appam/two.json" # optional pool
export OPENAI_CODEX_AUTH_FILE="$HOME/.appam/auth.json" # optional auth cache override

If OPENAI_CODEX_ACCESS_TOKEN is unset, Appam first checks the platform-separated auth-file list in OPENAI_CODEX_AUTH_FILES. Otherwise it looks for an openai-codex OAuth entry in OPENAI_CODEX_AUTH_FILE. Every auth file retains the existing schema and independent refresh lock.

Construction

Agent::quick() auto-detects the provider from openai-codex/... model strings:

use appam::prelude::*;

let agent = Agent::quick(
    "openai-codex/gpt-5.5",
    "You are a helpful coding assistant.",
    vec![],
)?;

For explicit configuration, use LlmProvider::OpenAICodex:

use appam::prelude::*;

let agent = AgentBuilder::new("codex-agent")
    .provider(LlmProvider::OpenAICodex)
    .model("gpt-5.5")
    .system_prompt("You are a helpful coding assistant.")
    .build()?;

Authentication

The Codex provider resolves auth in this order:

1. OpenAICodexConfig.access_token
2. OPENAI_CODEX_ACCESS_TOKEN
3. cached OAuth credentials in OPENAI_CODEX_AUTH_FILES
4. cached OAuth credentials in OPENAI_CODEX_AUTH_FILE

With multiple auth files, new client sessions select healthy credentials in round-robin order and remain sticky to that credential. A structured usage_limit_reached or usage_not_included response suppresses the exhausted slot for Retry-After, or for one hour when the provider supplies no reset hint, and retries the request with the next healthy credential. Network errors, server errors, and ordinary rate_limit_exceeded responses keep the normal same-account backoff policy.

For trusted local CLI workflows, use the example binary to trigger the browser login flow and persist credentials. Authenticate each pool path separately before enabling the full OPENAI_CODEX_AUTH_FILES list.

Reasoning

The provider reuses Appam's OpenAI reasoning and text verbosity controls:

use appam::prelude::*;

let agent = AgentBuilder::new("codex-reasoning")
    .provider(LlmProvider::OpenAICodex)
    .model("gpt-daybreak-blue-latest")
    .system_prompt("You are a reasoning assistant.")
    .openai_reasoning(ReasoningConfig::high_effort())
    .build()?;

The exact gpt-5.6-sol and gpt-daybreak-blue-latest models share configuration rules on the Codex subscription transport: their model-aware default remains high, explicit xhigh is supported, and sampling parameters are rejected. Appam preserves the selected model identifier in requests; unknown suffixed variants continue to use the generic capability rules.

Codex Fast mode is independent of reasoning effort. Request it with the shared OpenAI service-tier builder option:

let agent = AgentBuilder::new("codex-fast")
    .provider(LlmProvider::OpenAICodex)
    .model("gpt-5.6-sol")
    .system_prompt("You are a coding assistant.")
    .openai_service_tier(ServiceTier::Priority)
    .build()?;

This serializes service_tier: "priority" in the Codex request body.

Example Binary

cargo run --example coding-agent-openai-codex

The example will try cached auth first and fall back to an interactive ChatGPT login flow only when no usable Codex credential is available.