先看实际响应

本文适用于 Windows、macOS 和 Linux 上的 rdp-cli 0.1.0 RDP 接口，依据 2026 年 9 月既有连接与 Agent 验收记录整理，不代表本轮新测服务器。使用获授权的 Windows RDP 服务端和本机对应的当前发行版。示例假定 PATH 中有 rdp-cli；Windows 在程序目录使用 .\rdp-cli.exe，Linux 使用已安装命令或下载的可执行文件。

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

以自己返回的会话 ID 替换 SESSION。失败时读取 error.code、error.message 和 error.retryable；状态成功时核对 data.connection_state、data.control_state、存在时的 data.last_error 及 data.capabilities。可重试标记不代表可以重放输入。

按连接阶段检查

错误 检查与处理
CONNECT_TIMEOUT / RDP_CONNECT_FAILED 核对主机、实际端口（通常为3389）、局域网/VPN路由和RDP服务是否启动。请管理员确认监听与允许访问的防火墙规则。端口可达不等于RDP登录成功；修正原因后再尝试一次。
RDP_TLS_HANDSHAKE_FAILED 检查服务器TLS配置。默认 modern 要求TLS 1.2；仅对可信网络中已确认的旧服务器按需使用 --tls-profile legacy，它允许旧加密配置。不要全局套用或为通过测试而关闭服务端安全设置。
CERTIFICATE_UNTRUSTED 使用 --cert-policy strict 时核对主机名与证书链，或先与管理员核验返回的SHA-256指纹，再添加精确的信任记录。当前默认值是 ignore，它不验证服务端身份；不要为了消除strict报错直接切换为ignore。
AUTH_FAILED 核对用户名、本地/域账户选择、--domain 和远程登录权限。按快速上手使用密码提示或已有凭据引用，不要循环猜试密码：TLS失败、主机不可达都不能证明密码错误。

已连接却没有可用画面

执行下面的只读查询，打开 data.path 指向的PNG。connected 表示协议已激活并收到连贯画面；画面仍可能是登录页、欢迎页或黑屏，不代表桌面已经可用。

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 需要重新建立获授权连接，不要反复重连试图复活它。

带着证据继续排查

仍无法解决时提供客户端版本、服务器版本、协议、时间、错误码及脱敏状态/截图，移除密码、访问令牌与敏感画面。本文不证明所有服务器的兼容性或长期稳定性。

下载 · 快速上手 · 命令参考