Using OpenAI with OpenClaw

Prerequisites

• ✓An OpenAI Platform account with an API key from the OpenAI dashboard if you want usage-based access to `openai/gpt-5.4`.
• ✓A ChatGPT/Codex subscription if you want to use the `openai-codex/*` OAuth route instead of an API key.
• ✓An existing OpenClaw installation with the CLI available so you can run `openclaw onboard` and `openclaw config` commands.

Steps

1. 1

   Decide between OpenAI API key and Codex subscription

   Pick whether your OpenClaw agents should talk to OpenAI via a direct API key (`openai/*`) or via ChatGPT/Codex OAuth (`openai-codex/*`). Use the API key path when you want usage-based billing and direct OpenAI Platform API access; use Codex when you rely on your ChatGPT subscription and Codex cloud.

   textCopy

   Route summary:
   *   `openai/gpt-5.4` = direct OpenAI Platform API route
   *   Requires `OPENAI_API_KEY` (or equivalent OpenAI provider config)
   *   In OpenClaw, ChatGPT/Codex sign-in is routed through `openai-codex/*`, not `openai/*`
   
   Route summary:
   *   `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth route
   *   Uses ChatGPT/Codex sign-in, not a direct OpenAI Platform API key
   *   Provider-side limits for `openai-codex/*` can differ from the ChatGPT web/app experience

2. 2

   Onboard OpenClaw with an OpenAI API key

   If you choose the direct OpenAI Platform route, run the OpenClaw onboarding wizard with the OpenAI API key option. You can run it interactively or wire it into automation by passing `OPENAI_API_KEY` non-interactively.

   bashCopy

   openclaw onboard --auth-choice openai-api-key
   # or non-interactive
   openclaw onboard --openai-api-key "$OPENAI_API_KEY"

3. 3

   Set GPT‑5.4 as the default model using the OpenAI API key

   4` by default. This snippet also wires your `OPENAI_API_KEY` into the environment OpenClaw reads.

   jsonCopy

   {
     env: { OPENAI_API_KEY: "sk-..." },
     agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
   }

4. 4

   Onboard OpenClaw with a Codex (ChatGPT) subscription

   If you prefer to use your ChatGPT/Codex subscription instead of an API key, run the onboarding flow with the Codex auth choice. You can either let the wizard drive OAuth or call the Codex login directly when you script this.

   bashCopy

   # Run Codex OAuth in the wizard
   openclaw onboard --auth-choice openai-codex
   
   # Or run OAuth directly
   openclaw models auth login --provider openai-codex

5. 5

   Set GPT‑5.4 as the default model using Codex OAuth

   4 route so OpenClaw uses ChatGPT/Codex OAuth instead of the API key path. This keeps the model ID consistent while swapping the underlying transport and auth.

   jsonCopy

   {
     agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
   }

6. 6

   Tune the OpenAI interaction style

   OpenClaw ships an OpenAI-specific prompt overlay that makes responses warmer and more expressive. Keep it on for a friendly tone, or turn it off if you want the raw base OpenClaw system prompt.

   jsonCopy

   {
     plugins: {
       entries: {
         openai: {
           config: {
             personality: "friendly",
           },
         },
       },
     },
   }
   
   {
     plugins: {
       entries: {
         openai: {
           config: {
             personality: "off",
           },
         },
       },
     },
   }
   
   openclaw config set plugins.entries.openai.config.personality off

7. 7

   Configure OpenAI image and video generation defaults

   If you want OpenClaw’s shared tools to use OpenAI for images and video, set the default image and video models. This lets your agents call `image_generate` and `video_generate` without specifying provider details each time.

   jsonCopy

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

8. 8

   Control transport, warm-up, and fast mode for OpenAI routes

   Fine-tune how OpenClaw talks to OpenAI by setting transport, WebSocket warm-up, priority processing, and fast mode. These options help you balance latency, reliability, and cost for both `openai/*` and `openai-codex/*` models.

   jsonCopy

   {
     agents: {
       defaults: {
         model: { primary: "openai-codex/gpt-5.4" },
         models: {
           "openai-codex/gpt-5.4": {
             params: {
               transport: "auto",
             },
           },
         },
       },
     },
   }
   
   {
     agents: {
       defaults: {
         models: {
           "openai/gpt-5.4": {
             params: {
               openaiWsWarmup: false,
             },
           },
         },
       },
     },
   }
   
   {
     agents: {
       defaults: {
         models: {
           "openai/gpt-5.4": {
             params: {
               openaiWsWarmup: true,
             },
           },
         },
       },
     },
   }
   
   {
     agents: {
       defaults: {
         models: {
           "openai/gpt-5.4": {
             params: {
               serviceTier: "priority",
             },
           },
           "openai-codex/gpt-5.4": {
             params: {
               serviceTier: "priority",
             },
           },
         },
       },
     },
   }
   
   {
     agents: {
       defaults: {
         models: {
           "openai/gpt-5.4": {
             params: {
               fastMode: true,
             },
           },
           "openai-codex/gpt-5.4": {
             params: {
               fastMode: true,
             },
           },
         },
       },
     },
   }

9. 9

   Enable or disable OpenAI Responses server-side compaction

   4, you can control OpenAI’s server-side compaction hints from OpenClaw. Use these settings when you want to tweak how aggressively OpenAI compacts context or when you need to turn it off.

   jsonCopy

   {
     agents: {
       defaults: {
         models: {
           "azure-openai-responses/gpt-5.4": {
             params: {
               responsesServerCompaction: true,
             },
           },
         },
       },
     },
   }
   
   {
     agents: {
       defaults: {
         models: {
           "openai/gpt-5.4": {
             params: {
               responsesServerCompaction: true,
               responsesCompactThreshold: 120000,
             },
           },
         },
       },
     },
   }
   
   {
     agents: {
       defaults: {
         models: {
           "openai/gpt-5.4": {
             params: {
               responsesServerCompaction: false,
             },
           },
         },
       },
     },
   }

Configuration

Troubleshooting

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

Frequently asked questions