WoWS Remote Agent

Windows용 제한된 원격 제어 에이전트입니다. Codex 또는 MCP/HTTP를 지원하는 다른 AI가 Tailscale 사설 네트워크를 통해 다음 작업을 수행할 수 있게 합니다:

• 게임 PC와 《战舰世界》 프로세스 상태 확인;

• 현재 데스크톱 스크린샷 가져오기;

• 로컬에서 구성된 게임 프로그램 실행 및 포커스;

• 사용자가 로컬에서 보정한 메뉴 위치 클릭;

• 사전 검토된 메뉴 워크플로 실행;

• 로컬 Ctrl+Alt+F12 또는 원격 abort로 언제든지 긴급 중지.

이 프로젝트는 자동 조종, 조준, 사격, AFK 파밍 또는 탐지 회피 기능을 제공하지 않습니다. Wargaming 공식 프로젝트가 아니며 Wargaming과 관련이 없습니다.

보안 경계

에이전트에는 임의 셸, 임의 프로그램 실행 또는 파일 관리 인터페이스가 없습니다. 원격 측에서는 구성 파일에 유일하게 지정된 프로그램만 시작할 수 있으며, 키보드 화이트리스트에는 Enter, Esc, Tab, Space, 방향키 등의 메뉴 키만 포함되고 W/A/S/D는 포함되지 않습니다. 임의 단일 단계 클릭은 기본적으로 비활성화되어 있으며 로컬에서 구성된 워크플로만 허용됩니다.

모든 쓰기 작업은 다음에 기록됩니다:

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

start_battle 워크플로는 AI가 호출 시 confirmed=true를 전달하도록 요구합니다. 이것은 당신의 감독을 대체할 수 없습니다. 게임 PC 화면을 볼 수 있을 때만 사용하세요.

《战舰世界》규칙 5.07은 플레이어가 참여하지 않거나 수동적으로 참여하는 경우 봇, 클리커, 매크로 및 유사한 방식을 금지합니다. 협동 모드에는 자동화 면제가 없습니다. 따라서 이 프로젝트는 시작 및 메뉴 탐색만을 대상으로 하며 자동 전투 도구로 확장해서는 안 됩니다. 사용 전에 해당 지역의 최신 규칙을 직접 확인하세요.

Related MCP server: Desktop Commander MCP Server

빠른 설치

요구 사항:

• 게임 PC는 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을 먼저 다운로드하여 읽고 저장소와 버전을 확인한 후 실행하세요. 프로덕션 환경에서는 장기간 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'

사용자 PC의 실제 실행 프로그램을 입력하세요. 설치 프로그램은 게임 파일을 검사하거나 수정하지 않습니다.

협동 모드 버튼 보정

게임을 고정 해상도와 테두리 없는 창으로 유지하세요. 명령을 실행할 때마다 카운트다운이 끝나기 전에 마우스를 해당 버튼 위로 이동하되 클릭하지 마세요:

& '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 배율을 변경한 후에는 다시 보정해야 합니다.

게임 PC 확인

& '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 세션에서 실행되어야 합니다. Windows 서비스의 Session 0은 안정적으로 스크린샷을 찍거나 데스크톱을 클릭할 수 없으므로 설치 프로그램은 “로그인 시 시작” 예약 작업을 사용합니다. 잠금 화면 또는 로그아웃 상태에서는 데스크톱 제어가 작동하지 않습니다.

제어 PC에서 Codex 연결

먼저 두 PC가 동일한 Tailscale tailnet에 로그인하도록 하세요. 게임 PC의 connection.json을 제어 PC로 안전하게 복사한 다음 제어 PC에서 실행:

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

스크립트는 다음을 수행합니다:

• 액세스 토큰을 현재 Windows 사용자의 WOWS_REMOTE_AGENT_TOKEN 환경 변수에 기록합니다;

• codex mcp add를 사용하여 Streamable HTTP MCP를 등록합니다;

• 평문 토큰을 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

원격 연결 테스트

제어 PC에서 실행:

& .\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

자세한 내용은 배포 및 문제 해결과 보안 모델을 참조하세요.

저장소에는 GitHub Actions CI 예제가 포함되어 있습니다. 저장소 관리자는 토큰에 workflow 권한이 있을 때 이를 .github/workflows/ci.yml에 복사하면 Windows와 Ubuntu, Python 3.11/3.12에서 자동으로 검사를 실행할 수 있습니다.