⌘K

OpenClaw

Overview

OpenClaw supports custom model providers through ~/.openclaw/openclaw.json. Add Vtrix under models.providers, use the OpenAI-compatible request adapter, and select the Vtrix model with an OpenClaw model reference such as vtrix/gpt-5.3-codex.

Prerequisites

  • Node.js 22.19+, 23.11+, or 24+
  • OpenClaw CLI
  • A Vtrix API key, created in Settings
Optional: use Vtrix Doctor

You can also use Vtrix Doctor to check the local Base URL, API key, and model settings before editing files. Supported tools, including OpenClaw and Hermes, can be configured after confirmation.

Configuration Steps

1

Install OpenClaw

• Using the installer script

curl -fsSL https://openclaw.ai/install.sh | bash

• Or using npm

npm install -g openclaw@latest
openclaw onboard --install-daemon

After installation, run:

openclaw --version
openclaw doctor
2

Store your Vtrix API key

OpenClaw loads .env from the current working directory and ~/.openclaw/.env. Create or edit the global file:

mkdir -p ~/.openclaw
vim ~/.openclaw/.env

Add:

VTRIX_API_KEY=YOUR_VTRIX_API_KEY
3

Add Vtrix as a custom provider

Create or edit ~/.openclaw/openclaw.json:

vim ~/.openclaw/openclaw.json

Add or merge the following JSON5 configuration:

{
  agents: {
    defaults: {
      model: { primary: "vtrix/gpt-5.3-codex" },
      models: {
        "vtrix/gpt-5.3-codex": { alias: "GPT-5.3 Codex via Vtrix" },
        "vtrix/gpt-5.5": { alias: "GPT-5.5 via Vtrix" },
        "vtrix/qwen3.7-max": { alias: "Qwen3.7 Max via Vtrix" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      vtrix: {
        baseUrl: "https://cloud.vtrix.ai/llm",
        apiKey: "${VTRIX_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gpt-5.3-codex", name: "GPT-5.3 Codex" },
          { id: "gpt-5.5", name: "GPT-5.5" },
          { id: "qwen3.7-max", name: "Qwen3.7 Max" },
        ],
      },
    },
  },
}
Base URL

Use https://cloud.vtrix.ai/llm as the Vtrix OpenAI-compatible Base URL. OpenClaw’s openai-completions adapter appends the chat completions route for model calls.

4

Validate and start OpenClaw

Validate the configuration:

openclaw config validate
openclaw models list

Start or restart the gateway:

openclaw gateway start

For a quick local check, run:

openclaw infer "Summarize this project in one sentence."

If OpenClaw responds normally, requests are routed to Vtrix through the configured provider. You can also check usage or billing in Vtrix Settings.

Troubleshooting

Invalid config or gateway refuses to start

Cause: ~/.openclaw/openclaw.json is JSON5, but it still must match OpenClaw’s schema. Unknown keys or malformed values can make the gateway reject the file.

Fix:

openclaw config validate
openclaw doctor --fix
Error: 401 Unauthorized

Cause: VTRIX_API_KEY is missing, incorrect, or not loaded by OpenClaw.

Fix:

grep VTRIX_API_KEY ~/.openclaw/.env

Confirm the key exists, then restart OpenClaw.

Model picker does not show Vtrix models

Cause: agents.defaults.models does not include vtrix/... model references, or the models.providers.vtrix.models entries are missing.

Fix: Confirm both sections exist:

agents: {
  defaults: {
    model: { primary: "vtrix/gpt-5.3-codex" },
    models: { "vtrix/gpt-5.3-codex": { alias: "GPT-5.3 Codex via Vtrix" } },
  },
}
Error: model not found

Cause: The model ID under models.providers.vtrix.models[].id does not match a Vtrix model ID.

Fix: Open the Models page, copy the correct model ID, and update both the provider model entry and the vtrix/... reference.