OpenClaw

Overview

OpenClaw is an open-source, self-hosted personal AI assistant platform that connects messaging apps to AI agents running on your own hardware. Designed for developers and power users, it lets you own an autonomous AI assistant without giving up control of your data.

• Official homepage: https://openclaw.ai
• Documentation: https://docs.openclaw.ai
• GitHub: https://github.com/openclaw/openclaw

OpenClaw is fully open source—you can browse the source, file issues, or contribute on the OpenClaw GitHub repository. This tutorial covers installation, configuration, and the complete steps for connecting OpenClaw to Models Hub.

🌟 Core Features

Multi-Channel Integration

• Multi-channel integration: Supports Telegram, Discord, WhatsApp, iMessage, and other messaging channels, and can be extended to more platforms via plugins
• Single gateway: Manages all channels through a single Gateway process
• Voice support: Supports voice interaction on macOS/iOS/Android
• Canvas interface: Can render interactive Canvas interfaces

Self-Hosting and Data Security

• Fully self-hosted: Runs on your own machine or server
• Open and transparent: MIT-licensed open source, fully transparent code
• Local data: Context and skills are stored on your local computer, not in the cloud

Intelligent Agent Capabilities

• Always running: Supports persistent background operation with durable memory
• Scheduled tasks: Supports cron scheduled tasks
• Session isolation: Isolates sessions by agent/workspace/sender
• Multi-agent routing: Supports multiple agents working together
• Tool calling: Native support for tool calling and code execution

📦 Before You Start

What you need

• Node.js 22 or higher
• A working Models Hub Base URL (typically ending with /v1)
• A working Models Hub API Key

Before you start connecting to Models Hub, we recommend getting the Gateway and Control UI running by following OpenClaw's current recommended flow first. This makes it easier to tell, when troubleshooting later, whether OpenClaw itself failed to start or the model provider configuration is wrong.

1. Install OpenClaw (macOS/Linux)

curl -fsSL https://openclaw.ai/install.sh | bash

For other installation methods, see the official OpenClaw documentation: Getting Started.

2. Run the Onboarding Wizard

openclaw onboard --install-daemon

This wizard completes basic authentication, Gateway setup, and optional channel initialization. The goal here is to get OpenClaw running first, then switch the default model to Models Hub afterward.

3. Check the Gateway and Control UI

openclaw gateway status

openclaw dashboard

If your browser can open the Control UI, OpenClaw's basics are running normally. At this stage there is no need to configure messaging channels like Telegram, Discord, or Feishu first.

4. Locate the Configuration File

OpenClaw's configuration file is typically located at ~/.openclaw/openclaw.json. You can continue editing it on top of what the onboarding wizard generated.

Path-related environment variables

If you run OpenClaw under a dedicated service account, or want to customize the config/state directories, you can use:

• OPENCLAW_HOME
• OPENCLAW_STATE_DIR
• OPENCLAW_CONFIG_PATH

For details, see the official environment variables documentation: Environment Variables.

🚀 Using Models Hub as the Model Provider

OpenClaw supports connecting custom or OpenAI-compatible model gateways through models.providers. For Models Hub, the most common approach is to add it to the config as a custom provider, then point the default model at modelsok/model-id.

Integration Approach

1. Declare a modelsok provider under models.providers
2. Point baseUrl at your Models Hub Base URL, making sure it includes /v1
3. Set api to openai-completions
4. List the model IDs you want OpenClaw to use under models
5. Switch the default model to modelsok/... in agents.defaults.model.primary

Recommended: Store the Key in an Environment Variable

First provide your Models Hub key in the current shell, the service environment, or a .env file that OpenClaw can read:

export MODELSOK_API_KEY="ms_live_your_key"

Then add or modify the following snippet in openclaw.json:

{
  models: {
    mode: "merge",
    providers: {
      modelsok: {
        baseUrl: "https://modelsok.com/v1",
        apiKey: "${MODELSOK_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gemini-2.5-flash", name: "Gemini 2.5 Flash" },
          { id: "kimi-k2.5", name: "Kimi K2.5" },
        ],
      },
    },
  },

  agents: {
    defaults: {
      model: {
        primary: "modelsok/gemini-2.5-flash",
        fallbacks: ["modelsok/kimi-k2.5"],
      },
      models: {
        "modelsok/gemini-2.5-flash": { alias: "flash" },
        "modelsok/kimi-k2.5": { alias: "kimi" },
      },
    },
  },
}

This is not a complete configuration you must copy verbatim, but rather the most essential parts for connecting to Models Hub. As long as the provider, model IDs, and default model references line up correctly, OpenClaw can call the model resources you expose through Models Hub.

Key Configuration Notes

Verifying a Successful Connection

After completing the configuration, return to the Control UI or reopen it:

openclaw dashboard

If you can start a conversation in OpenClaw normally and the default model has become modelsok/..., the connection was successful. You can also use:

openclaw models list

to confirm that models with the modelsok/ prefix now appear in the available list.

FAQ

• baseUrl missing /v1: This is one of the most common connection errors.
• Wrong model ID: primary and fallbacks must correspond to the id values in models.providers.modelsok.models.
• Key only valid in the current terminal: If the Gateway runs as a background service, make sure the service process can also read MODELSOK_API_KEY.
• For foreground troubleshooting: You can use the official foreground run mode openclaw gateway --port 18789 to observe logs and errors.