OpenAI Codex Adapter

Configuration for GPT-4o and o1 models, token/context limit management, mapping chat completions to task outputs, and cost reporting via the cost_events table.

The OpenAI Adapter

What you'll learn

Configure an OpenAI-backed agent, understand function calling support, and swap models between GPT-4o and GPT-3.5-turbo.

Configuration

{
  "adapter_type": "openai",
  "adapter_config": {
    "model":       "gpt-4o",
    "max_tokens":  2048,
    "temperature": 0.4,
    "api_key_env": "OPENAI_API_KEY",
    "timeout_ms":  45000
  }
}

Never put the key value directly in adapter_config — Paperclip reads the named environment variable at invocation time.

How the Adapter Calls the API

The OpenAI adapter uses the Chat Completions endpoint:

const response = await openai.chat.completions.create({
  model: config.model,
  messages: [
    { role: 'system',  content: task.systemPrompt },
    { role: 'user',    content: task.taskPrompt  }
  ],
  max_tokens:  config.max_tokens ?? 2048,
  temperature: config.temperature ?? 0.7,
});

Model Selection Guide

Model	Speed	Cost	Best for
`gpt-4o`	Medium	$$$	Complex reasoning, code, long context
`gpt-4o-mini`	Fast	$	Summarisation, classification
`gpt-3.5-turbo`	Fast	$	Simple text tasks, high volume
`o1-mini`	Slow	$$	Multi-step math, logic

For most Paperclip agents gpt-4o-mini offers the best cost/quality ratio.

Switching a Running Agent's Model

You can update adapter_config live without restarting:

curl -X PATCH http://localhost:3100/api/companies/${COMPANY_ID}/agents/${AGENT_ID} \
  -H "Content-Type: application/json" \
  -d '{"adapter_config": {"model": "gpt-4o-mini", "max_tokens": 1024}}'

Changes take effect on the next heartbeat tick.

Cost Tracking

The OpenAI adapter extracts usage.prompt_tokens and usage.completion_tokens from the API response and passes them to the cost ledger. Pricing per model is configured in packages/server/src/lib/costs/pricing.ts.

To add a new model's pricing:

// pricing.ts
export const PRICING: Record<string, TokenPricing> = {
  'gpt-4o':      { input: 0.005, output: 0.015 },  // per 1K tokens
  'gpt-4o-mini': { input: 0.00015, output: 0.0006 },
  // add new entries here
};

Checkpoint ✓

[ ] You can create an OpenAI-backed agent with a safe api_key_env reference
[ ] You understand how to choose between GPT-4o and GPT-4o-mini
[ ] You know how to update the model without restarting the server