OpenClaw Integration with The Grid | Custom Backend Setup

Set up OpenClaw with The Grid as a custom OpenAI-compatible backend. Add a provider, allowlist instruments, and restart the gateway.

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.

• 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:

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:

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

"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.

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:

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

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

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

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.

402 Payment Required. Your credits are at zero. Top up at app.thegrid.ai.

Adding The Grid removed your built-in providers. You forgot "mode": "merge" in the models section. Add it and restart the gateway.

"Gateway service not loaded" when restarting. You haven't installed the gateway service yet. Run openclaw gateway install first, then openclaw gateway restart.

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.