3f74f00295
## What changed - Mark `openai-codex` as stable and align its versioned runtime dependency with Codex CLI `0.144.4`. - Regenerate the Python protocol models and notification registry from that runtime, exposing the latest requests, responses, notifications, and schema fields. - Keep `ReasoningEffort` and `ThreadSource` as enum-style APIs while accepting unknown future wire values, and omit `last_turn_id` from the flat `thread_fork` helper. ## Testing - Cover stable SDK/runtime version matching, forward-compatible enum parsing, and generated client method signatures. GitOrigin-RevId: eaa616bcbfca4258f11274e12e7eefaa551110b7
3.9 KiB
Getting Started
This guide gets a published OpenAI Codex Python SDK installation running with a multi-turn thread.
1. Install
Install the SDK:
pip install openai-codex
Requirements:
- Python
>=3.10 - An existing Codex account session, or one of the login flows below
The SDK installs its matching openai-codex-cli-bin runtime dependency
automatically. SDK release versions track the corresponding Codex CLI release.
2. Authenticate When Needed
Existing Codex authentication is reused automatically. For ChatGPT browser login:
from openai_codex import Codex
with Codex() as codex:
login = codex.login_chatgpt()
print(login.auth_url)
print(login.wait().success)
For device-code login:
with Codex() as codex:
login = codex.login_chatgpt_device_code()
print(login.verification_url, login.user_code)
print(login.wait().success)
For API-key login:
with Codex() as codex:
codex.login_api_key("sk-...")
print(codex.account().account)
3. Run A Turn
from openai_codex import Codex, Sandbox
with Codex() as codex:
thread = codex.thread_start(sandbox=Sandbox.workspace_write)
result = thread.run("Say hello in one sentence.")
print("Thread:", thread.id)
print("Text:", result.final_response)
print("Items:", len(result.items))
Thread.run(...) starts a turn, waits for completion, and returns
TurnResult. Plain strings are shorthand for TextInput(...).
Use Thread.turn(...) when you need a TurnHandle for streaming, steering,
or interrupting an active turn.
4. Choose Sandbox Access
Use one enum for the initial thread and later turn overrides:
from openai_codex import Codex, Sandbox
with Codex() as codex:
thread = codex.thread_start(sandbox=Sandbox.workspace_write)
thread.run("Make the requested changes.")
review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)
Available presets:
Sandbox.read_only: read files without allowing writes.Sandbox.workspace_write: read files and write inside the workspace and configured writable roots; this is the normal default for workspace work.Sandbox.full_access: run without filesystem access restrictions.
When sandbox= is omitted, Codex uses its configured default. A turn override
also applies to subsequent turns on that thread.
5. Continue A Thread
from openai_codex import Codex
with Codex() as codex:
thread = codex.thread_start()
thread.run("Summarize Rust ownership in two bullets.")
result = thread.run("Now explain it to a Python developer.")
print(result.final_response)
To resume a stored thread later:
with Codex() as codex:
thread = codex.thread_resume("thr_123")
print(thread.run("Continue where we left off.").final_response)
6. Use The Async Client
import asyncio
from openai_codex import AsyncCodex, Sandbox
async def main() -> None:
async with AsyncCodex() as codex:
thread = await codex.thread_start(sandbox=Sandbox.workspace_write)
result = await thread.run("Continue where we left off.")
print(result.final_response)
asyncio.run(main())
7. Get Help
Python's built-in documentation tools cover the curated SDK surface:
import openai_codex
from openai_codex import Codex, CodexConfig
help(openai_codex)
help(Codex)
help(CodexConfig)
python -m pydoc openai_codex
Developing From This Repository
Contributors working from a checkout can install development dependencies from the repository:
cd sdk/python
uv sync --group dev
source .venv/bin/activate