LobeChat Custom API: OpenAI-Compatible Setup and Deployment (2026)

LobeChat is an open-source AI chat application that supports multiple models, assistants, plugins, and knowledge bases. You can deploy it to the cloud with one click or run it on your own server. There are two ways to connect a custom API: enter the provider information in the interface, or hard-code it at deployment time with environment variables. The former suits a personal computer; the latter suits teams and long-running deployments.

This article uses common versions as of October 2026 and covers parameter preparation, Docker deployment, environment variables, UI configuration, and troubleshooting.

Note: LobeChat and LobeHub are products of their respective owners, and OpenAI is a trademark of its respective owner. This article is a technical integration guide only. Environment variable names and interface entry points may change between versions; refer to the current official documentation. For models and pricing, refer to the site's model pricing.

1. Choosing among three connection methods

Method	Suitable scenario	Configuration location	Advantage
UI configuration	Personal use, quick trial	AI provider settings	Takes effect immediately, no restart
Docker environment variables	Self-hosted server, team sharing	`docker run` or Compose	Versionable and reproducible
Cloud platform environment variables	Managed platforms such as Vercel	Project environment variables	No operations overhead; good for small teams

For a personal computer, get the UI configuration working first, then migrate to Docker. For team deployments, use environment variables from the start and keep the key and address in a secrets manager rather than writing them into a code repository.

2. Prepare three parameters

API key: create one in the ZSQH AI Gateway, named after the project or environment.
Base URL: https://ai.zhongshangqihang.com/v1, the OpenAI-compatible endpoint.
Model ID: copy it from the model pricing page; use the API identifier, not the display name.

Verify with curl first so a gateway problem is not mistaken for a LobeChat configuration problem:

export ZSQH_API_KEY="sk-your-key"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [{"role": "user", "content": "Reply with OK only"}]
  }'

If the response contains choices, all three parameters are valid and you can move on to deployment.

3. Docker deployment

The simplest approach is to start a container from the official image and pass the key, proxy address, and model list through environment variables:

docker run -d --name lobechat \
  -p 3210:3210 \
  -e OPENAI_API_KEY="sk-your-key" \
  -e OPENAI_PROXY_URL="https://ai.zhongshangqihang.com/v1" \
  -e CUSTOM_MODELS="-all,+your-model-id" \
  lobehub/lobe-chat

After startup, visit http://server-address:3210. What the parameters mean:

OPENAI_API_KEY: the gateway key. Inject it through environment variables or a secrets manager; do not put it in a public Compose file.
OPENAI_PROXY_URL: overrides the default OpenAI address and points to your compatible gateway.
CUSTOM_MODELS: controls the model list. -all clears the default list first, and +model-id adds one model.

If you use Docker Compose, put the same variables in the environment section. After changing variables, recreate the container; a simple restart may not load the new environment.

4. Environment variables and the model list

Variable	Required	Example	Notes
`OPENAI_API_KEY`	Yes	`sk-...`	Key created in the gateway
`OPENAI_PROXY_URL`	Yes	`https://ai.zhongshangqihang.com/v1`	Overrides the default Base URL
`CUSTOM_MODELS`	Recommended	`-all,+model-a,+model-b`	Controls visible models
`OPENAI_MODEL_LIST`	Version-dependent	`+model-a`	Older versions may use this name

Key points of CUSTOM_MODELS syntax:

+model-id adds a model, and -model-id hides one.
-all clears the default list first, avoiding a pile of models that cannot be called.
Separate entries with commas and do not add spaces.
You can rename with model-id=display-name, but do not change the model ID itself.

Different versions support variable names and syntax somewhat differently; older versions may use OPENAI_MODEL_LIST. If the model list disappears after an upgrade, check the documentation for your current version instead of forcing an old tutorial onto it.

5. Configuring in the interface

If you do not want to change environment variables, you can configure everything in the interface. Using a common current version as an example:

Open LobeChat and go to settings.
Find "AI Service Provider" or "Language Model."
Select OpenAI and enter the API key and proxy address.
Add the custom model ID in the model list.
Save, start a new conversation, and select the model to test.

UI configuration is suitable for local use. After deploying to a server, settings saved in the browser belong to the current user and may need to be reconfigured after switching devices or clearing the cache; teams should prefer environment variables.

6. Verification and reverse proxy

After the container starts, check the logs first to confirm there are no environment variable errors:

docker logs -f lobechat

Then send a message in the interface to test. If you deploy on the public internet, put Nginx or Caddy in front and do at least three things:

Configure HTTPS; do not send keys over plain HTTP.
Set access controls so the application is not exposed directly to everyone.
Configure timeouts and buffering; streaming responses require proxy buffering to be disabled.

When Nginx handles streaming responses, a common configuration is to turn off proxy_buffering and extend the read timeout appropriately. Otherwise, answers may appear all at once or stall midway.

7. Production deployment checklist

Inject the key through a secrets manager or environment variables; never bake it into the image.
Issue a dedicated key for LobeChat so you can set limits and revoke it easily.
Configure a database; otherwise conversations and settings may exist only locally.
Enable HTTPS and access control; do not expose a public deployment unprotected.
Set gateway budgets and concurrency caps to prevent abnormal loops from consuming quota.
Back up the database and uploaded files regularly.
Read the changelog before upgrading, and pin image version tags instead of staying on latest long term.

8. Common errors and fixes

Symptom	Common cause	Fix
No models after startup	`CUSTOM_MODELS` did not take effect	Check the variable name, commas, and whether the container was recreated
`401 Unauthorized`	Key not injected or no longer valid	Check environment variables inside the container and recreate the key
`404 Not Found`	Wrong proxy address path	Check `/v1` and add or remove the ending if needed
`model not found`	Model ID does not match the pricing page	Copy the exact identifier
Answer stalls midway	Reverse proxy buffering or timeout	Disable buffering and extend the read timeout
File upload fails	Storage or model capability not configured	Check storage configuration and model capabilities
Knowledge base unavailable	Embedding model not configured	Configure a working embedding model separately

When troubleshooting, first determine whether the application is not reading the configuration or the gateway is rejecting the request. For the former, check container environment variables and logs; for the latter, check the HTTP status code. The two require completely different fixes.

FAQ

Is LobeChat free?

LobeChat is an open-source project that you can deploy yourself; model usage fees are charged by the API provider you connect. Prices for hosted services and premium features follow the official offering.

Do I have to use Docker?

Not necessarily. You can also run it with Node.js or deploy it to a cloud platform that supports Next.js. Docker's advantages are consistent environments and easy migration, which is why it is more common for team deployments.

What is the difference between `OPENAI_PROXY_URL` and the proxy address in the interface?

Environment variables take effect at the deployment layer and suit unified team configuration; UI settings belong to the current user and may need to be reconfigured after switching devices. When both exist, the current version's precedence rules apply.

Why does the model list contain models that do not work?

Most likely you did not use -all to clear the default list, or the CUSTOM_MODELS syntax is wrong. Keep only one confirmed model at first, then add more after it works.

Can I connect Claude or Gemini?

Yes, provided the gateway offers those models in an OpenAI-compatible format and the model ID is correct. Capabilities that differ from the native protocol, such as certain tool calls or image parameters, need to be tested in practice; refer to the site documentation.

Next steps

Connecting LobeChat can be split into two steps: first use curl to confirm the gateway works, then align the Base URL, key, and model through environment variables or the interface. Team deployments should prefer environment variables; personal trials should prefer the interface. If you need a unified model endpoint and usage management, sign up for the ZSQH AI Gateway; models and pricing follow the model pricing page.