先讀實際回應

本文適用於 Windows、macOS 和 Linux 上的 rdp-cli 0.1.0 RDP 介面，依據2026年9月既有連線與Agent驗收紀錄整理，並非本輪新測伺服器。請使用獲授權的Windows RDP伺服器與本機對應的目前發行版。範例假設PATH中有 rdp-cli；Windows在程式目錄使用 .\rdp-cli.exe，Linux使用已安裝的命令或下載的執行檔。

rdp-cli --version
rdp-cli list
rdp-cli status --session SESSION

以自己取得的工作階段ID替換 SESSION。失敗時讀取 error.code、error.message、error.retryable；狀態成功時核對 data.connection_state、data.control_state、存在時的 data.last_error 及 data.capabilities。可重試標記不代表可以重送輸入。

依連線階段檢查

錯誤 檢查與處理
CONNECT_TIMEOUT / RDP_CONNECT_FAILED 核對主機、實際連接埠（通常3389）、區域網路/VPN路由及RDP服務。請管理員確認監聽與允許存取的防火牆規則。連接埠可達不等於RDP登入成功；修正原因後再試一次。
RDP_TLS_HANDSHAKE_FAILED 檢查伺服器TLS設定。預設 modern 要求TLS 1.2；只有可信網路中已確認的舊伺服器才視需要使用 --tls-profile legacy，它允許舊加密設定。不要全面套用或為通過測試而關閉伺服器安全設定。
CERTIFICATE_UNTRUSTED 使用 --cert-policy strict 時核對主機名稱與憑證鏈，或先和管理員核驗回傳的SHA-256指紋，再加入精確信任紀錄。目前預設為 ignore，不驗證伺服器身分；不要只為消除strict錯誤而改用ignore。
AUTH_FAILED 核對使用者名稱、本機/網域帳戶、--domain 和遠端登入權限。依快速入門使用密碼提示或既有認證參照，不要反覆猜測密碼：TLS失敗或主機無法連線不代表密碼錯誤。

已連線卻沒有可用畫面

執行下方唯讀查詢並開啟 data.path 指向的PNG。connected 表示通訊協定已啟動並收到一致畫面；仍可能顯示登入頁、歡迎頁或黑畫面，不代表桌面已可用。

rdp-cli screenshot --session SESSION

遇到 FRAME_UNAVAILABLE，先查看狀態與 error.retryable，等重新連線或顯示切換穩定後再截圖。若圖像持續全黑，檢查伺服器、本機睡眠與VPN中斷情況。歷史黑畫面有不同或未確認的原因，不要向看不見的目標輸入認證，也不要把靜止画面一概當成通訊協定凍結。

處理輸入與權限錯誤

  • OBSERVATION_REQUIRED：重新截圖並讀取，以新的 data.observation 執行下一個動作。重新連線、接管或顯示變更後都要更新。
  • SESSION_PAUSED、CONTROL_HELD_BY_HUMAN 或 CONTROL_NOT_OWNED：停止輸入並尊重目前控制者。獲授權交還後才恢復，接著重新截圖；不要另開檢視器繞過暫停。
  • PERMISSION_DENIED / CAPABILITY_UNAVAILABLE：檢查相關能力及存取授權。開啟檢視器無法讓伺服器支援缺少的功能。UNICODE_INPUT_UNAVAILABLE 需要受支援的輸入方式，而非盲目重試。

復原結果不明的操作

對可能需要恢復的輸入，操作前為每個不同動作指定並保存唯一 --request-id，範例請求 ID 應替換為你自己的值。若收到錯誤 JSON，可取頂層 request_id；若回應完全遺失且未保存原 ID，不能事後建立新 ID 查詢舊操作或盲目重送。

操作期間出現 REQUEST_TIMEOUT 或 SERVICE_UNAVAILABLE，請保留原始請求ID。先用 list 檢查本機服務，再查詢原操作後決定是否重試。回應遺失時，輸入可能已送出。

rdp-cli operations status --session SESSION --request-id REQUEST_ID
rdp-cli status --session SESSION
rdp-cli screenshot --session SESSION

以原始值替換 REQUEST_ID，不要用狀態查詢本身的ID。核對 data.state、保留的 data.result 與新截圖。OPERATION_NOT_FOUND 可能表示紀錄過期或服務已更換，不能證明原操作未執行。修正連線原因後，對未關閉工作階段明確執行 reconnect 仍會保持暫停。SESSION_CLOSED 必須建立新的獲授權連線，不能反覆重新連線使其復活。

帶著證據繼續排查

若仍未解決，請提供用戶端與伺服器版本、通訊協定、時間、錯誤碼及去除敏感資訊的狀態/截圖。移除密碼、存取權杖和敏感畫面。本文不代表所有伺服器的相容性或長期穩定性。

下載 · 快速入門 · 命令參考