​

XBOX PC 遠端工具常見問題集與疑難排解指南

​

常見問題集

​

Fully Managed 與 Lightweight 裝置類型有何差異？

​

在哪裡可以找到應用程式版本號碼？

​

有哪些已知問題、相依性與限制？

​

已知問題

1. PowerShell/DSC 設定可能會失敗，且 XBOX PC Toolbox 可能會在設定期間意外關閉。
   • 因應措施： 請參閱 PowerShell 與 DSC 佈建在設定期間失敗。
2. 已加入網域的目標裝置：在 Fully Managed 模式下，OpenSSH 連線僅支援密碼型驗證 (建議使用金鑰型驗證，但目前無法使用)。對於已加入網域的裝置，可改用 Lightweight 佈建。
   • 注意：此問題會影響使用 Fully Managed 模式且已加入網域的 Windows 專業版裝置。小組正與 OpenSSH 及 Microsoft Entra ID 小組合作，以在未來進行改進。
3. WinGet 命令錯誤 (例如 winget search 失敗)
   • 因應措施： 重新開機目標裝置。產品小組正在調查此問題。
4. Visual Studio 偵錯工具效能：XBOX PC Remote Debugger 尚未針對效能進行最佳化。與本機偵錯相比，偵錯時間預期會較慢。未來的版本將會改善偵錯工具效能。
5. XBOX PC Remote Debugger 在多次偵錯反覆執行後可能會停止回應。請在大約 50 次反覆執行後重新啟動目標裝置。
   • 因應措施： 重新啟動目標裝置，然後重新啟動偵錯工作階段。

​

相依性與限制

• 兩部裝置在設定期間都需要網際網路存取。
• 裝置必須位於相同的區域網路，且能夠互相 ping。
• XBOX PC Toolbox 應用程式僅在 RETAIL 沙箱中提供。請確定裝置處於 RETAIL 模式，才能從 Microsoft Store 下載。
• 支援的裝置：Windows 10 或 Windows 11 家用版或專業版。
• 設定期間需要能實際操作兩部裝置。
• 設定時，兩部裝置都需要系統管理員存取權。
• 已加入 Microsoft Entra ID 的目標裝置僅透過 Lightweight 佈建提供支援。已加入 Entra 的裝置無法使用 Fully Managed。應用程式會自動偵測此狀況，並在設定期間停用 Fully Managed 選項。

​

從開發電腦取消配對是否會完全中斷裝置連線？

​

如何找到裝置連線資訊？

# Open a PowerShell 7 terminal
$env:ComputerName  # Device name
$env:Username      # Username  
ipconfig           # IP address

​

如何驗證裝置上的設定變更？

# Open a PowerShell 7 terminal on the DevPC
dsc config test -f "$env:LOCALAPPDATA\XboxPCDeviceManager\config\devPC.dsc.yaml"

# Network (usable on either device)  
dsc config test -f "$env:LOCALAPPDATA\XboxPCDeviceManager\config\network.dsc.yaml"

# Open a PowerShell 7 terminal on TargetDevice
dsc config test -f "$env:LOCALAPPDATA\XboxPCDeviceManager\config\targetDevice.dsc.yaml"

​

如何驗證與變更沙箱？

​

如何為安全通道設定選取特定的網路介面卡？

​

如何回報問題？

• 作業系統版本 (Windows 10/11 組建)
• PowerShell 版本 ($PSVersionTable)，適用於 XBOX Device Management PowerShell 模組問題
• 網路設定 (Wi-Fi/乙太網路、公司/家用)
• 錯誤訊息 (確切文字)
• 重現步驟
• 您使用的工具 (XBOX PC Toolbox、XBOX Device Management PowerShell 模組、wdRemote 或 wdEndpoint)
• 預覽版本

​

XBOX Device Management PowerShell 模組 (XDM) 與 wdRemote/wdEndpoint 有何差異？

• XDM：設定安全通訊通道。
• wdRemote/wdEndpoint：透過這些通道部署與啟動遊戲。

​

我需要同時使用 XDM 與 wdRemote/wdEndpoint 嗎？

​

為什麼第一次要以系統管理員身分執行 wdEndpoint？

​

可以將多個遊戲部署至同一部目標裝置嗎？

​

如果部署期間網路連線中斷會發生什麼情況？

​

所有通訊都會加密嗎？

​

每項工作應該使用哪個工具？

• XBOX PC Toolbox：用於遠端佈建與取得裝置、設定安全通道、安裝相依性以及設定裝置。
• 測試連線：在部署遊戲之前使用 XBOX PC Toolbox。
• 遠端工作階段：使用啟用 XDM 的遠端工作階段與 PowerShell 遠端處理，在目標裝置上執行命令。
• wdRemote/wdEndpoint：使用這些工具部署、測試與終止遊戲。

​

這些工具可以用於任何 Windows 遊戲嗎？

​

這些工具使用哪些網路連接埠？

• XDM：SSH (連接埠 22)
• wdEndpoint：HTTPS (連接埠 4275)

​

疑難排解指南

​

在公司網路環境中配對失敗

• 確認兩部裝置在網路上可以互相看見。公司防火牆或網路分割可能會封鎖裝置之間的通訊。
• 確定裝置之間已開啟下列連接埠：連接埠 22 (OpenSSH) 與連接埠 4275 (Remote Iteration 工具)。
• 嘗試配對或連線之前，請中斷任何 VPN 連線。
• 如果貴組織要求裝置註冊，請確認您的裝置已依照 IT 原則完成註冊。

​

安裝必要工具時發生錯誤

• 因應措施：從 %onedrive%/Documents/PowerShell/Modules/ 刪除模組目錄，然後再試一次。
• 原因：OneDrive 可能會干擾 PowerShell 模組安裝。

​

PowerShell 與 DSC 佈建在設定期間失敗

• 開啟提高權限的終端機並執行：

winget uninstall Microsoft.PowerShell
winget uninstall Microsoft.DSC
winget install Microsoft.PowerShell --installer-type wix
winget install Microsoft.DSC --installer-type zip

• 如果在執行這些步驟後，設定在安裝 DSC 時停止回應，請重新啟動 XBOX PC Toolbox 並再試一次。

​

OpenSSH 錯誤：kex_exchange_identification: read: Connection reset

• 重新啟動目標裝置。
• 確定裝置使用私人網路設定檔；否則，防火牆可能會封鎖連線。
• 檢查本機裝置上的 known_hosts 檔案是否損毀。

​

winget Microsoft PowerShell 7.5 安裝失敗 (0x8A150049)

• 因應措施：解除安裝 PowerShell 7.6 (隨附於 Visual Studio 2026)。較新的版本會造成安裝衝突。

​

配對後透過 SSH 執行 winget 失敗

• 因應措施：在目標裝置上執行 Repair-WinGetPackageManager，或重新開機目標裝置。
• 原因：此問題會在 SSH 連線上發生。

​

在掌機裝置上部署遊戲失敗

• 因應措施：調整目標裝置上的電源設定，防止裝置在部署期間進入睡眠。部署時，請確定裝置的睡眠計時器設定為較長的時間或已停用。
• 原因：XBOX PC Toolbox 不再透過 DSC 管理裝置電源設定。在睡眠計時器較積極的掌機裝置上，裝置會在部署途中進入睡眠，導致 wdRemote 失敗。

​

遠端目標裝置上顯示配對成功，但開發電腦上的 SSH 連線失敗

Get-Service sshd

Restart-Service sshd

ssh -o IdentitiesOnly=yes -i "$env:USERPROFILE\.ssh\XboxPCDeviceManagerKey" -o PreferredAuthentications=publickey user@target-ip "echo SUCCESS"

• 如果此命令成功，表示 ssh-agent 快取了錯誤的金鑰。請依照下列步驟修正。
• 如果此命令失敗，則問題出在遠端目標裝置端。若要進一步診斷，請參閱如何收集 OpenSSH 記錄。

# Clear all cached keys
ssh-add -D

# Restart the agent service
Restart-Service ssh-agent

# Re-add only the correct key
ssh-add "$env:USERPROFILE\.ssh\XboxPCDeviceManagerKey"

# Verify only your key is loaded
ssh-add -l

# Test the connection
ssh -o PreferredAuthentications=publickey user@target-ip "echo SUCCESS"

​

如何收集 OpenSSH 記錄

1. 以系統管理員身分開啟 記事本。
2. 開啟檔案 C:\ProgramData\ssh\sshd_config。

3. 找到以 # Logging 開頭的區段，並將：
   # Logging
   #SyslogFacility AUTH
   #LogLevel INFO
   
   變更為：
   # Logging
   SyslogFacility LOCAL0
   LogLevel Debug3
   
4. 以系統管理員身分開啟 PowerShell 終端機，並重新啟動 SSH 服務：
   net stop sshd
   net start sshd
   
5. 在 XBOX PC Toolbox 應用程式中重現問題。
6. 從 C:\ProgramData\ssh\logs 收集記錄。將資料夾壓縮為 .zip 檔案，以便與開發小組分享。
7. 收集記錄後，還原步驟 3 中所做的變更 (在每一行的開頭加回 #)，並再次使用步驟 4 重新啟動 SSH 服務。

​

另請參閱

• 如何使用 XBOX PC 遠端工具
• XBOX PC 遠端工具快速入門指南
• XBOX PC 遠端工具概觀