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

# 安装步骤：供 Agent 读取

> Open Study 插件的官方安装来源、Codex 安装命令、账号连接和检查步骤。

这页供代用户安装的 Agent 读取。普通用户只需复制[安装提示词](/connect-ai/install-codex)，不用手动完成本页全部步骤。

## 1. 确认要安装到哪个客户端

目标是让用户在自己的 Agent 中使用 **Open Study Skill + 远程 MCP**。下面的安装器适用于支持插件的 **Codex 桌面端与 Codex CLI**，不适用于 Codex IDE 扩展。

先识别当前客户端和操作系统。如果用户要装到其他客户端，说明这份包是 Codex 格式；先核对该客户端的官方 Skill、远程 HTTP MCP 和网页登录支持，再提出适配方案，不直接执行 Codex 命令。本页没有给其他客户端已通过完整使用验证的承诺。

若当前 Agent 不能联网或操作本机，说明具体缺少哪项能力，给用户[手动安装入口](/connect-ai/install-codex)。不要只返回“安装完成”。

## 2. 取得官方插件包

官方发布入口：[Open Study → 连接 AI](https://study.faroapi.cn/#ai)。按页面提供的版本下载；页面要求登录时，让用户完成网页登录。

本页已核对的 **0.5.0** 包地址为：

```text theme={null}
https://study.faroapi.cn/downloads/open-study-plugin-v0.5.0.bin
```

该文件内容是 **ZIP**。网站下载按钮把它命名为 `open-study-plugin-v0.5.0.zip`；直接下载时请保存为 `.zip` 再解压，**不要把 URL 的 `.bin` 猜改成 `.zip`**。如果返回网页或错误，不要当成安装包执行；让用户从官方页面下载并提供文件。

网站提供了不同版本时，以该版本的包内说明为准，不把下面的 0.5.0 命令强套到新包。

完整解压到用户准备长期保留的目录，找到包含以下文件的那一层：

```text theme={null}
open-study-codex-marketplace-v0.5.0/
  .agents/plugins/marketplace.json
  plugins/open-study/.codex-plugin/plugin.json
  plugins/open-study/.mcp.json
  plugins/open-study/skills/open-study/SKILL.md
  install.sh
  install.ps1
  INSTALL.md
  UPDATE.md
```

读取 `INSTALL.md`、插件声明和安装脚本后再运行；不要仅复制一个脚本，也不要在临时下载目录安装后把来源目录删掉。

## 3. 检查环境并安装

先运行 `codex --version` 和 `codex plugin --help`。macOS / Linux 另需 `python3 --version`。

找不到命令时，先检查已安装的工具位置；确实缺少时按 [Codex CLI 官方说明](https://developers.openai.com/codex/cli)和 [Python 官方说明](https://www.python.org/downloads/)补齐。使用用户当前的权限范围，不自行改系统权限来强行安装。

在**完整解压目录**运行：

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

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

安装器将注册本地插件来源并安装 `open-study@open-study`。成功后说明安装版本和来源目录；下载包只是不依赖 GitHub 的安装方式，使用仍需联网。

如果已经有 Open Study，先查看现有来源。来源冲突时保留原配置，按[更新与连接问题](/connect-ai/update-troubleshoot)处理，不删除旧插件来绕过报错。

<Accordion title="可选：已有仓库访问权限时从 GitHub 安装">
  官方仓库是 `moonlight-code-space/open-study-codex-plugin`，安装分支是 `plugin-stable`。只有用户已能访问这个仓库时才使用；无权限时改用下载包，不反复要求重新登录 GitHub。

  在完整解压的发布包根目录运行：

  <Tabs>
    <Tab title="macOS / Linux">
      ```bash theme={null}
      sh ./install.sh moonlight-code-space/open-study-codex-plugin
      ```
    </Tab>

    <Tab title="Windows">
      ```powershell theme={null}
      powershell -ExecutionPolicy Bypass -File .\install.ps1 moonlight-code-space/open-study-codex-plugin
      ```
    </Tab>
  </Tabs>

  已有本地包来源不能靠这条命令自动迁移到 GitHub。
</Accordion>

## 4. 新对话中连接账号

安装后，让用户新建 Codex 对话。新插件在新对话加载，旧对话不需要删除。[Codex 官方插件说明](https://learn.chatgpt.com/docs/plugins)。

插件已经配置产品 MCP 地址 `https://study.faroapi.cn/mcp`，不要再添加重复连接，也不要换成文档站的 MCP。

使用客户端正常的 Open Study 连接流程。需要授权时，让用户在 Open Study 网页登录并选择 **允许连接**；安装时已经完成授权的，可直接查询。网站和 Agent 应连接同一账号。

## 5. 用一次查询确认可以使用

在能加载插件的新对话里，实际调用连接检查 `system_status`；连接正常后用 `library_search` 查询已有资料，列出最多三条标题和 BV 号。查询返回空列表也可以；没有调用结果时，不要把口头确认当作连接成功。

这一步只查已有资料，不自动提交视频、重新整理或生成网站 AI 结果。

结束时只告诉用户三件事：

1. 插件装到了哪个客户端、安装是否完成；
2. 账号是否连接、资料查询是否返回结果；
3. 下一步可以发链接，还是需要登录或新开对话。

若要切到新对话才能继续，给用户这句话：

```text theme={null}
请使用 Open Study 查询我的资料库，列出最多三条标题和 BV 号。没有资料就说明为空；还未连接时带我完成网页登录。只查询已有资料。
```

## 装好后按 Skill 使用

插件自带日常流程：公开 B 站链接 → 提交一次整理 → 等待服务器结果 → 读取相关资料 → 回答用户问题。价格、积分和使用记录留在网站查看，不在每次回答中展开。

本页核对的包有一处旧提示：积分不足时可能建议人民币钱包充值。遇到这种情况，应按网站当前的[积分说明](/billing/credits-and-usage)处理，不承诺钱包余额可以补足整理积分。

接下来按[第一次使用](/connect-ai/use-codex)发送链接，或使用[工作流提示词](/library/learn-with-materials)。