OpenClaw + OpenAI: The Proven GPT Integration Guide [2024]

OpenAI is the most-used LLM provider in OpenClaw deployments, and the integration is genuinely straightforward. What separates builders whose agents perform well from those who hit 429 errors at 3am is the four extra lines of config most guides never mention. Here's the full setup — including the parts that bite you later.

OpenAI API Key Setup

Go to platform.openai.com → API keys → Create new secret key. Give it a descriptive name like "openclaw-production" so you can identify it in usage logs. Copy it immediately — OpenAI shows the full key only once.

Store the key in an environment variable, not in gateway.yaml directly. This is non-negotiable for any deployment that goes near version control.

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

For persistent configuration on Linux/macOS, add this line to your ~/.bashrc or ~/.zshrc. For Docker deployments, pass it via the -e flag or a .env file. For cloud deployments, use your platform's secrets manager.

gateway.yaml Configuration for OpenAI

Here's the production-ready OpenAI configuration block for gateway.yaml:

llm:
  provider: openai
  model: gpt-4o
  api_key: ${OPENAI_API_KEY}
  streaming: true
  max_tokens: 4096
  temperature: 0.7
  timeout: 30
  retry_attempts: 2
  fallback:
    provider: openai
    model: gpt-3.5-turbo
    api_key: ${OPENAI_API_KEY}

Walk through each field that isn't obvious:

• streaming — sends tokens to the output channel as they're generated rather than waiting for the full response
• max_tokens — caps the output length per request; prevents runaway completions from burning your quota
• temperature — 0.7 is the right default for conversational agents; drop to 0.2 for factual/analytical tasks
• timeout — 30 seconds handles most GPT-4o requests; complex tasks occasionally need more
• fallback — using GPT-3.5-turbo as fallback means agents keep responding even during GPT-4o incidents

GPT-4o vs GPT-4-turbo: Which Model to Choose

This is where most teams overthink it. Here's the decision:

Use GPT-4o. It's faster than GPT-4-turbo, cheaper, and performs comparably on almost every agent task. GPT-4-turbo made sense in 2023. As of early 2025, GPT-4o is the clear default choice.

Handling OpenAI Rate Limits

Rate limits are the most common reason OpenClaw agents fail in production. OpenAI enforces limits at two levels: requests per minute (RPM) and tokens per minute (TPM).

Here's what you actually get on each tier as of early 2025:

• Free tier — 3 RPM, 40k TPM on GPT-4o. Not viable for production.
• Tier 1 ($5 spent) — 500 RPM, 30k TPM. Good for development and low-traffic agents.
• Tier 2 ($50 spent) — 5,000 RPM, 450k TPM. Handles most production agent workloads.
• Tier 3 ($100 spent) — 5,000 RPM, 800k TPM. For high-volume deployments.

Cost Management

Set a hard spending limit before your first production deployment. In the OpenAI dashboard: Settings → Billing → Usage limits → Set monthly budget. OpenAI sends an alert email when you hit 85% and cuts off the API at 100%. This prevents runaway agent loops from generating unexpected bills.

In gateway.yaml, set max_tokens: 4096 to cap per-request output length. An agent that accidentally enters a generation loop with no token limit can exhaust a $100 monthly budget in under an hour. The cap costs nothing when responses are shorter than the limit and saves you when something goes wrong.

Streaming Responses

Streaming makes your agents feel dramatically faster without changing the underlying latency. Instead of waiting 8 seconds for a full GPT-4o response, users see the first tokens in under a second and watch the response build in real time.

Enable it with one line in gateway.yaml:

llm:
  provider: openai
  model: gpt-4o
  api_key: ${OPENAI_API_KEY}
  streaming: true  # Add this

OpenClaw handles the streaming protocol with OpenAI and forwards tokens to your output channel as they arrive. For Telegram channels, users see the typing indicator immediately and the response populates progressively. For API channels, you receive a stream of events rather than a single response payload.

Function Calling With OpenClaw Tools

OpenClaw's tool system is a direct abstraction over OpenAI function calling. When you define tools in your agent config, OpenClaw formats them as OpenAI function definitions automatically. You never need to implement the function call/response cycle manually.

Here's how the mapping works:

# In your agent config:
tools:
  - name: search_web
    description: "Search the web for current information"
    parameters:
      query:
        type: string
        description: "The search query"
        required: true

# OpenClaw converts this to OpenAI format automatically:
# {"type": "function", "function": {"name": "search_web", ...}}

When GPT-4o decides to call a tool, OpenClaw intercepts the function call, executes the tool, and returns the result in the format OpenAI expects — all transparently. Your agent config stays provider-agnostic.

Common Mistakes

• Using the wrong API key format — new OpenAI keys start with sk-proj- for project keys. If you're getting 401 errors, check that you're not mixing an old format key with a project-scoped API.
• Not setting a monthly budget — set it before your first production agent goes live, not after the first unexpected bill.
• Skipping streaming — the perceived performance difference is significant. Enable it from day one.
• Setting temperature to 0 for everything — temperature 0 makes conversational agents feel robotic. Use 0 for structured data extraction, 0.7 for conversation.
• Not handling 429s in the fallback config — configure a fallback model so rate limits don't cascade to user-visible errors.

Frequently Asked Questions

How do I connect OpenClaw to OpenAI?

Set provider: openai, model: gpt-4o, and api_key: your-key in the llm section of gateway.yaml, then restart the gateway. OpenClaw initializes the OpenAI client on startup and routes all agent LLM calls through it automatically.

Which OpenAI model should I use with OpenClaw?

GPT-4o is the best default — it balances capability and cost better than GPT-4-turbo and runs faster. Use GPT-4-turbo only if you need a legacy integration. Use GPT-4o-mini for high-volume, low-complexity tasks where cost is the primary constraint.

Does OpenClaw support OpenAI function calling?

Yes. OpenClaw's tool system maps directly to OpenAI function calling. Define tools in your agent config and OpenClaw automatically formats them as OpenAI function definitions, handling the entire function call/response cycle transparently.

How do I handle OpenAI rate limits in OpenClaw?

Configure retry_attempts: 2 and timeout: 30 in the llm section. OpenClaw retries on 429 rate limit errors with exponential backoff automatically. For sustained high volume, upgrade to OpenAI Tier 2 — it gives 5,000 RPM on GPT-4o.

Can OpenClaw stream OpenAI responses?

Yes. Add streaming: true to the llm section in gateway.yaml. OpenClaw streams tokens from OpenAI and forwards them to the output channel in real time. Users see responses appear progressively rather than waiting for the full completion.

How do I manage OpenAI costs with OpenClaw?

Set a monthly spending limit in the OpenAI dashboard under Billing. In OpenClaw, configure max_tokens: 4096 to cap per-request token usage. GPT-4o costs $5 per million input tokens and $15 per million output tokens as of early 2025.