> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LobeHub

> LobeHub Open-source AI Chat Client Integration Guide with custom providers and local knowledge base

> Open-source AI chat client integration guide with custom providers and local knowledge base

## 1. Overview

LobeHub is an open-source, cross-platform AI chat client (formerly Lobe Chat) supporting multiple models, multimodal interactions, a plugin system, and local knowledge bases. With GravitexAI, you can access 100+ mainstream AI models using a single API key in LobeHub, without needing to register and pay for each provider separately.

<CardGroup cols={3}>
  <Card title="Open-source & self-hostable" icon="github">
    Desktop, web, Docker, and Vercel deployments — full data control
  </Card>

  <Card title="Plugins & multimodal" icon="plug">
    Built-in web search, code interpreter, image understanding, video generation plugins
  </Card>

  <Card title="Local knowledge base" icon="database">
    Upload PDF / Markdown for RAG — reference private documents in conversations
  </Card>
</CardGroup>

## 2. Quick start

### Step 1: Get a GravitexAI API Key

1. Visit the [GravitexAI Console](https://maas.gravitex.ai/#/api-keys)
2. Click **Create API Key**, name it, and save
3. Copy the key starting with `sk-` for later

### Step 2: Install LobeHub

LobeHub offers three ways to use it:

<Tabs>
  <Tab title="Desktop">
    **Option A: Download from the official site**

    1. Visit [https://app.lobehub.com/downloads](https://app.lobehub.com/downloads) to download the installer

    **Option B: Download from GitHub Releases**

    1. Open [https://github.com/lobehub/lobe-chat/releases](https://github.com/lobehub/lobe-chat/releases)
    2. Find the latest version and download the installer for your system:

    * Windows: .exe
    * macOS: .dmg
    * Linux: .AppImage / .deb / .rpm
  </Tab>

  <Tab title="Web (official)">
    Visit `lobechat.com` directly, sign up and log in — no self-deployment needed
  </Tab>

  <Tab title="Self-hosted">
    Deploy via Docker / Vercel / local source code — suitable for enterprise or privacy scenarios
  </Tab>
</Tabs>

<Tip>
  Individual users are recommended to use the official web or desktop version first. If you have data privacy or compliance requirements, Docker self-hosting is recommended (configure GravitexAI via environment variables).
</Tip>

### Step 3: Open LobeHub settings

1. Click **Personal Avatar → App Settings** in the top-left to enter the settings page
2. Select **Agent → AI Provider** from the left navigation
3. Click the `+` button in the top-right to add a custom provider

<img src="https://mintcdn.com/gravitexai/1w6qMcPexYzhP5k_/images/lobehub1.png?fit=max&auto=format&n=1w6qMcPexYzhP5k_&q=85&s=622e758b529c3d167d50246a78e6838f" alt="Open LobeHub settings and add a custom provider" width="2400" height="1692" data-path="images/lobehub1.png" />

### Step 4: Create a custom AI provider

| Field                    | Value                        | Notes                                                                     |
| ------------------------ | ---------------------------- | ------------------------------------------------------------------------- |
| **Provider ID**          | `gravitexai`                 | Unique provider identifier, cannot be changed after creation              |
| **Provider Name**        | `gravitexai`                 | Custom provider name                                                      |
| **Provider Description** | `gravitexai`                 | Custom description                                                        |
| **Provider Logo**        | (leave blank)                | Optional, custom logo URL                                                 |
| **Request Format**       | `OpenAI`                     | GravitexAI is fully compatible with the OpenAI protocol                   |
| **Proxy URL**            | `https://api.gravitex.ai/v1` | Base URL, **must end with `/v1`**                                         |
| **API Key**              | Your GravitexAI API Key      | Get it from the [GravitexAI Console](https://maas.gravitex.ai/#/api-keys) |

Click the **Create** button in the bottom-right corner to save.

<img src="https://mintcdn.com/gravitexai/1w6qMcPexYzhP5k_/images/lobehub2.png?fit=max&auto=format&n=1w6qMcPexYzhP5k_&q=85&s=b426609b24b782760a15da26dbd72c28" alt="Create a custom AI provider" width="2400" height="1692" data-path="images/lobehub2.png" />

<Tip>
  **Configuration notes**

  * The **Proxy URL** must end with `/v1`, otherwise request routing will fail
  * When pasting the **API Key**, remove any leading or trailing spaces
  * Selecting `OpenAI` as the **Request Format** gives access to all 100+ GravitexAI models
  * One key can enable multiple models simultaneously, billed by usage — no separate payment per model needed
</Tip>

### Step 5. Verify connectivity

After successful creation, you'll be redirected to the provider details page. You can:

1. **Fill in API Key and Proxy URL**: Confirm or modify the settings again
2. **Enable advanced options** (optional):
   * **Use Responses API spec**: Enable to use the new OpenAI request format (only supported by OpenAI models)
   * **Use client request mode**: Browser sends requests directly, which can improve response speed
3. **Connectivity check**: Select a model from the dropdown and click the **Check** button to test connectivity
4. **Get model list**: Click the **Get Model List** button to automatically fetch all models provided by GravitexAI

Once retrieved successfully, the **Model List** will display all models currently available from GravitexAI, grouped by type: chat, image, video, embeddings, TTS.

<img src="https://mintcdn.com/gravitexai/1w6qMcPexYzhP5k_/images/lobehub3.png?fit=max&auto=format&n=1w6qMcPexYzhP5k_&q=85&s=4db45efc3f29c87016ac4e7c7bdc9a90" alt="Verify connectivity and get model list" width="2400" height="1692" data-path="images/lobehub3.png" />

<Warning>
  If the **Connectivity Check** fails, troubleshoot in this order:

  * Check if the proxy URL ends with `/v1`
  * Verify the API Key is valid (can be verified in the GravitexAI Console)
  * Check if a firewall / proxy is blocking HTTPS
</Warning>

### Step 6. Select a model and start chatting

From the model dropdown in the chat interface, select the model you want to use (e.g., `claude-opus-5`, `gpt-5.6-luna`, `deepseek-v4-pro`) and start chatting.

<Card title="View popular model recommendations" icon="star" href="https://maas.gravitex.ai/#/api-models">
  View the latest model recommendations, performance comparisons, and scenario-based usage suggestions covering text creation, coding, quick responses, image generation, video generation, and more.
</Card>

<Info>
  **Why are specific models not listed here?**

  AI models iterate very quickly. To ensure you get the most accurate model recommendation information, we maintain the latest model list, performance data, and usage suggestions on the [Model Recommendations page](https://maas.gravitex.ai/#/api-models).
</Info>

## 3. One-stop access to 100+ models

LobeHub has built-in official channels for multiple providers, requiring individual API keys. By connecting to GravitexAI, you only need to create **one** custom provider to cover all models:

| Channel                            | Applicable Models                                               | Core Advantage                                 | API URL                      |
| ---------------------------------- | --------------------------------------------------------------- | ---------------------------------------------- | ---------------------------- |
| **OpenAI-compatible (GravitexAI)** | All 100+ models (including Claude, Gemini, GPT, DeepSeek, etc.) | One key for all models, simplest configuration | `https://api.gravitex.ai/v1` |

<Tip>
  **One GravitexAI channel accesses all models including Claude / Gemini / GPT / DeepSeek**

  GravitexAI wraps mainstream models like Claude, Gemini, GPT, and DeepSeek into a unified OpenAI-compatible protocol. By creating one `GravitexAI` custom provider in LobeHub, you can select all 100+ models from the model dropdown without configuring separate channels for different providers.
</Tip>

## 4. LobeHub features

### Plugin system

LobeHub provides a rich plugin marketplace (Settings → Plugins). Recommended plugins to enable:

* **Web Search**: Let the model access the internet in real time
* **Code Interpreter**: Run Python code and create data visualizations in conversations
* **Chart Generation**: Automatically generate flowcharts and mind maps
* **Image Generation**: Generate images through models like `gpt-image-2`, `gemini-3-pro-image`

### Local knowledge base (RAG)

LobeHub supports uploading files to build a local vector database:

1. Go to the **Knowledge Base** page and create a new knowledge base
2. Upload PDF, Markdown, Word, Excel, TXT, and other files
3. The system automatically slices and vectorizes the content
4. When chatting, enable the knowledge base and the model will answer based on your private materials

<Warning>
  The **Vectorization** step of the knowledge base calls the Embedding model (billed). We recommend using GravitexAI's `text-embedding-3-large` and other embedding models.
</Warning>

### Multimodal conversation

Support uploading images for visual understanding, image recognition, and OCR:

* Recommended vision models: `gemini-3.6-flash`, `claude-opus-5`, `gpt-5.6-terra`
* Drag images directly into the chat box and the model will automatically recognize them

### Agent Market

LobeHub includes rich preset agents (translation, writing, coding, interviews, etc.). You can also:

* Enable community-shared agents with one click in the **Agent Market**
* Create custom agents: define personas, prompts, opening messages, knowledge bases, and plugins

### Chat management and export

* Multi-branch conversations, message editing, and regeneration
* Chat export: Markdown, PNG, JSON
* Global search of chat history

## 5. Advanced configuration

### Network proxy and self-hosting

If you need to use a proxy or self-host LobeHub:

1. **Desktop**: Settings → Network → Configure HTTP/HTTPS proxy
2. **Self-hosted (Docker)**: Inject GravitexAI configuration via environment variables:
   ```bash theme={null}
   OPENAI_API_KEY=sk-your-gravitex-key
   OPENAI_PROXY_URL=https://api.gravitex.ai/v1
   CUSTOM_MODELS=gpt-5.6-terra,claude-opus-5,deepseek-v4-pro
   ```
3. **Client request mode**: When enabled, the browser connects directly to the API (ensure the browser can access GravitexAI)

### Keyboard shortcuts

| Shortcut               | Function         |
| ---------------------- | ---------------- |
| `Ctrl/Cmd + N`         | New conversation |
| `Ctrl/Cmd + K`         | Quick search     |
| `Ctrl/Cmd + /`         | Command palette  |
| `Ctrl/Cmd + Shift + M` | Switch model     |

## 6. Mobile

LobeHub desktop supports Windows / macOS / Linux. For mobile, access the `lobechat.com` web version via browser (responsive design) — no separate app installation required.

## 7. Troubleshooting

<AccordionGroup>
  <Accordion title="Connection failed / connectivity check fails">
    | Phenomenon        | Troubleshooting                                                                                                          |
    | ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
    | 401 / 403 prompt  | API Key is invalid or balance is insufficient. Go to [GravitexAI Console](https://maas.gravitex.ai/#/api-keys) to verify |
    | 404 prompt        | Proxy URL doesn't end with `/v1`, missing `/v1` suffix                                                                   |
    | Timeout prompt    | Network issue, check proxy or firewall settings                                                                          |
    | CORS error prompt | Disable **Use Client Request Mode**, or route through server                                                             |
  </Accordion>

  <Accordion title="Model list is empty">
    * Click the **Get Model List** button to manually fetch
    * Wait 1-2 seconds and refresh the page
    * Confirm the API Key status is normal in the GravitexAI Console
  </Accordion>

  <Accordion title="Slow responses or stream disconnection">
    * Switch to a faster model (e.g., `gemini-3.6-flash`, `claude-haiku-4-5`, `deepseek-v4-flash`)
    * Disable unnecessary plugins
    * Check network latency
    * Reduce context length (close long old conversations)
  </Accordion>

  <Accordion title="Does data sync between web and desktop versions?">
    When logged in with the same LobeHub account, some configurations and sessions can sync. We recommend regularly exporting local data for backup.
  </Accordion>

  <Accordion title="What is the relationship between LobeChat and LobeHub?">
    LobeChat is the open-source project name, and LobeHub is the product / cloud platform name. Both share the same underlying code. Desktop and self-hosted versions are typically built based on the LobeChat repository.
  </Accordion>

  <Accordion title="Why can't I call models after self-hosting?">
    Check if the API Key is correct, if the Base URL is reachable, if server outbound access is restricted, and if DNS resolution is normal within the container.
  </Accordion>
</AccordionGroup>

## 8. Best practices

### Model selection strategy

Use different models for different tasks, select by complexity tier:

* **Daily chat / simple Q\&A**: `gemini-3.1-flash-lite`, `claude-haiku-4-5`, `deepseek-v4-flash`
* **Complex reasoning / long document analysis**: `claude-opus-5`, `gpt-5.6-sol`, `deepseek-v4-pro`
* **Coding**: `claude-opus-5`, `gpt-5.6-sol`, `claude-sonnet-5`
* **Image understanding**: `gemini-3.6-flash`, `claude-opus-5`, `gpt-5.6-terra`
* **Image generation**: `gpt-image-2`, `gemini-3-pro-image`

For the complete model list and performance comparison, please refer to the [Model Recommendations page](https://maas.gravitex.ai/#/api-models).

### Context management

* Regularly clean up unused old conversations
* Break complex tasks into multiple short conversations
* Use the **Fork Conversation** feature to explore different answers

### Security and privacy

* Do not share API Keys in public
* Rotate keys regularly
* For sensitive conversations, consider self-hosting LobeHub with fully local data storage

### Self-hosting recommendations

* Use Docker + PostgreSQL in production — do not use the built-in database
* Consider Cloudflare as a reverse proxy
* Manage keys centrally through environment variables for multi-instance deployment

## 9. Comparison of three approaches

| Dimension                | Desktop                       | Web (official)                  | Self-hosted                                |
| ------------------------ | ----------------------------- | ------------------------------- | ------------------------------------------ |
| Installation difficulty  | Low (download installer)      | Very low (open webpage)         | Medium to high (requires deployment)       |
| Data ownership           | Local primary                 | Official cloud                  | Fully autonomous                           |
| Network requirements     | Model API access only         | Needs official site + model API | Depends on deployment location             |
| Multi-user collaboration | Weak                          | Medium                          | Strong (with account permissions)          |
| Target users             | Individual productivity users | Casual / lightweight users      | Enterprise, teams, privacy-sensitive users |
| Cost                     | Free (bring your own API Key) | Free tier + paid plans          | Server cost + bring your own API Key       |

<Info>
  **More help**: Contact [bd@gravitex.ai](mailto:bd@gravitex.ai) or call 13603055233 for technical support.
</Info>