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)
Codex subscription

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

Get your API key

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

Run onboarding

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

Or pass the key directly:

velaclaw onboard --openai-api-key "$OPENAI_API_KEY"

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.

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

Run Codex OAuth

velaclaw onboard --auth-choice openai-codex

Or run OAuth directly:

velaclaw models auth login --provider openai-codex

Set the default model

velaclaw config set agents.defaults.model.primary openai-codex/gpt-5.4

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
CLI

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

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:

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
Custom threshold
Disable

Useful for compatible endpoints like Azure OpenAI Responses:

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

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

{
  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.

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.

Overview

Concepts and configuration

Providers

OpenAI

OpenAI

Getting started

Route summary

Config example

Route summary

Config example

Context window cap

Image generation

Video generation

Personality overlay

Voice and speech

Advanced configuration

Model selection

Image generation

Video generation

OAuth and auth

​OpenAI

​Getting started

​Route summary

​Config example

​Route summary

​Config example

​Context window cap

​Image generation

​Video generation

​Personality overlay

​Voice and speech

​Advanced configuration

​Related

Model selection

Image generation

Video generation

OAuth and auth

OpenAI

Getting started

Route summary

Config example

Route summary

Config example

Context window cap

Image generation

Video generation

Personality overlay

Voice and speech

Advanced configuration

Related