rdp-cli
Resolver errores de conexión RDP, pantalla negra y entrada bloqueada
Versión y plataforma: 0.1.2 · Windows / macOS / Linux · RDP
Empieza por la respuesta real
Revisa los problemas RDP por etapas: red, cifrado, autenticación, pantalla y entrada. Elige la siguiente acción según el código de error, en lugar de cambiar contraseñas o reconectar repetidamente.
rdp-cli --version
rdp-cli list
rdp-cli status --session SESSION
Sustituye SESSION por tu ID de sesión. Ante un fallo, lee error.code, error.message y error.retryable. En un estado correcto revisa data.connection_state, data.control_state, data.last_error si existe y data.capabilities. Una marca de reintento no autoriza repetir entradas.
Comprueba la conexión por etapas
| Error | Comprobación y acción |
|---|---|
CONNECT_TIMEOUT / RDP_CONNECT_FAILED |
Comprueba host, puerto configurado (normalmente 3389), ruta LAN/VPN y servicio RDP. Pide al administrador que revise la escucha y la regla de firewall permitida. Un puerto accesible no demuestra un inicio RDP correcto. Reintenta una vez tras corregir la causa. |
RDP_TLS_HANDSHAKE_FAILED |
Revisa TLS en el servidor. El perfil predeterminado modern exige TLS 1.2. Usa --tls-profile legacy solo para un servidor antiguo identificado en una red de confianza: permite criptografía anterior. No lo apliques a todas las conexiones ni desactives la seguridad del servidor para pasar una prueba. |
CERTIFICATE_UNTRUSTED |
Con --cert-policy strict, verifica el nombre y la cadena del certificado, o contrasta la huella SHA-256 con el administrador antes de guardar una confianza específica. El valor actual por defecto, ignore, no verifica la identidad. No cambies a ignore solo para ocultar el fallo. |
AUTH_FAILED |
Revisa usuario, cuenta local o de dominio, --domain y permiso de inicio remoto. Usa el diálogo de contraseña o una referencia guardada del inicio rápido. No pruebes contraseñas repetidamente: un fallo TLS o un host inaccesible no demuestran una clave incorrecta. |
Conectado, pero sin imagen útil
Ejecuta esta consulta de lectura y abre el PNG de data.path. connected significa que RDP se activó y recibió una imagen coherente; puede ser el inicio de sesión, la bienvenida o una pantalla negra. No confirma que el escritorio esté listo.
rdp-cli screenshot --session SESSION
Si recibes FRAME_UNAVAILABLE, revisa el estado y error.retryable; espera a que termine la reconexión o el cambio de pantalla y captura de nuevo. Si sigue en negro, revisa el servidor, la suspensión del cliente y la VPN. Inspecciona la pantalla antes de introducir credenciales.
Resuelve errores de entrada y permisos
OBSERVATION_REQUIRED: captura y lee una imagen nueva; usa sudata.observationen la próxima acción. Renuévala tras reconectar, ceder el control o cambiar las pantallas.SESSION_PAUSED,CONTROL_HELD_BY_HUMANoCONTROL_NOT_OWNED: detén la entrada y respeta al controlador actual. Reanuda solo tras una devolución autorizada y vuelve a capturar; no eludas la pausa con otro visor.PERMISSION_DENIED/CAPABILITY_UNAVAILABLE: revisa la capacidad y la autorización. Abrir un visor no habilita funciones ausentes del servidor.UNICODE_INPUT_UNAVAILABLErequiere un método compatible, no reintentos ciegos.
Recupera una acción de resultado incierto
Antes de una entrada cuyo resultado pueda necesitar recuperación, asigna y guarda un --request-id único por acción distinta; sustituye los ID de ejemplo por valores propios. Si recibes un JSON de error, conserva su request_id de nivel superior; si se pierde toda la respuesta y no guardaste el ID original, no inventes otro para consultar la acción anterior ni la repitas a ciegas.
Tras REQUEST_TIMEOUT o SERVICE_UNAVAILABLE durante una acción, conserva el ID original. Comprueba el servicio local con list y consulta la operación antes de reintentar: la entrada puede haberse enviado aunque se perdiera la respuesta.
rdp-cli operations status --session SESSION --request-id REQUEST_ID
rdp-cli status --session SESSION
rdp-cli screenshot --session SESSION
Sustituye REQUEST_ID por el valor original, no por el ID de la consulta. Comprueba data.state, data.result retenido y una captura nueva. OPERATION_NOT_FOUND puede indicar caducidad o cambio de servicio; no demuestra que no se ejecutara. Tras corregir la conexión, un reconnect explícito de una sesión no cerrada la deja en pausa. SESSION_CLOSED necesita una conexión nueva autorizada, no reconexiones repetidas.
Comandos ampliados de rdp-cli
Ejecuta primero rdp-cli --version. Los comandos siguientes requieren agent_execution.contract_version igual a 1; las versiones anteriores pueden seguir usando el flujo paso a paso descrito arriba.
Sustituye los marcadores en mayúsculas por los valores devueltos. En Windows PowerShell, usa .\rdp-cli.exe desde su carpeta; en macOS o Linux, usa el comando instalado o la ruta real del ejecutable.
Conecta tu agente y diagnostica problemas
Usa MCP integrado en el ejecutable o la CLI. Guarda perfiles con referencias a credenciales y utiliza doctor para comprobar las distintas capas de conexión.
Este ejemplo de doctor lee las evidencias existentes y no solicita una prueba activa. Unknown o not-run no indican una comprobación superada. Los perfiles usan referencias a credenciales, sin contraseñas en los ejemplos.
rdp-cli profiles list
rdp-cli doctor --session SESSION
Continúa con la evidencia necesaria
Si persiste, aporta versiones del cliente y servidor, protocolo, hora, código y estado/captura sin información sensible. Elimina contraseñas, tokens y contenido privado.