XBOX PC Remote (wdRemote.exe) - XBOX Game Development Documentation

XBOX PC Toolbox 应用处于预览阶段。请从 Windows 上的 Microsoft Store 下载。

XBOX PC Remote (wdRemote.exe) 是一个命令行工具,支持在远程 Windows 设备上构建游戏所需的两种工作流。使用这两条命令可以:

通过 PIN 配对在开发 PC 与远程设备之间建立可信、安全的连接。
在远程 Windows 设备上部署、启动和终止游戏。

wdRemote 在开发 PC 上运行,并与远程设备上运行的 wdEndpoint.exe 实例通信。请参阅 XBOX PC Remote 工具概述,了解 wdRemote 和 wdEndpoint 在 Windows 设备远程开发工具套件中所扮演的角色。请使用 XBOX PC Toolbox 或 WinGet 在你的开发 PC 上安装 wdRemote。 winget install Microsoft.Gaming.RemoteIterationClient 使用 wdRemote 运行下表中列出的命令。

命令	说明
wdRemote /action:pair	通过 PIN 配对在开发 PC 与远程设备之间建立可信、安全的连接。
wdRemote /action:purgekeys	从开发 PC 中移除所有加密密钥和设备配对。
wdRemote /action:version	显示 wdRemote.exe 的版本。
wdRemote /action:status	显示开发 PC 与目标设备之间的连接状态。
wdRemote /action:deploy	将游戏从开发 PC 部署到远程 Windows 设备。
wdRemote /action:launch	在远程 Windows 设备上启动游戏。
wdRemote /action:resume	恢复在远程 Windows 设备上以挂起状态启动的游戏。
wdRemote /action:terminate	终止在远程 Windows 设备上运行的游戏。

配对远程 Windows 设备和安全密钥管理

wdRemote /action:pair

此命令通过 PIN 配对在开发 PC 与远程设备之间建立可信、安全的连接。远程设备上运行的 wdEndpoint 会生成 PIN。 wdRemote /action:pair /device:HostName | IP Address /pin:pin number [/sshKey:filename]

选项	说明
/action:pair	指示 wdRemote 执行 PIN 配对操作。
/device:	远程设备的 IP 地址或主机名。
/pin:	由远程设备上运行的 wdEndpoint 实例生成的 PIN。
/sshKey:	要安装在远程设备上的可选 ssh 密钥。此密钥可用于在开发 PC 与远程设备之间建立 ssh 连接。

示例:

// 通过在远程设备上运行 `wdEndpoint /pair` 获取 PIN,启动配对流程。`wdEndpoint /pair` 必须从以管理员权限运行的命令提示符执行。
c:>wdEndpoint /pair

wdEndpoint version: 1.0.0.0
No configuration found at 'C:\ProgramData\Microsoft GDK\wdEndpoint\wdEndpoint.json', using defaults.
Overriding security mode for pairing.

Device ID: 29aab0e953b95099388b169861940a7501c7c7be
Security Mode: Private
Common Roots:
  (Default) C:\ProgramData\Microsoft GDK\gameroot

Server startup.
Listening for requests on: https://+:4275/gamingTransport/.
Entered exclusive pairing mode for 120 seconds.
PIN: q87p7w  

// 在桌面 PC 上将生成的 PIN 传递给 wdRemote 的配对 /action
c:>wdRemote /action:pair /device:myROGAllyX /pin:q87p7w

Successfully paired.
Client: a701ed911d794154737a1ed2cfe29e292d532561
Device: 231d6063b48cfc136f8ebdcad0a472edc7a27527

返回本主题顶部。

wdRemote /action:purgekeys

wdRemote 与 wdEndpoint 之间的所有流量都经过加密。wdRemote 会在首次被要求连接到远程设备时自动创建所需的加密密钥和证书。这些密钥也会在配对过程中使用。 wdRemote /action:purgekeys 会从开发 PC 中移除所有密钥和设备配对。 wdRemote /action:purgekeys 返回本主题顶部。

状态和版本信息

wdRemote /action:version

显示 wdRemote.exe 的版本。 wdRemote /action:version 返回本主题顶部。

wdRemote /action:status

显示开发 PC 与目标设备之间的连接状态。wdRemote /action:pair 会验证所有设备配对并检查加密是否生效。 wdRemote /action:status /device:HostName | IP Address

选项	说明
/action:status	指示 `wdRemote` 显示开发 PC 与由 `/device:` 参数标识的设备之间的连接状态。
/device:	远程设备的 IP 地址或主机名。

返回本主题顶部。

部署、启动和终止应用程序

wdRemote /action:deploy

将游戏从开发 PC 部署到由 /device: 参数指定的目标设备。所有部署都是增量部署,这意味着仅将自上次部署以来发生更改的文件传输到目标设备。游戏存储在目标设备上一个称为 Common Root 的目录中。默认情况下,Common Root 为 %ProgramData%\Microsoft GDK\gameroot。除非指定绝对路径,否则传递给 wdRemote 的目标路径相对于 Common Root;若指定绝对路径,则会忽略 Common Root。可以通过创建一个名为 wdEndpoint.json 的文件并将其放置在目标设备的 %ProgramData%\Microsoft GDK\wdEndpoint\ 中,来更改默认 Common Root 的位置并添加更多的 Common Root。wdEndpoint.json 以以下格式包含一个 Common Root 列表。

{
  root:<absolute file path>,
  alias:<name>,
  default:true|false
}

指定 default 是可选的。如果指定了多个默认项,则列表中的第一项成为默认项。如果没有 root 被标记为默认,则列表中的第一项将成为默认项。以下示例 wdEndpoint.json 定义了两个 Common Root:一个位于 c:\developmentbuilds 的默认 root,以及另一个位于 d:\releasedbuilds 的 root。

{
    "gameRoots": [
        {
            "root": "c:\\developmentbuilds",
            "alias": "primary",
            "default": true
        },
        {
            "root": "d:\\releasedbuilds",
            "alias": "released"
        }
    ]
}

wdRemote /action:deploy /device:HostName | IP Address /source:directory /destination:folder under gameRoot [/root:gameRoot alias]

选项	说明
/action:deploy	指示 `wdRemote` 执行部署操作。
/device:	远程设备的 IP 地址或主机名。
/source:	开发 PC 上包含要部署的游戏的目录。
/destination:	目标设备上要部署游戏的目录。此路径相对于 Common Root。
/root:	一个可选的 Common Root 别名。如果未指定,则使用默认 Common Root。

示例

// 将 c:\gamesource\x64\Debug 的内容部署到默认 Common Root 下名为 Daily 的目录。使用上面的示例配置文件,游戏将被部署到目标设备上的 c:\developmentbuilds\Daily。
c:\>wdRemote /action:deploy /device:myROGAllyX /source:c:\gamesource\x64\Debug /destination:Daily

// 将 \\releases\october2025\buildoutput 的内容部署到位于 d:\releasedbuilds 的 Common Root 下名为 october2025 的目录。使用上面的示例配置文件,
// 游戏将被部署到目标设备上的 d:\releasedbuilds\october2025。
c:\>wdRemote /action:deploy /device:myROGAllyX /source:\\releases\october2025\buildoutput /destination:october2025

返回本主题顶部。

wdRemote /action:launch

在由 /device: 参数指定的远程设备上启动游戏。启动的游戏的进程 ID 将作为输出显示。wdRemote 保证远程设备上一次仅运行一个游戏。如果在执行 wdRemote /action:launch 时远程设备上已有游戏在运行,则该正在运行的游戏会在新游戏启动之前被终止。

wdRemote /action:launch /device:HostName | IP Address /path:path to exe in Common Root [/args:list of arguments] [/root:gameRoot alias] [/suspend]

选项	说明
/action:launch	指示 wdRemote 执行启动操作。
/device:	远程设备的 IP 地址或主机名。
/path:	要启动的可执行文件的路径。相对路径将在 Common Root 下解析。如果指定绝对路径,则忽略 Common Root。
/args:	要传递给可执行文件的参数列表。
/root:	一个可选的 Common Root 别名。如果未指定,则使用默认 Common Root。
/suspend:	一个可选标志,以挂起状态启动游戏。使用 `wdRemote /action:resume` 恢复通过 `/suspend` 启动的游戏。

示例

// 在默认 Common Root 中启动游戏,并向游戏传递一个命令行参数
c:\>wdRemote /action:launch /device:myROGAllyX /path:Daily\Game.exe /args:"-level 2"

// 以挂起状态启动游戏
c:\>wdRemote /action:launch /device:myROGAllyX /path:Daily\Game.exe /suspend

返回本主题顶部。

wdRemote /action:resume

恢复远程设备上使用 wdRemote /action:launch 及 /suspend 标志以挂起状态启动的游戏。 wdRemote /action:resume /device:HostName | IP Address

选项	说明
/action:resume	指示 `wdRemote` 执行恢复操作。
/device:	远程设备的 IP 地址或主机名。

示例

c:\>wdRemote /action:resume /device:myROGAllyX

返回本主题顶部。

wdRemote /action:terminate

终止在远程设备上运行的游戏。 wdRemote /action:terminate /device:HostName | IP Address [/processid:id]

选项	说明
/action:terminate	指示 `wdRemote` 执行终止操作。
/device:	远程设备的 IP 地址或主机名。
/processid:	要终止的进程的 ID。

返回本主题顶部。

另请参阅

wdEndpoint Xbox PC Remote 工具

​配对远程 Windows 设备和安全密钥管理

​wdRemote /action:pair

​wdRemote /action:purgekeys

​状态和版本信息

​wdRemote /action:version

​wdRemote /action:status

​部署、启动和终止应用程序

​wdRemote /action:deploy

​wdRemote /action:launch

​wdRemote /action:resume

​wdRemote /action:terminate

​另请参阅

配对远程 Windows 设备和安全密钥管理

wdRemote /action:pair

wdRemote /action:purgekeys

状态和版本信息

wdRemote /action:version

wdRemote /action:status

部署、启动和终止应用程序

wdRemote /action:deploy

wdRemote /action:launch

wdRemote /action:resume

wdRemote /action:terminate

另请参阅