Use your own agent with Oraicle

Oraicle does not run your agent. It serves the model your agent calls. You point the agent at our API with a key, and every call it makes is paid per token from your prepaid wallet.

Your agent runs on your own computer, and you are responsible for what it does there. Its tools, skills and chat channels are its own, not ours.

The three settings

Setting	Value
Base URL	https://api.oraicle.me/v1
API key	A key from the console, read from an environment variable
Model	An id from Models, such as openai/gpt-oss-120b

The API takes requests in the OpenAI Chat Completions format. Keys begin with oai-.

OpenClaw

OpenClaw is an open-source agent that runs on your computer and talks to you through WhatsApp, Telegram, Slack and other chat apps. It reads its settings from ~/.openclaw/openclaw.json, and you add Oraicle there as a custom provider.

1. A key for the agent

On the API keys tab of the console, choose Create key. Give the agent a key of its own, with a Spend limit. Once that key has spent the limit, the API refuses its next call; the rest of your balance is left alone.

Put the key in ~/.openclaw/.env, the file OpenClaw’s own docs recommend for provider keys:

~/.openclaw/.env

ORAICLE_API_KEY=oai-...

2. Oraicle as a provider

Add this to ~/.openclaw/openclaw.json. If the file already has a models or an agents block, merge these lines into it rather than adding a second one.

~/.openclaw/openclaw.json

{
  models: {
    providers: {
      oraicle: {
        baseUrl: "https://api.oraicle.me/v1",
        apiKey: "${ORAICLE_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "openai/gpt-oss-120b", name: "gpt-oss-120b", contextWindow: 131072 },
          { id: "moonshotai/Kimi-K2.6", name: "Kimi K2.6", contextWindow: 262144 },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "oraicle/openai/gpt-oss-120b" },
    },
  },
}

Line by line:

• apiKey names the environment variable, so the key itself is never written into the file.
• api: "openai-completions" is OpenClaw’s name for the Chat Completions format. We have no /v1/responses endpoint, so openai-responses does not work here.
• id is the model id exactly as Models lists it. contextWindow is how many tokens the model reads at once, as the model’s page on oraicle.me shows it.
• primary is oraicle/ followed by the model id. OpenClaw reads the first part as the provider and the rest as our id, slash included.

Restart OpenClaw’s gateway so it reads the new key:

openclaw gateway restart

Then send your agent one message and open Usage in the console: the model is listed there with what the call cost.

OpenClaw’s own guide to custom providers lists every other field this block accepts.

Which models to pick

An agent works by calling tools — reading a file, searching, running a command — so the model has to call tools well. Start with openai/gpt-oss-120b: in our own chat it drives every live-data tool, and it costs less per token than most models on the list. moonshotai/Kimi-K2.6 handles tools as well and reads a conversation twice as long.

Do not use meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8 for an agent: it writes a tool call out as text instead of making one.

Any other agent tool

Most agent tools ask for the same three things under their own names: a base URL (sometimes “API base” or “endpoint”), an API key and a model name. Give them https://api.oraicle.me/v1, your key and a model id. Where a tool asks which API it talks to, choose OpenAI or “OpenAI-compatible”. Everything below holds for them too. n8n, LiteLLM and Open WebUI have pages of their own.

What Oraicle does for an agent, and what it does not

• Chat completions, streamed or whole, with tool calling. Your agent’s own tools are sent to the model, and the model’s calls to them come back to your agent to run.
• Live data only where the agent lets you add it. Web, news, weather and the other oracles are switched on with a tools entry such as {"type": "weather"}. That entry is our addition to the OpenAI format, so an agent tool can use it only if it lets you add your own entries to the request. OpenClaw fills that list with its own tools.
• No embeddings. There is no /v1/embeddings endpoint yet. OpenClaw’s memory search needs embeddings from somewhere else; without them it searches by keyword.
• Only what the agent sends. What reaches us is each request your agent sends to the model: your message, and anything the agent put in it, such as a file it read. Nothing else it does passes through us.

What it costs

The same per-token prices as on Models, paid from your balance. No subscription, and no charge per agent.

An agent sends more than you type. Every call carries its instructions, the descriptions of its tools and the conversation so far. You pay the input price on all of it, every time. One message from you can take several calls while the agent works.

A call that fails before the model produces anything is not billed. A call already running when the key reaches its Spend limit finishes, so the key can end slightly above the limit.

Where it breaks

The API answers	What it means
User balance is zero (or less).	Your wallet is empty. Every call is refused until you top up.
Token limit reached.	This key has spent its Spend limit. Raise the limit on the API keys tab, or give the agent a new key.
Too many requests — please slow down.	More than 90 calls in one minute from one account. An agent in a tight loop can get there; the count starts again at the next minute.
Invalid personal access token	The key is mistyped, revoked or past its Expiry. The console suggests 90 days when you create a key; an agent that runs for months needs a longer one, or a new key when it ends.
invalid model ID	The id in models or primary is not one of ours. Ids are case-sensitive, and the part before the slash belongs to the id.

A long session that stops with an error about the context length has outgrown the model. Start a new session, or move to a model with a longer contextWindow.