gpt-codex-client

OpenAI SDK-style Python client for ChatGPT/Codex OAuth-backed workflows.

English · 简体中文 · PyPI · Docs

gpt-codex-client is an OpenAI SDK-style Python client for ChatGPT/Codex OAuth-backed workflows. It is intentionally not an API-key client for api.openai.com; it uses a local token cache compatible with ~/.codex/auth.json and requires an account that can access the relevant ChatGPT/Codex backend.

Install

uv add gpt-codex-client

Quick Start

from gpt_codex_client import CodexClient

with CodexClient(no_browser=True) as client:
    response = client.responses.create(
        model="gpt-5.5",
        input="Write a short Python function that reverses a string.",
    )
    print(response.output_text)

Highlights

• Responses-style sync and async clients with streaming support.
• Chat Completions compatibility for existing message/tool-call workflows.
• OAuth PKCE login, refresh tokens, and ~/.codex/auth.json token cache support.
• Model discovery from the public OpenAI Codex model registry.
• Optional Pydantic parsing for structured output.

List Models

client.models.list() reads the public OpenAI Codex model registry from the openai/codex GitHub repository instead of the ChatGPT/Codex backend /models endpoint.

from gpt_codex_client import CodexClient

with CodexClient() as client:
    models = client.models.list()
    for model in models:
        print(model.id)

The registry source is:

https://raw.githubusercontent.com/openai/codex/main/codex-rs/models-manager/models.json

Set GPT_CODEX_CLIENT_MODELS_MANIFEST_URL or pass models_manifest_url= to use another compatible registry.

Authentication

The client lazily authenticates on the first request. By default it reads and writes ~/.codex/auth.json with 0600 permissions.

from gpt_codex_client import login

login(no_browser=True)

The default OAuth client id follows the ChatGPT/Codex sign-in flow used by the official Codex clients. If OpenAI issues a different client id for your app, set GPT_CODEX_CLIENT_OAUTH_CLIENT_ID or pass auth_client_id= to CodexClient.

For automation, pass a login_handler that receives the authorization URL and returns the final redirect URL:

from gpt_codex_client import login

token = login(login_handler=lambda url: input(f"Open {url}\nRedirect URL: "))

Responses

with CodexClient() as client:
    response = client.responses.create(
        model="gpt-5.5",
        input="Summarize this repository.",
        reasoning={"effort": "medium"},
        text={"verbosity": "low"},
    )

Streaming returns a context manager and iterator:

with CodexClient() as client:
    with client.responses.create(model="gpt-5.5", input="Say hi", stream=True) as stream:
        for event in stream:
            if event.type == "response.output_text.delta":
                print(event.data.get("delta"), end="")

Structured Output

Install the optional extra when using Pydantic models:

uv add "gpt-codex-client[pydantic]"

from pydantic import BaseModel
from gpt_codex_client import CodexClient

class Result(BaseModel):
    title: str

parsed = CodexClient().responses.parse(
    model="gpt-5.5",
    input="Return JSON with a title.",
    text_format=Result,
)
print(parsed.parsed.title)

Chat Compatibility

The chat compatibility layer converts Chat Completions-style messages and function tools into Responses requests:

completion = CodexClient().chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello"}],
)
print(completion.choices[0].message.content)

Development

uv sync --all-extras --dev
uv run pytest -q

Protocol reliability (0.2.0)

Inference opening retries now honor max_retries for streamed and aggregated calls. Stream failures expose partial results through StreamError; EOF without a terminal event is an error. Chat tool calls use id/type/function format and include argument deltas and accurate finish reasons. Optional preserve_context retains opaque Codex context for same-model replay. See streaming, Chat migration, and native replay. Validation uses offline MockTransport fixtures, not live OAuth/Codex calls.