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

# 远程访问 Linkly AI

> 通过公网隧道 + Auth 认证在 ChatGPT、Claude.ai 等在线 AI 应用中安全的远程访问你的本地知识库

## 什么是远程访问

Linkly AI 运行在你的本机上，而 ChatGPT、Claude.ai 等在线 AI 应用运行在云端，它们无法直接访问你的本地的知识库 MCP 服务。

`远程访问`功能通过在你的桌面端和云端之间建立一条安全隧道，实现公网中转：

1. 桌面端通过 API Key 鉴权，建立 WebSocket 隧道连接到 `mcp.linkly.ai`
2. 在线 AI 应用通过 OAuth 授权后，将 MCP 请求发送到 `https://mcp.linkly.ai/mcp`
3. 云端服务将请求通过隧道转发到你的桌面端，桌面端执行后返回结果

你的文档数据始终保存在本地，隧道仅转发 MCP 请求和响应，不存储任何文档内容。

<Note>
  `mcp.linkly.ai` 是一个云端 MCP 中转服务，由 Linkly AI
  官方维护。数据在其中匿名发送，Linkly AI 仅记录使用次数用于展示。
</Note>

## 配置步骤

<Steps>
  <Step title="注册 Linkly AI 账号">
    前往 [linkly.ai](https://linkly.ai) 注册并登录账号。
  </Step>

  <Step title="生成 API Key">
    在 Dashboard 的「API Key 管理」中，点击「新增 API Key」，生成一个以 `lkai_` 开头的 Key。

    <Warning>
      请妥善保管你的 API Key，不要泄露给他人。泄露的 Key 可能被用于访问你的本地知识库。
    </Warning>
  </Step>

  <Step title="在桌面端连接隧道">
    打开 Linkly AI Desktop，进入 **设置 → MCP**，找到「远程访问」区域：

    1. 在 API Key 输入框中粘贴刚才生成的 Key
    2. 点击「连接公网隧道」按钮
    3. 等待状态显示为 <Badge stroke color="green">● 已连接</Badge>
  </Step>

  <Step title="在 AI 应用中添加 MCP 服务">
    在 ChatGPT、Claude.ai 等支持 MCP 的 AI 应用中，添加以下 MCP 端点：

    ```
    https://mcp.linkly.ai/mcp
    ```

    首次添加时会触发 OAuth 授权流程，按照提示在浏览器中登录并授权即可。

    各应用的具体配置方式，请参阅[集成文档](/docs/zh/integration/use-in-claude)。
  </Step>
</Steps>

## OAuth 授权说明

ChatGPT、Claude.ai 等在线 AI 应用在首次连接远程 MCP 服务时，会自动触发 OAuth 2.1 授权流程：

1. AI 应用发现 MCP 端点需要授权
2. 自动跳转到 linkly.ai 的登录页面
3. 你登录并确认授权后，AI 应用获得访问令牌
4. 后续请求自动携带令牌，无需重复授权

<Tip>如果你已经在浏览器中登录了 linkly.ai，授权过程会更加快速。</Tip>

## 安全注意事项

* **API Key 保管**：API Key 等同于你的隧道凭证，请勿分享给他人。如果怀疑泄露，可在 Dashboard 中撤销并重新生成
* **HTTPS 传输**：远程隧道全程使用 HTTPS/WSS 加密传输，确保数据安全
* **随时可撤销**：你可以在桌面端随时断开隧道。在 Dashboard 中撤销 API Key 可阻止新的连接和重连，但不会立即断开已建立的隧道会话
* **数据不上云**：你的文档数据始终保存在本地电脑上，隧道仅转发 MCP 工具调用的请求和响应

## 常见问题

<AccordionGroup>
  <Accordion title="提示「API Key 无效」">
    请检查：

    1. API Key 是否完整粘贴（以 `lkai_` 开头）
    2. API Key 是否已在 Dashboard 中被撤销
    3. 尝试在 Dashboard 重新生成一个新的 API Key
  </Accordion>

  <Accordion title="桌面端离线，远程调用返回错误">
    远程 MCP 服务需要桌面端保持运行并连接隧道。如果桌面端关闭或隧道断开，远程调用会立即返回 503 错误。

    请确保：

    * Linkly AI Desktop 已启动
    * MCP 服务正在运行（设置中显示 Running）
    * 隧道状态为 <Badge stroke color="green">● 已连接</Badge>
  </Accordion>

  <Accordion title="隧道连接断开">
    隧道具有自动重连机制（最多重试 10 次，采用指数退避策略）。如果频繁断开，请检查：

    * 网络连接是否稳定
    * API Key 是否仍然有效

    如果持续断开，可尝试手动断开后重新连接。
  </Accordion>

  <Accordion title="OAuth 授权失败">
    如果在 ChatGPT 或 Claude.ai 中添加 MCP 后授权失败：

    1. 确保桌面端隧道处于连接状态
    2. 尝试在浏览器中先登录 linkly.ai
    3. 重新在 AI 应用中添加 MCP 服务器

    如果问题持续，请移除已添加的 MCP 服务器后重新添加。
  </Accordion>
</AccordionGroup>