rdp-cli

RDP 연결과 검은 화면 및 입력 거부 문제 해결

대상 버전 및 환경: 0.1.2 · Windows / macOS / Linux · RDP

실제 응답부터 확인하기

RDP 연결 문제를 네트워크, 암호화, 인증, 화면, 입력 순서로 확인합니다. 비밀번호를 바꾸거나 재연결을 반복하기 전에 반환된 오류 코드에 맞는 조치를 선택하세요.

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

SESSION을 자신의 연결 결과 ID로 바꿉니다. 실패하면 error.code, error.message, error.retryable을 읽으세요. 상태 응답이 성공하면 data.connection_state, data.control_state, 존재하는 경우 data.last_error, 그리고 data.capabilities를 확인합니다. 재시도 가능 표시는 입력을 다시 보내도 된다는 허가가 아닙니다.

연결 단계별로 점검하기

오류 점검 및 조치
CONNECT_TIMEOUT / RDP_CONNECT_FAILED 호스트, 실제 포트(보통3389), LAN/VPN 경로와 RDP 서비스 실행 여부를 확인합니다. 관리자에게 수신 대기와 허용된 방화벽 규칙을 확인하도록 요청하세요. 포트에 도달해도 RDP 로그인 성공을 뜻하지는 않습니다. 원인을 고친 후 한 번 다시 시도합니다.
RDP_TLS_HANDSHAKE_FAILED 서버 TLS 설정을 확인합니다. 기본 modern은 TLS 1.2가 필요합니다. 신뢰할 수 있는 네트워크의 확인된 구형 서버에만 --tls-profile legacy를 고려하세요. 오래된 암호화를 허용하므로 모든 연결에 적용하거나 시험을 통과하려고 서버 보안을 끄지 마세요.
CERTIFICATE_UNTRUSTED --cert-policy strict에서는 서버 이름과 인증서 체인을 확인합니다. 개별 신뢰 기록을 추가하려면 반환된 SHA-256 지문을 먼저 관리자와 대조하세요. 현재 기본값 ignore는 서버 신원을 검증하지 않습니다. strict 오류를 숨기기 위해 바꾸지 마세요.
AUTH_FAILED 사용자 이름, 로컬/도메인 계정, --domain, 원격 로그인 권한을 확인합니다. 빠른 시작의 숨김 암호 입력이나 저장된 자격 증명을 사용하세요. TLS 실패나 호스트 도달 불가는 암호 오류의 증거가 아니므로 암호를 반복해서 시도하지 마세요.

연결되었지만 화면을 사용할 수 없을 때

아래 읽기 전용 조회를 실행하고 data.path의 PNG를 여세요. connected는 RDP가 활성화되고 일관된 프레임을 받았다는 뜻입니다. 로그인, 환영 또는 검은 화면일 수도 있으며 데스크톱 준비 완료를 보장하지 않습니다.

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에서는 설치한 명령 또는 실제 실행 파일 경로를 사용합니다.

에이전트 연결과 연결 문제 진단

실행 파일에 내장된 MCP 또는 CLI를 사용하세요. 자격 증명 참조를 포함한 연결 프로필을 저장하고 doctor로 연결 계층별 기능을 확인합니다.

이 doctor 예제는 기존 증거만 읽으며 능동적인 검사를 요청하지 않습니다. unknown이나 not-run은 검사 통과를 뜻하지 않습니다. 연결 프로필은 자격 증명 참조를 사용하며 예제에 비밀번호를 쓰지 않습니다.

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

증거와 함께 다음 단계로

해결되지 않으면 클라이언트/서버 버전, 프로토콜, 시간, 오류 코드와 민감 정보를 제거한 상태/스크린샷을 제공하세요. 암호, 접근 토큰, 사적인 화면 정보는 빼야 합니다.

다운로드 · 빠른 시작 · 명령 참고