> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runbridge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use OpenClaw with RunBridge AI

> Register a RunBridge AI custom provider and choose it as the default OpenClaw model.

[OpenClaw](https://openclaw.ai) supports custom OpenAI-compatible providers. This guide registers a RunBridge AI model and selects it for the agent using Chat Completions.

## Prerequisites

* A current OpenClaw installation. Its [installation guide](https://docs.openclaw.ai/install) currently requires Node.js 24.16+ or 26.1+ for the CLI.
* An active API key from the [RunBridge AI console](https://runbridge.ai/console/token).
* A [text model](/overview/models) that supports Chat Completions, streaming, and tool calling. Replace every `your-model-id` below with the same exact model ID.

## Install OpenClaw

Use the [official installer](https://docs.openclaw.ai/install), which can provision a compatible Node.js version. If installing before configuring the provider, use its **skip onboarding** option. Confirm installation:

```bash theme={null}
openclaw --version
```

## Configure the provider and model

Add the key to the user-level `~/.openclaw/.env` file, or `$OPENCLAW_STATE_DIR/.env` if you use a custom state directory:

```dotenv theme={null}
RUNBRIDGE_API_KEY=your-runbridge-api-key
```

Use the global OpenClaw file or the Gateway's process environment, not a project `.env`. Keep the key outside your project repository.

Locate the active configuration:

```bash theme={null}
openclaw config file
```

Merge this JSON into that file (normally `~/.openclaw/openclaw.json`). Preserve existing providers, agents, and model entries:

```json theme={null}
{
  "models": {
    "mode": "merge",
    "providers": {
      "runbridge": {
        "baseUrl": "https://api.runbridge.ai/v1",
        "apiKey": "${RUNBRIDGE_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "your-model-id",
            "name": "RunBridge AI text model"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "runbridge/your-model-id"
      }
    }
  }
}
```

`runbridge` is your custom provider ID. The `models` entry registers the API model, while `agents.defaults.model.primary` selects it. Merely setting the default does not register a provider. Despite the adapter name `openai-completions`, this configuration sends Chat Completions requests to `/v1/chat/completions` with Bearer authentication.

<Note>
  Only declare model capabilities that the selected model supports. For image input, add `"input": ["text", "image"]` to its model entry after confirming vision support. Set context and output limits from the model's documented limits.
</Note>

## Verify the connection

```bash theme={null}
openclaw config validate
openclaw models list
```

Confirm the registered model appears as `runbridge/your-model-id`. For an existing Gateway service, reload the configuration:

```bash theme={null}
openclaw gateway restart
```

For a first installation, complete the [official onboarding flow](https://docs.openclaw.ai/start/onboarding-overview) while retaining your existing custom model configuration. Open a new chat and ask: **Reply with CONNECTED only.** This makes a real API request and may incur usage. Check a small coding task separately to verify tool calling.

## Troubleshooting

| Symptom | Check |
| - | - |
| `RUNBRIDGE_API_KEY` is unresolved or HTTP 401 | Put the key in the global OpenClaw `.env` or Gateway process environment, then restart the Gateway. A terminal export may not reach an already running service. |
| Unknown model/provider | Register `models.providers.runbridge.models` and use exactly the same ID in `agents.defaults.model.primary`. |
| HTTP 404 | Keep `/v1` in `baseUrl` and use `api: openai-completions`. Do not append the request path manually. |
| Model ignores images or tool calls fail | Confirm the endpoint and model support those capabilities, then set the matching model metadata. |
| Config validation fails | Preserve the surrounding JSON/JSON5 structure and merge existing objects and arrays rather than replacing the entire file. |

See OpenClaw's [custom provider reference](https://docs.openclaw.ai/concepts/model-providers/custom-providers) and [environment variable reference](https://docs.openclaw.ai/help/environment) for further details.

<script type="application/ld+json">
  {`
    {
    "@context": "https://schema.org",
    "@type": "TechArticle",
    "headline": "Use OpenClaw with RunBridge AI",
    "description": "Register a RunBridge AI custom provider and choose it as the default OpenClaw model.",
    "url": "https://runbridge.mintlify.site/integrations/openclaw",
    "publisher": {
      "@type": "Organization",
      "name": "RunBridge AI"
    }
    }
    `}
</script>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.