rdp-cli

Resolver falhas de conexão RDP, tela preta e entrada bloqueada

Versão e plataforma: 0.1.2 · Windows / macOS / Linux · RDP

Comece pela resposta real

Investigue problemas RDP por etapa: rede, criptografia, autenticação, tela e entrada. Escolha a próxima ação pelo código de erro, em vez de trocar senhas ou reconectar repetidamente.

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

Substitua SESSION pelo seu ID retornado. Em falhas, leia error.code, error.message e error.retryable. Num estado bem-sucedido, examine data.connection_state, data.control_state, data.last_error quando existir e data.capabilities. A indicação de nova tentativa não autoriza repetir entradas.

Verifique as etapas da conexão

Erro Verificação e ação
CONNECT_TIMEOUT / RDP_CONNECT_FAILED Confira host, porta configurada (normalmente 3389), rota LAN/VPN e serviço RDP. Peça ao administrador que confira a escuta e a regra permitida do firewall. Porta acessível não prova um login RDP bem-sucedido. Tente uma vez após corrigir a causa.
RDP_TLS_HANDSHAKE_FAILED Examine o TLS do servidor. O perfil padrão modern exige TLS 1.2. Use --tls-profile legacy apenas em um servidor antigo identificado numa rede confiável, pois permite criptografia antiga. Não aplique a todas as conexões nem desative a segurança do servidor para passar no teste.
CERTIFICATE_UNTRUSTED Com --cert-policy strict, verifique nome e cadeia de certificados ou confira a impressão SHA-256 com o administrador antes de cadastrar uma confiança específica. O padrão atual ignore não verifica a identidade. Não mude apenas para esconder uma falha strict.
AUTH_FAILED Confira usuário, conta local ou de domínio, --domain e direito de login remoto. Use a entrada de senha ou referência salva do guia rápido. Não tente senhas repetidamente: falha TLS e host inacessível não provam senha incorreta.

Conectado, mas sem imagem utilizável

Execute a consulta de leitura e abra o PNG em data.path. connected indica ativação do RDP e recebimento de um quadro coerente. Ele ainda pode mostrar login, boas-vindas ou tela preta, sem comprovar que o desktop está pronto.

rdp-cli screenshot --session SESSION

Se receber FRAME_UNAVAILABLE, confira o estado e error.retryable, aguarde a reconexão ou a mudança de tela estabilizar e capture novamente. Se a tela continuar preta, verifique o servidor, a suspensão do cliente e a VPN. Examine a tela antes de digitar credenciais.

Resolva erros de entrada e permissão

  • OBSERVATION_REQUIRED: capture e leia uma imagem nova, usando seu data.observation na próxima ação. Renove após reconexão, troca de controle ou mudança de telas.
  • SESSION_PAUSED, CONTROL_HELD_BY_HUMAN ou CONTROL_NOT_OWNED: pare a entrada e respeite quem controla. Retome apenas após devolução autorizada e capture de novo; não contorne a pausa com outro visualizador.
  • PERMISSION_DENIED / CAPABILITY_UNAVAILABLE: confira capacidade e autorização. Um visualizador não habilita recursos ausentes no servidor. UNICODE_INPUT_UNAVAILABLE exige um método compatível, não tentativas cegas.

Verifique uma ação de resultado incerto

Antes de uma entrada cujo resultado possa exigir recuperação, defina e guarde um --request-id único por ação distinta; substitua os IDs de exemplo por valores próprios. Se receber um JSON de erro, guarde seu request_id no nível superior; se a resposta inteira se perder e o ID original não tiver sido salvo, não invente outro para consultar a ação anterior nem a repita às cegas.

Após REQUEST_TIMEOUT ou SERVICE_UNAVAILABLE durante uma ação, guarde o ID original. Confira o serviço local com list e consulte a operação antes de repetir. A entrada pode ter sido enviada mesmo que a resposta tenha se perdido.

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

Substitua REQUEST_ID pelo valor original, não pelo ID da consulta. Examine data.state, o data.result retido e uma captura nova. OPERATION_NOT_FOUND pode indicar expiração ou troca do serviço; não prova que a ação não ocorreu. Após corrigir a conexão, um reconnect explícito de sessão não encerrada mantém a pausa. SESSION_CLOSED exige uma nova conexão autorizada, não reconexões repetidas.

Comandos avançados do rdp-cli

Execute primeiro rdp-cli --version. Os comandos abaixo exigem agent_execution.contract_version igual a 1; versões anteriores podem continuar usando o fluxo de ações individuais descrito acima.

Substitua os campos em maiúsculas pelos valores retornados. No Windows PowerShell, use .\rdp-cli.exe na pasta do programa; no macOS ou Linux, use o comando instalado ou o caminho real do executável.

Conecte o agente e investigue a conexão

Use o MCP integrado ao executável ou a CLI. Salve perfis de conexão nomeados com referências às credenciais e examine as camadas da conexão com doctor.

Este exemplo de doctor lê as evidências existentes e não solicita um teste ativo. Unknown ou not-run não indicam aprovação. Os perfis usam referências às credenciais, sem senhas nos exemplos.

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

Continue com as evidências certas

Se persistir, informe versões do cliente/servidor, protocolo, horário, código e estado/captura sem dados sensíveis. Remova senhas, tokens e conteúdo privado.

Baixar · Guia rápido · Referência de comandos