Add a custom model provider in OpenClaw

Back up the active configuration and confirm the protocol

Website under maintenance. These are planned configuration examples: api.ubtl.net is a planned domain, no real API test has been performed, and OpenClaw connectivity is unverified. Confirm the OpenAI-compatible request paths, chosen protocol, authentication requirements, and model identifiers before use.

Locate the active profile and configuration file first. A typical location is ~/.openclaw/openclaw.json, but use the file actually loaded by your current profile. Pause relevant work or choose a suitable maintenance window, back up the original, and merge the blocks below. Do not replace a complete existing configuration with this example; preserve other providers, tool permissions, and communication settings.

Merge the provider and model reference

This is valid JSON with models.mode set to merge and ubtl added as a provider. The api value openai-completions is an OpenClaw interface selector; confirm that the corresponding protocol is supported rather than inferring compatibility from /v1 in a URL. Use the same confirmed identifier in the model list and agents.defaults.model.primary, with the provider prefix in the latter.

The apiKey field references ${UBTL_API_KEY}; do not replace it with a plaintext secret. Set UBTL_API_KEY to a future authorized value in the environment of the process that actually launches the gateway. A variable in an interactive terminal is not automatically available to a background service. YOUR_MODEL_ID and the display name assert no model capabilities, context limit, or price.

{
  "models": {
    "mode": "merge",
    "providers": {
      "ubtl": {
        "baseUrl": "https://api.ubtl.net/v1",
        "apiKey": "${UBTL_API_KEY}",
        "api": "openai-completions",
        "models": [
          {"id": "YOUR_MODEL_ID", "name": "UBTL model"}
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {"primary": "ubtl/YOUR_MODEL_ID"}
    }
  }
}

Reload the gateway and validate minimally

Reload or restart the gateway according to your installed version's operating instructions. First check JSON parsing, environment-variable resolution, and the selected model reference. After availability is confirmed, try a short prompt in a test session without external side effects or unnecessary tools. If it fails, check the background process's key environment first, then /v1 URL assembly and API selection, then model permissions. Remove authentication material from diagnostic logs. Restore the backup and reload again if you need to revert.