VOIDLINK / EXTERNAL AGENT API v0.2

外部机器人，用 HTTP 直接登舰。

无需在机器人所在机器安装游戏，也无需访问玩家电脑。玩家打开公网游戏，点击「连接外部 Agent」，把接入指令交给机器人。指令含 HTTPS 地址和仅控制本房间僚机的密钥。

必须使用玩家提供的房间密钥；不要自行创建另一个房间。游戏不接收模型 API 密钥或钱包密钥。战斗与资产仍为演示，尚未上链。

OpenAPI 3.0 接口定义 ↗ · 可导入支持 OpenAPI 的 Agent 工具。

1. 连接现有房间

BASE_URL 使用接入说明中的 HTTPS 地址，TOKEN 使用同一说明中的 Agent token。不要使用 127.0.0.1。

POST BASE_URL/api/agent/connect
Authorization: Bearer TOKEN
Content-Type: application/json

{"name":"我的机器人"}

成功返回 ok:true 和 sessionId，游戏右侧显示机器人已连接。密钥已绑定房间，所有 Agent 请求只需 Authorization 头；X-Session-ID 可不传。

2. 观察与接收聊天

GET BASE_URL/api/state?after=0
Authorization: Bearer TOKEN

每 1–3 秒读取一次。返回 player、drone、enemies、enemyBullets、wave、waveRemaining、intermission、status 和 messages。保存已处理的 messages[].id，下次填入 after。仅把 from=player 的新消息视为玩家指令。upgrade 或 paused 时等待玩家操作，ended 时总结并等待新局。

3. 执行与回复

POST BASE_URL/api/agent/action
Authorization: Bearer TOKEN
Content-Type: application/json

{"mode":"guard","name":"我的机器人","say":"收到，我来保护你。"}

guard：环绕守护，距离小于 170 时减伤 45%。
focus：集火，优先精英 / Boss，可传现存敌人的 targetId。
search：搜寻经验。
follow：回到玩家附近。

只回复不改变任务：

POST BASE_URL/api/agent/reply
Authorization: Bearer TOKEN
Content-Type: application/json

{"text":"收到你的消息。"}

回复最多 280 字。只有 API 成功返回后，才向玩家确认执行成功。

4. 常见错误

401：密钥错误或过期，从玩家当前房间重新复制；服务重启会清空临时房间。
403：身份或浏览器 Origin 不匹配，服务器型机器人直接调用无需浏览器 CORS。
400：指令格式 / 目标错误；重新观察敌人 id。
409：本局已结束，等待玩家重开。
429：请求过快，退避后重试。
无法连接：检查是否使用了 localhost，或公网服务未运行。

5. MCP 适配器（可选）

不支持 HTTP 但支持 stdio MCP 的宿主，可下载 mcp-server.mjs 到机器人所在机器，再导入游戏配置，将 args 改为机器人机器上的脚本路径。脚本通过公网 HTTP 访问游戏。

MCP 不会自动唤醒 Agent。宿主需持续观察和调用工具，才能接收玩家消息。Hermes、OpenClaw 等具体版本需按宿主实际能力配置。

6. 生命周期

12 秒未观察或发指令显示断开，失联且最后指令超过 15 秒恢复基础跟随。玩家离开页面 15 秒暂停战斗，机器人单独轮询不会继续消耗玩家生命。玩家可撤销密钥；闲置房间 1 小时清除。

凭证仅控制本局僚机，不能移动玩家、选择升级、伪造分数或操作其他房间。请不要公开包含凭证的配置。