Connect OpenClaw to your virtual workspace

Compatibility: The plugin currently targets OpenClaw 2026.7.1-2 and Node.js 24.15 or newer. Check the repository's README and releases before upgrading OpenClaw because its plugin SDK is still evolving.

What the plugin can do

• Receive new messages from Spot rooms, channels, and direct messages.
• Discover and monitor the channels the bot can access in a configured organization.
• Reply to a top-level channel message in its Spot reply thread and continue the same OpenClaw conversation when people answer there.
• Send proactive text messages to configured targets, react to messages, and inspect their reactions.
• Show a transient Spot typing indicator while preparing a normal reply.
• Respond only to direct messages, mentions, or every allowed message, depending on activationMode.
• Observe the bot's state, other visible avatars, and accessible rooms.
• Join and leave a world; move, teleport, turn, and emote.
• Move to a room by its Spot ID, slug, or exact name without exposing or guessing floorplan coordinates.
• Maintain an avatar lease across OpenClaw reconnects when avatar.joinOnStart is enabled.
• Run a default account or multiple named Spot accounts from one OpenClaw installation.

Prerequisites

You need:

• OpenClaw 2026.7.1-2 and Node.js 24.15 or newer.
• Permission to create and manage bot users in the Spot team.
• A Spot bot, an API token for that bot, and the world's stable ID. To discover organization channels, you also need the organization's stable ID.
• A Spot deployment that supports the Agent Gateway and the bot-avatar and room-discovery API endpoints.
• An HTTPS Spot base URL for remote deployments. The hosted service uses https://spotvirtual.com; plain HTTP is accepted only for loopback development hosts.

Create a Spot bot and API token

1. In Spot, open Team settings, then Bots.
2. Create a bot and give it a recognizable name and avatar.
3. Open the bot, create an access token, and copy the token when Spot displays it.
4. Put the bot in an appropriate role and verify its effective permissions for the worlds, rooms, and channels it will use.

Token scopes and role permissions are separate

A token scope allows an API operation. The bot user's effective Spot role permissions decide whether that operation is allowed for a particular world, room, or conversation. Configure both layers; a broad token does not override the bot's role.

Grant only the token scopes needed by your configuration:

• EventRead receives Agent Gateway events and reads messages and reaction state.
• EventWrite sends messages, adds or removes reactions, and publishes typing state.
• ThreadRead discovers organization channels and fetches threads used for routing.
• ThreadWrite creates per-message reply threads and initiates a direct message through a user:<userId> target.
• WorldRead supports world subscriptions, room discovery, and avatar observation.
• AvatarWrite supports avatar join, leave, movement, facing, and emotes.

The bot's effective Spot permissions should include, as applicable:

• canViewWorlds to discover and subscribe to a world.
• canEnterRooms to join or move into rooms that require it.
• canMessageSpotThreads for room chat.
• canViewChannels and canMessageChannels for named-channel monitoring and replies.
• canAddReactions if the agent may add reactions in organization conversations. Removing reactions is limited to the bot's own reaction records.
• canViewChatHistory is not used by the current connector. Grant it only to a separate REST history consumer, or if a future connector release adds history replay.
• canEmote if the avatar may use emotes.
• canDirectMessageMembers if the agent will initiate DMs.

Important: The current connector does not fetch REST history or replay missed messages after reconnecting. Live Agent Gateway delivery and REST history use separate authorization paths, so canViewChatHistory is only relevant to a separate history consumer today.

Install the channel plugin

Until a packaged release is published, install from the public source repository:

git clone https://github.com/spotxyz/spot-openclaw.git
cd spot-openclaw
npm install
npm run check
npm test
npm run build
openclaw plugins install --link .
openclaw plugins enable spot
openclaw plugins doctor
openclaw plugins inspect spot

Restart the OpenClaw gateway after installing the plugin or rebuilding it.

Configure OpenClaw

Keep the Spot token in an OpenClaw secret provider instead of writing it directly into openclaw.json. For a user-scoped environment provider named default, make SPOT_AGENT_TOKEN available to the OpenClaw gateway and add:

{
  "tools": {
    "profile": "coding",
    "alsoAllow": ["spot"]
  },
  "messages": {
    "groupChat": {
      "unmentionedInbound": "room_event",
      "visibleReplies": "message_tool"
    }
  },
  "plugins": {
    "entries": {
      "spot": {
        "enabled": true
      }
    }
  },
  "channels": {
    "spot": {
      "enabled": true,
      "baseUrl": "https://spotvirtual.com",
      "token": {
        "source": "env",
        "provider": "default",
        "id": "SPOT_AGENT_TOKEN"
      },
      "orgId": "your-org-id",
      "worldId": "your-world-id",
      "monitorOrgChannels": true,
      "allowFrom": ["trusted-spot-user-id"],
      "activationMode": "all",
      "avatar": {
        "joinOnStart": true,
        "spotId": "optional-starting-spot-id"
      }
    }
  }
}

File and command-backed OpenClaw SecretRefs are also supported. A literal token is useful for short-lived local development, but is not recommended for a persistent gateway.

The alsoAllow entry is required when a restrictive OpenClaw tool profile such as the local-install default coding profile is active. The plugin ID grants tools owned by Spot, including Spot tools added by future versions, without enabling unrelated plugins. To expose only a smaller, frozen avatar surface, list the individual spot_* tool names instead. Restart the Gateway after changing this policy.

With joinOnStart enabled, OpenClaw maintains the bot's avatar lease. On reconnect it preserves an avatar that is already joined; the configured starting spotId or coordinates are used only when the avatar is absent.

Configuration reference

Top-level fields under channels.spot configure the default account and act as defaults for entries in accounts.

For example, one gateway can run two independent Spot bot identities against the same deployment:

{
  "channels": {
    "spot": {
      "baseUrl": "https://spotvirtual.com",
      "activationMode": "mentions",
      "allowFrom": ["trusted-spot-user-id"],
      "accounts": {
        "hq": {
          "token": {
            "source": "env",
            "provider": "default",
            "id": "SPOT_HQ_AGENT_TOKEN"
          },
          "worldId": "hq-world-id",
          "avatar": {
            "joinOnStart": true,
            "spotId": "hq-lobby-spot-id",
            "ttlSeconds": 600
          }
        },
        "events": {
          "token": {
            "source": "env",
            "provider": "default",
            "id": "SPOT_EVENTS_AGENT_TOKEN"
          },
          "worldId": "events-world-id",
          "subscribeThreads": ["events-help-channel-id"]
        }
      }
    }
  }
}

Who can activate the agent

Inbound activation is fail-closed:

• An empty allowFrom list allows nobody to activate the agent.
• Add exact Spot user IDs for the people who should be able to invoke it.
• "allowFrom": ["*"] trusts every sender visible to the token and should be used only for a fully trusted audience.
• Bot-authored events are ignored unless allowBotMessages is explicitly enabled.
• direct-or-mention, the default, responds to allowed DMs and mentions. mentions requires a mention, while all processes every allowed new message.

Monitor channels without answering every message

Set orgId and monitorOrgChannels: true to discover and subscribe to every organization channel the bot can view. The Agent Gateway accepts at most 100 thread subscriptions per connection; manually configured subscribeThreads and discovered organization channels count toward the same limit.

While connected, the plugin subscribes when a channel is created or updated or when the bot joins it, and unsubscribes when the channel is deleted or the bot leaves. This keeps private-channel monitoring aligned when the bot is removed and later re-added.

For quiet ambient monitoring, combine activationMode: "all" with the two messages.groupChat settings shown above. unmentionedInbound: "room_event" gives OpenClaw the allowed, unmentioned channel messages as room context instead of treating each one as a direct request. visibleReplies: "message_tool" permits an ambient turn to post only when the agent intentionally calls the shared message tool. Mentions and direct messages remain normal requests.

The allowFrom filter still applies before monitoring. Use exact user IDs unless the whole channel audience is trusted.

Message targets

OpenClaw uses these destination forms:

• thread:<threadId> sends to a canonical Spot room, channel, or DM thread.
• user:<userId> gets or creates a DM thread, then sends to it.
• spot:<spotId-or-slug> resolves a room in the configured world and sends to its chat thread.
• world:<worldId> sends to the chat thread for the managed avatar's current room in that world.

An inbound event establishes a durable reply destination. For an actionable top-level channel message, the connector creates or reuses that message's Spot reply thread before processing it, and that child becomes the OpenClaw conversation and reply destination. Follow-up messages there continue the same conversation without requiring another mention. A passive ambient room_event stays in the parent channel and creates a reply thread lazily only if the agent intentionally sends a reply. Room chat and direct-message replies stay in their existing thread.

Reactions and typing

The standard OpenClaw message tool supports action: "react" and action: "reactions" for Spot event IDs. A reaction can be added, removed with remove: true, or listed without a separate Spot-specific tool.

For normal requests, the connector starts Spot's typing indicator when reply generation begins, refreshes it while work continues, and clears it when the turn finishes. Ambient room_event processing does not show typing because it may produce no visible response. Typing is best-effort and expires automatically if a connection closes unexpectedly.

Avatar tools

• spot_observe returns the managed avatar, visible avatars, and accessible rooms.
• spot_avatar_state returns only the managed avatar's current state.
• spot_rooms discovers room names, slugs, stable Spot IDs, chat thread IDs, and access decisions.
• spot_join and spot_leave start or end avatar presence.
• spot_move walks to a reachable world coordinate.
• spot_teleport moves immediately to an exact coordinate.
• spot_move_to_room resolves a room and moves there without guessing coordinates.
• spot_face changes the avatar's facing angle.
• spot_emote plays an emoji or avatar animation.

The standard OpenClaw message tool sends text. The Spot plugin deliberately does not add a second speech tool.

Room and ID stability

Spot has two similarly named room identifiers:

• A Spot ID identifies the logical room, its permissions, and its chat thread. It is a durable database ID and is the identifier to keep in OpenClaw configuration.
• A floorplan room ID identifies a geometric region in one version of a world's floorplan. Spot preserves it when possible, but splits, merges, imports, or ambiguous topology edits can replace or reassign it.

spot_rooms and spot_move_to_room work with the logical Spot. The server resolves that Spot to the current floorplan region at action time. Prefer the Spot ID over a slug or name because names and slugs can be edited, and never persist a floorplan room ID as the agent's room target.

If a floorplan edit removes a room mapping, the logical Spot and its chat history can remain, but it cannot be used as a physical destination until it is mapped to a floorplan room again.

Security defaults

• Use an OpenClaw SecretRef and a least-privilege bot token.
• Use HTTPS for remote Spot servers; the bearer token is sent on REST and WebSocket connections.
• Keep allowFrom restricted to exact trusted user IDs.
• Leave allowBotMessages off unless bot-to-bot interaction is intentional and bounded.
• Spot evaluates token scopes and the bot's current memberships, roles, room access, and world access independently.
• Avatar mutations go through authorized REST endpoints. The Agent Gateway connection is used for listening.
• Tokens are redacted from connector errors and health snapshots.

Current limitations

• The connector handles new text messages and can manage outbound reactions. It does not turn message edits, deletions, attachments, or inbound reaction changes into agent requests, and it does not support rich message blocks, voice, or video.
• Agent Gateway delivery is at-most-once. A sequence gap is reported as unhealthy but missed messages are not automatically replayed today.
• Organization-channel discovery monitors each channel's top-level thread. It does not recursively subscribe to unrelated reply threads that already exist; it follows reply threads the agent engages in.
• Outbound replies are text-only.
• Avatar presence is headless; it does not join voice/video calls or render the world as a browser client would.
• Compatibility is intentionally pinned to the OpenClaw 2026.7 plugin SDK range.

More information

• Spot OpenClaw source, setup details, and issue tracker
• Spot API documentation
• OpenClaw documentation
• Spot support