LobeChat (LobeHub): connect Zukko via the UI and environment variables

LobeChat is an open-source chat interface that the project now develops under the name LobeHub. You can connect your own API in two ways: in the provider settings in the UI, or with environment variables when you self-host. For Zukko you need the address https://api.zukko.pro/v1 and a fetch_... key. Below are both methods based on the official LobeHub docs, model list configuration, a cost estimate and troubleshooting.

LobeChat and LobeHub: what to know before you start

Many guides online show a one-command docker run with the lobe-chat image. The current documentation describes something else: the lobehub/lobehub image, port 3210, and a server version with a database — PostgreSQL, auth secrets and S3 storage for files. Do the full deployment by the official LobeHub guide; this article covers only the model connection part.

Method 1: through the UI

If LobeHub is already running, you can set up the provider without a restart:

1. Open app settings → AI Providers (App Settings → AI Providers in the docs).
2. Select the OpenAI provider and switch it on.
3. Paste your fetch_... key into API Key.
4. Set Proxy URL to https://api.zukko.pro/v1.
5. Click Check to test the connection.
6. Enable the models you need in the list. If Zukko models aren't there, fetch the list or add models manually by ID — for example, claude-sonnet-5.

Changes are saved automatically. You can then choose the provider and model in the agent settings.

Method 2: LobeChat with your own API via environment variables

When self-hosting, it's convenient to configure the provider on the server, so users don't have to enter a key. Add these lines to the env file you created following the LobeHub guide (the docs call it lobehub.env):

OPENAI_API_KEY=fetch_your_key
OPENAI_PROXY_URL=https://api.zukko.pro/v1
OPENAI_MODEL_LIST=-all,+claude-sonnet-5=Claude Sonnet 5<1000000>,+claude-opus-5-5=Claude Opus 5.5<1000000>,+gpt-5.6-sol=GPT-5.6 Sol<1000000>,+gpt-5.6-luna=GPT-5.6 Luna<1000000>,+glm-5.3-flash=GLM 5.3 Flash<128000>
SYSTEM_AGENT=default=openai/glm-5.3-flash

What each variable does:

• OPENAI_API_KEY — your Zukko key.
• OPENAI_PROXY_URL — overrides the OpenAI base URL. The default is https://api.openai.com/v1; we replace it with the Zukko address.
• OPENAI_MODEL_LIST — the list of models in the UI (syntax below).
• SYSTEM_AGENT — the model for LobeHub's system tasks (covered in its own section).

The OpenAI provider is enabled by default; you can disable it with ENABLED_OPENAI=0.

Why /v1 is required

The LobeHub docs have a specific warning for OPENAI_PROXY_URL: some proxies expect an address with /v1 and some without, and if you get an empty reply, try adding /v1. For Zukko the answer is fixed: the address is always https://api.zukko.pro/v1.

OPENAI_MODEL_LIST syntax

Per the LobeHub docs:

• +id adds a model, -id hides one; entries are comma-separated;
• -all hides all built-in models first, so only the ones you add with + remain;
• id=Name sets a display name;
• <number> after the name is the maximum context in tokens. You can add capabilities after colons, such as fc (function calling) or vision (images). Only add them if you're sure the model supports them.

-all matters here. Without it, the built-in OpenAI models stay in the list, Zukko doesn't serve them, and requests to them fail.

For current model IDs, call GET https://api.zukko.pro/v1/models (see the models documentation↗) or open the "Models" page in the dashboard.

A model for system tasks: SYSTEM_AGENT

Besides your messages, LobeHub sends requests on its own: it names topics, translates, compresses long history, generates agent descriptions, and, if autocomplete is enabled, suggests text as you type. If no model is set for these tasks, LobeHub may call a model that Zukko doesn't have, and the background features stop working.

The format is default=provider/model for all tasks at once, or task=provider/model for a specific one. Since Zukko is connected through the OpenAI provider, the provider here is openai. An example with a separate model for history compression:

SYSTEM_AGENT=default=openai/glm-5.3-flash,historyCompress=openai/claude-sonnet-5

History compression replaces part of the conversation, so you may want a model you trust more for your tasks. Topic names and autocomplete can safely go to the cheapest one.

How to apply changes

Environment variables are read when the container is created. docker restart lobehub won't reload them: remove the container and create it again with the same docker run command you used for installation. If you deployed LobeHub with Docker Compose, run docker compose up -d after editing the env file — Compose will recreate the container with the new values.

Check logs with docker logs -f lobehub (use your container's name).

Choosing a model by price

A monthly example: 30 messages a day for 30 days, so 900 messages. Each has 4,000 input tokens (question plus history) and 800 output tokens. That's 3,600,000 input and 720,000 output, 4,320,000 tokens in total:

• claude-sonnet-5: 4,320,000 × $0.3 / 1,000,000 = $1.296 a month;
• gpt-5.6-luna: 4,320,000 × $0.1 / 1,000,000 = $0.432;
• glm-5.3-flash: 4,320,000 × $0.04 / 1,000,000 = $0.1728.

For comparison, the same volume on claude-sonnet-5 at the vendor's official price ($2 and $10 per 1M input and output tokens): 3.6M × $2 + 0.72M × $10 = $7.2 + $7.2 = $14.4. A caveat: vendors may read resent context from the prompt cache at roughly 10% of the input price, while Zukko bills cached tokens at the regular input price. In long conversations with a large repeated history, the real difference is smaller than this straight calculation. More in the key limits and cache docs↗.

Choose the model for your main conversations based on your own tasks: connect two or three models, ask them the same 10–20 typical questions, and compare the answers and spending in the dashboard's "Usage" section.

Troubleshooting

Empty reply

A typical sign of an address without /v1, as the LobeHub docs state directly. Check that OPENAI_PROXY_URL or Proxy URL is https://api.zukko.pro/v1.

Built-in OpenAI models show up and requests to them fail

OPENAI_MODEL_LIST has no -all, so models that Zukko doesn't serve are visible. Put -all at the start of the list.

Topic names don't appear, translation doesn't work

System tasks call a model that Zukko doesn't have. Set SYSTEM_AGENT=default=openai/glm-5.3-flash or choose a system task model in the settings.

You changed the env file and nothing happened

The container wasn't recreated. docker restart doesn't reload variables — you need docker rm -f and a fresh docker run, or docker compose up -d.

400 on Claude models

claude-sonnet-5 and claude-opus-5-5 may reject a request with a 400 error if temperature is anything other than 1 or top_p is below 0.99. If you changed these parameters in the agent's model settings, restore the defaults for Claude.

401, 402, 403, 429

401 means the key was copied partially or deleted in the dashboard. 402 means the balance ran out. 403 model_not_allowed_for_key means the model isn't on the key's allowed list. 429 means too many requests; wait and retry.

FAQ

Do I have to self-host LobeHub?

No, if the provider settings in your version have a Proxy URL field — then method 1 is enough. Environment variables are for setting the key and model list centrally for all users of your server.

Can I connect Zukko as an Anthropic provider?

LobeHub has a separate Anthropic provider with its own proxy address, and Zukko accepts the Anthropic format too. But a single OpenAI provider is simpler: the gateway converts requests to Claude, and all models stay in one list. The difference between formats is explained in the format selection docs↗.

Is it safe to keep the key on the server?

The key from the env file is used by every user of your LobeHub, so don't expose the instance to the internet without authentication. Also set daily and monthly limits and an allowed-models list for the key in the dashboard.

Where do I get a key?

Create one in the Zukko dashboard↗. The full key is shown only once, so move it straight into the env file or the provider settings.