On this page
On this page
Setup guides and reference
Multiplayer
OpenClaw runs in one of two shapes. A personal claw is one person's assistant on their own machine - see Personal assistant setup. A multiplayer claw is one Gateway that a whole team shares: a bot in the workspace chat you already have, shared sessions everyone can open and steer in the Control UI, and roles that bound what each person can do. Both are the same product - multiplayer is configuration, not a separate edition.
This page covers both halves of running a multiplayer claw. Quick setup gets a team working together on any always-on host. Production deployment adds the always-on Linux pieces: Cloudflare Tunnel and Access, individual sign-in, verified GitHub identity, role bootstrap, read-only sharing from another Gateway, and recoverable operations.
How we build OpenClaw with OpenClaw
We use team.openclaw.ai as a multiplayer claw and shared development workspace for OpenClaw itself. Maintainers and agents work through repository changes in the same conversations:
- Start a repository task. Choose the OpenClaw project in New conversation and select Worktree for a managed branch and checkout. Give the agent a concrete change and the checks that demonstrate it works.
- Work together. Teammates with access can open the session, add context, and steer the next turn. Assign an owner for follow-through; creator and participant attribution remain separate.
- Review the work. Inspect the agent's results and the checkout diff, run the relevant tests, and resolve review findings before landing.
- Publish and follow CI. Use Publish PR after checking the selected GitHub publication account. The linked pull request and its CI details stay available in the conversation.
The screenshot shows a live repository task, cropped to its conversation. See Chat and code review for the diff, file, and PR controls.
Building the next version does not replace the running server. We keep deployment under its own approval and lifecycle owner, with coordinated activation and verification. See Keep operations recoverable.
One trust boundary
A gateway is one trust domain. Everyone who can message a tool-enabled agent shares that agent's delegated tool authority, and everyone with operator access shares one control plane. That is the right model for a team whose members already trust each other - session ownership, presence, and roles are collaboration guardrails inside the boundary, not isolation between adversaries. Keep untrusted code in sandboxes or remote workers.
If you need to serve mutually untrusted people or organizations, run one gateway per tenant instead, ideally on separate OS users or hosts: Security trust model.
Before you begin
- A host for the Gateway that stays on: a small VPS, an office Mac, or any supported install target.
- OpenClaw installed and onboarded on that host - see Getting started.
- A chat workspace the team already uses (Discord, Google Chat, Mattermost, Microsoft Teams, Slack, Telegram, ...) - see Channels.
- A strong latest-generation model. Shared gateways see more varied input than a solo setup, and modern models are substantially more resistant to prompt injection - see Security.
- Optional: teammates' GitHub accounts, if you want verified identity and commit credit.
A production deployment additionally needs:
- A Linux host with persistent storage and a dedicated service account. Use a supported Node runtime and an OpenClaw installation. Plan its storage layout first; see Optimal setup.
- A Cloudflare-managed domain, Zero Trust account, and
cloudflaredon the host. - An identity provider and an explicit policy for who may sign in.
- Model credentials and, if needed, a bot account for your team chat.
- Administrative SSH access, a private secret store, and a backup destination outside the server's failure domain.
Quick setup
These steps work on any host that stays on. For the full Linux and Cloudflare deployment, continue with Production deployment afterwards.
Step 1: Give the team access to the Gateway
The Gateway binds to loopback by default. Give teammates access through authenticated ingress instead of a public bind:
- Tailnet (recommended): put the host on your tailnet and enable Tailscale Serve. With
gateway.auth.allowTailscale, Control UI sign-in can use each person's Tailscale identity - no shared secret to distribute. - Trusted proxy: front the Gateway with an identity-aware proxy such as Cloudflare Access - see Trusted proxy auth.
- Shared secret: token or password auth works for small teams, but everyone uses one owner profile instead of per-person identity - see Authentication.
The identity-backed options are worth the setup: they are what turns "someone did something" into "who did what" in the session UI and commit credit below.
Step 2: Connect the team chat
Connect the channel your team lives in. Example: a Slack bot, allowed in one team channel, that replies when mentioned:
Group chats are a first-class deployment. The defaults are already team-shaped. Group access is allowlisted per room, and replies require a mention. DMs stay on the pairing default: the first time a teammate DMs the bot they get a pairing code. Approve it with openclaw pairing approve slack <code>. So the bot participates when addressed and stays quiet otherwise. In a private room whose members you trust, that is all the gating you need. For broad or public rooms, add sender allowlists and contextVisibility - see Groups.
If the same people should be allowed across several channels, define the list once as an access group and reference it from each channel's allowlist.
Step 3: Sign the team in to the Control UI
With per-person sign-in, each teammate opens the Control UI through the ingress from step 1. Each one gets a durable Gateway profile: display name, avatar, and per-person appearance preferences. Shared-secret connections use the same owner profile. With Cloudflare Access or Tailscale Serve, GitHub-backed sign-in verifies the account behind the profile - see User model.
Teammates can also create and import personal skills under Plugins → Skills without permission to change shared Gateway configuration. Skills stay personal until explicitly shared with the team. A session retains its selected revisions when another teammate joins; changing its assignee does not replace its skills. Your existing workspace skills remain in place, and extra channel identities for one operator do not enable the team-specific guidance.
Step 4: Work in shared sessions
A conversation that starts in the team channel can continue as a session the whole team can open, steer, and take over. Multi-user mode gives every session three layers of attribution: an immutable creator, an assignable owner, and the history of people who actually prompted. Assign sessions like GitHub issues from the session context menu. Multi-user mode also adds live presence. Presence shows who is viewing and who is typing, with drafts that never reach the model or the transcript.
For coding work, verified GitHub identity pays off at the commit: with Git co-author credit enabled, commits from a shared session carry Co-authored-by trailers for the people who steered it, and generated pull requests link back to the session so reviewers can read the conversation that produced the diff.
Teammates can add their own provider accounts under Settings → Profile → Connected accounts, using the sign-in methods offered by each provider. Their new sessions prefer that account without making it a Gateway-wide default. Collaborators use the session's selected account, and shared same-provider failover can still apply - see Per-person model accounts.
To let teammates read selected sessions from a personal Gateway without controlling that machine, use Session Share. The source operator chooses session groups and pairs a node that advertises only the two read-only session commands. Shared transcripts appear under that node in the team Control UI; viewing requires permission to view others' sessions, and does not allow continuing the source session.
Step 5: Bound what each person can do
Named operator roles bind authenticated profiles to a policy: which sessions they can touch, which agents they can use, a maximum set of operator scopes, and whether their new sessions must be sandboxed:
Give guests the session-only operator.sessions.write scope, which also permits reading. operator.read and operator.write are Gateway-wide: they add channel sends, node and computer control, logs, the user directory, and other shared surfaces that a guest does not need. With sessions.others: "view", guests can still read every shared session, including tool output. Keep sensitive work in draft sessions.
Assign roles with the users.setRole Gateway method; see Named operator roles for the full policy surface and Permission modes for per-session tool posture. To admit and expire individual outside guests, see Invite guests.
Coding as a guest
A sandbox-required guest can work without an administrator role. With the default
workspaceAccess: "none", file and shell tools use a writable private workspace,
not the shared agent workspace. Managed skill instructions stay read-only.
Child sessions inherit the parent's sandbox requirement, even when the agent's
default sandbox mode is off.
Local container sandboxes have no network by default. If guests need to clone public repositories or install project-local dependencies, explicitly enable outbound networking for the coding agent, for example:
Network access does not grant host execution or inject shared credentials. Use a sandbox image with the required runtimes already installed; the read-only root filesystem still prevents system package installation. Enabling egress allows requests to destinations reachable from the container, so use a restricted container network when that access needs tighter controls. See Sandboxing for workspace and network policy.
Guests publish through Publish PR from sessions they created. Publication
uses the shared GitHub account and opens a pull request by default. To create a
draft, ask the agent to publish with draft: true on github_publish. Updating an
existing PR preserves its draft or open state. Publication does not merge the PR. Protect the
base branch with GitHub rules so the shared account cannot
merge or bypass review. If the checkout's origin is the upstream repository,
guest branches live in that repository and its pull request workflows receive
repository secrets. Point origin at a fork owned by the shared account so
guest pull requests come from the fork, where GitHub withholds secrets from
pull_request workflows by default. See
Workflow and CI changes.
Verify the quick setup
- Mention the bot in the allowed team channel and confirm it replies there.
- Open the Control UI as two different people: both should see the session, its owner avatar, and each other's presence.
- Run
openclaw security auditon the host and resolve anything it flags about inbound access or exposure.
Production deployment
This section connects the pieces of a production multiplayer deployment: a persistent Gateway, Cloudflare Tunnel and Access, individual sign-in, GitHub identity, operator roles, and optional read-only sharing from another Gateway. Start with one server. Add a separate release or staging server when it needs different credentials, update timing, or operators.
It uses team.example.com for collaboration and
release.example.com for an optional second Gateway. Replace them with your
own hostnames; each Gateway needs its own configuration and state.
Optimal setup
A busy multiplayer claw runs many agents, managed worktrees, and SQLite databases on one host. Its storage layout decides how responsive it stays under that load.
Keep OpenClaw state off the worktree filesystem. Put the state directory
(~/.openclaw by default, or OPENCLAW_STATE_DIR) on XFS
or ext4. Put managed worktrees on Btrfs with
worktreeRoot,
where snapshots make new checkouts nearly instant; XFS reflinks also work. See
Filesystem acceleration.
Btrfs commits are filesystem-wide. While a commit runs, SQLite reads and writes that update file metadata can wait for it, and worktree snapshot creation and deletion make commits long. On a busy shared Btrfs volume we have measured single commits that took minutes and database commits that stalled for seconds. OpenClaw already creates SQLite stores with NOCOW on Btrfs, which limits fragmentation but does not remove these waits.
Keep the whole state directory on one filesystem. OpenClaw moves files between its subdirectories with renames, and a rename cannot cross filesystems.
Mount with noatime. Under the default relatime, a database that is
written continuously gets an access-time update on almost every read. On Btrfs,
each update joins the current transaction and can wait for a running commit;
lazytime does not avoid this on Btrfs. OpenClaw does not read access times.
You can switch a mounted filesystem without a restart, then add noatime to its
/etc/fstab entry:
Choose disks for the databases. Mirror the state filesystem (RAID1) when you can, so one failed drive does not take the databases with it. Drives with power-loss protection acknowledge cache flushes quickly, which keeps SQLite fsync latency low.
Move an existing Btrfs-only host. Apply noatime first; it needs no
downtime. Moving state then needs block-device space outside Btrfs: a new drive
or partition, or space at the end of the device released with
btrfs filesystem resize. Stop the Gateway, copy the state directory, mount the
new filesystem at the same path, and bind-mount the worktree directories back
from Btrfs so recorded worktree paths stay valid. If the new filesystem lives in
space released from Btrfs, never grow that Btrfs filesystem again
(btrfs filesystem resize max): it would overwrite the new filesystem.
1. Install under one service account
Complete Getting started as the account that will run the Gateway, including model setup and managed-service installation:
Keep subsequent configuration, backup, and update commands under that same
account. Running setup as root later creates a different home and can select a
different Gateway. Preserve any custom OPENCLAW_STATE_DIR,
OPENCLAW_CONFIG_PATH, and profile selector in the service and maintenance
environment. On Linux, verify that the user service remains available after
logout; see Gateway service management.
Allow SSH only from your administrative network. Keep the Gateway on loopback and do not open TCP 18789 publicly. The Cloudflare Tunnel makes an outbound connection; it does not need an inbound Gateway firewall rule.
Choose an agent ID, such as assistant, and use it consistently in channel
bindings and role agent lists. The examples below assume that agent already
exists. Keep shared workspace instructions concise and keep deployment secrets
out of AGENTS.md, IDENTITY.md, and personal instructions.
2. Configure the public URL and authenticated ingress
Create an Access application for team.example.com before exposing the tunnel.
Initially admit only the administrators who will finish setup. Choose an Access
policy backed by your intended identity provider; do not create a public bypass
for the Control UI or its WebSocket.
Follow Cloudflare Tunnel and Access to create the tunnel and DNS record. Its ingress should route only the chosen hostname to the loopback Gateway:
Protect the tunnel credential file and run cloudflared as a service. Preserve a
private local maintenance password using a SecretRef; the
example below expects OPENCLAW_GATEWAY_PASSWORD to be available to both the
Gateway service and the owning account's CLI. Do not distribute that password to
teammates: local password access represents the shared owner.
Merge the following into the existing configuration, preserving your agents, models, and channels:
Remove any earlier gateway.auth.token and OPENCLAW_GATEWAY_TOKEN when switching
to trusted-proxy auth: a shared token is incompatible with this mode. The private
local password fallback is supported. Validate the configuration, then use the
owning service's lifecycle to activate setup changes:
allowLoopback trusts local processes as well as cloudflared. OpenClaw checks
the proxy source and required headers; their presence is not Access JWT
signature verification. The external authentication boundary is Access plus the
private origin. Do not run hostile workloads with access to this listener. See
Trusted-proxy auth for header and client-address
requirements.
Set the public URL once
publicOrigin tells OpenClaw which external URL to advertise and supplies the
default browser-origin allowlist. For a Control UI served from that same origin,
leave gateway.controlUi.allowedOrigins unset.
Set an explicit allowedOrigins list only when you need a different browser
policy, such as a separately hosted Control UI. An explicit list replaces the
public-origin default; include the public origin too if both should connect.
An explicit empty list does not inherit publicOrigin. Existing local and
private-network origin rules still apply.
Without gateway.publicOrigin, the browser can work while an agent's session
lookup has no link-building rule and its runtime context has no session URL.
Set the bare HTTPS origin, with no path, query, or credentials. If the Control UI
uses a path prefix, configure gateway.controlUi.basePath separately.
For an existing server missing only this setting:
This conditional write refuses to overwrite an existing value. With live config
reload enabled, the public origin applies without a Gateway restart. When the
allowlist is inherited, browsers using the old origin must reconnect from an
accepted origin. An explicit allowlist remains unchanged. Newly
prepared tool contexts receive the link rule; an already-running turn can retain
its earlier context. Set https://release.example.com on the second server,
rather than copying the first server's URL.
Existing installations retain their explicit allowlists, including values saved
by earlier setup or Doctor runs. After upgrading to a version with this default,
remove the list with openclaw config unset gateway.controlUi.allowedOrigins if
you want it to follow publicOrigin; check that no additional UI origin is needed
first. Startup and Doctor leave the inherited default out of saved config.
3. Bootstrap administrators and assign roles
Have the administrator sign in through Access once. Their durable Gateway profile is created, initially with the observer role. From the local maintenance shell, list profiles and identify the verified person:
The role change closes that person's active Gateway connections. Reconnect the
browser. The administrator needs both the explicit identityScopes grant and
the administrative role ceiling. The local shared owner remains available for
maintenance and cannot be assigned a personal role.
Extend the Access policy to your team. After each member first signs in, assign
their profile the member role through the same method. An observer can read
visible sessions but cannot start agent work in this example. Do not temporarily
make the default role administrative to bootstrap someone.
The example deliberately auto-approves UI devices with non-admin scopes, then
limits each person through their role. Omit automatic approval if you want manual
device enrollment. Do not add operator.admin to the automatic device grant;
use selected verified identities instead. See Operator scopes
for narrower session-only and sandbox-required roles.
For a release Gateway, keeping the observer default and assigning only a few release operators is useful. Role assignments are local to each Gateway; admission to the collaboration server does not grant release authority.
Invite guests
To admit individual people outside the team for a limited time, use the Visitor Access plugin, available from a source checkout. It manages one dedicated Access allow policy, adds each invited email or verified GitHub account to it, and ends Gateway access when the grant expires (14 days by default) or is revoked.
Visitor Access requires gateway.roles.default to be a restricted guest role:
Everyone who resolves to the default role needs a current visitor grant. Before
switching the default, assign every staff member an explicit role with
users.setRole or gateway.roles.assignments.byGithubLogin. An administrator
then asks the agent to call visitor_invite with a GitHub login or email and an
optional note, such as a session link to start from. The result includes short
invitation text to hand to the guest: who invited them, the sign-in address from
gateway.publicOrigin, the identity to sign in with, the expiry, and the note.
Guests can create sandboxed sessions on the listed agents and publish open or explicitly requested draft pull requests from their own sessions through the shared GitHub account. They cannot merge through OpenClaw. Before inviting anyone, review the paths a required sandbox does not contain, listed under Named operator roles, and Workflow and CI changes for publication.
4. Synchronize people with verified GitHub identities
Keep these responsibilities separate:
| Responsibility | Configuration or owner |
|---|---|
| Who can reach the website | Cloudflare Access and its identity provider |
| Which person is signed in | Verified sign-in and the Gateway profile |
| What that person may do | Connection scopes and named operator roles |
| Which account publishes code | System, agent, or personal GitHub connection |
With the GitHub identity provider in Access, OpenClaw queries Access's identity endpoint, verifies that its email matches the authenticated proxy principal, and resolves the immutable numeric GitHub account ID to its current login. Names and avatars can then update through normal sign-in/profile synchronization. Saved custom profile choices remain governed by the User model.
This is sign-in-driven synchronization, not a background import of every GitHub organization member. Profiles and roles are local to each Gateway. The same verified GitHub account can identify a person on two servers without making their local profile IDs equal.
Use an OIDC provider without losing existing profiles
OIDC sign-in can retain an existing profile through its verified email. Before changing providers or email addresses, link the new verified address to the existing person from an administrator's maintenance session:
Before switching sign-in, also add the new verified address to any
gateway.auth.identityScopes grants that person needs. For the administrator
above, the new address needs its own ["operator.admin"] entry: linking an email
preserves the profile and role but does not copy the old address's scope grant.
Update any Access policy or trustedProxy.allowUsers email allowlist as needed.
Keep the old grant during the migration, verify the profile, aliases, role, and
effective permissions after reconnecting with the new address, then retire the
old grant if that identity should no longer have access. Do not merge people by
display name or copy profile databases between live servers.
For verified GitHub credit through OIDC, configure the explicit
cloudflareAccessOidc issuer, provider ID, and account-ID claim described in
Cloudflare OIDC setup.
The provider must verify the linked GitHub account, and Access must forward its
numeric account ID claim. A username or arbitrary OIDC subject is not a verified
GitHub account ID. Conflicts require administrator linking; the claim does not
assign a role or change the account that publishes code.
If admission depends on GitHub organization membership or repository permission, enforce that in Access or the identity provider. An organization policy for the GitHub IdP does not automatically cover a separate OIDC IdP. Understand when eligibility is rechecked and revoke existing Access sessions when removal must take effect before their normal expiry.
Configure GitHub access for repository work
Install gh for the Gateway service account. In Settings → Profile → GitHub
connections, an administrator chooses For the system to connect the shared
publication account. An agent can have an administrative override under
Agents → Tools. Verify the selected account before publishing.
My GitHub is a separate personal connection for explicitly selected publication. It does not change the shared shell account or establish verified sign-in identity. Git co-author credit is also separate: it uses verified human participants and their saved consent preference.
Use the Gateway's Publish PR action for its managed publication path. Managed identity does not rewrite an existing local repository's SSH remote or Git network credentials. Successful account verification also does not prove write permission to every repository. See GitHub identity for agent tools.
An optional gateway.controlUi.github.token serves GitHub lookups and project
discovery. For Enterprise, set gateway.controlUi.github.host to the selected
gateway.github.host so the service credential is used only for that host.
Keep it in a dedicated SecretRef instead of accidentally selecting a
publisher through a process-wide GH_TOKEN or GITHUB_TOKEN. Read credentials,
publication credentials, and each person's sign-in identity have different jobs.
5. Connect chat and remote clients
Follow Step 2: Connect the team chat for channel allowlists, mention requirements, and DM pairing. Website admission does not configure the bot's channel allowlist. If a channel sender should resolve to an existing person, use the explicit administrator-attested channel identity links in User model; matching display names are insufficient.
Browser cookies do not authenticate CLI, TUI, or node connections. Remote CLI
clients need gateway.remote.edgeAuth and their own Access login; see
Remote access.
Nodes and cloud workers need a route that authenticates every required join,
WebSocket, and transfer request. Prefer the Access service-token setup in
Cloudflare machine access.
A browser working while openclaw connect receives HTTP 302 means the machine
request reached Access, not that node pairing succeeded. Keep machine credentials
out of browser links and do not bypass Access for the whole Gateway.
Trusted relay plugins can use principal-bound remote ingress for a remote Control UI and MCP calls; MCP Relay uses it to bring a Team Gateway into ChatGPT and Codex. A Team grant belongs to the verified person who approves it in this Gateway's Control UI, never the shared owner or the loopback password. The plugin's consent flow should default to Read + write and offer Full within that person's current role. Full gives administrators admin access and does not elevate restricted roles. Both UI and RPC must share the same live grant; the plugin and relay own expiry and revocation. Ingress reconnects are tokenless and issue no reusable device token. This SDK capability does not itself install or configure a relay service.
6. Give widgets a separate sandbox origin
Inline Canvas widgets and MCP Apps use a separate sandbox listener. Behind HTTPS ingress, configure a second hostname that reaches that listener instead of letting the browser try the Gateway's public hostname on port 18790:
Create a separate proxied DNS CNAME for team-sandbox.example.com pointing to
<tunnel-id>.cfargotunnel.com, then add
team-sandbox.example.com -> http://localhost:18790 to the tunnel ingress before
its catch-all rule, using the configured sandbox port if different. Adding an
ingress rule alone does not create the DNS record. See Cloudflare's
tunnel DNS routing.
Keep this hostname outside the interactive Access application and route it only
to the sandbox listener, never the main Gateway. The sandbox serves the isolated
renderer shell; authenticated widget content travels through the Gateway. Do not
put other authenticated applications on the sandbox origin.
Canvas can start this listener lazily even when MCP Apps are not enabled. Enable MCP Apps separately only if you need that capability; see MCP Apps. Test a real widget after setup: a healthy chat page does not prove its iframe can load.
7. Share selected sessions from another Gateway
To show release-server conversations on the collaboration server, configure Session Share. On the source, enable the plugin with an explicit group:
On the receiver, the gateway.publicOrigin configured above supplies the join
endpoint when the loopback Gateway has no other advertised route. For the Access
service-token topology above, use that same HTTPS hostname. If you operate a
separate authenticated machine endpoint, set
plugins.entries.device-pair.config.publicUrl to its URL instead:
Join codes retain existing Tailscale, remote, and bind-derived routes before
falling back to publicOrigin. The pairing-specific publicUrl override takes
precedence over discovery. The device-pair plugin does not need to be enabled
for core join-code creation.
See Node onboarding.
On the source, run the node under the source Gateway's account, state directory, and configuration, with exactly the two read-only session commands:
Approve the intended device on the receiver and confirm the two-command allowlist. Move selected source sessions into the Team group. Subagents and incognito sessions remain excluded. Removing the group revokes new reads but cannot retract text someone already read.
Receiver-side linkGitHubIdentities: true, configured for the paired node ID,
can display verified remote GitHub account IDs as matching local profiles.
This is attribution, not a role or ownership grant. The view stays read-only;
it does not authorize continuing the source session or executing commands there.
An ordinary source session URL still points to that source's own publicOrigin
and requires source access.
8. Verify the complete flow
Use both host checks and two real user accounts:
- Run
openclaw config validate --json,openclaw gateway status --deep, andopenclaw security auditas the service owner. Resolve unintended exposure. - Confirm that an unauthenticated public request meets Access, then sign in and reach a connected Control UI. An Access redirect alone does not prove Gateway health.
- Confirm distinct profiles for two people, administrator/member behavior, and observer restrictions. Reconnect after changing a role.
- Ask the agent for the current session's link and a different visible session's
link. Open both and check the host and destination. A missing link rule points
to
publicOrigin, notallowedOrigins. - Exercise one model turn, the intended channel reply, a widget if enabled, and one node connection if used. Check the selected GitHub account and actual repository permissions before a requested publication.
- If sharing sessions, read a selected source conversation from the receiver, then remove a disposable shared session from the source group and verify that a fresh receiver read is denied.
Keep operations recoverable
Use one lifecycle owner per installation. For a normal managed installation,
use openclaw update and the native Gateway service commands. If an external
deployment system owns the service, use that owner instead; do not race it with
a second updater, a direct restart, or an in-place source build. Coordinate an
interruption with the team and verify the serving version after activation.
See Updating and Restart recovery.
A collaboration server and a release server can deliberately follow different
update schedules. Make each policy explicit; copying configuration should not
silently enable automatic deployments on the other server. Keep visual
environment labels distinct through gateway.controlUi.environment.
Create and verify a backup before substantial updates:
The restore command stages recovery data; activating it is a separate offline operation. Keep credentials protected and an off-host copy. Use the native backup owner's SQLite snapshots rather than copying live database/WAL files. Do not roll a live server back by overwriting its current databases with an old snapshot. See Backups.
Budget persistent disk and temporary space for dependencies, builds, SQLite
snapshot verification, and backups. A large free root disk does not help a
small /tmp quota. Configure needed temporary space in the actual service
environment, not only an SSH shell. On Btrfs, inspect metadata allocation and
retained snapshots as well as df: snapshots can pin space after files are
deleted. Retire only known disposable data and completed recovery points.
For rootless Podman sandboxes, budget one kernel session keyring per running container under the Gateway service user's per-user quota. On a busy host, set kernel.keys.maxkeys=2000 and kernel.keys.maxbytes=200000 with sudo sysctl -w kernel.keys.maxkeys=2000 kernel.keys.maxbytes=200000, and persist both values in /etc/sysctl.d/61-openclaw-keyring-quota.conf. A create keyring: Disk quota exceeded error can mean this quota is exhausted even when the filesystem has space; inspect sysctl kernel.keys.maxkeys kernel.keys.maxbytes on the container engine host.
Monitor process restarts, readiness, channel connectivity, storage, and real session/model failures. Keep incident alerts outside the Gateway that might be down. A green HTTP root, a quiet bot, or a successful Access login is not enough to establish that the service can complete work.
Troubleshooting
| Symptom | Check |
|---|---|
| Browser works; agent cannot provide session links | Set this server's gateway.publicOrigin; prepare a new turn after reload. |
| Access succeeds but Gateway rejects the connection | Check loopback trust, forwarded client addresses, required identity headers, and allowedOrigins. |
| Administrator signs in as an observer | Assign the real profile's administrative role and grant the verified identity operator.admin, then reconnect. |
| OIDC migration creates another person | Verify the sign-in email and explicitly link its alias to the existing profile. |
| GitHub login looks right but publication uses another account | Check the system/agent/personal publication selection and repository Git authentication separately. |
| Chat works but widgets fail | Check the distinct sandbox origin, tunnel port, and absence of an interactive Access challenge on that hostname. |
| Node join receives HTTP 302 | Supply machine Access authentication on every required route. |
| Shared sessions are missing or names do not link | Check source group, node account/state, two-command allowlist, receiver role, and verified numeric GitHub IDs. |
| Update fails despite free disk | Check service temporary-space quota, filesystem metadata, and retained snapshots before retrying. |
When to split things up
- Separate workspaces or personas (projects that must not share memory or files): use multiple agents on one gateway - see Multi-agent routing.
- Mutually untrusted users, customers, or organizations: separate gateways, ideally separate OS users or hosts - see Security trust model and Security.
Related
- Why OpenClaw: working together - the team collaboration surfaces in one place
- Multi-user mode - ownership, participants, and owner filtering in depth
- Operator scopes - connection roles, scopes, and role assignment
- Groups - group behavior, mention gating, and context visibility
- Security - the trust model behind the one-boundary rule
