UE5远程驾驶台 · 本机编辑器一键驱动
不用手动点 UE5 编辑器界面，直接在 WorkBuddy 会话里把已打开的 UE5 编辑器
「开起来」——导入资产、建蓝图 / 动画蓝图、跑 Python、截图验收，全靠
custom-mcp:unreal 远程执行通道（腾讯 runreal/unreal-mcp，工具前缀
mcp__unreal__*）走本机 TCP 19999 完成。
一图看懂：架构与数据流
flowchart LR
A[WorkBuddy 会话] -->|custom-mcp:unreal 桥| B[unreal-mcp 进程]
B -->|Remote Execution 协议| C[(UE5 编辑器<br/>本地 TCP :19999)]
C -->|资产导入 / 建BP / 跑Python / 截图| A
style A fill:#fff3e0,stroke:#ff5722,color:#000
style B fill:#ffe0b2,stroke:#ff7043,color:#000
style C fill:#ffccbc,stroke:#e64a19,color:#000
无头沙箱里没有显示器，编辑器必须由用户在本机双击 .bat 启动并保持打开；
AI 通过 TCP 抵达编辑器（MCP 多播本机不可达，所以编辑器必须先活着）。
前置条件（已在本机验证）
~/.workbuddy/mcp.json注册unreal→@runreal/unreal-mcp
（disabled: false），在 WorkBuddy 里显示为custom-mcp:unreal。- 编辑器必须打开并保持打开；
Editor Settings → Python → Enable Remote Execution要勾上。 - 编辑器会在本机 19999 端口开 TCP 监听，供远程驱动。
连接失败 → 根因对照（先查这张表）
| 现象 | 根因 | 修复动作 |
|---|---|---|
Remote node is not available |
编辑器没开 / Remote Execution 没真启用 | 让用户双击 Launch_*.bat 启动并保持打开，自动重连 |
| 勾了 Remote Execution 仍连不上 | 真实开关 bRemoteExecution 仍是 false |
见下方「致命坑」 |
import unreal 报错 / 片段不执行 |
提交的 Python 带注释或没以 import unreal 开头 |
见「Python 执行规则」 |
| 工具调用无响应 | MCP 未注册 / 端口被防火墙挡 | 查 mcp.json、确认 19999 监听 |
致命坑：bRemoteExecution 才是真开关
本地 ini 里的 PythonScriptPluginSettings.PythonRemoteExecution=True 只是
UI 可见性标记，不是真实值——引擎头文件默认把它关掉（bRemoteExecution
默认 false）。所以「在设置里勾了」不代表真开了。
真修复：在项目 Config/DefaultEditor.ini 加这段，重启编辑器才生效：
[/Script/PythonScriptPlugin.PythonScriptPluginSettings]
bRemoteExecution=True
排错决策树
flowchart TD
Q[连接失败 / Remote node is not available] --> E1{编辑器开着吗?}
E1 -->|否| F1[让用户双击 Launch_*.bat 启动并保持打开]
E1 -->|是| E2{Remote Execution 真开了?}
E2 -->|否| F2[DefaultEditor.ini 加 bRemoteExecution=True 并重启编辑器]
E2 -->|是| E3{Python 片段合规?}
E3 -->|否| F3[必须以 import unreal 开头 / 片段内禁注释]
E3 -->|是| F4[查 MCP 注册 / 端口19999 / 防火墙]
F1 --> Q
F2 --> Q
F4 --> DONE[连接成功, 开始驱动]
style Q fill:#fff3e0,stroke:#ff5722,color:#000
style F2 fill:#ffe0b2,stroke:#ff7043,color:#000
Python 执行规则（强制）
editor_run_python提交的代码必须以import unreal开头，且片段内
不能有注释。- 跑已有
.py文件：exec(open(r'D:/.../xxx.py').read())。 - 自动进 PIE：编辑器稳约 3 秒后调
editor_request_begin_play()；
绝不用-ExecutePythonScript。
标准工作流
- 确认编辑器已开 + Remote Execution 已勾（否则让用户启动
.bat）。 - 连接
unrealMCP。 - 按任务
editor_run_python（导入 / 建蓝图 / 截图）。 - 截图，对照视觉验收清单（
game-visual-qc技能）出报告。
常见坑速查（参考资料）
更细的踩坑记录、.bat 启动器写法、C++ 两 Target 注意事项，
见 references/ue5_remote_reference.md。架构图见 assets/architecture.svg
（可直接用于上架展示页）。
