OpenClaw Agent setup

OpenClaw is a general-purpose agent built around a local Gateway, suited to long-running automation, tools, channels, and cross-device sessions. Its CLI, Control UI, and macOS companion connect to the same Gateway, so model providers are persistent Gateway state.

Install OpenClaw first, then create a Lumoswitch API configuration with OpenAI-compatible output.

Choose a setup method

Do not remove ~/.openclaw to disconnect Lumoswitch. That directory also contains channels, sessions, workspaces, and other provider credentials.

Prepare the connection values

Persistent use

Run this during initial setup and whenever the URL, Access Key, or model changes:

OpenClaw onboarding writes the Access Key to the current agent's local credential store. Use it only on a trusted personal device.

set -e
openclaw onboard --non-interactive --accept-risk --mode local \
  --skip-health \
  --auth-choice custom-api-key \
  --custom-base-url "{{api_base_url}}" \
  --custom-model-id "{{model}}" \
  --custom-api-key "{{access_key}}" \
  --custom-provider-id "lumoswitch" \
  --custom-compatibility openai \
  --secret-input-mode plaintext
LUMOSWITCH_OPENCLAW_MODELS='{{openclaw_models_json}}'
LUMOSWITCH_OPENCLAW_AGENT_MODELS='{{openclaw_agent_models_json}}'
openclaw config set models.providers.lumoswitch.models "$LUMOSWITCH_OPENCLAW_MODELS" --strict-json --replace
openclaw config set agents.defaults.models "$LUMOSWITCH_OPENCLAW_AGENT_MODELS" --strict-json --merge
openclaw models set "lumoswitch/{{model}}"
openclaw

For everyday use, run:

openclaw

There is no one-time setup command. The generated catalog sets reasoning and emits supportsReasoningEffort, supportedReasoningEfforts, and reasoningEffortMap only when the route can actually transport adjustable levels. Per-model params.thinking receives the safe default or explicit off, preventing a global default from injecting a control into an incompatible endpoint.

Native Windows PowerShell import

These commands run natively in Windows PowerShell without WSL and use the same connection values as the macOS/Linux templates on this page.

Persistent use on Windows

This command backs up existing Lumoswitch-owned files and restricts access to the configuration and launcher for the current user.

& {
  $ErrorActionPreference = 'Stop'
  $lumoswitchExecutable = Get-Command 'openclaw.cmd' -CommandType Application -ErrorAction SilentlyContinue
  if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'openclaw' -CommandType Application -ErrorAction Stop }
  $lumoswitchOpenClaw = $lumoswitchExecutable.Path

  & $lumoswitchOpenClaw 'onboard' '--non-interactive' '--accept-risk' '--mode' 'local' '--skip-health' '--auth-choice' 'custom-api-key' '--custom-base-url' '{{api_base_url}}' '--custom-model-id' '{{model}}' '--custom-api-key' '{{access_key}}' '--custom-provider-id' 'lumoswitch' '--custom-compatibility' 'openai' '--secret-input-mode' 'plaintext'
  if ($LASTEXITCODE -ne 0) { throw 'OpenClaw onboarding failed.' }
  $lumoswitchModels = @'
{{openclaw_models_json}}
'@
  & $lumoswitchOpenClaw 'config' 'set' 'models.providers.lumoswitch.models' $lumoswitchModels '--strict-json' '--replace'
  if ($LASTEXITCODE -ne 0) { throw 'OpenClaw model configuration failed.' }
  $lumoswitchAgentModels = @'
{{openclaw_agent_models_json}}
'@
  & $lumoswitchOpenClaw 'config' 'set' 'agents.defaults.models' $lumoswitchAgentModels '--strict-json' '--merge'
  if ($LASTEXITCODE -ne 0) { throw 'OpenClaw Agent configuration failed.' }
  & $lumoswitchOpenClaw 'models' 'set' 'lumoswitch/{{model}}'
  if ($LASTEXITCODE -ne 0) { throw 'OpenClaw default-model selection failed.' }
  & $lumoswitchOpenClaw
}

Remove the Lumoswitch setup

The commands below are identical in Windows PowerShell and macOS/Linux terminals. OpenClaw owns this native configuration, so there is no Lumoswitch launcher file to remove.

First inspect the current default model:

openclaw config get agents.defaults.model --json

If it still points to lumoswitch/{{model}}, switch to another already-configured model first:

openclaw models set "another-provider/model"

Then remove the Lumoswitch provider and list any remaining credential profiles:

openclaw config unset models.providers.lumoswitch
openclaw models auth list --provider lumoswitch

If the second command shows a Profile ID, use that exact value:

openclaw models auth logout "replace-with-profile-id" --yes

These are field-scoped OpenClaw commands. They do not remove other providers, channels, the Gateway, sessions, or workspaces. A Profile ID is generated from actual stored state and cannot be safely hard-coded. Run openclaw config validate afterward.

macOS companion and other surfaces

The official OpenClaw macOS app is a menu-bar companion, not a separate inference client. It connects to a local or remote Gateway and reuses that Gateway's default model and credentials. After onboarding, the app needs no second Lumoswitch Key; removing Lumoswitch from the Gateway also stops the companion from using it.

The Control UI manages the same Gateway configuration. Settings → Model Providers shows credential sources and supports connection tests or removing API keys stored in configuration. OpenClaw does not have an official IDE extension that needs a separate Lumoswitch credential; editor or remote clients still connect to the existing Gateway.

Verify and troubleshoot

• This template targets OpenAI-compatible Chat Completions.
• Run openclaw models status --json to inspect provider, credential, and runtime status.
• Run openclaw config validate after field-level removal to detect stale references.
• The target model must genuinely support OpenClaw's tool calls; protocol compatibility cannot add missing capabilities.

References: custom provider configuration, non-interactive onboarding, Config CLI, Models CLI, and the macOS companion.