Per-member env files · workspace isolation · loggable acceptance · six-step rollout · Mac pool handoff
Platform leads running one 24/7 OpenClaw Gateway for a small team hear the same question weekly: can we share it? Yes, but if model keys, channel tokens, and workspace paths live in one unaudited .env, the next misconfiguration becomes a full outage. This article answers who has which problem (multi-user access, key rotation, unclear ownership), then gives a conclusion: treat sharing as compartments (separate env_file roots, data directories, and port tables) plus least privilege plus segmented log acceptance. You will get pain points, a selection matrix, a six-step runbook, hard parameters, and a sign-off matrix. For namespace-level CLI failures read Compose networking triage; for memory limits and log rotation see Compose production baseline; for a second stack on the same host see multi-instance isolation; for channel exposure see production hardening checklist; for install language parity use install and doctor checklist; for dedicated Mac capacity use order page.
Sharing is not the same as pasting the admin key into a group chat. When each engineer exports the same variable names locally, or CI hardcodes one path, you get one Gateway process and N conflicting truths. These five patterns dominated 2026 support threads; turning them into written rules beats buying more compute.
Keys coupled to workspaces: storing provider keys next to channel secrets in a single repo-level .env means one mistaken commit forces a fleet rotation, and logs rarely show which CLI performed the last write.
Missing bind and port matrix: a staging stack grabs adjacent ports, production looks healthy, but health checks hit the wrong process; on-call falls back to reboot roulette.
Channel allowlists versus real egress: some members exit through a corporate proxy, others use home broadband; allowedOrigins may cover only one shape, so only Alice works while Bob always sees 403, misread as RBAC.
No compartment acceptance language: launch reviews ask “can it send a message?” but never “does each member mount a distinct env_file and backup split?” Compliance asks for evidence the next day and the team has none.
Drift from the Mac pool handoff path: Gateway lives on a VPS while heavy builds run on remote Macs; without one topology sheet for SSH hostnames, private DNS, and inbound callbacks, webhooks flap and teams wrongly raise model timeouts.
Map the taxes to deliverables: port table, env_file map, channel origin list, minimal backup set, and one smallest channel probe command. Without those five artifacts, do not add new members to the production profile. It feels bureaucratic; it is how tacit knowledge becomes diffable configuration.
Add an organizational lens: shared Gateways change more often than solo homelabs. Reviews must graduate from “feature works” to rollbackable, bisectable, and handoffable. Every change should list old versus new values, impacted members, and a rollback window such as dual-written keys for N hours.
Finally, sharing is not sharing root. Even with one Docker host, use named volumes, subdirectory ACLs, and read-only mounts to pin writable workspace boundaries; otherwise one mistaken delete removes both production and staging session state. Read COMPOSE_PROJECT_NAME isolation to avoid “two compose files, one mount point” traps.
Once taxes become checklists, teams ask the next honest question: separate Gateways per person, or one Gateway with compartments? The next section puts cost, exposure, and ops load on the same review page.
There is no universal answer, only a fit for team size, compliance, and how many TLS endpoints and webhooks you want to operate. Print the matrix: pick one default for the quarter and write a footnote for when you must escalate to the next tier.
| Mode | When it fits | Main benefit | Main cost |
|---|---|---|---|
| Per-member Gateway | Up to three people, strong isolation, or one-audit-trail-per-human rules | Smallest blast radius; rotations do not cascade | CPU, RAM, duplicated webhooks, multiple TLS lifecycles |
| Single Gateway, compartmented keys | Five to fifteen people, shared callback domain, unified dashboards | Ops surface concentrates; metrics align | Requires strict env_file and directory separation or drift explodes |
| Single Gateway, role-based volumes | Platform versus product teams need writable versus read-only consumption | Fewer installs; one place to apply hardening checklists | Volume permissions and CI mounts get subtle; reviews must be finer |
Sharing only works when every difference maps to a replaceable file, not to shared mutable defaults; otherwise you get economies of scale for incidents, not for throughput.
If you land on single Gateway with compartments, define a compartment as a machine-checkable triple: COMPOSE_PROJECT_NAME, data directory mount, and per-member env_file. If you cannot describe it in three lines, the compartment is not real yet.
Cheapest observability first; stop and save outputs when any step fails. If wizard field names differ, reconcile with install and doctor checklist.
Freeze the skeleton: separate roots for production and staging, README forbids cross symlinks, choose named volumes or bind mounts and version the choice.
Split env_file: baseline (listen, log level) versus member secrets (models and channels); CI injects read-only tokens and never writes back to the host.
Check the port table: published ports, in-container binds, and host firewall must triangulate; cross-check with the symptom tree in Compose networking triage.
Minimal channel probe: each member runs send-receive with their CLI or browser origin, capture timestamps and request identifiers; every 403 must include an origins diff.
Backup drill: export the smallest restorable set (config plus session policy), cold start on staging, write RTO and RPO numbers in the change footnote.
On-call packet: leave three commands: openclaw doctor, last two hundred Gateway log lines, and channel status; the next responder must not need private chats.
/srv/openclaw/
prod/
compose.yaml
env/
base.env
alice.env
bob.env
data/
staging/
compose.yaml
env/
base.env
alice.staging.env
data/
Tip: if you need a parallel second stack on one host, read multi-instance isolation for port tables and COMPOSE_PROJECT_NAME, then merge into this runbook.
Only statements you can point to in configuration, not vibes. For memory limits and json-file rotation, use Compose production baseline.
18789 as the default local control plane context; sign-off must list bind address, reverse proxy path, and whether the UI is internet reachable, not only the integer.Warning: do not rotate model keys, channel tokens, and TLS certificates in one ticket; triangular changes make rollback non-bisectable. For TLS paths read reverse proxy TLS guide.
Upgrade acceptance from a demo to checkboxed compliance language: default deny, explicit allow, rollback ready. If any row cannot be checked, stay on an internal profile.
| Check | Pass criteria | Typical failure signal |
|---|---|---|
| Key compartments | Per-member env_file, CI uses read-only injection | Shared .env in git history or pasted secrets |
| Exposure | Control plane not directly reachable from the public internet, or constrained via allowlists or mTLS | Scans find unauthenticated dashboards on 0.0.0.0 |
| Observability | 403 or timeouts map to origins, edge, or upstream within five minutes | Stacks without request identifiers |
Relying on one hero engineer’s mental map guarantees pain during turnover; treating runbooks and port tables as repository assets is how AI agents graduate from toys to infrastructure.
Common mistake: rotate model keys at the first 403; most incidents need an origins and egress matrix first.
Temporary shell hacks without written lists rarely survive audits; when OpenClaw must be described alongside fixed egress, hostnames, and private mesh topology, ad-hoc VPS stacks often lack signable change records. For iOS builds, desktop handoff, and always-on agents in an exclusive, region-predictable footprint where Gateway and Mac pools share one vocabulary, VpsMesh Mac Mini cloud rental is usually the better fit: dedicated nodes simplify binds and ACL narratives and align with private mesh runbook; pricing is on pricing page, connectivity on help center.
Publish a port and bind matrix, data directory ownership with COMPOSE_PROJECT_NAME, and a per-member env_file map. Update the table before running commands. For hardening items see production hardening checklist.
Dual-write window: add the new key in a separate env_file, validate channels on staging, switch production compose references, keep a rollback window, then run openclaw doctor and a minimal probe. Orders and egress needs: order page.
Align timestamps to separate edge auth from application allowedOrigins. If only one member fails, verify that member CLI origin or egress against the allowlist, then read Compose networking triage and help center.