2026-05-13 OpenClaw multi-agent agents.json role split on a headless leased Apple Silicon cloud Mac (HK / JP / KR / SG / US)

One gateway, one personality, one accidental rm -rf story—until you split OpenClaw into explicit multi-agent profiles. On leased Mac mini M4 hosts in Hong Kong, Tokyo, Seoul, Singapore, and the United States, the same UID often co-hosts xcodebuild lanes, signing trees, and an assistant that answers Slack. This 2026-05-13 playbook treats agents.json as an operational contract: who may touch which roots, which OPENCLAW_STATE_DIR owns checkpoints, and how inbound events map to a single agent identity. It chains workspace allowlists, session checkpoint discipline, and onboard plus doctor triage into a reproducible dev vs ops split that survives launchd restarts without merging durable state.

Why multi-agent configuration matters on shared lease builders

Assistants that can read repositories are not interchangeable with automations that restart daemons or rotate tokens. When both personas share one state directory, dedupe caches, plugin manifests, and partially written JSON collide under bursty webhooks—especially after npm upgrades or launchctl kickstart storms. Multi-agent design is therefore about blast radius: narrow tool surfaces per role, pin logs with distinct prefixes, and require human review when widening scopes. Treat agents.json like infrastructure code: peer review, checksum in deploy bundles, and region-by-region rollout so Tokyo canary failures do not poison Singapore traffic.

Anatomy of agents.json beside the gateway process model

Think in three layers: transport (HTTP, Slack, Telegram), gateway (routing, auth, rate limits), and agent runtime (tool execution, model calls, filesystem policy). agents.json belongs to the runtime layer—it declares named agents, default models, skill bundles, and per-agent policy knobs. Gateways read these declarations at startup; changing them without a controlled restart invites half-old policy in memory. Document which fields are hot-reloadable in your OpenClaw build and which require stop-start sequencing aligned with checkpoint guidance.

• Identity — stable id strings referenced by routers and metrics.
• Scope — workspace roots that must mirror allowlists from monorepo guardrails.
• Tooling — explicit allow/deny lists; ops personas may include service controllers while dev personas omit them.

Dev vs ops personas: what each profile should never inherit

The developer assistant should prioritize read-mostly repo navigation, diff-friendly edits, and test commands scoped to CI checkouts. The ops automation persona may invoke broader host introspection but must still avoid interactive prompts and unbounded shell. Keep secrets out of both profiles’ inline prompts—load from macOS keychain or sealed env files referenced in plist EnvironmentVariables. When teams blur the boundary “temporarily,” incidents follow: an assistant thread inherits ops tools and touches launchd plists while a human still thinks it is read-only exploration.

OPENCLAW_STATE_DIR isolation per agent on one physical Mac

Split state roots under predictable prefixes such as ~/Library/Application Support/OpenClaw/state-dev and .../state-ops, or per-tenant subdirectories if multiple product lines share a lease. Never symlink one state tree into another; APFS firmlinks and backup tools can flatten distinctions you thought were separate. Align scratch directories with per-agent TMPDIR exports so parallel jobs do not delete each other’s partial uploads. After directory moves, run the same verification steps documented for doctor triage to confirm gateways resolve the intended paths under non-interactive shells.

# example: export before exec in a launchd wrapper #!/bin/bash set -euo pipefail export OPENCLAW_STATE_DIR="$HOME/.openclaw-state/ops" exec /usr/local/bin/openclaw gateway --config "$HOME/.openclaw/ops-gateway.json"

Gateway routing: correlation keys, channels, and collision avoidance

Inbound webhooks should carry stable identifiers—repository full name plus delivery id, Slack team plus channel plus thread ts, or a signed internal job token. Map each identifier pattern to one agent id in router configuration; avoid regex fall-through that sends traffic to a default assistant when ops automation was intended. For dual gateways on one host, reuse upstream labeling ideas from dual-port articles but keep persona routing orthogonal to A/B traffic splits. Log routing decisions at info level during rollout, then downgrade once error budgets stabilize.

Decision matrix: one agent vs split agents vs split gateways

Signal	Prefer single agent	Prefer split agents.json	Prefer split gateway processes
Tool surface overlap	High overlap, same risk class	Low overlap, same gateway auth	Different auth domains or TLS certs
Release cadence	Weekly prompt tweaks only	Different teams own JSON files	Independent SLOs or maintenance windows
State dir contention	Rare writes, small caches	Heavy checkpoint or plugin IO	Hard isolation for compliance audits
Operational cost	Lowest moving parts	Moderate: more dirs plus routing tests	Highest: twice the launchd plus health probes

Eight-step rollout for multi-agent OpenClaw on leased Apple Silicon

1. Inventory every automation and human-triggered entrypoint hitting the gateway in the last 30 days.
2. Draft agents.json with dev and ops profiles; attach workspace roots per allowlist guidance.
3. Create sibling OPENCLAW_STATE_DIR trees with matching ownership and disk quotas.
4. Implement deterministic routing rules with unit tests for sample payloads.
5. Deploy plists or wrappers per persona; reload with launchctl kickstart in staging first.
6. Run synthetic jobs that must fail when routed to the wrong profile.
7. Capture before/after metrics for denied tool attempts and p95 gateway latency.
8. Document rollback: tarball state dirs plus prior JSON committed in Git tags.

SLO signals for multi-agent gateways

Signal	Threshold	Action
Routing ambiguity rate	> 0.1% of requests	Freeze routing changes; add explicit matchers
State dir cross-writes	Any detected outside declared roots	Stop gateway; restore from checkpoint snapshot
Drift between Git JSON and host files	Any undeployed manual edit	Rollback host; enforce PR-only workflow

FAQ

Question	Practical answer (2026-05-13)
Should dev and ops share one model allowlist?	Share the provider list if cost-managed together; split disallowed models if ops jobs require cheaper or offline-capable endpoints.
Can I hot-edit agents.json over SSH during an incident?	Only with a paired restart plan and a tagged Git commit; otherwise prefer feature flags in router config with shorter blast radius.

Why Mac mini M4 rentals simplify multi-agent OpenClaw

Fast NVMe and generous unified memory let you host multiple state trees, parallel model caches, and simultaneous gateway health checks without thrashing swap—useful when you rehearse routing changes while CI still compiles. Compare regional capacity on the pricing page and walk engineers through SSH and optional VNC guides before widening tool scopes.