> ## Documentation Index
> Fetch the complete documentation index at: https://zju-a00451d9-feat-personal-agent-team.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tabs>
  <Tab title="API key (OpenAI Platform)">
    **Best for:** direct API access and usage-based billing.

    <Steps>
      <Step title="Get your API key">
        Create or copy an API key from the [OpenAI Platform dashboard](https://platform.openai.com/api-keys).
      </Step>

      <Step title="Run onboarding">
        ```bash theme={null}
        velaclaw onboard --auth-choice openai-api-key
        ```

        Or pass the key directly:

        ```bash theme={null}
        velaclaw onboard --openai-api-key "$OPENAI_API_KEY"
        ```
      </Step>

      <Step title="Verify the model is available">
        ```bash theme={null}
        velaclaw models list --provider openai
        ```
      </Step>
    </Steps>

    ### 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` |

    <Note>
      ChatGPT/Codex sign-in is routed through `openai-codex/*`, not `openai/*`.
    </Note>

    ### Config example

    ```json5 theme={null}
    {
      env: { OPENAI_API_KEY: "sk-..." },
      agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
    }
    ```

    <Warning>
      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.
    </Warning>
  </Tab>

  <Tab title="Codex subscription">
    **Best for:** using your ChatGPT/Codex subscription instead of a separate API key. Codex cloud requires ChatGPT sign-in.

    <Steps>
      <Step title="Run Codex OAuth">
        ```bash theme={null}
        velaclaw onboard --auth-choice openai-codex
        ```

        Or run OAuth directly:

        ```bash theme={null}
        velaclaw models auth login --provider openai-codex
        ```
      </Step>

      <Step title="Set the default model">
        ```bash theme={null}
        velaclaw config set agents.defaults.model.primary openai-codex/gpt-5.4
        ```
      </Step>

      <Step title="Verify the model is available">
        ```bash theme={null}
        velaclaw models list --provider openai-codex
        ```
      </Step>
    </Steps>

    ### 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) |

    <Note>
      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.
    </Note>

    ### Config example

    ```json5 theme={null}
    {
      agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
    }
    ```

    <Tip>
      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.
    </Tip>

    ### 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`:

    ```json5 theme={null}
    {
      models: {
        providers: {
          "openai-codex": {
            models: [{ id: "gpt-5.4", contextTokens: 160000 }],
          },
        },
      },
    }
    ```

    <Note>
      Use `contextWindow` to declare native model metadata. Use `contextTokens` to limit the runtime context budget.
    </Note>
  </Tab>
</Tabs>

## 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 |

```json5 theme={null}
{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-1" },
    },
  },
}
```

<Note>
  See [Image Generation](/tools/image-generation) for shared tool parameters, provider selection, and failover behavior.
</Note>

## 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 |

```json5 theme={null}
{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}
```

<Note>
  See [Video Generation](/tools/video-generation) for shared tool parameters, provider selection, and failover behavior.
</Note>

## 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      |

<Tabs>
  <Tab title="Config">
    ```json5 theme={null}
    {
      plugins: {
        entries: {
          openai: { config: { personality: "friendly" } },
        },
      },
    }
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    velaclaw config set plugins.entries.openai.config.personality off
    ```
  </Tab>
</Tabs>

<Tip>
  Values are case-insensitive at runtime, so `"Off"` and `"off"` both disable the overlay.
</Tip>

## Voice and speech

<AccordionGroup>
  <Accordion title="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`.

    ```json5 theme={null}
    {
      messages: {
        tts: {
          providers: {
            openai: { model: "gpt-4o-mini-tts", voice: "coral" },
          },
        },
      },
    }
    ```

    <Note>
      Set `OPENAI_TTS_BASE_URL` to override the TTS base URL without affecting the chat API endpoint.
    </Note>
  </Accordion>

  <Accordion title="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` |

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

  <Accordion title="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` |

    <Note>
      Supports Azure OpenAI via `azureEndpoint` and `azureDeployment` config keys. Supports bidirectional tool calling. Uses G.711 u-law audio format.
    </Note>
  </Accordion>
</AccordionGroup>

## Advanced configuration

<AccordionGroup>
  <Accordion title="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          |

    ```json5 theme={null}
    {
      agents: {
        defaults: {
          models: {
            "openai-codex/gpt-5.4": {
              params: { transport: "auto" },
            },
          },
        },
      },
    }
    ```

    Related OpenAI docs:

    * [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
    * [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
  </Accordion>

  <Accordion title="WebSocket warm-up">
    Velaclaw enables WebSocket warm-up by default for `openai/*` to reduce first-turn latency.

    ```json5 theme={null}
    // Disable warm-up
    {
      agents: {
        defaults: {
          models: {
            "openai/gpt-5.4": {
              params: { openaiWsWarmup: false },
            },
          },
        },
      },
    }
    ```
  </Accordion>

  <Accordion title="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`.

    ```json5 theme={null}
    {
      agents: {
        defaults: {
          models: {
            "openai/gpt-5.4": { params: { fastMode: true } },
            "openai-codex/gpt-5.4": { params: { fastMode: true } },
          },
        },
      },
    }
    ```

    <Note>
      Session overrides win over config. Clearing the session override in the Sessions UI returns the session to the configured default.
    </Note>
  </Accordion>

  <Accordion title="Priority processing (service_tier)">
    OpenAI's API exposes priority processing via `service_tier`. Set it per model in Velaclaw:

    ```json5 theme={null}
    {
      agents: {
        defaults: {
          models: {
            "openai/gpt-5.4": { params: { serviceTier: "priority" } },
            "openai-codex/gpt-5.4": { params: { serviceTier: "priority" } },
          },
        },
      },
    }
    ```

    Supported values: `auto`, `default`, `flex`, `priority`.

    <Warning>
      `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.
    </Warning>
  </Accordion>

  <Accordion title="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)

    <Tabs>
      <Tab title="Enable explicitly">
        Useful for compatible endpoints like Azure OpenAI Responses:

        ```json5 theme={null}
        {
          agents: {
            defaults: {
              models: {
                "azure-openai-responses/gpt-5.4": {
                  params: { responsesServerCompaction: true },
                },
              },
            },
          },
        }
        ```
      </Tab>

      <Tab title="Custom threshold">
        ```json5 theme={null}
        {
          agents: {
            defaults: {
              models: {
                "openai/gpt-5.4": {
                  params: {
                    responsesServerCompaction: true,
                    responsesCompactThreshold: 120000,
                  },
                },
              },
            },
          },
        }
        ```
      </Tab>

      <Tab title="Disable">
        ```json5 theme={null}
        {
          agents: {
            defaults: {
              models: {
                "openai/gpt-5.4": {
                  params: { responsesServerCompaction: false },
                },
              },
            },
          },
        }
        ```
      </Tab>
    </Tabs>

    <Note>
      `responsesServerCompaction` only controls `context_management` injection. Direct OpenAI Responses models still force `store: true` unless compat sets `supportsStore: false`.
    </Note>
  </Accordion>

  <Accordion title="Strict-agentic GPT mode">
    For GPT-5-family runs on `openai/*` and `openai-codex/*`, Velaclaw can use a stricter embedded execution contract:

    ```json5 theme={null}
    {
      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

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

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
    Choosing providers, model refs, and failover behavior.
  </Card>

  <Card title="Image generation" href="/tools/image-generation" icon="image">
    Shared image tool parameters and provider selection.
  </Card>

  <Card title="Video generation" href="/tools/video-generation" icon="video">
    Shared video tool parameters and provider selection.
  </Card>

  <Card title="OAuth and auth" href="/gateway/authentication" icon="key">
    Auth details and credential reuse rules.
  </Card>
</CardGroup>