🦞 OpenClaw Godot Plugin
TL;DR: Vibe-code your game development remotely from anywhere! 🌍
한줄요약: 이제 집밖에서도 원격으로 바이브코딩으로 게임 개발 가능합니다! 🎮
Connect Godot 4.x to OpenClaw AI assistant via HTTP. Works in Editor mode without hitting Play!
⚠️ Disclaimer
This software is in beta. Use at your own risk.
- Always backup your project before using
- Test in a separate project first
- The authors are not responsible for any data loss or project corruption
See LICENSE for full terms.
🔀 Hybrid Architecture
This plugin supports two connection modes - use whichever fits your workflow:
Mode A: OpenClaw Gateway (Remote Access)
Telegram/Discord/Web → OpenClaw Gateway → Godot Plugin
- ✅ Remote access from anywhere
- ✅ Chat integration (Telegram, Discord, etc.)
- ✅ Cron jobs, automation, multi-device
- ⚠️ Requires OpenClaw Gateway running
Mode B: MCP Direct (Local Development)
Claude Code/Desktop → MCP Server → Godot Plugin
- ✅ Direct connection, no middleware
- ✅ Works with Claude Code, Cursor, etc.
- ✅ Lower latency for local development
- ⚠️ Local only (127.0.0.1)
Quick Setup
📖 Setup Guide | 셋업 가이드
Claude Code MCP Registration
First time setup:
# Register MCP server
claude mcp add godot -- node /path/to/your-project/MCP~/index.js
Re-register (if path changed):
# Remove old registration
claude mcp remove godot
# Add with new path
claude mcp add godot -- node /new/path/MCP~/index.js
Verify registration:
claude mcp list
✨ Key Features
- 🎮 Works in Editor & Play Mode - No need to hit Play to use AI tools
- 🔌 Auto-Connect - Connects when Godot starts, maintains connection across mode changes
- 🎬 Scene Management - Create, open, save, and inspect scenes
- 🔧 Node Manipulation - Create, find, modify, delete nodes (80+ types)
- 📸 Debug Tools - Screenshots, scene tree view, console logs
- 🎮 Input Simulation - Keyboard, mouse, and action input for game testing
- 🎯 Editor Control - Play, stop, pause scenes remotely
- 📜 Script Access - List and read GDScript files
- 🔄 Play Mode Stability - Maintains connection during Play mode
Requirements
⚠️ Tested on Godot 4.6-stable only.
While designed for Godot 4.x, this plugin has only been tested on Godot 4.6-stable. If you encounter issues on other Godot versions, please:
- 🐛 Open an Issue with your Godot version and error details
- 🔧 Submit a Pull Request if you have a fix
Your contributions help make this plugin work across all Godot versions!
Installation
Option 1: Git Clone (Recommended)
# Clone the repository
git clone https://github.com/TomLeeLive/openclaw-godot-plugin.git
# Copy addon to your project
cp -r openclaw-godot-plugin/addons/openclaw your-project/addons/
Option 2: Download ZIP
- Download from Releases
- Extract
addons/openclawto your project'saddons/directory
Quick Start
1. Install OpenClaw Gateway Extension (Required)
Copy the gateway extension files to OpenClaw:
# Copy extension files
cp -r OpenClawPlugin~/* ~/.openclaw/extensions/godot/
# Restart gateway to load the extension
openclaw gateway restart
# Verify
openclaw godot status
Note:
OpenClawPlugin~contains the gateway extension that enablesgodot_executeandgodot_sessionstools. This is required for OpenClaw to communicate with Godot.
2. Install Godot Plugin
- Copy
addons/openclawfolder to your project'saddons/directory - Enable the plugin:
Project → Project Settings → Plugins → OpenClaw → Enable - Connection is automatic when Godot starts
- Check Output panel for
[OpenClaw] Connected to Gateway
3. Chat with OpenClaw
Ask OpenClaw to inspect your scene, create nodes, or debug issues - all without entering Play mode!
4. Install OpenClaw Skill (Optional)
The companion skill provides workflow patterns and tool references for the AI:
# Clone skill to OpenClaw workspace
git clone https://github.com/TomLeeLive/openclaw-godot-skill.git ~/.openclaw/workspace/skills/godot-plugin
The skill provides:
- Quick reference for all 30 tools
- Common workflow patterns (scene creation, testing, etc.)
- Detailed parameter documentation
- Troubleshooting guides
Note: The skill is separate from the gateway extension. The extension enables the tools; the skill teaches the AI how to use them effectively.
Available Tools (30 tools, 80+ node types)
Scene Tools (5)
Node Tools (6)
Transform Tools (3)
Editor Tools (4)
Debug Tools (3)
Console Tools (2)
Input Tools (7)
Script Tools (2)
Resource Tools (1)
Example Usage
Scene Creation
You: Create a 2D platformer scene
OpenClaw:
[Executes scene.create {rootType: "Node2D", name: "Level1"}]
[Executes node.create {type: "CharacterBody2D", name: "Player"}]
[Executes node.create {type: "Camera2D", name: "Camera", parent: "Player"}]
[Executes transform.setPosition {path: "Player", x: 100, y: 200}]
Done! Created Level1 scene with Player and Camera.
Game Testing with Input
You: Test the player movement
OpenClaw:
[Executes editor.play]
[Executes input.keyDown {key: "W"}] # Move up
[Executes input.keyUp {key: "W"}]
[Executes input.actionPress {action: "jump"}]
[Executes debug.screenshot]
[Executes editor.stop]
Tested player movement. Screenshot attached.
Reading Logs
You: Check for errors
OpenClaw:
[Executes console.getLogs {type: "error", limit: 10}]
Found 2 errors:
- ERROR: Node not found: Player
- ERROR: Invalid resource path
Configuration
The plugin connects to http://localhost:18789 by default (OpenClaw Gateway).
To change, modify GATEWAY_URL in addons/openclaw/connection_manager.gd.
Architecture
┌─────────────────────────────────────────────────────────────┐
│ Godot Editor │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ OpenClawPlugin (EditorPlugin) │ │
│ │ @tool script │ │
│ └──────────────────────┬─────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ ConnectionManager │ │
│ │ (HTTP polling, PROCESS_MODE_ALWAYS) │ │
│ │ │ │
│ │ • Heartbeat: 30s interval │ │
│ │ • Auto-reconnect on disconnect │ │
│ │ • Maintains connection during Play mode │ │
│ └──────────────────────┬─────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Tools (30 tools, 80+ node types) │ │
│ │ │ │
│ │ • Scene/Node/Transform manipulation │ │
│ │ • Input simulation (keyboard, mouse, actions) │ │
│ │ • Debug tools (screenshot, logs) │ │
│ │ • Editor control (play, stop) │ │
│ └────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
│
│ HTTP (port 18789)
▼
┌──────────────────────────────────────────────────────────────┐
│ OpenClaw Gateway │
│ http://localhost:18789 │
│ │
│ Endpoints: │
│ • POST /godot/register - Register Godot session │
│ • POST /godot/heartbeat - Keep session alive │
│ • GET /godot/poll - Poll for commands │
│ • POST /godot/result - Send tool execution results │
└──────────────────────────────────────────────────────────────┘
File Structure
Skill vs Extension
Summary: Skill = AI documentation, Extension = Executable code
Installation Flow
Plugin (OpenClawPlugin~/) ───copy───→ ~/.openclaw/extensions/godot/
└── Manual installation
Skill (extension/) ───copy───→ ~/.openclaw/extensions/godot/
└── install-extension.sh
Both paths install the same extension code. Use whichever method is convenient.
Troubleshooting
Plugin won't load
- Check Godot version (4.x required)
- Look for parse errors in Output panel
- Ensure all .gd files are present in addons/openclaw/
Connection issues
- Verify Gateway is running:
openclaw gateway status - Check URL: default is
http://localhost:18789 - Look at Output panel in Godot for
[OpenClaw]status
Input not working
- Input simulation only works during Play mode
- Ensure the game window has focus
- Check if the action exists in Input Map
Play mode disconnects
- Plugin uses
PROCESS_MODE_ALWAYSto stay active - Heartbeat interval is 30 seconds
- If disconnected, plugin auto-reconnects
🔐 Security: Model Invocation Setting
When publishing to ClawHub or installing as a skill, you can configure disableModelInvocation in the skill metadata:
Recommendation for Godot Plugin: false
Reason: During Godot development, it's useful for AI to autonomously perform supporting tasks like checking scene tree, taking screenshots, and inspecting nodes.
When to use true: For sensitive tools (payments, deletions, message sending, etc.)
# Example skill metadata
metadata:
openclaw:
disableModelInvocation: false # Recommended for Godot plugin
Documentation
- 📖 Setup Guide | 셋업 가이드
- 🔧 Development | 개발 가이드
- 🧪 Testing | 테스팅
- 🤝 Contributing | 기여 가이드
🎭 AI Personas for Game Development
Want your AI agent to have a consistent personality while developing your game? ClawSouls provides open-source persona packages (Soul Spec) that work with OpenClaw and other AI frameworks. Give your coding assistant a specialized game dev personality, or create custom NPC behavior profiles.
- Browse community souls: clawsouls.ai
- Soul Spec standard: soulspec.org
- Quick start:
npx clawsouls init my-game-dev --spec 0.4
Changelog
See CHANGELOG.md for version history.
License
MIT License - see LICENSE for details.
Made with 🦞 by the OpenClaw community
License
This project has been licensed under Apache-2.0 since its initial release. Copyright 2026 Tom Lee (TomLeeLive)
Securing the MCP Bridge
The bridge listens on 127.0.0.1 only. Two additional hardening layers (v1.4.4+):
- Browser-origin rejection — requests carrying an
Originheader are refused (403). Local MCP clients never send one; web pages probing the local port do. - Optional shared-secret auth — set the same environment variable for the Godot editor process and your MCP client, then restart both:
export OPENCLAW_BRIDGE_TOKEN="some-long-random-string"
When set, every request must carry X-OpenClaw-Token: <token> (the bundled MCP~/index.js sends it automatically). Unset = no auth, matching previous behavior.
