System API

{
  node: {
    version: string // process.version, e.g. "v22.3.0"
    major: number // parsed major version
    sufficient: boolean // major >= 22
    path: string // process.execPath
  }
  openclaw: {
    installed: boolean
    version: string | null // null when the version probe timed out / failed
    path: string | null // resolved binary path, or null when not installed
    stateDir: string // resolved OpenClaw state dir (~/.openclaw)
    configExists: boolean // openclaw.json present
    envExists: boolean // .env present
  }
  gateway: {
    running: boolean // PID alive OR port reachable
    port: number // PID-file port → openclaw.json gateway.port → 18789
    pid: number | null // null unless a Clawboo-managed PID is alive
    managedByClawboo: boolean // a live PID file written by this server
    uptimeMs: number | null // since the managed start, else null
  }
}

{ "error": "<message>" }

curl http://localhost:18790/api/system/status

data: {"type":"progress","step":"installing","message":"Installing OpenClaw..."}

data: {"type":"output","line":"added 1 package in 4s"}

data: {"type":"complete","success":true,"version":"2026.5.27"}

curl -N -X POST http://localhost:18790/api/system/install-openclaw

{
  provider: string       // required (e.g. 'anthropic', 'openai', 'ollama', ...)
  apiKey?: string        // required for every provider except 'ollama'
  model?: string         // optional model override; else a per-provider default
  gatewayPort?: number   // optional; default 18789
}

{ "error": "JSON body required" }

{ "error": "provider is required" }

{ "error": "apiKey is required for non-ollama providers" }

{ ok: true, gatewayUrl: string }   // gatewayUrl is `ws://localhost:<port>`

{ "error": "<message>" }

curl -X POST http://localhost:18790/api/system/configure-openclaw \
  -H 'Content-Type: application/json' \
  -d '{"provider":"anthropic","apiKey":"sk-ant-...","gatewayPort":18789}'

{ ok: true, gatewayUrl: string, provider: string }   // gatewayUrl is `ws://localhost:18789`

{ ok: false, needsCodexAuth: true, loginCommand: string }
// or
{ ok: false, needsKey: true }

{ "error": "<message>" }

curl -X POST http://localhost:18790/api/system/auto-configure-openclaw

{
  action: 'start' | 'stop' | 'restart' | 'status'
}

{ "error": "JSON body required" }

{ "error": "action must be 'start', 'stop', 'restart', or 'status'" }

{
  running: boolean // PID alive OR port reachable
  pid: number | null // null unless a managed PID is alive
  port: number
  uptimeMs: number | null
}

{ ok: true, stopped: true }
// or, when no gateway process was found:
{ ok: false, message: 'No gateway process found' }

data: {"type":"progress","step":"starting","message":"Starting gateway on port 18789..."}

data: {"type":"progress","step":"waiting","message":"Waiting for gateway... (3/120)"}

data: {"type":"complete","success":true,"pid":48211,"port":18789}

# Stop (JSON)
curl -X POST http://localhost:18790/api/system/gateway \
  -H 'Content-Type: application/json' \
  -d '{"action":"stop"}'

# Start (SSE)
curl -N -X POST http://localhost:18790/api/system/gateway \
  -H 'Content-Type: application/json' \
  -d '{"action":"start"}'

{
  config: Record<string, unknown> | null // parsed openclaw.json, or null if missing/corrupt
  env: {
    hasAnthropicKey: boolean
    hasOpenAIKey: boolean
    hasGoogleKey: boolean
    hasOpenRouterKey: boolean
    hasXaiKey: boolean
    hasGroqKey: boolean
    hasMistralKey: boolean
    hasMoonshotKey: boolean
    hasMiniMaxKey: boolean
    hasTogetherKey: boolean
    hasNvidiaKey: boolean
    hasHuggingFaceKey: boolean
    hasCerebrasKey: boolean
    hasVeniceKey: boolean
    hasGatewayToken: boolean
  }
  version: string | null // OpenClaw version (null if probe failed)
  execAsk: unknown | null // tools.exec.ask from openclaw.json
  execSecurity: unknown | null // tools.exec.security
}

{ "error": "<message>" }

curl http://localhost:18790/api/system/openclaw-config

{
  model?: string        // → agents.defaults.model.primary
  fallbacks?: string[]  // → agents.defaults.model.fallbacks (non-strings filtered out)
  gatewayPort?: number  // → gateway.port (and Clawboo settings gatewayUrl)
  apiKeys?: Array<{ provider: string; key: string }>  // → .env + auth-profiles.json
  agentModel?: { agentId: string; model: string | null }  // per-agent override in agents.list[]
  exec?: { ask?: string; security?: string }  // → tools.exec.*
  agentToAgent?: { enabled: boolean }  // → tools.agentToAgent.enabled (and sessions.visibility on enable)
}

{ "error": "JSON body required" }

{ ok: true }
// or, when the gateway is running:
{ ok: true, hotReloadHint: true }

{ "error": "<message>" }

curl -X PATCH http://localhost:18790/api/system/openclaw-config \
  -H 'Content-Type: application/json' \
  -d '{"model":"anthropic/claude-sonnet-4-5","agentToAgent":{"enabled":true}}'

{ "error": "OpenClaw not installed" }

{ "error": "Failed to run openclaw: <message>" }

{ "error": "No pending device pairing requests found", "details": "<truncated output>" }

{ ok: true, requestId: string, output: string }

{ "error": "Failed to approve device: <message>", "requestId": "<uuid>" }

curl -X POST http://localhost:18790/api/system/approve-device

{
  groups: Array<{
    provider: string
    models: Array<{ id: string; label: string }>
  }> | null
  configuredProviders: string[]   // provider ids with a key (always includes 'ollama')
}

curl http://localhost:18790/api/system/models

# Full payload, including the registry check
curl http://localhost:18790/api/system/self-version

# Just this server's identity, no outbound network call
curl 'http://localhost:18790/api/system/self-version?local=1'

curl -N -X POST http://localhost:18790/api/system/self-update