How to Set Up OpenClaw with OpenAI GPT Models

OpenClaw keeps model routing and authentication as separate layers. Every OpenAI model uses the openai/* prefix regardless of how you authenticate. The auth method determines billing, rate limits, and which runtime executes your agent.

API Key (Direct Billing)

• Pay per token through the OpenAI Platform
• No usage caps beyond your OpenAI account limits
• Works with every OpenAI model: chat, image, video, and speech
• Best for production agents with high-volume or continuous workloads

Codex Subscription (OAuth)

• Uses your ChatGPT Plus or Pro subscription quota
• Flat monthly cost instead of per-token billing
• Includes access to the native Codex app-server runtime for GPT-5.5
• Subject to subscription-tier usage limits

The practical tradeoff: API keys give you metered access with no usage ceiling. Codex subscription routes through your ChatGPT account, which means a fixed monthly rate but with your tier's limits. For development, prototyping, and moderate workloads, the Codex path is often cheaper. For agents that run continuously or process large volumes, API key billing gives you predictable throughput without quota concerns.

OpenAI enabled ChatGPT subscription access for OpenClaw in May 2026, opening the Codex auth path to 3.2 million OpenClaw users. The openai-codex identifier handles authentication while model references continue using the standard openai/* prefix.

Auth resolution follows a priority chain: explicit OpenClaw profile first, then the app-server account, then fallback to CODEX_API_KEY or OPENAI_API_KEY environment variables. This matters when you have both auth methods configured and need to control which one a given agent uses.

API Key Configuration

Create an API key on the OpenAI Platform dashboard. Give it a descriptive name like "OpenClaw Production" and copy it immediately.

Run the onboarding command:

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

You can also set the key directly as an environment variable:

export OPENAI_API_KEY="sk-your-key-here"

Codex Subscription Configuration

If you have a ChatGPT Plus or Pro subscription, authenticate via OAuth instead:

openclaw onboard --auth-choice openai-codex

This opens a browser window for the OAuth flow. For headless servers or CI environments where a browser isn't available, add the device-code flag:

openclaw onboard --auth-choice openai-codex --device-code

The device-code flow prints a URL and a one-time code to your terminal. Open the URL on any device, enter the code, and approve the connection.

Verifying the Connection

After setting up either method, confirm your configuration:

openclaw status

This shows whether your gateway and provider configuration are valid. For deeper diagnostics, openclaw doctor --fix repairs common issues like legacy openai-codex/* model references that should use the openai/* prefix. To inspect your active model, runtime, and auth profiles:

openclaw models status
openclaw models auth list --provider openai-codex

If you run into configuration problems after upgrading OpenClaw, openclaw config validate checks the integrity of your entire configuration file and flags deprecated or malformed entries.

OpenClaw routes all OpenAI models through the openai/* prefix. The model you specify determines the capabilities your agent can access and, for chat models, which runtime executes it.

Chat Models

openai/gpt-5.5 is the default agent model. With Codex subscription auth, it runs on the native Codex app-server runtime by default. With API key auth, it uses the PI embedded runtime. You can force the PI runtime regardless of auth method by setting agentRuntime.id: "pi" in your configuration.

GPT-5.5 ships with a native context window of 1,000,000 tokens. OpenClaw caps the runtime default at 272,000 tokens for practical performance, since most agent tasks don't need the full window.

openai/gpt-5.4-mini is a lighter alternative when cost matters more than maximum reasoning depth.

openai/chat-latest is a moving alias that points to whatever model ChatGPT's Instant mode currently uses. It shifts as OpenAI updates the default, so pin a specific model for production stability.

Image Generation

openai/gpt-image-2 is the default for image generation. For cases requiring transparent PNGs or WebPs with alpha channels, openai/gpt-image-1.5 adds that support.

Video and Speech

openai/sora-2 handles text-to-video, image-to-video, and single-video editing modes.

For text-to-speech, gpt-4o-mini-tts is the default with 14 voice options including alloy, coral, echo, sage, and marin. Higher-fidelity alternatives include tts-1 and tts-1-hd. Transcription runs on gpt-4o-transcribe, and gpt-realtime-2 powers interactive voice sessions.

Configure TTS for your agent:

{
  messages: {
    tts: {
      providers: {
        openai: { model: "gpt-4o-mini-tts", voice: "coral" }
      }
    }
  }
}

Memory Embeddings

If your agent uses memory search, configure the embedding model separately:

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small"
      }
    }
  }
}

This uses OpenAI's text-embedding-3-small for similarity search across your agent's stored memories, independent of which chat model handles conversations.

GPT-5 models also support a personality overlay with three modes: "friendly" (default), "on", and "off". For stricter execution in embedded mode, the "strict-agentic" contract setting retries planning-only turns with an action directive and auto-enables plan updates.

Give Your OpenClaw Agent Persistent Storage

OpenClaw agents running GPT models generate files that need to outlast the session. Fast.io gives you 50GB of free storage with built-in RAG search, MCP access, and one-click handoff to your team. No credit card required.

Sign Up Free

Getting model routing right is only half the picture. Context window sizing, compaction behavior, and transport configuration all affect how your agent performs in practice.

For example, an agent that summarizes uploaded legal contracts might process 50,000 tokens per document. Setting the context window to 160,000 tokens handles three documents per session while keeping latency under control. If the agent runs longer sessions, server-side compaction kicks in at the 70% threshold and condenses older context automatically, so the agent doesn't lose track of earlier documents mid-conversation.

The subsections below cover each tuning lever with concrete configuration and the tradeoffs involved.

{
  models: {
    providers: {
      "openai-codex": {
        models: [{ id: "gpt-5.5", contextTokens: 160000 }]
      }
    }
  }
}

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

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { transport: "sse" }
        }
      }
    }
  }
}

{
  models: {
    providers: {
      openai: {
        baseUrl: "https://your-resource.openai.azure.com",
        apiKey: "your-azure-key"
      }
    }
  }
}

An OpenClaw agent running GPT-5.5 can generate images, video, documents, and structured data across sessions. Where that output lives determines whether your team can actually use it.

Local filesystems work during development but don't survive container restarts or server migrations. S3 and GCS provide durability without collaboration features. Google Drive and Dropbox add sharing but weren't designed for agent workflows where files need to be indexed, searched, and handed off programmatically.

Fast.io is built for this scenario. It's a workspace platform where agents and humans share the same files, search layer, and handoff workflows. Your OpenClaw agent writes files to a workspace through the MCP server or REST API, and team members see those files immediately.

What makes Fast.io practical for OpenClaw agent workflows:

• MCP-native access: Fast.io exposes Streamable HTTP at /mcp and legacy SSE at /sse. OpenClaw agents can read, write, search, and manage files through the MCP toolset.
• Built-in Intelligence: Enable Intelligence on a workspace and every uploaded file is automatically indexed for semantic search and citation-backed chat. No separate vector database to configure or maintain.
• Ownership transfer: Your agent builds a workspace with organized outputs, then transfers the entire organization to a client or team member. The agent keeps admin access for ongoing work.
• Webhooks: Get notified when files change in a workspace. Build reactive workflows that trigger downstream processing without polling.
• Free agent tier: 50GB storage, 5,000 credits per month, 5 workspaces. No credit card, no trial, no expiration. Get started free.

Agents can also pull files from existing cloud storage into Fast.io workspaces using Cloud Import. Connect Google Drive, OneDrive, Box, or Dropbox via OAuth and import folder structures without downloading anything locally.

For teams already running OpenClaw with GPT models, adding a persistent storage layer takes minutes. The agent authenticates once, uploads outputs to a shared workspace, and every collaborator gets immediate access through the browser or their own MCP client.