실제 응답부터 확인하기
Windows, macOS, Linux의 rdp-cli 0.1.0 RDP 인터페이스를 대상으로 합니다. 2026년 9월의 기존 연결 및 Agent 검증 기록을 바탕으로 하며 이번에 서버를 새로 시험한 결과가 아닙니다. 허가된 Windows RDP 서버와 해당 플랫폼의 현재 배포판을 사용하세요. 예제는 PATH의 rdp-cli를 사용합니다. Windows는 EXE 폴더에서 .\rdp-cli.exe로, Linux는 설치한 명령이나 다운로드한 실행 파일로 바꾸세요.
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는 새로 허가된 연결이 필요하며 반복 재연결로 복구할 수 없습니다.
증거와 함께 다음 단계로
해결되지 않으면 클라이언트/서버 버전, 프로토콜, 시간, 오류 코드와 민감 정보를 제거한 상태/스크린샷을 제공하세요. 암호, 접근 토큰, 사적인 화면 정보는 빼야 합니다. 모든 서버의 호환성이나 장기 안정성을 보장하는 안내가 아닙니다.