### Clone and Setup Development Environment

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Clone the repository, navigate into the directory, install dependencies, copy example environment variables, and edit them for your configuration. Finally, start the development server.

```bash
git clone https://github.com/GewoonJaap/codex-openai-wrapper.git
cd codex-openai-wrapper
npm install
cp .dev.vars.example .dev.vars
# Edit .dev.vars with your configuration
npm run dev
```

--------------------------------

### Example Environment Variables Configuration

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

This is an example of the `.dev.vars` file content. You need to replace placeholder values with your actual API keys and tokens.

```bash
# OpenAI API Configuration
OPENAI_API_KEY=your_api_key_here
CHATGPT_RESPONSES_URL=https://api.openai.com/v1/chat/completions

# Authentication
OPENAI_CODEX_AUTH={"tokens":{"access_token":"your_token","account_id":"your_account"}}

# Optional: Reasoning Configuration
REASONING_EFFORT=medium
REASONING_SUMMARY=auto
REASONING_COMPAT=think-tags

# Optional: Debugging
VERBOSE=false
DEBUG_MODEL=gpt-4
```

--------------------------------

### Copy Environment File Example

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Create a local environment file by copying the example configuration file. This file will store your API keys and other settings.

```bash
cp .dev.vars.example .dev.vars
```

--------------------------------

### Apply Patch Syntax Example

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/src/prompt.md

A full patch example demonstrating file addition, renaming, updating, and deletion within the patch envelope.

```text
**_ Begin Patch
_** Add File: hello.txt
+Hello world
**_ Update File: src/app.py
_** Move to: src/main.py
@@ def greet():
-print("Hi")
+print("Hello, world!")
**_ Delete File: obsolete.txt
_** End Patch
```

--------------------------------

### Production Environment File Example

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Example configuration for a production environment file. It sets the Node environment to production and includes necessary API credentials.

```bash
NODE_ENV=production
OPENAI_API_KEY=your_production_key
CHATGPT_RESPONSES_URL=https://api.openai.com/v1/chat/completions
OPENAI_CODEX_AUTH={"tokens":{"access_token":"prod_token","account_id":"prod_account"}}
REASONING_EFFORT=medium
VERBOSE=false
```

--------------------------------

### Install Dependencies and Deploy

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Install project dependencies and deploy the application to Cloudflare Workers. Use 'npm run dev' for local development.

```bash
# Install dependencies
npm install

# Deploy to Cloudflare Workers
npm run deploy

# Or run locally for development
npm run dev
```

--------------------------------

### Docker Compose for Development

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Clone the repository, copy example environment variables, edit them with your configuration, and start the Docker Compose services in detached mode.

```bash
git clone https://github.com/GewoonJaap/codex-openai-wrapper.git
cd codex-openai-wrapper
cp .dev.vars.example .dev.vars
# Edit .dev.vars with your configuration
docker-compose up -d
```

--------------------------------

### Start Codex CLI and Authenticate

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Start the Codex CLI and follow the prompts to sign in with ChatGPT. A ChatGPT Plus, Pro, or Team account is required. This process initiates a local server for authentication.

```bash
codex
```

--------------------------------

### Install OpenAI Codex CLI

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Install the OpenAI Codex CLI using npm or Homebrew. This is a prerequisite for obtaining OAuth2 credentials.

```bash
npm install -g @openai/codex
# Alternatively: brew install codex
```

--------------------------------

### Start Development Mode with Docker Compose

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Starts the service in development mode, enabling hot reloading. This is useful for making code changes and seeing them reflected without manual restarts.

```bash
# Start in development mode (default)
docker-compose up

# View logs
docker-compose logs -f codex-openai-wrapper
```

--------------------------------

### Example Tool Call with Fetch API

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Demonstrates how to make a tool call using the Fetch API in JavaScript. Ensure you include the correct API key and endpoint.

```javascript
const response = await fetch('/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk-your-api-key-here'
  },
  body: JSON.stringify({
    model: 'gpt-4',
    messages: [
      { role: 'user', content: 'What is the weather in Tokyo?' }
    ],
    tools: [
      {
        type: 'function',
        function: {
          name: 'get_weather',
          description: 'Get current weather information for a location',
          parameters: {
            type: 'object',
            properties: {
              location: {
                type: 'string',
                description: 'City name'
              },
              unit: {
                type: 'string',
                enum: ['celsius', 'fahrenheit'],
                description: 'Temperature unit'
              }
            },
            required: ['location']
          }
        }
      }
    ],
    tool_choice: 'auto'
  })
});
```

--------------------------------

### Available npm Scripts

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

A list of npm scripts to manage the project, including starting the development server, deploying, linting, formatting, running tests, and building the project.

```bash
npm run dev          # Start development server
```

```bash
npm run deploy       # Deploy to Cloudflare Workers  
```

```bash
npm run lint         # Run ESLint and TypeScript checks
```

```bash
npm run format       # Format code with Prettier
```

```bash
npm test            # Run test suite
```

```bash
npm run build       # Build the project
```

--------------------------------

### GET /v1/models

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Lists the available models supported by the wrapper.

```APIDOC
## GET /v1/models

### Description
Retrieves a list of models available through the wrapper.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- **object** (string) - The type of the response.
- **data** (array) - List of model objects.
```

--------------------------------

### Start Service with Docker Compose

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Launches the OpenAI Codex CLI wrapper service using Docker Compose. Ensure your `docker-compose.yml` and `.dev.vars` are correctly configured.

```bash
docker-compose up -d
```

--------------------------------

### Deploy Production Service

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Command to start the production service in detached mode.

```bash
docker-compose -f docker-compose.prod.yml up -d
```

--------------------------------

### Run Service with Pre-built Image

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Starts the OpenAI Codex CLI wrapper service in detached mode using a pre-built Docker image and the specified environment file.

```bash
# Create environment file
cp .dev.vars.example .dev.vars
# Edit .dev.vars with your configuration

# Run with pre-built image
docker run -d \
  --name codex-openai-wrapper \
  -p 8787:8787 \
  --env-file .dev.vars \
  ghcr.io/gewoonjaap/codex-openai-wrapper:latest
```

--------------------------------

### Reasoning output structure

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Example of the structured response format containing thinking content.

```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion.chunk",
  "created": 1708976947,
  "model": "gpt-4",
  "choices": [{
    "index": 0,
    "delta": {
      "content": "<think>\nLet me break this problem down step by step...\n</think>\n\nTo solve this equation..."
    },
    "finish_reason": null
  }]
}
```

--------------------------------

### GET /v1/models

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Retrieves a list of available models, including configured presets and reasoning effort levels.

```APIDOC
## GET /v1/models

### Description
Returns available models including all configured model presets with their reasoning effort levels.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- **object** (string) - The list type.
- **data** (array) - List of model objects.

#### Response Example
{
  "object": "list",
  "data": [
    {"id": "gpt-5", "object": "model", "owned_by": "owner"},
    {"id": "gpt-5-codex-high", "object": "model", "owned_by": "owner", "description": "Maximizes reasoning depth for complex problems", "reasoning_effort": "high"}
  ]
}
```

--------------------------------

### OpenAI SDK Chat Completion with Reasoning (Python)

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Example of using the OpenAI Python SDK to perform a chat completion with streaming enabled and custom reasoning parameters. Ensure your base URL and API key are correctly configured.

```python
from openai import OpenAI

# Initialize with your worker endpoint
client = OpenAI(
    base_url="https://your-worker.workers.dev/v1",
    api_key="sk-your-secret-api-key-here"
)

# Chat completion with reasoning
response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "system", "content": "You are a helpful coding assistant."},
        {"role": "user", "content": "Write a binary search algorithm in Python"}
    ],
    extra_body={
        "reasoning": {
            "effort": "high",
            "summary": "on"
        }
    },
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

--------------------------------

### List Models API Response

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Example JSON response when listing available models via the API.

```json
{
  "object": "list",
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "created": 1708976947,
      "owned_by": "openai-codex"
    }
  ]
}
```

--------------------------------

### Invoke apply_patch via Shell

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/src/prompt.md

Example of calling the apply_patch tool using a shell command with a formatted patch string.

```shell
shell {"command":["apply_patch","*** Begin Patch\n*** Add File: hello.txt\n+Hello, world!\n*** End Patch\n"]}
```

--------------------------------

### GET /health

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Performs a simple health check for monitoring purposes.

```APIDOC
## GET /health

### Description
Provides a simple health check for monitoring and load balancer configuration.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status.

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### cURL Ollama Chat

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Initiate a chat with an Ollama model using cURL. This example uses the /api/chat endpoint.

```bash
# Ollama chat
curl -X POST https://your-worker.workers.dev/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-secret-api-key-here" \
  -d '{
    "model": "llama2",
    "messages": [
      {"role": "user", "content": "Hello world!"}
    ]
  }'
```

--------------------------------

### OpenAI SDK Chat Completion Stream (JavaScript/TypeScript)

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Example of using the OpenAI JavaScript/TypeScript SDK to stream chat completions. Configure the baseURL and apiKey with your worker details.

```typescript
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://your-worker.workers.dev/v1',
  apiKey: 'sk-your-secret-api-key-here',
});

const stream = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'user', content: 'Explain async/await in JavaScript' }
  ],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || '';
  process.stdout.write(content);
}
```

--------------------------------

### Copy Credentials to Remote Server

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Transfer the `auth.json` file from your local machine to a remote server using `scp` for headless or remote server setups.

```bash
# Authenticate locally first, then copy the auth.json file
scp ~/.codex/auth.json user@remote:~/.codex/auth.json
```

--------------------------------

### Get Model Information

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Retrieve specific information about a model by sending a POST request with the model name. Authentication is required.

```http
POST /api/show
Authorization: Bearer sk-your-api-key-here
Content-Type: application/json

{
  "name": "llama2"
}
```

--------------------------------

### List Models API Request

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Send a GET request to the /v1/models endpoint to retrieve a list of available models. Requires authentication.

```http
GET /v1/models
Authorization: Bearer sk-your-api-key-here
```

--------------------------------

### Deploy with Docker

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Pull the pre-built image, configure environment variables, and run the container.

```bash
# Pull and run pre-built image
docker pull ghcr.io/gewoonjaap/codex-openai-wrapper:latest

# Create environment configuration
cat > .env << 'EOF'
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_CODEX_AUTH={"tokens":{"id_token":"...","access_token":"...","refresh_token":"...","account_id":"..."},"last_refresh":"..."}
CHATGPT_LOCAL_CLIENT_ID=app_EMoamEEZ73f0CkXaXp7hrann
CHATGPT_RESPONSES_URL=https://chatgpt.com/backend-api/codex/responses
REASONING_EFFORT=medium
EOF

# Run container
docker run -d \
  --name codex-openai-wrapper \
  -p 8787:8787 \
  --env-file .env \
  ghcr.io/gewoonjaap/codex-openai-wrapper:latest

# Test the deployment
curl http://localhost:8787/health
# {"status":"ok"}
```

--------------------------------

### Run Pre-built Image with Custom Configuration

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Runs the OpenAI Codex CLI wrapper using a pre-built image, mapping ports and loading custom environment variables from a file.

```bash
docker run -d \
  --name codex-wrapper \
  -p 8787:8787 \
  --env-file .dev.vars \
  ghcr.io/gewoonjaap/codex-openai-wrapper:latest
```

--------------------------------

### List Available Models

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Retrieves a list of all configured models and their reasoning effort levels.

```bash
# List available models
curl -X GET https://your-worker.workers.dev/v1/models \
  -H "Authorization: Bearer sk-your-api-key-here"
```

--------------------------------

### Configure Production Docker Compose

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Use these configurations to deploy the service. Option A uses a pre-built image, while Option B builds the image from source.

```yaml
version: '3.8'

services:
  codex-openai-wrapper:
    image: ghcr.io/gewoonjaap/codex-openai-wrapper:latest
    container_name: codex-openai-wrapper-prod
    ports:
      - "8787:8787"
    volumes:
      - codex_storage_prod:/app/.mf
    env_file:
      - .env.production
    restart: always
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8787/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

volumes:
  codex_storage_prod:
    driver: local
```

```yaml
version: '3.8'

services:
  codex-openai-wrapper:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        NODE_ENV: production
    container_name: codex-openai-wrapper-prod
    ports:
      - "8787:8787"
    volumes:
      - codex_storage_prod:/app/.mf
    env_file:
      - .env.production
    restart: always
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8787/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

volumes:
  codex_storage_prod:
    driver: local
```

--------------------------------

### Execute completion with reasoning

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Use the litellm completion method to trigger reasoning capabilities by passing an extra_body parameter.

```python
response = litellm.completion(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "Solve this step by step: What is 15 * 24?"}
    ],
    extra_body={
        "reasoning": {
            "effort": "medium",
            "summary": "auto"
        }
    },
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

--------------------------------

### Manage Containers

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Standard commands for stopping, restarting, and updating the service.

```bash
# Stop the service
docker-compose down

# Restart the service
docker-compose restart codex-openai-wrapper

# Update and restart
git pull
docker-compose down
docker-compose up -d --build
```

--------------------------------

### Configure Environment Variables

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Define required API keys, OAuth2 credentials, and optional settings in a .dev.vars or .env file.

```bash
# .dev.vars configuration file

# Required: API key for client authentication
OPENAI_API_KEY=sk-your-secret-api-key-here

# Required: OAuth2 credentials from Codex CLI (~/.codex/auth.json)
OPENAI_CODEX_AUTH={"tokens":{"id_token":"eyJ...","access_token":"sk-proj-...","refresh_token":"rft_...","account_id":"user-..."},"last_refresh":"2024-01-15T10:30:00.000Z"}

# Required: ChatGPT API configuration
CHATGPT_LOCAL_CLIENT_ID=app_EMoamEEZ73f0CkXaXp7hrann
CHATGPT_RESPONSES_URL=https://chatgpt.com/backend-api/codex/responses

# Optional: Ollama integration for local models
OLLAMA_API_URL=http://localhost:11434

# Optional: Default reasoning configuration
REASONING_EFFORT=medium      # minimal, low, medium, high
REASONING_SUMMARY=auto       # auto, on, off
REASONING_COMPAT=think-tags  # think-tags, standard, o3, legacy

# Optional: Debug settings
VERBOSE=false
DEBUG_MODEL=
```

--------------------------------

### Configure reasoning via environment variables

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Set global reasoning defaults using environment variables.

```bash
REASONING_EFFORT=high
REASONING_SUMMARY=on
REASONING_COMPAT=think-tags
```

--------------------------------

### Deploy to Cloudflare Workers

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Clone the repository, set up KV storage, configure secrets, and deploy.

```bash
# Clone and setup
git clone https://github.com/GewoonJaap/codex-openai-wrapper.git
cd codex-openai-wrapper
npm install

# Create KV namespace for token storage
wrangler kv namespace create "KV"
# Update wrangler.toml with the returned namespace ID

# Set secrets
wrangler secret put OPENAI_API_KEY
wrangler secret put OPENAI_CODEX_AUTH
wrangler secret put CHATGPT_LOCAL_CLIENT_ID
wrangler secret put CHATGPT_RESPONSES_URL

# Deploy
npm run deploy

# Local development
npm run dev
```

--------------------------------

### List Available Models

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Use this endpoint to retrieve a list of all available models supported by the wrapper. No authentication is required.

```http
GET /api/tags
Authorization: Bearer sk-your-api-key-here
```

--------------------------------

### Configure Environment Variable

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/authentication.md

Add the API key to your .dev.vars file or Cloudflare Workers environment.

```text
OPENAI_API_KEY=sk-your-openai-api-key-here
```

--------------------------------

### Build Docker Image from Source

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Builds the Docker image locally from the project's source code. This is useful if you need to make modifications to the application code.

```bash
# Build the Docker image
docker build -t codex-openai-wrapper .

# Run with custom configuration
docker run -d \
  --name codex-wrapper \
  -p 8787:8787 \
  --env-file .dev.vars \
  codex-openai-wrapper
```

--------------------------------

### Interact with OpenAI-Compatible Endpoints

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Use these commands to interact with the service using standard OpenAI API patterns.

```bash
# Chat completions
curl -X POST http://localhost:8787/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hello!"}]}'

# Text completions
curl -X POST http://localhost:8787/v1/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","prompt":"Complete this sentence:"}'

# List models
curl http://localhost:8787/v1/models
```

--------------------------------

### Adjust Memory Limits

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Configuration guidance for increasing memory allocation for Docker containers.

```bash
# Increase Docker memory limit
# Docker Desktop: Settings → Resources → Memory → Increase limit
# Linux: Edit /etc/docker/daemon.json
```

--------------------------------

### Interact with Ollama-Compatible Endpoints

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Use these commands to interact with the service using Ollama API patterns.

```bash
# Chat with Ollama format
curl -X POST http://localhost:8787/api/chat \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"llama2","messages":[{"role":"user","content":"Hello!"}]}'

# Show model details
curl -X POST http://localhost:8787/api/show \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"llama2"}'

# List available models
curl http://localhost:8787/api/tags
```

--------------------------------

### LiteLLM Integration Configuration

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Configure LiteLLM to use the wrapper as its OpenAI-compatible endpoint. Set the api_base and api_key according to your worker's details.

```python
import litellm

# Configure LiteLLM to use your worker
litellm.api_base = "https://your-worker.workers.dev/v1"
litellm.api_key = "sk-your-secret-api-key-here"
```

--------------------------------

### View Service Logs

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Commands for inspecting container logs for troubleshooting.

```bash
# View real-time logs
docker-compose logs -f codex-openai-wrapper

# View last 100 lines
docker-compose logs --tail=100 codex-openai-wrapper

# Filter error logs
docker-compose logs codex-openai-wrapper | grep ERROR
```

--------------------------------

### Resolve Build Failures

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Perform a clean build by removing existing containers and pruning the system cache.

```bash
# Clean build (remove cache)
docker-compose down
docker system prune -f
docker-compose up -d --build --force-recreate
```

--------------------------------

### Clone Repository for Source Build

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Clone the project repository if you plan to build the Docker image from source.

```bash
git clone https://github.com/GewoonJaap/codex-openai-wrapper.git
cd codex-openai-wrapper
```

--------------------------------

### Backup and Restore Data

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Commands to manage persistent data volumes using an Ubuntu container.

```bash
# Backup persistent data
docker run --rm -v codex_openai_wrapper_storage:/data -v $(pwd):/backup ubuntu tar czf /backup/codex-backup.tar.gz /data

# Restore persistent data
docker run --rm -v codex_openai_wrapper_storage:/data -v $(pwd):/backup ubuntu tar xzf /backup/codex-backup.tar.gz -C /
```

--------------------------------

### Chat Completion with Advanced Reasoning

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Configure reasoning effort levels and enable reasoning summaries for complex queries.

```bash
curl -X POST https://your-worker.workers.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "gpt-5",
    "messages": [
      {"role": "user", "content": "Solve step by step: What is the derivative of x^3 + 2x^2 - 5x + 3?"}
    ],
    "reasoning": {
      "effort": "high",
      "summary": "on"
    },
    "stream": false
  }'
```

--------------------------------

### Docker Deployment: Pull and Run Image

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Pull the latest Docker image and run it as a detached container. Ensure to create an environment file for API keys and authentication.

```bash
# Pull and run the latest image
docker pull ghcr.io/gewoonjaap/codex-openai-wrapper:latest

# Create environment file
echo "OPENAI_API_KEY=sk-your-api-key-here" > .env
echo "OPENAI_CODEX_AUTH={...your-auth-json...}" >> .env

# Run the container
docker run -d \
  --name codex-openai-wrapper \
  -p 8787:8787 \
  --env-file .env \
  ghcr.io/gewoonjaap/codex-openai-wrapper:latest
```

--------------------------------

### POST /v1/chat/completions

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Provides OpenAI-compatible chat completions with support for streaming, tool calling, and configurable reasoning.

```APIDOC
## POST /v1/chat/completions

### Description
Provides OpenAI-compatible chat completions with support for streaming, tool calling, and configurable reasoning.

### Method
POST

### Endpoint
/v1/chat/completions

### Request Body
- **model** (string) - Required - The model name (e.g., gpt-5)
- **messages** (array) - Required - List of message objects with role and content
- **stream** (boolean) - Optional - Enable real-time streaming via SSE
- **reasoning** (object) - Optional - Configuration for reasoning effort (effort: minimal|low|medium|high, summary: on|off)
- **tools** (array) - Optional - List of function definitions for tool calling
- **tool_choice** (string) - Optional - Control tool usage (e.g., auto)

### Request Example
{
  "model": "gpt-5",
  "messages": [
    {"role": "system", "content": "You are a helpful coding assistant."},
    {"role": "user", "content": "Explain how async/await works in JavaScript"}
  ],
  "stream": true
}

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the completion
- **choices** (array) - List of completion choices

#### Response Example
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Async/await is a way to..."
    },
    "finish_reason": "stop"
  }]
}
```

--------------------------------

### POST /v1/completions

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Provides legacy text completion support, accepting a prompt string and returning generated text.

```APIDOC
## POST /v1/completions

### Description
Provides legacy text completion support, accepting a prompt string and returning generated text. Supports both streaming and non-streaming modes.

### Method
POST

### Endpoint
/v1/completions
```

--------------------------------

### Integrate with TypeScript/JavaScript SDK

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Configure the OpenAI client to point to the wrapper's base URL and handle streaming chat completions.

```typescript
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://your-worker.workers.dev/v1',
  apiKey: 'sk-your-secret-api-key-here',
});

async function main() {
  // Streaming chat completion
  const stream = await openai.chat.completions.create({
    model: 'gpt-5-medium',
    messages: [
      { role: 'user', content: 'Explain async/await in JavaScript' }
    ],
    stream: true,
  });

  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content || '';
    process.stdout.write(content);
  }
}

main();
```

--------------------------------

### Integrate with Python SDK

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Configures the official OpenAI Python SDK to communicate with the wrapper, supporting streaming and custom body parameters.

```python
from openai import OpenAI

# Initialize client with worker endpoint
client = OpenAI(
    base_url="https://your-worker.workers.dev/v1",
    api_key="sk-your-secret-api-key-here"
)

# Chat completion with streaming and reasoning
response = client.chat.completions.create(
    model="gpt-5-high",  # Uses high reasoning effort preset
    messages=[
        {"role": "system", "content": "You are a helpful coding assistant."},
        {"role": "user", "content": "Write a binary search algorithm in Python with detailed explanation"}
    ],
    extra_body={
        "reasoning": {
            "effort": "high",
            "summary": "on"
        }
    },
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

--------------------------------

### Pull Pre-built Docker Image

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Use this command to pull the latest pre-built Docker image for the OpenAI Codex CLI wrapper.

```bash
docker pull ghcr.io/gewoonjaap/codex-openai-wrapper:latest
```

--------------------------------

### Tool Calling Request

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Define tools using JSON Schema to enable structured function calling capabilities.

```bash
curl -X POST https://your-worker.workers.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "gpt-5",
    "messages": [
      {"role": "user", "content": "What is the weather in Tokyo?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get current weather information for a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string", "description": "City name"},
              "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'
```

--------------------------------

### POST /v1/completions

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Generates text completions based on a provided prompt using the specified model.

```APIDOC
## POST /v1/completions

### Description
Generates text completions based on a provided prompt using the specified model.

### Method
POST

### Endpoint
/v1/completions

### Request Body
- **model** (string) - Required - The model ID to use.
- **prompt** (string) - Required - The input text prompt.
- **stream** (boolean) - Optional - Whether to stream the response.

### Request Example
{
  "model": "gpt-5",
  "prompt": "Write a Python function to calculate fibonacci numbers:",
  "stream": false
}

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the completion.
- **object** (string) - The object type.
- **created** (integer) - Timestamp of creation.
- **model** (string) - The model used.
- **choices** (array) - List of completion choices.

#### Response Example
{
  "id": "cmpl-abc123",
  "object": "text_completion",
  "created": 1708976947,
  "model": "gpt-5",
  "choices": [{
    "index": 0,
    "text": "def fibonacci(n):\n    if n <= 1:\n        return n\n    return fibonacci(n-1) + fibonacci(n-2)",
    "finish_reason": "stop",
    "logprobs": null
  }]
}
```

--------------------------------

### Debug authentication and token refresh

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Use these curl commands to verify authentication status and test token refresh functionality.

```bash
# Check authentication status
curl -X POST https://your-worker.workers.dev/debug/auth \
  -H "Authorization: Bearer sk-your-api-key-here"

# Test token refresh
curl -X POST https://your-worker.workers.dev/debug/refresh \
  -H "Authorization: Bearer sk-your-api-key-here"
```

--------------------------------

### Configure Wrangler.toml for KV Namespace

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Update your `wrangler.toml` file with the ID of the created KV namespace. This binds the namespace to your worker.

```toml
kv_namespaces = [
  { binding = "KV", id = "your-kv-namespace-id" }
]
```

--------------------------------

### Perform Text Completion Request

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Sends a POST request to the completions endpoint to generate text based on a prompt.

```bash
curl -X POST https://your-worker.workers.dev/v1/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "gpt-5",
    "prompt": "Write a Python function to calculate fibonacci numbers:",
    "stream": false
  }'
```

--------------------------------

### Force API Key Usage in Codex CLI

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Configure the Codex CLI to prioritize API key authentication over ChatGPT authentication by setting a configuration flag.

```bash
codex --config preferred_auth_method="apikey"
```

--------------------------------

### Basic Chat Completion Request

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Perform a standard chat completion request using the /v1/chat/completions endpoint with streaming enabled.

```bash
curl -X POST https://your-worker.workers.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "gpt-5",
    "messages": [
      {"role": "system", "content": "You are a helpful coding assistant."},
      {"role": "user", "content": "Explain how async/await works in JavaScript"}
    ],
    "stream": true
  }'
```

--------------------------------

### Configure Network Security

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Isolate the service by running it on a custom Docker network.

```bash
# Run on custom network
docker network create codex-network
docker-compose up -d
```

--------------------------------

### Codex CLI Credentials File Format

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

The `auth.json` file contains OAuth2 tokens and last refresh timestamp. Ensure this file is kept secure.

```json
{
  "tokens": {
    "id_token": "eyJhbGciOiJSUzI1NiIs...",
    "access_token": "sk-proj-...",
    "refresh_token": "rft_...",
    "account_id": "user-..."
  },
  "last_refresh": "2024-01-15T10:30:00.000Z"
}
```

--------------------------------

### Locate Codex CLI Credentials File

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Find the authentication credentials file generated by the Codex CLI. The location varies by operating system.

```bash
C:\Users\USERNAME\.codex\auth.json
```

```bash
~/.codex/auth.json
```

--------------------------------

### Create Cloudflare KV Namespace

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Create a new Cloudflare Workers KV namespace to cache tokens. This is a required step for deployment.

```bash
# Create a KV namespace for token caching
wrangler kv namespace create "KV"
```

--------------------------------

### Retrieve Ollama Model Information

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Fetches details for a specific model or lists all available Ollama models.

```bash
# Get model details
curl -X POST https://your-worker.workers.dev/api/show \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{"name": "llama2"}'

# List available Ollama models
curl -X GET https://your-worker.workers.dev/api/tags \
  -H "Authorization: Bearer sk-your-api-key-here"
```

--------------------------------

### Text Completions API Request

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Send a POST request to the /v1/completions endpoint for text generation tasks. Specify the model, prompt, and optionally max_tokens and stream.

```http
POST /v1/completions
Authorization: Bearer sk-your-api-key-here
Content-Type: application/json

{
  "model": "gpt-3.5-turbo-instruct",
  "prompt": "Write a Python function to calculate fibonacci numbers:",
  "max_tokens": 150,
  "stream": true
}
```

--------------------------------

### Set OpenAI API Key Environment Variable

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Alternatively, set your OpenAI API key as an environment variable for authentication. This is useful for API key-based authentication.

```bash
export OPENAI_API_KEY="your-api-key-here"
```

--------------------------------

### Fix Permission Errors

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Adjust file ownership and directory permissions to ensure the Docker daemon can access project files.

```bash
# Fix ownership issues
sudo chown -R $USER:$USER .
chmod -R 755 .
```

--------------------------------

### Resolve Port Conflicts

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Identify processes occupying the target port and reassign the container port mapping if necessary.

```bash
# Check what's using port 8787
lsof -i :8787

# Use different port
docker-compose up -d -p 8788:8787
```

--------------------------------

### Monitor Service Health

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Verify the service status using the health endpoint.

```bash
# Check service health
curl http://localhost:8787/health

# Expected response
{"status":"ok","timestamp":"2024-01-01T00:00:00.000Z"}
```

--------------------------------

### Handle Authentication Error Responses

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/authentication.md

JSON error responses returned when authentication fails or is missing.

```json
{
  "error": {
    "message": "Missing Authorization header"
  }
}
```

```json
{
  "error": {
    "message": "Invalid Authorization header format. Expected: Bearer <token>"
  }
}
```

```json
{
  "error": {
    "message": "Invalid API key"
  }
}
```

```json
{
  "error": {
    "message": "Server configuration error"
  }
}
```

--------------------------------

### Environment Variables for Cloudflare Workers

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Configure the `.dev.vars` file with necessary environment variables for your Cloudflare Worker deployment. This includes API keys, authentication details, and optional configurations.

```bash
# Required: API key for client authentication
OPENAI_API_KEY=sk-your-secret-api-key-here

# Required: Codex CLI authentication JSON
OPENAI_CODEX_AUTH={"tokens":{"id_token":"eyJ...","access_token":"sk-proj-...","refresh_token":"rft_...","account_id":"user-..."},"last_refresh":"2024-01-15T10:30:00.000Z"}

# Required: ChatGPT API configuration
CHATGPT_LOCAL_CLIENT_ID=your_client_id_here
CHATGPT_RESPONSES_URL=https://chatgpt.com/backend-api/codex/responses

# Optional: Ollama integration
OLLAMA_API_URL=http://localhost:11434

# Optional: Reasoning configuration
REASONING_EFFORT=medium
REASONING_SUMMARY=auto
REASONING_COMPAT=think-tags
```

--------------------------------

### POST /api/chat

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Interface for Ollama-compatible chat requests.

```APIDOC
## POST /api/chat

### Description
Sends a chat request to an Ollama-compatible backend.

### Method
POST

### Endpoint
/api/chat

### Request Body
- **model** (string) - Required - The Ollama model name.
- **messages** (array) - Required - List of message objects.

### Request Example
{
  "model": "llama2",
  "messages": [{"role": "user", "content": "Hello!"}]
}
```

--------------------------------

### cURL Chat Completion

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Perform a chat completion using cURL. Replace placeholders with your actual API key and desired model.

```bash
# Chat completion
curl -X POST https://your-worker.workers.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-secret-api-key-here" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "user", "content": "Explain machine learning"}
    ]
  }'
```

--------------------------------

### Perform Authenticated Requests

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/authentication.md

Use curl to send authenticated requests to the proxy endpoints.

```bash
curl -X POST https://your-worker.your-subdomain.workers.dev/v1/chat/completions \
  -H "Authorization: Bearer sk-your-openai-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

```bash
curl -X POST https://your-worker.your-subdomain.workers.dev/api/chat \
  -H "Authorization: Bearer sk-your-openai-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

--------------------------------

### Define Authorization Header

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/authentication.md

Include the API key in the Authorization header using the Bearer token format.

```text
Authorization: Bearer sk-your-openai-api-key-here
```

--------------------------------

### Configure Docker Secrets

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Use Docker secrets for sensitive information like API keys and tokens.

```yaml
# In docker-compose.prod.yml
services:
  codex-openai-wrapper:
    secrets:
      - openai_api_key
      - codex_auth_token

secrets:
  openai_api_key:
    file: ./secrets/openai_api_key.txt
  codex_auth_token:
    file: ./secrets/codex_auth.json
```

--------------------------------

### Chat Completions API Request

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Send a POST request to the /v1/chat/completions endpoint for chat-based interactions. Include the Authorization header and a JSON body with model and messages.

```http
POST /v1/chat/completions
Authorization: Bearer sk-your-api-key-here
Content-Type: application/json

{
  "model": "gpt-4",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user", 
      "content": "Explain quantum computing in simple terms"
    }
  ],
  "stream": true
}
```

--------------------------------

### Set Production Secrets

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Set production secrets using the wrangler CLI. These are required for secure API access.

```bash
wrangler secret put OPENAI_API_KEY
wrangler secret put OPENAI_CODEX_AUTH
wrangler secret put CHATGPT_LOCAL_CLIENT_ID
wrangler secret put CHATGPT_RESPONSES_URL
```

--------------------------------

### Port Forwarding for Remote Authentication

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Use SSH port forwarding to authenticate the Codex CLI on a headless or remote server by accessing the local authentication server URL from your local machine.

```bash
# From your local machine, create an SSH tunnel
ssh -L 1455:localhost:1455 user@remote-host

# Then run codex in the SSH session and open localhost:1455 locally
```

--------------------------------

### Pull Specific Version of Docker Image

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/docs/docker.md

Pulls a specific tagged version of the pre-built Docker image, useful for managing deployments and ensuring stability.

```bash
docker pull ghcr.io/gewoonjaap/codex-openai-wrapper:v1.0.0
```

--------------------------------

### Ollama Chat Request

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Sends a chat request using the Ollama-compatible API format.

```bash
# Ollama-style chat request
curl -X POST https://your-worker.workers.dev/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "llama2",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ],
    "stream": false
  }'
```

--------------------------------

### Service Information Endpoint

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Retrieve general service information. This endpoint does not require any authentication.

```http
GET /
```

--------------------------------

### POST /api/chat

Source: https://context7.com/gewoonjaap/codex-openai-wrapper/llms.txt

Provides Ollama-compatible chat functionality, translating messages and responses between formats.

```APIDOC
## POST /api/chat

### Description
Provides Ollama-compatible chat functionality, allowing integration with tools expecting the Ollama API format.

### Method
POST

### Endpoint
/api/chat

### Request Body
- **model** (string) - Required - The model name.
- **messages** (array) - Required - List of chat messages.
- **stream** (boolean) - Optional - Whether to stream the response.

### Request Example
{
  "model": "llama2",
  "messages": [
    {"role": "user", "content": "Hello, how are you?"}
  ],
  "stream": false
}

### Response
#### Success Response (200)
- **model** (string) - The model name.
- **message** (object) - The assistant's response message.

#### Response Example
{
  "model": "llama2",
  "message": {
    "role": "assistant",
    "content": "Hello! I am doing well, thank you for asking."
  }
}
```

--------------------------------

### Ollama Chat Interface API Request

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Send a POST request to the /api/chat endpoint for Ollama-compatible chat interactions. Include Authorization header and JSON body with model and messages.

```http
POST /api/chat
Authorization: Bearer sk-your-api-key-here
Content-Type: application/json

{
  "model": "llama2",
  "messages": [{"role": "user", "content": "Hello!"}],
  "stream": true
}
```

--------------------------------

### Advanced Reasoning API Request

Source: https://github.com/gewoonjaap/codex-openai-wrapper/blob/main/README.md

Utilize enhanced reasoning capabilities by including a 'reasoning' object in the request body. Specify 'effort' and 'summary' levels.

```json
{
  "model": "gpt-4",
  "messages": [
    {
      "role": "user", 
      "content": "Solve this step by step: What is the derivative of x^3 + 2x^2 - 5x + 3?"
    }
  ],
  "reasoning": {
    "effort": "high",
    "summary": "on"
  }
}
```