Omlx

Name: Omlx
Rating: 3.5 (1 reviews)
Author: pm990320

By pm990320 👁 6 views ▲ 0 votes

OpenClaw plugin for oMLX — local Apple Silicon inference with dynamic model discovery and per-model system prompts

GitHub

Install

npm install
npm

Configuration Example

{
  "plugins": {
    "entries": {
      "omlx": {
        "enabled": true,
        "config": {
          "baseUrl": "http://127.0.0.1:5741"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "omlx/qwen3-8b"
    }
  }
}

README

# openclaw-omlx

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

It adds an `omlx` provider to OpenClaw with:

- boot-time model discovery from `GET /v1/models`
- 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 intentionally generic. It does **not** know anything about privatenet. If you want to point it at a router or proxy that exposes the same OpenAI-compatible API, just change `baseUrl`.

## Install

```bash
openclaw plugins install openclaw-omlx
```

## What it does

- Registers the `omlx` provider in OpenClaw
- Fetches available models from `<baseUrl>/v1/models` 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`.

```json
{
  "plugins": {
    "entries": {
      "omlx": {
        "enabled": true,
        "config": {
          "baseUrl": "http://127.0.0.1:5741"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "omlx/qwen3-8b"
    }
  }
}
```

### API key

The plugin reads the API key from:

1. `plugins.entries.omlx.config.apiKey`
2. `OMLX_API_KEY`
3. default value: `omlx`

That default matches oMLX's common local default behavior.

## System prompt configuration

The plugin can append to or replace the system prompt for oMLX-backed runs.

Priority order:

1. per-agent override
2. per-model override
3. global default

### Global default

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

### Per-model override

```json
{
  "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

```json
{
  "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"
              }
            }
          }
        }
      }
    }
  }
}
```

## Using oMLX directly vs through a router

Direct oMLX:

```json
{
  "plugins": {
    "entries": {
      "omlx": {
        "config": {
          "baseUrl": "http://127.0.0.1:5741"
        }
      }
    }
  }
}
```

Router or proxy exposing the same API:

```json
{
  "plugins": {
    "entries": {
      "omlx": {
        "config": {
          "baseUrl": "http://127.0.0.1:8741"
        }
      }
    }
  }
}
```

No other plugin changes are needed.

## 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

```bash
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

tools