claw-codex 0.2.0

Codex OAuth Python library with optional local OpenRouter-compatible server

Claw Codex Python Library + Local Server

Local tools for using Codex OAuth credentials (ChatGPT subscription) in two ways:

• As a reusable library for direct chat.completions-style calls.
• As a local FastAPI server with OpenRouter-like endpoints and a demo UI.

This project is for local testing/investigation. Make sure usage complies with provider terms.

Install

pip install claw-codex

For local development:

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Library Quickstart (recommended for other projects)

from claw_codex import ClawCodexClient

client = ClawCodexClient()

# One-time auth flow
start = client.start_auth()
print(start.authorize_url)
client.exchange_code("PASTE_REDIRECT_URL_OR_CODE")

# OpenRouter-style chat call
resp = client.chat_completions(
    model="claw/codex",
    messages=[
        {"role": "system", "content": "You are helpful."},
        {"role": "user", "content": "Say hello from Codex."},
    ],
)
print(resp["choices"][0]["message"]["content"])

CLI Authentication and Chat

• Start server (existing behavior):
  • claw-codex
• Interactive CLI auth:
  • claw-codex auth login --open-browser
• Check auth state:
  • claw-codex auth status
• Exchange pasted redirect URL/code:
  • claw-codex auth exchange 'http://localhost:1455/auth/callback?code=...&state=...'
• Send a prompt via library client:
  • claw-codex chat "Write a short haiku" --text-only

Credentials are stored in ~/.claw-codex/auth.json by default.

UI and Local Proxy

Run:

claw-codex serve

Then open:

• Demo UI: http://127.0.0.1:1455/demo
• Start auth via API: POST /auth/codex/start
• Chat endpoint: POST /v1/chat/completions

Test Mode (no real OAuth)

CLAW_CODEX_MOCK=1 pytest

Testing

pytest

Publishing

Release instructions for GitHub + PyPI are in docs/PUBLISHING.md. Library API details and streaming examples are in docs/LIBRARY.md. Before publishing, update URLs in pyproject.toml to your real GitHub repository.