OpenClaw ClipProxy Provider Models: Configuring GPT-5.4

If you're setting up OpenClaw with ClipProxy as your provider gateway, the model configuration JSON is where everything starts. Searches for "id": "gpt-5.4" and "name": "gpt-5.4" tell us people are looking at the provider models config and trying to figure out how to wire GPT-5.4 into their agent stack. This guide covers exactly that: how the ClipProxy provider models schema works, how to register GPT-5.4 (or any model), and the gotchas that trip people up.

What Is ClipProxy in OpenClaw?

ClipProxy is a lightweight proxy layer that sits between your AI agent and the upstream LLM providers. Instead of hardcoding API endpoints and model names directly into your agent configuration, you define a set of provider models in ClipProxy's config. The agent talks to ClipProxy, and ClipProxy routes requests to the right provider based on the model ID you specify.

This is useful for several reasons:

• You can swap models without changing agent code
• You can define aliases (your agent requests "gpt-5.4" and ClipProxy maps it to the correct OpenAI endpoint and API version)
• You can set per-model rate limits, timeouts, and fallback behavior
• You can run multiple providers behind a single interface

The Provider Models JSON Schema

The core of ClipProxy configuration is the provider_models array. Each entry defines a model your agent can request by name. Here is what a GPT-5.4 entry looks like:

{
  "provider_models": [
    {
      "id": "gpt-5.4",
      "name": "gpt-5.4",
      "provider": "openai",
      "endpoint": "https://api.openai.com/v1/chat/completions",
      "api_key_env": "OPENAI_API_KEY",
      "max_tokens": 32768,
      "context_window": 256000,
      "supports_vision": true,
      "supports_tools": true,
      "rate_limit": {
        "requests_per_minute": 500,
        "tokens_per_minute": 200000
      }
    }
  ]
}

The id field is what your agent uses to request this model. The name field is the display name (used in logs and dashboards). For most setups, id and name are identical, but you can set name to something human-readable like "GPT 5.4 (Production)" while keeping id as the machine-friendly slug.

Field Reference

| Field | Required | Description | |---|---|---| | id | Yes | Unique identifier the agent uses to request this model | | name | Yes | Display name for logs, dashboards, and debug output | | provider | Yes | Provider type: openai, anthropic, ollama, azure, custom | | endpoint | Yes | Full URL to the provider's chat completions endpoint | | api_key_env | Yes | Environment variable name holding the API key | | max_tokens | No | Maximum output tokens per request (default: provider default) | | context_window | No | Total context window size in tokens | | supports_vision | No | Whether the model accepts image inputs (default: false) | | supports_tools | No | Whether the model supports tool/function calling (default: false) | | rate_limit | No | Per-model rate limiting config | | fallback_to | No | Model id to fall back to if this model is unavailable | | priority | No | Routing priority when multiple models match (lower = higher priority) |

How Request Routing Works

When your OpenClaw agent sends a request with "model": "gpt-5.4", ClipProxy follows this path:

1. ClipProxy looks up the id in its provider models list
2. If found, it checks the rate limit counters for that model
3. If under the limit, it forwards the request to the configured endpoint with the correct API key
4. If rate limited (or the provider returns a 429/503), ClipProxy checks the fallback_to field and reroutes to the fallback model
5. If no fallback is configured, it returns the error to the agent

Registering Multiple Models

Most production setups register several models. Here is a typical multi-provider config:

{
  "provider_models": [
    {
      "id": "gpt-5.4",
      "name": "gpt-5.4",
      "provider": "openai",
      "endpoint": "https://api.openai.com/v1/chat/completions",
      "api_key_env": "OPENAI_API_KEY",
      "max_tokens": 32768,
      "context_window": 256000,
      "supports_vision": true,
      "supports_tools": true,
      "fallback_to": "claude-opus-4-6",
      "priority": 1
    },
    {
      "id": "claude-opus-4-6",
      "name": "claude-opus-4-6",
      "provider": "anthropic",
      "endpoint": "https://api.anthropic.com/v1/messages",
      "api_key_env": "ANTHROPIC_API_KEY",
      "max_tokens": 32768,
      "context_window": 200000,
      "supports_vision": true,
      "supports_tools": true,
      "fallback_to": "local-llama",
      "priority": 2
    },
    {
      "id": "local-llama",
      "name": "local-llama",
      "provider": "ollama",
      "endpoint": "http://localhost:11434/v1/chat/completions",
      "api_key_env": "",
      "max_tokens": 8192,
      "context_window": 32000,
      "supports_vision": false,
      "supports_tools": false,
      "priority": 3
    }
  ]
}

The priority field determines which model to try first when the agent doesn't specify a model explicitly. Lower numbers mean higher priority. Combined with fallback_to, this creates a chain: GPT-5.4 first, then Claude Opus if OpenAI is down, then a local Llama instance as the last resort.

GPT-5.4 Specific Configuration

GPT-5.4 is OpenAI's latest flagship model as of early 2026. A few things to know when configuring it in ClipProxy:

| Property | GPT-5.4 Value | Notes | |---|---|---| | Context window | 256K tokens | Largest context window in the GPT series | | Max output | 32K tokens | Configurable via max_tokens | | Vision support | Yes | Accepts base64 and URL image inputs | | Tool calling | Yes | Parallel tool calls supported | | Streaming | Yes | SSE streaming via standard OpenAI format | | Rate limits (Tier 5) | 10K RPM / 2M TPM | Varies by org tier, set conservative limits in ClipProxy |

When setting rate_limit in your ClipProxy config, always set it slightly below your actual OpenAI tier limits. If your org is Tier 3 with 3,500 RPM, set ClipProxy to 3,000 RPM. This gives you a buffer before hitting 429s and lets ClipProxy's fallback logic trigger proactively rather than reactively.

Validating Your Configuration

Before starting the agent, validate the config with the built-in check command:

openclaw config validate

This verifies:

• All id fields are unique
• All fallback_to references point to existing model IDs (no circular chains)
• All api_key_env variables are set in the environment
• All endpoint URLs are reachable (optional, with --check-endpoints)

A common mistake is setting fallback_to to a model ID that doesn't exist in the config, which silently fails at runtime. The validate command catches this.

# Quick connectivity check
openclaw config validate --check-endpoints

If validation passes, start your agent normally:

openclaw start --config ./cliproxy-config.json

Common Pitfalls

• Mismatched id and actual model name: If you set "id": "gpt-5.4" but the OpenAI endpoint expects "model": "gpt-5.4-2026-02" (the full version string), requests will fail with a model-not-found error. Check OpenAI's model list to confirm the exact string. ClipProxy passes the id as the model parameter unless you add a model_override field.

• Circular fallback chains: Setting model A's fallback_to as model B, and model B's fallback_to as model A, creates an infinite loop. ClipProxy detects this at startup and refuses to load, but only if you run config validate first.

• Missing environment variables: Setting "api_key_env": "OPENAI_API_KEY" requires that variable to be exported in the shell where OpenClaw runs. If you're using systemd or launchd to manage the process, environment variables from your shell profile won't be available. Pass them explicitly in the service definition.

• Rate limit math on shared keys: If multiple OpenClaw instances share the same API key, each instance's rate limit counter is local. You could have three instances each configured for 1,000 RPM, sending a combined 3,000 RPM to a 3,500 RPM tier. Set per-instance limits to floor(tier_limit / instance_count).

Model Override for Versioned Endpoints

When OpenAI releases a point version (like gpt-5.4-2026-02), you may want your agent to keep requesting "gpt-5.4" while ClipProxy sends the full version string to the API. Use the model_override field:

{
  "id": "gpt-5.4",
  "name": "gpt-5.4",
  "provider": "openai",
  "model_override": "gpt-5.4-2026-02",
  "endpoint": "https://api.openai.com/v1/chat/completions",
  "api_key_env": "OPENAI_API_KEY"
}

This way, updating to a new point release is a one-line config change. No agent code changes, no redeployment of the agent itself. Just update the config and restart ClipProxy.

Connecting This to Desktop Agents

If you're running OpenClaw as a desktop agent (the primary use case), ClipProxy's model config determines which LLM powers every action the agent takes on your machine. For tasks like reading your screen, clicking UI elements, and automating workflows across apps, model selection matters:

• GPT-5.4 excels at multi-step tool calling chains and handles vision inputs well for screen understanding
• Claude Opus tends to pick simpler, more direct approaches to UI automation (fewer intermediate steps)
• Local models work for simple text tasks but struggle with vision and complex tool orchestration

The recommended setup for a desktop agent is GPT-5.4 or Claude Opus as primary, with a local model as the offline fallback. This keeps the agent functional even when you lose internet connectivity.

Minimal Working Configuration

Here is the smallest valid ClipProxy config for GPT-5.4:

{
  "provider_models": [
    {
      "id": "gpt-5.4",
      "name": "gpt-5.4",
      "provider": "openai",
      "endpoint": "https://api.openai.com/v1/chat/completions",
      "api_key_env": "OPENAI_API_KEY"
    }
  ]
}

Save this to cliproxy-config.json, export your API key, validate, and start:

export OPENAI_API_KEY="sk-..."
openclaw config validate --config ./cliproxy-config.json
openclaw start --config ./cliproxy-config.json

Everything else (rate limits, fallbacks, vision flags) is optional. The defaults are sensible for getting started. Add complexity only when you need it.

Wrapping Up

ClipProxy's provider models config is the control plane for which LLMs your OpenClaw agent can use. The "id": "gpt-5.4" and "name": "gpt-5.4" entries define how your agent addresses the model, while the rest of the fields handle routing, rate limiting, and fallback logic. Start with a single model entry, validate it, and expand from there.

Fazm is an open source macOS AI agent. Open source on GitHub.