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.

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

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

Troubleshooting

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.