跳至指南

故障排除

若 onemind 運作不如預期，請先執行 onemind version 確認安裝，然後在下方找到對應項目。

找不到 onemind

  • macOS/Linux：確認 ~/.local/bin 已加入 PATH，然後開啟新終端機。
  • 再次執行安裝程式，以修復執行檔及服務註冊。

瀏覽器授權已過期或被拒絕

按 Escape，再次選擇 登入，然後在瀏覽器中批准新請求。被拒絕或過期的請求無法重複使用。

onemind 無法連接伺服器

執行 onemind session status 查看目前使用的 API 地址。若要更改，請在終端機執行 onemind server https://your-server。僅接受 https:// 地址；純 http:// 僅允許用於本地回環地址。更改伺服器後，先前的憑證會被移除；請執行 onemind 並選擇登入以連接新伺服器。

同步提示未連接本地項目

onemind sync 在沒有活躍綁定時會輸出以下其中一則訊息：

  • 「Sync has not started. Detect an AI tool with 'onemind project TOOL'」 — 執行 onemind project TOOL /path/to/repo 偵測儲存庫，然後完成同步設定將其綁定至普通 Project，再次執行 onemind sync。
  • 「Sync setup is saved, but local access is blocked」 — 路徑已在同步設定中，但程序無法讀取或寫入該目錄。授予所需的檔案系統權限，再次執行 onemind sync。
  • 「Sync setup is saved, but the local target is unavailable」 — 已綁定的路徑不存在，或 AI 工具未在執行。請啟動或修復 AI 工具，視需要還原路徑，再次執行 onemind sync。
  • 「Select this device, target, and Project at …」 — 此裝置或目標尚未在同步設定中啟用。開啟同步設定，為此裝置和目標啟用同步，再次執行 onemind sync。

同步拒絕 AGENTS.md

管理標記損壞或存在歧義時，onemind 會停止。請恢復一對有效標記，執行 onemind mind restore pre-onemind --yes 回到 onemind 接管前的 agent 提示詞，或手動將 .one-mind/AGENTS.md.backup 複製回正在使用的指令檔案；手工編輯時務必保留管理區塊以外的所有內容。

撤銷首次 Mind 同步

首次 Mind 同步之後，恢復的含義是回到 onemind 接管前的狀態——指令檔案中原先的本地 agent 提示詞——而非恢復某個 Matrix Mind 版本。

onemind mind backups --path /目標/路徑
onemind mind restore pre-onemind --path /目標/路徑 --file AGENTS.md --yes

對於全局工具主目錄，將 --path 設為該工具根目錄（例如 ~/.codex 且 --file AGENTS.md，或 ~/.claude 且 --file CLAUDE.md）。直接修改 ~/.codex 或 ~/.claude 是最後手段的恢復步驟；請始終從備份副本開始，並保留管理區塊以外的所有內容。

後台服務未運行

執行 onemind service status。如果失敗，請嘗試 onemind service install，然後再次檢查狀態。在 Linux 上，請確保用戶 systemd 會話和 Secret Service/keyring 可用。

安全憑據存儲不可用

onemind 不會降級使用明文憑據。請啟動或解鎖作業系統的憑據服務，然後重新打開 CLI 並再次登入。

安全存儲中找不到工作階段

若 CLI 報告「OneMind session not found in secure storage」，表示已儲存的憑證已被移除或從未寫入。執行 onemind 並選擇登入以建立新工作階段。

OneMind 版本降級被拒絕

若同步停止並顯示「refusing OneMind version regression from vN to vN」，表示雲端套件包含的管理區塊是由比當前擁有指令檔案的 CLI 版本更舊的版本寫入的。這通常意味著在同步執行後 CLI 被降級了。請使用CLI 快速開始中的官方安裝程式重新安裝當前版本，然後再次執行 onemind sync。

提案失敗

onemind propose 可能會以下列其中一則訊息失敗：

  • 「choose an exact Project target in OneMind before proposing」 — 目前目錄沒有活躍的 Project 綁定。請先執行 onemind project TOOL /path/to/repo 並完成同步設定，再提案。
  • 「proposal is queued locally; exact Project upload is not active」 — 提案已在本地儲存，但由於 Project 綁定未完全啟用，上傳被阻止。請完成同步設定，然後執行 onemind sync 以清空已排隊的提案。

Matrix 面板中的權限請求顯示為已過期

工具請求若未在時限內回應則會過期。若任務詳情面板對某個請求顯示已過期或已取消，表示工具已當作拒絕處理，其執行可能在沒有該操作的情況下繼續。請先查看執行狀態和輸出，再決定是否傳送後續訊息；如工具仍需要權限，會發出新的請求。

同步顯示需要恢復或確認超時

在同步活動中開啟同步詳情，閱讀狀態下方的說明。

需要恢復：同步無法安全確認。前往目標裝置，按照畫面上的恢復步驟操作。裝置必須可連線且已登入。

已回滾：裝置已還原先前的檔案，無需進一步操作，除非仍需要執行該同步。

確認超時：裝置未能在時限內確認結果。請確認目標裝置已上線、已登入且正在執行後台服務，然後在同步詳情中查看其恢復狀態。

Matrix 任務一直等待裝置

指派給原生 AI 工具的任務在已指派工具的裝置尚未認領執行時，會顯示「等待 [裝置] 接取」。若狀態顯示裝置離線，請將任務重新指派給其他裝置或工具以繼續執行。重新指派步驟請參閱Matrix 對話。

任務對話達到限制

當訊息無法傳送時，編輯器工具列會顯示原因：

  • 檔案或情境限制（任務對話）：「此任務對話已達到其檔案或情境限制。」請從目前草稿中移除檔案或縮短訊息。先前的記錄將保留。
  • 情境視窗已滿（onemind 智能體）：「已達 100%，onemind 無法回覆。」開啟新的 onemind 智能體對話以繼續。

詳情請參閱 Matrix 對話 及 onemind 智能體。

Mind 為唯讀

若 Mind 的編輯和提交操作被封鎖，且面板顯示 Mind 變更暫時為唯讀，表示團隊的活躍成員數超過方案的座位限制。當成員被移除使數量降至限制以內、新增座位以涵蓋當前成員數，或升級方案後，寫入權限即會恢復。座位和方案選項請參閱方案與帳單。

付款仍在確認中

完成結帳後，產品會顯示確認中狀態，伺服器正在等待 Paddle 的已驗證確認。此過程通常在幾秒內完成。若確認中狀態持續數分鐘，請重新載入頁面或登出再登入。若方案未啟用，請透過支援聯絡客服。帳單詳情請參閱方案與帳單。