IronClaw custom API setup: providers, keys and privacy boundaries

IronClaw takes a custom API in one four-field block: a [llm.default] slot in ~/.ironclaw/reborn/config.toml carrying provider_id, base_url, model and api_key_env — or, when no slot exists, the LLM_BACKEND / LLM_BASE_URL / LLM_API_KEY environment variables it falls back to. Both forms are current and documented. What the configuration pages do not collect in one place is the list of things a custom endpoint then does not get — native streaming, model discovery, Anthropic cache_control breakpoints and accurate cost display among them — and that list is the part worth reading before you pick a provider.

One disambiguation first, because the search results are dominated by other products. This page is about github.com/nearai/ironclaw, described by its own repository metadata as "IronClaw is an Agent OS focused on privacy, security and extensibility": Rust, not archived and not a fork, 12,626 stars, created February 3, 2026 and last pushed on September 21, 2026 (GitHub API, same day). It is not the Corsair gaming mouse of that name, the Sanguine Productions tabletop RPG, the IRONCLAW crypto token, or the unrelated JoasASantos/ironclaw repository — none of whose prices or configuration belong anywhere near this page. Canonical documentation is docs.ironclaw.com and the repository's own docs/ tree; a third-party Mintlify mirror ranks for the same titles and can be stale.

Attribution is worth quoting rather than paraphrasing, because the vendor's own surfaces differ: ironclaw.com puts "Built by" beside a NEAR logo and the words "Near Foundation" in the body, and "— by NEAR AI" in the footer, while the GitHub organisation is nearai.

The minimal IronClaw custom provider configuration

The slot struct in ironclaw_config accepts exactly four optional fields, and its own doc comments describe them as overrides of the catalog entry: model overrides the provider's default_model, api_key_env overrides its api_key_env, and base_url overrides its default_base_url. The provider documentation adds that base_url "also works on any other provider when you need to route it through a proxy or a regional endpoint" — so this is not only a generic-adapter feature.

[llm.default]
provider_id = "openai_compatible"
base_url    = "https://api.kunavo.com/v1"
model       = "claude-sonnet-4-6"
api_key_env = "LLM_API_KEY"

Three rules that bite. Omitting base_url is fatal, not defaulted: the docs say it "leaves the slot pointing nowhere and model resolution fails", and the openai_compatible catalog entry carries base_url_required: true. api_key_env takes a variable name, never a key — a pasted secret is "rejected at parse time, not silently accepted", and ironclaw config set <provider>.api_key prompts with input hidden instead. Nothing applies until a restart: config set "never restarts anything", it prints the ironclaw service restart step you still have to run. And do not expect config set to write the slot for you — the configuration page lists [llm.default] among the sections "edited in config.toml directly", and config set "rejects an unsupported key rather than silently doing nothing".

The environment form is the documented fallback when [llm.default] is absent, and the docs settle the choice plainly: "Both work … Prefer the TOML slot for a permanent install, and the environment form for one-off runs and containers."

export LLM_BACKEND=openai_compatible
export LLM_BASE_URL=https://api.kunavo.com/v1
export LLM_API_KEY=sk-kn-...
export LLM_MODEL=claude-sonnet-4-6

# optional: LLM_EXTRA_HEADERS is the openai_compatible entry's
# extra_headers_env; the timeout is a general .env.example setting
export LLM_EXTRA_HEADERS=X-Title:MyAgent
export LLM_REQUEST_TIMEOUT_SECS=120

Resolution order is compiled defaults < config.toml < environment variables < CLI flags, so an exported variable quietly outranks the file you just edited. The CLI route avoids hand-editing altogether: ironclaw models list, then ironclaw models set-provider <id> --model <model>, then ironclaw models status. Confirm your paths with ironclaw config path rather than trusting either documented location — the quickstart page says everything lives under ~/.ironclaw while the configuration and onboarding pages say ~/.ironclaw/reborn. One operational trap for hosted users: the configuration page says ironclaw service commands "do not work on a NEAR AI hosted instance — there is no user service manager for them to talk to", so you SSH in for ironclaw config and restart from the Agent Dashboard instead. All quotations read from the main branch on September 21, 2026.

What a custom endpoint does not reach

These are IronClaw's own statements about its intended runtime behaviour, read from the source and contract files on main. They are not observed runs, and main was ahead of the 1.4.0 release tag — published August 28, 2026, per the GitHub releases API — when they were read.

IronClaw's catalog is a chat catalog, and Kunavo serves no embedding, text-to-speech or speech-to-text model, so any part of your setup that needs one has to point somewhere else entirely.

IronClaw's cost display is not your bill

Two separate paths compute money inside IronClaw, they disagree, and neither one reads your provider. price_usage() in ironclaw_common prices from a hardcoded per-token table and falls back to default_cost() — 0.0000025 input and 0.00001 per token, a GPT-4o-shaped $2.50 / $10.00 per million — with the stated reasoning that "a new paid model never silently prices at zero". Meanwhile the loop host's StaticModelCostTable does the opposite for budget reservations: a profile missing from its table "falls back to None, which the accountant treats as zero-cost". And on the llm_costs path the cache-read discount is guessed from the model name by substring — claude divides by ten, gpt or an o1/o3/o4 prefix by two, everything else by one.

The practical consequence is that IronClaw's budget.user_daily_usd, budget.pause_at and the rest of the [budget] keys police an estimate, not a charge. They are still worth setting on an always-on agent — a runaway loop stopped early is the point — but reconcile against the usage your provider recorded, not against the number on screen.

A worked estimate for an agent day

This is token arithmetic, not a measured task cost and not a bill ceiling. Assume one day of agent activity totalling 1,000,000 uncached input tokens and 40,000 output tokens — an assumption for illustration, chosen because an always-on runtime accumulates input through heartbeat ticks and routines rather than through long replies. Rates are live Kunavo catalog prices per million tokens.

The last column is the useful surprise, and it is a property of the id string rather than of the model. vision_models.rs substring-matches a fixed list that includes claude-opus-, claude-sonnet-, claude-haiku- and claude-fable-, so those ids route image attachments; the other ids in the table above match none of gpt-4o, gemini-1.5, gemini-2 or the rest of the list and would be classified text-only. On a miss the loop-host gateway sends the message text without the image parts and raises no error — the durable transcript keeps an <attachments> pointer, but the model never sees the image. Read the pattern list against the exact id you intend to type before assuming image input works. Scale the dollar figures by your own days before treating them as a budget. Kunavo's catalog amount is a billing floor rather than a cap: when the upstream reports its charge, the bill is the greater of catalog cost and upstream cost times the applicable markup. Cache charges and external tools sit outside this example, and the minimum top-up is $10 in prepaid credit — a funding minimum, not a task fee or a subscription. See billing details.

Which route wins, and what IronClaw itself costs

The software is free: the repository root carries both LICENSE-APACHE and LICENSE-MIT, and its README states MIT OR Apache 2.0. There is no paid edition of the binary and no licence fee. What you pay is tokens, plus hosting if you take the vendor's.

Hosted plan prices read from ironclaw.com on September 21, 2026; there is no /pricing page, the plans live on the homepage, and the rendered markup shows the $5 inside a struck-through span with $0 as the live price. The homepage also claims "Spin up to 5 agents in a Trusted Execution Environment with up to 130M tokens per month" — that sentence sits above all three cards and names no plan, so do not attach it to one. Three things this guide could not establish and will not guess: whether the hosted plans permit a third-party key at all, what the included credits actually buy or what happens when they run out, and which plan the 130M figure belongs to. Token rates read from near.ai/pricing the same day, which states "There is no platform fee on top of the model rate" and covers its confidential text models only.

One privacy boundary to state plainly, because it is the reason people choose this runtime. The controls IronClaw's own README and security page describe — secrets "encrypted at rest" and injected at the host boundary, the WASM sandbox for untrusted tools, endpoint allowlisting, leak detection — are local controls over the machine running the agent. The hardware attestation is a separate, NEAR AI Cloud property: near.ai says inference there "executes in an Intel TDX + NVIDIA confidential-GPU enclave" and that "each response carries a verifiable hardware quote". Pointing IronClaw at a third-party endpoint sends prompt content to that endpoint under that endpoint's terms, and nothing in either list follows it there. The vendor-authored "OpenClaw vs IronClaw" table on ironclaw.com is marketing by one side, not a neutral comparison — and be careful with search results, because in a results-page sample taken on September 17, 2026, the four query forms best api for ironclaw, cheapest api for ironclaw, best model for ironclaw and ironclaw custom provider each returned eight or more OpenClaw results in the top ten, whose model rankings describe a different product.

Set it up, then check the first charge

Kunavo publishes an OpenAI-shaped endpoint at https://api.kunavo.com/v1 and an Anthropic-shaped one, which map onto the openai_compatible and anthropic provider ids. Kunavo has not runtime-tested IronClaw, so treat the block above as a documented-protocol starting point and not as a compatibility claim: keep a working route available, run one bounded task, and read the charge your account actually recorded. If you drive Goose from IronClaw over ACP — .env.example documents the Agent Client Protocol sandbox and the command ironclaw acp add goose — the Goose integration covers that side separately, and creating a Kunavo account funds a key when you are ready. For the surrounding choices, see the OpenAI-compatible API reference, OpenRouter alternatives and AI cost optimization.

FAQ

Repository metadata, providers.json, CONTRACT.md, llm_costs.rs, vision_models.rs, the docs/ tree, ironclaw.com and near.ai/pricing all read on September 21, 2026, from the main branch rather than the 1.4.0 release tag. No IronClaw request has been sent to a Kunavo endpoint; every compatibility statement here is a reading of both sides' documentation. Kunavo token rates come from the live catalog, and every dollar example is illustrative token arithmetic.