axio-transport-codex 0.8.0

ChatGPT (Codex) OAuth transport for Axio using Responses API

axio-transport-codex

ChatGPT OAuth transport for axio using the OpenAI Responses API.

Authenticates via the same OAuth2 PKCE flow used by the ChatGPT desktop client — no API key purchase required; your ChatGPT subscription covers usage. Implements the OpenAI Responses API (not the legacy chat completions endpoint).

Features

• No API key purchase — authenticates with your ChatGPT account via OAuth2 PKCE
• Responses API — uses OpenAI's newer Responses endpoint (/backend-api/codex/responses)
• Automatic token refresh — access tokens are silently refreshed before expiry; callers notified via on_auth_refresh
• Full streaming — incremental text, reasoning, and tool-call events via SSE
• Tool calling — works with all axio tool handlers; parallel tool calls enabled
• Retry logic — automatic backoff on 429 and 5xx responses; honours Retry-After header
• aiohttp-based — non-blocking I/O throughout

Installation

pip install axio-transport-codex

With the TUI settings screen (ChatGPT sign-in dialog):

pip install "axio-transport-codex[tui]"

Authentication

CodexTransport authenticates with ChatGPT using OAuth2 PKCE. The transport stores an access token (api_key), a refresh token, and an expiry timestamp. It refreshes the access token automatically when it is within 30 seconds of expiry.

Running the OAuth flow

Use run_oauth_flow() from axio_transport_codex.oauth to obtain tokens for the first time. It opens a browser window for ChatGPT sign-in and waits for the callback on http://localhost:1455/auth/callback.

import asyncio
from axio_transport_codex.oauth import run_oauth_flow
from axio_transport_codex import CodexTransport

async def main() -> None:
    tokens = await run_oauth_flow()
    # tokens = {
    #   "access_token": "...",
    #   "refresh_token": "...",
    #   "expires_at": "1234567890",   # Unix timestamp as string
    #   "account_id": "...",
    # }

    transport = CodexTransport(
        api_key=tokens["access_token"],
        refresh_token=tokens["refresh_token"],
        expires_at=tokens["expires_at"],
        account_id=tokens["account_id"],
    )

Persisting tokens across sessions

Pass an on_auth_refresh callback to receive updated credentials whenever the access token is refreshed. Save the returned dict to disk or a secrets store and restore it on the next run.

import json, pathlib, aiohttp
from axio_transport_codex import CodexTransport

CRED_FILE = pathlib.Path("~/.config/axio/codex.json").expanduser()

async def save_tokens(tokens: dict[str, str]) -> None:
    CRED_FILE.parent.mkdir(parents=True, exist_ok=True)
    CRED_FILE.write_text(json.dumps(tokens))

async def main() -> None:
    creds = json.loads(CRED_FILE.read_text()) if CRED_FILE.exists() else {}

    async with aiohttp.ClientSession() as session:
        transport = CodexTransport(
            api_key=creds.get("api_key", ""),
            refresh_token=creds.get("refresh_token", ""),
            expires_at=creds.get("expires_at", ""),
            account_id=creds.get("account_id", ""),
            session=session,
            on_auth_refresh=save_tokens,
        )
        # use transport with an Agent ...

Refreshing tokens manually

from axio_transport_codex.oauth import refresh_access_token

tokens = await refresh_access_token(refresh_token="...")
# tokens = {"access_token": ..., "refresh_token": ..., "expires_at": ..., "account_id": ...}

Usage

import asyncio
import aiohttp
from axio.agent import Agent
from axio.context import MemoryContextStore
from axio.events import TextDelta
from axio_transport_codex import CodexTransport, CODEX_MODELS

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        transport = CodexTransport(
            api_key="<your-chatgpt-access-token>",
            refresh_token="<your-refresh-token>",
            expires_at="<unix-timestamp-string>",
            account_id="<your-account-id>",
            model=CODEX_MODELS["gpt-4.1"],
            session=session,
        )
        agent = Agent(system="You are a helpful assistant.", tools=[], transport=transport)
        ctx = MemoryContextStore()
        async for event in agent.run_stream("Explain the Rust borrow checker.", ctx):
            if isinstance(event, TextDelta):
                print(event.delta, end="", flush=True)
        print()

asyncio.run(main())

The session parameter is required for streaming. Create an aiohttp.ClientSession in an async context and pass it to the transport.

Configuration reference

CodexTransport is a dataclass with the following fields:

Field	Type	Default	Description
name	str	"ChatGPT (Codex)"	Display name (used by TUI)
api_key	str	""	ChatGPT OAuth access token
refresh_token	str	""	OAuth refresh token for silent renewal
expires_at	str	""	Access token expiry as a Unix timestamp string
account_id	str	""	ChatGPT account/organisation ID (sent as ChatGPT-Account-ID header)
base_url	str	"https://chatgpt.com/backend-api/codex"	API base URL
model	ModelSpec	CODEX_MODELS["gpt-4.1"]	Active model
models	ModelRegistry	all CODEX_MODELS	Available models
session	aiohttp.ClientSession | None	None	HTTP session (required for streaming)
on_auth_refresh	Callable[[dict[str, str]], Awaitable[None]] | None	None	Callback invoked with fresh credentials after token refresh
max_retries	int	10	Maximum retry attempts on 429 / 5xx
retry_base_delay	float	5.0	Base delay in seconds for exponential backoff

Models

Model ID	Context	Max output	Capabilities
gpt-4.1	1,047,576	32,768	text, vision, tool use
gpt-4.1-mini	1,047,576	32,768	text, vision, tool use
gpt-4.1-nano	1,047,576	32,768	text, tool use
gpt-4o	128,000	16,384	text, vision, tool use
gpt-4o-mini	128,000	16,384	text, vision, tool use
o4-mini	200,000	100,000	text, reasoning, tool use
o3	200,000	100,000	text, reasoning, tool use
o3-mini	200,000	100,000	text, reasoning, tool use

The default model is gpt-4.1.

fetch_models()

await transport.fetch_models() queries the Codex /models endpoint for the list of models your account has access to. If the request fails or the account is not configured, it falls back to the built-in CODEX_MODELS registry. Models not found in the built-in registry are added with basic text and tool_use capabilities.

session and api_key must be set before calling fetch_models().

Plugin registration

When installed, this package registers itself via entry points so axio-tui discovers it automatically:

[project.entry-points."axio.transport"]
codex = "axio_transport_codex:CodexTransport"

[project.entry-points."axio.transport.settings"]
codex = "axio_transport_codex.tui:CodexSettingsScreen"

Part of the axio ecosystem

axio · axio-transport-openai · axio-transport-anthropic · axio-tui

License

MIT