Zotero Codex怎么用：3种实现、安装连接与全文排查

更新于 2026-10-26 · jetstream.mom

简答：先按需求选实现：搜索本地文献和导出引用看 OpenAI plugins 仓库中的 Zotero skill；想在 Zotero 侧边栏聊天看 RTLiang 项目；要联动 PDF 页面和 Better Notes 再评估 haohaomin MCP。三者不要混用命令，安装后先完成搜索、BibTeX 导出和全文读取三项验证。

定义：Zotero Codex是对多种把 Codex 与本地 Zotero 文库连接起来的 skill、侧边栏插件或 MCP 项目的统称，不是一个唯一软件名称。

先选对实现：搜索、侧边栏和 MCP 不是一回事

本站与 Zotero、Codex 及下列社区项目无关联。已核对到的公开资料显示，搜索词“Zotero Codex”至少对应三类实现：OpenAI plugins 仓库中的 Zotero skill、RTLiang 的 Zotero 侧边栏插件，以及 haohaomin 的 Zotero Codex MCP 项目。它们的安装入口、版本要求和写入能力不同，不能把一个项目的命令复制到另一个项目。

需求	优先查看	文档明确支持	写入风险与边界
搜索本地条目、集合和标签，导出 BibTeX，向 LaTeX 或 Markdown 草稿插入引用	OpenAI plugins 仓库中的 Zotero skill	skill 文件列出本地 API 检查、搜索、BibTeX 导出、引用插入和按需读取全文	导入 BibTeX、RIS 或连接器保存属于明确写操作，需要确认来源和目标
在 Zotero 阅读器旁边讨论论文，发送摘要、引用信息或选中文本	RTLiang/zotero-codex	项目 README 自述支持 Zotero 侧边栏、PDF 阅读、Codex CLI 登录和会话继续	插件本身不直接修改 Zotero 条目，但 Codex 权限和文件访问仍需检查
读取 PDF 指定页、页面图片、选区，编辑 Better Notes 或同步 Markdown	haohaomin/zotero-codex	项目 README 自述支持本地 MCP、PDF 页面、选区、笔记编辑和 Markdown 同步	属于社区项目；会执行笔记或文献写入，Windows 宿主尚未验收

最快的选择结论是：只做文献搜索和引用导出，先看 Zotero skill；想在 Zotero 内边读边聊，选侧边栏插件；需要 PDF 页面图像、选区或 Better Notes，再单独评估 MCP。下面的命令只适用于对应项目。

OpenAI plugins 仓库中的 Zotero skill 说明见 Zotero skill 原文；侧边栏安装要求见 RTLiang 项目 README；MCP 功能边界见 haohaomin 项目 README。

安装前检查：版本、客户端和本地 API

按2026-10界面核对，三种方案都需要 Zotero Desktop，但兼容关系不能合并成一个结论。

组件	OpenAI plugins 仓库中的 Zotero skill	RTLiang 侧边栏	haohaomin MCP
Zotero	skill 文档未在该文件中限定具体大版本；以仓库当前说明和本机检查结果为准	README 明确写 Zotero 10.0.x，manifest 限制为 10.0.*	README 明确写需要 Zotero 10；0.8.3 的项目验证记录使用 Zotero 10.0.5
Codex	需要能运行该 skill 的 Codex 环境；仓库文件未给出统一客户端版本号	需要安装并完成 `codex login`；交互视图还依赖实验性 dynamic-tool 支持	需要支持本地 MCP 的 Codex 客户端；连接后需重启 Codex
插件或 skill 版本	当前打开的 SKILL.md 未标注独立版本号	从 Release 下载 XPI；具体版本以 Release 页面为准	README 当前标为 Zotero Codex MCP 0.8.3；MCP 服务和 XPI 应保持相同版本
Better Notes	不是该 skill 的必需项	不是 README 的必需项	实时笔记协作需要 Better Notes，README 标注已验证 3.3.3

因此，安装前不要只看“Zotero Codex”这个名称。应记录 Zotero Desktop 版本、Codex 客户端或 CLI 版本、XPI 或 skill 来源、插件版本以及是否启用 Better Notes。官方插件机制的市场和本地插件说明可参考 OpenAI Developers 的插件文档，但它不能替代具体项目 README 的兼容性说明。

三条安装路径：只照对应项目的步骤操作

路径一：OpenAI plugins 仓库中的 Zotero skill

在你的 Codex 环境中启用或取得该仓库的 Zotero skill，并确认 <plugin-root> 指向 skill 所在插件根目录。
保持 Zotero Desktop 运行，先检查本地 API 状态：

python3 <plugin-root>/skills/zotero/scripts/zotero.py status --json

如果状态中的 local_api_enabled_pref 为 false，且任务确实需要操作本地 Zotero，再执行：

python3 <plugin-root>/skills/zotero/scripts/zotero.py enable --restart

随后用只读操作验证搜索和导出：

python3 <plugin-root>/skills/zotero/scripts/zotero.py search "transformer" --json
python3 <plugin-root>/skills/zotero/scripts/zotero.py export-bibtex --out references.bib

这些命令来自该 skill 的 SKILL.md，不是所有 Zotero 插件或 MCP 项目的通用命令。

路径二：RTLiang Zotero 侧边栏插件

安装 Codex CLI，并在终端运行 codex login。
从项目 Release 下载 XPI，在 Zotero 的“工具 → 插件 → 齿轮 → 从文件安装插件”中安装。
重启 Zotero，选中一篇论文或打开 PDF，点击右侧 Codex 图标。
若自动找不到 Codex，在侧边栏设置中填写 Codex 可执行文件的绝对路径。

macOS 和 Linux 的 README 示例检查命令是：

which codex
codex --version
codex login status

Windows PowerShell 示例是：

Get-Command codex
codex --version
codex login status

项目 README 还列出独立安装器的默认路径：macOS/Linux 通常为 ~/.local/bin/codex，Windows 通常为 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin\codex.exe；自定义安装目录应以本机实际路径为准。

路径三：haohaomin Zotero Codex MCP

从项目 Release 下载与 MCP 服务对应版本的 XPI。
在 Zotero 中打开“工具 → 插件 → 从文件安装插件”。
进入“设置 → Zotero MCP”，等待运行组件检查完成，再点击“连接 Codex”。
重启 Codex，保持 Zotero 打开，发送“检查 Zotero 连接状态”。

该项目 README 自述会自动准备运行组件，不要求普通用户单独安装 Node.js 或常驻终端；首次准备运行组件需要网络。连接按钮还会开启本地 API，并更新 Codex 用户配置中的 Zotero 连接。若下载或校验失败，项目自述会保留可用的旧运行包，具体行为应以本机界面为准。

按平台完成导入、开启、验证三步

Windows：PowerShell、绝对路径和宿主限制

导入：在 Zotero 插件页从文件安装对应 XPI；不要把 XPI 解压后手动复制到配置目录。
开启：RTLiang 方案在 PowerShell 中检查 codex；若使用独立 Codex 存储目录，可先设置 $env:CODEX_HOME，再运行 codex login。
验证：侧边栏发送“搜索标题中包含 transformer 的条目”，再导出一个小范围 BibTeX。日志入口优先看 Zotero 插件管理页、侧边栏设置和 Codex 终端输出；haohaomin 项目 README 明确写 Windows 宿主尚未验收，因此不应把其 macOS 验证记录当成 Windows 兼容承诺。

macOS：终端 PATH 与应用环境差异

导入：在 Zotero 的插件管理页安装 Release 中的 XPI。
开启：终端执行 which codex、codex --version 和 codex login status；侧边栏找不到时，把终端返回的绝对路径填入设置。
验证：先测试条目搜索，再测试 PDF 选中文本或全文索引。日志入口包括终端输出、侧边栏设置、Zotero 插件状态；如果只在终端可运行而 Zotero 内找不到，优先检查应用没有继承相同 PATH，改用绝对路径。

Linux：先验证 CLI，再验证 Zotero 插件

导入：按项目说明安装 XPI；若使用 Zotero skill，则确认插件根目录和 Python 3 可执行。
开启：执行 which codex、codex --version、codex login status；skill 方案执行 status --json。
验证：先搜索已知条目，再导出 references.bib，最后读取一个已有全文索引的附件。日志入口为终端输出、Codex 配置和 Zotero 插件页。本文不补充研究资料未明确给出的 Linux 专用安装包命令。

实际论文工作流：从搜索到引用，不直接改主文件

下面用一篇你已保存到本地 Zotero 的论文作为示例。为了降低误写风险，先使用副本文件和只读请求；标题、作者和年份仅作为你自己的本地条目，不代表本文核验了某篇论文的内容。

搜索：提示“搜索标题或摘要中包含 transformer 的条目，只返回标题、作者、年份和 item key”。
确认：从结果中选定一个 item key，要求返回集合、标签和附件数量，避免选到同名条目。
读取：提示“读取该条目已索引全文的前1000个字符，并说明是否存在附件和全文索引”。若是扫描 PDF，优先使用支持页面图像的 MCP 方案；haohaomin README 明确说明扫描件没有独立 OCR 引擎。
整理：提示“根据全文中方法、数据集和主要结论生成三列表格，并在每项后标出对应页码或原文位置”。模型无法定位时，应回到 PDF 页面验证。
导出：skill 方案可使用 export-bibtex 导出新的 references.bib，不要覆盖正在写作的主文件。
插入：复制一份 paper.tex 或 paper.md，再让 skill 使用 citation key 插入引用；完成后人工检查引用键、作者年份和 BibTeX 字段。
写入：只有确认目标笔记、集合或文件后，才执行导入、创建笔记或编辑笔记。haohaomin 项目明确提供笔记编辑和同步工具，但写入结果仍应通过 Zotero 界面和版本记录复核。

搜索：找到我本地库中与 transformer 相关的条目，只返回标题、作者、年份、item key。
读取：对 item key 为 ABC123 的条目，确认附件并读取已索引全文前 1000 个字符。
导出：把该条目导出到新的 references.bib，不修改 Zotero 文库。
引用：在 paper-copy.tex 的 <cite> 标记处插入该条目的 citation key，并同步副本 references.bib。
复核：列出刚才执行过的写入动作、目标文件和是否成功。

OpenAI skill 原文明确把搜索、库存、集合、标签、BibTeX 导出和引用插入列为常见工作流，并要求把导入和连接器保存视为明确写操作；因此“先只读、后写入”比直接让模型整理整个文库更稳妥。

隐私、凭据与网络：分别判断本地和远程边界

“本地 API”不等于“所有内容都不会离开本机”。当你发送论文标题、摘要、PDF 选中文本、全文、笔记或附件路径时，相关内容可能进入你所使用的 AI 客户端上下文，具体取决于实现、权限和模型服务。

OpenAI plugins 仓库中的 Zotero skill：skill 文件说明它从 Codex 操作本地 Zotero Desktop，并按请求读取全文或附件；文件没有在该处声明统一的凭据存储策略，不能自行推断。
RTLiang 侧边栏：README 自述默认使用现有 Codex 登录；独立存储目录会包含登录凭据和会话数据，应保持目录私有，不放入云同步。Windows PowerShell 设置 CODEX_HOME 后再登录。
haohaomin MCP：README 明确写选中的论文或笔记内容会作为上下文交给 AI 客户端，并提供笔记编辑、PDF 读取和同步能力；因此写入前必须确认权限和目标。

实际排查时，把“登录失败、运行组件下载失败、Zotero API 未开启、PDF 无全文索引”分成四段。先查看项目界面和日志，再记录访问时间、操作系统、版本、网络类型、错误原文和重试结果。只有在本地进程和插件状态正常、其他网络访问正常，而目标下载或登录持续失败时，才继续检查 DNS、代理、MTU 或连接路径。

连接失败决策表：先判断是哪一段断了

现象	先查什么	处理与验证
找不到 Codex	CLI 是否安装、PATH、侧边栏可执行文件路径	运行 `codex --version` 和 `codex login status`；在插件设置中填写绝对路径，重新启动 Zotero。
skill 报本地 API 未就绪	Zotero 是否运行、状态命令输出	对 Zotero skill 执行 `status --json`；确有需要时再执行 `enable --restart`，然后重新搜索。
XPI 安装后没有入口	XPI 是否来自对应项目 Release、插件是否启用、Zotero 是否重启	删除错误项目的 XPI，重新核对来源和版本；不要混装两个同名项目。
能搜索条目但读不到全文	附件是否存在、全文是否已索引、是否选错附件	先读元数据；扫描件可能只有图像。haohaomin 项目可按页读取图像，但 README 明确没有独立 OCR 引擎。
MCP 连接按钮失败	运行组件下载、网络、Codex 配置和 Zotero 是否保持打开	查看“设置 → Zotero MCP”状态，重试组件准备；升级后重启 Codex，再发送连接状态检查。
笔记写入失败或内容不一致	revision、编辑器状态、目标笔记和同步冲突	重新读取最新笔记，确认目标后再提交；不要在超时后更换请求标识盲目重复写入。

建议保存一份测试记录：日期、系统、Zotero 版本、Codex 客户端、项目仓库和版本、网络类型、操作、错误原文、重试次数和结果。这样才能区分客户端问题、网络问题与 PDF 索引问题。

常见问题：版本和功能边界怎么判断

Zotero Codex 是官方软件吗？

不能把它当作唯一官方软件名称。本文核对到的是 OpenAI plugins 仓库中的 Zotero skill，以及 RTLiang、haohaomin 两个不同项目。haohaomin README 明确声明项目为社区开发；其他项目也应以各自仓库、Release 和许可证为准。

三种实现可以同时安装吗？

不建议为了测试而同时安装。它们可能使用不同的 XPI、Codex 配置、本地 API 或 MCP 连接。先选择一个实现，完成只读验证，再决定是否需要另一种能力。

RTLiang 侧边栏支持哪些 Zotero 版本？

其 README 明确写 Zotero 10.0.x，manifest 限制为 10.0.*。不要把这个版本要求推广到 OpenAI plugins 仓库中的 Zotero skill 或 haohaomin 项目。

haohaomin 项目在 Windows 上可以直接使用吗？

项目 README 的当前边界写明真实鼠标拖拽及 Windows 宿主还未验收。因此不能把它写成已确认的 Windows 兼容方案；若在 Windows 试用，应先使用隔离文库，只做搜索和读取验证。

凭据会保存在哪里？

RTLiang README 说明独立 Codex 存储目录会包含登录凭据和会话数据，并建议保持私有、不要放入云同步。其他项目的具体凭据保存方式不能据此推断，应查看对应项目说明和 Codex 客户端设置。

扫描版 PDF 能不能直接让 Codex 总结？

不能一概而论。已有文字层且完成索引的 PDF 更适合全文读取；haohaomin 项目自述可读取 PDF 页面图像，但没有独立 OCR 引擎。先验证一页，再决定是否需要外部 OCR 或人工录入。

连接失败应该先改 DNS 还是重装插件？

先查项目是否选对、Zotero 是否运行、本地 API 是否就绪、Codex 是否登录、XPI 是否匹配。只有这些本地检查通过且目标下载或登录仍持续失败时，才记录 DNS、代理、MTU 和路径信息。

怎样算安装成功？

至少完成三项低风险验证：搜索一个已知条目、导出一个新的 BibTeX 文件、读取一段已索引全文。三项都成功后，再测试引用插入或笔记写入。

常见问题

Zotero Codex 是官方软件吗？

不能把它当作唯一官方软件名称。当前核对到的是一个 OpenAI plugins 仓库 skill 和两个不同社区项目，安装前应查看具体仓库、Release、许可证与兼容性说明。

三种 Zotero Codex 实现可以混装吗？

不建议。XPI、命令、Codex 配置和 MCP 连接可能不同。先选一个实现完成搜索、导出和全文读取验证，再评估是否需要另一种能力。

RTLiang 项目支持什么 Zotero 版本？

其 README 明确写 Zotero 10.0.x，manifest 限制为 10.0.*。这一要求不能直接推广到其他 Zotero skill 或 MCP 项目。

haohaomin 项目能否确认支持 Windows？

不能确认。项目当前边界明确写真实鼠标拖拽及 Windows 宿主还未验收，Windows 用户应先用隔离文库做只读验证。

Codex 登录凭据保存在哪里？

RTLiang README 说明独立 Codex 存储目录会包含登录凭据和会话数据，应保持私有并避免云同步。其他项目的凭据策略需分别核对，不能混用结论。

扫描版 PDF 可以直接读取吗？

不能一概而论。全文索引适合文字层 PDF；haohaomin 项目可按页读取图像，但没有独立 OCR 引擎。先验证单页，再决定是否增加 OCR 流程。

连接失败先改 DNS 还是重装插件？

先检查项目来源、Zotero 运行状态、本地 API、Codex 登录和 XPI 版本。以上均正常且目标下载或登录仍失败时，再检查 DNS、代理、MTU 和连接路径。

怎么判断连接成功？

完成搜索一个已知条目、导出新的 BibTeX、读取一段已索引全文三项低风险测试，再测试引用插入或笔记写入。

Zotero Codex怎么用：3种实现、安装连接与全文排查

先选对实现：搜索、侧边栏和 MCP 不是一回事

安装前检查：版本、客户端和本地 API

三条安装路径：只照对应项目的步骤操作

路径一：OpenAI plugins 仓库中的 Zotero skill

路径二：RTLiang Zotero 侧边栏插件

路径三：haohaomin Zotero Codex MCP

按平台完成导入、开启、验证三步

Windows：PowerShell、绝对路径和宿主限制

macOS：终端 PATH 与应用环境差异

Linux：先验证 CLI，再验证 Zotero 插件

实际论文工作流：从搜索到引用，不直接改主文件

隐私、凭据与网络：分别判断本地和远程边界

连接失败决策表：先判断是哪一段断了

常见问题：版本和功能边界怎么判断

Zotero Codex 是官方软件吗？

三种实现可以同时安装吗？

RTLiang 侧边栏支持哪些 Zotero 版本？

haohaomin 项目在 Windows 上可以直接使用吗？

凭据会保存在哪里？

扫描版 PDF 能不能直接让 Codex 总结？

连接失败应该先改 DNS 还是重装插件？

怎样算安装成功？

常见问题

Zotero Codex 是官方软件吗？

三种 Zotero Codex 实现可以混装吗？

RTLiang 项目支持什么 Zotero 版本？

haohaomin 项目能否确认支持 Windows？

Codex 登录凭据保存在哪里？

扫描版 PDF 可以直接读取吗？

连接失败先改 DNS 还是重装插件？

怎么判断连接成功？

相关阅读

参考资料