> ## 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 遠端 (wdRemote.exe)

> XBOX PC 遠端 (wdRemote.exe)

# XBOX PC 遠端 (wdRemote.exe)

<Info>
  XBOX PC Toolbox 應用程式目前為預覽版。請從 Windows 上的 [Microsoft Store](https://aka.ms/toolboxinstaller) 下載。
</Info>

XBOX PC 遠端 (`wdRemote.exe`) 是一個命令列工具，可將開發電腦安全地連線至遠端 Windows 裝置。它支援 PIN 配對、雙向檔案傳輸、遠端檔案刪除、遊戲部署與生命週期管理，以及遠端工具執行。

`wdRemote` 在開發電腦上執行，並與在遠端裝置上執行的 [wdEndpoint.exe](/zh-TW/tools/tools-pc/commandlinetools/gr-wdEndpoint) 執行個體通訊。如需 `wdRemote` 與 `wdEndpoint` 在 Windows 裝置遠端開發工具套件中所扮演角色的說明，請參閱 [XBOX PC 遠端工具概觀](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/overviews/remote-win-gamedev)。

使用 [XBOX PC Toolbox](/zh-TW/tools/tools-pc/xboxpctoolbox/xboxpctoolbox) 或 WinGet 在您的開發電腦上安裝 `wdRemote`。

`winget install Microsoft.Gaming.RemoteIterationClient`

使用 `wdRemote` 執行下表所列的命令。

| 命令 | 描述 |
| - | - |
| [wdRemote /action:pair](#wdremote-action-pair) | 透過 PIN 配對，在開發電腦與遠端裝置之間建立受信任的安全連線。 |
| [wdRemote /action:purgekeys](#wdremote-action-purgekeys) | 從開發電腦移除所有加密金鑰與裝置配對。 |
| [wdRemote /action:version](#wdremote-action-version) | 顯示 wdRemote.exe 的版本。 |
| [wdRemote /action:status](#wdremote-action-status) | 顯示開發電腦與目標裝置之間的連線狀態。 |
| [wdRemote /action:deploy](#wdremote-action-deploy) | 將遊戲從開發電腦部署至遠端 Windows 裝置。 |
| [wdRemote /action:launch](#wdremote-action-launch) | 在遠端 Windows 裝置上啟動遊戲。 |
| [wdRemote /action:resume](#wdremote-action-resume) | 繼續執行遠端 Windows 裝置上以暫停狀態啟動的遊戲。 |
| [wdRemote /action:terminate](#wdremote-action-terminate) | 終止遠端 Windows 裝置上的遊戲、工具作業或指定的處理序。 |
| [wdRemote /action:copy](#wdremote-action-copy) | 將檔案從開發電腦複製到遠端 Windows 裝置。 |
| [wdRemote /action:copyfrom](#wdremote-action-copyfrom) | 將檔案從遠端 Windows 裝置複製到開發電腦。 |
| [wdRemote /action:delete](#wdremote-action-delete) | 刪除遠端 Windows 裝置上的檔案或目錄內容。 |
| [wdRemote /action:run](#wdremote-action-run) | 在遠端 Windows 裝置上執行可執行檔。 |

## 配對遠端 Windows 裝置與安全性金鑰管理

### wdRemote /action:pair

此命令會透過 PIN 配對，在開發電腦與遠端裝置之間建立受信任的安全連線。PIN 是由在遠端裝置上執行的 [wdEndpoint](/zh-TW/tools/tools-pc/commandlinetools/gr-wdEndpoint) 產生。

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

| 選項 | 描述 |
| - | - |
| /action:pair | 表示 wdRemote 應執行 PIN 配對作業。 |
| /device: | 遠端裝置的 IP 位址或主機名稱。 |
| /pin: | 由在遠端裝置上執行的 [wdEndpoint](/zh-TW/tools/tools-pc/commandlinetools/gr-wdEndpoint) 執行個體所產生的 PIN。 |
| /sshKey: | 要安裝在遠端裝置上的選用 ssh 金鑰。此金鑰可用於在開發電腦與遠端裝置之間建立 ssh 連線。 |

範例：

```
// Start the pairing process by obtaining a pin using `wdEndpoint /pair` on the remote device.  `wdEndpoint /pair` must be executed from a command prompt with Administrator privileges
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: <example-device-id>
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: <example-pin>

// Specify the result PIN to the pairing /action to wdRemote on the development PC
c:>wdRemote /action:pair /device:example-device /pin:<example-pin>

Successfully paired.
Client: <example-client-id>
Device: <example-device-id>
```

[返回本主題頂端。](/zh-TW/tools/tools-pc/commandlinetools/gr-wdRemote)

### wdRemote /action:purgekeys

`wdRemote` 與 [wdEndpoint](/zh-TW/tools/tools-pc/commandlinetools/gr-wdEndpoint) 之間的所有流量都會加密。`wdRemote` 第一次被要求連線至遠端裝置時，會自動建立必要的加密金鑰與憑證。這些金鑰也會用於配對程序。

此動作會從開發電腦移除所有金鑰與裝置配對。

`wdRemote /action:purgekeys`

[返回本主題頂端。](/zh-TW/tools/tools-pc/commandlinetools/gr-wdRemote)

## 狀態與版本資訊

### wdRemote /action:version

顯示 wdRemote.exe 的版本。

`wdRemote /action:version`

[返回本主題頂端。](/zh-TW/tools/tools-pc/commandlinetools/gr-wdRemote)

### wdRemote /action:status

顯示開發電腦與目標裝置之間的連線狀態。`wdRemote /action:pair` 會驗證所有裝置配對，並檢查以確保加密已生效。

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

| 選項 | 描述 |
| - | - |
| /action:status | 表示 `wdRemote` 應顯示開發電腦與 `/device:` 引數所識別之裝置間的連線狀態 |
| /device: | 遠端裝置的 IP 位址或主機名稱。 |

[返回本主題頂端。](/zh-TW/tools/tools-pc/commandlinetools/gr-wdRemote)

## 部署、啟動與終止應用程式

### wdRemote /action:deploy

將遊戲從開發電腦部署至 `/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* 為選用。如果指定了多個預設值，則列出的第一個會成為預設值。如果沒有任何根目錄標示為預設，則列出的第一個會成為預設值。

下列 `wdEndpoint.json` 範例定義了兩個 Common Root：位於 `c:\developmentbuilds` 的預設根目錄，以及位於 `d:\releasedbuilds` 的另一個根目錄。

```json theme={null}
{
    "gameRoots": [
        {
            "root": "c:\\developmentbuilds",
            "alias": "primary",
            "default": true
        },
        {
            "root": "d:\\releasedbuilds",
            "alias": "released"
        }
    ]
}
```

`wdRemote /action:deploy /device:<remote device> /source:<source directory> /destination:<absolute or common root relative destination directory> [/root:<common root alias>] [/attributes:<-AHSR>]`

| 選項 | 描述 |
| - | - |
| /action:deploy | 表示 `wdRemote` 應執行部署動作。 |
| /device: | 遠端裝置的 IP 位址或主機名稱。 |
| /source: | 開發電腦上包含要部署之遊戲的目錄。 |
| /destination: | 相對目的地路徑會在所選的 Common Root 底下解析。如果指定絕對路徑，則會忽略 Common Root。 |
| /root: | 選用的 Common Root 別名。如果未指定，則使用預設 Common Root。 |
| /attributes: | 選擇性地依據檔案屬性包含或排除檔案與目錄。 |

`/attributes:` 選項支援下列字母。

| 字母 | 檔案屬性 |
| - | - |
| `A` | 封存 |
| `H` | 隱藏 |
| `R` | 唯讀 |
| `S` | 系統 |

`-` 之前的字母表示包含。`-` 之後的字母表示排除。

範例

```
// Deploys the contents of c:\gamesource\x64\Debug to a directory named Daily under the default Common Root.  Using the example config file above, the game
// will be deployed to c:\developmentbuilds\Daily on the target device.
c:\>wdRemote /action:deploy /device:example-device /source:c:\gamesource\x64\Debug /destination:Daily

// Deploys the contents of \\example-server\builds\buildoutput to a directory named october2025 under the Common Root at d:\releasedbuilds.  Using the example config file above,
// the game will be deployed to d:\releasedbuilds\october2025 on the target device.
c:\>wdRemote /action:deploy /device:example-device /source:\\example-server\builds\buildoutput /destination:october2025 /root:released

// Deploys everything except hidden files and directories.
c:\>wdRemote /action:deploy /device:example-device /source:C:\game /destination:game1 /attributes:-H
```

[返回本主題頂端。](/zh-TW/tools/tools-pc/commandlinetools/gr-wdRemote)

### wdRemote /action:launch

在 `/device:` 引數所指定的遠端裝置上啟動遊戲。已啟動之遊戲的處理序識別碼會顯示為輸出。`wdRemote` 保證遠端裝置上一次只會執行一個遊戲。如果在您執行 `wdRemote /action:launch` 時遠端裝置上已有遊戲在執行，則會在新遊戲啟動之前終止執行中的遊戲。

`wdRemote /action:launch /device:<remote device> /path:<absolute or Common Root-relative executable path> [/root:<Common Root alias>] [/args:"<arguments>"] [/suspend]`

| 選項 | 描述 |
| - | - |
| /action:launch | 表示 wdRemote 應執行啟動動作。 |
| /device: | 遠端裝置的 IP 位址或主機名稱。 |
| /path: | 要啟動之可執行檔的路徑。相對路徑會在 Common Root 底下解析。如果指定絕對路徑，則會忽略 Common Root。 |
| /args: | 要傳遞給可執行檔的引數清單。 |
| /root: | 選用的 Common Root 別名。如果未指定，則使用預設 Common Root。 |
| /suspend: | 以暫停狀態啟動遊戲的選用旗標。使用 `wdRemote /action:resume` 繼續執行以 `/suspend` 啟動的遊戲。 |

範例

```
// Launches a game in the default Common Root, passing a command line argument to the game
c:\>wdRemote /action:launch /device:example-device /path:Daily\Game.exe /args:"-level 2"

// Launches a game in a suspended state
c:\>wdRemote /action:launch /device:example-device /path:Daily\Game.exe /suspend
```

[返回本主題頂端。](/zh-TW/tools/tools-pc/commandlinetools/gr-wdRemote)

### wdRemote /action:resume

繼續執行遠端裝置上使用 `wdRemote /action:launch` 搭配 `/suspend` 旗標以暫停狀態啟動的遊戲。

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

| 選項 | 描述 |
| - | - |
| /action:resume | 表示 `wdRemote` 應執行繼續動作。 |
| /device: | 遠端裝置的 IP 位址或主機名稱。 |

範例

```
c:\>wdRemote /action:resume /device:example-device
```

[返回本主題頂端。](/zh-TW/tools/tools-pc/commandlinetools/gr-wdRemote)

### wdRemote /action:terminate

終止遠端遊戲、遠端工具作業或指定的遠端處理序。

```
wdRemote /action:terminate /device:<remote device>
wdRemote /action:terminate /device:<remote device> /tool[:<pid>]
```

| 形式 | 行為 |
| - | - |
| 無 `/tool` 引數 | 終止遠端遊戲。 |
| `/tool` | 終止遠端工具作業。 |
| `/tool:pid` | 嘗試終止具有指定處理序識別碼的處理序。 |

範例

```
// Terminates the remote game.
c:\>wdRemote /action:terminate /device:example-device

// Terminates the remote tool job.
c:\>wdRemote /action:terminate /device:example-device /tool

// Attempts to terminate the specified process.
c:\>wdRemote /action:terminate /device:example-device /tool:1234
```

[返回本主題頂端。](/zh-TW/tools/tools-pc/commandlinetools/gr-wdRemote)

## 複製與刪除檔案

### wdRemote /action:copy

將檔案從開發電腦複製到遠端 Windows 裝置。

```
wdRemote /action:copy /device:HostName | IP Address /source:source directory /destination:remote directory [/root:gameRoot alias]
```

| 選項 | 描述 |
| - | - |
| /action:copy | 表示 `wdRemote` 應執行複製作業。 |
| /device: | 遠端 Windows 裝置的 IP 位址或主機名稱。 |
| /source: | 開發電腦上的來源目錄。 |
| /destination: | 遠端 Windows 裝置上的目的地目錄。 |
| /root: | 用於解析相對目的地路徑的選用 Common Root 別名。如果相對路徑省略此選項，則使用預設 Common Root。絕對目的地路徑會忽略 Common Root。 |

範例

```
c:\>wdRemote /action:copy /device:example-device /source:C:\game /destination:game1
```

### wdRemote /action:copyfrom

將檔案從遠端 Windows 裝置複製到開發電腦。`/source` 是遠端路徑，`/destination` 是本機路徑。`/root` 用於解析相對遠端來源路徑，當 `/source` 為絕對路徑時會被忽略。

```
wdRemote /action:copyfrom /device:HostName | IP Address /source:remote source directory /destination:local destination directory [/root:gameRoot alias]
```

| 選項 | 描述 |
| - | - |
| /action:copyfrom | 表示 `wdRemote` 應執行從裝置複製的作業。 |
| /device: | 遠端 Windows 裝置的 IP 位址或主機名稱。 |
| /source: | 遠端 Windows 裝置上的來源目錄。 |
| /destination: | 開發電腦上的目的地目錄。 |
| /root: | 用於解析相對遠端來源路徑的選用 Common Root 別名。 |

範例

```
c:\>wdRemote /action:copyfrom /device:example-device /source:game1 /destination:C:\local_copy
```

### wdRemote /action:delete

嘗試刪除遠端 Windows 裝置上的檔案或選取的目錄內容。目錄刪除會盡力而為。端點記錄會記錄已刪除的項目數量與失敗數量，但不會記錄個別的檔案路徑。

```
wdRemote /action:delete /device:HostName | IP Address /path:remote directory or file [/root:gameRoot alias] [/include:pattern] [/exclude:pattern] [/excludedir:pattern] [/attributes:<-AHSR>] [/deleteroot]
```

| 選項 | 描述 |
| - | - |
| /action:delete | 表示 `wdRemote` 應執行刪除作業。 |
| /device: | 遠端 Windows 裝置的 IP 位址或主機名稱。 |
| /path: | 要刪除的遠端目錄或檔案。 |
| /root: | 用於解析相對遠端路徑的選用 Common Root 別名。 |
| /include: | 包含符合模式的檔案。支援 `*` 與 `?` 萬用字元。 |
| /exclude: | 排除符合模式的檔案。支援 `*` 與 `?` 萬用字元。排除的優先順序高於包含。 |
| /excludedir: | 排除名稱符合模式的目錄。支援 `*` 與 `?` 萬用字元。 |
| /attributes: | 依封存、隱藏、唯讀與系統屬性包含或排除檔案與目錄。排除某個屬性也會排除具有該屬性的目錄及其所有內容。 |
| /deleteroot | 在刪除 `/path` 所指定目錄的內容之後，嘗試移除該目錄。只有在目錄為空時才會移除。不論是否使用此選項，作業都會嘗試移除通過目錄篩選條件的空白子目錄。 |

<Warning>
  刪除作業可能會追蹤 `/path` 底下的目錄連接點與目錄符號連結，並刪除該目錄之外的相符檔案。命令仍可能回報成功；不會提供個別項目的結果或復原作業。請確定 `/path` 本身不是連結的目錄，並使用 `/excludedir` 依名稱排除已知的連結子目錄。
</Warning>

當 `/path` 識別的是單一檔案時，會忽略搜尋選項與 `/deleteroot`。

範例

```
c:\>wdRemote /action:delete /device:example-device /path:game1
c:\>wdRemote /action:delete /device:example-device /path:game1 /exclude:"*.pdb" /excludedir:"logs"
c:\>wdRemote /action:delete /device:example-device /path:game1 /deleteroot
c:\>wdRemote /action:delete /device:example-device /path:game1\readme.txt
```

## 執行遠端工具

### wdRemote /action:run

在遠端 Windows 裝置上執行可執行檔。

```
wdRemote /action:run /device:HostName | IP Address /path:absolute executable path [/args:"arguments"] [/waitForExit] [/streamOutput] [/asAdmin]
```

| 選項 | 描述 |
| - | - |
| /action:run | 表示 `wdRemote` 應執行可執行檔。 |
| /device: | 遠端 Windows 裝置的 IP 位址或主機名稱。 |
| /path: | 遠端 Windows 裝置上可執行檔的絕對路徑。 |
| /args: | 傳遞給可執行檔的引數。 |
| /waitForExit | 等候可執行檔結束。 |
| /streamOutput | 串流標準輸出與標準錯誤，直到可執行檔結束。 |
| /asAdmin | 以系統管理員身分執行可執行檔。 |

`/waitForExit` 無法與 `/streamOutput` 合併使用。`/asAdmin` 無法與 `/streamOutput` 合併使用。

若未使用 `/waitForExit` 或 `/streamOutput`，命令會回報已啟動的處理序識別碼與執行緒識別碼。若使用 `/waitForExit` 或 `/streamOutput`，`wdRemote.exe` 會傳回遠端處理序的結束代碼。

範例

```
c:\>wdRemote /action:run /device:example-device /path:C:\tools\mytool.exe
c:\>wdRemote /action:run /device:example-device /path:C:\tools\mytool.exe /args:"-arg1 -arg2" /waitForExit
c:\>wdRemote /action:run /device:example-device /path:C:\tools\mytool.exe /args:"-arg1 -arg2" /streamOutput
c:\>wdRemote /action:run /device:example-device /path:C:\tools\mytool.exe /asAdmin
```

## 其他資源

[wdEndpoint](/zh-TW/tools/tools-pc/commandlinetools/gr-wdEndpoint)
[XBOX PC 遠端工具](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/overviews/remote-gamedev-tools)


## Related topics

- [PC 開發的命令列工具](/zh-TW/tools/tools-pc/commandlinetools/gr-commandlinetools-toc.md)
- [命令列工具](/zh-TW/tools/tools-pc/commandlinetools/index.md)
- [XBOX PC 遠端接聽端點 (wdEndpoint.exe)](/zh-TW/tools/tools-pc/commandlinetools/gr-wdEndpoint.md)
- [XBOX PC 遠端工具常見問題集與疑難排解指南](/zh-TW/tools/tools-pc/xbox-pc-remote-tools/faq.md)
- [如何使用 XBOX PC 遠端工具](/zh-TW/tools/tools-pc/xbox-pc-remote-tools/how-to-use-tools.md)