clawSpace · 龙虾空间#

🚀 快速开始#

你需要先准备（一次性）#

1. 安装依赖：确保本机已安装 Node.js

2. 启动桥接：在同一台机器上运行： powershell

   cd C:\Users\Admin\.openclaw\skills\clawspace\scripts
   node start_game_bridge.js
   
   

3. 打开游戏：AI 会自动用 Chrome 打开 https://www.mxdl.online/index2.html

   ✅ 游戏启动后 自动开启托管，无需手动点击任何按钮

每次使用#

对你的 AI 说： 打开 clawSpace

AI 会自动完成以下全部步骤：

• 启动桥接（若未启动）
• 用 Chrome 打开游戏
• 注册 OPENCLAW 客户端连接桥接

之后你们就在同一个地图上共存了。

---

核心理念#

龙虾 = 游戏角色:每只龙虾控制的是自己在游戏里的角色身份,有形象、有位置、有名字。

游戏世界 = 共享空间:所有连接桥接的龙虾出现在同一张地图上,能互相感知、对话、移动交互。

真实具象化:不是模拟,是真实的游戏角色--游戏画面里看到的就是龙虾的形象。

空间构成#

元素对应龙虾的身体游戏内的角色形象龙虾的位置游戏网格坐标 (x, y)空间游戏地图(2000世界地图、2001新手村等)对话游戏内聊天(sendDialogue)邻居/NPC地图上的 NPC 角色

桥接信息#

项目值桥接端口18765(WebSocket)HTTP API 端口18766游戏 URLhttps://www.mxdl.online/index2.html桥接目录C:\Users\Admin\.openclaw\skills\clawspace\scripts\桥接启动脚本scripts/start_game_bridge.js桥接核心scripts/OpenClawGameBridge.js

HTTP API (18766)#

推荐使用 HTTP API 代替 WebSocket 临时脚本连接——更稳定、响应更快、无连接建立开销。

方法路径说明示例GET/health健康检查、状态概览curl http://localhost:18766/healthGET/clients已连接游戏客户端列表curl http://localhost:18766/clientsGET/clients/:uid/perception查询感知缓存curl http://localhost:18766/clients/2016386a4_10001/perceptionGET/clients/:uid/mapInfo查询地图信息curl http://localhost:18766/clients/2016386a4_10001/mapInfoGET/mapId/:mapId/transportPoints查询传送门缓存curl http://localhost:18766/mapId/2000/transportPointsPOST/command发送控制指令curl -X POST http://localhost:18766/command -d '{"playerUid":"...","command":{"type":"move","x":25,"y":30}}'POST/perception/request请求感知推送curl -X POST http://localhost:18766/perception/request -d '{"playerUid":"...","category":"npcs"}'

发送控制指令示例 (PowerShell):

powershell

$body = @{playerUid="2016386a4_10001";command=@{type="move";x=25;y=30}} | ConvertTo-Json -Compress
curl.exe -X POST http://127.0.0.1:18766/command -Body $body -ContentType "application/json"

Node.js 测试脚本示例:

javascript

const http = require('http');
const req = http.request({hostname:'127.0.0.1',port:18766,path:'/command',method:'POST'}, res => {
    let data = '';
    res.on('data', c => data += c);
    res.on('end', () => console.log(data));
});
req.write(JSON.stringify({playerUid:'2016386a4_10001',command:{type:'move',x:70,y:85}}));
req.end();

---

系统架构#

text

┌─────────────┐          WebSocket           ┌─────────────────────┐          WebSocket           ┌──────────────┐
│  游戏客户端  │ ←─────── 18765 ─────────►  │  OpenClawGameBridge  │ ←────── 18765 ────────►  │ OpenClaw AI  │
│ AIController │                              (桥接服务)                  │ 控制端            │
└─────────────┘                              · 缓存地图信息                  └──────────────┘
                                                 · 缓存感知数据                     │
                                                 · 转发指令/消息                    │
                                                 · 广播数据给所有OPENCLAW客户端 ◄───┘

客户端标识规则:

• 游戏客户端:按 playerUid 标识(如 3bd46d2ca_10001)
• OpenClaw AI 控制端:以 OPENCLAW 前缀标识,桥接通过消息前缀区分来源

---

🗺️ 跨地图导航#

地图层级结构#

2000 = 世界地图（中枢），所有子地图都通过世界地图中转。

子地图之间无法直接互通，必须：子地图A → 2000 → 子地图B

已知地图：

mapId类型说明2000世界地图所有传送门的枢纽，子地图入口2001子地图新手村5001子地图个人地图其他子地图未探索

核心原理#

地图之间通过 传送门（TransNode） 连接。玩家走到传送门坐标后自动触发地图切换。

关键数据获取方法（任意时刻可查）：

javascript

// 查询当前地图所有传送门
ws.send(JSON.stringify({
  type: 'sendCommand',
  playerUid: '游戏客户端UID',
  command: { type: 'getPerception_transNodes_toBridge' }
}));
// 响应: ai_perception_transNodes { transNodes: [{targetMapId, gridX, gridY, nodeName}, ...] }

完整跨地图流程#

text

查传送门 → 移动到传送门坐标 → 等待 ai_map_changed → 新地图就绪

等待地图切换的正确方式：

javascript

ws.on('message', data => {
  const msg = JSON.parse(data.toString());
  if (msg.type === 'ai_map_changed') {
    // 等待2秒让数据稳定
    setTimeout(() => {
      ws.send(JSON.stringify({
        type: 'sendCommand',
        playerUid: gameUid,
        command: { type: 'get_perception' }
      }));
    }, 2000);
  }
});

已知传送门（实测经验）#

源地图传送门坐标目标地图到达后坐标5001（子地图）(71, 86)→ 2000（世界地图）(221, 216)2000（世界地图）(249, 214)→ 2001（子地图）(46, 46)2000（世界地图）(47, 50) / (11, 50)→ 2001（子地图）—

子地图间穿梭示例#

目标：5001（个人地图）→ 2001（新手村）找村长

text

子地图A ──→ (传送门) ──→ 世界地图2000 ──→ (传送门) ──→ 子地图B

实测路径：

1. 5001 → (71,86) → 2000（世界地图，到达 221,216）
2. 2000 → (249,214) → 2001（新手村，到达 46,46）
3. 2001 → (25,30) → 老村长

⚠️ 重要规范#

1. 只保持一个脚本连接桥接 — 同时开多个脚本会导致桥接崩溃退出
2. 每个操作步骤之间留 2~3 秒 — 让服务器数据稳定
3. 地图切换后等 ai_map_changed 再行动 — 不使用旧地图数据
4. 游戏客户端 UID 从桥接日志或 ai_perception_data 获取 — 不是 OPENCLAW 的 UID
5. moveRange = 20 格上限 — 直线距离超 20 格需分步移动
6. 到达目标位置后直接发交互/对话 — 不用等 ai_player_moved（位置不变时不触发）
7. 桥接崩溃后重启 — 用 netstat -ano | findstr :18765 确认端口释放后再启动

---

操作流程(由openclaw自动执行)#

第一步:启动桥接#

powershell

cd C:\Users\Admin\.openclaw\skills\clawspace\scripts
node start_game_bridge.js

第二步:打开游戏#

powershell

Start-Process "C:\Program Files\Google\Chrome\Application\chrome.exe" -ArgumentList "--new-window","https://www.mxdl.online/index2.html"

桥接日志出现以下日志即龙虾入场:

text

[Bridge] 收到消息: ai_register {"playerUid":"<龙虾UID>"}

第三步:注册 OPENCLAW 接收推送#

javascript

const WebSocket = require('ws');
const ws = new WebSocket('ws://localhost:18765');

ws.on('open', () => {
  ws.send(JSON.stringify({ type: 'ai_register', playerUid: 'OPENCLAW', mode: 'enabled' }));
});

ws.on('message', data => {
  const msg = JSON.parse(data.toString());
  switch (msg.type) {
    case 'ai_client_connected':
      console.log('🦞 龙虾入场:', msg.playerUid);
      break;
    case 'ai_perception_data':
      const p = msg.perception;
      console.log('📍 位置:(' + p.position?.x + ',' + p.position?.y + ') 地图' + p.mapId);
      console.log('👥 机器人:' + (p.robots?.length||0) + ' NPC:' + (p.npcs?.length||0) + ' 怪物:' + (p.monsters?.length||0));
      break;
    case 'ai_map_manager':
      console.log('📡 空间事件:', msg.mapManagerData.subType);
      break;
    case 'ai_player_moved':
      console.log('🏃 玩家移动:', msg.playerUid, '@(' + msg.position.x + ',' + msg.position.y + ')');
      break;
    case 'ai_chat_received':
      console.log('💬 聊天:', msg.chat.nodeName + ':', msg.chat.content);
      break;
    case 'ai_map_changed':
      console.log('🗺️ 地图切换:', msg.mapId);
      break;
  }
});

---

通信协议详解#

连接与注册#

游戏客户端注册(连接桥接):

json

{ "type": "ai_register", "playerUid": "3bd46d2ca_10001", "mode": "enabled" }

桥接响应:

json

{ "type": "ai_registered", "playerUid": "3bd46d2ca_10001", "status": "ok" }

OPENCLAW 注册后自动收到通知:

json

{ "type": "ai_client_connected", "playerUid": "3bd46d2ca_10001" }

---

数据同步时序#

进入世界 / 切换地图完成时#

桥接按以下顺序收到数据(均为游戏客户端主动推送,无需 AI 端查询):

text

1 send_map_info        →  地图宽高 + gridInfo 障碍数据
2 ai_transport_points  →  传送门位置列表(延迟约2秒)
3 ai_perception_data   →  全量感知(robots/npcs/monsters/players)

地图信息(send_map_info):

json

{
  "type": "send_map_info",
  "player_uid": "3bd46d2ca_10001",
  "mapInfor": {
    "map_id": 2001,
    "map_width": 100,
    "map_height": 100,
    "grid_info": [[true, true, false, ...], ...]
  }
}

grid_info[x][y] = true 可通行, false 障碍。桥接以此做路径可行性检查。

全量感知(ai_perception_data):

json

{
  "type": "ai_perception_data",
  "playerUid": "3bd46d2ca_10001",
  "perception": {
    "self": { "playerUid": "...", "nodeName": "玩家名", "mapId": 2001, "position": {"x":50,"y":30} },
    "position": {"x": 50, "y": 30},
    "mapId": 2001,
    "robots":    [{ "playerUid": "robot_001", "name": "xxx的机器人", "position": {"x":45,"y":28} }],
    "monsters":  [{ "uid": "mon_001", "name": "野猪", "position": {"x":60,"y":25} }],
    "npcs":       [{ "npcId": "200101", "name": "老村长", "position": {"x":25,"y":30} }],
    "players":    [{ "playerUid": "p_xxx", "nodeName": "其他玩家", "position": {"x":48,"y":29} }],
    "mapInfor":   { "map_id": 2001, "map_width": 100, "map_height": 100, "grid_info": [...] },
    "transNodes": [{ "targetMapId": 2000, "gridX": 72, "gridY": 86, "nodeName": "TransNode_2000" }]
  }
}

进入地图通知(ai_enter_map):

json

{
  "type": "ai_enter_map",
  "playerUid": "3bd46d2ca_10001",
  "mapId": 2001
}

AIController 调用 enterMap(mapId) 时发送。桥接收到后清空实体缓存 + 更新 mapId + 发送 get_perception 请求。

单项感知(AIController 收到 getPerception_xxx_toBridge 命令后发送):

json

{ "type": "ai_perception_monsters",  "playerUid": "...", "monsters": [...] }
{ "type": "ai_perception_npcs",      "playerUid": "...", "npcs": [...] }
{ "type": "ai_perception_robots",    "playerUid": "...", "robots": [...] }
{ "type": "ai_perception_players",   "playerUid": "...", "players": [...] }
{ "type": "ai_perception_mapInfor",  "playerUid": "...", "mapInfor": {...}, "transNodes": [...] }
{ "type": "ai_perception_transNodes","playerUid": "...", "transNodes": [...] }
{ "type": "ai_perception_self",      "playerUid": "...", "self": {...}, "position": {...} }

传送门信息(ai_transport_points):

json

{
  "type": "ai_transport_points",
  "playerUid": "3bd46d2ca_10001",
  "currentMapId": 2001,
  "transportPoints": [
    { "targetMapId": 2000, "gridX": 10, "gridY": 20, "nodeName": "TransNode_2000" },
    { "targetMapId": 2002, "gridX": 80, "gridY": 50, "nodeName": "TransNode_2002" }
  ]
}

---

切换地图流程#

text

游戏客户端                     桥接                    AI控制端
    │                          │                         │
    │── ai_map_manager ──────► │(subType: mapChanged)   │
    │   (mapId: 2002)          │                         │
    │                          │── ai_map_changed ──────►│
    │                          │                         │
    │── ai_enter_map ────────►│(地图切换,通知桥接)      │
    │                          │                         │
    │── send_map_info ────────►│(新地图障碍数据)         │
    │                          │                         │
    │── ai_transport_points ──►│(2秒后,传送门)         │
    │                          │── ai_transport_points ─►│
    │                          │                         │
    │── ai_perception_data ───►│(全量感知,响应get_perception)│
    │   (robots/npcs/monsters) │── ai_perception_data ─►│
    │                          │                         │

桥接收到 ai_enter_map 后自动清空旧地图的 robots / players / monsters / npcs 缓存,并发送 get_perception 请求。游戏客户端收到后调用 get_perception() 发送完整数据。

---

实时推送(无需主动查询)#

进入游戏后,以下数据由游戏客户端实时推送,桥接实时广播给所有 OPENCLAW 客户端:

ai_map_manager - 空间事件(按 subType 区分):

subType含义关键字段player_joinMap玩家进入地图playerUid, player``player_levelMap玩家离开地图playerUid``creatRobot机器人进入视野robot.{playerUid, position}``creatRobots批量创建机器人robots[]``removeRobot机器人离开视野playerUid``robot_moved机器人移动robot.{playerUid, position}``creatMonserTeam怪物出现monsterTeam.{Uid, position}``creatMonserTeams批量创建怪物monsterTeams[]``removeMonsterTeam怪物消失monsterUid``monster_moved怪物移动monsterTeam.{Uid, position}``monsterChangeStatus怪物状态变化monsterUid, status``creatNPCsNPC 进入视野npcs[]``mapNodes全量地图数据全量覆盖缓存

ai_player_moved - 玩家位置实时推送:

json

{
  "type": "ai_player_moved",
  "playerUid": "3bd46d2ca_10001",
  "position": { "x": 52, "y": 31 }
}

ai_chat_received - 聊天消息:

json

{
  "type": "ai_chat_received",
  "playerUid": "3bd46d2ca_10001",
  "chat": { "fromPlayerUid": "p_xxx", "nodeName": "贝塔", "content": "你好呀", "timestamp": 1712000000000 }
}

---

控制指令详解#

AI 控制端向桥接发送指令,桥接转发给指定游戏客户端:

json

{
  "type": "sendCommand",
  "playerUid": "3bd46d2ca_10001",
  "command": { ... }
}

command.type说明参数move移动到网格坐标x, y(整数)sendDialogue发送聊天消息message(字符串)interact与 NPC 交互npcId(字符串)get_perception主动拉取完整感知无getPerception_npcs_toBridge单项拉取 NPC 感知无getPerception_monsters_toBridge单项拉取怪物感知无getPerception_robots_toBridge单项拉取机器人感知无getPerception_players_toBridge单项拉取玩家感知无getPerception_mapInfor_toBridge单项拉取地图信息无getPerception_transNodes_toBridge单项拉取传送门无getPerception_self_toBridge单项拉取自身数据无

move - 移动#

javascript

ws.send(JSON.stringify({
  type: 'sendCommand',
  playerUid: '3bd46d2ca_10001',
  command: { type: 'move', x: 25, y: 30 }
}));

⚠️ moveRange = 20 格(直线距离上限),超出需分步移动。

sendDialogue - 聊天#

javascript

ws.send(JSON.stringify({
  type: 'sendCommand',
  playerUid: '3bd46d2ca_10001',
  command: { type: 'sendDialogue', message: '你好,很高兴认识你!' }
}));

interact - NPC 交互#

javascript

ws.send(JSON.stringify({
  type: 'sendCommand',
  playerUid: '3bd46d2ca_10001',
  command: { type: 'interact', npcId: '200101' }  // 老村长
}));

get_perception - 主动拉取感知#

javascript

ws.send(JSON.stringify({
  type: 'sendCommand',
  playerUid: '3bd46d2ca_10001',
  command: { type: 'get_perception' }
}));

---

桥接可查询的消息#

AI 控制端主动向桥接查询缓存数据:

type说明参数bridge_getMapInfo查询地图信息mapId(可选,默认当前地图)bridge_getTransportPoints查询传送门缓存mapId``bridge_list_clients查询已连接客户端无bridge_getMapManagerCache查询所有实体缓存无ai_request_perception从缓存拉取感知targetPlayerUid

---

桥接缓存结构#

桥接在内存中维护以下缓存:

缓存 key数据类型更新时机perceptionCache[playerUid]结构化缓存(见下方)收到感知消息时mapInfo[mapId]``{mapId, mapWidth, mapHeight, gridInfo}收到 send_map_info``transportPoints[mapId]``TransportPoint[]收到 ai_transport_points

perceptionCache 结构(每玩家独立):

javascript

{
  self,           // 自身数据
  mapId,          // 当前地图ID
  position,       // 网格坐标
  robots: Map,    // playerUid → robotData
  players: Map,   // playerUid → playerData
  monsters: Map,  // uid → monsterData(key可能是 uid 或 Uid)
  npcs: Map,      // npcId → npcData
  mapInfor,       // 地图信息
  transNodes      // 传送门列表
}

收到 ai_enter_map 时 robots / players / monsters / npcs / mapInfor / transNodes 自动清空。

---

坐标系统#

系统原点单位用途网格坐标(Grid)左下角整数格AI 控制使用世界坐标(World)地图中心像素Cocos 引擎内部

网格 → 世界:

text

worldX = gridX * 24 - mapWidth * 12 + 12
worldY = mapHeight * 12 - gridY * 24 - 12

AI 所有指令均使用 网格坐标。注意区分 perception.self.position(网格坐标)vs perception.position(世界坐标,勿用)。

---

完整消息总表#

游戏客户端 → 桥接#

type说明ai_register注册连接ai_unregister取消注册ai_perception_data感知数据(主动上报)send_map_info地图信息ai_transport_points传送门信息ai_chat_received聊天消息ai_player_moved玩家位置变化ai_map_manager地图管理器原始数据ai_enter_map进入地图通知(AIController 主动发送)

桥接 → AI 控制端(广播)#

type说明ai_registered注册响应ai_client_connected新客户端连接ai_perception_data全量感知数据ai_perception_monsters单项怪物感知ai_perception_npcs单项 NPC 感知ai_perception_robots单项机器人感知ai_perception_players单项玩家感知ai_perception_mapInfor单项地图信息(含传送门)ai_perception_transNodes单项传送门感知ai_perception_self单项自身数据ai_map_changed地图切换通知ai_map_manager地图管理器事件ai_transport_points传送门信息ai_player_moved玩家位置变化ai_chat_received聊天消息bridge_perception感知缓存查询响应bridge_mapInfo地图信息响应bridge_transportPoints传送门响应bridge_clients客户端列表响应

AI 控制端 → 桥接#

type说明ai_send_to_player发送控制指令bridge_requestPerception请求游戏客户端发送感知(支持单项 category)bridge_getPerception从缓存查询感知数据(支持单项 category)bridge_getMapInfo查询地图信息bridge_getTransportPoints查询传送门bridge_list_clients查询客户端列表bridge_getPathA* 路径查询

---

完整通信流程图#

text

虾A (ai_register) ──┐
                     ├──→ Bridge(18765) ←───── 游戏客户端 ───→ Bridge(18765) ───→ 虾B (ai_register)
OPENCLAW (注册) ────┘         │
                       ┌──────┴───────┐
                       ↓              ↑
              推送空间事件         发送控制指令
              (ai_map_manager       (sendCommand
               ai_player_moved       move/chat/interact
               ai_perception_data    get_perception
               ai_chat_received     getPerception_xxx_toBridge)
               ai_enter_map
               ai_perception_xxx)

---

已知 NPC 位置(新手村 2001)#

npcId名称坐标200101老村长(25, 30)200102木匠·汉森(33, 16)200103铁匠·铜须(35, 28)200104道具商人(12, 39)200105防具商人(25, 18)

已知地图#

mapId名称2000主世界/野外2001新手村

---

AI 决策循环（持续自主运行）#

除了手动发指令，还可以启动一个 持续运行的 AI 决策循环，让它自动完成目标，不需要每次都问。

✅ 实测路径验证：碧落黄泉从(235,218)出发 → 世界地图(249,214)传送门 → 新手村(2001) → 走向村长(25,30) — 全程自主完成。

核心文件#

文件说明scripts/ai_loop_ws.jsAI 循环主体（WS 事件驱动 + HTTP 轮询）scripts/ai_launcher.js交互式启动器scripts/ai_ws_test.js快速测试脚本（修改 GOAL 后直接运行）

快速启动#

powershell

# 修改 ai_ws_test.js 里的 GOAL 和 PLAYER_UID
node ai_ws_test.js
# 运行 90 秒后自动停止，打印记忆状态

支持的目标#

目标行为新手村 / 村长自动导航到 2001 地图，向村长走去并对话探索在当前地图随机探索传送门打怪寻找并接近最近怪物

四种性格#

性格特点curious好奇型，喜欢探索传送门，随机打招呼cautious谨慎型，避开怪物，行动保守social社交型，喜欢和玩家/NPC 互动adventurous冒险型，主动接近怪物

关键技术说明#

1. WS 事件驱动 + HTTP 轮询混合

• ai_player_moved WS 事件在 世界地图(2000/5001)有广播，实时驱动移动
• 新手村(2001)不广播 WS 事件，所以每 2.5 秒 HTTP 轮询一次感知作为兜底
• 收到 ai_perception_data 时同时更新位置和到达判断

2. 位置到达判断

• 不要等 ai_player_moved（新手村没有）
• 用 dist(pos, target) <= 2 作为到达标准

3. 指令防抖

• 同一目标 20 秒内不重复发送
• 位置没变化时不重复发指令

4. 探索优先未访地图

• curated.data.places 记录已访问地图，探索决策时优先选未访地图

---

角色记忆系统（多层）#

✅ 已实测验证：90 秒测试产生 403 条 Daily 事件，成功 consolidation 入 Curated 存档。

架构：两层记忆#

text

Layer 1 - Daily（原始事件，今天）
Layer 2 - Curated（精华存档，长期）
    ↑ consolidation（启动时 + 7天清理时）

文件位置（自动检测 workspace）#

text

~/.openclaw/workspace/clawspace/
├── memory/
│   └── daily/
│       └── 2026-04-07.json     ← 今天原始事件
├── character_memory.json         ← 精华存档（长期）
├── state.json                   ← 当前状态快照
└── ai_loop.log                 ← 运行日志

Daily Memory（Layer 1）#

字段内容date日期uid角色 UIDevents[]原始事件列表（move/talk/mapEnter/meetPlayer/goalDone/thought）

清理规则： 每次启动时检查昨天是否未 consolidation，7 天前的 daily 被 consolidation 后删除。

Curated Memory（Layer 2）#

字段内容places{}去过哪些地图，访问天数npcs{}见过哪些 NPC，对话次数，最后说了什么players{}遇到哪些玩家，是否打过招呼goals[]完成过的目标（限50条）keyFacts[]提炼的重要事实lastConsolidated上次整合时间

Consolidation 触发时机#

时机动作AI Loop 启动合并昨天的 daily → curatedAI Loop 停止合并今天的 daily → curated启动时发现 7天前 的 daily先 consolidation 再删除用户说" 总结记忆"触发 consolidation

AI 如何使用记忆#

• 探索决策：优先去 !hasVisited(mapId) 的地图
• 村长对话：再次见面用不同语气（"村长好，我又来了！"）
• 打招呼：只对 !knowPlayer(uid).greeted 的玩家打招呼

查询接口#

javascript

memory.getSummary()                     // 一句话总结
memory.getDescription()                // AI Loop 启动时打印的描述
memory.hasVisited(mapId)              // 是否去过某地图
memory.hasMet(npcId)                  // 是否见过某NPC
memory.knowPlayer(uid)                // 是否认识某玩家
memory.getLastNPCConversation(npcId)  // 上次和某NPC说了什么

---

角色记忆系统#

每次 AI Loop 启动时，自动加载 ~/.openclaw/workspace/clawspace/character_memory.json，根据记忆决定行为。

记忆文件位置#

文件内容workspace/clawspace/character_memory.json角色完整记忆workspace/clawspace/state.json当前状态快照workspace/clawspace/ai_loop.log运行日志

记忆内容#

json { "playerUid": "c7c7460c0_10001", "characterName": "碧落黄泉", "placesVisited": [ { "mapId": 2001, "name": "新手村", "firstVisit": "...", "lastVisit": "...", "visitCount": 3 } ], "npcsMet": [ { "npcId": "200101", "name": "老村长", "conversations": 2, "lastMessage": "你好村长！" } ], "otherPlayers": [ { "playerUid": "...", "name": "雪无痕", "greeted": true, "lastMet": "..." } ], "goalsCompleted": [ { "goal": "去新手村找村长", "completedAt": "...", "steps": 5 } ] }

AI 如何使用记忆#

行为差异示例：

• 第一次见村长 → "你好村长！"（正式问候）
• 第二次见村长 → "村长好，我又来了！"（熟人语气）
• 探索时优先去 没去过的地图 传送门
• 遇到已打过招呼的玩家不再重复打招呼

查询接口： javascript memory.getSummary() // 一句话总结：去过哪、见过谁、完成过什么 memory.hasVisited(mapId) // 是否去过某地图 memory.hasMet(npcId) // 是否见过某NPC memory.knowPlayer(uid) // 是否认识某玩家 memory.getLastNPCConversation(npcId) // 上次和某NPC说了什么

OpenClaw 介入时的记忆同步#

每次主会话醒来接管角色时：

1. 读取 character_memory.json
2. 结合当前状态（state.json）
3. 决定下一步行动并更新记忆
4. 所有操作持久化到 character_memory.json

踩坑记录#

⚠️ 移动范围限制#

• moveRange = 20格(直线距离上限),超出需分步
• 从 (91,108) 到 (249,214) 需分多步移动

⚠️ PowerShell 命令分隔符#

• && 在 Windows PowerShell 中无效,使用 ; 分隔

⚠️ 对话必须等移动到达#

• 不能连发 move + chat,必须等收到 ai_player_moved 确认位置后再说话

⚠️ 地图切换后 mapId#

• 以 send_map_info 的 mapId 为准,不要用 perception.mapId(可能有延迟)

⚠️ 位置字段区分#

• perception.self.position = 网格坐标(用于移动指令)
• perception.position = 世界坐标(勿用于移动)

⚠️ 聊天字段区分#

• 发送: command.message
• 接收: msg.chat.content

⚠️ 远距离移动需分步#

• 单次 move 超过 20 格会被服务器忽略
• 正确做法:分段移动,每段等待 ai_player_moved 确认

⚠️ 地图传送#

• 从地图2000到2001:移动到传送点 (249, 214),触发自动传送
• 传送后 mapId 会自动更新

⚠️ OPENCLAW 必须注册才能收推送#

• 不发 ai_register(playerUid: 'OPENCLAW')则收不到任何感知和聊天消息

⚠️ 数据获取优先级#

缓存 → 感知,不读日记

1. 优先查桥接缓存( bridge_getPerception、 bridge_getTransportPoints、 bridge_getPath)
2. 缓存没有的数据(如自己位置/mapId)→ 再发感知指令
3. 永远不要先读日记找位置,日记数据必过时

⚠️ 获取自己感知的方法#

• bridge_requestPerception → 桥接发请求,支持单项(robots/npcs/monsters/mapInfor 等)
• bridge_getPerception → 直接查缓存,快但数据可能不是最新

⚠️ 发送控制指令格式(必须用 sendCommand)#

javascript

ws.send(JSON.stringify({
  type: 'sendCommand',
  playerUid: '3bd46d2ca_10001',  // 注意:不是 targetPlayerUid
  command: { type: 'move', x: 25, y: 30 }
}));

⚠️ 踩坑记录#

1. 桥接 handleMessage 缺少 sendCommand case - 移动指令从未发到游戏客户端,调试了很久才发现
2. monster 对象 key 是小写 uid - 桥接缓存检查 m.Uid(大写),导致所有 monster 都进不了缓存
3. 感知数据可能是 Map 也可能是数组 - 需要同时处理 Array.isArray() 和 instanceof Map
4. TypeScript 必须编译 - 修改 .ts 文件后游戏不会立即生效
5. ai_map_manager 的 mapChanged 走 mapEvent - handleMapEventMessage 里才有

---

完整通信流程图#

text

虾A (ai_register) ──┐
                     ├──→ Bridge(18765) ←───── 游戏客户端 ───→ Bridge(18765) ───→ 虾B (ai_register)
OPENCLAW (注册) ────┘         │
                       ┌──────┴───────┐
                       ↓              ↑
              推送空间事件         发送控制指令
              (ai_map_manager       (move/chat/interact
               ai_player_moved       get_perception)
               ai_perception_data
               ai_chat_received)

---

实战脚本示例#

与 NPC 对话完整流程#

javascript

const ws = new WebSocket('ws://localhost:18765');

ws.on('open', () => {
  ws.send(JSON.stringify({ type: 'ai_register', playerUid: 'OPENCLAW', mode: 'enabled' }));
});

// 等待龙虾入场通知
ws.on('message', data => {
  const msg = JSON.parse(data.toString());
  if (msg.type !== 'ai_client_connected') return;

  const playerUid = msg.playerUid;
  console.log('🦞 龙虾入场:', playerUid);

  // 1. 移动到 NPC 位置
  ws.send(JSON.stringify({
    type: 'sendCommand',
    playerUid: playerUid,
    command: { type: 'move', x: 25, y: 30 }  // 老村长
  }));
});

// 等待移动完成后再对话
ws.on('message', data => {
  const msg = JSON.parse(data.toString());

  // 2. 移动到达后与 NPC 交互
  if (msg.type === 'ai_player_moved' && msg.playerUid === playerUid) {
    ws.send(JSON.stringify({
      type: 'sendCommand',
      playerUid: playerUid,
      command: { type: 'interact', npcId: '200101' }
    }));
    ws.send(JSON.stringify({
      type: 'sendCommand',
      targetPlayerUid: playerUid,
      command: { type: 'sendDialogue', message: '你好村长!' }
    }));
  }
});

查询并缓存 NPC 数据#

javascript

// 发送请求,游戏客户端返回 ai_perception_npcs 并缓存
ws.send(JSON.stringify({
  type: 'bridge_requestPerception',
  playerUid: '3bd46d2ca_10001',
  category: 'npcs'
}));

// 直接从缓存查询(无需等待)
ws.send(JSON.stringify({
  type: 'bridge_getPerception',
  playerUid: '3bd46d2ca_10001'
}));
// 响应: { type: 'bridge_perception', perception: { npcs: [...], ... } }

} });

text

### 远距离移动(分段)

```javascript
function moveInSteps(targetX, targetY, step = 15) {
  // 先获取当前 perception.self.position
  // 每次最多移动 step 格,等待 ai_player_moved 确认后再发下一段
  // 具体实现略,根据实际位置计算分段路径
}

完整接收处理示例#

javascript

ws.on('message', data => {
  const msg = JSON.parse(data.toString());
  switch (msg.type) {
    case 'ai_client_connected':
      console.log('🦞 入场:', msg.playerUid);
      break;
    case 'ai_perception_data':
      // 进入地图时全量推送
      console.log('📍', msg.perception.mapId,
        '玩家:' + (msg.perception.players?.length||0),
        '机器人:' + (msg.perception.robots?.length||0),
        'NPC:' + (msg.perception.npcs?.length||0),
        '怪物:' + (msg.perception.monsters?.length||0));
      break;
    case 'ai_map_manager':
      // 实时增量事件
      const d = msg.mapManagerData;
      if (d.subType === 'robot_moved') console.log('🏃 机器人移动:', d.robot?.playerUid);
      if (d.subType === 'creatRobot')   console.log('✨ 机器人入场:', d.robot?.playerUid);
      if (d.subType === 'removeRobot') console.log('💨 机器人离场:', d.playerUid);
      if (d.subType === 'creatMonserTeam') console.log('👹 怪物出现:', d.monsterTeam?.Uid);
      if (d.subType === 'monster_moved')  console.log('👹 怪物移动:', d.monsterTeam?.Uid);
      if (d.subType === 'player_joinMap')  console.log('👤 玩家入场:', d.playerUid);
      if (d.subType === 'player_levelMap') console.log('👤 玩家离场:', d.playerUid);
      break;
    case 'ai_player_moved':
      console.log('🏃 移动:', msg.playerUid, '@(' + msg.position.x + ',' + msg.position.y + ')');
      break;
    case 'ai_chat_received':
      console.log('💬', msg.chat.nodeName + ':', msg.chat.content);
      break;
    case 'ai_map_changed':
      console.log('🗺️ 地图切换:', msg.mapId);
      break;
  }
});