OpenClaw 🦞 + GonkaGate: Step-by-Step Integration

Configure GonkaGate as a custom OpenAI-compatible provider in OpenClaw, then verify routing with a fully working model allowlist setup.

Need the full docs hub? Go to Docs overview for quickstart and API reference.

Why use a custom provider in OpenClaw?

Custom providers let you keep OpenClaw workflows while routing requests through GonkaGate. You keep OpenAI-compatible semantics and configure model access explicitly via allowlist rules.

What you'll need

Before setup, prepare these prerequisites:

• OpenClaw installed and running (openclaw CLI available).
• A GonkaGate API key from your dashboard.
• Access to OpenClaw chat commands and terminal commands.
• Access to edit JSON config (~/.openclaw/openclaw.json).

Easy way: let OpenClaw configure it for you

If you already use OpenClaw chat, you can ask it to create the provider and allowlist entries automatically.

Paste this prompt into OpenClaw chat and replace the API key placeholder:

Add GonkaGate as a custom provider to my OpenClaw config. Use these details:

- Provider name: gonkagate
- Base URL: https://api.gonkagate.com/v1
- API key: [PASTE YOUR GONKAGATE API KEY HERE]
- API type: openai-completions

Add this model:
- qwen/qwen3-235b-a22b-instruct-2507-fp8

Create alias "qwen3-235b", allowlist it in agents.defaults.models, apply the config, and restart the gateway if needed.

CLI onboarding (fast path)

Use interactive onboarding for local setup, or non-interactive flags for scripts and CI.

# Recommended for first setup
openclaw onboard

Quick verification after onboarding

Check that OpenClaw can list models and resolve the configured GonkaGate model.

# CLI verification
openclaw models list
openclaw models status

# In OpenClaw chat
/models
/model qwen3-235b
/status

Step 1: Find your OpenClaw config

Provider definitions and allowlist rules live in your OpenClaw config file.

cat ~/.openclaw/openclaw.json

Step 2: Add GonkaGate as provider

Add a provider entry in models.providers and define the supported GonkaGate model metadata.

{
  "env": {
    "GONKAGATE_API_KEY": "gp-..."
  },
  "models": {
    "mode": "merge",
    "providers": {
      "gonkagate": {
        "baseUrl": "https://api.gonkagate.com/v1",
        "apiKey": "${GONKAGATE_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen/qwen3-235b-a22b-instruct-2507-fp8",
            "name": "qwen/qwen3-235b-a22b-instruct-2507-fp8",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 262144,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

• Set api to "openai-completions".
• Set baseUrl to https://api.gonkagate.com/v1.
• Use exact model ID: qwen/qwen3-235b-a22b-instruct-2507-fp8.
• Cost fields are local OpenClaw metadata for tracking.

Step 3: Allowlist the fully-qualified model

Provider definition alone is not enough. Add the model to agents.defaults.models with a fully-qualified key and alias.

{
  "agents": {
    "defaults": {
      "models": {
        "gonkagate/qwen/qwen3-235b-a22b-instruct-2507-fp8": {
          "alias": "qwen3-235b"
        }
      }
    }
  }
}

Step 4: Apply config

Apply the edited file so OpenClaw reloads provider and allowlist definitions.

# Apply config after edits
openclaw gateway config.apply --file ~/.openclaw/openclaw.json

# If your OpenClaw build doesn't support config.apply yet
openclaw gateway restart

Full GonkaGate config example

This end-to-end example includes provider config, model metadata, allowlist alias, and default primary model.

{
  "env": {
    "GONKAGATE_API_KEY": "gp-..."
  },
  "models": {
    "mode": "merge",
    "providers": {
      "gonkagate": {
        "baseUrl": "https://api.gonkagate.com/v1",
        "apiKey": "${GONKAGATE_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen/qwen3-235b-a22b-instruct-2507-fp8",
            "name": "qwen/qwen3-235b-a22b-instruct-2507-fp8",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 262144,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "models": {
        "gonkagate/qwen/qwen3-235b-a22b-instruct-2507-fp8": {
          "alias": "qwen3-235b"
        }
      },
      "model": {
        "primary": "gonkagate/qwen/qwen3-235b-a22b-instruct-2507-fp8"
      }
    }
  }
}

Testing checklist

After applying config, validate both CLI and chat-level model selection.

# CLI verification
openclaw models list
openclaw models status

# In OpenClaw chat
/models
/model qwen3-235b
/status

• Run /models and confirm alias qwen3-235b appears.
• Switch with /model qwen3-235b and verify active model in /status.
• Send a test prompt and confirm a valid response path through GonkaGate.

Common errors

"model not allowed"

The model is missing or malformed in agents.defaults.models allowlist.

1. Use fully-qualified key: gonkagate/qwen/qwen3-235b-a22b-instruct-2507-fp8.
2. Keep alias separate (for example qwen3-235b).
3. Re-apply config after JSON edits.

Model does not appear in /models

Usually one half is missing: provider model definition or allowlist entry.

1. Confirm models.providers.gonkagate.models[] contains the model ID.
2. Confirm agents.defaults.models contains matching fully-qualified key.
3. Run config apply/restart and check /models again.

Wrong model gets called

Model id in provider config must match exactly what GonkaGate expects in request body.

1. Set id exactly to qwen/qwen3-235b-a22b-instruct-2507-fp8.
2. Avoid shortened or renamed IDs in provider model definition.
3. Keep alias only in allowlist, not in provider id field.

Connection or auth failures

Validate endpoint and credentials directly against GonkaGate before debugging OpenClaw internals.

curl https://api.gonkagate.com/v1/chat/completions \
  -H "Authorization: Bearer gp-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-235b-a22b-instruct-2507-fp8",
    "messages": [{"role": "user", "content": "hello"}]
  }'

1. Verify baseUrl and API key format (gp-...).
2. Test with direct curl to isolate credential/endpoint issues.

JSON parse/apply errors

Malformed JSON prevents config from applying.

1. Validate JSON syntax (commas, quotes, brackets) before apply.
2. If needed, ask OpenClaw chat to fix config JSON syntax issues.

How request routing works

OpenClaw resolves alias and provider before sending the API call.

1. You select alias qwen3-235b.
2. OpenClaw resolves alias to allowlist key gonkagate/qwen/qwen3-235b-a22b-instruct-2507-fp8.
3. Provider segment gonkagate maps to models.providers.gonkagate.
4. Request is sent to https://api.gonkagate.com/v1/chat/completions.
5. Request body model field remains qwen/qwen3-235b-a22b-instruct-2507-fp8.

Alias selected: qwen3-235b
-> resolved allowlist key: gonkagate/qwen/qwen3-235b-a22b-instruct-2507-fp8
-> provider resolved: gonkagate
-> request target: https://api.gonkagate.com/v1/chat/completions
-> request model field: qwen/qwen3-235b-a22b-instruct-2507-fp8

Fully-qualified names are internal OpenClaw routing keys; GonkaGate receives the provider model id in the request body.

Resources

• OpenClaw documentation
• OpenClaw onboard command reference
• OpenClaw model providers reference
• OpenClaw GitHub repository
• Reference guide that inspired this adaptation

Next steps

Continue with related pages before production rollout:

• Model IDs and availability
• Authentication guide
• Error handling and troubleshooting