> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XBOX PC Remote (wdRemote.exe)

> XBOX PC Remote (wdRemote.exe)

<Info>XBOX PC Toolbox 应用处于预览阶段。请从 Windows 上的 [Microsoft Store](https://aka.ms/toolboxinstaller) 下载。</Info>

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

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

`wdRemote` 在开发 PC 上运行,并与远程设备上运行的 [wdEndpoint.exe](/tools/tools-pc/commandlinetools/gr-wdEndpoint) 实例通信。请参阅 [XBOX PC Remote 工具概述](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/overviews/remote-win-gamedev),了解 `wdRemote` 和 `wdEndpoint` 在 Windows 设备远程开发工具套件中所扮演的角色。

请使用 [XBOX PC Toolbox](/tools/tools-pc/xboxpctoolbox/xboxpctoolbox) 或 WinGet 在你的开发 PC 上安装 `wdRemote`。

`winget install Microsoft.Gaming.RemoteIterationClient`

使用 `wdRemote` 运行下表中列出的命令。

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

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

<a id="wdRemote_pair" />

### wdRemote /action:pair

此命令通过 PIN 配对在开发 PC 与远程设备之间建立可信、安全的连接。远程设备上运行的 [wdEndpoint](/tools/tools-pc/commandlinetools/gr-wdEndpoint) 会生成 PIN。

`wdRemote /action:pair /device:HostName | IP Address /pin:pin number` *\[/sshKey:filename]*

| 选项           | 说明                                                                                |
| ------------ | --------------------------------------------------------------------------------- |
| /action:pair | 指示 wdRemote 执行 PIN 配对操作。                                                          |
| /device:     | 远程设备的 IP 地址或主机名。                                                                  |
| /pin:        | 由远程设备上运行的 [wdEndpoint](/tools/tools-pc/commandlinetools/gr-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
```

[返回本主题顶部。](/tools/tools-pc/commandlinetools/gr-wdRemote)

<a id="wdRemote_purgekeys" />

### wdRemote /action:purgekeys

`wdRemote` 与 [wdEndpoint](/tools/tools-pc/commandlinetools/gr-wdEndpoint) 之间的所有流量都经过加密。`wdRemote` 会在首次被要求连接到远程设备时自动创建所需的加密密钥和证书。这些密钥也会在配对过程中使用。

`wdRemote /action:purgekeys` 会从开发 PC 中移除所有密钥和设备配对。

`wdRemote /action:purgekeys`

[返回本主题顶部。](/tools/tools-pc/commandlinetools/gr-wdRemote)

## 状态和版本信息

<a id="wdRemote_version" />

### wdRemote /action:version

显示 wdRemote.exe 的版本。

`wdRemote /action:version`

[返回本主题顶部。](/tools/tools-pc/commandlinetools/gr-wdRemote)

<a id="wdRemote_status" />

### wdRemote /action:status

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

`wdRemote /action:status /device:HostName | IP Address`

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

[返回本主题顶部。](/tools/tools-pc/commandlinetools/gr-wdRemote)

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

<a id="wdRemote_deploy" />

### 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 列表。

```json theme={null}
{
  root:<absolute file path>,
  alias:<name>,
  default:true|false
}
```

指定 *default* 是可选的。如果指定了多个默认项,则列表中的第一项成为默认项。如果没有 root 被标记为默认,则列表中的第一项将成为默认项。

以下示例 `wdEndpoint.json` 定义了两个 Common Root:一个位于 `c:\developmentbuilds` 的默认 root,以及另一个位于 `d:\releasedbuilds` 的 root。

```json theme={null}
{
    "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
```

[返回本主题顶部。](/tools/tools-pc/commandlinetools/gr-wdRemote)

<a id="wdRemote_launch" />

### 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
```

[返回本主题顶部。](/tools/tools-pc/commandlinetools/gr-wdRemote)

<a id="wdRemote_resume" />

### 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
```

[返回本主题顶部。](/tools/tools-pc/commandlinetools/gr-wdRemote)

<a id="wdRemote_terminate" />

### wdRemote /action:terminate

终止在远程设备上运行的游戏。

`wdRemote /action:terminate /device:HostName | IP Address [/processid:id]`

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

[返回本主题顶部。](/tools/tools-pc/commandlinetools/gr-wdRemote)

## 另请参阅

[wdEndpoint](/tools/tools-pc/commandlinetools/gr-wdEndpoint)
[Xbox PC Remote 工具](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/overviews/remote-gamedev-tools)


## Related topics

- [PC 开发的命令行工具](/zh-CN/tools/tools-pc/commandlinetools/gr-commandlinetools-toc.md)
- [命令行工具](/zh-CN/tools/tools-pc/commandlinetools/index.md)
- [如何使用 XBOX PC Remote 工具](/zh-CN/tools/tools-pc/xbox-pc-remote-tools/how-to-use-tools.md)
- [XBOX PC Remote 侦听终结点 (wdEndpoint.exe)](/zh-CN/tools/tools-pc/commandlinetools/gr-wdEndpoint.md)
- [XBOX PC Remote 工具:2026 年 3 月 (2603) 发行说明](/zh-CN/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md)