OpenAI

OpenAI multimodal models support text, images, and PDF input (application/pdf). For PDFs, provide a local file rather than a URL.

fast-agent exposes three OpenAI-facing provider paths. Use the provider prefix when you want to force a specific API surface:

Prefer models hosted on responses or codexresponses for OpenAI API work unless a legacy model is specifically needed.

Encrypted reasoning blocks are used to maintain model intelligence between tool calls and turns, with user-facing reasoning summaries made available.

Feature availability by OpenAI provider

Model availability

Responses models

Use responses for OpenAI Responses API models and for using the flex service tier or Remote MCP/Connectors.

WebSocket Support

Responses-compatible models use WebSockets as the default transport, with continuation support so repeated turns can avoid resending unchanged input items. fast-agent sends store=false on Responses requests. Read compatibility with ZDR policies for more details.

WebSocket mode can be disabled by using transport=sse in the model string.

Encrypted Reasoning

Reasoning summaries are displayed, with encrypted blocks stored locally for session resumption.

Responses models also have short aliases.

Examples:

• responses.gpt-5.5?reasoning=medium
• responses.gpt-5.5?web_search=on
• responses.gpt-5.4?service_tier=flex

Codex Responses models

Use codexresponses for Codex subscription-backed models. Authenticate with fast-agent auth codexplan or provide CODEX_API_KEY.

The codexresponses provider is similar to responses, with these main differences:

• The flex service tier is not supported.
• Remote MCP and Connectors are not supported.
• The supported model list includes gpt-5.3-codex-spark.
• Billing is via the Codex subscription.

Examples:

• codexplan
• codexresponses.gpt-5.5?reasoning=high
• codexresponses.gpt-5.3-codex-spark?web_search=on

Legacy Chat Completions models

Examples:

• openai.gpt-4.1
• openai.gpt-4o
• openai.my-custom-deployment

Configuration

YAML Configuration:

openai:
  api_key: "your_openai_key" # Default
  base_url: "https://api.openai.com/v1" # Default, only include if required

Environment Variables:

• OPENAI_API_KEY: Your OpenAI API key
• OPENAI_BASE_URL: Override the API endpoint

Responses (OpenAI Responses API)

Use the responses provider for OpenAI Responses API models (for example gpt-5, o3, o4-mini).

responses:
  api_key: "your_openai_key"
  base_url: "https://api.openai.com/v1" # Optional override
  reasoning: "medium" # Optional default
  text_verbosity: "medium" # Optional default for supporting models
  transport: "sse" # sse | websocket | auto
  web_search:
    enabled: false
    tool_type: web_search # web_search | web_search_preview
    # search_context_size: medium # low | medium | high
    # allowed_domains: ["openai.com", "docs.openai.com"]
    # external_web_access: false # only applies to tool_type=web_search
    # user_location:
    #   type: approximate
    #   city: "Minneapolis"
    #   region: "Minnesota"
    #   country: "US"
    #   timezone: "America/Chicago"

Per-run override via model string is also supported:

• responses.gpt-5-mini?web_search=on
• responses.gpt-5-mini?web_search=off
• responses.gpt-5.3-codex?transport=ws

Provider-managed remote MCP and connectors:

The OpenAI responses provider supports provider-managed remote MCP servers and OpenAI hosted connectors declared with management: provider under mcp.servers or card mcp_connect entries.

• Remote MCP servers must be remote http/sse URLs.
• Connector entries use connector_id instead of url. See OpenAI's hosted connector documentation for current connector behavior and authorization requirements.
• Set exactly one of url or connector_id.
• Use access_token for bearer auth / connector authorization.
• defer_loading: true enables server-side lazy tool loading.
• Not supported by codexresponses, Codex OAuth aliases, openresponses, or generic openai chat-completions models.

Connector IDs are validated against the installed OpenAI SDK. At the time this page was generated, the accepted IDs are:

• connector_dropbox
• connector_gmail
• connector_googlecalendar
• connector_googledrive
• connector_microsoftteams
• connector_outlookcalendar
• connector_outlookemail
• connector_sharepoint

Example connector entry:

mcp:
  servers:
    dropbox:
      management: provider
      connector_id: connector_dropbox
      access_token: "${DROPBOX_CONNECTOR_TOKEN}"
      description: "Dropbox connector"

See Configuration Reference for the MCP server schema and Agent Cards for card-scoped runtime targets.

Codex (OAuth Responses)

fast-agent supports using your OpenAI Codex subscription. Run fast-agent auth codexplan once, then use a Codex OAuth model alias such as codexplan (GPT-5.5 planning), codexplan54 (GPT-5.4 planning), codexplan53 (GPT-5.3 Codex planning), or codexspark (GPT-5.3 Codex Spark).

Quick Start:

# Start OAuth login (stores tokens in your OS keyring)
fast-agent auth codexplan

# Use the Codex planning model
fast-agent --model codexplan

# Pin a previous planning model via OAuth
fast-agent --model codexplan54

Provider Configuration:

codexresponses:
  # Optional: override defaults
  base_url: "https://chatgpt.com/backend-api/codex"
  text_verbosity: "medium"  # low | medium | high
  web_search:
    enabled: false
  default_headers:
    X-Custom-Header: "value"

Environment Variables:

• CODEX_API_KEY: Optional. Provide a Codex OAuth access token directly.

Notes:

• Tokens are stored in your OS keyring via fast-agent auth codexplan.
• codexplan maps to codexresponses.gpt-5.5?reasoning=medium.
• codexplan54 maps to codexresponses.gpt-5.4?reasoning=high.
• codexplan53 maps to codexresponses.gpt-5.3-codex?reasoning=medium.
• codexspark maps to codexresponses.gpt-5.3-codex-spark.
• All Codex OAuth aliases use the same stored OAuth token.
• Provider-managed MCP is not supported with codexresponses, including Codex OAuth aliases such as codexplan, codexplan54, and codexspark. Use responses instead when you need management: provider.
• To remove tokens, use: fast-agent auth codex-clear.
• fast-agent check and fast-agent auth show Codex OAuth status.