Use OpenClaw with Models Hub: One-Click Setup and Manual Providers

Configure OpenClaw for Models Hub with one Models Hub CLI command, or edit the models.providers block in openclaw.json manually, with verification and error troubleshooting.

OpenClaw is an open-source, self-hosted personal AI assistant platform that connects messaging apps to AI agents running on your own hardware. Switch its default model to Models Hub and every conversation the Gateway handles uses your Models Hub balance for whichever model you choose. This page covers the connection only, not installing OpenClaw or setting up channels — see the official getting-started guide for that.

Three things you need

A Models Hub API key, the base URL https://modelsok.com/v1 (note the required /v1), and one or more model names.

Prerequisites

OpenClaw installed and running: curl -fsSL https://openclaw.ai/install.sh | bash, then openclaw onboard --install-daemon to finish onboarding. openclaw gateway status should show the Gateway healthy and openclaw dashboard should open the Control UI; you don't need to set up channels (Telegram, Discord, etc.) yet.
A Models Hub API key, created on the Tokens page. The token's group must have access to the models you plan to use.

Recommended models

Use case	Model	Pricing	Live status
Everyday conversation	`claude-sonnet-4-6`	Price	Availability and latency
Complex tasks and long context	`gpt-5.5`	Price	Availability and latency
Cheap and fast for always-on small tasks	`gpt-5.4-mini`	Price	Availability and latency

Model names are authoritative on the pricing page.

Option 1: one-command setup (recommended)

The Models Hub CLI writes your API key, base URL and default model into ~/.openclaw/openclaw.json and ~/.openclaw/.env.

curl -fsSL https://modelsok.com/cli/install.sh | sh

After installing, run models and choose OpenClaw from the interactive menu, or run it non-interactively: models configure --target openclaw --api-key <your-api-key>. Full reference: CLI one-command setup.

Option 2: configure providers manually

OpenClaw connects to custom or OpenAI-compatible model gateways through models.providers. Export your key first, then edit ~/.openclaw/openclaw.json:

export MODELSOK_API_KEY="your-models-hub-api-key"

{
  models: {
    mode: "merge",
    providers: {
      modelsok: {
        baseUrl: "https://modelsok.com/v1",
        apiKey: "${MODELSOK_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
          { id: "gpt-5.5", name: "GPT-5.5" },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "modelsok/claude-sonnet-4-6",
        fallbacks: ["modelsok/gpt-5.5"],
      },
    },
  },
}

Option	Description
`models.mode`	Set to `merge` so `modelsok` is appended while OpenClaw's built-in providers are kept
`models.providers.modelsok.baseUrl`	Your Models Hub base URL; must include `/v1`
`models.providers.modelsok.apiKey`	Inject via `${MODELSOK_API_KEY}` rather than a literal key
`models.providers.modelsok.api`	Models Hub is an OpenAI-compatible gateway, so use `openai-completions`
`models.providers.modelsok.models`	Each `id` here must exactly match a Models Hub model name
`agents.defaults.model.primary`	The default primary model, in `modelsok/<model>` format

Verify

After saving, reopen openclaw dashboard and start a conversation — a normal reply with the default model shown as modelsok/... means you're connected. You can also run openclaw models list to confirm models with the modelsok/ prefix appear. Then check Usage logs in the Models Hub console for a request under that model name within seconds.

Common errors

Symptom	Cause	Fix
Connection failure on `baseUrl`	Missing `/v1`, the most common setup mistake	Make sure it's `https://modelsok.com/v1`
Default model doesn't show `modelsok/...`	`agents.defaults.model.primary` wasn't changed, or is nested wrong	Recheck against the JSON structure above
`401` / authentication failure	Wrong key, stray whitespace, or a disabled token	Re-copy from the Tokens page
Model not found	The `id` under `models.providers.modelsok.models` doesn't match a real Models Hub name	Check the pricing page
Gateway running as a background service can't read the key	The service process doesn't see the shell's `export`ed variable	Make sure the service's own environment has `MODELSOK_API_KEY`, or use the `.env` written by one-click setup

For foreground troubleshooting, run openclaw gateway --port 18789 and watch the logs. More in Troubleshooting.

FAQ

How is it billed? Per input and output token actually consumed, at the price on each model's pricing page; every request is itemized in usage logs.

How is this different from using a vendor's account directly? Same request format, just a different provider; one key connects multiple vendors' models without registering with each separately.

How do I switch models? Change agents.defaults.model.primary and restart the Gateway, or give models aliases under agents.defaults.models and reference them directly in a conversation.

CLI one-command setup: the same tool also configures Claude Code, Codex and Gemini CLI
Model pricing and model status
Claude Code setup, Codex CLI setup

Use OpenClaw with Models Hub: One-Click Setup and Manual Providers

On this page