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