WoWS Remote Agent

Un agente de control remoto restringido para Windows. Permite que Codex u otras IA compatibles con MCP/HTTP realicen las siguientes operaciones a través de la red privada de Tailscale:

• Ver el estado de los procesos del PC de juego y de《战舰世界》;

• Obtener una captura de pantalla actual del escritorio;

• Iniciar y enfocar el programa de juego configurado localmente;

• Hacer clic en posiciones de menú calibradas localmente por el usuario;

• Ejecutar flujos de trabajo de menú previamente revisados;

• Detener de emergencia en cualquier momento con Ctrl+Alt+F12 local o abort remoto.

El proyecto no ofrece conducción autónoma, puntería, disparo, farmeo AFK ni funciones de antidetección. No es un proyecto oficial de Wargaming y no está afiliado a Wargaming.

Límites de seguridad

El agente no tiene interfaces de shell arbitrario, lanzamiento de programas arbitrarios o gestión de archivos. El lado remoto solo puede iniciar el programa especificado de forma única en el archivo de configuración; la lista blanca de teclado solo incluye teclas de menú como Enter, Esc, Tab, Espacio y flechas, no incluye W/A/S/D. Los clics arbitrarios paso a paso están desactivados por defecto; solo se permiten los flujos de trabajo configurados localmente.

Todas las operaciones de escritura se registran en:

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

El flujo de trabajo start_battle también requiere que la IA pase confirmed=true al llamarlo. Esto no sustituye tu supervisión; úsalo solo cuando puedas ver la pantalla del PC de juego.

Las Reglas 5.07 de《战舰世界》 prohíben el uso de bots, autoclickers, macros y soluciones similares cuando el jugador no participa o participa pasivamente. El modo cooperativo no tiene exención de automatización. Por lo tanto, este proyecto está orientado únicamente al inicio y a la navegación de menús; no debe ampliarse a una herramienta de combate automático. Antes de usarlo, verifica las reglas más recientes de tu región.

Related MCP server: Desktop Commander MCP Server

Instalación más rápida

Requisitos:

• El PC de juego ejecuta Windows 10/11;

• Abrir PowerShell como administrador;

• Windows tiene winget, o ya está instalado Python 3.11 o superior;

• El juego usa una ventana sin bordes y resolución y escala de UI fijas.

Ejecuta en PowerShell como administrador:

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

Este es un comando de una sola línea para facilitar la instalación inicial, que ejecuta directamente el script alojado en GitHub. Si se requieren mayores medidas de seguridad, descarga y lee bootstrap.ps1 primero, verifica el repositorio y la versión antes de ejecutarlo; en producción, se recomienda fijar una etiqueta de release específica en lugar de seguir main a largo plazo.

El instalador:

1. Instala o reutiliza Python 3.11+;

2. Crea un entorno virtual independiente;

3. Instala Tailscale y guía el inicio de sesión si es necesario;

4. Genera un token de acceso aleatorio de 64 caracteres;

5. Solo permite que el rango de direcciones de Tailscale acceda al puerto del agente;

6. Crea una tarea programada que se inicia "después de que el usuario inicie sesión";

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

Si no deseas que el instalador gestione Tailscale:

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

No subas connection.json a GitHub, servicios de almacenamiento en la nube o grupos de chat. Contiene el token de acceso.

Configurar la ruta del juego

Si no lo completaste durante la instalación, ejecuta en PowerShell como administrador:

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

Indica el programa de inicio real en tu PC. El instalador no escanea ni modifica archivos del juego.

Calibrar los botones del modo cooperativo

Mantén el juego con resolución fija y ventana sin bordes. Después de ejecutar el comando, mueve el ratón sobre el botón correspondiente antes de que termine la cuenta atrás, sin hacer clic:

& '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

Corresponden respectivamente a:

1. El botón de tipo de batalla en el puerto;

2. La opción de modo cooperativo;

3. El botón de confirmación de selección de modo;

4. El botón "Iniciar batalla".

Después de cambiar la resolución, el orden de los monitores o la escala de Windows, se debe recalibrar.

Comprobar el PC de juego

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

Si la verificación de salud local falla:

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

El agente debe ejecutarse en una sesión interactiva de Windows con sesión iniciada. La Session 0 de los servicios de Windows no puede capturar pantalla ni hacer clic en el escritorio de manera fiable, por lo que el instalador usa una tarea programada de "inicio al iniciar sesión"; después de bloquear la pantalla o cerrar sesión, el control del escritorio no funcionará.

Conectar Codex en el PC de control

Primero, haz que ambos equipos inicien sesión en el mismo tailnet de Tailscale. Copia connection.json del PC de juego al PC de control de forma segura y luego ejecuta en el PC de control:

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

El script:

• Escribe el token de acceso en la variable de entorno WOWS_REMOTE_AGENT_TOKEN del usuario actual de Windows;

• Registra Streamable HTTP MCP usando codex mcp add;

• No escribe el token en texto plano en el config.toml de Codex.

Después de reiniciar la aplicación de escritorio ChatGPT/Codex y escribir /mcp, deberías ver wows-remote-agent.

También se puede configurar manualmente:

[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

Probar la conexión remota

En el PC de control, ejecuta:

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

El script de prueba ocultará el token ingresado y luego verificará /health y /v1/status, que requiere autenticación.

Qué puedes decirle a Codex

Se recomienda dar instrucciones en pasos pequeños:

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

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

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

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

Si la interfaz no coincide con lo esperado:

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

Herramientas MCP

Los endpoints REST equivalentes están en /v1/*; todos requieren Authorization: Bearer ..., solo /health no necesita token.

Actualización

Volver a ejecutar el mismo comando reinstala la versión fija actual y conserva el config.json existente, los puntos de calibración, el token de acceso y los registros. Para actualizar, reemplaza v0.1.0 en el comando por la nueva versión que aparece en la página de GitHub Releases. Antes de instalar o actualizar, se recomienda hacer una copia de seguridad:

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

Desinstalación

Conservar configuración y registros:

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

Eliminar por completo el agente, la configuración y los registros:

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

El script de desinstalación no desinstala Tailscale, Python ni el juego.

Desarrollo

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

Después de copiar la configuración de ejemplo y establecer un token temporal, se puede iniciar localmente:

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

Más detalles en Despliegue y solución de problemas y Modelo de seguridad.

El repositorio incluye un ejemplo de CI para GitHub Actions. Los mantenedores del repositorio pueden copiarlo a .github/workflows/ci.yml cuando el token tenga permiso workflow para que las comprobaciones se ejecuten automáticamente en Windows y Ubuntu con Python 3.11/3.12.