Godot 插件技能

通过 30 个内置工具控制 Godot 4.x 编辑器，支持 80+ 种节点类型。

连接模式

模式 A：OpenClaw 网关（远程）

适用于 Telegram、Discord 及其他 OpenClaw 渠道：

• 插件通过 WebSocket 连接到网关
• 网关 URL：可在 Godot 停靠面板 UI 中配置
• 最佳适用场景：远程访问、移动端消息交互

模式 B：MCP 桥接（本地）

适用于 Claude Code、Cursor 及本地 AI 工具：

• Godot 插件内置 HTTP 服务器
• 启动方式：在停靠面板 UI 中点击“Start MCP”（端口 27183）
• 添加至 Claude Code：claude mcp add godot -- node /MCP~/index.js

首次设置

若 godot_execute 工具不可用，请安装网关扩展：

# 从技能目录执行
./scripts/install-extension.sh

# 重启网关
openclaw gateway restart

扩展文件位于 extension/ 目录中。

快速参考

核心工具

常见工作流

1. 场景创建

使用 godot_execute 工具：

• godot_execute(tool="scene.create", parameters={rootType: "Node2D", name: "Level1"})
• godot_execute(tool="node.create", parameters={type: "CharacterBody2D", name: "Player"})
• godot_execute(tool="scene.save")

2. 查找与修改节点

• godot_execute(tool="node.find", parameters={name: "Player"})
• godot_execute(tool="node.getData", parameters={path: "Player"})
• godot_execute(tool="transform.setPosition", parameters={path: "Player", x: 100, y: 200})

3. 使用输入进行游戏测试

• godot_execute(tool="editor.play")
• godot_execute(tool="input.keyPress", parameters={key: "W"})
• godot_execute(tool="input.actionPress", parameters={action: "jump"})
• godot_execute(tool="debug.screenshot")
• godot_execute(tool="editor.stop")

4. 查看日志

• godot_execute(tool="console.getLogs", parameters={limit: 50})
• godot_execute(tool="console.getLogs", parameters={type: "error", limit: 20})

工具分类

控制台（2 个工具）

• console.getLogs — 从 Godot 日志文件获取日志 {limit: 100, type: "error"|"warning"|""}
• console.clear — 占位符（日志无法通过编程方式清除）

场景（5 个工具）

• scene.getCurrent — 获取当前场景信息
• scene.list — 列出所有 .tscn/.scn 文件
• scene.open — 按路径打开场景
• scene.save — 保存当前场景
• scene.create — 创建新场景 {rootType: "Node2D"|"Node3D"|"Control", name: "SceneName"}

节点（6 个工具）

• node.find — 按名称、类型或分组查找
• node.create — 创建节点（支持 80+ 类型：CSGBox3D、MeshInstance3D、ColorRect 等）
• node.delete — 按路径删除节点
• node.getData — 获取节点信息、子节点及变换数据
• node.getProperty — 获取属性值
• node.setProperty — 设置属性值（Vector2/Vector3 自动转换）

变换（3 个工具）

• transform.setPosition — 设置位置 {x, y} 或 {x, y, z}
• transform.setRotation — 设置旋转（单位：度）
• transform.setScale — 设置缩放

编辑器（4 个工具）

• editor.play — 运行当前场景或指定场景
• editor.stop — 停止运行
• editor.pause — 切换暂停状态
• editor.getState — 获取运行状态、引擎版本、项目名称

调试（3 个工具）

• debug.screenshot — 截取视口画面
• debug.tree — 以文本形式获取场景树
• debug.log — 打印消息

输入（7 个工具）— 用于游戏测试

• input.keyPress — 按下并释放按键 {key: "W"}
• input.keyDown — 持续按下按键
• input.keyUp — 释放按键
• input.mouseClick — 在指定位置点击 {x, y, button: "left"|"right"|"middle"}
• input.mouseMove — 将鼠标移动到指定位置 {x, y}
• input.actionPress — 触发输入动作 {action: "jump"}
• input.actionRelease — 释放输入动作

脚本（2 个工具）

• script.list — 列出所有 .gd 文件
• script.read — 读取脚本内容

资源（1 个工具）

• resource.list — 按扩展名列出文件

输入支持的按键

A-Z, 0-9, SPACE, ENTER, ESCAPE, TAB, BACKSPACE, DELETE
UP, DOWN, LEFT, RIGHT
SHIFT, CTRL, ALT
F1-F12

支持创建的节点类型

提示

输入模拟

• 仅在 运行模式（Play mode） 下生效
• 对已映射的动作（来自 Input Map），请使用 input.actionPress
• 对直接按键模拟，请使用 input.keyPress

查找节点

node.find {name: "Player"}      # 按名称子串匹配
node.find {type: "Sprite2D"}    # 按精确类型匹配
node.find {group: "enemies"}    # 按分组匹配

向量属性

node.setProperty 自动将字典转换为 Vector2 / Vector3：

{path: "Cam", property: "zoom", value: {x: 2, y: 2}}  # → Vector2(2, 2)

控制台日志

console.getLogs {limit: 50}           # 最近 50 行
console.getLogs {type: "error"}       # 仅错误日志
console.getLogs {type: "warning"}     # 仅警告日志

🔐 安全性：模型调用设置

发布至 ClawHub 时，可配置 disableModelInvocation：

推荐设置：true

原因：在 Godot 开发过程中，允许 AI 自主执行辅助任务（如检查场景树、截图、检视节点等）非常有用。

何时应设为 true：针对敏感操作（如支付、删除、发送消息等）。

自 v1.2.10 起，该技能默认启用 disableModelInvocation: true —— 仅响应用户的显式请求。

安全性与隐私披露

本技能驱动一个实时运行的 Godot 编辑器。以下为能力与当前限制的完整披露：

• 本地 HTTP 桥接无身份验证（当前限制）：MCP 桥接（端口 27183）接收请求时不校验身份，也不限制来源。请确保其仅绑定至 localhost，切勿在共享或公共网络中暴露该端口——否则任何本地进程均可向编辑器发送指令。令牌认证与来源白名单功能已在路线图中。
• 破坏性操作：在执行节点修改/删除、场景保存、输入模拟等操作前，需向用户确认。建议在自动化会话前，先将项目纳入版本控制。
• 数据可见性：工具可读取并传输项目名称、引擎版本、场景结构、脚本内容及视口截图至所连接的智能体。请勿在内容严禁离机的项目中使用本技能。
• 触发范围：看似常规的请求（例如“清理场景”、“保存全部”）可能映射为改变编辑器状态的操作 —— 建议在会话中首次调用状态变更类指令前，进行一次确认。

许可证

Apache-2.0 — 详见 LICENSE.md