Back to Tutorials

Why does NVIDIA’s “OpenAI-compatible” Kimi K2.5 API keep failing in OpenClaw (and how do you make it rock-solid)?

9 min read

Why does NVIDIA’s “OpenAI-compatible” Kimi K2.5 API keep failing in OpenClaw (and how do you make it rock-solid)?

You’ve got the key. The docs say it’s OpenAI-compatible. A curl call might even feel snappy. And then—bam—your agent runner starts doing the digital equivalent of shrugging: 404s, schema validation blow-ups, “quota/billing” vibes, or a response that shows up after you’ve already made coffee, drank it, and questioned your life choices.

TL;DR: Treat NVIDIA’s hosted Kimi K2.5 as “OpenAI-compatible at the HTTP layer,” not “drop-in for every toolchain.” Prove your key with a known-good curl first, set the base URL correctly (https://integrate.api.nvidia.com/v1, not the full /chat/completions path in a base-url field), then wire OpenClaw using its current schema (custom provider via models.providers, strict validation). Assume trial rate limits, design for retries, and add a circuit-breaker fallback so your agents don’t stall when the endpoint queues.

The sneaky truth: “OpenAI-compatible” is necessary… and still not sufficient

NVIDIA isn’t lying. Their hosted endpoint for chat completions is literally the familiar OpenAI-shaped path: POST /v1/chat/completions at integrate.api.nvidia.com, with Bearer auth. citeturn0search1turn3view0

But agent frameworks aren’t just “an HTTP call.” They’re a stack of assumptions: where the base URL ends, how streaming is negotiated, how models are enumerated, how tool-calls are represented, how many requests happen in parallel, how timeouts are applied, and whether your config file is being validated against today’s schema or last month’s.

So if you want predictable behavior, you have to make the integration boring. Almost dull. That’s the goal.

Known-good curl first (seriously): a 60-second sanity check

Start with a minimal request that mirrors NVIDIA’s own published example: correct URL, correct Authorization header format, correct model string. citeturn3view0

export NVIDIA_API_KEY="nvapi-..."

curl -sS https://integrate.api.nvidia.com/v1/chat/completions \
  -H "Authorization: Bearer ${NVIDIA_API_KEY}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moonshotai/kimi-k2.5",
    "messages": [{"role":"user","content":"Say hi in one short sentence."}],
    "temperature": 0.6,
    "max_tokens": 128,
    "stream": false
  }' | jq

If that fails, don’t touch OpenClaw yet. Fix the basics. If it succeeds, now you’ve got a baseline: the key works, the model id is valid, and the endpoint is reachable.

Optional but useful: some accounts can also hit GET /v1/models to confirm the key and see what’s visible. This endpoint is referenced in NVIDIA forum troubleshooting and is handy when you’re chasing “works here, fails there” bugs. citeturn6search7turn6search8

curl -sS https://integrate.api.nvidia.com/v1/models \
  -H "Authorization: Bearer ${NVIDIA_API_KEY}" \
  -H "Accept: application/json" | jq

Base URL vs endpoint path: the copy/paste booby trap

A lot of “OpenAI-compatible” clients ask for a base URL, not a full endpoint. If you paste the full /v1/chat/completions into a base_url field, some libraries will happily append /chat/completions again. Congratulations, you just made a 404 generator.

For NVIDIA’s integrate endpoint, the stable pattern is:

  • Base URL: https://integrate.api.nvidia.com/v1
  • Client path: /chat/completions (client appends this)

NVIDIA’s own NeMo-Curator docs show base_url set to https://integrate.api.nvidia.com/v1 for OpenAI-format services. citeturn4view0

OpenAI SDK snippet (Python + Node) that behaves like curl

Once curl is green, move one rung up the ladder. Here’s a minimal OpenAI SDK pattern that’s worked well for “OpenAI-compatible but not OpenAI” endpoints: set base_url, set api_key, and keep your request shape plain.

from openai import OpenAI

client = OpenAI(
  base_url="https://integrate.api.nvidia.com/v1",
  api_key="nvapi-...",
)

resp = client.chat.completions.create(
  model="moonshotai/kimi-k2.5",
  messages=[{"role": "user", "content": "Give me a 10-word greeting."}],
  temperature=0.6,
  max_tokens=64,
)

print(resp.choices[0].message.content)
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://integrate.api.nvidia.com/v1",
  apiKey: process.env.NVIDIA_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "moonshotai/kimi-k2.5",
  messages: [{ role: "user", content: "Say hello, no extra words." }],
  temperature: 0.6,
  max_tokens: 64,
});

console.log(resp.choices[0].message.content);

If this is fast but your agent framework is slow, that’s a clue. Not proof, but a clue. Keep it in your pocket for the latency section below.

OpenClaw wiring: use the current schema, not vibes

OpenClaw is strict on config validation—unknown keys or “close enough” structures can prevent the Gateway from even starting. That’s a feature, not a bug. citeturn1search3

The modern approach (as of the docs updated around early 2026) is:

  • Select the model via agents.defaults.model.primary
  • Add custom providers (base URL + auth + model ids) via models.providers
  • If you set agents.defaults.models, it becomes your allowlist (and can silently block your shiny new model if you forget to include it)

Those rules and the custom-provider shape are documented in OpenClaw’s model provider docs. citeturn2search1turn2search2

Here’s a config template that treats NVIDIA as a custom OpenAI-compatible provider. It’s intentionally minimal; you can add fancy stuff later when things are stable.

{
  "env": {
    "NVIDIA_API_KEY": "nvapi-..."
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "nvidia/moonshotai/kimi-k2.5",
        "fallbacks": [
          "openai/gpt-5.2"
        ]
      },
      "models": {
        "nvidia/moonshotai/kimi-k2.5": {
          "alias": "Kimi K2.5 (NVIDIA)"
        }
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "nvidia": {
        "baseUrl": "https://integrate.api.nvidia.com/v1",
        "apiKey": "${NVIDIA_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "moonshotai/kimi-k2.5", "name": "Kimi K2.5" }
        ]
      }
    }
  }
}

Two gotchas I see a lot:

  • “Unrecognized key: models” usually means you’re editing the wrong config file for your OpenClaw build, or you’re pasting an agent-level snippet into the gateway-level config (or vice versa). Run openclaw doctor; it’ll point at the exact path/key that’s failing. citeturn1search3
  • Model refs with slashes must include a provider prefix. OpenClaw parses provider/model by splitting on the first slash, which is why nvidia/moonshotai/kimi-k2.5 is correct, and moonshotai/kimi-k2.5 by itself is not a valid OpenClaw ref. citeturn1search0turn2search2

About “free”: you’re dealing with a trial tier and rate limits (plan for it)

NVIDIA’s messaging around Kimi K2.5 on hosted endpoints is effectively “free for prototyping with registration,” which is true… in the way that a Costco sample is free. It’s not infinite, and it’s not a promise of production-grade capacity at 2pm on a Tuesday. citeturn3view0

NVIDIA forum staff have been pretty clear that build.nvidia.com’s trial experience is enforced via rate limits (and the old credit-style counters were removed). Limits vary per model and can vary with concurrent users, and they’re not always published in a neat table. citeturn8search0turn8search2

Also worth noting: the Kimi K2.5 model reference itself calls it a trial service governed by NVIDIA API Trial Terms of Service. That framing matters when you’re building an agent runner that assumes consistent throughput. citeturn0search0

Why curl is fast but OpenClaw is slow: a checklist that actually helps

This is the one people find spooky: “My curl returns quickly, but my agent tool hangs for minutes.” I’ve been there. It’s usually not one thing. It’s three things, arguing in a trench coat.

1) Streaming vs non-streaming (and SSE handling)

NVIDIA’s own Kimi K2.5 example enables streaming. If your framework requests stream=true but doesn’t read the stream promptly (or buffers it oddly), you can get the “it’s stuck” illusion. Start with stream=false until everything else is correct, then add streaming back intentionally. citeturn3view0

2) Token bloat (max_tokens is a foot-gun)

Interactive agents don’t need 16K output tokens per step. That’s not “generous,” that’s “I just increased my worst-case latency.” Cap max_tokens aggressively for tool loops: 256–1024 for planning steps, maybe 2048 when you genuinely need a big answer. NVIDIA’s sample payload uses a very large max_tokens value, which is fine for a demo but can be brutal in agent chains. citeturn3view0

3) Concurrency + retries = accidental self-DDoS

Agents fan out: tool calls, memory summarization, follow-up questions, self-critique loops. If you let OpenClaw (or anything) run those in parallel against a trial-limited endpoint, you can end up queueing yourself. The fix is boring: set conservative concurrency, add backoff, and respect provider rate limits. NeMo docs explicitly warn OpenAI-compatible services have rate limits (RPM/TPM/request size). citeturn4view0

Practical defaults I like for agent runners on trial endpoints:

  • Timeout: 30–60s per step (hard), with a smaller connect timeout
  • Retries: 2–3 max, exponential backoff + jitter (don’t dogpile)
  • Concurrency: start at 1 for the LLM call path; increase only after measuring
  • Streaming: off until stable; then on, but verify SSE parsing end-to-end

A production-minded pattern: health checks + circuit breaker + fallback (hello, n8n)

If you’re building agent workflows for real teams, the right question isn’t “Is this endpoint free?” It’s “What happens on a bad day?” Because bad days happen. A lot. And usually five minutes before a demo.

Here’s the pattern I recommend (and honestly, it’s the kind of thing we package into production-ready n8n automations at brilliantworkflows.com):

  1. Probe workflow (scheduled): every 1–5 minutes, run a tiny chat completion (max_tokens 16) and record latency + status code.
  2. Trip a circuit breaker: if p95 latency > threshold (say 20s) or errors spike (429/401/5xx), mark provider as “degraded.”
  3. Route agent calls: when degraded, send requests to a fallback provider/model (OpenAI, Anthropic, local Ollama, whatever you’ve got).
  4. Emit receipts: log which provider answered, tokens used, time-to-first-token (if streaming), and total time.

This is how you stop “provider drama” from leaking into user experience. Users don’t care that it queued. They care that it answered.

Troubleshooting matrix (symptom → likely cause → fix)

  • 404 Not Found: base URL includes /chat/completions and the client appended it again. Fix: base_url = https://integrate.api.nvidia.com/v1.
  • 401 Unauthorized: wrong header format or wrong key in the runtime environment. Fix: Authorization: Bearer <key>; verify with curl from the same machine/container.
  • “Out of credits” / quota-ish errors: you’re hitting trial limits or provider gating. Fix: reduce concurrency, add backoff, check build.nvidia.com rate limits, add fallbacks.
  • OpenClaw: Unrecognized key: models (or similar): schema drift or wrong file. Fix: openclaw doctor; migrate config to the documented models.providers + agents.defaults.model.primary structure.
  • Curl fast, agent slow: agent is making multiple calls, requesting huge max_tokens, or mishandling streaming. Fix: cap tokens, turn off streaming temporarily, drop concurrency, add timeouts.

A closing thought (and a dare)

“Compatible” is a starting line. Integration is the race. If you do nothing else this week, do the curl sanity check, fix your base URL, and add one fallback. Just one. Your future self will thank you, quietly, at 11:47pm.

And if you want the boring parts automated—health checks, circuit breakers, failover routing, logging—that’s the exact lane we build in at brilliantworkflows.com. Download, import into n8n, ship. Skip the tedious setup. (I know, I sound like a billboard, but it’s true.)