openclaw stop — Stop Agent Service

Synopsis

openclaw stop [OPTIONS] [JOB_ID]

When called without arguments, openclaw stop gracefully shuts down the running OpenClaw service started with openclaw start. Optionally provide a JOB_ID to stop only a specific job while leaving the service running.

Options & Flags

Flag	Type	Default	Description
`--force`	flag	false	Immediately kill the process without waiting for graceful shutdown
`--timeout`	int	30	Seconds to wait for graceful shutdown before forcing
`--all`	flag	false	Stop all running jobs without stopping the service

Graceful vs Force Shutdown

OpenClaw distinguishes between two types of shutdown:

Graceful Shutdown (default)

Sends a SIGTERM signal to the running process. OpenClaw will:

Stop accepting new tasks
Wait for in-progress jobs to save their partial results
Flush logs to disk
Release file handles and connections
Exit cleanly

openclaw stop
# Graceful shutdown initiated. Waiting up to 30s...

Force Kill

Use --force to immediately terminate. Running tasks will be aborted without saving partial results:

openclaw stop --force
# Process killed immediately (SIGKILL)

⚠️

Data Safety

Force killing with --force may leave temporary files or incomplete outputs. Always prefer graceful shutdown unless the process is unresponsive.

Stopping Specific Jobs

When the service is running, you can stop individual jobs without shutting down the whole service:

# List running jobs
openclaw status

# Output:
# JOB_ID          STATUS    STARTED     TASK
# job_a1b2c3d4    running   08:00:05    Analyze codebase...
# job_e5f6g7h8    running   08:01:22    Generate report...

# Stop one specific job
openclaw stop job_a1b2c3d4

# Stop all jobs but keep service alive
openclaw stop --all

📝

Job IDs

Job IDs are returned when submitting tasks via the REST API or displayed in verbose mode. You can also retrieve them with openclaw status.

Shutdown Timeout

By default, graceful shutdown waits 30 seconds for running jobs to complete. Customize this:

# Wait up to 60 seconds for graceful shutdown
openclaw stop --timeout 60

# Give only 5 seconds before forcing
openclaw stop --timeout 5

If the timeout expires and the process is still running, OpenClaw automatically escalates to a force kill.

💡

See Also

openclaw start — launch the service
openclaw run — one-off task execution
Common Errors — if stop is unresponsive

Signal Reference

OpenClaw handles OS signals for graceful shutdown:

Signal	Equivalent Command	Behavior
`SIGINT` (Ctrl+C)	`openclaw stop`	Graceful: finish current step, save state, exit cleanly
`SIGTERM`	`openclaw stop --graceful`	Graceful: same as SIGINT, used by systemd and Docker stop
`SIGKILL` (kill -9)	`openclaw stop --force`	Immediate: no cleanup, in-progress work may be lost
`SIGUSR1`	n/a	Pause execution (continue with `openclaw run --resume`)

Stop via Process Management

# Find and stop OpenClaw processes by PID
OPENCLAW_PID=$(pgrep -f "openclaw")
echo "OpenClaw PID: $OPENCLAW_PID"

# Graceful stop
kill -SIGTERM $OPENCLAW_PID

# Force stop (if graceful fails)
kill -9 $OPENCLAW_PID

Stop in Systemd

# systemd handles SIGTERM automatically on service stop
sudo systemctl stop openclaw

# Check if stopped successfully
sudo systemctl status openclaw
# Loaded: loaded (/etc/systemd/system/openclaw.service)
# Active: inactive (dead)

Process Management Scripts

Stop with Cleanup Check

#!/usr/bin/env bash
# stop-and-verify.sh
openclaw stop --graceful

# Wait for clean exit
for i in $(seq 1 10); do
  if ! pgrep -f "openclaw" > /dev/null; then
    echo "OpenClaw stopped cleanly after ${i}s"
    exit 0
  fi
  sleep 1
done
echo "Graceful stop timeout — forcing" && openclaw stop --force

Exit Codes

Exit Code	Meaning
`0`	Process stopped successfully
`1`	No running OpenClaw process found
`2`	Graceful timeout — use `--force`

Verifying a Clean Stop

After running openclaw stop, confirm no orphaned processes remain:

# Linux/macOS: check for lingering processes
pgrep -af openclaw || echo "No openclaw processes running"

# Confirm PID file is removed
ls ~/.openclaw/openclaw.pid 2>/dev/null && echo "WARNING: PID file still exists" || echo "PID file cleaned up"

# Windows PowerShell
Get-Process -Name "openclaw" -ErrorAction SilentlyContinue | Out-Null
if ($?) { Write-Warning "Process still running" } else { Write-Host "Clean stop confirmed" }

If openclaw stop doesn't work (e.g. the process is frozen), follow the force-kill procedure in the Graceful vs Force Stop section above. For daemon mode specifics, see openclaw start — Process Management.

← openclaw start openclaw config →