⌁ Guides

OpenClaw

Register Gondola as an openai-completions provider in openclaw.json and run any Venice model, paid per request in USDC on Base.

Create an API key

Sign in with your Base wallet at /keys and mint a Gondola API key. Keys start with gnd_. It authenticates every request and each call is charged in USDC against your Gondola balance.

Top up USDC on Base once at /wallet. The same balance powers the browser chat and every tool you connect.

Install the provider plugin

The fastest path is the official plugin. It registers the gondola provider with a curated catalog of 14 flagship models, discovers all 105 chat models live from the API, and shows real USD prices per model:

shell

openclaw plugins install @gondola-market/openclaw-gondola-provider
export GONDOLA_API_KEY=gnd_xxxx
openclaw models set gondola/claude-sonnet-5

Source and issues: github.com/Gondola-Market/openclaw-gondola-provider (MIT). If the provider does not appear after install, run openclaw plugins enable gondola.

Prefer no plugin? Add a Gondola provider by hand to ~/.openclaw/openclaw.json (JSON5). The provider's api must be the literal openai-completions, and the default model is set at agents.defaults.model.primary as gondola/<id>:

~/.openclaw/openclaw.json

{
  agents: {
    defaults: {
      model: { primary: "gondola/claude-sonnet-5" },
    },
  },
  models: {
    providers: {
      gondola: {
        baseUrl: "https://api.gondola-ai.com/v1",
        apiKey: "${GONDOLA_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "claude-sonnet-5", name: "Claude Sonnet 5", contextWindow: 1000000, maxTokens: 32768 },
        ],
      },
    },
  },
}

Export the key before starting OpenClaw:

shell

export GONDOLA_API_KEY=gnd_xxxx

Base URL gotcha

The baseUrl is api.gondola-ai.com/v1 only. Do not append /chat/completions; the provider adds the path itself.

Also available: the Anthropic Messages wire format

The example above speaks openai-completions. OpenClaw also has an api: "anthropic-messages" custom-provider format, and Gondola's /v1/messages surface speaks it too. Point baseUrl at the host root, no /v1 suffix (OpenClaw appends the path itself, the same convention Claude Code uses):

~/.openclaw/openclaw.json (alternative provider)

{
  models: {
    providers: {
      "gondola-anthropic": {
        baseUrl: "https://gondola-ai.com",
        apiKey: "${GONDOLA_API_KEY}",
        api: "anthropic-messages",
        models: [
          { id: "claude-sonnet-5", name: "Claude Sonnet 5", contextWindow: 1000000, maxTokens: 64000 },
        ],
      },
    },
  },
}

Pick a model

Gondola serves the full Venice catalog. Each model needs an entry in the provider's models array keyed by its exact id, referenced as gondola/<id>. Pull the live list:

shell

curl https://api.gondola-ai.com/v1/models

Each entry includes context_length and max_completion_tokens. Copy those into contextWindow and maxTokens per model. The published numbers are the limits the gateway actually enforces, so copying them is always safe.

Prompt privacy

Gondola never stores prompts or completions: requests are metered, forwarded, and gone when the response finishes (the one exception, a video source clip over 18 MiB, is held privately for the length of its job; see /privacy), and Venice runs a no-logging model underneath. For zero retention on Venice-controlled infrastructure too, pick a model whose privacy field reads private on GET /v1/models. Details on /privacy.

Notes and troubleshooting

Set real context values

If you omit contextWindow and maxTokens, OpenClaw defaults to 200000 and 8192, which may not match the model you chose. Use the real numbers from the models list.

Cap the price on unattended runs

OpenClaw agents can run many steps unwatched. If the provider config lets you add a custom request header, set x-gondola-max-factor to a value from 0 to 1 to refuse any request priced above that ceiling instead of paying more; omit it and a request with no cheaper capacity can fall through to Gondola's own backup key at Venice list price. For a hard dollar limit rather than a relative one, send x-gondola-max-charge-usd (for example 0.50) and any request whose estimated charge would exceed it is refused with a 402 before anything is billed.

Environment substitution (${GONDOLA_API_KEY}) accepts uppercase variable names only and throws at load if the variable is unset, so export it first. The config schema is strict; run openclaw doctor --fix to diagnose a rejected config. If a request returns insufficient balance, top up at /wallet.

Loading page

{ agents: { defaults: { model: { primary: "gondola/claude-sonnet-5" }, }, }, models: { providers: { gondola: { baseUrl: "https://api.gondola-ai.com/v1", apiKey: "${GONDOLA_API_KEY}", api: "openai-completions", models: [ { id: "claude-sonnet-5", name: "Claude Sonnet 5", contextWindow: 1000000, maxTokens: 32768 }, ], }, }, }, }

{ models: { providers: { "gondola-anthropic": { baseUrl: "https://gondola-ai.com", apiKey: "${GONDOLA_API_KEY}", api: "anthropic-messages", models: [ { id: "claude-sonnet-5", name: "Claude Sonnet 5", contextWindow: 1000000, maxTokens: 64000 }, ], }, }, }, }