Multi-user Mode for OpenClaw Agents

Multi-user mode allows multiple trusted individuals to share control of a single OpenClaw agent. It introduces session ownership, a log of participant activity, real-time presence, and owner-based filtering, enabling teams to identify who initiated work, who currently handles it, and who has contributed along the way.

Trust boundary

Anyone with the ability to operate an agent can trigger any action that agent is capable of performing. Features like session ownership, sidebar visibility, and presence indicators are designed for usability, not as security measures.

If users must not see each other's sessions, tools, credentials, or files, set up separate agents or distinct gateway/host trust boundaries. Owner avatars and filters should never be relied upon for isolation.

The three ownership layers

Each session includes up to three levels of attribution:

Creator (immutable): when the creation path can verify who initiated it, new sessions store a one-time createdActor. Authenticated users are recorded with their persistent Gateway profile id; sessions launched by an agent capture that agent's id. Sessions without a confirmed actor remain unattributed. Sharing and visibility control remain tied to the creator, even if ownership later changes.
Owner (assignable): the individual or agent currently accountable for the session, similar to a GitHub issue assignee. It starts as the creator and can be transferred at any time; the transfer logs who made the change and when. The sidebar avatar, owner filter, and People sorting all reflect the current owner.
Participants (history): everyone who has actively engaged with the session, including authenticated users, channel senders, and requesting agents, is logged automatically on each turn. The session's own agent and passive viewers are never included. Participant history is capped at 32 distinct actors per session and is recorded asynchronously in the background, so it never slows down a turn.

Display names and avatars for humans come from the current Gateway profile when session rows are fetched; agent actors use the configured agent identity. OpenClaw does not save display labels on session entries, so renaming a profile or agent updates the ownership interface without altering session history.

Assigning an owner

In the Control UI, the session context menu (accessible via kebab or right-click on a sidebar row, and also from the chat header) provides:

Assign to me: take over responsibility for the session yourself.
Assign to…: choose from a submenu listing known people and configured agents.

Agents can transfer ownership using the sessions tool with action: "assign_owner" and ownerType ("human" or "agent") plus ownerId, which targets the current session by default or another visible session through sessionKey.

Both approaches invoke the Gateway method sessions.assignOwner (operator.write). Assignment requires an identified caller, either an authenticated Gateway profile or a trusted agent identity, and is permitted based on session visibility. Agent owner ids must reference a configured agent. After the transfer, the avatar tooltip changes from "Created by" to "Owned by".

Changing the owner affects only responsibility and display. It does not alter sharing authority (which remains with the creator) and neither grants nor removes any access.

Finding sessions by owner

When ownership is visible, the sidebar's session filter menu adds an Owners section:

All owners displays everything (the default).
Selecting a specific person or agent shows only the sessions they currently own.
Involving me lists sessions you own plus those where you have prompted at least once. The Gateway evaluates this filter against the full participant history, matching only your authenticated profile identity; channel-native sender ids are for display only and never match, so a numeric channel id cannot clash with your profile.

Involving me requires a signed-in Gateway profile. The People sort mode arranges sessions by current owner and orders those groups alphabetically by name.

Reading the avatars

The Control UI keeps ownership and presence visually separate:

A solid owner avatar on a session row persists for the entire session and always indicates the current owner. It dims slightly when the owner is offline.
If other people or agents have prompted the session, the row avatar becomes a pair-stack: the owner stays in front, with either a single other participant peeking out behind, or a +N count summarizing multiple. The chat header shows the owner chip plus a participant facepile of up to four avatars, excluding the owner.
Ringed or translucent presence avatars indicate people who are currently connected or viewing; these come from live presence, not ownership, and vanish when those viewers disconnect.

When multiple people view the same session, the transcript shows a live typing indicator above the composer. Someone typing in the Control UI streams their draft text into the indicator bubble in real time; other typists display a three-dot bubble. Drafts are ephemeral presence: they are never stored, never enter the session transcript or the model's context, and disappear shortly after the typist pauses or sends.

If the loaded session list has fewer than two distinct owner identities and no session has recorded outside participants, OpenClaw hides all ownership and owner-filter chrome. A single-user gateway therefore appears unchanged.

Agent-spawned sessions

Sessions created by an agent with sessions_spawn (visible: true) are credited to that requesting agent: the creator and initial owner is the agent itself, and the sidebar displays the agent's configured identity name and avatar rather than an internal session key.

The accepted spawn result serves as a receipt: it contains the child session key, the run id, a direct Control UI sessionUrl (omitted when the Control UI is disabled), and an owner record naming the requesting agent. When an agent acknowledges the spawn in a chat channel, it places the session URL on the first line and Owner: <label> on the second, allowing you to open the session and see who is responsible at a glance. Use Assign to me to take over the session yourself if you assume the work. See Sub-agents for the spawn lifecycle.

Identity-scoped convenience state

When a connection has a durable Gateway profile, new-session preferences and picker recents follow that person across browsers. Preferences remain per agent, while recents are derived only from sessions that person created. Connections without a durable identity keep browser-local preferences and derive recents from the loaded session roster.

This state improves continuity; it is not an authorization or isolation boundary. Operator scopes still control actions, and a shared Gateway remains one trust domain for sessions, tools, credentials, and files.

Drafts

Start a session as a draft to keep work in progress out of teammates' sidebars until you publish it. Drafts are never hidden from admins, who see other people's drafts with a faded ghost marker. This is a coordination feature, not a security boundary.

Turn attribution

Turn sender attribution is best-effort. Steering can merge input into an active turn, so the transcript cannot always represent each person's contribution as a separate turn. Participant history records that an actor prompted the session, not which words were theirs.

GitHub-backed sign-in through Cloudflare Access or Tailscale Serve automatically verifies the person's GitHub account under Settings → Profile → Identity. Public Co-authored-by credit remains a separate, default-off Git co-author credit toggle. Attribution uses that explicit preference plus the durable profile participant records described above, not display names or the four-person facepile projection. See User model for privacy, eligibility, bounds, account changes, and disabling future credit.