OpenClaw Custom Provider Setup

Open this owner page only if OpenClaw already owns the provider layer in your stack. Use it to get one routed request working first; broader wrapper or SDK choices belong on the hub pages linked below.

If you landed here from a broad guides or integrations route and only need the right owner page, use Framework and Tool Wrapper Guides for wrapper choices or OpenAI SDK Compatibility for shared base URL, auth, and request-shape setup.

Fast path

Use this path when OpenClaw onboarding already fits your setup. You need an OpenClaw install, a GonkaGate API key, and a model ID from Get models.

Interactive onboarding

openclaw onboard

Non-interactive onboarding

openclaw onboard --non-interactive \
  --auth-choice custom-api-key \
  --custom-base-url "https://api.gonkagate.com/v1" \
  --custom-model-id "qwen/qwen3-235b-a22b-instruct-2507-fp8" \
  --custom-api-key "$GONKAGATE_API_KEY" \
  --custom-compatibility openai

If your installed OpenClaw version exposes different flags, check the OpenClaw onboard reference.

Verify after onboarding

openclaw models list
openclaw models status

/models
/model qwen3-235b
/status

Confirm that:

• qwen3-235b appears in /models.
• /model qwen3-235b switches the active model.
• A test prompt returns a valid answer through GonkaGate.

Manual config shape

If you need to review or edit the JSON directly, OpenClaw must contain four things:

• GONKAGATE_API_KEY in an env block or another secret source OpenClaw can read.
• A provider entry under models.providers.gonkagate.
• The exact GonkaGate model ID inside the provider models[] list.
• A fully-qualified allowlist key under agents.defaults.models.

Provider definitions usually live in ~/.openclaw/openclaw.json. Older installs may still point to ~/.clawdbot/clawdbot.json, usually as a symlink.

{
  "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"
      }
    }
  }
}

Keep these boundaries straight:

• api must be openai-completions so OpenClaw sends requests to the OpenAI-compatible /chat/completions path.
• baseUrl must be https://api.gonkagate.com/v1.
• The provider id must match the exact GonkaGate model ID.
• The shorter alias belongs only in agents.defaults.models, not in the provider id.

Apply and verify

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

openclaw gateway config.apply --file ~/.openclaw/openclaw.json

If your build does not support config.apply yet, restart the gateway instead:

openclaw gateway restart

Then run both CLI and chat-level checks:

• openclaw models list to confirm the provider metadata loaded.
• openclaw models status to confirm the gateway sees the provider.
• /models to confirm the alias is visible.
• /model qwen3-235b plus /status to confirm the selected model changed.
• One test prompt to confirm a full request path through GonkaGate.

Common failures

model not allowed

The allowlist entry is missing or malformed.

1. Use the fully-qualified key gonkagate/qwen/qwen3-235b-a22b-instruct-2507-fp8.
2. Keep qwen3-235b only as the alias value.
3. Re-apply the config after editing JSON.

The model does not appear in /models

Usually one half is missing: provider metadata or allowlist entry.

1. Confirm models.providers.gonkagate.models[] contains the model ID.
2. Confirm agents.defaults.models contains the matching fully-qualified key.
3. Apply the config again and re-run /models.

The wrong model gets called

OpenClaw can only forward the model ID you put in the provider config.

1. Set id exactly to qwen/qwen3-235b-a22b-instruct-2507-fp8.
2. Do not shorten or rename that ID in the provider block.
3. Keep the alias only in the allowlist entry.

Auth or base URL errors

Validate the shared connection values before you keep debugging OpenClaw internals.

1. Confirm the base URL is https://api.gonkagate.com/v1.
2. Confirm the API key starts with gp-.
3. Check for JSON syntax mistakes before re-applying the config.

Related pages

• Get models for current machine-readable model IDs before editing provider config.
• Authentication and API Keys for key creation, header format, and rotation.
• API Reference Overview for the exact request and response contract after OpenClaw forwards the call.
• API Error Handling for request IDs, retry decisions, and escalation flow once the provider path works.