rdp-cli

排查 RDP 連線、黑畫面與輸入遭拒問題

適用版本與平台: 0.1.2 · Windows / macOS / Linux · RDP

先讀實際回應

依網路、加密、認證、畫面和輸入的順序排查 RDP 連線問題。根據回傳的錯誤碼選擇處理步驟,避免反覆更改密碼或重新連線。

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 必須建立新的獲授權連線,不能反覆重新連線使其復活。

rdp-cli 的增強命令

先執行 rdp-cli --version。以下增強命令要求回應中的 agent_execution.contract_version 為 1;舊版本仍可使用上文的單步操作。

將大寫預留位置換成實際回傳值。Windows PowerShell 中請在程式目錄使用 .\rdp-cli.exe;macOS、Linux 使用已安裝的命令或執行檔的實際路徑。

接入 Agent,也查清連線問題

同一個檔案提供內建 MCP 和命令列。以具名連線設定檔保存參數與憑證參照,用 doctor 分層檢查連線能力。

此處的 doctor 範例讀取既有證據,不發起主動探測。unknown、not-run 都不代表檢查通過。連線設定檔使用憑證參照,範例不寫入密碼。

rdp-cli profiles list
rdp-cli doctor --session SESSION

帶著證據繼續排查

若仍未解決,請提供用戶端與伺服器版本、通訊協定、時間、錯誤碼及去除敏感資訊的狀態/截圖。移除密碼、存取權杖和敏感畫面。

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