Configure OpenClaw with Zukko — provider choice and config

OpenClaw connects to Zukko as a custom model provider: you specify the address, the fetch_... key, the API type, and a list of models. The easiest places to slip up are the /v1 suffix and the model definitions. Below are both connection options, ready-made configs, and common errors.

What OpenClaw is

OpenClaw↗ is an open-source personal AI assistant that runs on your machine. Its core is the Gateway: it stores settings, calls models, and connects the agent to interfaces — a terminal TUI, a web dashboard, and messaging apps. The agent's model is set through providers; besides the built-in ones, you can define your own, which is how Zukko connects.

Two connection options

The Zukko gateway understands both formats and can serve any catalog model through either. Pick the one you're used to, or the one that better supports the OpenClaw features you need.

Quick setup with onboard (OpenAI)

Install OpenClaw (the official installer is described in the docs; there's also an npm package):

npm install -g openclaw

Then run setup without interactive prompts. The flags below come from the openclaw onboard reference in the OpenClaw docs:

openclaw onboard --non-interactive --accept-risk \
  --auth-choice custom-api-key \
  --custom-base-url "https://api.zukko.pro/v1" \
  --custom-model-id "claude-sonnet-5" \
  --custom-api-key "fetch_..." \
  --secret-input-mode plaintext \
  --custom-compatibility openai

Replace fetch_... with your key from the API keys page↗. The --accept-risk flag is required in non-interactive mode: it acknowledges the risks of an agent with system access. Flag names change between versions — if the command is rejected, check openclaw onboard --help or configure manually as described below.

Manual setup: OpenAI Compatible

The OpenClaw config is ~/.openclaw/openclaw.json in JSON5 format:

{
  models: {
    mode: "merge",
    providers: {
      zukko: {
        baseUrl: "https://api.zukko.pro/v1",
        apiKey: "fetch_...",
        api: "openai-completions",
        models: [
          {
            id: "claude-sonnet-5",
            name: "Claude Sonnet 5",
            input: ["text"],
            contextWindow: 1000000,

What matters here:

• baseUrl — https://api.zukko.pro/v1, with /v1.
• apiKey — your fetch_... key.
• api — openai-completions.
• models — the provider's models; id must match the id in the Zukko catalog.
• agents.defaults.model.primary — the default model in provider/model form.
• agents.defaults.models — aliases and per-model settings for the agent. The Zukko docs recommend adding every connected model here.

mode: "merge" keeps OpenClaw's built-in providers and adds Zukko alongside them.

Manual setup: Anthropic Messages

Same file, different API type and address:

{
  models: {
    mode: "merge",
    providers: {
      zukko: {
        baseUrl: "https://api.zukko.pro",
        apiKey: "fetch_...",
        api: "anthropic-messages",
        models: [
          {
            id: "claude-sonnet-5",
            name: "Claude Sonnet 5",
            input: ["text"],
            contextWindow: 1000000,

Differences from the OpenAI option:

• baseUrl — https://api.zukko.pro, without /v1.
• api — anthropic-messages.

Applying and checking

According to the OpenClaw docs, the Gateway watches the config file and picks up most changes on its own. After editing:

openclaw config validate
openclaw models list

The first command checks syntax and schema, the second shows whether OpenClaw sees the zukko/... models. There is a config.apply RPC method for replacing the config, but it overwrites the whole file — to add a provider, editing openclaw.json is enough.

Then start the terminal UI with openclaw or open the web dashboard with openclaw dashboard and ask a question. The request should show up under Usage in your Zukko dashboard. To switch models in chat, use /model, for example /model sonnet or /model zukko/claude-sonnet-5.

Adding more models

To switch between Zukko models, add them to the provider's models array:

models: [
  { id: "claude-sonnet-5", name: "Claude Sonnet 5", input: ["text"], contextWindow: 1000000, maxTokens: 8192 },
  { id: "claude-opus-5-5", name: "Claude Opus 5.5", input: ["text"], contextWindow: 1000000, maxTokens: 8192 },
  { id: "gpt-5.6-sol", name: "GPT-5.6 Sol", input: ["text"], contextWindow: 1000000, maxTokens: 8192 },
  { id: "glm-5.3-flash", name: "GLM 5.3 Flash", input: ["text"], contextWindow: 128000, maxTokens: 8192 },
]

And aliases in agents.defaults.models:

models: {
  "zukko/claude-sonnet-5": { alias: "sonnet" },
  "zukko/claude-opus-5-5": { alias: "opus" },
  "zukko/gpt-5.6-sol": { alias: "sol" },
  "zukko/glm-5.3-flash": { alias: "flash" },
}

Zukko prices per 1M tokens (input/output): Claude Sonnet 5, Claude Opus 5.5, and GPT-5.6 Sol — $0.30/$0.30, GLM 5.3 Flash — $0.04/$0.04. For the current list, use GET https://api.zukko.pro/v1/models or the Models↗ page in your dashboard. If a model accepts images and you want to send them from chats, the OpenClaw docs say to set input: ["text", "image"] for it.

If it fails

The model doesn't show up in openclaw models list or /model

1. The model is defined in models.providers.zukko.models and its id matches the Zukko catalog.
2. The model is referenced as zukko/<id>.
3. openclaw config validate shows no errors — the Gateway won't apply an invalid file.

An error like "not allowed by agents.defaults.modelPolicy.allow"

Your config has an allowlist in agents.defaults.modelPolicy.allow. Add zukko/<id> to it or remove the restriction.

401 unauthorized

Check apiKey: the exact fetch_... value from the keys page↗, with no spaces.

402

Your balance has run out — top up↗ and retry.

404

Almost always a mixed-up /v1:

• for openai-completions — https://api.zukko.pro/v1;
• for anthropic-messages — https://api.zukko.pro.

FAQ

Which API option should I choose?

If you're used to the OpenAI SDK, pick openai-completions; if the Anthropic SDK, anthropic-messages. The set of available models is the same. If some OpenClaw feature works in one option and not the other, just switch api and baseUrl.

Can I keep both options in one config?

Yes, define two providers with different names:

providers: {
  zukko_openai: { baseUrl: "https://api.zukko.pro/v1", apiKey: "fetch_...", api: "openai-completions", models: [/* ... */] },
  zukko_anthropic: { baseUrl: "https://api.zukko.pro", apiKey: "fetch_...", api: "anthropic-messages", models: [/* ... */] },
}

Model references then become zukko_openai/claude-sonnet-5 and zukko_anthropic/claude-sonnet-5.

How do I see which models Zukko has?

Call GET https://api.zukko.pro/v1/models with your key or open the Models↗ page in the dashboard. More in the models reference↗.

What does the agent cost, and does caching matter?

The agent sends a large, repeated context to the model, so most of the spend is input tokens. Vendors charge around 10% of the input price for prompt-cache reads, while Zukko bills cached tokens at the regular input price. So for long agent sessions the real difference from the official price list is smaller than a direct price comparison suggests. Watch your spend in the dashboard and set a daily limit on the key.

A short cheat sheet is in the Zukko docs for OpenClaw↗.