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

# 更新插件与排查连接问题

> 更新 Open Study 插件，并解决新任务里插件未出现、OAuth 未完成或来源冲突。

远程 MCP 服务由 Open Study 服务端更新；本地插件只包含轻量的 Skill 和连接声明。服务端更新通常不要求重新安装插件。

## 先分清：网站更新，还是插件更新

| 变化发生在哪里            | 你需要做什么                  |
| ------------------ | ----------------------- |
| Open Study 网站或远程服务 | 正常继续使用；服务端更新不等于必须重装插件   |
| 插件的操作说明或连接配置       | 按自己的安装来源更新，再新建 Codex 任务 |
| 网站和插件版本号不同         | 不代表装错；它们各自发布版本，不要求数字相同  |

## 从 GitHub 安装：运行更新器

仅适用于已经从正式 GitHub 来源安装、且当前账号仍能访问私有仓库的用户。在**完整解压的发布包根目录**运行：

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    sh ./update.sh
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    powershell -ExecutionPolicy Bypass -File .\update.ps1
    ```
  </Tab>
</Tabs>

脚本会刷新已经配置的 `plugin-stable` 来源，再安装对应的 `open-study`。实际等待时间取决于网络和 Codex 的处理结果；以脚本明确显示成功为准。

<Warning>
  更新成功后必须新建 Codex 任务。已经打开的任务不会热替换 Skill 和 MCP 声明。
</Warning>

## 从离线包安装：先保留正在使用的版本

离线包**不能使用上面的 GitHub 更新器**。在已核对的发布包中，还没有经过验证的一键离线换包流程；包内 `UPDATE.md` 主要说明 GitHub 更新和迁移，不表示离线安装可以直接运行 `update.sh`。

请这样处理：

1. 保留当前能使用的完整解压目录，不要删除、移动或只覆盖其中几份文件。
2. 如果只是网站升级，先继续使用现有插件并做一次资料库查询，不必因为网站版本变了就换包。
3. 只有新发布说明明确提供适用于**你当前版本的离线迁移步骤**时，再按该说明更换。
4. 必须更新但没有对应说明时，准备旧版本、新版本和安装报错，按[反馈说明](/help/contact)请维护者确认步骤。

<Warning>
  把新包解压到另一目录后直接运行安装器，可能被“已有不同本地来源”拦住。这是在保留旧配置，不代表你应该删除旧目录来试。没有 GitHub 仓库权限时，也不能把迁移到 GitHub 当作解决办法。
</Warning>

## 插件安装后没有出现

请按顺序检查：

1. 安装命令是否明确显示成功；
2. 是否在安装后新建了 Codex 任务；
3. 插件列表里是否有 `open-study`，并且已启用；
4. 是否存在另一个同名插件来源，或指向旧解压目录的本地来源；
5. 是否在旧的 `bilistudy` Skill 与新的 `open-study` 之间选错。

如果新旧两套暂时并存，在请求中明确写“使用 `$open-study`”。

如果安装时提示找不到 `codex`、`python3` 或脚本文件，先回到[安装前检查](/connect-ai/install-codex)，确认工具和当前目录，重复点安装不会补齐它们。

## Open Study 显示未连接

1. 在新任务里输入“检查 Open Study 连接状态”；
2. 按提示打开 OAuth 页面；
3. 确认地址属于 `study.faroapi.cn`；
4. 选择 **允许连接**；
5. 再做一次资料库搜索；空库可以返回“没有资料”，不需要为了测试连接先整理新视频。

安装成功只表示插件文件已经进入 Codex，不代表网站 OAuth 已经完成。

如果浏览器停在错误页，不要反复打开旧的授权回调链接。从 Codex 重新发起这一次连接，完成后再查询资料。仍失败时，保留错误文字，不要公开分享带登录参数的完整地址。

## 网站里有资料，Codex 却找不到

先核对连接的是不是同一个 Open Study 账号，再把查询改为准确 BV 号。文档站搜索不会查私人资料；需要让 Codex 使用 **Open Study 插件**，而不是只打开这份说明书。

## 更新脚本停止并提示来源冲突

安装器发现同名本地来源、另一个 GitHub 仓库、不同更新分支或重复来源时会停止，以免覆盖现有配置。报错中可能把插件来源写成 `marketplace`。

先保留能用的旧来源，记录提示、安装方式和版本。确实需要迁移时，按对应发布说明处理；没有说明就[反馈当前问题](/help/contact)。

## 怎样算恢复正常

新建任务后，确认 Codex 实际调用 Open Study 的连接检查和资料库查询，并成功得到服务端结果：已有资料能找到，真实空库则返回空列表。只口头说“已连接”而没有成功调用，不算检查完成。

需要验证整理功能时，再明确提交一条新链接，等待结果，并在网站找到对应资料。

<Card title="仍然无法使用？" icon="circle-help" href="/help/faq">
  按症状查看常见问题，并准备不包含密码或密钥的问题信息。
</Card>