Mythical Pro Agents

# OpenAI-Compatible Endpoints

GitHub Edit page

# OpenAI-Compatible Endpoints

Oracle uses the official OpenAI Node.js SDK, which allows it to connect to any API that adheres to the OpenAI API specification. This includes:

- Official OpenAI API
- Azure OpenAI Service
- Local inference servers (e.g., vLLM, Ollama)
- Proxy servers (e.g., LiteLLM)

## #Azure OpenAI

Oracle uses Azure's v1 Responses endpoint when `--azure-endpoint` (or `azure.endpoint`) is set. Pass your resource endpoint, Azure key, and deployment name:

    export AZURE_OPENAI_ENDPOINT="https://your-resource-name.openai.azure.com/"
    export AZURE_OPENAI_API_KEY="your-azure-api-key"
    export AZURE_OPENAI_DEPLOYMENT="gpt-5-1-pro"

Key lookup for GPT-family models when an Azure endpoint is set:

- First looks for `AZURE_OPENAI_API_KEY`.
- Falls back to `OPENAI_API_KEY` if the Azure key is missing.

Without an Azure endpoint, Oracle keeps using `OPENAI_API_KEY` as before. If Azure env/config is present but you want first-party OpenAI for one run, pass `--provider openai` or `--no-azure`.

Notes:

- Oracle calls Azure at `https://<resource>.openai.azure.com/openai/v1`.
- For Responses API runs, Azure expects `model` to be your deployment name. Oracle fails early when an Azure endpoint is active without a deployment, except for `gpt-5.5-pro` where the CLI model id is used as the implicit deployment.
- API runs print the selected route without secrets, for example `Provider: Azure OpenAI | endpoint: your-resource.openai.azure.com | deployment: my-deployment | key: AZURE_OPENAI_API_KEY|OPENAI_API_KEY`.
- `AZURE_OPENAI_API_VERSION` is still accepted for back-compat, but Azure's v1 Responses endpoint does not require it.

## #Provider diagnostics

Check provider readiness before an API run:

    oracle doctor --providers --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro
    oracle --preflight --models gpt-5.4,gemini-3-pro
    oracle --route --model gpt-5.4

The output is redacted and local: provider, base host, key source, Azure status, and missing-route errors. These commands exit before sending a prompt or creating a session.

When Azure env/config is present, GPT-family API models route through Azure unless you force first-party OpenAI:

    oracle --provider openai --route --model gpt-5.4
    oracle --no-azure --route --model gpt-5.4

### #CLI Configuration

You can also pass the Azure settings via CLI flags (env for the key is still recommended):

    oracle --azure-endpoint https://... --azure-deployment my-deployment-name

Force first-party OpenAI when Azure env vars are exported:

    oracle --provider openai --engine api --model gpt-5.5-pro -p "Review this"
    oracle --no-azure --engine api --model gpt-5.5-pro -p "Review this"

## #GPT-5.6 Pro reasoning mode

GPT-5.6 Pro is a Responses API execution mode, not a separate model slug. Select the Sol model and enable Pro mode explicitly:

    oracle --engine api \
      --model gpt-5.6-sol \
      --reasoning-mode pro \
      --reasoning-effort max \
      -p "Review this difficult architecture" \
      --file "src/**"

Oracle sends `model: "gpt-5.6-sol"` with `reasoning.mode: "pro"` and `reasoning.effort: "max"`. Mode and effort are independent. GPT-5.6 supports `none`, `low`, `medium`, `high`, `xhigh`, and `max`; without an explicit effort, Oracle retains the model's configured effort. Pro-mode runs use Oracle's long-running API defaults: they detach unless `--wait` is supplied, default to a 60-minute timeout, and use Responses background mode when the selected route supports it.

`--reasoning-mode` accepts `standard` or `pro`; `--reasoning-effort` accepts all six GPT-5.6 effort levels. Both are API-only and restricted to the GPT-5.6 family. Oracle rejects reasoning mode for OpenRouter and custom `--base-url` routes because those routes currently use Oracle's Chat Completions adapter, which cannot represent Responses API reasoning mode.

Do not pass `--model gpt-5.6-pro` or `--model gpt-5.6-sol-pro`; Oracle rejects those fake slugs and points to `--reasoning-mode pro`.

## #Custom Base URLs (LiteLLM, Localhost)

For other compatible services that use the standard OpenAI protocol but a different URL:

    oracle --base-url http://localhost:4000

Or via `config.json`:

    {
      "apiBaseUrl": "http://localhost:4000"
    }

If a gateway exposes a different on-wire model id, add an API-only override to the user config at `~/.oracle/config.json`:

    {
      apiBaseUrl: "http://localhost:4000",
      model: "gpt-5.5",
      modelOverrides: {
        "gpt-5.5": {
          apiModel: "gateway-model",
          reasoning: { effort: "high" },
        },
      },
    }

Overrides accept existing built-in model keys only and are ignored in project `.oracle/config.json` files. See Local configuration for the full field list and precedence.

## #Model aliases

Oracle keeps a stable CLI-facing model set, but some names are aliases for the concrete API model ids it sends:

- `gpt-5.1-pro`, `gpt-5.2-pro` → `gpt-5.5-pro` (API)

Notes:

- `gpt-5.1-pro` and `gpt-5.2-pro` are CLI aliases for “the current Pro API model” — OpenAI’s API uses `gpt-5.5-pro`.
- If you want the classic Pro tier explicitly, use `gpt-5-pro`.

### #Browser engine vs API base URLs

`--base-url` / `apiBaseUrl` only affect API runs. For browser automation, use `--chatgpt-url` (or `browser.chatgptUrl` in config) to point Chrome at a specific ChatGPT workspace/folder such as `https://chatgpt.com/g/.../project`.

### #Example: LiteLLM

LiteLLM allows you to use Azure, Anthropic, VertexAI, and more using the OpenAI format.

1. Start LiteLLM:

```bash litellm --model azure/gpt-4-turbo` ``

2. Connect Oracle:

```bash oracle --base-url http://localhost:4000` ``

## #OpenRouter

Oracle can also talk to OpenRouter (Responses API compatible) with any model id:

    export OPENROUTER_API_KEY="sk-or-..."
    oracle --model minimax/minimax-m2 --prompt "Summarize the notes"

- If `OPENROUTER_API_KEY` is set and no provider-specific key is available for the chosen model, Oracle defaults the base URL to `https://openrouter.ai/api/v1`.
- You can still set `--base-url` explicitly; if it points at OpenRouter (with or without a trailing `/responses`), Oracle will use `OPENROUTER_API_KEY` and forward optional attribution headers (`OPENROUTER_REFERER` / `OPENROUTER_TITLE`).
- Multi-model runs accept OpenRouter ids alongside built-in ones. See `docs/openrouter.md` for details.