常見錯誤碼
Vibex 的失敗以結構化錯誤碼返回，介面會顯示錯誤碼: 說明。常見錯誤碼如下：
遠端與配對
會話與工作區
檔案與 Git
配置與釋出
如果你的問題不在表裡，請在 Issue 裡附上完整的錯誤碼字串——它是定位問題的關鍵。
Agent 無法啟動或不可用
- 開啟 配置中心 → Agent，確認該 Agent 的狀態不是 已停用。
- 狀態為 未安裝 時點選 安裝；狀態為 由使用者管理 時，確認對應的命令列程式在
PATH上且可執行。 - 展開 原生憑證，檢查登入狀態；必要時 重新認證。
- 展開 模型供應商設定，確認已配置模型並用 測試連線 驗證連通性。
- 在終端機裡直接執行該 Agent 的版本檢查命令，確認
PATH和權限沒有問題。
訊息卡住或狀態不正確
- 檢視時間線是否停在 permission request 或 elicitation，等待你處理。
- 確認沒有另一個執行正在佔用同一個工作區。
- 應用剛重啟時，等待持久化狀態載入完成。
- 會話顯示
running但實際沒有程序時，重啟一次權威執行階段讓它重新探測狀態。
檔案或 Git 結果不對
- 確認當前專案和工作區。
Local和Worktree是兩個不同的目錄，改錯地方很常見。 - 儲存編輯器檔案後再重新整理檔案樹和 Git status。
- 檢查是否存在外部修改或合併衝突。
- 執行 revert、amend、push 或刪除 worktree 之前，先閱讀 diff 並建立恢復點。
終端機沒有輸出
檢查標籤是否繫結到正確的工作區、PTY 是否被標記為stale，以及 shell 是否已退出。調整面板尺寸或重新開啟標籤，以新的終端機快照為準。
Vibex 的終端機滾動緩衝區固定為 10000 行，更早的輸出已經丟棄，需要時請重新執行命令。
預覽打不開
桌面端無法連線到自託管執行階段
- 在伺服器上確認
curl -fsS http://127.0.0.1:8765/api/v2/info有響應。 - 確認
VIBEX_PUBLIC_HOST是客戶端實際能撥到的地址，並帶上埠。 - 區域網模式必須使用
VIBEX_TLS_MODE=pinned_certificate，並從連線串配對（連線串裡帶證書）；手工填地址會因缺少證書而失敗。 - 公網模式確認
VIBEX_ALLOWED_HOSTS包含實際訪問的域名，否則閘道器返回421。 - 檢查伺服器日誌裡的
tls_fingerprint，與客戶端顯示的 證書 行比對。
手機無法連線
- 確認權威執行階段正在執行，並且已經啟用了一種連線方式（Tailscale Serve / Direct HTTPS / Self-hosted Relay / 區域網配對）。
- 檢查手機和權威端的網路；Direct 失敗時改試 Tailnet 或 Relay。
- 重新生成二維碼或連線串，不要複用舊的配對憑據。
- 顯示
revoked時必須重新配對；顯示resync_required時等待權威端同步完成。 - 使用 Relay 時檢查
/health和/api/info——注意 Relay 上沒有/api/v2/info。
TUI 無法啟動或附著
瀏覽器打不開或操作失敗
電腦操作不可用
SSH / WSL 配置失敗
先看診斷卡上的錯誤碼，再看執行階段日誌。常見原因：- 主機金鑰未知或變更：先在終端機裡
ssh <alias>核對指紋；變更時不要盲目刪除known_hosts。 - 認證失敗：確認非互動登入可用，ssh-agent 已載入正確的 Key。
- glibc 太舊：需要 glibc 2.35+；Alpine 等 musl 主機不能執行。
- 埠被佔用：釋放埠或重試，Vibex 會嘗試下一個空閒埠。
- 隧道失敗：通常是本地埠被佔用或 SSH 斷開；重試或換一個本地埠。
- 升級失敗：已回滾到
previous；檢視新版本日誌，確認通道和版本相容。
供應商、路由組與閘道器
市場安裝失敗
提交診斷資訊
請提供：- Vibex 版本與釋出通道（在 設定 → 關於 檢視）
- 作業系統與版本
- 復現步驟
- 結構化錯誤碼（最關鍵）
- 脫敏後的時間戳