# OpenClaw

OpenClaw talks to The Grid the same way it talks to any OpenAI-compatible or Anthropic-compatible endpoint: as a custom provider in `openclaw.json`. No plugin, no proxy. The same Grid consumption key works for both API paths.

## Prerequisites

* OpenClaw installed with a recent gateway version (`openclaw --version`).
* A Grid account at [app.thegrid.ai](https://app.thegrid.ai).
* Credits in your account. The Grid is prepaid; zero credits returns 402.
* A Grid consumption API key from **Settings → API Keys → Create Consumption Key**.

## Setup

### 1. Store your Grid key

Add to `~/.openclaw/.env`:

```bash
THEGRID_API_KEY=your-consumption-api-key
```

### 2. Add The Grid to `openclaw.json`

On a fresh install, run `openclaw setup` (or create the file with `{}`) before editing. Then add The Grid under `models.providers`. Use the live instrument IDs from the [current instruments list](/docs/instrument-specifications/current-instruments.md):

```json
{
  "gateway": { "mode": "local" },
  "models": {
    "mode": "merge",
    "providers": {
      "thegrid": {
        "baseUrl": "https://api.thegrid.ai/v1",
        "apiKey": "${THEGRID_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "code-prime", "name": "Code Prime", "reasoning": true, "input": ["text"], "contextWindow": 128000, "maxTokens": 128000 },
          { "id": "code-max", "name": "Code Max", "reasoning": true, "input": ["text"], "contextWindow": 1000000, "maxTokens": 128000 },
          { "id": "agent-prime", "name": "Agent Prime", "reasoning": true, "input": ["text"], "contextWindow": 256000, "maxTokens": 128000 }
        ]
      }
    }
  }
}
```

{% hint style="warning" %}
`"mode": "merge"` is required. Without it, your custom provider replaces OpenClaw's entire built-in catalog. `"gateway": { "mode": "local" }` is also required, or the gateway service exits under launchd.
{% endhint %}

If you prefer the Anthropic Messages path (beta), register a second provider with `"baseUrl": "https://messages-beta.api.thegrid.ai/v1"` and `"api": "anthropic-messages"`. The same consumption key authenticates both surfaces.

### 3. Add instruments to the model allowlist

Still in `openclaw.json`, add the instruments to `agents.defaults.models` so they appear in the `/model` picker:

```json
{
  "agents": {
    "defaults": {
      "model": { "primary": "thegrid/code-prime" },
      "models": {
        "thegrid/code-prime": {},
        "thegrid/code-max": {},
        "thegrid/agent-prime": {}
      }
    }
  }
}
```

### 4. Install or restart the gateway

On a clean machine, install the gateway service before restarting:

```bash
openclaw gateway install
openclaw gateway restart
```

If you would rather not install a persistent service, `openclaw gateway run` runs the gateway in the foreground.

## Verification

```bash
openclaw capability model run --gateway --model thegrid/code-prime --prompt "ping" --json
```

A valid completion confirms end-to-end routing. `openclaw models status --probe` is fine for pre-flight, but it can report OK when a real call still fails, so prefer the capability run for the real check.

## Troubleshooting

{% hint style="warning" %}
**401 Unauthorized.** The key in `openclaw.json` (or the env var it references) is a Grid trading key, not a consumption key. Trading keys do not authorize inference.
{% endhint %}

{% hint style="warning" %}
**402 Payment Required.** Your credits are at zero. Top up at [app.thegrid.ai](https://app.thegrid.ai).
{% endhint %}

{% hint style="warning" %}
**Adding The Grid removed your built-in providers.** You forgot `"mode": "merge"` in the `models` section. Add it and restart the gateway.
{% endhint %}

{% hint style="info" %}
**"Gateway service not loaded" when restarting.** You haven't installed the gateway service yet. Run `openclaw gateway install` first, then `openclaw gateway restart`.
{% endhint %}

{% hint style="info" %}
**Instruments don't appear in `/model`.** Confirm both halves of the config: the provider block under `models.providers` and the allowlist entries under `agents.defaults.models`.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://thegrid.ai/docs/integrations-and-best-practices/integrations/openclaw.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.