Skip to navigation
Integrations

OpenClaw

View as Markdown

OpenClaw logo

Use OpenModels as the upstream model provider for OpenClaw. OpenClaw keeps control of the local Gateway, sessions, channels, tools, and dashboard, while model requests are sent through the OpenModels OpenAI-compatible API.

This guide focuses on OpenClaw calling OpenModels. If you want another app to call OpenClaw’s own /v1 endpoint, see “Use OpenClaw as an OpenAI-compatible endpoint” below.

When to use this

Use this setup when you want:

  • OpenClaw as a self-hosted assistant gateway for chat apps, agents, and local tools.
  • OpenModels as the upstream model marketplace.
  • One OpenModels API key with credit-based billing and model IDs from the Models page.
  • OpenAI-compatible chat completions without changing OpenClaw source code.

Prerequisites

  • OpenClaw installed on the host that runs the Gateway.
  • Node.js 24, or Node.js 22.19 or later.
  • An OpenModels API key in the ale-... format.
  • Available credits in your OpenModels account.
  • A supported OpenModels chat model ID, such as qwen3.5-flash or kimi-k2.7-code.

1. Install and start OpenClaw

On macOS or Linux:

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

The local OpenClaw dashboard usually runs at:

http://127.0.0.1:18789/

2. Prepare your OpenModels key

Create an API key in the OpenModels dashboard and keep it outside source control:

export OM_API_KEY="ale-your-api-key"

For a long-running OpenClaw daemon, put the key somewhere the daemon can read. OpenClaw supports daemon env files, so a simple local setup can use:

mkdir -p ~/.openclaw
printf 'OM_API_KEY=ale-your-api-key\n' >> ~/.openclaw/.env

Do not commit real ale-... keys to an application repository.

3. Add OpenModels as a provider

OpenClaw model references use this shape:

provider/model

Use openmodels as the provider ID and put the OpenModels model ID after the slash.

Edit ~/.openclaw/openclaw.json:

{
  models: {
    mode: "merge",
    providers: {
      openmodels: {
        baseUrl: "https://api.getopenmodels.com/v1",
        api: "openai-completions",
        apiKey: "ale-your-api-key",
        models: [
          {
            id: "qwen3.5-flash",
            name: "qwen3.5-flash",
            input: ["text"],
            contextWindow: 1000000,
            maxTokens: 8192
          },
          {
            id: "kimi-k2.7-code",
            name: "kimi-k2.7-code",
            input: ["text"],
            contextWindow: 256000,
            maxTokens: 8192
          }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "openmodels/qwen3.5-flash",
        fallbacks: ["openmodels/kimi-k2.7-code"]
      },
      models: {
        "openmodels/qwen3.5-flash": { alias: "Qwen Flash" },
        "openmodels/kimi-k2.7-code": { alias: "Kimi Code" }
      }
    }
  }
}

If you already have models or agents config, merge the keys above instead of replacing the whole file. The apiKey value in the example is a placeholder. For production, prefer OpenClaw’s secrets or env mechanism. If you write a key directly into openclaw.json, make sure the file is readable only by the local user.

OpenClaw validates config strictly. If the Gateway does not start after the edit, run:

openclaw doctor
openclaw doctor --fix

4. Restart and verify

Restart the Gateway:

openclaw gateway restart

Check that the provider and model are visible:

openclaw models list --provider openmodels
openclaw models set openmodels/qwen3.5-flash
openclaw models status

Then send a message in the dashboard or a connected chat channel. OpenClaw should use the selected OpenModels-backed model.

5. Switch models in a session

Switch to another OpenModels model:

/model openmodels/kimi-k2.7-code

Return to the configured default:

/model default

If OpenClaw reports that the model is not allowed, add the matching openmodels/<model-id> entry to agents.defaults.models or remove the allowlist.

Use OpenClaw as an OpenAI-compatible endpoint

This is the reverse direction: another app calls OpenClaw, then OpenClaw runs its configured agent.

When enabled, the OpenClaw Gateway can expose an OpenAI-compatible endpoint:

http://127.0.0.1:18789/v1

For Open WebUI or another trusted local app:

FieldValue
Base URLhttp://127.0.0.1:18789/v1
API keyOpenClaw Gateway bearer token
Modelopenclaw/default

Keep these URLs separate:

  • Use https://api.getopenmodels.com/v1 when an app calls OpenModels directly.
  • Use http://127.0.0.1:18789/v1 when an app calls your local OpenClaw Gateway.
  • In OpenClaw’s /v1 endpoint, the OpenAI model field selects an OpenClaw agent target such as openclaw/default. Backend provider or model overrides belong in OpenClaw config or the x-openclaw-model header.

Do not expose OpenClaw’s /v1 endpoint directly to the public internet. A valid Gateway token is an operator-level credential for that Gateway.

Troubleshooting

SymptomCheck
OpenModels returns 401 or invalid keyConfirm apiKey is a valid ale-... key and the key still exists
Balance or billing failureAdd credits to the OpenModels account before sending requests
Model is not allowedAdd openmodels/<model-id> to agents.defaults.models, or clear the allowlist
Gateway does not startRun openclaw doctor and inspect the strict config validation error
The session keeps using the old modelRun /model default, or start a new session without a pinned model
OpenClaw /v1/models only shows openclaw/defaultThat endpoint returns OpenClaw agent targets, not raw OpenModels model IDs

References