> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modellix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Modellix LLM with Pi Agent

> Add Modellix as a custom OpenAI-compatible provider in Pi with models.json, openai-completions, and provider/name model IDs.

Configure [Pi](https://pi.dev/docs/latest/providers) to call the Modellix LLM gateway. Pi does not ship a built-in Modellix provider, so add a [custom provider](https://pi.dev/docs/latest/models) in `~/.pi/agent/models.json` that points at Chat Completions on [`POST /v1/chat/completions`](/llm/chat-completions).

<Note>
  This page covers **LLM text** only (`https://llm.modellix.ai`). For Pi media packages and skills (image, video, speech), see [Plugin](/ways-to-use/plugin) and [Skill](/ways-to-use/skill).

  Modellix model IDs are `provider/name` (for example `openai/gpt-5.5`). Put that full string in each model `id` under your custom provider. See [Models & Pricing](/llm/overview#models-and-pricing).
</Note>

## Set Up Pi

<Steps>
  <Step title="Get a Modellix API Key">
    Create a Modellix API key in the [console](https://modellix.ai/console/api-key) and export it so `models.json` can resolve `$MODELLIX_API_KEY`:

    ```bash theme={null}
    export MODELLIX_API_KEY="mdlx-xxxxxxxx"
    ```

    Add the same line to your shell profile (for example `~/.zshrc`) for persistent use.
  </Step>

  <Step title="Add a Custom Provider">
    Create or update `~/.pi/agent/models.json`:

    ```json theme={null}
    {
      "providers": {
        "modellix": {
          "baseUrl": "https://llm.modellix.ai/v1",
          "api": "openai-completions",
          "apiKey": "$MODELLIX_API_KEY",
          "models": [
            { "id": "openai/gpt-5.5", "name": "GPT 5.5", "contextWindow": 200000 },
            { "id": "openai/gpt-5.6-sol", "name": "GPT 5.6 Sol", "contextWindow": 200000 },
            { "id": "openai/gpt-5.6-terra", "name": "GPT 5.6 Terra", "contextWindow": 200000 },
            { "id": "openai/gpt-5.6-luna", "name": "GPT 5.6 Luna", "contextWindow": 200000 },
            { "id": "anthropic/claude-sonnet-5", "name": "Claude Sonnet 5", "contextWindow": 200000 },
            { "id": "google/gemini-3.6-flash", "name": "Gemini 3.6 Flash", "contextWindow": 200000 },
            { "id": "xai/grok-4.5", "name": "Grok 4.5", "contextWindow": 200000 }
          ]
        }
      }
    }
    ```

    Merge the `modellix` entry into an existing `providers` object if you already use custom models. Add or remove entries under `models` as needed.

    | Field         | Value                                                                           |
    | ------------- | ------------------------------------------------------------------------------- |
    | Provider key  | `modellix` (custom; do not use built-in `openai`, `anthropic`, or `openrouter`) |
    | `baseUrl`     | `https://llm.modellix.ai/v1`                                                    |
    | `api`         | `openai-completions`                                                            |
    | `apiKey`      | `$MODELLIX_API_KEY` (or `${MODELLIX_API_KEY}`)                                  |
    | `models[].id` | Exact Modellix Model IDs (`provider/name`)                                      |

    <Warning>
      Use a custom provider key such as `modellix`. Overwriting Pi's built-in `openai` or `anthropic` providers sends traffic to the vendor endpoints instead of Modellix.
    </Warning>

    <Tip>
      You do **not** need a separate Anthropic base URL. Register `anthropic/...` and `google/...` IDs on the same Modellix provider; traffic goes through OpenAI-compatible Chat Completions on `https://llm.modellix.ai/v1`.
    </Tip>
  </Step>

  <Step title="Select a Modellix Model">
    In an interactive Pi session, run `/model` and choose a Modellix entry (for example `openai/gpt-5.5` under the `modellix` provider).

    Or start Pi with the provider and model on the command line:

    ```bash theme={null}
    pi --provider modellix --model openai/gpt-5.5
    ```

    Pi reloads `models.json` each time you open `/model`, so you can edit the file during a session without restarting.

    <Tip>
      If a Modellix model appears in the file but stays unavailable in `/model`, confirm `$MODELLIX_API_KEY` is set. Pi requires auth before custom models become selectable.
    </Tip>
  </Step>

  <Step title="Start Pi">
    Start Pi as usual:

    ```bash theme={null}
    pi
    ```

    Or with Modellix selected up front:

    ```bash theme={null}
    pi --provider modellix --model openai/gpt-5.5
    ```
  </Step>
</Steps>

## Troubleshooting

| Symptom                                  | Check                                                                                                              |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| 401 / auth errors                        | `MODELLIX_API_KEY` is set; `apiKey` uses `$MODELLIX_API_KEY` or `${MODELLIX_API_KEY}`                              |
| Model listed but unavailable in `/model` | Auth is configured (env var, `apiKey` in `models.json`, or `--api-key`)                                            |
| Model not found / 404                    | `models[].id` is a full ID like `openai/gpt-5.5`, not bare `gpt-5.5`; ID is in the live catalog                    |
| Traffic hits OpenAI or OpenRouter        | Provider key is `modellix`; you did not select a built-in `openai` / `openrouter` model                            |
| Wrong path / URL errors                  | `baseUrl` is `https://llm.modellix.ai/v1` (include `/v1`), not the media API host                                  |
| Developer role / 400 errors              | Set provider `compat.supportsDeveloperRole` to `false` (see [Pi Custom Models](https://pi.dev/docs/latest/models)) |

## Related

* [Pi Custom Models](https://pi.dev/docs/latest/models) — `models.json` schema and examples
* [Pi Providers](https://pi.dev/docs/latest/providers) — auth and custom providers overview
* [Models & Pricing](/llm/overview#models-and-pricing) — Model IDs and rates
* [LLM API guide](/llm/api/api) — protocols and curl examples
* [OpenClaw](/llm/agent/openclaw) · [OpenCode](/llm/agent/opencode) — other OpenAI-compatible custom setups
* [Plugin](/ways-to-use/plugin) · [Skill](/ways-to-use/skill) — Pi media capabilities