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

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 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) 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:

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:

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:

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:

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) backs up your existing TOML before injecting an [model_providers.omlx] section:

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:

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:

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

Key Source Files and Implementation Details

File	Purpose
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	OpenClawIntegration class with configure (lines 45-84) and launch (lines 64-66). Manages ~/.openclaw/openclaw.json.
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	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 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 (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 (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}