The OpenClaw Host Capacity Playbook

The first time my host ran out of processes, nothing crashed. Every shell command I tried to run came back with spawn /bin/zsh EAGAIN, sub-agents refused to start, and the jobs that depended on them reported that there was simply nothing to do today. The logs looked calm. The machine was full.

That failure repeated five times over three months before I started treating it as a capacity problem. This page is what I do now. It is written for a single always-on box (a Mac mini in my case, though the Linux notes are here too) running a gateway, a handful of agents, and whatever those agents decide to spawn.

Why Agent Hosts Fill Up

A normal server runs a fixed set of services. An agent host runs a fixed set of services plus a population of short-lived children that the agents create on their own: shells for tool calls, browser instances, MCP servers, sub-agents, the sub-agents' shells. Each one is supposed to exit when its work is done. Some do not.

The ones that stay behind are usually a dev server an agent started to test something and never stopped, or a child whose parent died before it could be cleaned up, so it got reparented to PID 1 and kept running with no listening port and no purpose. Zombies are the other kind. They cost almost nothing individually, but they point at a parent process with a reaping bug, and that bug will keep producing them.

Meanwhile the operating system has a hard ceiling on processes per user. On macOS you can see it with sysctl kern.maxprocperuid. On Linux, ulimit -u shows the per-user cap, and if the agents run under systemd, the unit's TasksMax may bite well before that. Cross the line and every new fork() fails.

Measure the Idle Baseline First

You cannot set a threshold on a number you have never looked at. Pick a quiet moment, when no scheduled jobs are running and no agent is mid-task, and count:

# processes owned by the agent user
ps -U "$(id -u)" -o pid= | wc -l

# everything on the box
ps -A -o pid= | wc -l

# the ceiling you are working against (macOS)
sysctl kern.maxproc kern.maxprocperuid

Write both counts down with the date. Do it again on a different day, at a different hour, because one sample tells you very little. My idle numbers came out around 430 processes for the agent user and about 670 total, and I was surprised how much of that was ordinary desktop software: a browser, a couple of chat apps, a sync client.

That surprise matters, and it took me a while to learn why. The first alert threshold I wrote was on the total process count. It fired constantly. The total was dominated by apps the operator had open for their actual job, none of which the agents controlled, and the alert kept blocking agent work on days when the agent population itself was perfectly healthy. The per-user count for the account the agents run under is the number that tracks what your agents are doing. Every one of my real incidents showed up there first, at roughly 30% above the idle baseline.

Record the Count When Things Die

When a background service gets killed with SIGTERM or a spawn fails with EAGAIN, capture the process count at that moment. A tiny wrapper around your gateway's launch script is enough: trap the signal, append a line with a timestamp, the per-user count, and the total, then exit. Without that line you end up guessing afterwards, and the guesses are always optimistic.

Five incidents with counts attached will tell you where your real ceiling sits. Five without them tell you nothing.

Finding Orphans Without Killing the Wrong Thing

Start by listing processes owned by the agent user whose parent is PID 1, sorted by how long they have been alive:

ps -U "$(id -u)" -o pid,ppid,etime,command | awk '$2 == 1'

Most of what comes back is legitimate. Launchd and systemd services are children of PID 1 by design, and so is your gateway if it runs as a daemon. What you are looking for is the stranger: a node server.js that has been up for nine hours, a bun process from six days ago. For each suspect, check whether it is listening on anything:

lsof -nP -a -p <pid> -iTCP -sTCP:LISTEN

An old dev server with no listening port and no parent is almost certainly abandoned. Almost. Before killing it, find out who started it. Check its working directory with lsof -a -p <pid> -d cwd, and search your agents' recent logs for the command line. If you kill something without knowing its source, the same agent will start another one tomorrow and you will be back here.

Zombies show up with a Z in the state column:

ps -A -o stat,pid,ppid,command | awk '$1 ~ /^Z/'

You cannot kill a zombie. It is already dead. Look at the PPID column instead, and note which parent keeps accumulating them. That parent has a bug in how it waits on its children, and the fix belongs in its code. Restarting the parent clears the current batch and buys time, nothing more.

Put a Gate in Front of Spawning

Cleanup is reactive. The durable fix is a check that runs before any agent is allowed to start a sub-agent or a heavy tool, and says no when the host is close to full. Mine is a few lines of shell that every spawn path calls first:

#!/bin/sh
# spawn-gate: exit non-zero if the agent user is over budget
LIMIT=550
COUNT=$(ps -U "$(id -u)" -o pid= | wc -l | tr -d ' ')
if [ "$COUNT" -gt "$LIMIT" ]; then
  echo "spawn-gate: $COUNT processes (limit $LIMIT), refusing" >&2
  exit 1
fi

The limit came from the measurements above. Idle sat around 430, incidents started around 500 to 570, so 550 leaves normal bursts alone and stops a runaway fan-out before it reaches the ceiling. Your number will be different. Use your own baseline, and leave enough headroom between the gate and the kernel limit that a human can still open a terminal when the gate trips.

The gate has to fail loudly. An agent that hits it should report “could not start, host over capacity” to wherever you read status, since the original failure mode was an agent treating an empty result as a quiet day. That pattern is covered in more depth in detecting silent failures, and it applies here exactly.

One rule you will be tempted to break: do not let the gate kill things to make room. A gate that starts terminating processes on its own is a second, less predictable agent, and it will eventually pick the gateway.

Limit Fan-Out Where It Starts

Most process spikes trace back to one pattern: an orchestrating agent splits a task into many parallel pieces, each piece spawns its own tools, and a few of those spawn more. The patterns in parallel task execution are genuinely useful, and they need a ceiling. Cap concurrent sub-agents per job at a small number and let the rest queue. Four parallel workers that finish are faster than twenty that trip the gate halfway through.

Schedules matter too. If three heavy cron jobs all start at 6:00, stagger them by ten minutes. It costs nothing.

A Weekly Capacity Check

Once a week, at the same quiet hour, I take the same two counts and compare them against the baseline. A slow upward drift with no new services means something is leaking. Then I run the orphan listing and the zombie listing, and I close any desktop app on the host that nobody is using, which on one occasion freed fourteen processes in a single click.

Ten minutes.

If the drift is real and you cannot find the source, restart the gateway during an idle window with openclaw gateway stop and openclaw gateway start --daemon, then count again. If the number drops sharply, the leak lives inside something the gateway supervises, and that narrows the search to your skills and their child processes.

Related Reading

• OpenClaw Agent Observability: Detecting Silent Failures
• The OpenClaw Agent Incident Response Playbook
• OpenClaw Parallel Task Execution
• OpenClaw Mac Mini M2 Advanced Optimization Guide

Frequently Asked Questions

What does spawn EAGAIN mean on an OpenClaw host?

It means the operating system refused to create a new process, almost always because the user account running your agents has reached its process limit. The fix is to find what is holding those process slots (usually orphaned dev servers, stuck browser instances, or a burst of sub-agents) and then add a spawn gate so it does not happen again.

Should I just raise the process limit?

Raising kern.maxprocperuid or ulimit -u can buy headroom on a host that is legitimately busy, but it does not fix a leak. A leaking host with a higher limit takes longer to fill and then fails the same way. Measure your baseline and find the leak first, then raise the limit only if your healthy peak really needs it.

Which number should my alert watch, total processes or per-user processes?

The per-user count for the account your agents run under. Total process count includes desktop apps and system services that your agents do not control, so an alert on it will fire on normal working days and train you to ignore it.

How much headroom should a spawn gate leave?

Enough that normal bursts pass and a person can still log in and run commands when the gate trips. On my host that meant a gate about 120 processes above the idle baseline and well below the kernel limit. Derive yours from at least a week of measured idle and peak counts.