Mac Multi User Agents

Use this skill when one Mac should support multiple dedicated OpenClaw agent users.

This skill is for the pattern you described on the MacBook Pro:

• one strong Mac
• several agent users
• Fast User Switching
• one shared /opt/homebrew toolchain
• separate ~/.openclaw, SSH, browser, and session state per user

It does not try to hide the fact that macOS user management still requires admin access.

Use This Skill For

• preparing a MacBook Pro to host 2-4 dedicated agent users
• estimating a sane number of agent users from the Mac's CPU and RAM
• keeping one shared Homebrew toolchain while isolating per-user OpenClaw state
• rendering or executing repeatable user-create commands instead of clicking around in System Settings
• checking whether a user has the required shell/tool paths
• documenting and auditing per-user rollout

Do Not Use This Skill For

• creating production macOS MDM policy
• bypassing sudo or admin approval for user creation
• pretending multiple agents should share one login
• turning the Mac into a shared human workstation and agent host without boundaries

Requirements

• admin access on the Mac
• Homebrew installed at /opt/homebrew
• OpenClaw installed in the shared toolchain
• enough RAM, storage, and browser capacity for the planned agent count

Design Rules

• one macOS user per agent
• one ~/.openclaw per agent
• one ~/.ssh per agent
• one browser profile set per agent
• shared /opt/homebrew only for binaries and formulae
• no shared session files between agents

Workflow

1. Inspect The Host

Run:

scripts/detect-host.sh
scripts/recommend-layout.sh

This reports:

• current user list
• whether Homebrew/OpenClaw are on the shared path
• current Fast User Switching state
• current hostname and shell layout
• a recommended range for additional agent users based on CPU/RAM

2. Render Or Execute User Creation

Do not improvise account creation from memory.

Render the commands first:

scripts/render-user-create.sh --user agent3 --full-name "Agent 3"
scripts/render-user-create.sh --user agent4 --full-name "Agent 4" --admin no

This prints a repeatable sysadminctl-based flow and the baseline directories to create afterward.

If you want the skill to actually create the user, use:

export AGENT_PASSWORD='set-a-real-password'
scripts/create-user.sh --user agent3 --full-name "Agent 3" --password-env AGENT_PASSWORD

Or dry-run first:

scripts/create-user.sh --user agent3 --full-name "Agent 3" --password-env AGENT_PASSWORD --dry-run

This keeps the process auditable and avoids hand-built user creation every time.

3. Keep The Toolchain Shared

Recommended shared toolchain:

• /opt/homebrew/bin/brew
• /opt/homebrew/bin/node
• /opt/homebrew/bin/npm
• /opt/homebrew/bin/openclaw

Read references/shared-homebrew.md before changing ownership or permissions under /opt/homebrew.

4. Bootstrap Per-User State

For each agent user, create or verify:

• ~/.ssh
• ~/.openclaw
• shell PATH that includes /opt/homebrew/bin
• authorized keys if cross-host or gateway SSH is required

Use:

scripts/verify-user-shell.sh --user agent3

to check the resulting shell/tool state.

5. Enable Fast User Switching

Read references/fast-user-switching.md.

The purpose is:

• easy hop between agent users
• no need to log out the whole Mac
• clear separation of browser/session state

6. Leave Receipts

Use:

scripts/write-receipt.sh --action "create-user" --status ok --detail "Prepared agent3 on MacBook Pro"
scripts/write-receipt.sh --action "verify-user-shell" --status ok --detail "agent3 sees brew node openclaw"

Security Rules

• do not give every agent user admin unless there is a real reason
• keep /opt/homebrew shared, but keep ~/.openclaw private per user
• do not share browser profiles between agent users
• keep SSH keys per user, not one copied private key everywhere
• if one user is removed, cleanup should not break the other users

Rollback

A single agent user should be removable without reinstalling the Mac.

Baseline rollback:

• remove that user
• remove that user’s ~/.openclaw
• remove that user’s SSH keys and browser state
• keep shared Homebrew intact

Files

• scripts/detect-host.sh: inspect the Mac and shared toolchain state
• scripts/recommend-layout.sh: suggest a sane agent-user count from hardware
• scripts/render-user-create.sh: print repeatable user-creation commands
• scripts/create-user.sh: actually create and bootstrap an agent user with sysadminctl
• scripts/verify-user-shell.sh: verify a target user sees the expected toolchain
• scripts/write-receipt.sh: append JSONL receipts for rollout work
• references/fast-user-switching.md: practical guidance for multi-user Mac agent hosts
• references/shared-homebrew.md: rules for one shared Homebrew toolchain across agent users