> ## 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.

# 在 Codex 里连接 Open Study

> Codex CLI 和桌面端共用一份插件配置：两条命令装好；桌面端在 设置 → 插件 → MCP 里授权，按钮没反应就运行 codex mcp login open-study。

Codex CLI 和 Codex 桌面端共用同一份插件配置：在终端里装一次，桌面端重启后也能用。已有用户用这种方式连上 Open Study。Codex IDE 扩展不支持这套插件安装方式。

## 安装插件

```bash theme={null}
codex plugin marketplace add moonlight-code-space/open-study --ref plugin-stable --json
codex plugin add open-study@open-study --json
```

只装了桌面端、终端里找不到 `codex` 命令的，先装 [Codex CLI](https://developers.openai.com/codex/cli)，或者把快速开始里的安装提示词发给 Codex 桌面端让它代装。

已经装过的，先按原安装方式更新，不要重复添加来源，也不要换成本地下载目录。

> **连不上 GitHub 时**
>
> 只在第一次安装、又连不上 GitHub 时用；已经从 GitHub 装过的，保留现有插件，恢复连接后再更新。
>
> 1. 登录网站，打开左侧 **快速开始**，在页面下方 **离线包** 里下载 **Codex 插件**，完整解压到准备长期保留的文件夹。
> 2. 先确认终端能运行 `codex plugin --help`；macOS / Linux 还要有 Python 3，缺了先装 [Codex CLI](https://developers.openai.com/codex/cli) 或 [Python 3](https://www.python.org/downloads/)。
> 3. 在解压出来、包含 `install.sh` 的那个文件夹里运行：macOS / Linux 用 `sh ./install.sh --offline`，Windows 用 `powershell -ExecutionPolicy Bypass -File .\install.ps1 -Offline`。
> 4. 装好后保留这个文件夹，再按下面的步骤授权。

## 授权

有的 Codex 版本装完会自己弹出授权，跟着走完即可。

**桌面端**：打开 **设置 → 插件**，切到顶部的 **MCP** 页签，插件带来的服务在「来自插件」里，open-study 那一行点 **进行身份验证**（英文界面是 **Authenticate**）。浏览器打开 Open Study 的授权页后，登录并点 **允许连接**。

这个按钮有时点了不会打开浏览器。没反应就改用下面的命令，桌面端和命令行共用同一份授权。

**命令行**：

```bash theme={null}
codex mcp login open-study
```

它会先打印一条 `https://study.faroapi.cn/authorize` 开头的授权链接，再尝试打开浏览器，然后在本机等你最多 5 分钟。登录后点 **允许连接**，等命令显示 `Successfully logged in to MCP server 'open-study'`。浏览器没自己打开时，把打印出来的链接复制到浏览器里打开。不要加 `--no-browser`：加了它，命令会要求把跳转后的地址粘贴回终端。

**让 Codex 里的 AI 代为授权**：AI 能运行 `codex` 命令时，可以替你运行上面这条命令，从输出里取出授权链接，用默认浏览器打开并发给你，再等命令显示成功。Codex 可能请你批准联网或本机端口，照实批准即可。

还没有 Open Study 账号，先到 [study.faroapi.cn](https://study.faroapi.cn) 注册。密码只填在网站的授权页，不用发给 Agent。

## 不想自己敲命令

这一节写给人看：登录网站，打开左侧 **快速开始**，点 **Codex CLI** 或 **Codex 桌面端** 那张卡片，在 **提示词** 页签复制安装提示词发给 Codex。它会读这一页、代你安装，再引导你授权。

## 确认能用

完全退出并重开 Codex（命令行退出当前会话再启动；桌面端重开后点 **新建任务**），把这段发过去：

请使用 Open Study 查询我的资料库，列出最多三条资料标题和内容 ID。没有资料就说明为空；还没连上就告诉我下一步。只查询已有资料，不整理新视频。

请使用 Open Study 查询我的资料库，列出最多三条资料标题和内容 ID。没有资料就说明为空；还没连上就告诉我下一步。只查询已有资料，不整理新视频。

收到资料列表或「资料库为空」，就说明连上了。

## 更新与遇到问题

1. 先看原来的来源：

   ```bash theme={null}
   codex plugin marketplace list --json
   ```

   名称 `open-study` 应只出现一次，来源是 Git 仓库 `moonlight-code-space/open-study`；结果里有 `ref`、`refName` 或 `gitRef` 时应为 `plugin-stable`。来源是本地目录、别的仓库或有重复条目时，先保留配置，把结果[告诉维护者](https://docs.study.faroapi.cn/help/contact.md)。

2. 核对无误后依次运行，第一条失败时先处理错误，不继续下一条：

   ```bash theme={null}
   codex plugin marketplace upgrade open-study --json
   codex plugin add open-study@open-study --json
   ```

3. **旧版 `update.sh` 提示无法确认 ref**：部分 Codex 版本的结果不带 ref 字段。核实是唯一的官方 Git 来源后，直接用上面两条命令更新；显示别的 ref 或核实不了来源时不要继续。这个提示不代表插件坏了。

更新后完全退出并重开 Codex（命令行退出当前会话再启动；桌面端重开后点 **新建任务**），新开对话发上面「确认能用」那句。

从离线包装到本地目录的，保留原解压目录，不能用 GitHub 更新器；需要换包时[联系维护者](https://docs.study.faroapi.cn/help/contact.md)。

GitHub 上的版本有时比网站上显示的晚，这是正常的：保留 GitHub 来源，不要为了追版本换成本地下载的文件。

* **ChatGPT 的连接器不是 Codex 插件**：在 ChatGPT 普通聊天里加的连接器不会出现在 Codex 里，要按上面的命令装。
* **调用到旧的 bilistudy Skill**：新旧插件并存时，在请求里写明「使用 `$open-study`」。
* **连接问题**：见[插件更新与连接问题](https://docs.study.faroapi.cn/connect-ai/update-troubleshoot.md)。
* **官方说明**：[Codex 插件](https://developers.openai.com/plugins/build/plugins)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.