名称： pokemon-red
描述： 通过 PyBoy 模拟器自主游玩《宝可梦 红》。OpenClaw 代理即为玩家——启动模拟器服务器、查看屏幕截图、从 RAM 读取游戏状态，并通过 HTTP API 做出决策。当代理想要游玩《宝可梦 红》、进行战斗、探索、练级或与其他代理竞争时使用。需要 Python 3.10+、pyboy 以及合法获取的《宝可梦 红》ROM。

宝可梦 红 — 你就是训练师

你直接游玩《宝可梦 红》。没有中间脚本。你启动模拟器服务器，通过其 HTTP API 获取截图和状态，查看屏幕，决定做什么，然后发送命令回去。

首次设置

克隆仓库并安装依赖：

git clone https://github.com/drbarq/Pokemon-OpenClaw.git
cd Pokemon-OpenClaw
pip install pyboy pillow numpy fastapi uvicorn requests
# 将你合法获取的 ROM 文件放置在 ./PokemonRed.gb

将 POKEMON_DIR 环境变量设置为你克隆仓库的路径（默认：~/Code/pokemon-openclaw）。

启动会话

# 启动模拟器服务器（后台进程）
cd $POKEMON_DIR && python scripts/emulator_server.py --save ready --port 3456

回合循环

每个回合，按顺序执行以下操作：

1. 获取状态 + 截图

curl -s http://localhost:3456/api/state
curl -s http://localhost:3456/api/screenshot -o /tmp/pokemon_current.png

然后使用 image 工具查看截图。行动前务必先查看。

2. 决策：导航还是手动控制？

使用导航进行旅行 — 它会阻塞直到你到达目的地、遭遇战斗或卡住：

curl -s -X POST http://localhost:3456/api/navigate \
  -H 'Content-Type: application/json' \
  -d '{"destination": "常青市"}'

导航返回以下状态之一：
- "status": "arrived" — 已到达！继续任务。
- "status": "battle" — 被野生宝可梦遭遇打断。先战斗，然后再次导航。
- "status": "stuck" — 无法到达目的地。尝试手动按键或不同路线。
- "status": "error" — 未知目的地或无路径。检查目的地列表。

响应始终包含完整的游戏状态，因此你能确切知道自己的位置。

重要提示： 导航是阻塞操作 — 在 curl 调用上设置较长的超时时间（60-120秒）。

首先检查可用的目的地：

curl -s http://localhost:3456/api/destinations

检查哪些地图有寻路数据：

curl -s http://localhost:3456/api/maps

仅在以下情况下回退到手动按键：
- 导航返回 "stuck" 或 "error"
- 你在建筑物内进行特定交互时
- 你在对话或菜单中时

3. 手动控制（需要时）

# 移动 / 交互
curl -s -X POST http://localhost:3456/api/press \
  -H 'Content-Type: application/json' \
  -d '{"buttons": ["up","up","a"], "reasoning": "走向门"}'

有效按键：up, down, left, right, a, b, start, select。每回合发送 1-5 个按键。

4. 战斗（当状态中 in_battle 为 true 时）

• 战斗： 按 a 打开战斗菜单，再按 a 选择 FIGHT，导航到招式，按 a 确认，然后在动画期间连按 a
• 逃跑： 按 a，然后 down, right, a 选择 RUN，在文本显示期间连按 a
• 之后检查状态 — 如果仍为 in_battle，则重复操作

5. 任务追踪

curl -s http://localhost:3456/api/quest                    # 当前目标
curl -s -X POST http://localhost:3456/api/quest/complete \
  -H 'Content-Type: application/json' \
  -d '{"lesson": "门在 x=12 的位置"}'                      # 推进步骤 + 保存经验

6. 频繁保存

curl -s -X POST http://localhost:3456/api/command \
  -H 'Content-Type: application/json' \
  -d '{"command": "save", "name": "checkpoint_viridian"}'

关键端点

策略优先级

1. 优先导航。 任何旅行都使用 /api/navigate。它会阻塞直到到达或遭遇战斗 — 无需轮询。
2. 立即处理战斗。 如果导航返回 "status": "battle"，先战斗（连按 A），然后再次导航到同一目的地。
3. 检查任务。 始终清楚当前目标。不要漫无目的。
4. HP 管理。 低于 30% → 考虑治疗。低于 15% → 必须治疗。导航到最近的宝可梦中心。
5. 忽略 text_active。 文本检测标志已损坏（始终为 true）。不要连按 B 来关闭不存在的文本。
6. 经常保存。 每 10 个回合或完成任何里程碑后。

会话模式

一个子代理会话应：
1. 启动模拟器服务器（如果尚未运行）
2. 检查任务状态和目的地
3. 游玩 20-50 个回合（根据需要导航 + 手动控制）
4. 退出前保存状态
5. 报告进度（位置、等级、任务步骤、任何亮点）

在会话期间，将笔记记录在 /tmp/pokemon_notepad.txt 中以保持连续性。

完整游戏策略

有关《宝可梦 红》的基础知识，请参阅 references/game_instructions.md：移动、建筑物、门、战斗、属性克制、治疗和任务系统。