WoWS Remote Agent

Ein eingeschränkter Remote-Control-Agent für Windows. Er ermöglicht Codex oder anderen MCP/HTTP-fähigen KI-Systemen über das Tailscale-Privatnetz Folgendes:

• Den Status des Gaming-PCs und des World-of-Warships-Prozesses abrufen;

• Einen aktuellen Desktop-Screenshot aufnehmen;

• Das lokal konfigurierte Spiel starten und in den Fokus bringen;

• Vom Benutzer lokal kalibrierte Menüpositionen anklicken;

• Vorab geprüfte Menü-Workflows ausführen;

• Jederzeit per lokalem Ctrl+Alt+F12 oder remote abort einen Notstopp auslösen.

Das Projekt bietet kein Autopilot, Zielen, Schießen, Bot-Farming oder Anti-Erkennung. Es ist kein offizielles Projekt von Wargaming und steht in keiner Verbindung zu Wargaming.

Sicherheitsgrenzen

Der Agent hat keine Schnittstelle für beliebige Shells, beliebige Programmstarts oder Dateiverwaltung. Das entfernte Ende kann nur das im Konfigurationsfile eindeutig festgelegte Programm starten; die Tastatur-Whitelist enthält nur Menütasten wie Enter, Esc, Tab, Space und Pfeiltasten, nicht W/A/S/D. Einzelklicks sind standardmäßig deaktiviert; nur lokal konfigurierte Workflows sind erlaubt.

Alle Schreibvorgänge werden protokolliert in:

C:\ProgramData\WoWSRemoteAgent\logs\audit.jsonl

start_battle-Workflow verlangt außerdem, dass die KI beim Aufruf confirmed=true übergibt. Das ersetzt nicht deine Aufsicht; verwende es nur, wenn du den Bildschirm des Gaming-PCs sehen kannst.

World-of-Warships-Regel 5.07 verbietet den Einsatz von Bots, Clickern, Makros und ähnlichen Methoden, wenn der Spieler nicht teilnimmt oder nur passiv teilnimmt. Im Kooperationsmodus gibt es keine Ausnahme für Automatisierung. Daher ist dieses Projekt ausschließlich für Start und Menünavigation gedacht und sollte nicht zu einem automatischen Kampfwerkzeug ausgebaut werden. Prüfe vor der Verwendung selbst die aktuellen Regeln für deine Region.

Related MCP server: Desktop Commander MCP Server

Schnellste Installation

Voraussetzungen:

• Der Gaming-PC läuft mit Windows 10/11;

• PowerShell als Administrator öffnen;

• Windows verfügt über winget oder Python 3.11 oder höher ist bereits installiert;

• Das Spiel verwendet ein randloses Fenster mit fester Auflösung und fester UI-Skalierung.

In einer administrativen PowerShell ausführen:

Set-ExecutionPolicy -Scope Process Bypass -Force
irm https://raw.githubusercontent.com/jesson-hh/wows-remote-agent/v0.1.0/scripts/bootstrap.ps1 | iex

Dies ist ein Einzeiler für die Erstinstallation, der direkt ein Skript von GitHub ausführt. Bei höheren Sicherheitsanforderungen lade zuerst bootstrap.ps1 herunter und lies es; prüfe Repository und Version, bevor du es ausführst. Für die Produktion empfiehlt es sich, auf ein bestimmtes Release-Tag zu fixieren, statt langfristig main zu folgen.

Der Installer wird:

1. Python 3.11+ installieren oder wiederverwenden;

2. Eine eigene virtuelle Umgebung erstellen;

3. Tailscale installieren und bei Bedarf durch die Anmeldung führen;

4. Ein zufälliges Zugriffstoken mit 64 Zeichen erzeugen;

5. Nur Tailscale-IP-Bereichen Zugriff auf den Agent-Port erlauben;

6. Einen geplanten Task erstellen, der nach Benutzeranmeldung startet;

7. C:\ProgramData\WoWSRemoteAgent\connection.json erzeugen.

Falls der Installer Tailscale nicht verwalten soll:

irm https://raw.githubusercontent.com/jesson-hh/wows-remote-agent/v0.1.0/scripts/bootstrap.ps1 -OutFile "$env:TEMP\wows-bootstrap.ps1"
& "$env:TEMP\wows-bootstrap.ps1" -SkipTailscale

Lade connection.json nicht auf GitHub, in Cloud-Speicher oder Chat-Gruppen hoch. Es enthält ein Zugriffstoken.

Spielpfad festlegen

Falls beim Installieren nicht ausgefüllt, in einer administrativen PowerShell ausführen:

& 'C:\ProgramData\WoWSRemoteAgent\scripts\configure.ps1' `
  -GamePath 'D:\Games\World_of_Warships\WorldOfWarships.exe'

Bitte trag das tatsächliche Startprogramm auf deinem Computer ein. Der Installer scannt oder modifiziert keine Spieldateien.

Kooperationsmodus-Buttons kalibrieren

Behalte das Spiel mit fester Auflösung und randlosem Fenster. Bewege nach jedem Ausführen des Befehls den Mauszeiger vor Ablauf des Countdowns auf den jeweiligen Button, ohne zu klicken:

& 'C:\ProgramData\WoWSRemoteAgent\scripts\calibrate.ps1' -Name battle_type_button
& 'C:\ProgramData\WoWSRemoteAgent\scripts\calibrate.ps1' -Name coop_mode
& 'C:\ProgramData\WoWSRemoteAgent\scripts\calibrate.ps1' -Name confirm_mode
& 'C:\ProgramData\WoWSRemoteAgent\scripts\calibrate.ps1' -Name battle_button

Sie entsprechen:

1. Dem Button für den Gefechtstyp im Hafen;

2. Der Option für den Kooperationsmodus;

3. Dem Bestätigungsbutton der Modusauswahl;

4. Dem „Gefecht starten“-Button.

Nach Änderung der Auflösung, der Monitor-Reihenfolge oder der Windows-Skalierung muss neu kalibriert werden.

Gaming-PC prüfen

& 'C:\ProgramData\WoWSRemoteAgent\scripts\doctor.ps1'

Falls die lokale Gesundheitsprüfung fehlschlägt:

Get-ScheduledTask -TaskName 'WoWS Remote Agent'
Start-ScheduledTask -TaskName 'WoWS Remote Agent'
Get-Content 'C:\ProgramData\WoWSRemoteAgent\logs\audit.jsonl' -Tail 30

Der Agent muss in einer angemeldeten interaktiven Windows-Sitzung laufen. Session 0 von Windows-Diensten kann nicht zuverlässig Screenshots aufnehmen und auf den Desktop klicken; deshalb verwendet der Installer einen geplanten Task, der bei der Anmeldung startet. Bei gesperrtem Bildschirm oder nach Abmeldung funktioniert die Desktop-Steuerung nicht.

Codex auf dem Steuer-PC verbinden

Lass zuerst beide Computer im selben Tailscale-Tailnet anmelden. Kopiere connection.json vom Gaming-PC sicher auf den Steuer-PC und führe dann auf dem Steuer-PC aus:

git clone https://github.com/jesson-hh/wows-remote-agent.git
cd wows-remote-agent
& .\scripts\configure-codex.ps1 -ConnectionFile 'D:\Safe\connection.json'

Das Skript wird:

• Das Zugriffstoken in die Umgebungsvariable WOWS_REMOTE_AGENT_TOKEN des aktuellen Windows-Benutzers schreiben;

• Mit codex mcp add einen Streamable-HTTP-MCP registrieren;

• Das Klartext-Token nicht in die Codex-config.toml schreiben.

Nach einem Neustart der ChatGPT/Codex-Desktop-App und Eingabe von /mcp sollte wows-remote-agent sichtbar sein.

Manuelle Konfiguration ist ebenfalls möglich:

[mcp_servers.wows-remote-agent]
url = "http://100.x.y.z:8765/mcp"
bearer_token_env_var = "WOWS_REMOTE_AGENT_TOKEN"
default_tools_approval_mode = "prompt"
tool_timeout_sec = 150

Remote-Verbindung testen

Auf dem Steuer-PC ausführen:

& .\scripts\test-connection.ps1 -AgentIP 100.x.y.z

Das Testskript blendet das eingegebene Token aus und prüft dann /health und das authentifizierungspflichtige /v1/status.

Was du Codex sagen kannst

Es wird empfohlen, Anweisungen in kleinen Schritten zu geben:

检查游戏电脑状态，不要执行操作。

运行 open_game，等它完成后截图并告诉我当前界面。

先截图；只有画面确实是港口时才运行 enter_coop，然后再次截图。

我确认现在可以点击开始战斗。运行 start_battle，confirmed=true，然后停止操作。

Falls die Oberfläche von der Erwartung abweicht:

立即调用 abort，不要尝试猜测按钮。

MCP-Tools

Die REST-Äquivalente befinden sich unter /v1/*; alle erfordern Authorization: Bearer ..., nur /health benötigt kein Token.

Aktualisierung

Durch erneutes Ausführen desselben Befehls kannst du die aktuell festgelegte Version neu installieren und dabei die vorhandenen config.json, Kalibrierpunkte, Zugriffstoken und Protokolle behalten. Beim Upgrade ersetze v0.1.0 im Befehl durch die auf der GitHub-Releases-Seite aufgeführte neue Version. Vor Installation oder Upgrade wird weiterhin ein Backup empfohlen:

Copy-Item 'C:\ProgramData\WoWSRemoteAgent\config.json' "$env:USERPROFILE\Desktop\wows-agent-config.backup.json"

Deinstallation

Konfiguration und Protokolle behalten:

& 'C:\ProgramData\WoWSRemoteAgent\scripts\uninstall.ps1' -KeepConfig

Agent, Konfiguration und Protokolle vollständig entfernen:

& 'C:\ProgramData\WoWSRemoteAgent\scripts\uninstall.ps1'

Das Deinstallationsskript deinstalliert weder Tailscale, Python noch das Spiel.

Entwicklung

py -3.12 -m venv .venv
.\.venv\Scripts\python -m pip install -e '.[test]'
.\.venv\Scripts\python -m ruff check .
.\.venv\Scripts\python -m pytest

Nach dem Kopieren der Beispielkonfiguration und dem Setzen eines temporären Tokens kann lokal gestartet werden:

Copy-Item config.example.json .local-config.json
$env:WOWS_AGENT_CONFIG = (Resolve-Path .local-config.json)
$env:WOWS_AGENT_TOKEN = 'development-token-at-least-32-characters'
.\.venv\Scripts\python -m wows_remote_agent --config .local-config.json --host 127.0.0.1

Weitere Hinweise findest du unter Bereitstellung und Fehlerbehebung und Sicherheitsmodell.

Das Repository enthält ein GitHub Actions CI-Beispiel. Repository-Maintainer können es bei Token mit workflow-Berechtigung nach .github/workflows/ci.yml kopieren, um die Prüfungen automatisch unter Windows und Ubuntu mit Python 3.11/3.12 auszuführen.