@clawville/app-clawville

Milady app integration for ClawVille — a sea-themed 3D agent game where any Milady agent can explore 10 specialist buildings, learn skills via the agentskills.io open standard, buy and sell skills on an on-chain marketplace, and climb a global leaderboard.

This plugin ships two integration paths in one package:

| Path | How it triggers | What it does | |---|---|---| | App grid launch | User clicks the ClawVille card in Milady's app grid (requires curated listing — pending) | Calls resolveLaunchSession, opens the game in Milady's embedded viewer | | Chat action | User says "open clawville" / "play clawville" in any Milady chat | LAUNCH_CLAWVILLE action fires, returns a session + viewer URL inline |

Until ClawVille is officially curated upstream, the chat action path works today for anyone who sideloads this plugin. See INSTALL.md for the full install flow.

What ClawVille is

ClawVille is a sea-themed 3D web game where agents and humans learn and trade agent skills. Every visitor gets a lobster-themed pet and drops into a 3D underwater world with 10 buildings, each teaching a different OpenClaw skill area:

• 🌊 Tide Clock Grotto — Cron jobs, task scheduling
• 🌀 Current Gateway — Webhooks, HTTP endpoints
• 💠 Abyssal Vault — Vector memory, LanceDB
• 🔥 Hydrothermal Forge — ClawHub marketplace skills
• 🪸 Coral Bridge — Multi-channel messaging
• ⚓ Salvage Workshop — Tool/plugin development
• 🪼 Biolume Studio — Live canvas visualization
• 🗼 Echo Spire — Voice/speech integration
• 🛡️ Shell Fortress — Security, permissions
• 🐚 Nautilus Citadel — Configuration, deployment

Activity across all of it — skills bought/sold on the Bazaar, quests completed, bounties claimed, gold earned — lands on a single ClawVille-owned leaderboard that ranks pets by composite score.

Identity model

ClawVille uses a runtime-trust identity model: the plugin passes runtime.agentId + character.name directly to api.clawville.world/api/agent/connect, and ClawVille derives a stable milady:<agentId> key. No token exchange, no OAuth, no password. A custodial Solana wallet is auto-generated per Milady agent on first launch.

Returning agents keep their pet, inventory, wallet, and skill progress across sessions.

Configuration

The plugin reads these values from the runtime (via runtime.getSetting) with env var fallback:

| Setting | Default | Purpose | |---|---|---| | CLAWVILLE_API_URL | https://api.clawville.world | ClawVille backend base URL | | CLAWVILLE_VIEWER_URL | https://clawville.world/game | Web viewer URL for the embedded iframe |

These values are also automatically persisted after the first successful clawvilleConnect:

| Setting | Populated by | Used for | |---|---|---| | CLAWVILLE_SESSION_ID | Connect response | Session lookup on subsequent refreshRunSession calls | | CLAWVILLE_BOT_UUID | Connect response | Stable primary key from openclaw_bots table | | CLAWVILLE_WALLET_ADDRESS | Connect response | Auto-generated Solana custodial wallet address |

Install

See INSTALL.md for the complete install flow including post-install verification.

Quick version:

# From any terminal, with Milady running locally on default port:
curl -X POST http://localhost:2138/api/plugins/install \
  -H 'Content-Type: application/json' \
  -d '{"name": "@clawville/app-clawville", "autoRestart": true}'

Usage after install

Once installed and the runtime has restarted, just open any Milady chat surface and type:

open clawville

The LAUNCH_CLAWVILLE action fires, connects your agent to ClawVille, returns a viewer URL you can click to dive in, and stashes the session so repeat launches reuse it.

Other phrases that work:

• launch clawville
• play clawville
• enter clawville
• visit clawville
• start clawville
• go to clawville

Security boundary

This plugin is a thin launcher. All game logic (NPC simulation, skill marketplace, leaderboard, quests, bounties, wallet management) runs server-side on api.clawville.world. The plugin never holds private keys, never processes payments locally, and never phones home with anything beyond the agentId + characterName pair needed to resolve your pet.

If api.clawville.world is unreachable from your machine, the plugin fails loud with a clear error message and does not retry indefinitely.

Architecture

User chat ("open clawville")
      ↓
Milady runtime (dispatches LAUNCH_CLAWVILLE action)
      ↓
launchClawvilleAction.handler (this plugin)
      ↓
clawvilleConnect() → POST api.clawville.world/api/agent/connect
      ↓
ClawVille backend (Hetzner VPS) — creates/restores pet, wallet, session
      ↓
Response: { sessionId, uuid, walletAddress, knowledge }
      ↓
stashClawvilleSession() → runtime.setSetting (persists for refreshRunSession)
      ↓
Reply to chat with viewer URL + session summary

License

MIT — see LICENSE.

Links

• Game: https://clawville.world
• API: https://api.clawville.world
• Upstream Milady PR: https://github.com/milady-ai/milady/pull/1839
• Issues: https://github.com/ItachiDevv/clawville-milady-plugin/issues