Skip to content
ggui

OpenClaw Agent

Install the ggui skill from ClawHub and your OpenClaw agents can generate interactive UIs on demand — forms, dashboards, wizards, and more.

Setup

Section titled “Setup”

1. Install the Skill

Section titled “1. Install the Skill”
Terminal window
clawhub install ggui

This adds the ggui MCP tools and skill documentation to your OpenClaw agent’s context.

2. Point at a ggui server

Section titled “2. Point at a ggui server”

🟢 OSS / self-hosted — no signup. Run ggui serve locally (see the OSS Quick Start) — defaults to http://127.0.0.1:6781/mcp with dev-mode auth (Bearer dev).

🟣 Hosted Guuey — sign up, create an app, get a key:

  1. Sign up at platform.guuey.com and create an app
  2. Go to Agent Connectors and create a connector to get an API key
  3. Set environment variables:
Terminal window
export GGUI_API_KEY="ggui_sk_..."
export GGUI_APP_ID="app_..."

3. Configure MCP

Section titled “3. Configure MCP”

The skill includes an mcporter.json that automatically configures the MCP connection. If you need manual setup:

🟣 Hosted Guuey:

{
  "mcpServers": {
    "ggui": {
      "type": "http",
      "url": "https://api.guuey.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GGUI_API_KEY}",
        "X-Ggui-App-Id": "${GGUI_APP_ID}"
      }
    }
  }
}

🟢 OSS / self-hosted — point at your local ggui serve with dev-mode auth:

{
  "mcpServers": {
    "ggui": {
      "type": "http",
      "url": "http://127.0.0.1:6781/mcp",
      "headers": {
        "Authorization": "Bearer dev"
      }
    }
  }
}

Usage

Section titled “Usage”

Once installed, your OpenClaw agent has access to 7 MCP tools:

ToolWhat It Does
ggui_pushGenerate a UI from a natural language prompt
ggui_popRemove the top card from the UI stack
ggui_consumePoll for user events (form submissions, clicks)
ggui_get_sessionGet the current session state
ggui_closeClose a session and free resources
ggui_list_featured_templatesDiscover reusable UI templates
ggui_render_templateRender a cached template instantly

Example: Collect User Feedback

Section titled “Example: Collect User Feedback”

Ask your OpenClaw agent:

“Collect feedback from the user about their recent purchase. Ask for a star rating and comments.”

The agent will:

  1. Call ggui_push with an appropriate prompt
  2. Share the generated URL with the user
  3. Call ggui_consume to wait for the user’s response
  4. Process the submitted rating and comments
  5. Call ggui_close to clean up

Example: Multi-Step Wizard

Section titled “Example: Multi-Step Wizard”

“Walk the user through a 3-step onboarding: personal info, preferences, then confirmation.”

The agent uses ggui_push for each step, passing data from previous steps via context, and ggui_pop if the user wants to go back.

Example: Use Templates

Section titled “Example: Use Templates”

“Show the user a login form.”

The agent can call ggui_list_featured_templates to find a cached login form template, then ggui_render_template for instant rendering without generation.

How It Works

Section titled “How It Works”
OpenClaw Agent              ggui API                    User's Browser
     |                         |                              |
     |-- ggui_push(prompt) --->|                              |
     |                         |-- AI generates React UI      |
     |<-- { sessionId, url } --|                              |
     |                         |                              |
     |   (share URL with user) |                              |
     |                         |<---- user opens URL ---------|
     |                         |----  rendered UI ----------->|
     |                         |                              |
     |-- ggui_consume -------->|                              |
     |                         |<---- user submits form ------|
     |<-- { events } ---------|                              |
     |                         |                              |
     |-- ggui_close ---------->|                              |
  1. Your agent calls ggui_push with a natural language description
  2. ggui’s AI generates a fully functional React component
  3. The user opens the rendered URL in their browser
  4. The user interacts with the UI (fills forms, clicks buttons)
  5. Your agent polls ggui_consume to receive events
  6. Your agent processes the data and continues its task

Key Patterns

Section titled “Key Patterns”
  • Natural language prompts: Describe the UI you want — ggui handles the React code generation
  • Context passing: Use context to pass data into the generated UI (user names, option lists, prefilled values)
  • Stack navigation: Push multiple cards for multi-step flows, pop to go back
  • Templates first: Check ggui_list_featured_templates before generating — templates render instantly (~100ms vs ~3s for generation)
  • Event polling: Use ggui_consume in a loop to wait for user responses — events are cleared after consumption

Troubleshooting

Section titled “Troubleshooting”
IssueSolution
Unauthorized errorCheck that GGUI_API_KEY and GGUI_APP_ID are set correctly
Session Not FoundSession may have expired — create a new one with ggui_push
Production FailedTry a simpler prompt, or check your account has generation credits
No events returnedThe user hasn’t interacted yet — keep polling with ggui_consume

Next Steps

Section titled “Next Steps”