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 su data.observation en la próxima acción. Renuévala tras reconectar, ceder el control o cambiar las pantallas.
  • SESSION_PAUSED, CONTROL_HELD_BY_HUMAN o CONTROL_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_UNAVAILABLE requiere 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.

Descargar · Inicio rápido · Referencia de comandos