> ## Documentation Index > Fetch the complete documentation index at: https://vibex.peatboy.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 故障排查 > 按錯誤碼、Agent、檔案、終端機和遠端連線定位常見問題。 先確認權威執行階段仍在執行、當前專案和工作區正確，再去看結構化錯誤碼和最近一條時間線事件。**不要把完整日誌直接發到公開 Issue**，見文末的脫敏清單。 ## 常見錯誤碼 Vibex 的失敗以結構化錯誤碼返回，介面會顯示 `錯誤碼: 說明`。常見錯誤碼如下： ### 遠端與配對 | 錯誤碼 | 含義 | 處理 | | - | - | - | | `remote_pairing_code_invalid` | 配對碼錯誤、已使用或不存在。 | 在權威端重新生成配對碼。 | | `remote_pairing_code_expired` | 配對碼已過期（預設 5 分鐘）。 | 重新生成，注意儘快使用。 | | `remote_pairing_link_invalid` | 連線串格式錯誤，或其中的地址不是允許的區域網地址。 | 使用權威端列印的完整連線串，不要手工拼裝。 | | `device_revoked` | 該裝置已被撤銷。 | 重新配對。 | | `resync_required` | 客戶端檢測到序號或游標缺口。 | 等待權威端重新同步，不要重複傳送有副作用的命令。 | | `server_shutdown` | 權威執行階段正在關閉。 | 重啟執行階段後重連。 | ### 會話與工作區 | 錯誤碼 | 含義 | 處理 | | - | - | - | | `remote_agent_workspace_root_missing` | 會話請求的工作區目錄在權威端不存在。 | 確認目錄已掛載且位於 `VIBEX_WORKSPACE_ROOTS` 之內。 | | `remote_agent_workspace_mode_mismatch` | 請求的工作區模式與權威端記錄不一致。 | 在權威端重新選擇工作區。 | | `permission_denied` | 當前裝置權限級別不足。 | 用更高權限級別重新配對，或改在權威端操作。 | ### 檔案與 Git | 錯誤碼 | 含義 | 處理 | | - | - | - | | `file_external_revision_changed` | 儲存時檔案已被外部程序修改。 | 重新載入檔案後再決定如何合併。 | | `office_legacy_format_unsupported` | 該 Office 格式（`doc` / `xls` / `ppt`）無法渲染。 | 用系統預設應用開啟，或先轉換為 `docx` / `xlsx` / `pptx`。 | ### 配置與釋出 | 錯誤碼 | 含義 | 處理 | | - | - | - | | `provider_native_import_source_missing` | 找不到要匯入的原生配置來源。 | 確認對應 Agent 的配置檔案存在。 | | `release_channel_override_rejected` | 試圖在執行階段切換髮布通道。 | 通道由安裝包決定，請安裝對應通道的版本。 | 如果你的問題不在表裡，請在 Issue 裡附上**完整的錯誤碼字串**——它是定位問題的關鍵。 ## Agent 無法啟動或不可用 1. 開啟 **配置中心 → Agent**，確認該 Agent 的狀態不是 **已停用**。 2. 狀態為 **未安裝** 時點選 **安裝**；狀態為 **由使用者管理** 時，確認對應的命令列程式在 `PATH` 上且可執行。 3. 展開 **原生憑證**，檢查登入狀態；必要時 **重新認證**。 4. 展開 **模型供應商設定**，確認已配置模型並用 **測試連線** 驗證連通性。 5. 在終端機裡直接執行該 Agent 的版本檢查命令，確認 `PATH` 和權限沒有問題。 ## 訊息卡住或狀態不正確 * 檢視時間線是否停在 permission request 或 elicitation，等待你處理。 * 確認沒有另一個執行正在佔用同一個工作區。 * 應用剛重啟時，等待持久化狀態載入完成。 * 會話顯示 `running` 但實際沒有程序時，重啟一次權威執行階段讓它重新探測狀態。 > [!WARNING] > > `running` 只是上次觀察到的狀態，不代表程序仍然存活。不要據此重複傳送有副作用的命令。 ## 檔案或 Git 結果不對 * 確認當前**專案**和**工作區**。`Local` 和 `Worktree` 是兩個不同的目錄，改錯地方很常見。 * 儲存編輯器檔案後再重新整理檔案樹和 Git status。 * 檢查是否存在外部修改或合併衝突。 * 執行 revert、amend、push 或刪除 worktree 之前，先閱讀 diff 並建立恢復點。 ## 終端機沒有輸出 檢查標籤是否繫結到正確的工作區、PTY 是否被標記為 `stale`，以及 shell 是否已退出。調整面板尺寸或重新開啟標籤，以新的終端機快照為準。 Vibex 的終端機滾動緩衝區固定為 10000 行，更早的輸出已經丟棄，需要時請重新執行命令。 ## 預覽打不開 | 現象 | 說明 | | - | - | | 顯示 **不支援的檔案** | 該格式不支援預覽：`.bmp`、`.odt`、`.odp`，以及超過 8 MiB 或 5 萬行的檔案。 | | Office 檔案報錯 | 只有 `docx`、`xlsx`、`ods`、`pptx` 能渲染；`doc` / `xls` / `ppt` 需要先轉換。 | | 音訊或影片 | 不會內嵌播放，會交給系統預設應用。 | | HTML / JSON / YAML | 以帶高亮的源文本開啟，不會渲染或格式化。 | | PDF 缺少某張依賴 | 重新安裝 Vibex，或使用 **Open in system**。 | ## 桌面端無法連線到自託管執行階段 1. 在伺服器上確認 `curl -fsS http://127.0.0.1:8765/api/v2/info` 有響應。 2. 確認 `VIBEX_PUBLIC_HOST` 是**客戶端實際能撥到的地址**，並帶上埠。 3. 區域網模式必須使用 `VIBEX_TLS_MODE=pinned_certificate`，並從**連線串**配對（連線串裡帶證書）；手工填地址會因缺少證書而失敗。 4. 公網模式確認 `VIBEX_ALLOWED_HOSTS` 包含實際訪問的域名，否則閘道器返回 `421`。 5. 檢查伺服器日誌裡的 `tls_fingerprint`，與客戶端顯示的 **證書** 行比對。 ## 手機無法連線 1. 確認權威執行階段正在執行，並且已經啟用了一種連線方式（**Tailscale Serve** / **Direct HTTPS** / **Self-hosted Relay** / **區域網配對**）。 2. 檢查手機和權威端的網路；Direct 失敗時改試 Tailnet 或 Relay。 3. 重新生成二維碼或連線串，不要複用舊的配對憑據。 4. 顯示 `revoked` 時必須重新配對；顯示 `resync_required` 時等待權威端同步完成。 5. 使用 Relay 時檢查 `/health` 和 `/api/info`——注意 Relay 上**沒有** `/api/v2/info`。 ## TUI 無法啟動或附著 | 現象 | 常見原因 | 處理 | | - | - | - | | `home is locked` | 桌面端持有同一個 home，且沒有允許 TUI 接入。 | 在桌面端開啟 **設定 → 常規 → Vibex TUI**，退出桌面端，或 `vibex connect` 到另一個執行階段。 | | 啟動後立即退出 | home 路徑的通道與執行階段 flavor 不匹配。 | 用 `vibex status` 檢視 home、flavor 和端點；必要時用 `--home` 指向正確的目錄。 | | 中文或圖示顯示為方塊 | 終端機字型缺少 CJK 或 Nerd Font 字形。 | 換字型；TUI 會為部分圖示提供 ASCII 回退。 | | 複製不到剪貼簿 | 終端機不支援 OSC 52。 | 在 SSH/tmux 裡開啟剪貼簿轉發；必要時用桌面端複製。 | | 遠端模式不能引導 | 遠端模式沒有原生 steering。 | 用 `Ctrl+C` 打斷後重新發送。 | ## 瀏覽器打不開或操作失敗 | 現象 | 常見原因 | 處理 | | - | - | - | | 提示找不到瀏覽器 | 沒有安裝 Chrome、Chromium 或 Edge。 | 安裝一個受支援的瀏覽器，重新打開面板。 | | 頁面能開啟但 Agent 看不到元素 | 頁面沒有可訪問性樹，或元素在跨源 iframe 裡。 | 讓 Agent 重新觀察；必要時用截圖或提取文本。 | | 元素引用過期 | 頁面重新渲染、導航或再次觀察。 | 讓 Agent 重新觀察後再操作。 | | 導航被拒絕 | 目標地址觸發了跨源或本機地址核准。 | 在面板裡確認導航；不要繞過核准。 | | 下載沒有開始 | **允許下載** 關閉，或頁面觸發了被攔截的儲存對話方塊。 | 在 **設定 → 瀏覽器** 開啟下載；檢視面板裡的阻止提示。 | | 登入狀態沒有匯入 | 源瀏覽器正在執行，或配置不可讀。 | 退出源瀏覽器後重試；匯入只讀取，不寫回。 | ## 電腦操作不可用 | 現象 | 常見原因 | 處理 | | - | - | - | | 開關不可用 | 驅動未安裝。 | 在 **設定 → 電腦操作** 安裝驅動，再檢查系統權限。 | | 提示缺少輔助功能或螢幕錄製 | 作業系統沒有授權。 | 到系統設定裡授權，必要時重啟應用或系統。 | | 操作顯示“未驗證” | 引擎已派發但無法確認效果。 | 讓 Agent 重新觀察，不要假定成功。 | | Wayland 下只看到 X11 視窗 | 實驗路徑未開啟。 | 設定 `CUA_DRIVER_RS_ENABLE_WAYLAND=1` 後重啟執行階段；部分合成器仍不支援後臺輸入。 | | 遠端執行階段沒有面板 | 電腦操作只在本機執行階段可用。 | 在執行階段的宿主機上操作，或改用終端機/瀏覽器工具。 | ## SSH / WSL 配置失敗 先看診斷卡上的錯誤碼，再看執行階段日誌。常見原因： * **主機金鑰未知或變更**：先在終端機裡 `ssh ` 核對指紋；變更時不要盲目刪除 `known_hosts`。 * **認證失敗**：確認非互動登入可用，ssh-agent 已載入正確的 Key。 * **glibc 太舊**：需要 glibc 2.35+；Alpine 等 musl 主機不能執行。 * **埠被佔用**：釋放埠或重試，Vibex 會嘗試下一個空閒埠。 * **隧道失敗**：通常是本地埠被佔用或 SSH 斷開；重試或換一個本地埠。 * **升級失敗**：已回滾到 `previous`；檢視新版本日誌，確認通道和版本相容。 完整錯誤碼和支援矩陣見 [SSH 與 WSL 遠端執行階段](https://vibex.peatboy.com/docs/zh-TW/ssh-runtime.md#故障排查)。 ## 供應商、路由組與閘道器 | 現象 | 常見原因 | 處理 | | - | - | - | | 模型選擇器裡沒有共享 Provider | Provider 被設為“僅通過路由組使用”，或 Agent 沒有繫結它。 | 編輯 Provider 或 Agent 的繫結。 | | 路由組沒有可用 Key | 成員 Provider 的 Key 未啟用、冷卻中或失效。 | 到閘道器 → Key 檢查狀態；測試單把 Key。 | | 閘道器顯示不可用 | 埠繫結失敗或服務已停止。 | 檢查端口占用；關閉再開啟閘道器；直接 Provider 不受影響。 | | 請求總是落到同一個成員 | 策略是手動/按順序，或開啟了固定對話成員。 | 調整策略或關閉固定。 | | 首 Token 很慢 | 首 Token 超時或成員本身慢。 | 檢視請求臺賬的 p50/p95；調整超時和耐心等待。 | | 協議錯誤或工具呼叫失敗 | 模型的介面協議宣告不正確。 | 在模型設定裡改為繼承或指定正確協議；用測試連線驗證。 | ## 市場安裝失敗 | 現象 | 常見原因 | 處理 | | - | - | - | | 搜尋沒有結果 | 上游目錄不可達，或查詢過窄。 | 清空搜尋、重試；檢查網路。 | | 安裝按鈕不可用 | 條目已被撤下，或當前執行階段沒有市場能力。 | 重新載入；換一個條目或手動匯入。 | | Skill 安裝被拒絕 | 文件過大、檔案清單不合法，或目標 Agent 不接受。 | 閱讀安裝預覽裡的原因；縮小 Skill 或換 Agent。 | | 安裝後 Agent 沒有載入 | 沒有在 **Agent 啟用範圍** 裡開啟。 | 開啟對應 Agent 的開關，重啟會話。 | ## 提交診斷資訊 請提供： * Vibex 版本與釋出通道（在 **設定 → 關於** 檢視） * 作業系統與版本 * 復現步驟 * **結構化錯誤碼**（最關鍵） * 脫敏後的時間戳 提交前請移除：token、私鑰、配對碼、連線串、工作區路徑、提示詞、檔案內容、Git diff 和終端機輸出。 Issue 入口：[GitHub Issues](https://github.com/vibex-ai/vibex/issues)。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.