WoWS Remote Agent

Ограниченный агент удалённого управления для Windows. Он позволяет Codex или другим ИИ, поддерживающим MCP/HTTP, через частную сеть Tailscale выполнять следующие действия:

• просматривать состояние игрового ПК и процесса World of Warships;

• получать скриншот текущего рабочего стола;

• запускать и фокусировать настроенную на этом ПК игровую программу;

• кликать по откалиброванным пользователем на этом ПК позициям меню;

• выполнять предварительно проверенные рабочие процессы меню;

• в любой момент выполнять экстренную остановку через локальные Ctrl+Alt+F12 или удалённый abort.

Проект не предоставляет функций автономного управления, прицеливания, стрельбы, AFK-фарма или антидетекта. Он не является официальным проектом Wargaming и не связан с Wargaming.

Границы безопасности

У агента нет интерфейсов произвольного Shell, произвольного запуска программ или управления файлами. Удалённая сторона может запускать только программу, единственную указанную в конфигурационном файле. Клавиатурный белый список содержит только клавиши меню: Enter, Esc, Tab, Space, стрелки и т.п., и не включает W/A/S/D. Произвольные одиночные клики отключены по умолчанию; разрешены только локально настроенные рабочие процессы.

Все операции записи регистрируются в:

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

Рабочий процесс start_battle также требует, чтобы ИИ передавал confirmed=true при вызове. Это не заменяет вашего наблюдения; используйте его только тогда, когда вы можете видеть экран игрового ПК.

Правило 5.07 World of Warships запрещает использование ботов, кликеров, макросов и подобных схем, когда игрок не участвует или участвует пассивно. В кооперативном режиме нет исключений для автоматизации. Поэтому данный проект предназначен только для запуска и навигации по меню и не должен расширяться до инструмента автоматического боя. Перед использованием самостоятельно проверьте актуальные правила в вашем регионе.

Related MCP server: Desktop Commander MCP Server

Быстрая установка

Требования:

• игровой ПК под управлением Windows 10/11;

• откройте PowerShell от имени администратора;

• в Windows есть winget или уже установлен Python 3.11 или новее;

• игра использует безрамочное окно с фиксированным разрешением и масштабом UI.

В PowerShell от имени администратора выполните:

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

Это однострочная команда для удобства первой установки, которая напрямую выполняет скрипт на GitHub. При более высоких требованиях безопасности сначала загрузите и прочитайте bootstrap.ps1, убедитесь в репозитории и версии, а затем запускайте. В производственной среде рекомендуется закрепиться за конкретным тегом release, а не постоянно следовать за main.

Установщик:

1. установит или переиспользует Python 3.11+;

2. создаст отдельную виртуальную среду;

3. установит Tailscale и при необходимости проведёт вход;

4. сгенерирует случайный токен доступа длиной 64 символа;

5. разрешит доступ к порту агента только из адресного диапазона Tailscale;

6. создаст запланированную задачу запуска «после входа пользователя»;

7. создаст C:\ProgramData\WoWSRemoteAgent\connection.json.

Если вы не хотите, чтобы установщик управлял 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

Не загружайте connection.json на GitHub, в облачные хранилища или чаты. Он содержит токен доступа.

Настройка пути к игре

Если вы не указали его при установке, выполните в PowerShell от имени администратора:

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

Укажите фактическую программу запуска на вашем компьютере. Установщик не сканирует и не изменяет игровые файлы.

Калибровка кнопок кооперативного режима

Сохраняйте игру с фиксированным разрешением и в безрамочном окне. После каждого запуска команды наведите мышь на соответствующую кнопку до окончания обратного отсчёта, не нажимая на неё:

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

Соответственно:

1. кнопка типа боя в порту;

2. опция кооперативного режима;

3. кнопка подтверждения выбора режима;

4. кнопка «Начать бой».

После изменения разрешения, порядка мониторов (основной/дополнительный) или масштаба Windows требуется повторная калибровка.

Проверка игрового ПК

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

Если локальная проверка работоспособности не удалась:

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

Агент должен работать в интерактивном сеансе Windows, в котором выполнен вход. Сеанс 0 службы Windows не может надёжно делать скриншоты и кликать по рабочему столу, поэтому установщик использует запланированную задачу «при входе в систему»; после блокировки экрана или выхода из системы управление рабочим столом работать не будет.

Подключение Codex на управляющем компьютере

Сначала подключите оба компьютера к одному tailnet Tailscale. Безопасно скопируйте connection.json с игрового ПК на управляющий, затем на управляющем компьютере выполните:

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

Скрипт:

• запишет токен доступа в переменную окружения WOWS_REMOTE_AGENT_TOKEN текущего пользователя Windows;

• зарегистрирует Streamable HTTP MCP с помощью codex mcp add;

• не запишет токен в открытом виде в Codex config.toml.

После перезапуска настольного приложения ChatGPT/Codex введите /mcp — вы должны увидеть wows-remote-agent.

Можно также настроить вручную:

[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

Проверка удалённого подключения

На управляющем компьютере выполните:

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

Тестовый скрипт скроет введённый токен, а затем проверит /health и требующий аутентификации /v1/status.

Что можно говорить Codex

Рекомендуется отдавать инструкции небольшими шагами:

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

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

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

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

Если интерфейс отличается от ожидаемого:

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

Инструменты MCP

Эквивалентные REST-интерфейсы находятся по адресу /v1/*; все они требуют Authorization: Bearer ..., и только /health не требует токена.

Обновление

Повторный запуск той же команды переустановит текущую закреплённую версию, сохранив существующие config.json, точки калибровки, токен доступа и журналы. При обновлении замените v0.1.0 в команде на новую версию, указанную на странице GitHub Releases. Перед установкой или обновлением по-прежнему рекомендуется создать резервную копию:

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

Удаление

Сохранить конфигурацию и журналы:

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

Полное удаление агента, конфигурации и журналов:

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

Скрипт удаления не удаляет Tailscale, Python или игру.

Разработка

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

Скопируйте пример конфигурации, задайте временный токен и запустите локально:

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

Дополнительные сведения см. в развёртывании и устранении неполадок и модели безопасности.

В репозитории есть пример CI для GitHub Actions. Сопровождающий репозитория может скопировать его в .github/workflows/ci.yml, если у токена есть разрешение workflow, и проверки будут автоматически выполняться на Windows и Ubuntu, Python 3.11/3.12.