openclaw-omlx

OpenClaw provider plugin for oMLX-style OpenAI-compatible servers.

It adds an omlx provider to OpenClaw with:

• boot-time model discovery via the OpenAI-compatible /v1/models endpoint
• runtime dynamic model resolution for any oMLX-served model id
• configurable baseUrl
• optional API key override
• system prompt additions or replacements globally, per model, or per agent

This plugin is generic and works with any OpenAI-compatible server. If you run oMLX behind a proxy or load balancer, just change baseUrl.

Install

openclaw plugins install openclaw-omlx

Setup

After installing the plugin, you need to configure auth for the omlx provider so OpenClaw can pass an API key to your local server. The API key is the one configured in your oMLX server (see the oMLX docs for how to set or retrieve it).

Option 1: Environment variable

Set the OMLX_API_KEY environment variable:

export OMLX_API_KEY=<your-api-key>

Option 2: Add auth via CLI

Run the plugin's auth flow:

openclaw models auth login --provider omlx

Or paste a token directly:

openclaw models auth paste-token --provider omlx

When prompted, enter your API key. To add auth for a specific agent, pass --agent <agent-id>.

Option 3: Edit auth-profiles.json directly

Add an omlx:default profile to your agent's auth-profiles.json (located at ~/.openclaw/agents/<agent-id>/agent/auth-profiles.json):

{
  "profiles": {
    "omlx:default": {
      "type": "token",
      "provider": "omlx",
      "token": "<your-api-key>"
    }
  },
  "lastGood": {
    "omlx": "omlx:default"
  }
}

Verify

Make sure your oMLX server is running, then start the agent. The plugin will discover available models from the server's /v1/models endpoint on boot.

What it does

• Registers the omlx provider in OpenClaw
• Discovers available models from the server's /v1/models endpoint during catalog load
• Falls back gracefully if oMLX is not reachable at boot
• Accepts arbitrary model ids at runtime via resolveDynamicModel, so newly loaded server models can be used without restarting OpenClaw

Configuration

Add plugin config under plugins.entries.omlx.config in openclaw.json.

{
  "plugins": {
    "entries": {
      "omlx": {
        "enabled": true,
        "config": {
          "baseUrl": "http://127.0.0.1:8000/v1"
        }
      }
    }
  }
}

Then set an agent's model to an omlx model (e.g. in the agent definition or via agents.defaults.model):

{
  "agents": {
    "defaults": {
      "model": "omlx/qwen3-8b"
    }
  }
}

API key

The plugin reads the API key from (in priority order):

1. plugins.entries.omlx.config.apiKey
2. OMLX_API_KEY environment variable
3. The auth profile configured during setup

System prompt configuration

The plugin can append to or replace the system prompt via the before_agent_start hook.

Priority order:

1. per-agent override — matches by agent ID; applies regardless of which model the agent uses
2. per-model override — matches by model ID; only applies when the agent uses an omlx/ model
3. global default — only applies when the agent uses an omlx/ model and no per-model override matches

Global default

{
  "plugins": {
    "entries": {
      "omlx": {
        "enabled": true,
        "config": {
          "systemPrompt": {
            "default": "Answer concisely and prefer practical steps.",
            "mode": "append"
          }
        }
      }
    }
  }
}

Per-model override

{
  "plugins": {
    "entries": {
      "omlx": {
        "config": {
          "systemPrompt": {
            "default": "Be brief.",
            "models": {
              "qwen3-8b": {
                "text": "Prefer code examples and explicit shell commands.",
                "mode": "append"
              },
              "llama-3.3-70b": {
                "text": "You are a pure code assistant.",
                "mode": "replace"
              }
            }
          }
        }
      }
    }
  }
}

Per-agent override

{
  "plugins": {
    "entries": {
      "omlx": {
        "config": {
          "systemPrompt": {
            "agents": {
              "main": {
                "text": "You are Patrick's local oMLX assistant.",
                "mode": "append"
              },
              "bob": {
                "text": "You write code first and explain second.",
                "mode": "replace"
              }
            }
          }
        }
      }
    }
  }
}

Custom base URL

By default the plugin connects to http://127.0.0.1:8000/v1. The baseUrl should include the /v1 path prefix since OpenClaw appends endpoint paths (e.g. /chat/completions) directly to it.

{
  "plugins": {
    "entries": {
      "omlx": {
        "config": {
          "baseUrl": "http://192.168.1.50:8000/v1"
        }
      }
    }
  }
}

Notes

• If the catalog fetch fails at boot, the plugin logs a warning and returns an empty catalog instead of crashing.
• Dynamic model resolution still allows manually referenced omlx/<model-id> models after the server becomes available.
• Per-model prompt overrides are resolved from the agent's configured model reference, so they work best when the agent explicitly uses an omlx/<model-id> model.

Development

npm install
npm run lint
npm run typecheck
npm test
npm run build

Publishing

This package is set up for conventional commits and release-please.

• merge conventional commits to main
• release-please opens or updates the release PR
• when a version tag is created, GitHub Actions publishes to npm