OpenAI Provider

기준일: 2026-07-26
난이도: 중급
공식 기준: OpenAI

개요

이 페이지는 OpenClaw OpenAI provider의 인증, 모델 ref, 온보딩 플래그, 설정 키를 공식 문서 기준으로 정리합니다.

공식 요약: Use OpenAI via API keys or Codex subscription in OpenClaw

model ref는 보통 provider/model 형식입니다. API key·endpoint·model id는 아래 원문 값을 그대로 쓰세요. 임의로 키나 엔드포인트를 만들지 마세요.

빠른 참조

Goal	Use	Notes
ChatGPT/Codex subscription, native Codex runtime	openai/gpt-5.6-sol	Fresh subscription setup; sign in with Codex auth.
Direct API-key billing for agent turns	openai/gpt-5.6 plus an ordered API-key auth profile	Fresh API-key setup; the bare direct-API id resolves to Sol.
Choose an exact GPT-5.6 tier	openai/gpt-5.6-sol, -terra, or -luna	Check models list for the tiers available to this account.
Account without GPT-5.6 access	openai/gpt-5.5	Explicit recovery choice; OpenClaw does not silently downgrade.
Direct API-key billing, explicit OpenClaw runtime	openai/gpt-5.6 plus provider/model agentRuntime.id: "openclaw"	Select a normal openai API-key profile.
Latest ChatGPT Instant model alias	openai/chat-latest	Direct API-key only; moving alias, not the stable default.
Image generation or editing	openai/gpt-image-2	Works with OPENAI_API_KEY or Codex OAuth.
Transparent-background images	openai/gpt-image-1.5	Set outputFormat to png or webp and background=transparent.

공식 문서 기반 상세

아래는 공식 providers/openai 문서를 Mintlify 컴포넌트만 정리하고 공통 제목을 한국어로 맞춘 내용입니다. 설정 키, env, model ref, CLI 플래그는 원문 그대로 유지합니다.

OpenClaw uses one provider id, openai, for both direct API-key auth and ChatGPT/Codex subscription auth. openai/* is the canonical model route. For embedded agent turns with runtime policy unset or auto, OpenAI's route facts decide whether OpenClaw may select the bundled Codex app-server runtime implicitly. The openai/* prefix alone does not select a runtime.

• Agent models - openai/* through the runtime selected by explicit agentRuntime config or OpenAI's implicit route policy. Sign in with Codex auth for ChatGPT/Codex subscription use, or configure an API-key auth profile when you want key-based billing.
• Non-agent OpenAI APIs - direct OpenAI Platform access, billed per use, through OPENAI_API_KEY or an openai API-key auth profile.
• Legacy config - codex/* and openai-codex/* refs are repaired to openai/* plus model-scoped agentRuntime.id: "codex" by openclaw doctor --fix.

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

사용량·비용 추적

OpenClaw keeps subscription quota and Platform API billing distinct:

• ChatGPT/Codex OAuth shows the subscription plan, quota windows, and credit balance.
• OPENAI_ADMIN_KEY shows 30 days of provider-reported organization cost and completions usage in Control UI Usage, including daily spend, request/token totals, top models, and cost categories.
• OPENAI_PROJECT_ID optionally scopes Admin API history to one project.
• OpenClaw never sends OPENAI_API_KEY or an openai inference profile to organization APIs; those credentials may belong to custom, Azure, or agent-local endpoints.

An explicit Admin key takes precedence over OAuth. Provider-reported history is not merged with OpenClaw's session-derived estimated cost; it can include API activity from other clients and provider-side billing adjustments.

OpenAI's API Usage Dashboard documentation describes the organization-owner and explicit Usage Dashboard permission requirements for usage data.

Provider, model, runtime, and channel are separate layers. If those labels are getting mixed together, read Agent runtimes before changing config.

선택 가이드

Goal	Use	Notes
ChatGPT/Codex subscription, native Codex runtime	openai/gpt-5.6-sol	Fresh subscription setup; sign in with Codex auth.
Direct API-key billing for agent turns	openai/gpt-5.6 plus an ordered API-key auth profile	Fresh API-key setup; the bare direct-API id resolves to Sol.
Choose an exact GPT-5.6 tier	openai/gpt-5.6-sol, -terra, or -luna	Check models list for the tiers available to this account.
Account without GPT-5.6 access	openai/gpt-5.5	Explicit recovery choice; OpenClaw does not silently downgrade.
Direct API-key billing, explicit OpenClaw runtime	openai/gpt-5.6 plus provider/model agentRuntime.id: "openclaw"	Select a normal openai API-key profile.
Latest ChatGPT Instant model alias	openai/chat-latest	Direct API-key only; moving alias, not the stable default.
Image generation or editing	openai/gpt-image-2	Works with OPENAI_API_KEY or Codex OAuth.
Transparent-background images	openai/gpt-image-1.5	Set outputFormat to png or webp and background=transparent.

이름 매핑

Name you see	Layer	Meaning
openai	Provider prefix	Canonical OpenAI model route; route facts determine the implicit runtime.
codex plugin	Plugin	Bundled plugin providing the native Codex app-server runtime and /codex chat controls.
provider/model agentRuntime.id: codex	Agent runtime	Force the native Codex app-server harness for matching embedded turns.
/codex ...	Chat command set	Bind/control Codex app-server threads from a conversation.
runtime: "acp", agentId: "codex"	ACP session route	Explicit fallback path that runs Codex through ACP/acpx.

암시적 agent runtime

When provider/model agentRuntime policy is unset or auto, OpenAI's provider-owned route policy chooses the implicit runtime from the effective endpoint and adapter:

Effective route facts	Implicit runtime
Exact official Platform HTTPS endpoint with openai-responses, or exact official ChatGPT HTTPS endpoint with openai-chatgpt-responses; no authored request override	Codex may be selected
Authored openai-completions adapter	OpenClaw
Custom endpoint	OpenClaw
Explicit exact official endpoint using HTTP	Rejected
Route with an authored provider/model request override	OpenClaw

An explicit non-default provider/model agentRuntime.id remains authoritative. For example, agentRuntime.id: "openclaw" keeps an otherwise Codex-eligible route on OpenClaw, while agentRuntime.id: "codex" requires Codex and fails closed when the effective route is not declared Codex-compatible. Runtime selection does not change credential type or billing: Platform API-key auth and ChatGPT/Codex subscription auth remain distinct.

openclaw doctor --fix migrates legacy codex/* and openai-codex/* model refs, legacy Codex auth profile ids, and legacy Codex auth-order entries to the canonical openai route. Migrated model refs receive model-scoped agentRuntime.id: "codex"; use auth.order.openai for new auth-order config.

Fresh OpenAI setup applies a GPT-5.6 primary only when no primary model is configured. Adding or refreshing OpenAI auth preserves an existing explicit selection, including openai/gpt-5.5, unless you explicitly use models auth login --set-default or models set. Use an API-key auth profile only when you want API-key auth for an agent model.

GPT-5.6 limited preview

OpenClaw recognizes the exact openai/gpt-5.6-sol, openai/gpt-5.6-terra, and openai/gpt-5.6-luna model ids. All three expose xhigh and max reasoning in the current catalog. OpenAI describes Sol as the flagship tier, Terra as the balanced tier, and Luna as the fast, lower-cost tier. See the GPT-5.6 launch announcement and access guide.

With direct OpenAI API-key auth, the bare openai/gpt-5.6 id is an alias for Sol and is the fresh setup default. The native Codex catalog does not apply that direct-API alias client-side; depending on workspace access, it can show the exact Sol, Terra, and Luna ids. Fresh ChatGPT/Codex OAuth setup therefore uses openai/gpt-5.6-sol. Check the current account with:

openclaw models list --provider openai

API organization and Codex workspace access can differ. If GPT-5.6 is not available, select GPT-5.5 explicitly:

openclaw models set openai/gpt-5.5

OpenClaw surfaces the upstream access error and does not silently replace a GPT-5.6 selection with GPT-5.5.

Eligible exact official HTTPS routes may select the bundled Codex app-server plugin when runtime policy is unset or auto; authored Completions routes, custom endpoints, and request-transport overrides remain on OpenClaw. Plaintext official HTTP endpoints are rejected. Explicit provider/model runtime config remains authoritative. Run openclaw doctor --fix to repair stale legacy Codex model refs, codex-cli/* refs, or old runtime session pins that were not set by explicit runtime config.

OpenClaw feature coverage

OpenAI capability	OpenClaw surface	Status
Chat / Responses	openai/<model> model provider	Yes
Codex subscription models	openai/<model> with OpenAI OAuth	Yes
Legacy Codex model refs	old Codex model refs, codex-cli/<model>	Repaired by doctor to openai/<model>
Codex app-server harness	Codex-compatible HTTPS route with runtime unset/auto, or explicit agentRuntime.id: codex	Yes
Server-side web search	Native OpenAI Responses tool	Yes, when web search is enabled and no other provider is pinned
Images	image_generate	Yes
Videos	video_generate	Yes
Text-to-speech	tts.provider: "openai" / tts	Yes
Batch speech-to-text	tools.media.audio / media understanding	Yes
Streaming speech-to-text	Voice Call streaming.provider: "openai"	Yes
Realtime voice	Voice Call realtime.provider: "openai" / Control UI Talk talk.realtime.provider: "openai"	Yes (OpenAI Platform API key)
Embeddings	memory embedding provider	Yes

OpenAI Realtime voice goes through the public OpenAI Platform Realtime API and requires a Platform API key. Codex OAuth tokens authenticate the ChatGPT Codex backend instead; they are not interchangeable with Platform API keys for the public Realtime endpoints.

If API-key auth reports missing billing, top up Platform credits at platform.openai.com/account/billing for the organization backing your realtime credentials when using API-key auth. Realtime voice accepts the openai API-key auth profile created by openclaw onboard --auth-choice openai-api-key, a Platform API key set via talk.realtime.providers.openai.apiKey for Control UI Talk, or plugins.entries.voice-call.config.realtime.providers.openai.apiKey for Voice Call, or the OPENAI_API_KEY environment variable.

In Control UI Video Talk, OpenAI WebRTC receives camera context on demand: when the model calls describe_view, the browser sends one bounded JPEG over the realtime data channel. OpenClaw does not attach a continuous camera track to the OpenAI session.

Memory embeddings

OpenClaw can use OpenAI, or an OpenAI-compatible embedding endpoint, for memory_search indexing and query embeddings:

{
  memory: {
    search: {
      provider: "openai",
      model: "text-embedding-3-small",
    },
  },
}

For OpenAI-compatible endpoints that require asymmetric embedding labels, set queryInputType and documentInputType under memory.search. OpenClaw forwards these as provider-specific input_type request fields: query embeddings use queryInputType; indexed memory chunks and batch indexing use documentInputType. See the Memory configuration reference for the full example.

시작하기

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


  

Get your API key

    Create or copy an API key from the [OpenAI Platform dashboard](https://platform.openai.com/api-keys).
  

  

Run onboarding

    ```bash
    openclaw onboard --auth-choice openai-api-key
    ```

    Or pass the key directly:

    ```bash
    openclaw onboard --openai-api-key "$OPENAI_API_KEY"
    ```
  

  

Verify the model is available

    ```bash
    openclaw models list --provider openai
    ```
  



### Route summary

| Model ref        | Runtime policy or route facts                                 | Route                     | Auth                              |
| ---------------- | ------------------------------------------------------------- | ------------------------- | --------------------------------- |
| `openai/gpt-5.6` | unset/`auto`, exact official HTTPS native route, no request override | Codex may be selected     | Ordered API-key auth profile      |
| `openai/gpt-5.6` | provider/model `agentRuntime.id: "openclaw"`                  | OpenClaw embedded runtime | Selected `openai` API-key profile |
| `openai/gpt-5.5` | explicit provider/model `agentRuntime.id`                     | Selected agent runtime    | Selected OpenAI API-key profile   |
| `openai/*`       | authored Completions, custom, or request override | OpenClaw embedded runtime | Credential type remains unchanged |
| `openai/*`       | plaintext official HTTP endpoint                  | Rejected                 | Credential is not sent             |

With runtime unset or auto, only an eligible exact official HTTPS native route may select the Codex app-server harness implicitly. For API-key auth on an agent model, create an openai API-key auth profile and order it with auth.order.openai; OPENAI_API_KEY remains the direct fallback for non-agent OpenAI API surfaces. Run openclaw doctor --fix to migrate older legacy Codex auth-order entries.

### Config example

```json5
{
  env: { OPENAI_API_KEY: "example-openai-key-not-real" },
  agents: { defaults: { model: { primary: "openai/gpt-5.6" } } },
}
```

The bare direct-API `gpt-5.6` id resolves to the Sol tier. If this API
organization does not expose GPT-5.6, set the primary to
`openai/gpt-5.5` explicitly.

To try ChatGPT's current Instant model from the OpenAI API, set the model
to `openai/chat-latest`:

```json5
{
  env: { OPENAI_API_KEY: "example-openai-key-not-real" },
  agents: { defaults: { model: { primary: "openai/chat-latest" } } },
}
```

`chat-latest` is a moving alias. Fresh OpenAI API-key setup instead uses
`openai/gpt-5.6`, whose bare direct-API id resolves to Sol. Existing
explicit primaries, including `openai/gpt-5.5`, remain unchanged. The
`chat-latest` alias only accepts `medium` text verbosity; OpenClaw forces
any other requested verbosity to `medium` for this model.

OpenClaw does not expose gpt-5.3-codex-spark on the direct OpenAI API-key route. It is available only through Codex subscription catalog entries when your signed-in account exposes it.

**Best for:** using your ChatGPT/Codex subscription with native Codex
app-server execution instead of a separate API key. Codex cloud requires
ChatGPT sign-in.


  

Run Codex OAuth

    ```bash
    openclaw onboard --auth-choice openai
    ```

    Or run OAuth directly:

    ```bash
    openclaw models auth login --provider openai
    ```

    For headless or callback-hostile setups, add `--device-code` to sign
    in with a ChatGPT device-code flow instead of the localhost browser
    callback:

    ```bash
    openclaw models auth login --provider openai --device-code
    ```
  

  

Use the canonical OpenAI model route

    ```bash
    openclaw config set agents.defaults.model.primary openai/gpt-5.6-sol
    ```

    No runtime config is required for this exact official HTTPS native
    route. It may select the Codex app-server runtime automatically, and
    OpenClaw installs or repairs the bundled Codex plugin when that runtime
    is chosen.
  

  

Verify Codex auth is available

    ```bash
    openclaw models list --provider openai
    ```

    After the gateway is running, send `/codex status` or `/codex models`
    in chat to verify the native app-server runtime.
  



### Route summary

| Model ref                | Runtime policy or route facts                                 | Route                                                    | Auth                                               |
| ------------------------ | ------------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------- |
| `openai/gpt-5.6-sol`     | unset/`auto`, exact official HTTPS native route, no request override | Codex may be selected                                    | Codex sign-in, or an ordered `openai` auth profile |
| `openai/gpt-5.6-terra`   | unset/`auto`, exact official HTTPS native route, no request override | Codex may be selected                                    | Codex sign-in when the catalog exposes Terra       |
| `openai/gpt-5.6-luna`    | unset/`auto`, exact official HTTPS native route, no request override | Codex may be selected                                    | Codex sign-in when the catalog exposes Luna        |
| `openai/gpt-5.6-sol`     | provider/model `agentRuntime.id: "openclaw"`                  | OpenClaw embedded runtime, internal Codex-auth transport | Selected `openai` OAuth profile                    |
| `openai/gpt-5.5`         | explicit provider/model `agentRuntime.id`                     | Selected agent runtime                                   | Selected OpenAI auth profile                       |
| `openai/*`               | authored Completions, custom, or request override | OpenClaw embedded runtime                                | Credential requirement remains route-specific      |
| `openai/*`               | plaintext official HTTP endpoint                  | Rejected                                                 | Credential is not sent                              |
| Legacy Codex GPT-5.5 ref | repaired by doctor                                            | Rewritten to `openai/gpt-5.5`                            | Migrated OpenAI OAuth profile                      |
| `codex-cli/gpt-5.5`      | repaired by doctor                                            | Rewritten to `openai/gpt-5.5`                            | Codex app-server auth                              |

Fresh subscription-backed setup uses exact openai/gpt-5.6-sol; the native Codex catalog may also expose exact Terra or Luna refs. If the account does not expose GPT-5.6, select openai/gpt-5.5 explicitly. Older Codex GPT refs are legacy OpenClaw routes, not the native Codex runtime path; run openclaw doctor --fix to migrate them without upgrading an existing explicit GPT-5.5 selection. gpt-5.3-codex-spark stays limited to accounts whose Codex subscription catalog advertises it; direct OpenAI API-key and Azure refs for it stay suppressed.

New config should put OpenAI agent auth order under auth.order.openai; doctor migrates older legacy Codex auth-order entries.

### Config example

```json5
{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.6-sol" },
    },
  },
}
```

With an API-key backup, keep the selected model under `openai/*` and put
the auth order under `openai`. OpenClaw tries the subscription first, then
the API key, while staying on the Codex harness:

```json5
{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.6-sol" },
    },
  },
  auth: {
    order: {
      openai: [
        "openai:user@example.com",
        "openai:api-key-backup",
      ],
    },
  },
}
```

Onboarding no longer imports OAuth material from ~/.codex. Sign in with browser OAuth (default) or the device-code flow above; OpenClaw manages the resulting credentials in its own agent auth store.

### Check and recover Codex OAuth routing

```bash
openclaw models status
openclaw models auth list --provider openai
openclaw config get agents.defaults.model --json
openclaw config get models.providers.openai.agentRuntime --json
```

For a specific agent, add `--agent <id>`:

```bash
openclaw models status --agent <id>
openclaw models auth list --agent <id> --provider openai
```

If an older config still has legacy Codex GPT refs, or a stale OpenAI
runtime session pin without explicit runtime config, repair it:

```bash
openclaw doctor --fix
openclaw config validate
```

If `models auth list --provider openai` shows no usable profile, sign in
again:

```bash
openclaw models auth login --provider openai
openclaw models status --probe --probe-provider openai
```

Use `--profile-id` for multiple Codex OAuth logins in the same agent, then
control them via auth ordering or `/model ...@<profileId>`:

```bash
openclaw models auth login --provider openai --profile-id openai:ritsuko
openclaw models auth login --provider openai --profile-id openai:lain
```

Run `openclaw doctor --fix` to migrate older legacy OpenAI Codex prefix
profile ids and order entries before relying on profile ordering.

### Status indicator

Chat `/status` shows which model runtime is active for the current
session. The bundled Codex app-server harness appears as
`Runtime: OpenAI Codex` when an eligible implicit route or explicit
provider/model runtime policy selects it.

### Doctor warning

If legacy Codex model refs or stale OpenAI runtime pins remain in config
or session state, `openclaw doctor --fix` rewrites them to `openai/*` with
the Codex runtime unless OpenClaw is explicitly configured.

### Context window defaults and long-context opt-in

OpenClaw treats native model capacity and the active runtime budget as
separate values:

- `contextWindow` declares the provider's total model window.
- `contextTokens` caps how much of that window OpenClaw uses for active input.

ChatGPT/Codex OAuth follows the live Codex account catalog. The current
catalog commonly advertises a `272000` token active window for GPT-5.6.
Direct API-key GPT-5.5 and GPT-5.6 models also default to `272000`
`contextTokens`, even though the Platform API exposes a larger native
window. This keeps the normal latency, quality, and cost profile consistent
across auth modes. A configured `agents.defaults.contextTokens` value can
lower that budget further, but it cannot raise a model above its configured
`contextTokens` cap.

For direct API-key GPT-5.5 and GPT-5.6, OpenAI documents a `1050000`
token provider window and `128000` maximum output tokens. Reserving the
full output allowance leaves `922000` tokens for input. This is a derived
operating budget, not a separate provider-published input limit. See the
official [model comparison](https://developers.openai.com/api/docs/models/compare)
and [GPT-5.5 model page](https://developers.openai.com/api/docs/models/gpt-5.5).
The following example opts one Terra model into that allowance and asks
OpenAI to compact at `700000` active tokens:

```json5
{
  models: {
    providers: {
      openai: {
        models: [
          {
            id: "gpt-5.6-terra",
            name: "GPT-5.6 Terra",
            contextWindow: 1050000,
            contextTokens: 922000,
            maxTokens: 128000,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.6-terra" },
      models: {
        "openai/gpt-5.6-terra": {
          agentRuntime: { id: "openclaw" },
          params: {
            responsesServerCompaction: true,
            responsesCompactThreshold: 700000,
          },
        },
      },
    },
  },
}
```

`agentRuntime.id: "openclaw"` is intentional in this example. It proves the
embedded OpenClaw Responses path is using the model metadata and server-side
compaction settings above. A native Codex harness thread owns its context
budget in Codex config instead; see
[Codex harness long context](https://docs.openclaw.ai/plugins/codex-harness#direct-api-long-context).

OpenAI applies higher long-context pricing once a GPT-5.5 or GPT-5.6 request exceeds 272000 input tokens: the whole qualifying request is billed at 2× input and 1.5× output rates. Large prompts are resent or compacted across turns, so an opt-in session can cost substantially more than the default even when the visible reply is short. See OpenAI API pricing. The API remains authoritative for account access, actual limits, and billing.

### Catalog recovery

OpenClaw uses upstream Codex catalog metadata for `gpt-5.5` when it is
present. If live Codex discovery omits the `gpt-5.5` row while the account
is authenticated, OpenClaw synthesizes that OAuth model row so cron,
sub-agent, and configured default-model runs do not fail with
`Unknown model`.

Native Codex app-server auth

The native Codex app-server harness uses openai/* model refs when an eligible exact official HTTPS route selects it implicitly, or when provider/model agentRuntime.id: "codex" selects it explicitly. Its auth is still account-based. OpenClaw selects auth in this order:

1. Ordered OpenAI auth profiles for the agent, preferably under auth.order.openai. Run openclaw doctor --fix to migrate older legacy Codex auth profile ids and auth order.
2. The app-server's existing account, such as a local Codex CLI ChatGPT sign-in. For the default isolated agent home, OpenClaw bridges that native CLI account into the app-server through its login RPC; it does not share the CLI's config, plugins, or thread store.
3. For local stdio app-server launches only, and only when the app-server reports no account: CODEX_API_KEY, then OPENAI_API_KEY.

A local ChatGPT/Codex subscription sign-in is not replaced just because the gateway process also has OPENAI_API_KEY for direct OpenAI models or embeddings. The env API-key fallback applies only to the local stdio no-account path; it is never sent over WebSocket app-server connections. When a subscription-style Codex profile is selected, OpenClaw also keeps CODEX_API_KEY and OPENAI_API_KEY out of the spawned stdio app-server child and sends the selected credentials through the app-server login RPC instead.

When that subscription profile is blocked by a Codex usage limit, OpenClaw marks the profile blocked until Codex's advertised reset time and lets auth ordering rotate to the next openai:* profile, without changing the selected model or dropping out of the Codex harness. Once the reset time passes, the subscription profile is eligible again.

이미지 생성

The bundled openai plugin registers image generation through the image_generate tool. It supports both OpenAI API-key and Codex OAuth image generation through the same openai/gpt-image-2 model ref.

Capability	OpenAI API key	Codex OAuth
Model ref	openai/gpt-image-2	openai/gpt-image-2
Auth	OPENAI_API_KEY	OpenAI Codex OAuth sign-in
Transport	OpenAI Images API	Codex Responses backend
Max images per request	4	4
Edit mode	Enabled (up to 5 reference images)	Enabled (up to 5 reference images)
Size overrides	Supported, including 2K/4K sizes	Supported, including 2K/4K sizes
Aspect ratio / resolution	Not forwarded to OpenAI Images API	Mapped to a supported size when safe

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

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

gpt-image-2 is the default for OpenAI text-to-image generation and image editing. gpt-image-1.5, gpt-image-1, and gpt-image-1-mini remain usable as explicit model overrides. Use openai/gpt-image-1.5 for transparent-background PNG/WebP output; the current gpt-image-2 API rejects background: "transparent".

For a transparent-background request, call image_generate with model: "openai/gpt-image-1.5", outputFormat: "png" or "webp", and background: "transparent"; the older openai.background provider option is still accepted. OpenClaw also protects the public OpenAI and OpenAI Codex OAuth routes by rewriting default openai/gpt-image-2 transparent requests to gpt-image-1.5; Azure and custom OpenAI-compatible endpoints keep their configured deployment/model names.

The same setting is exposed for headless CLI runs:

openclaw infer image generate \
  --model openai/gpt-image-1.5 \
  --output-format png \
  --background transparent \
  --prompt "A simple red circle sticker on a transparent background" \
  --json

Use the same --output-format and --background flags with openclaw infer image edit when starting from an input file. --openai-background remains available as an OpenAI-specific alias. Use --quality low|medium|high|auto to control OpenAI Images quality and cost. Use --openai-moderation low|auto to pass OpenAI's moderation hint from either image generate or image edit.

For ChatGPT/Codex OAuth installs, keep the same openai/gpt-image-2 ref. When an openai OAuth profile is configured, OpenClaw resolves that stored OAuth access token and sends image requests through the Codex Responses backend; it does not first try OPENAI_API_KEY or silently fall back to an API key. Configure models.providers.openai explicitly with an API key, custom base URL, or Azure endpoint when you want the direct OpenAI Images API route instead. If that custom image endpoint is on a trusted LAN/private address, also set browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw keeps private/internal OpenAI-compatible image endpoints blocked unless this opt-in is present.

Generate:

/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1

Generate a transparent PNG:

/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

Edit:

/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536

비디오 생성

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 for text-to-video and image-to-video
Aspect ratio	Converted to the closest supported size, not forwarded raw
Other overrides	resolution, audio, watermark are unsupported and dropped with a tool warning

OpenAI image-to-video requests use POST /v1/videos with an image input_reference. Single-video edits use POST /v1/videos/edits with the uploaded video in the video field.

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

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

The OpenAI provider declares supportsSize but not supportsAspectRatio or supportsResolution. OpenClaw's shared normalization layer converts a requested aspectRatio into the closest matching OpenAI size before the request reaches the provider, so aspect-ratio requests generally still work. resolution has no size fallback and is dropped, surfaced to the caller as Ignored unsupported overrides for openai/<model>: resolution=<value>.

GPT-5 prompt contribution

OpenClaw adds a shared GPT-5 prompt contribution for GPT-5-family models on the openai provider (including legacy pre-repair Codex refs that normalize to openai/*). Other providers that also serve GPT-5-family model ids, such as OpenRouter or opencode routes, do not receive this overlay; it is gated on provider id openai, not on model id alone. Older GPT-4.x models never receive it.

The native Codex app-server harness does not receive the persona/tool- discipline behavior contract or the friendly interaction-style overlay through developer instructions; native Codex keeps Codex-owned base, model, and project-doc behavior, and OpenClaw disables Codex's built-in personality for native threads so agent workspace personality files stay authoritative. OpenClaw contributes only runtime context to native Codex threads: channel delivery, OpenClaw dynamic tools, ACP delegation, workspace context, and OpenClaw skills. The heartbeat-guidance text from this same contribution is the one exception: native Codex heartbeat turns do get it, injected as dedicated collaboration instructions rather than through the shared prompt-contribution hook.

The GPT-5 contribution adds a tagged behavior contract for persona persistence, execution safety, tool discipline, output shape, completion checks, and verification on matching OpenClaw-assembled prompts. Channel- specific reply and silent-message behavior stays in the shared OpenClaw system prompt and outbound delivery policy. The friendly interaction-style layer is separate and configurable.

Value	Effect
"friendly" (default)	Enable the friendly interaction-style layer
"on"	Alias for "friendly"
"off"	Disable only the friendly style layer

```json5
{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: { personality: "friendly" },
      },
    },
  },
}
```


```bash
openclaw config set agents.defaults.promptOverlays.gpt5.personality off
```

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

Legacy plugins.entries.openai.config.personality is still read as a compatibility fallback when the shared agents.defaults.promptOverlays.gpt5.personality setting is unset.

Voice and speech

Speech synthesis (TTS)

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

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

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

`extraBody` is merged into `/audio/speech` request JSON after OpenClaw's
generated fields, so use it for OpenAI-compatible endpoints that require
additional keys such as `lang`. Prototype keys are ignored.

```json5
{
  tts: {
    providers: {
      openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },
    },
  },
}
```

Set OPENAI_TTS_BASE_URL to override the TTS base URL without affecting the chat API endpoint. OpenAI TTS and Realtime voice are both configured through an OpenAI Platform API key; OAuth-only installs can still use Codex-backed chat models, but not OpenAI live talk-back.

Speech-to-text

The bundled `openai` plugin registers batch speech-to-text through
OpenClaw's media-understanding transcription surface.

- Default model: `gpt-4o-transcribe`
- Endpoint: OpenAI REST `/v1/audio/transcriptions`
- Input path: multipart audio file upload
- Used wherever inbound audio transcription reads `tools.media.audio`,
  including Discord voice-channel segments and channel audio attachments

To force OpenAI for inbound audio transcription:

```json5
{
  tools: {
    media: {
      audio: {
        models: [
          {
            type: "provider",
            provider: "openai",
            model: "gpt-4o-transcribe",
          },
        ],
      },
    },
  },
}
```

Language and prompt hints are forwarded to OpenAI when supplied by the
shared audio media config or per-call transcription request.

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` |
| Language         | `...openai.language`                                                 | (unset) |
| Prompt           | `...openai.prompt`                                                   | (unset) |
| Silence duration | `...openai.silenceDurationMs`                                        | `800`   |
| VAD threshold    | `...openai.vadThreshold`                                             | `0.5`   |
| Auth             | `...openai.apiKey`, `OPENAI_API_KEY`, or `openai` API-key profile    | Platform API key required |

Uses a WebSocket connection to wss://api.openai.com/v1/realtime with G.711 u-law (g711_ulaw / audio/pcmu) audio. For an openai API-key profile, the Gateway mints an ephemeral Realtime transcription client secret before opening the WebSocket. This streaming provider is for Voice Call's realtime transcription path; Discord voice currently records short segments and uses the batch tools.media.audio transcription path instead.

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-2.1`  |
| Voice                                  | `...openai.voice`                                                       | `alloy`             |
| Temperature (Azure deployment bridge)  | `...openai.temperature`                                                 | `0.8`               |
| VAD threshold                          | `...openai.vadThreshold`                                                | `0.5`                |
| Silence duration                       | `...openai.silenceDurationMs`                                           | `500`                |
| Prefix padding                         | `...openai.prefixPaddingMs`                                             | `300`                |
| Reasoning effort                       | `...openai.reasoningEffort`                                             | (unset)              |
| Auth                                   | `openai` API-key profile, `...openai.apiKey`, or `OPENAI_API_KEY` | OpenAI Platform API key required |

Available built-in Realtime voices for `gpt-realtime-2.1`: `alloy`, `ash`,
`ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`, `cedar`.

…이하 생략. 전체 내용은 공식 문서를 확인하세요.

이 페이지는 길이상 일부가 잘렸습니다. 전체: https://docs.openclaw.ai/providers/openai

검증 체크리스트

• openclaw models list --provider openai 로 모델이 보이는지 확인
• 기본 model alias를 agents.defaults.model.primary에 설정했는지 확인
• API key / OAuth / 로컬 런타임 인증 경로를 공식 문서와 대조했는지 확인
• failover 시 데이터가 다른 provider로 이동할 수 있는지 검토

관련

• Provider 목록 인덱스
• 로컬 모델과 Provider
• 공식: Provider directory, Model providers