Configure OpenClaw to Call Models via CLIProxyAPI (Copy-Paste Ready)

If you already have a CLIProxyAPI endpoint and want OpenClaw to call models through the proxy instead of calling the provider directly, this guide gives you a copy-paste-ready configuration.

1) Where is CLIProxyAPI connected into OpenClaw?

In OpenClaw, model routing is determined in two layers:

1. Provider layer (models.providers)
   Declare the proxy endpoint + the list of models that OpenClaw can see.
2. Agent routing layer (agents.defaults.model and agents.list[].model)
   Select the primary model (primary) and fallback models (fallbacks) in the format:
3. provider/model-id
   Example: cliproxy/gpt-5-mini

2) Minimal configuration sample for models.providers.cliproxy

Open the file:

nano ~/.openclaw/openclaw.json

Add (or update) the following block:

{
  "models": {
    "mode": "replace",
    "providers": {
      "cliproxy": {
        "baseUrl": "https://proxy.naai.studio/v1",
        "apiKey": "<YOUR_CLIPROXY_API_KEY>",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-5-mini",
            "name": "GPT 5 Mini",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 1000000,
            "maxTokens": 8192
          },
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 1000000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

Quick explanation of key fields

• baseUrl: CLIProxyAPI endpoint (must include /v1 if the proxy uses an OpenAI-compatible standard).
• apiKey: key for OpenClaw to auth into the proxy.
• api: in real configurations this is openai-completions.
• models[].id: must exactly match the model ID exposed by the proxy.
• models.mode: "replace": use the models you declare to replace the default list.

3) Set primary + fallback models for the default agent

After you have a provider, set the model routing in agents.defaults.model:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "cliproxy/gpt-5-mini",
        "fallbacks": [
          "cliproxy/claude-opus-4-6",
          "anthropic/claude-opus-4-6",
          "openai-codex/gpt-5.3-codex"
        ]
      }
    }
  }
}

Principles:
- primary should be a cheap/fast model for most tasks.
- fallbacks should mix multiple providers to increase availability when the proxy or quota fails.

Important note: to be able to select additional models directly in the chat UI, you must declare the model list under fallbacks in the agent configuration.

4) Per-agent override (if needed)

If you have multiple personas/workspaces (e.g. personal, work), you can override models individually under agents.list[]:

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "model": {
          "primary": "openai-codex/gpt-5.1-codex-mini",
          "fallbacks": [
            "cliproxy/claude-opus-4-6",
            "cliproxy/gemini-3-pro-preview"
          ]
        }
      }
    ]
  }
}

The nice part: you still keep cliproxy/* in the fallbacks so the session is automatically "rescued" when the primary model fails.

5) Verification checklist after saving the configuration

1. Check JSON validity (no trailing commas, brackets properly closed).
2. Call the proxy models endpoint (ensure key/URL are correct).
3. Restart OpenClaw.
4. Test a short prompt to confirm the primary model works.
5. Test a fallback scenario (temporarily disable the primary or use an invalid model ID to observe fallback switching).

6) Common errors and quick fixes

401 Unauthorized error

• Incorrect apiKey or the key has been revoked.
• Fix: create a new key and update models.providers.cliproxy.apiKey.

404 / model not found error

• baseUrl has an incorrect path or the model id does not exist on the proxy.
• Fix: double-check /v1 and sync model IDs with the list returned by the proxy.

No fallback even though primary fails

• Incorrect model route format (missing provider prefix, e.g. using gpt-5-mini instead of cliproxy/gpt-5-mini).
• Fix: always use the full provider/model-id format.

7) Security when working with openclaw.json

• Do not commit ~/.openclaw/openclaw.json to git.
• Do not paste real tokens into public tickets/chats.
• If a key has ever been exposed, rotate it immediately (API key, bot token, gateway token).
• When sharing configurations, replace all secrets with placeholders.

Conclusion

To integrate CLIProxyAPI into OpenClaw reliably, just remember 3 points:
1. Correctly declare models.providers.cliproxy.
2. Route primary/fallback with the proper provider/model-id format.
3. Verify after every configuration change.

If you follow these 3 steps, you can both leverage your existing account via the proxy and keep the agent system stable when provider errors occur.