OpenAI

OpenAI

OpenAI provides developer APIs for GPT models. Velaclaw supports two auth routes:

• API key — direct OpenAI Platform access with usage-based billing (openai/* models)
• Codex subscription — ChatGPT/Codex sign-in with subscription access (openai-codex/* models)

OpenAI explicitly supports subscription OAuth usage in external tools and workflows like Velaclaw.

Getting started

Choose your preferred auth method and follow the setup steps.

API key (OpenAI Platform)

Best for: direct API access and usage-based billing.

1. Get your API key

   Create or copy an API key from the OpenAI Platform dashboard.

2. Run onboarding

   velaclaw onboard --auth-choice openai-api-key
   

   Or pass the key directly:

   velaclaw onboard --openai-api-key "$OPENAI_API_KEY"
   
3. Verify the model is available

   velaclaw models list --provider openai
   

Route summary

Model ref	Route	Auth
openai/gpt-5.4	Direct OpenAI Platform API	OPENAI_API_KEY
openai/gpt-5.4-pro	Direct OpenAI Platform API	OPENAI_API_KEY

ChatGPT/Codex sign-in is routed through openai-codex/*, not openai/*.

Config example

{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}

Velaclaw does not expose openai/gpt-5.3-codex-spark on the direct API path. Live OpenAI API requests reject that model. Spark is Codex-only.

Codex subscription

Best for: using your ChatGPT/Codex subscription instead of a separate API key. Codex cloud requires ChatGPT sign-in.

1. Run Codex OAuth

   velaclaw onboard --auth-choice openai-codex
   

   Or run OAuth directly:

   velaclaw models auth login --provider openai-codex
   
2. Set the default model

   velaclaw config set agents.defaults.model.primary openai-codex/gpt-5.4
   
3. Verify the model is available

   velaclaw models list --provider openai-codex
   

Route summary

Model ref	Route	Auth
openai-codex/gpt-5.4	ChatGPT/Codex OAuth	Codex sign-in
openai-codex/gpt-5.3-codex-spark	ChatGPT/Codex OAuth	Codex sign-in (entitlement-dependent)

This route is intentionally separate from openai/gpt-5.4. Use openai/* with an API key for direct Platform access, and openai-codex/* for Codex subscription access.

Config example

{
  agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
}

If onboarding reuses an existing Codex CLI login, those credentials stay managed by Codex CLI. On expiry, Velaclaw re-reads the external Codex source first and writes the refreshed credential back to Codex storage.

Context window cap

Velaclaw treats model metadata and the runtime context cap as separate values.

For openai-codex/gpt-5.4:

• Native contextWindow: 1050000
• Default runtime contextTokens cap: 272000

The smaller default cap has better latency and quality characteristics in practice. Override it with contextTokens:

{
  models: {
    providers: {
      "openai-codex": {
        models: [{ id: "gpt-5.4", contextTokens: 160000 }],
      },
    },
  },
}

Use contextWindow to declare native model metadata. Use contextTokens to limit the runtime context budget.

Image generation

The bundled openai plugin registers image generation through the image_generate tool.

Capability	Value
Default model	openai/gpt-image-1
Max images per request	4
Edit mode	Enabled (up to 5 reference images)
Size overrides	Supported
Aspect ratio / resolution	Not forwarded to OpenAI Images API

{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-1" },
    },
  },
}

See Image Generation for shared tool parameters, provider selection, and failover behavior.

Video generation

The bundled openai plugin registers video generation through the video_generate tool.

Capability	Value
Default model	openai/sora-2
Modes	Text-to-video, image-to-video, single-video edit
Reference inputs	1 image or 1 video
Size overrides	Supported
Other overrides	aspectRatio, resolution, audio, watermark are ignored with a tool warning

{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}

See Video Generation for shared tool parameters, provider selection, and failover behavior.

Personality overlay

Velaclaw adds a small OpenAI-specific prompt overlay for openai/* and openai-codex/* runs. The overlay keeps the assistant warm, collaborative, concise, and a little more emotionally expressive without replacing the base system prompt.

Value	Effect
"friendly" (default)	Enable the OpenAI-specific overlay
"on"	Alias for "friendly"
"off"	Use base Velaclaw prompt only

Config

{
  plugins: {
    entries: {
      openai: { config: { personality: "friendly" } },
    },
  },
}

CLI

velaclaw config set plugins.entries.openai.config.personality off

Values are case-insensitive at runtime, so "Off" and "off" both disable the overlay.

Voice and speech

Speech synthesis (TTS)

The bundled openai plugin registers speech synthesis for the messages.tts surface.

Setting	Config path	Default
Model	messages.tts.providers.openai.model	gpt-4o-mini-tts
Voice	messages.tts.providers.openai.voice	coral
Speed	messages.tts.providers.openai.speed	(unset)
Instructions	messages.tts.providers.openai.instructions	(unset, gpt-4o-mini-tts only)
Format	messages.tts.providers.openai.responseFormat	opus for voice notes, mp3 for files
API key	messages.tts.providers.openai.apiKey	Falls back to OPENAI_API_KEY
Base URL	messages.tts.providers.openai.baseUrl	https://api.openai.com/v1

Available models: gpt-4o-mini-tts, tts-1, tts-1-hd. Available voices: alloy, ash, ballad, cedar, coral, echo, fable, juniper, marin, onyx, nova, sage, shimmer, verse.

{
  messages: {
    tts: {
      providers: {
        openai: { model: "gpt-4o-mini-tts", voice: "coral" },
      },
    },
  },
}

Set OPENAI_TTS_BASE_URL to override the TTS base URL without affecting the chat API endpoint.

Realtime transcription

The bundled openai plugin registers realtime transcription for the Voice Call plugin.

Setting	Config path	Default
Model	plugins.entries.voice-call.config.streaming.providers.openai.model	gpt-4o-transcribe
Silence duration	...openai.silenceDurationMs	800
VAD threshold	...openai.vadThreshold	0.5
API key	...openai.apiKey	Falls back to OPENAI_API_KEY

Uses a WebSocket connection to wss://api.openai.com/v1/realtime with G.711 u-law audio.

Realtime voice

The bundled openai plugin registers realtime voice for the Voice Call plugin.

Setting	Config path	Default
Model	plugins.entries.voice-call.config.realtime.providers.openai.model	gpt-realtime
Voice	...openai.voice	alloy
Temperature	...openai.temperature	0.8
VAD threshold	...openai.vadThreshold	0.5
Silence duration	...openai.silenceDurationMs	500
API key	...openai.apiKey	Falls back to OPENAI_API_KEY

Supports Azure OpenAI via azureEndpoint and azureDeployment config keys. Supports bidirectional tool calling. Uses G.711 u-law audio format.

Advanced configuration

Transport (WebSocket vs SSE)

Velaclaw uses WebSocket-first with SSE fallback ("auto") for both openai/* and openai-codex/*.

In "auto" mode, Velaclaw:

• Retries one early WebSocket failure before falling back to SSE
• After a failure, marks WebSocket as degraded for ~60 seconds and uses SSE during cool-down
• Attaches stable session and turn identity headers for retries and reconnects
• Normalizes usage counters (input_tokens / prompt_tokens) across transport variants

Value	Behavior
"auto" (default)	WebSocket first, SSE fallback
"sse"	Force SSE only
"websocket"	Force WebSocket only

{
  agents: {
    defaults: {
      models: {
        "openai-codex/gpt-5.4": {
          params: { transport: "auto" },
        },
      },
    },
  },
}

Related OpenAI docs:

• Realtime API with WebSocket
• Streaming API responses (SSE)

WebSocket warm-up

Velaclaw enables WebSocket warm-up by default for openai/* to reduce first-turn latency.

// Disable warm-up
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: { openaiWsWarmup: false },
        },
      },
    },
  },
}

Fast mode

Velaclaw exposes a shared fast-mode toggle for both openai/* and openai-codex/*:

• Chat/UI: /fast status|on|off
• Config: agents.defaults.models["<provider>/<model>"].params.fastMode

When enabled, Velaclaw maps fast mode to OpenAI priority processing (service_tier = "priority"). Existing service_tier values are preserved, and fast mode does not rewrite reasoning or text.verbosity.

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": { params: { fastMode: true } },
        "openai-codex/gpt-5.4": { params: { fastMode: true } },
      },
    },
  },
}

Session overrides win over config. Clearing the session override in the Sessions UI returns the session to the configured default.

Priority processing (service_tier)

OpenAI’s API exposes priority processing via service_tier. Set it per model in Velaclaw:

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": { params: { serviceTier: "priority" } },
        "openai-codex/gpt-5.4": { params: { serviceTier: "priority" } },
      },
    },
  },
}

Supported values: auto, default, flex, priority.

serviceTier is only forwarded to native OpenAI endpoints (api.openai.com) and native Codex endpoints (chatgpt.com/backend-api). If you route either provider through a proxy, Velaclaw leaves service_tier untouched.

Server-side compaction (Responses API)

For direct OpenAI Responses models (openai/* on api.openai.com), Velaclaw auto-enables server-side compaction:

• Forces store: true (unless model compat sets supportsStore: false)
• Injects context_management: [{ type: "compaction", compact_threshold: ... }]
• Default compact_threshold: 70% of contextWindow (or 80000 when unavailable)

Enable explicitly

Useful for compatible endpoints like Azure OpenAI Responses:

{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.4": {
          params: { responsesServerCompaction: true },
        },
      },
    },
  },
}

Custom threshold

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            responsesServerCompaction: true,
            responsesCompactThreshold: 120000,
          },
        },
      },
    },
  },
}

Disable

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: { responsesServerCompaction: false },
        },
      },
    },
  },
}

responsesServerCompaction only controls context_management injection. Direct OpenAI Responses models still force store: true unless compat sets supportsStore: false.

Strict-agentic GPT mode

For GPT-5-family runs on openai/* and openai-codex/*, Velaclaw can use a stricter embedded execution contract:

{
  agents: {
    defaults: {
      embeddedPi: { executionContract: "strict-agentic" },
    },
  },
}

With strict-agentic, Velaclaw:

• No longer treats a plan-only turn as successful progress when a tool action is available
• Retries the turn with an act-now steer
• Auto-enables update_plan for substantial work
• Surfaces an explicit blocked state if the model keeps planning without acting

Scoped to OpenAI and Codex GPT-5-family runs only. Other providers and older model families keep default behavior.

Native vs OpenAI-compatible routes

Velaclaw treats direct OpenAI, Codex, and Azure OpenAI endpoints differently from generic OpenAI-compatible /v1 proxies:

Native routes (openai/*, openai-codex/*, Azure OpenAI):

• Keep reasoning: { effort: "none" } intact when reasoning is explicitly disabled
• Default tool schemas to strict mode
• Attach hidden attribution headers on verified native hosts only
• Keep OpenAI-only request shaping (service_tier, store, reasoning-compat, prompt-cache hints)

Proxy/compatible routes:

• Use looser compat behavior
• Do not force strict tool schemas or native-only headers

Azure OpenAI uses native transport and compat behavior but does not receive the hidden attribution headers.

Related

Model selection

Choosing providers, model refs, and failover behavior.

Image generation

Shared image tool parameters and provider selection.

Video generation

Shared video tool parameters and provider selection.

OAuth and auth

Auth details and credential reuse rules.