# How to Integrate oMLX with OpenCode, OpenClaw, or Codex: Complete Setup Guide

> Integrate oMLX with OpenCode OpenClaw or Codex effortlessly. This guide shows how to run the oMLX inference server and use Python classes to auto configure your tools for seamless integration.

- Repository: [Jun Kim/omlx](https://github.com/jundot/omlx)
- Tags: how-to-guide
- Published: 2026-05-11

---

**To integrate oMLX with OpenCode, OpenClaw, or Codex, run the local oMLX inference server and use the provided Python integration classes—`OpenClawIntegration`, `OpenCodeIntegration`, or `CodexIntegration`—to automatically configure each tool's JSON or TOML config file to point at your local endpoint.**

The **jundot/omlx** repository ships a FastAPI-based inference server that mimics the OpenAI and Anthropic APIs, enabling seamless integration with external IDE tools. By using the built-in integration adapters, you can direct OpenCode, OpenClaw, or Codex to consume local models through oMLX's optimized inference engine rather than cloud APIs.

## How the Integration Architecture Works

oMLX provides an **`Integration`** base class in [`omlx/integrations/base.py`](https://github.com/jundot/omlx/blob/main/omlx/integrations/base.py) that standardizes the connection process across all supported tools. Each adapter follows a four-step workflow:

1. **Detect**: The `is_installed` method (lines 37-40 in [`omlx/integrations/base.py`](https://github.com/jundot/omlx/blob/main/omlx/integrations/base.py)) uses `shutil.which` to verify that `openclaw`, `opencode`, or `codex` binaries exist in your system PATH.
2. **Configure**: The tool-specific `configure` method writes a provider entry to the tool's configuration file (JSON for OpenClaw/OpenCode, TOML for Codex), setting `baseURL` to your oMLX server (e.g., `http://127.0.0.1:8000/v1`), the `apiKey`, and the default model in the format `omlx/<model-id>`.
3. **Launch**: The `launch` method executes the external tool with the correct environment variables, or prints the command for manual execution.
4. **Admin UI**: Alternatively, the web dashboard at `/admin` provides a one-click **Integrations** tab that executes the same `configure` and `launch` logic through the UI.

All adapters create timestamped backups (`*.bak`) of existing configuration files before modification, making the integration fully reversible.

## Step-by-Step Integration Guide

### 1. Start the oMLX Inference Server

Before connecting external tools, start the local inference server:

```bash
omlx serve --model-dir ~/models

```

By default, this exposes an OpenAI-compatible API at `http://127.0.0.1:8000/v1`. Verify the server is running:

```bash
curl http://127.0.0.1:8000/v1/models

```

### 2. Integrate OpenClaw

OpenClaw stores its configuration in `~/.openclaw/openclaw.json`. Use the `OpenClawIntegration` class to automate the setup:

```python
from omlx.integrations.openclaw import OpenClawIntegration

# Verify installation

if not OpenClawIntegration().is_installed():
    raise RuntimeError("OpenClaw not found – install with: npm install -g openclaw")

# Write configuration (lines 45-84 in omlx/integrations/openclaw.py)

OpenClawIntegration().configure(
    port=8000,
    api_key="my-secret-key",  # Defaults to "omlx" if omitted

    model="Step-3.5-Flash-8bit",
    host="127.0.0.1",
    tools_profile="coding",
)

# Launch OpenClaw (lines 64-66 in omlx/integrations/openclaw.py)

OpenClawIntegration().launch(
    port=8000,
    api_key="my-secret-key",
    model="Step-3.5-Flash-8bit",
)

```

This creates an **omlx** provider entry in `~/.openclaw/openclaw.json` pointing to your local server.

### 3. Integrate OpenCode

OpenCode uses `~/.config/opencode/opencode.json` for its settings:

```python
from omlx.integrations.opencode import OpenCodeIntegration

# Configure (lines 55-84 in omlx/integrations/opencode.py)

OpenCodeIntegration().configure(
    port=8000,
    api_key="my-secret-key",
    model="Step-3.5-Flash-8bit",
    host="127.0.0.1",
    context_window=131072,
    max_tokens=8192,
    model_type="llm",  # Use "vlm" for vision-language models

)

# Launch manually or via the integration helper

# opencode launch --model Step-3.5-Flash-8bit

```

### 4. Integrate Codex

Codex stores configuration in `~/.codex/config.toml`. The integration (lines 37-104 of [`omlx/integrations/codex.py`](https://github.com/jundot/omlx/blob/main/omlx/integrations/codex.py)) backs up your existing TOML before injecting an `[model_providers.omlx]` section:

```python
from omlx.integrations.codex import CodexIntegration

# Configure

CodexIntegration().configure(
    port=8000,
    api_key="my-secret-key",
    model="Step-3.5-Flash-8bit",
    host="127.0.0.1",
)

# Launch (lines 11-34 in omlx/integrations/codex.py)

# This replaces the current process with the codex binary

CodexIntegration().launch(
    port=8000,
    api_key="my-secret-key",
    model="Step-3.5-Flash-8bit",
)

```

After launching, the `codex` CLI communicates exclusively with your local oMLX instance.

## Generic Integration Helper

For custom scripts or automation, use this generic function to handle all three tools:

```python
def integrate(tool: str, *, port: int = 8000, api_key: str = "omlx",
              model: str, host: str = "127.0.0.1", **kwargs):
    """Run the appropriate oMLX integration."""
    from omlx.integrations import (
        OpenClawIntegration, OpenCodeIntegration, CodexIntegration
    )
    mapping = {
        "openclaw": OpenClawIntegration,
        "opencode": OpenCodeIntegration,
        "codex":    CodexIntegration,
    }
    cls = mapping[tool.lower()]
    integ = cls()
    if not integ.is_installed():
        raise RuntimeError(f"{tool} not installed.")
    integ.configure(port, api_key, model, host=host, **kwargs)
    integ.launch(port, api_key, model, host=host, **kwargs)

```

Usage:

```python
integrate("openclaw", model="Step-3.5-Flash-8bit")

```

## Key Source Files and Implementation Details

| File | Purpose |
|------|---------|
| [`omlx/integrations/base.py`](https://github.com/jundot/omlx/blob/main/omlx/integrations/base.py) | Defines the `Integration` dataclass and `is_installed` method (lines 37-40) using `shutil.which` for binary detection. |
| [`omlx/integrations/openclaw.py`](https://github.com/jundot/omlx/blob/main/omlx/integrations/openclaw.py) | `OpenClawIntegration` class with `configure` (lines 45-84) and `launch` (lines 64-66). Manages `~/.openclaw/openclaw.json`. |
| [`omlx/integrations/opencode.py`](https://github.com/jundot/omlx/blob/main/omlx/integrations/opencode.py) | `OpenCodeIntegration` class with `configure` (lines 55-84) and `launch` (lines 87-100). Handles VLMs via `model_type` parameter. |
| [`omlx/integrations/codex.py`](https://github.com/jundot/omlx/blob/main/omlx/integrations/codex.py) | `CodexIntegration` class with `configure` (lines 37-104) and `launch` (lines 11-34). Modifies `~/.codex/config.toml` with automatic backup. |

## Summary

- **oMLX** exposes an OpenAI-compatible API at `http://127.0.0.1:8000/v1` via its FastAPI server.
- **Three integration classes**—`OpenClawIntegration`, `OpenCodeIntegration`, and `CodexIntegration`—handle configuration automatically.
- **Configuration files** are modified in-place with automatic backups (`*.bak`): `~/.openclaw/openclaw.json`, `~/.config/opencode/opencode.json`, and `~/.codex/config.toml`.
- **Detection**: The `is_installed` method in [`omlx/integrations/base.py`](https://github.com/jundot/omlx/blob/main/omlx/integrations/base.py) verifies tool availability before attempting configuration.
- **Reversibility**: Delete the generated config sections or restore the `.bak` files to undo the integration.

## Frequently Asked Questions

### Where does oMLX store the configuration files for each tool?

OpenClaw configuration is written to `~/.openclaw/openclaw.json`, OpenCode to `~/.config/opencode/opencode.json`, and Codex to `~/.codex/config.toml`. According to the source code in [`omlx/integrations/codex.py`](https://github.com/jundot/omlx/blob/main/omlx/integrations/codex.py) (lines 37-104), the Codex integration specifically creates a timestamped backup of your existing TOML before modification.

### How does the integration verify that external tools are installed?

The `Integration` base class in [`omlx/integrations/base.py`](https://github.com/jundot/omlx/blob/main/omlx/integrations/base.py) (lines 37-40) implements an `is_installed` method that uses Python's `shutil.which` to check for the presence of `openclaw`, `opencode`, or `codex` binaries in your system PATH. This check prevents configuration errors for tools that haven't been installed yet.

### Can I use Vision Language Models (VLMs) with these integrations?

Yes. The `OpenCodeIntegration.configure` method in [`omlx/integrations/opencode.py`](https://github.com/jundot/omlx/blob/main/omlx/integrations/opencode.py) accepts a `model_type` parameter. Set `model_type="vlm"` to expose image modality capabilities to OpenCode, while `"llm"` restricts the integration to text-only models. This configuration affects how the tool interprets the model's capability set.

### Is the integration reversible?

Absolutely. Each integration adapter creates a timestamped backup file (e.g., `config.toml.1701234567.bak`) before modifying the original configuration. To reverse the integration, simply restore the backup file or manually remove the `omlx` provider entry from the tool's configuration file. The changes are non-destructive and file-based only.