OpenAI

Use GPT-5.6, GPT-4o, GPT-4.1, and other OpenAI models with Docker Agent.

Setup

# Set your API key
export OPENAI_API_KEY="sk-..."

Configuration

Inline

agents:
  root:
    model: openai/gpt-5.6

Named Model

models:
  gpt:
    provider: openai
    model: gpt-5.6
    max_tokens: 4000

Available Models

Starting with GPT-5.6, OpenAI renamed the -mini/-nano size tiers to -terra/-luna (with -sol denoting the frontier tier previously left unsuffixed).

Find more model names at modelnames.ai or in the official OpenAI docs.

Service Tier (Fast Mode)

Set provider_opts.service_tier to request OpenAI's Fast mode:

models:
  fast-gpt:
    provider: openai
    model: gpt-5.6
    provider_opts:
      service_tier: fast

OpenAI also accepts priority for Fast mode. It provides faster processing at premium pricing on supported models, without reducing reasoning effort. This is independent of thinking_budget and applies to all requests using the configured model, including internal calls such as title generation and compaction.

The value is forwarded unchanged to Chat Completions (including reranking) and Responses requests, over either SSE or WebSocket. OpenAI-compatible providers using these APIs also receive the option when set; the endpoint must support it. Other tiers, such as auto, default, and flex, can also be requested; availability and valid values depend on the API and model. When omitted or empty, no service_tier is sent, leaving the API's default behavior unchanged. Non-string values are ignored.

See examples/openai-service-tier.yaml for a complete example.

Hosted Tool Search

Set provider_opts.native_tool_search: true to let OpenAI's hosted tool search discover the agent's deferred tools instead of the built-in search_tool/add_tool pair:

models:
  gpt:
    provider: openai
    model: gpt-5.6-sol
    provider_opts:
      native_tool_search: true

Deferred tools are declared with defer_loading: true alongside a server-executed tool_search tool on Responses API requests. Strictly opt-in: only openai models that support deferred tools (gpt-5.4 and later) qualify; the option is ignored elsewhere (chatgpt, OpenAI-compatible endpoints including a custom base_url, Chat Completions requests) and the legacy behaviour is kept.

See examples/deferred_native_tool_search.yaml for a complete example.

Thinking Budget

OpenAI reasoning models (o-series, gpt-5, gpt-5-mini, gpt-5.6 family, gpt-6 family) support extended thinking through the reasoning_effort API parameter. Set thinking_budget to control the effort level:

models:
  gpt-thinker:
    provider: openai
    model: gpt-5.6
    thinking_budget: high   # none | minimal | low | medium | high | xhigh | max

Effort levels:

Token counts, adaptive, and adaptive/<effort> are rejected with a configuration error at request time. Older models (o1, o3-mini) only accept low/medium/high; xhigh requires gpt-5.2+; max requires gpt-5.6+; none is supported on GPT-5.x from 5.6 onward and GPT-6 Sol/Luna, but not Astra; minimal is not accepted on gpt-5.6+.

GPT-6 Sol/Luna also support function tools with thinking_budget: none on Chat Completions. Tool calling with reasoning requires the Responses API, which Docker Agent selects automatically for these models on the openai provider. Astra requires Responses for tool calling.

See the Thinking / Reasoning guide for a cross-provider overview.

Custom Endpoint

Use base_url to connect to OpenAI-compatible APIs:

models:
  custom:
    provider: openai
    model: gpt-5.6-terra
    base_url: https://your-proxy.example.com/v1

WebSocket Transport

For OpenAI Responses API models (gpt-4.1+, o-series, gpt-5), you can use WebSocket streaming instead of the default SSE (Server-Sent Events):

models:
  fast-gpt:
    provider: openai
    model: gpt-4.1
    provider_opts:
      transport: websocket  # Use WebSocket instead of SSE

Benefits

• ~40% faster for workflows with 20+ tool calls
• Persistent connection reduces per-turn overhead
• Server-side caching of connection state
• Automatic fallback to SSE if WebSocket fails

Requirements

• Only works with Responses API models: gpt-4.1+, o1, o3, o4, gpt-5
• NOT compatible with the --models-gateway flag (automatically falls back to SSE when a gateway is configured)
• Requires OPENAI_API_KEY environment variable

Example

See examples/websocket_transport.yaml for a complete example.

Prompt Cache Diagnostics

Enable provider_opts.cache_diagnostics to compare a response's cache reuse with its preceding assistant turn. Available on the OpenAI Responses API with GPT-5.6 and later supported models:

models:
  gpt:
    provider: openai
    model: gpt-5.6-sol
    provider_opts:
      cache_diagnostics: true

Run with --debug to log the diagnostic result, cache-miss reason, reusable and missed token estimates, and actual cached tokens. Reasons can include changed tools, input, reasoning effort, or service tier. Diagnostics do not change caching behavior or load conversation history.

The comparison comes from the current session's preceding assistant response, not shared client state. The first turn, a model switch, or a session without a comparison ID skips the comparison. Expired diagnostic records and unavailable results are logged without failing the conversation. This option is ignored for Chat Completions, the chatgpt provider, and custom base_url endpoints.

Extra Request Body

Use provider_opts.extra_body to pass backend-specific fields to Chat Completions requests, including when you use a custom base_url. For example, a local Qwen server may support chat_template_kwargs: {enable_thinking: false}. Explicit fields override generated values. This option does not apply to the Responses API.

Reasoning State Preservation

Reasoning replay is opt-in, so existing configurations keep their request and session-storage behavior. Enable it for first-party OpenAI Responses sessions, including the chatgpt provider:

provider_opts:
  preserve_reasoning: true

This preserves encrypted reasoning items and assistant message phases in the session and replays the ordered output alongside tool results. Enabling native_tool_search also enables output replay because hosted search needs to retain its loaded tools. cache_diagnostics alone saves only response metadata; it does not enable reasoning replay.

Opaque state is only replayed to the same provider and resolved model. When hooks edit assistant text, reasoning summaries, or tool calls, Docker Agent falls back to the edited conversation instead of replaying stale output. Hosted tool-search history is discarded when it references tools no longer in the allowed catalog. Other providers and custom endpoints retain their existing behavior.

When enabled, this adds opaque data to the local session store and may increase input-token usage and trigger earlier compaction; it does not expose hidden reasoning as readable text. Reasoning tokens remain part of the context estimate, and the existing session compaction strategy still applies. With replay enabled, WebSocket requests replay the full history without also chaining it through previous_response_id.

See OpenAI's reasoning guide and cache diagnostics guide.