LobeChat brings several model providers into one interface, which is convenient to use but easy to mismanage: who created a key, which models it can call, whether it lives in the browser or a database, whether backups carry it away, and whether it still works after a team member leaves. This article follows the sequence of creation, configuration, storage, rotation, team policy, and troubleshooting to set out a workable practice.

Note: LobeChat and LobeHub are products and trademarks of their respective owners, and OpenAI is a trademark of OpenAI, Inc. This article is a technical guide only and implies no affiliation or partnership with those companies. Interfaces, variable names, and storage methods change between versions; follow the current official documentation. Models and prices are governed by the site's model pricing page.

1. Distinguish three kinds of keys first

"LobeChat API Key" often refers to three different things:

  • Account or platform credentials: used to sign in to LobeHub Cloud or an enterprise platform, with permissions set by the platform.
  • Model vendor keys: issued by OpenAI, Anthropic, Google, and others, entered under the matching provider.
  • Gateway keys: issued by an OpenAI-compatible gateway, where one key can call models from multiple vendors.

This article covers the third kind, and the advice also applies to other vendor keys you enter into LobeChat. A gateway key is not used for sign-in and cannot call a vendor's private interfaces. When configuring, choose the OpenAI-compatible entry point or a custom provider; do not paste the key into a vendor-specific field.

2. Create a key: define purpose and limits first

Do not create a key and then decide who should use it. Reversing the order saves trouble later:

  1. Open the ZSQH AI Gateway sign-up page, register, and sign in to the console.
  2. Go to the API keys page and create a new key.
  3. Name it with the user, environment, and purpose, for example lobe-team-prod, not test.
  4. Set a spending limit and an expiry date; where model scoping is supported, restrict which models the project can use.
  5. Confirm the account balance so you do not finish configuration only to find calls cannot be made.
  6. Copy the key into a password manager; do not send it to a group chat, document, or ticket first.

Once created, confirm that the key, address, and model work together from the command line:

export ZSQH_API_KEY="sk-your-key"

curl -sS "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"}]}'

A choices field in the response means the request chain works. A 401 points first to the key, a 404 to the /v1 path, and a model-not-found error to the model ID.

3. Server environment variables vs user-level configuration

LobeChat keys can sit at two layers with completely different effects:

Layer Configuration location Scope Suitable for
Server environment variables Deployment environment, lobehub.env, secret management Shared by the whole instance Team-wide entry point, default models
User-level provider settings Settings interface after sign-in A single account Personal bring-your-own-key, temporary trials
Gateway-side keys Gateway console Metered per key Quotas, auditing, revocation

The server-side OPENAI_API_KEY is a shared key: anyone who can use the instance can call with it. Users can also enter their own keys in settings. In server database mode, user keys are encrypted before being written to the database, and the encryption depends on KEY_VAULTS_SECRET. If that variable is lost, stored user keys may become undecryptable, so back it up at deployment time.

Common server variables include:

  • OPENAI_API_KEY: the shared gateway key.
  • OPENAI_PROXY_URL: overrides the default OpenAI address and points to a compatible gateway.
  • OPENAI_MODEL_LIST: controls the model list; it does not grant additional permissions.
  • KEY_VAULTS_SECRET: encrypts user keys and proxy addresses in the database.
  • AUTH_SECRET: relates to sessions and authentication, and should be generated separately.
  • DATABASE_URL: the PostgreSQL connection string, required in server mode.

Do not write the same key into both environment variables and user settings unless you know which layer takes effect. When troubleshooting, first confirm which key the request actually uses, then check the gateway logs.

4. Configuring multiple models and providers

The syntax for OPENAI_MODEL_LIST is: + adds, - hides, and model-id=display-name<capabilities> customizes the display name and capabilities, separated by ASCII commas. For example:

-all,+model-a=Daily chat<128000:fc:vision>,+model-b=Long-document analysis<200000:reasoning>

Inside the angle brackets, the first item is the maximum context length, followed by capability tags. Common tags include fc (function calling), vision, file, reasoning, and search (web search). Fill in tags according to the model's actual abilities. A wrong tag will not fail immediately, but it will cause failures in plugin or image tasks.

The principle for multiple providers is "one configuration per upstream endpoint":

  • Create only one provider entry per gateway and distinguish purposes through the model list.
  • Create separate entries for different gateways or environments, with the environment in the name.
  • Use an independent key for each entry so limits and revocation can be handled separately.
  • Do not duplicate the same key just to make the model list look fuller; billing will become confusing.

The model list only affects what the interface displays; real permissions live on the gateway side. To restrict which models a key may call, configure that in the console instead of relying on front-end hiding.

5. Where keys are stored and where they leak

By deployment method:

  • Local or browser mode: configuration is kept in browser local storage and may disappear after switching devices or clearing the cache. Do not save long-lived keys on a shared computer.
  • Server database mode: user keys are encrypted and written to PostgreSQL, with encryption dependent on KEY_VAULTS_SECRET. Database backups contain ciphertext, but the secret file itself must be stored separately.
  • Environment files: lobehub.env is plain text. Set permissions so only the service account can read it, keep it out of Git, and do not distribute it with images.
  • S3 and backups: S3 stores files and knowledge-base material and usually contains no keys; database backups and deployment configuration may indirectly contain sensitive information.

Also watch screenshots, tickets, and chat logs. Many leaks do not come from a breached database but from a key pasted in the wrong place.

6. Rotation and revocation

Rotate every 90 days, or immediately after a team member leaves, a device is lost, or exposure is suspected. The order is "create the new key, switch over, then disable the old one":

  1. Create a new key with the same permissions, adding a date suffix to the name.
  2. Update lobehub.env or user-level provider settings, checking each entry.
  3. Restart or recreate the service and send a test request.
  4. Confirm in the gateway logs that the new key has calls and the old key has no new traffic.
  5. Watch error rates and usage for a period to confirm no script or device was missed.
  6. Disable the old key and keep its records for a while before deleting it.

Do not delete the old key before configuring the new one; that creates a window in which calls fail. If exposure is suspected, disable first to stop the damage, then investigate abnormal usage and request sources.

7. Team policy: one key per person, separate environments

  • One key per person and one key per purpose; create separate keys for automated tasks.
  • Use independent keys for development, testing, and production so test traffic does not pollute production billing.
  • Set spending limits, expiry dates, and model scope wherever possible, and at minimum the first two.
  • Use a shared server key only for the default entry point, with a conservative limit so anomalies are easy to spot.
  • Keep a register listing only key name, holder, purpose, creation date, and expiry; never the full key.
  • Each month, review keys unused for a long time, keys over budget, and abnormal authentication failures.
  • Build key creation, handover, and disabling into onboarding and offboarding processes.
  • Define which data may enter cloud models, and assess sensitive projects before use.
  • Review the model pricing page periodically, since prices and available models change.

Even a small team should keep a record of who requested a key, who uses it, and when it expires. When something goes wrong, you can locate it quickly.

8. Troubleshooting

Symptom Common cause Action
401 Authentication error Wrong key, disabled key, or trailing space Copy again and confirm the key belongs to this gateway
403 Forbidden Quota exhausted, insufficient permission, or model scope restricted Check quota and model permissions in the console
404 Not Found Incorrect API address path Keep only the /v1 portion
429 Too Many Requests Rate limiting or hitting the quota ceiling Check usage and concurrency settings
model not found Wrong model ID or model not enabled Copy the exact identifier from the pricing page
User keys suddenly fail KEY_VAULTS_SECRET changed or missing Restore the original secret and re-enter user keys
curl works but the interface fails Settings not saved, browser cache, or network proxy Save again and check the proxy

When troubleshooting, first separate "the application did not read the configuration" from "the gateway rejected the request": inspect environment variables, the database, and logs for the former, and HTTP status codes for the latter.

FAQ

Is the LobeChat API key stored in the browser or on the server?

It depends on the deployment. Browser or local mode stores it in local storage. In server database mode, user keys are encrypted and written to PostgreSQL, while a shared key in server environment variables exists in plain text in the deployment environment.

If OPENAI_API_KEY is configured on the server, do users still need to enter a key?

No. The server key is shared, and users within the instance can call directly. Users may also enter their own key for independent quotas or a different provider; which takes precedence depends on the current version.

Can one key call multiple models?

Usually yes, as long as the gateway allows that key to call those models. The model list only controls display; actual permissions and quotas are set in the gateway console.

What happens if I change KEY_VAULTS_SECRET?

Encrypted user keys and proxy addresses may become undecryptable, which appears as user keys suddenly failing. Back up before any change and consult the migration notes for the current version; do not change it casually.

What should I do first after a key leaks?

Disable or delete the key first to stop the damage, then investigate abnormal usage, request sources, and time periods. Afterwards, check environment files, database backups, repositories, chat logs, and screenshots, and rotate other credentials in the same environment if necessary.

Summary

Configuring keys in LobeChat is not complicated; long-term management is the hard part: traceable names, capped quotas, protected storage, bounded backups, and the ability to stop damage after a leak. You can sign up for the ZSQH AI Gateway and create a client-specific key, then tighten the policy as the team grows and review costs periodically against model pricing.

Related reading: