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 seudata.observationna próxima ação. Renove após reconexão, troca de controle ou mudança de telas.SESSION_PAUSED,CONTROL_HELD_BY_HUMANouCONTROL_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_UNAVAILABLEexige 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.