Configure OpenClaw

OpenClaw ↗ is an open-source local AI assistant that can connect models to Telegram, WhatsApp, Slack, and other messaging channels. This guide covers installation, a LAYSO AI model provider, agent routing, and the first successful request.

One key for all platform models

Models are billed at the current prices shown on LAYSO AI Models & Pricing. Every successful request has an itemized charge; failed tasks are not charged.

Why use LAYSO AI?

• One key for platform models: no separate credential for every model.
• Mainstream protocol support: OpenAI Responses, Anthropic Messages, and native Gemini integrations.
• Flexible agent routing: assign different models to primary, research, and routine agents.
• Itemized usage: inspect the model, tokens, and charge for every successful request.

Long-running OpenClaw workflows and multi-agent tasks can use many tokens. Choose a model by capability, context length, and price on LAYSO AI Models & Pricing ↗, then copy the exact model ID shown there.

Install

OpenClaw currently requires Node.js 22.22.3+, 24.15+, or 25.9+; Node.js 26 is recommended. Use the official installer below.

macOS / Linux / WSL2

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

Windows PowerShell

iwr -useb https://openclaw.ai/install.ps1 | iex

Verify the installation

openclaw --version

A version number confirms that installation succeeded.

IMAGE SLOT 01Install OpenClaw and check its version/screenshots/openclaw/01-install-version.pngRecommended ratio 16:9 · 1600 × 900

Quick start

Step 1: Get an API key and model ID

1. Create and copy a key from LAYSO AI API Keys ↗.
2. Choose a model on LAYSO AI Models & Pricing ↗ and copy its exact model ID.

Do not guess model aliases, and never place a real API key in a project file or Git repository.

Step 2: Store the API key

OpenClaw recommends its global runtime environment file, ~/.openclaw/.env, for provider credentials. The Gateway service can read this file under the current user, making it more appropriate than a project-level .env.

macOS / Linux / WSL2

mkdir -p ~/.openclaw
printf 'LAYSO_API_KEY=sk-...\n' >> ~/.openclaw/.env
chmod 600 ~/.openclaw/.env

Windows PowerShell

New-Item -ItemType Directory -Force "$HOME\.openclaw"
Add-Content "$HOME\.openclaw\.env" 'LAYSO_API_KEY=sk-...'

Replace sk-... with the complete LAYSO AI key. If LAYSO_API_KEY already exists in the file, edit that line instead of appending a duplicate.

Step 3: Run onboarding

For a first-time setup, run the official onboarding wizard and install the managed Gateway service:

openclaw onboard --install-daemon

The wizard continues with workspace, Gateway, and messaging-channel setup. Configure the model provider through openclaw.json in the next section. If onboarding asks for a model first, skip it or select a temporary custom provider, then replace it with this guide's configuration.

IMAGE SLOT 02Complete the OpenClaw onboarding wizard/screenshots/openclaw/02-onboarding.pngRecommended ratio 16:9 · 1600 × 900

Step 4: Open the configuration file

OpenClaw uses JSON5 in openclaw.json. Default locations are:

System	Configuration file
macOS	/Users/<username>/.openclaw/openclaw.json
Windows	C:\Users\<username>\.openclaw\openclaw.json
Linux / WSL2	/home/<username>/.openclaw/openclaw.json

You can also ask OpenClaw for the active path:

openclaw config file

Step 5: Add the LAYSO AI provider

OpenAI Responses compatibility is recommended. Replace <PRIMARY_MODEL_ID> with an exact ID copied from the pricing page:

{
  models: {
    mode: "merge",
    providers: {
      layso_ai: {
        baseUrl: "https://api.layso.ai/v1",
        apiKey: "${LAYSO_API_KEY}",
        api: "openai-responses",
        models: [
          {
            id: "<PRIMARY_MODEL_ID>",
            name: "LAYSO AI Primary"
          }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "layso_ai/<PRIMARY_MODEL_ID>"
      }
    }
  }
}

The provider ID is layso_ai, so a full model reference in OpenClaw must be written as layso_ai/<MODEL_ID>.

Step 6: Validate and open the dashboard

openclaw config validate
openclaw models list --provider layso_ai
openclaw gateway restart
openclaw dashboard

If the managed service is not installed, run openclaw gateway run in the current terminal. Send a short prompt in the Dashboard, then verify the model, tokens, and charge in LAYSO AI task details.

IMAGE SLOT 03Verify the LAYSO AI connection in Dashboard/screenshots/openclaw/03-dashboard-success.pngRecommended ratio 16:9 · 1600 × 900

Complete configuration

Provider protocols and URLs

The OpenClaw api field selects the request adapter. Use one protocol appropriate for the model and workflow; OpenAI Responses is recommended for the first setup.

Protocol	api	baseUrl	Notes
OpenAI Responses	openai-responses	https://api.layso.ai/v1	Recommended for models supporting the Responses API
OpenAI Chat Completions	openai-completions	https://api.layso.ai/v1	For tools or models that only support Chat Completions
Anthropic Messages	anthropic-messages	https://api.layso.ai	Use the root URL; do not add /anthropic or /v1
Native Gemini	google-generative-ai	https://api.layso.ai	Use the root URL; do not add /gemini or /v1beta

One provider can use only one api adapter. To use multiple protocols at the same time, create separate IDs such as layso_openai, layso_anthropic, and layso_gemini.

Model catalog

A custom provider must register its models in the models array. One LAYSO AI key can access platform models, but OpenClaw only displays models registered under that provider.

models: [
  { id: "<PRIMARY_MODEL_ID>", name: "Primary" },
  { id: "<FAST_MODEL_ID>", name: "Fast" },
  { id: "<RESEARCH_MODEL_ID>", name: "Research" }
]

Copy every ID from LAYSO AI Models & Pricing ↗. Model capabilities, context lengths, and prices should be taken from the live page.

Default model and fallback

The following configuration uses a primary model by default and falls back to a faster model when needed:

agents: {
  defaults: {
    model: {
      primary: "layso_ai/<PRIMARY_MODEL_ID>",
      fallbacks: ["layso_ai/<FAST_MODEL_ID>"]
    },
    models: {
      "layso_ai/<PRIMARY_MODEL_ID>": { alias: "primary" },
      "layso_ai/<FAST_MODEL_ID>": { alias: "fast" },
      "layso_ai/<RESEARCH_MODEL_ID>": { alias: "research" }
    }
  }
}

Model references always use <provider ID>/<model ID>. A bare model ID cannot resolve the custom provider.

Multi-agent routing

If you already created multiple OpenClaw agents, assign different models by role:

agents: {
  defaults: {
    model: { primary: "layso_ai/<PRIMARY_MODEL_ID>" }
  },
  list: [
    { id: "main", model: "layso_ai/<PRIMARY_MODEL_ID>" },
    { id: "research", model: "layso_ai/<RESEARCH_MODEL_ID>" },
    { id: "quick", model: "layso_ai/<FAST_MODEL_ID>" }
  ]
}

Complete one successful request with the default agent before adding multi-agent and channel configuration. This keeps troubleshooting focused.

Full example

This example includes one provider, three model roles, a default model, and a fallback. Replace all three placeholder IDs. If you only need one model, remove the other rows and references.

{
  models: {
    mode: "merge",
    providers: {
      layso_ai: {
        baseUrl: "https://api.layso.ai/v1",
        apiKey: "${LAYSO_API_KEY}",
        api: "openai-responses",
        models: [
          { id: "<PRIMARY_MODEL_ID>", name: "LAYSO AI Primary" },
          { id: "<FAST_MODEL_ID>", name: "LAYSO AI Fast" },
          { id: "<RESEARCH_MODEL_ID>", name: "LAYSO AI Research" }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "layso_ai/<PRIMARY_MODEL_ID>",
        fallbacks: ["layso_ai/<FAST_MODEL_ID>"]
      },
      models: {
        "layso_ai/<PRIMARY_MODEL_ID>": { alias: "primary" },
        "layso_ai/<FAST_MODEL_ID>": { alias: "fast" },
        "layso_ai/<RESEARCH_MODEL_ID>": { alias: "research" }
      }
    }
  }
}

Model selection guidance

Role	Prioritize	Suitable work
Primary	balanced capability, tool use, stability	conversation, coding, cross-tool tasks
Research	long context, reasoning	deep analysis, long documents, multi-step research
Fast	latency, price	classification, summaries, simple and frequent tasks

Do not copy aliases from another platform. Select a currently available model on LAYSO AI Models & Pricing and use its exact ID.

Connect messaging channels

After the model request works, run onboarding again to add Telegram, WhatsApp, Slack, or another channel:

openclaw onboard

Complete the channel credentials, account pairing, and permissions in the wizard. Then probe channel and Gateway status:

openclaw channels status --probe
openclaw gateway status --deep

IMAGE SLOT 04Connect Telegram, WhatsApp, or Slack/screenshots/openclaw/04-channel-connected.pngRecommended ratio 16:9 · 1600 × 900

Troubleshooting

401 / 403 authentication errors

1. Check that LAYSO_API_KEY in ~/.openclaw/.env is complete and has no extra spaces or line breaks.
2. Restart the Gateway so the managed service reloads the environment.
3. Do not place a real key directly in openclaw.json.

404 or protocol mismatch

Keep each api and baseUrl paired correctly:

• openai-responses / openai-completions use https://api.layso.ai/v1.
• anthropic-messages uses https://api.layso.ai; do not append /anthropic or /v1.
• google-generative-ai uses https://api.layso.ai; do not append /gemini or /v1beta.

Model not found

Confirm that these three values match exactly:

1. The ID registered in models.providers.layso_ai.models[].id.
2. The <MODEL_ID> portion of agents.defaults.model.primary.
3. The exact ID shown on Models & Pricing.

Configuration changes do not apply

openclaw config validate
openclaw gateway restart
openclaw models status

If you see config reload skipped or Invalid config, fix the JSON5 syntax or unknown fields before restarting the Gateway.

Messaging channel does not reply

openclaw channels status --probe
openclaw gateway status --deep
openclaw logs --follow

First confirm that the model works in Dashboard, then inspect channel pairing, allowlists, and permissions.

Token usage is too high

• Use a faster, lower-cost model for routine work.
• Switch to a research model only for complex tasks.
• Reduce unnecessary context and attachments.
• Review the model, tokens, and itemized charge in LAYSO AI task details.

Security and billing

• Keep ~/.openclaw/.env local and out of Git.
• Never expose a full API key in screenshots, logs, chats, or public examples.
• One LAYSO AI API key can access platform models.
• Every successful request has an itemized charge; failed tasks are not charged.

Replace the image placeholders

Place your screenshots in docs/public/screenshots/openclaw/, then replace each placeholder with a Markdown image. For example:

![OpenClaw onboarding](/screenshots/openclaw/02-onboarding.png)