smolagents-codex

Use a ChatGPT/Codex OAuth session as a smolagents.Model.

PyPI • Getting Started • Python Usage • Support Matrix • Troubleshooting

---

smolagents-codex is an unofficial external adapter that lets smolagents.CodeAgent call the ChatGPT Codex Responses backend through OAuth device-code login.

It does not fork smolagents, does not use the Codex CLI, does not require a Platform API key, and does not use LiteLLM or the OpenAI Python SDK.

Warning

This package talks to an internal ChatGPT/Codex transport, not the public OpenAI API. The backend can change without notice.

Features

• smolagents.Model implementation for CodeAgent
• OAuth device-code login against ChatGPT/Codex
• Access-token refresh with local credential storage
• Direct HTTPS/SSE transport to the Codex Responses backend
• Text-only message conversion for system, developer, user, assistant, and CodeAgent observation history
• Client-side stop-sequence trimming

Getting Started

Install from PyPI:

pip install smolagents-codex

Log in with device-code OAuth:

python -m smolagents_codex login

The command prints a verification URL and one-time code. Open the URL in a normal browser and enter the code only if you started the login.

Check or clear credentials:

python -m smolagents_codex status
python -m smolagents_codex logout

Important

No default model is hardcoded. Pass a model ID that your ChatGPT/Codex account can use. Model IDs are case-sensitive.

Python Usage

from smolagents import CodeAgent
from smolagents_codex import CodexOAuthModel

model = CodexOAuthModel(model_id="MODEL_ID")

agent = CodeAgent(
    tools=[],
    model=model,
    stream_outputs=False,
    use_structured_outputs_internally=False,
    max_steps=3,
)

print(agent.run("Calculate 17 * 23 and return the result."))

Run the bundled example:

export SMOLAGENTS_CODEX_MODEL=MODEL_ID
python examples/code_agent.py

python examples/code_agent.py MODEL_ID

Credentials

Set SMOLAGENTS_CODEX_HOME to choose the credential directory. Otherwise the package uses ~/.smolagents-codex/credentials.json.

Credential files are written with private Unix permissions where supported, but file permissions are not encryption.

Support Matrix

Area	Status
smolagents.CodeAgent	Supported
Blocking generate()	Supported
Text messages	Supported
OAuth device-code login	Supported
Access-token refresh	Supported
Public smolagents streaming	Not supported
ToolCallingAgent / native function calls	Not supported
Structured response_format	Not supported
Images, audio, video, files	Not supported
Codex server-side tools	Not supported
Codex CLI state	Not used

Troubleshooting

Symptom	Fix
Device auth disabled	Enable device-code authentication in ChatGPT security settings or ask a workspace admin.
401 after refresh	Run python -m smolagents_codex login.
403	Check workspace membership, RBAC, entitlements, and admin restrictions.
404	Check the model ID and whether the endpoint is available to your plan.
429	You hit ChatGPT/Codex plan or usage limits.
Timeout	Retry on a stable network.
Corporate proxy/custom CA	Use standard httpx environment settings such as HTTPS_PROXY, SSL_CERT_FILE, or SSL_CERT_DIR.
Malformed credential file	Run python -m smolagents_codex logout, then python -m smolagents_codex login.

Development

pip install -e '.[dev]'
ruff check .
mypy src/smolagents_codex
python -m build

Protocol details and upstream source commits are recorded in PROTOCOL.md. Re-check that file when Codex or smolagents changes.