WoWS Remote Agent

一个面向 Windows 的受限远程控制代理。它让 Codex 或其他支持 MCP/HTTP 的 AI 通过 Tailscale 私有网络完成以下操作：

• 查看游戏电脑和《战舰世界》进程状态；
• 获取当前桌面截图；
• 启动并聚焦本机配置的游戏程序；
• 点击用户在本机校准过的菜单位置；
• 执行预先审核过的菜单工作流；
• 随时通过本机 Ctrl+Alt+F12 或远程 abort 急停。

项目不提供自动驾驶、瞄准、开火、挂机刷取或反检测功能。它不是 Wargaming 官方项目，与 Wargaming 没有关联。

安全边界

代理没有任意 Shell、任意程序启动或文件管理接口。远程端只能启动配置文件中唯一指定的程序，键盘白名单只有 Enter、Esc、Tab、Space、方向键等菜单键，不包含 W/A/S/D。默认关闭任意单步点击，只允许本机配置的工作流。

所有写操作记录在：

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

start_battle 工作流还要求 AI 在调用时传入 confirmed=true。这不能代替你的监督；请只在你能看到游戏电脑屏幕时使用。

《战舰世界》规则 5.07 禁止在玩家不参与或被动参与时使用机器人、点击器、宏和类似方案。合作模式没有自动化豁免。因此本项目只面向启动与菜单导航，不应扩展成自动战斗工具。使用前请自行核对你所在地区的最新规则。

最快安装

要求：

• 游戏电脑运行 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 会话中。Windows 服务的 Session 0 无法可靠截图和点击桌面，所以安装器使用“登录时启动”的计划任务；锁屏或退出登录后，桌面控制不会工作。

在控制电脑上连接 Codex

先让两台电脑登录同一个 Tailscale tailnet。把游戏电脑上的 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'

脚本会：

• 把访问令牌写入当前 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

测试远程连接

在控制电脑运行：

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

测试脚本会隐藏输入令牌，然后验证 /health 与需要身份验证的 /v1/status。

可以对 Codex 说什么

建议按小步骤发出指令：

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

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

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

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

如界面和预期不同：

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

MCP 工具

工具	行为	默认是否改动电脑
get_status	游戏进程、工作流和急停状态	否
list_workflows	工作流是否完成校准	否
capture_screen	返回缩小后的 JPEG	否
launch_game	启动唯一配置的程序	是
focus_game	聚焦游戏窗口	是
run_workflow	执行本机配置的步骤	是
click_target	单击本机校准点，默认禁用	是
press_menu_key	点击菜单键，默认禁用	是
abort	停止工作流并释放白名单键	是

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 上自动运行检查。