Skip to main content
OpenAI subscription is the first provider we support. More subscription providers will be added in future releases.
A ready-to-run example is available here!
Use your existing ChatGPT Plus or Pro subscription to access OpenAI’s Codex models without consuming API credits. The SDK handles OAuth authentication, credential caching, and automatic token refresh.

​
How It Works

1

​
Call subscription_login()

The LLM.subscription_login() class method handles the entire authentication flow:
from openhands.sdk import LLM

llm = LLM.subscription_login(vendor="openai", model="gpt-5.2-codex")
On first run, this opens your browser for OAuth authentication with OpenAI. After successful login, credentials are cached locally in ~/.openhands/auth/ for future use.
2

​
Use the LLM

Once authenticated, use the LLM with your agent as usual. The SDK automatically refreshes tokens when they expire.

​
Supported Models

The following models are available via ChatGPT subscription:
ModelDescription
gpt-5.2-codexLatest Codex model (default)
gpt-5.2GPT-5.2 base model
gpt-5.1-codex-maxHigh-capacity Codex model
gpt-5.1-codex-miniLightweight Codex model

​
Configuration Options

​
Force Fresh Login

If your cached credentials become stale or you want to switch accounts: 
llm = LLM.subscription_login(
    vendor="openai",
    model="gpt-5.2-codex",
    force_login=True,  # Always perform fresh OAuth login
)

​
Disable Browser Auto-Open

For headless environments or when you prefer to manually open the URL: 
llm = LLM.subscription_login(
    vendor="openai",
    model="gpt-5.2-codex",
    open_browser=False,  # Prints URL to console instead
)

​
Check Subscription Mode

Verify that the LLM is using subscription-based authentication: 
llm = LLM.subscription_login(vendor="openai", model="gpt-5.2-codex")
print(f"Using subscription: {llm.is_subscription}")  # True

​
Credential Storage

Credentials are stored securely in ~/.openhands/auth/. To clear cached credentials and force a fresh login, delete the files in this directory.

​
Ready-to-run Example

This example is available on GitHub: examples/01_standalone_sdk/35_subscription_login.py
examples/01_standalone_sdk/35_subscription_login.py
"""Example: Using ChatGPT subscription for Codex models.

This example demonstrates how to use your ChatGPT Plus/Pro subscription
to access OpenAI's Codex models without consuming API credits.

The subscription_login() method handles:
- OAuth PKCE authentication flow
- Credential caching (~/.openhands/auth/)
- Automatic token refresh

Supported models:
- gpt-5.2-codex
- gpt-5.2
- gpt-5.1-codex-max
- gpt-5.1-codex-mini

Requirements:
- Active ChatGPT Plus or Pro subscription
- Browser access for initial OAuth login
"""

import os

from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.file_editor import FileEditorTool
from openhands.tools.terminal import TerminalTool


# First time: Opens browser for OAuth login
# Subsequent calls: Reuses cached credentials (auto-refreshes if expired)
llm = LLM.subscription_login(
    vendor="openai",
    model="gpt-5.2-codex",  # or "gpt-5.2", "gpt-5.1-codex-max", "gpt-5.1-codex-mini"
)

# Alternative: Force a fresh login (useful if credentials are stale)
# llm = LLM.subscription_login(vendor="openai", model="gpt-5.2-codex", force_login=True)

# Alternative: Disable auto-opening browser (prints URL to console instead)
# llm = LLM.subscription_login(
#     vendor="openai", model="gpt-5.2-codex", open_browser=False
# )

# Verify subscription mode is active
print(f"Using subscription mode: {llm.is_subscription}")

# Use the LLM with an agent as usual
agent = Agent(
    llm=llm,
    tools=[
        Tool(name=TerminalTool.name),
        Tool(name=FileEditorTool.name),
    ],
)

cwd = os.getcwd()
conversation = Conversation(agent=agent, workspace=cwd)

conversation.send_message("List the files in the current directory.")
conversation.run()
print("Done!")
You can run the example code as-is.
The model name should follow the LiteLLM convention: provider/model_name (e.g., anthropic/claude-sonnet-4-5-20250929, openai/gpt-4o). The LLM_API_KEY should be the API key for your chosen provider.
ChatGPT Plus/Pro subscribers: You can use LLM.subscription_login() to authenticate with your ChatGPT account and access Codex models without consuming API credits. See the LLM Subscriptions guide for details.

​
Next Steps