WoWS Remote Agent

Windows向けの制限付きリモートコントロールエージェントです。CodexまたはMCP/HTTPに対応した他のAIが、Tailscaleプライベートネットワーク経由で以下の操作を行えるようにします：

• ゲームPCと『World of Warships』のプロセス状態を確認します；

• 現在のデスクトップのスクリーンショットを取得します；

• ローカルで設定されたゲームプログラムを起動し、フォーカスします；

• ユーザーがローカルでキャリブレーションしたメニュー位置をクリックします；

• 事前に審査されたメニューワークフローを実行します；

• いつでもローカルの Ctrl+Alt+F12 またはリモートの abort で緊急停止できます。

このプロジェクトは、自動操縦、照準、射撃、放置プレイ、アンチディテクション機能を提供しません。Wargaming公式プロジェクトではなく、Wargamingとは関連がありません。

安全境界

エージェントには、任意のシェル、任意のプログラム起動、ファイル管理インターフェースはありません。リモート側は設定ファイルで指定された唯一のプログラムのみ起動でき、キーボードのホワイトリストは Enter、Esc、Tab、Space、矢印キーなどのメニューキーのみで、W/A/S/D は含まれません。任意の単一クリックはデフォルトで無効になっており、ローカルで設定されたワークフローのみが許可されます。

すべての書き込み操作は次の場所に記録されます：

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

start_battle ワークフローでは、AI が呼び出し時に confirmed=true を渡すことも必要です。これはあなたの監督の代わりにはなりません。ゲームPCの画面を確認できる場合にのみ使用してください。

『World of Warships』ルール 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サービスのセッション0では、デスクトップのスクリーンショットやクリックを確実に行うことができないため、インストーラーは「ログイン時に起動」する予定タスクを使用します。ロック画面またはログアウト後は、デスクトップ操作は機能しません。

コントロールPCでCodexに接続する

まず2台の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 でチェックが自動的に実行されます。