Codex Provider — SCORPIOX CODE

Overview

The Codex provider connects scorpiox code to OpenAI's Codex backend via the ChatGPT backend API at chatgpt.com/backend-api/codex/responses. Authentication uses OAuth Bearer tokens fetched by scorpiox-codex-fetchtoken. All requests stream internally via SSE — this is an API requirement, not optional. The C implementation in sx_provider_codex.c maps scorpiox's model aliases (opus, sonnet, haiku) to GPT-5.x model identifiers.

Model Mapping

The C provider maps scorpiox's tier aliases to GPT-5.x model identifiers. The mapping is hardcoded in sx_provider_codex.c.

gpt-5.5

FLAGSHIP

Highest-capability GPT model. Deep reasoning, complex codegen, architectural analysis.

alias: opus

gpt-5.4

STANDARD

Balanced performance and cost. General-purpose coding, refactoring, reviews.

alias: sonnet

gpt-5.4-mini

MINI

Lightweight and fast. Quick edits, linting, simple Q&A. Lower cost per token.

alias: haiku

gpt-5.3-codex

LEGACY

Previous-generation Codex model. Still available for backwards compatibility.

—

gpt-5.2

LEGACY

Older GPT generation. Available for testing and regression comparisons.

—

codex-auto-review

REVIEW

Specialized model for automated code reviews. Read-only analysis, no code generation.

—

Authentication

The Codex provider uses OAuth Bearer token authentication. Tokens are fetched by scorpiox-codex-fetchtoken from one of four configurable sources. The C provider calls the token fetcher before each request and caches the result until expiration. Token auto-refresh is built in — if a request returns 401, the provider re-fetches the token and retries once.

# Auth header constructed by sx_provider_codex.c:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

# API endpoint (hardcoded in C source):
POST https://chatgpt.com/backend-api/codex/responses

Token Sources

tcp

TCP socket connection to token server. Default source. Fast, low-latency, production recommended.

http

HTTPS GET to CODEX_REMOTE_URL (default: token.scorpiox.net/codex). Simple webhook-style fetch.

ssh

SSH tunnel to remote host. Uses CODEX_SSH_HOST, CODEX_SSH_PORT, CODEX_SSH_USER, CODEX_SSH_PASS.

local

Read token from local file or environment variable. For development and testing only.

Supported Features

Feature support as defined in the C source sx_provider_codex.c:

📡

Streaming

Always-on SSE streaming. The Codex API requires streaming — all responses arrive as server-sent events.

🧠

Thinking

Extended reasoning blocks. Chain-of-thought content parsed from the SSE stream and rendered separately.

🔧

Tool Use

Tool calls via the scorpiox tool protocol. Responses include tool_use blocks with structured arguments.

⚡

Function Calling

Native OpenAI function calling format. Compatible with tools JSON schema definitions.

📊

Traffic Logging

Full request/response logging to disk. JSON files with sequence numbering for debugging and auditing.

🔄

Retry with Backoff

Automatic retry on transient failures (429, 500, 502, 503). Exponential backoff with jitter.

🔐

Token Auto-Refresh

Automatic token refresh on 401. The provider re-invokes scorpiox-codex-fetchtoken and retries.

📨

SSE Parsing

Built-in Server-Sent Events parser in C. Handles multi-line data fields, reconnection, and event types.

SSE Streaming

Unlike other providers where streaming is optional, the Codex API requires all requests to stream via Server-Sent Events (SSE). The C implementation in sx_provider_codex.c parses the SSE stream in real-time, extracting content deltas, thinking blocks, and tool calls as they arrive.

# SSE stream format from Codex API:

data: {"type":"response.output_text.delta","delta":"Hello"}
data: {"type":"response.output_text.delta","delta":" world"}
data: {"type":"response.thinking.delta","delta":"Let me analyze..."}
data: {"type":"response.function_call","name":"bash","arguments":"..."}
data: [DONE]

# The C SSE parser handles:
# - Multi-line data fields
# - UTF-8 streaming without buffering entire response
# - Graceful handling of connection drops
# - Event type routing (text, thinking, tool_call)

Configuration

All keys are set in scorpiox-env.txt. The provider reads these at startup from sx_config.c.

Key	Type	Default	Description
PROVIDER	string	scorpiox	Set to `codex` to activate this provider
CODEX_TOKEN_SOURCE	enum	tcp	Token fetch method: `local`, `http`, `ssh`, `tcp`
CODEX_REMOTE_URL	string	https://token.scorpiox.net/codex	Remote HTTP URL for token fetching (used when CODEX_TOKEN_SOURCE=http)
CODEX_SSH_HOST	string	—	SSH host for token fetching (used when CODEX_TOKEN_SOURCE=ssh)
CODEX_SSH_PORT	string	—	SSH port for token fetching
CODEX_SSH_USER	string	—	SSH username for token fetching
CODEX_SSH_PASS	string	—	SSH password for token fetching
MODEL	string	opus	Model tier alias. Maps to GPT-5.x: opus→gpt-5.5, sonnet→gpt-5.4, haiku→gpt-5.4-mini
TOOLS	string	all	Comma-separated tool list or `all` to enable all available tools

Quick Start

1. Switch to Codex provider

# In scorpiox-env.txt:
PROVIDER=codex
MODEL=opus
CODEX_TOKEN_SOURCE=tcp

2. Fetch your token

# Token is auto-fetched on first request, but you can test manually:
$ scorpiox-codex-fetchtoken
eyJhbGciOiJSUzI1NiIs...

# Or via HTTP source:
CODEX_TOKEN_SOURCE=http
CODEX_REMOTE_URL=https://token.scorpiox.net/codex

3. Start coding

# Interactive mode with Codex:
$ sx send "refactor this function to use async/await"

# Non-interactive query:
$ sx query "explain the memory layout of this struct"

# The provider handles all SSE parsing, tool execution,
# thinking extraction, and token refresh transparently.

Provider Comparison

Feature	Codex	Claude Code	OpenAI	Scorpiox Router
Streaming	✓ always-on SSE	✓ SSE	✗	✓ SSE
Thinking	✓	✓	✓	✓
Tool Use	✓	✓	✓	✓
Function Calling	✓	✗	✓	✗
Token Auto-Refresh	✓	✓	✗	✗
Traffic Logging	✓	✓	✓	✓
Auth Method	OAuth Bearer	OAuth Bearer	API Key	OAuth via Router
API Endpoint	chatgpt.com	api.anthropic.com	configurable	scorpiox.net:5175

Source Implementation

The Codex provider is implemented as a single C file with no external dependencies beyond the scorpiox core libraries. It implements the sx_provider interface used by all scorpiox providers.

// Source: scorpiox/libsxnet/sx_provider_codex.c
// API:    https://chatgpt.com/backend-api/codex/responses
// Auth:   OAuth Bearer (scorpiox-codex-fetchtoken)
// Stream: SSE (always-on, API requirement)

// Model mapping (hardcoded):
//   "opus"   → "gpt-5.5"
//   "sonnet" → "gpt-5.4"
//   "haiku"  → "gpt-5.4-mini"

// Token sources (CODEX_TOKEN_SOURCE):
//   "tcp"   → TCP socket to token server (default)
//   "http"  → HTTPS GET to CODEX_REMOTE_URL
//   "ssh"   → SSH tunnel via sshpass
//   "local" → Local file / env var

// Key functions:
//   sx_provider_codex_init()    — setup, read config
//   sx_provider_codex_send()    — build JSON, POST, parse SSE
//   sx_provider_codex_cleanup() — free resources