疑難排解

不支援 RSA 金鑰

Tessera 無法產生或輸入 RSA 金鑰：目前的 SSH 堆疊只能提供已棄用的 RSA/SHA-1 簽章。請改為產生 Ed25519 金鑰 —— 每一台現代 OpenSSH 伺服器都接受它。從舊版本留下的 RSA 金鑰會顯示為已停用。

mosh 連不上

伺服器上安裝了 mosh-server 嗎？
UDP 能到達伺服器嗎？有些防火牆和大多數 NAT 會阻擋它；mosh 預設需要 UDP 連接埠 60000–61000。
透過跳板主機時：mosh 的 UDP 無法穿過堡壘機。 Tessera 會提出警告（「經跳板鏈無法存取 mosh…」）並回退到 SSH。

轉發拒絕某個本機連接埠

iOS 沙箱無法綁定 1024 以下的連接埠 —— 請選擇較高的本機連接埠。同一台主機內的本機連接埠也不能重複。詳見連接埠轉發。

mosh 主機上的轉發已停用

當傳輸方式為 mosh 且啟動模式為自訂時，沒有可承載轉發的 SSH 連線。請把啟動模式改為 自動 tmux 或 具名 tmux —— 這兩種模式會保留一條 SSH 側通道，轉發可以搭載其上。

連線停在「正在連線」或「正在啟動 tmux」

等十二秒：啟動覆蓋層會指出它卡住的階段，並提供 編輯主機、重試和返回 —— 不再有無止盡的轉圈。如果問題出在 tmux 本身（未安裝、無法啟動，或主機的 dotfiles 在登入時已經啟動 tmux），Tessera 會退到純 shell 並附上說明原因的橫幅。而如果工作階段接入後畫面一直空白，橫幅會顯示「按任意鍵將其喚醒」 —— 照做即可。詳見連線卡住時。

tmux 沒有套用我的更改

環境變數和啟動指令片段只在 tmux 工作階段啟動時執行。請在伺服器上結束該工作階段（tmux kill-session）後重新連線。

檔案面板說主機金鑰不受信任

檔案橋接是一條獨立的 SSH 連線，套用同樣的信任規則。請對該主機開啟一個終端機工作階段，檢視「未知主機」面板並接受金鑰 —— 然後重新開啟面板。

檔案面板沒有跟隨我的 shell

跟隨目錄需要你的 shell 送出 OSC 7。請使用面板上的 啟用跟隨 —— 安裝 shell 整合 按鈕，然後執行 exec $SHELL 或重新連線。細節見檔案。

連到 WSL 主機的工作階段在輸出中途凍結

連線本身沒問題，但大量湧出的輸出始終沒有到達 —— 這是 WSL2 虛擬介面卡上的 MTU 不相符，吞掉了每一個大封包。詳見 WSL MTU 卡住。

本機網路連線失敗

iOS 把區域網路的存取鎖在 本機網路 權限之後。如果你曾拒絕它，請到「設定」App 中 Tessera 的項目下重新啟用。同一項權限也讓鄰近設定能找到你的另一台裝置。

鄰近設定找不到裝置

兩台裝置都必須讓 Tessera 停留在設定畫面、位於前景、連在同一個網路上，且兩邊都已授予本機網路權限。版本不相符會以明確的「請先更新…上的 Tessera」訊息中止。詳見鄰近設定。

接續互通沒有出現在另一台裝置上

接續互通是 Apple 的底層機制：兩台裝置需使用同一 Apple 帳戶、開啟藍牙和 Wi-Fi，並在 iOS「設定」App 中啟用「接續互通」。鎖定的裝置會刻意停止廣播。共用 tmux 工作階段的取回控制權還需要伺服器上有 tmux 3.2+。詳見接續互通。

智慧體卡片顯示「狀態無法使用」

探索已找到該智慧體，但精確狀態需要各主機上的狀態掛鉤 —— 可從卡片上安裝或更新它。在 Codex 上，首次整合啟動時可能還會要求你透過 /hooks 信任該掛鉤。詳見智慧體中心。

收不到通知

請檢查 iOS 通知權限（響鈴設定面板有直接連過去的入口）。請記得背景送達是盡力而為：iOS 可能會暫停長時間的背景工作階段。詳見通知。

購買沒有帶過來

設定 → 無限主機 → 回復購買 會重新檢查你的 Apple 帳戶 —— 涵蓋重新安裝、新裝置，以及最初付費購買 App 時已包含的解鎖。詳見免費與無限主機。

其他問題

設定 → 診斷 → 傳送給開發者 會開啟一封已填好收件人的郵件，並附上診斷日誌 —— 在點下傳送之前你可以看到全部內容。（這需要裝置上有郵件帳號；若沒有，請使用 輸出日誌，再從任何郵件 App 傳送該檔案。）或者到 GitHub Issues 提交議題。日誌已去識別化，且只有在你送出時才會離開你的裝置。