How to Set Up HeFu as a Custom Provider in LobeChat: A Step-by-Step Guide

Adding HeFu as a custom provider in LobeChat typically takes about five minutes and gives you one API key to route the model IDs in HeFu's catalog (including GPT-5.6, Claude Opus 5, DeepSeek-V4-Pro, Kimi K3, Gemini 3.6 Flash, and Qwen3.7-Max) through LobeChat's native interface—eliminating multiple provider subscriptions, separate plugins, or per-model configuration. LobeChat has supported custom OpenAI-compatible providers since January 22, 2025 (LobeHub changelog); as of August 2026, the custom provider settings are the same in cloud and self-hosted builds, with the official LobeChat docs as the authoritative reference for version-specific changes.

Why Use HeFu with LobeChat?

The core value is unification. Rather than maintaining separate keys for OpenAI, Anthropic, DeepSeek, and others, HeFu exposes a single OpenAI-compatible base URL that fronts a catalog spanning GPT-5.6 (Terra / Sol / Luna), Claude Opus 5 / Fable 5, DeepSeek-V4-Pro / V4-Flash, Kimi K2.5 / K2.6 / K3, Gemini 3.6 Flash / 3.5 series, Qwen3.7-Max, GLM-5.x, and more. If you want to understand the routing architecture behind this, read our guide on running DeepSeek, Qwen, and Kimi with a single API key.

For teams focused on Chinese-language workloads, HeFu's catalog overlaps significantly with mainstream aggregators—our OpenRouter alternatives for Chinese models compares the trade-offs. HeFu states it operates Hong Kong direct-connect nodes for models such as GPT-5.6, so no overseas credit card is required; check the HeFu official site for current node coverage and network availability.

LobeChat's ecosystem has also matured. As of May 2026, LobeHub—the successor project—has surpassed 77,000 GitHub stars and migrated from lobehub/lobe-chat to lobehub/lobehub, repositioning itself from an "open-source ChatGPT client" to an "agent collaboration platform" (AIHubMix, updated 2026-05-13). That growth means more contributors maintaining provider integrations, but custom providers remain the most flexible path for non-listed endpoints like HeFu.

Prerequisites: What You Need Before Starting

Prepare three things:

1. A HeFu account with an active API key, issued immediately after signup in the HeFu dashboard.
2. A running LobeChat instance—cloud at LobeHub, or self-hosted via Docker, Vercel, or desktop; the official deployment docs cover each option. The custom provider settings are identical in both.
3. The exact model IDs you plan to use, copied from the HeFu docs (e.g., gpt-5.6-terra, claude-opus-5, deepseek-v4-pro). Mismatched IDs are the most common cause of "model not found" errors.

Understanding LobeChat's Custom Provider Configuration

On January 22, 2025, LobeChat refactored its AI provider management system, adding first-class support for arbitrary OpenAI-compatible API endpoints as custom providers (LobeHub changelog, 2025-01-22). This replaced the earlier workaround of overriding OPENAI_PROXY_URL at the environment level—a variable that only accepts a single proxy URL with comma-separated API keys and a choice of random or round-robin selection (LobeHub environment variables reference).

As of August 2026, the custom provider UI lives under Settings → Language Model → Custom Provider, with per-provider toggles for function calling, vision, and file uploads. Community members have filed GitHub issue #12288 requesting dedicated CUSTOM_PROVIDER_* environment variables for batch configuration; as of May 2026, the UI path described here remains the standard approach.

Step 1: Obtain Your HeFu API Endpoint and Key

Log in to the HeFu dashboard and open the API Keys section. You'll find:

• Base URL: https://api.hefu.hk/v1
• Secret API key: a string beginning with sk-hefu-...

Note the distinction between the request endpoint and the model list endpoint. LobeChat sends chat completions to the base URL; tools may also call GET /v1/models on the same host for discovery. You only need the base URL for LobeChat—there is no separate model-list URL to enter.

Step 2: Add HeFu as a Custom Provider in LobeChat

In LobeChat (cloud or self-hosted):

1. Open Settings → Language Model.
2. Click Add Custom Provider.
3. Fill in the required fields:
   • Display name: HeFu
   • Base URL: https://api.hefu.hk/v1
   • API key: your HeFu secret key
   • HTTP proxy (optional): configure only if your network needs a proxy to reach api.hefu.hk. Mainland China users typically do not need this thanks to HeFu's Hong Kong nodes, per HeFu's official network documentation.
4. Save the provider.

Next, add models. In the provider's model list, enter each ID exactly as documented by HeFu, and enable capability toggles: function calling for tool-using models, vision for multimodal models, and file upload if you plan to attach documents. If you prefer a single-key catalog with pre-configured models, note that first-class providers such as ModelsLab (integrated via PR #12560 in March 2026) expose 200+ models—but for HeFu, manual entry is the standard workflow and gives you precise control over which models appear.

Configuring Model IDs and Capabilities

These HeFu model IDs are examples from the vendor's catalog; verify against the current HeFu docs before entering them in LobeChat:

Use case	Recommended HeFu model IDs
General-purpose / agentic work	gpt-5.6-terra, gpt-5.6-sol, claude-opus-5, kimi-k3
Coding	gpt-5.3-codex, qwen3-coder, claude-opus-5
Long-context Chinese text	kimi-k3, kimi-k2.6, deepseek-v4-pro
Multimodal (image / audio / video)	gemini-3.6-flash, qwen3.7-max, glm-5.x
Budget-focused inference	deepseek-v4-flash, gemini-3.5-flash

Capability toggles apply per provider, not per model; enabling vision on a non-vision model can cause silent request failures, so toggle conservatively.

Testing the Connection and Troubleshooting

After adding models, start a new conversation, pick a HeFu model, and send a test message. If it fails, check for these common cases:

• 401 Unauthorized: the key is wrong, expired, or has a copied whitespace character. Regenerate it in the HeFu dashboard.
• 404 Not Found: the base URL is malformed—make sure it ends with /v1, not /chat/completions.
• Model not found: the ID does not match HeFu's catalog; re-check the docs for typos or deprecated names.

If you previously set OPENAI_PROXY_URL in a self-hosted Docker deployment, note that it can override UI-configured endpoints in certain versions. Remove or unset it and restart the container.

Comparison: HeFu Custom Provider vs. Direct Provider API

Dimension	HeFu as custom provider	Direct per-provider API keys
Setup time	~5 minutes, one provider entry	Hours: separate keys, URLs, and configs per provider
Key management	One HeFu key for all models	One key per provider (OpenAI, Anthropic, DeepSeek, etc.)
Model flexibility	Switch across GPT, Claude, Kimi, Gemini, Qwen from the model picker	Only models within the configured provider
Capability toggles	Manual: enable vision / function calling per provider	Auto-detected for first-class providers
Cost structure	Single usage bill from HeFu	Separate bills; self-hosted LobeChat itself is free

HeFu's per-token rates are subject to adjustment; refer to the official HeFu pricing page for current numbers. For cost context: LobeHub cloud offers 450,000 free compute credits at signup and paid tiers (Starter / Premium / Ultimate), while self-hosted and desktop LobeChat are free and only inference costs apply (AIHubMix, updated 2026-05-13; see also LobeHub official pricing). For budget planning, see our pay-as-you-go DeepSeek cost guide.

Security and Best Practices

• Store the API key in an environment variable (e.g., HEFU_API_KEY in Docker -e) for self-hosted deployments, not in shared config files; see the LobeHub environment variables reference.
• Rotate keys regularly from the HeFu dashboard—especially if a key was ever pasted into a public workspace or committed to Git.
• Treat the key like a password: do not share screenshots that show both the key and your account name.
• Review capability toggles before sharing a provider config with teammates, so unused vision or file-upload features are not left enabled.

FAQ

Does HeFu support all LobeChat model features?

HeFu's API is OpenAI-compatible, so it supports LobeChat's standard chat-completion flow. Feature support ultimately depends on the upstream model—function calling works on models with native tool support (GPT-5.6, Claude Opus 5, DeepSeek-V4-Pro), while vision requires a multimodal model such as Gemini 3.6 Flash or Qwen3.7-Max. Toggle the matching capabilities in LobeChat's provider settings per the HeFu docs.

Can I use HeFu with a self-hosted LobeChat instance?

Yes. As of August 2026, the custom provider fields are identical in self-hosted and cloud LobeChat (check the official docs for version-specific behavior). In Docker, configure HeFu through the UI after starting the container, or pre-seed environment variables with your deployment tooling. The same base URL and key work in both cases.

How do I update the model list after HeFu adds new models?

Open your HeFu provider in Settings → Language Model and edit the model list to add new IDs. The API key persists while you edit, so there is no need to re-enter it. For a zero-maintenance alternative, first-class integrated providers such as ModelsLab (200+ models via one key since March 2026, per PR #12560) auto-expose their catalogs—but with HeFu, manual ID entry is the intended workflow and keeps your model picker focused on what you actually use.

Will my usage data be logged by HeFu when used through LobeChat?

Yes, standard API usage logging applies. HeFu records request metadata (timestamps, model, token count) for billing and abuse prevention, consistent with industry practice. Review the privacy and compliance page on the HeFu official site for the full policy. Since HeFu routes to upstream model providers, those providers' own data policies also apply; check each model's terms if you have specific retention requirements.