Plugin 连线与工具不可用排错

返回 Codex 教学总目录

目标与准备

本段提到的教学与资源: Plugins 安装与连线

步骤 1：先保留失败现场

先记下日期、作业系统、入口、版本、插件完整名称、来源分类、登入方式，以及哪一步失败。Windows、macOS、Linux 都用相同纪录格式；CLI 版本在终端机查，桌面版在程式资讯或更新画面查。不要用桌面版可用推定同台电脑的 CLI 也已安装；远端主机与本机也各自记录。版本栏填实际结果，不能直接抄本篇查证日。

codex --version

# Plugin incident
Date and time zone:
OS / surface / version:
Local or remote host:
Plugin name and source:
Sign-in method (no secrets):
Failing step:
Exact error (redacted):
Practice document revision:
Change attempted:
Retest result:

保存可公开的错误文字，将 email、文件网址中的私人识别码、token 与 cookie 遮蔽。完整验证网址可能含一次性登入码，不要贴进教材或求助纪录。保留错误类型、发生时间和重现步骤通常已足够；若需要服务端纪录，依服务自己的支援流程提供。一次只改一个条件，否则成功后无法知道是换帐号、重开任务还是修改权限生效。

步骤 2：用症状选择检查层

这是排查顺序，不是错误码的保证对照。401 常与认证相关、403 常与拒绝存取相关，但实际含义仍看服务回应；文件不存在、无权限或分享设定改变也可能被服务隐藏成相似讯息。遇到 429 或暂时不可用，记录回应中的等待资讯，稍后以同一份小文件重试，避免持续重送大量请求。不要为了让读取通过而把整个云端硬碟改成公开。

步骤 3：确认入口、安装与启用

桌面版开 Plugins，查看 Installed 与插件详情；CLI 先启动 codex，再输入 /plugins，确认目前 marketplace 和安装项目，已安装插件可用 Space 切换启用状态。安装或重新启用后建立新任务再测，旧任务可能保留先前能力清单。请先保存旧任务结果，不必删除它，也不要清空整个 Codex 设定资料夹。

/plugins

IDE 扩充套件不支援 Plugins，不能把看不到选单当成安装坏掉；请到桌面版或 CLI 测试。iOS、Android 的 Chat／Work 只能用该入口可提供的插件，Desktop only 不可在手机执行。Linux 桌面预览与个别插件也可能有额外条件。将这种结果记成「目前入口不支援」，不要反复重装。平台差异可回到跨装置操作。

步骤 4：分开验证帐号与文件存取

用与插件相同的外部帐号，在服务自己的网站打开练习文件，核对文件标题与 Revision。能在另一个已登入的浏览器帐号看到文件，不代表插件使用的帐号也有权限。若帐号不符，从插件或连线管理提供的重新连线流程修正，再开新任务读取同一网址。若只有这份文件无权限，先向文件拥有人确认分享对象，自己的练习文件只授权必要帐号即可。

ChatGPT 订阅登入与 OpenAI API key 登入不同；某些需要 OAuth 的插件在 API key 模式不可用。看到这项限制时查插件详情与帐号篇，不要把服务的密码放进 config.toml，也不要切换全面放行来处理 OAuth 问题。主机沙盒控制本机工作范围，外部服务的文件权限由该服务管理，放宽其中一层无法保证另一层通过。

步骤 5：以实际工具结果重测

Use the selected plugin to read my practice document at <PRACTICE_DOCUMENT_URL>.
Return its title, source link, Revision, Document marker and task counts.
Use a fresh tool result. If access fails, report the tool error and stop.
Do not edit, share, move or delete anything. Do not infer missing contents.

先把尖括号预留值换成你那份练习文件的网址，再在支援的选择器指定插件或能力。检查任务的工具活动，而不只看回复说「我已读取」。结果应包含文件标题、来源、当前 Revision、Document marker 和各项数量，与服务原始文件逐项比对。若没有工具活动，先确认能力是否已带入；若工具回传拒绝，保留原错误，不能让模型凭旧对话补答案。

接著在服务原站手动把教材 Revision 改成新的值，并同步修改一个可核对的数量；不要把新数量告诉 Codex。再以同一提示词开新任务，确认结果是否更新。若仍回传旧内容，检查网址是否指向副本、服务保存是否完成、工具是否提供重新读取方式，并记录延迟。不能仅因第二次答案正确，就声称所有文件与所有入口都已修复。

判读练习：相同「读不到」的三种原因

A 先改在桌面版或 CLI 的新任务核对，因为 IDE 不支援 Plugins；还不能宣称连线成功。B 先核对目标网址、帐号及文件分享对象，自己有权限时才修正练习文件的存取；重新安装不会替帐号取得文件权限。C 先比较工具来源与指定网址，再记录重新读取的时间与版本；没有依据就不能直接判定是模型记忆或快取。每例修正后都要回到同一份文件重测，不把整个帐号改成公开。

若三例都只有代理自然语言说「成功」，没有可核对的工具结果，最后一栏统一保留「实际读取未确认」。反过来，工具已清楚回报拒绝时，应记「已呼叫但失败」，不能写「工具未载入」。用这两句话校正事故纪录，就能把下一步交给正确的入口或服务维护者。

常见问题与恢复方式

找不到移除按钮时，先看是否为工作区安装或预设插件；这类项目可能由管理员控制，记录限制即可。卸载插件只移除该环境的套件，独立连接的 MCP 可能仍存在。若要结束练习，分别确认 Installed 状态与连线管理中的外部服务，再视需要撤销自己练习帐号的授权。不要删除别人依赖的共用连线，或把解除一次连线当成所有装置都已停用。

恢复时回到事故纪录，还原自己变更的单一条件：重新启用暂停的插件、接回原本应使用的练习帐号，或恢复教材权限。若重连后新任务仍不能读同一文件，整理「入口、插件来源、遮蔽后错误、已试一步、预期与实际」交给维护者；不要无限重装。需要分析伺服器设定时接续 MCP 排除问题，不要混用插件目录与自建伺服器设定档。

验收与下一步

完成标准是一份可重现的纪录：原始失败、定位的层、一次修改、同文件的新工具结果、原文件未被工具写入，以及练习连线保留或撤销的状态。未能取得工具结果时，结论应写「已定位入口限制」或「等待服务认证」，不填成功。本篇操作流程依官方文件查证，没有宣称在你的帐号安装、OAuth 或实体手机上实测；本机文章呈现测试也不是插件连线证据。

将这份纪录与 Skills 验收 分开保存：技能有被载入，不代表其背后服务已连线。常用报告栏位可收进范本与速查表，下次只更新实际观察值，保留不能重现的项目与日期。

返回 Codex 教学总目录

阅读完整文字说明

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI 工具
• 教程
• Codex