Teams and many Gateways
Share one Gateway with a team
Let several people use one Gateway, each signed in as themselves, in shared sessions, with a role that limits what they can do.
Read when: Your colleagues should work with the same agents, or someone else needs access to your computer.
OpenClaw runs in two shapes. A personal claw is one person's assistant on their own computer. A multiplayer claw is one Gateway a whole team shares: everyone signs in as themselves, works in shared sessions they can all open and steer, and has a role that limits what they can do. Both are the same product; the difference is configuration.
How it works
Ways people sign in
| Sign-in | What each person is | Config |
|---|---|---|
| Tailscale Serve | Their Tailscale identity | gateway.tailscale.mode: "serve" with gateway.auth.allowTailscale |
| Trusted proxy (for example Cloudflare Access) | The email the proxy vouches for | gateway.auth.mode: "trusted-proxy", trustedProxy.userHeader, allowUsers |
| Shared token or password | Everyone is the one Owner profile | gateway.auth.mode: "token" or "password" |
| OpenClaw ID members (Labs) | An invited OpenClaw ID account, as Operator or Viewer | See OpenClaw ID |
Per person and shared
| Each person has their own | Everyone shares |
|---|---|
Profile (name, avatar, appearance), role, Git co-author setting, personal USER.md per agent (with 2 or more people), personal model accounts, mentions inbox, recents, personal skills | Agents, their workspaces and tools, channels, system and agent credentials, config, the computer's user account |
Who can do what in a session
| Session access | Meaning |
|---|---|
| Shared | Everyone with access can send. |
| Read-only | Others can only read. |
| Suggest | Others suggest for approval. |
| Draft | Creator and admins only. |
Every session records its creator (fixed), its owner (assignable with Assign to me or Assign to…) and everyone who took part. People in the same session see each other, including a live draft marked "Typing · not sent". Typing @ and a name notifies that person in Inbox → Mentions.
Roles
Roles live in gateway.roles. Each role sets four things:
| Setting | Values |
|---|---|
sessions.others | "none" hides other people's sessions, "view" reads them, "suggest" reads and suggests, "write" takes part. A person always owns their own sessions. |
agents | "*" or a list of agent IDs the person may use. |
scopes | The most this role can do, for example operator.read, operator.write, operator.approvals, operator.admin. |
sandbox | "inherit" or "required". |
The role that applies is the one set with users.setRole, else one matched by GitHub login, else default. Changing a role reconnects that person with it.
roles: {
default: "observer",
definitions: {
observer: { sessions: { others: "view" }, agents: [], scopes: ["operator.read"] },
member: {
sessions: { others: "write" },
agents: ["assistant"],
scopes: ["operator.read", "operator.write", "operator.approvals", "operator.questions"],
},
administrator: { sessions: { others: "write" }, agents: "*", scopes: ["operator.admin"] },
},
}
From docs/start/multiplayer.md, docs/gateway/operator-scopes.md:291-390, docs/concepts/multi-user.md, docs/concepts/user-model.md.
What you need
| What | Why |
|---|---|
| A sign-in in front of the Gateway that says who each person is | Tailscale Serve or a trusted proxy. A shared token makes everyone the same person. |
| Admin rights | To set roles and assign them. |
| Optionally, your team's chat | For example Slack, with the bot answering only when mentioned. |
Turn it on
- Gateway configPut a sign-in in front: Tailscale Serve with
allowTailscale, or a trusted proxy. Do not open the Gateway to the internet without one. - Each teammateOpen the Control UI through that sign-in. Each person gets their own profile the first time.
- Gateway configAdd
gateway.roles(example above). - TerminalFind each person's profile and set their role:
openclaw users list --jsonopenclaw gateway call users.setRole --params '{"profileId":"<id>","role":"member"}' --json - Control UIWork together: assign sessions with Assign to…, mention people with
@, and set each session's access in Session sharing.
Check it works
| Where | What you see |
|---|---|
| Two browsers, two people | Both see the same session, its owner and each other's presence. |
openclaw users list --json | Each person with effectiveRole and where it came from (roleSource). |
| A person with an observer role | Can read but not send; sees no agents outside their list. |
openclaw security audit | No warnings about the sign-in. |
Limits
| Limit | Detail |
|---|---|
| Isolation | None between people. One Gateway per tenant when people must not see each other. |
| Personal Claude account | A personal Anthropic account takes an API key, not a Claude subscription token. |
| Gateway-wide scopes | operator.read and operator.write reach every session; give guests operator.sessions.write instead. |
| Personal files | USER.md per person only appears with 2 or more people. |
| Git co-author credit | Needs a verified GitHub sign-in, or name and email headers from the proxy. |
On Urbicana today
A member's computer is built for one person: the door admits the emails in ALLOW_USERS, which Rails sets to the member's own, and the Gateway trusts the door's x-forwarded-user header.
| Step | Today | Why | Fix and cost |
|---|---|---|---|
| A teammate signs in | Refused | Any email not in ALLOW_USERS gets "This agent is not yours." (agent-proxy/src/proxy.ts:951). | Rails passes a comma-separated list; the door already reads one. A Rails change, then the machine restarts. |
| What a teammate could do | Full admin | Every allowed email gets operator.admin (proxy.ts:661-664). | Grant admin to the owner only, or add gateway.roles to the seed. Small, but how to mark the owner is not decided. |
| Roles set by hand | Lost on restart | Each boot replaces the gateway block with the seed's (entrypoint.sh:105). | Put roles in the seed (gatewayConfig in proxy.ts). |
| A teammate's own Claude subscription | Not supported | Personal Anthropic accounts take an API key only (docs/concepts/multi-user.md:94). | None in this code; a teammate would use the owner's subscription. |
| Git co-author credit | Missing | The door sends only user, address, protocol and host. | The door adds name and email headers and the seed sets trustedProxy.gitCoauthor. Small; where the name comes from is not decided. |
| Profiles, presence, mentions | Not tried | They appear on their own once a second person signs in. | Try after the first fix. |
Videos to record
Record on a Gateway with Tailscale Serve or a trusted proxy, with two people in two browsers.
20 · Two people, one session
Two browsers- Person 1 opens the Control UI. Person 2 signs in from another browser.
- Both open the same session. Each sees the other's avatar.
- Person 2 types. Person 1 sees "Typing · not sent".
- Person 2 sends. The session row shows both people.
21 · Assign a session like an issue
One browser- Right-click a session → Assign to… → pick a person.
- "Created by" becomes "Owned by".
- Filter the sidebar to Involving me.
22 · Mention a teammate
Two browsers- Type
@and pick a person. Will notify. - Send.
- The teammate opens Inbox → Mentions and opens the entry.
23 · Roles in one minute
Terminal and two browsers- Show
gateway.roleswith observer, member and administrator. - A teammate signs in. They can read but not send.
openclaw users list --json."effectiveRole":"observer".- Run
users.setRolewithmember. The teammate reconnects and can send.
24 · Share or lock a session
Two browsers- Session sharing → Session access from Shared to Read-only.
- The teammate can no longer send.
- Turn on Anyone with the link, Make public, Copy public link.
- Open it signed out. A read-only transcript.