openclaw start — Launch Agent Service

Synopsis

openclaw start [OPTIONS]

Unlike openclaw run which executes a single task and exits, openclaw start launches OpenClaw as a long-running process. This is how you power Telegram bots, Discord integrations, REST API consumers, or any service that needs to accept tasks continuously.

Options & Flags

Flag	Type	Default	Description
`--port`	int	8080	REST API server port
`--host`	string	127.0.0.1	Bind address (use 0.0.0.0 for all interfaces)
`--daemon`	flag	false	Run as a background daemon process
`--profile`	string	default	Configuration profile to load on start
`--log-level`	string	info	Log verbosity: debug, info, warn, error
`--workers`	int	4	Number of concurrent worker threads
`--integration`	string	none	Enable a specific integration: telegram, discord

Usage Modes

Mode 1: Interactive REPL

Start an interactive session where you type tasks and see results in real time:

openclaw start

OpenClaw v1.0.0 Interactive Mode
Provider: openai / Model: gpt-4o
Type a task, or 'exit' to quit.

> Summarize the files in ./reports
[Agent] Scanning ./reports...
[Agent] Found 3 files. Summarizing...
Done. Here is the summary: ...

> exit
Goodbye.

Mode 2: REST API Server

Start a local REST API that other applications can call:

openclaw start --host 127.0.0.1 --port 8080

OpenClaw REST API starting on http://127.0.0.1:8080
Workers: 4 | Provider: openai | Model: gpt-4o
Press Ctrl+C to stop.

Mode 3: Background Daemon

Start as a daemon that persists after your terminal closes:

openclaw start --daemon --port 8080
# Returns immediately, process runs in background
echo "OpenClaw daemon started. PID stored in ~/.openclaw/daemon.pid"

REST API Endpoints

Method	Endpoint	Description
`GET`	`/health`	Health check — returns server status and version
`POST`	`/run`	Execute a task (JSON body: task, options)
`GET`	`/status/{job_id}`	Get status of a running or completed job
`DELETE`	`/stop/{job_id}`	Abort a running job
`GET`	`/jobs`	List all recent jobs with status

Health Check

curl http://localhost:8080/health

{
  "status": "ok",
  "version": "1.0.0",
  "provider": "openai",
  "model": "gpt-4o",
  "workers": 4,
  "uptime_seconds": 342
}

Submitting a Task via API

curl -X POST http://localhost:8080/run \
  -H "Content-Type: application/json" \
  -d '{"task": "Summarize all Python files in /app/src", "format": "markdown"}'

{
  "job_id": "job_a1b2c3d4",
  "status": "running",
  "created_at": "2026-03-12T08:00:00Z"
}

Full Daemon + API Example

# Start daemon
openclaw start --daemon --port 8080

# Wait a moment, then check health
sleep 2 && curl http://localhost:8080/health

# Submit a task
curl -X POST http://localhost:8080/run \
  -H "Content-Type: application/json" \
  -d '{"task": "Check disk usage in /var/log and summarize large files"}'

# Stop daemon gracefully
openclaw stop

⚠️

Security Note

When binding to 0.0.0.0 for external access, always use a reverse proxy with TLS and authentication. Never expose the OpenClaw API directly to the internet without access controls.

💡

See Also

openclaw stop — gracefully stop the service
openclaw run — one-off task execution
Telegram Integration — bot powered by start

Flags Reference

Flag	Environment Variable	Default	Description
`--port`	`OPENCLAW_PORT`	`8080`	TCP port the API server listens on
`--host`	`OPENCLAW_HOST`	`127.0.0.1`	Bind address; use `0.0.0.0` to allow network access
`--daemon`	—	off	Run in background; PID written to `~/.openclaw/openclaw.pid`
`--profile <name>`	`OPENCLAW_PROFILE`	`default`	Use a named configuration profile
`--log-level`	`OPENCLAW_LOG_LEVEL`	`INFO`	Logging verbosity: DEBUG, INFO, WARNING, ERROR
`--config <path>`	`OPENCLAW_CONFIG`	`~/.openclaw/config.yaml`	Explicit config file path

Health Check Endpoint

When running in server mode, a GET /health endpoint is available for uptime monitoring and orchestration readiness checks:

curl http://localhost:8080/health

{
  "status": "ok",
  "version": "1.4.2",
  "uptime_seconds": 3820,
  "models_loaded": ["claude-3-5-sonnet", "gpt-4o"],
  "active_tasks": 0
}

The endpoint returns HTTP 200 when healthy and HTTP 503 when a critical error is detected.

Process Management

When --daemon is used, OpenClaw writes its PID to ~/.openclaw/openclaw.pid:

# Check if daemon is running
PID=$(cat ~/.openclaw/openclaw.pid 2>/dev/null)
if [ -n "$PID" ] && kill -0 "$PID" 2>/dev/null; then
    echo "Running with PID $PID"
else
    echo "Not running"
fi

# Send graceful reload signal
kill -HUP $(cat ~/.openclaw/openclaw.pid)

# Use openclaw stop to shut down cleanly:
openclaw stop

← openclaw run openclaw stop →