> ## 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 开源 AI 对话客户端集成指南，支持自定义服务商与本地知识库

> 开源 AI 对话客户端集成指南，支持自定义服务商与本地知识库

## 一、产品简介

LobeHub 是一款开源、跨平台的 AI 对话客户端（原 Lobe Chat），支持多模型、多模态、插件系统与本地知识库。通过 GravitexAI ，您可以在 LobeHub 中使用一个 API 密钥访问 100+ 主流 AI 模型，无需为每个厂商单独注册和付费。

<CardGroup cols={3}>
  <Card title="开源可自托管" icon="github">
    桌面端、网页端、Docker、Vercel 均可部署，数据完全可控
  </Card>

  <Card title="插件与多模态" icon="plug">
    内置联网搜索、代码解释器、图像理解、视频生成等插件
  </Card>

  <Card title="本地知识库" icon="database">
    支持上传 PDF / Markdown 建立 RAG，对话引用私有资料
  </Card>
</CardGroup>

## 二、快速开始

### 1. 获取 GravitexAI API Key

1. 访问 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys)
2. 点击「新建API 密钥」，命名并保存
3. 复制以 `sk-` 开头的密钥备用

### 2. 安装 LobeHub

LobeHub 提供三种使用方式：

<Tabs>
  <Tab title="桌面版">
    **方式一：官方站点下载**

    1. 访问 [https://app.lobehub.com/downloads](https://app.lobehub.com/downloads) 下载安装包

    **方式二：GitHub Releases 下载**

    1. 打开 [https://github.com/lobehub/lobe-chat/releases](https://github.com/lobehub/lobe-chat/releases)
    2. 找到最新版本，下载对应系统的安装包：

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

  <Tab title="网页版（官方）">
    直接访问 `lobechat.com` 注册登录即可使用，无需自部署
  </Tab>

  <Tab title="自托管">
    通过 Docker / Vercel / 本地源码部署，适合企业或隐私场景
  </Tab>
</Tabs>

<Tip>
  个人用户推荐直接使用官方网页版或桌面版；如有数据隐私或合规需求，建议 Docker 自托管（环境变量中配置 GravitexAI 即可）。
</Tip>

### 3. 打开 ChatHub 设置

1. 在左上角点击「个人头像→选择应用设置」，进入设置页面
2. 左侧导航栏选择「智能体→AI服务商」
3. 点击右上角 `+` 添加自定义服务商

<img src="https://mintcdn.com/gravitexai/1w6qMcPexYzhP5k_/images/lobehub1.png?fit=max&auto=format&n=1w6qMcPexYzhP5k_&q=85&s=622e758b529c3d167d50246a78e6838f" alt="打开 LobeHub 设置并添加自定义服务商" width="2400" height="1692" data-path="images/lobehub1.png" />

### 4. 创建自定义 AI 服务商

| 字段           | 填写内容                         | 说明                                                         |
| ------------ | ---------------------------- | ---------------------------------------------------------- |
| **服务商 ID**   | `gravitexai`                 | 作为服务商唯一标识，创建后不可修改                                          |
| **服务商名称**    | `gravitexai`                 | 自定义服务商名称                                                   |
| **服务商简介**    | `gravitexai`                 | 自定义描述                                                      |
| **服务商 Logo** | （留空）                         | 可选，自定义 Logo 地址                                             |
| **请求格式**     | `OpenAI`                     | GravitexAI 完全兼容 OpenAI 协议                                  |
| **代理地址**     | `https://api.gravitex.ai/v1` | Base URL，**务必以 `/v1` 结尾**                                  |
| **API Key**  | 您的 GravitexAI API Key        | 在 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys) 获取 |

填写完成后点击右下角 **新建** 按钮保存。

<img src="https://mintcdn.com/gravitexai/1w6qMcPexYzhP5k_/images/lobehub2.png?fit=max&auto=format&n=1w6qMcPexYzhP5k_&q=85&s=b426609b24b782760a15da26dbd72c28" alt="创建自定义 AI 服务商" width="2400" height="1692" data-path="images/lobehub2.png" />

<Tip>
  **配置要点**

  * 「代理地址」必须以 `/v1` 结尾，否则请求会路由失败
  * 「API Key」粘贴时请删除前后空格
  * 「请求格式」选择 `OpenAI` 即可访问 GravitexAI 全部 100+ 模型
  * 一个密钥可同时启用多种模型，按用量计费，无需为单模型单独付费
</Tip>

### 5. 验证连通性

新建成功后，会跳转到服务商详情页。可以：

1. **填写 API Key 与代理地址**：再次确认或修改
2. **开启高级选项**（可选）：
   * 「使用 Responses API 规范」：开启后可使用 OpenAI 新一代请求格式（仅 OpenAI 模型支持）
   * 「使用客户端请求模式」：浏览器直接发起会话，可提升响应速度
3. **连通性检查**：在下拉框中选择一个模型，点击 **检查** 按钮测试连通性
4. **获取模型列表**：点击 **获取模型列表** 按钮，自动拉取 GravitexAI 提供的全部模型

成功获取后，「模型列表」会显示 GravitexAI 当前在售的全部模型，按类型分组：对话、图片、视频、向量化、TTS。

<img src="https://mintcdn.com/gravitexai/1w6qMcPexYzhP5k_/images/lobehub3.png?fit=max&auto=format&n=1w6qMcPexYzhP5k_&q=85&s=4db45efc3f29c87016ac4e7c7bdc9a90" alt="验证连通性与获取模型列表" width="2400" height="1692" data-path="images/lobehub3.png" />

<Warning>
  如果「连通性检查」失败，请按以下顺序排查：

  * 代理地址末尾是否包含 `/v1`
  * API Key 是否有效（可在 GravitexAI 控制台验证）
  * 防火墙 / 代理设置是否拦截 HTTPS
</Warning>

### 6. 选择模型开始对话

在对话界面的模型下拉框中，选择您想使用的模型（如 `claude-opus-5`、`gpt-5.6-luna`、`deepseek-v4-pro`），即可开始对话。

<Card title="查看当下热门模型推荐" icon="star" href="https://maas.gravitex.ai/#/api-models">
  查看最新的模型推荐、性能对比和场景化使用建议，涵盖文本创作、编程开发、快速响应、图像生成、视频生成等全场景。
</Card>

<Info>
  **为什么不在此列出具体模型？**

  AI 模型更新迭代速度非常快，为了确保您获取最准确的模型推荐信息，我们统一在 [模型推荐页面](https://maas.gravitex.ai/#/api-models) 维护最新的模型列表、性能数据和使用建议。
</Info>

## 三、一站式接入 100+ 模型

LobeHub 内置了多家服务商的官方渠道，需要逐个填密钥；接 GravitexAI 则只需建**一个**自定义服务商，即可覆盖全部模型：

| 渠道                        | 适用模型                                       | 核心优势             | API 地址                       |
| ------------------------- | ------------------------------------------ | ---------------- | ---------------------------- |
| **OpenAI 兼容（GravitexAI）** | 全部 100+ 模型（含 Claude、Gemini、GPT、DeepSeek 等） | 一个密钥通吃全部模型，配置最简单 | `https://api.gravitex.ai/v1` |

<Tip>
  **一个 GravitexAI 渠道就能访问 Claude / Gemini / GPT / DeepSeek 等所有模型**

  GravitexAI 把 Claude、Gemini、GPT、DeepSeek 等主流模型统一封装为 OpenAI 兼容协议，所以你只要在 LobeHub 里建一个 `GravitexAI` 自定义服务商，就能在模型下拉框里选到全部 100+ 模型，无需为不同厂商分别配置渠道。
</Tip>

## 四、LobeHub 特色玩法

### 插件系统

LobeHub 提供丰富的插件市场（设置 → 插件），推荐开启：

* **Web 搜索**：让模型实时联网获取最新信息
* **代码解释器**：对话中运行 Python 代码、做数据可视化
* **图表生成**：自动生成流程图、思维导图
* **图像生成**：通过 `gpt-image-2`、`gemini-3-pro-image` 等模型生成图片

### 本地知识库（RAG）

LobeHub 支持上传文件建立本地向量库：

1. 进入「知识库」页面，新建知识库
2. 上传 PDF、Markdown、Word、Excel、TXT 等文件
3. 系统自动切片、向量化
4. 对话时勾选知识库，模型将基于您的私有资料回答

<Warning>
  知识库的「向量化」步骤会调用 Embedding 模型（计费）。建议使用 GravitexAI 提供的 `text-embedding-3-large` 等向量化模型。
</Warning>

### 多模态对话

支持上传图片进行视觉理解、识图、OCR：

* 视觉模型推荐：`gemini-3.6-flash`、`claude-opus-5`、`gpt-5.6-terra`
* 直接在对话框拖入图片，模型会自动识别

### 助手市场（Agent Market）

LobeHub 内置丰富的预设助手（翻译、写作、编程、面试等），您也可以：

* 在「助手市场」一键启用社区分享的助手
* 自建助手：自定义人设、Prompt、开场白、知识库、插件

### 对话管理与导出

* 多分支对话、消息编辑与重新生成
* 对话导出：Markdown、PNG、JSON
* 全局搜索历史消息

## 五、高级配置

### 网络代理与自托管

如需使用代理或自托管 LobeHub：

1. **桌面版**：设置 → 网络 → 配置 HTTP/HTTPS 代理
2. **自托管（Docker）**：通过环境变量注入 GravitexAI 配置：
   ```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. **客户端请求模式**：开启后浏览器直连 API（需保证浏览器能访问 GravitexAI）

### 快捷键

| 快捷键                    | 功能   |
| ---------------------- | ---- |
| `Ctrl/Cmd + N`         | 新建对话 |
| `Ctrl/Cmd + K`         | 快速搜索 |
| `Ctrl/Cmd + /`         | 命令面板 |
| `Ctrl/Cmd + Shift + M` | 切换模型 |

## 六、移动端

LobeHub 桌面端支持 Windows / macOS / Linux，移动端可通过浏览器访问 `lobechat.com` 网页版（响应式适配），无需单独安装 App。

## 七、故障排除

<AccordionGroup>
  <Accordion title="连接失败 / 连通性检查不通过">
    | 现象           | 排查方向                                                                        |
    | ------------ | --------------------------------------------------------------------------- |
    | 提示 401 / 403 | API Key 无效或余额不足，前往 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys) 核对 |
    | 提示 404       | 代理地址未以 `/v1` 结尾，缺少 `/v1` 后缀                                                 |
    | 提示超时         | 网络环境问题，检查代理或防火墙设置                                                           |
    | 提示 CORS 错误   | 关闭「使用客户端请求模式」，或通过服务端中转                                                      |
  </Accordion>

  <Accordion title="模型列表为空">
    * 点击 **获取模型列表** 按钮手动拉取
    * 等待 1-2 秒后刷新页面
    * 确认 API Key 在 GravitexAI 控制台状态正常
  </Accordion>

  <Accordion title="响应慢或流式断流">
    * 切换到更快模型（如 `gemini-3.6-flash`、`claude-haiku-4-5`、`deepseek-v4-flash`）
    * 关闭不必要的插件
    * 检查网络延迟
    * 减少上下文长度（关闭过长的旧对话）
  </Accordion>

  <Accordion title="网页版和桌面版的数据互通吗？">
    使用同一 LobeHub 账号登录时，部分配置和会话可以同步；本地数据建议定期导出备份
  </Accordion>

  <Accordion title="LobeChat 和 LobeHub 是什么关系？">
    LobeChat 是开源项目名，LobeHub 是产品/云平台名。两者底层代码一致，桌面版和自托管版通常仍基于 LobeChat 仓库构建。
  </Accordion>

  <Accordion title="为什么自托管后无法调用模型？">
    检查 API Key 是否正确、Base URL 是否可达、服务器出网是否被限制、以及容器内 DNS 解析是否正常。
  </Accordion>
</AccordionGroup>

## 八、最佳实践

### 模型选择策略

不同任务用不同模型，按复杂度梯度选择：

* **日常聊天 / 简单问答**：`gemini-3.1-flash-lite`、`claude-haiku-4-5`、`deepseek-v4-flash`
* **复杂推理 / 长文档分析**：`claude-opus-5`、`gpt-5.6-sol`、`deepseek-v4-pro`
* **代码开发**：`claude-opus-5`、`gpt-5.6-sol`、`claude-sonnet-5`
* **图像理解**：`gemini-3.6-flash`、`claude-opus-5`、`gpt-5.6-terra`
* **图像生成**：`gpt-image-2`、`gemini-3-pro-image`

完整模型列表与性能对比请参考 [模型推荐页面](https://maas.gravitex.ai/#/api-models)。

### 上下文管理

* 定期清理无用的旧对话
* 复杂任务拆分成多个短对话
* 善用「分叉对话」功能探索不同回答

### 安全与隐私

* 不要在公共场合分享 API Key
* 定期更换密钥
* 敏感对话建议自托管 LobeHub，数据完全本地存储

### 自托管建议

* 生产环境使用 Docker + PostgreSQL，不要用内置数据库
* 反向代理建议套 Cloudflare
* 通过环境变量集中管理密钥，便于多实例部署

## 九、三种方式对比

| 维度    | 桌面版            | 网页版（官方）        | 自托管版               |
| ----- | -------------- | -------------- | ------------------ |
| 安装难度  | 低（下载安装包）       | 极低（打开网页）       | 中到高（需部署）           |
| 数据归属  | 本地为主           | 官方云端           | 完全自主               |
| 网络要求  | 访问模型 API 即可    | 需访问官方站点及模型 API | 取决于部署位置            |
| 多用户协作 | 弱              | 中              | 强（可配账号权限）          |
| 适合人群  | 个人效率用户         | 临时/轻量用户        | 企业、团队、隐私敏感用户       |
| 成本    | 免费（自备 API Key） | 免费档 + 付费套餐     | 服务器成本 + 自备 API Key |

<Info>
  **更多帮助**：技术支持联系 [bd@gravitex.ai](mailto:bd@gravitex.ai)，或致电 13603055233。
</Info>