API: Instanz-Aktionen (Start/Stop/Neustart)

Überblick

Steuere den Power-Status deiner Instanz über diese Endpunkte. Jede Aktion ändert den Instanz-Status und kann einige Sekunden dauern.

Prüfe die Felder can_start, can_stop und can_restart aus dem Instanz-Details Endpunkt, bevor du diese Aktionen aufrufst.

Instanz starten

POST /api/v1/instances/:id/start

Schaltet eine gestoppte Instanz ein. Die Instanz muss den Status stopped haben.

Beispiel:

curl -X POST https://clawhosters.com/api/v1/instances/42/start \
  -H "Authorization: Bearer oc_live_dein_api_schlüssel"

Erfolgsantwort (200 OK):

{
  "data": {
    "id": 42,
    "name": "my-ai-bot",
    "status": "running",
    "tier": "balanced",
    "can_start": false,
    "can_stop": true,
    "can_restart": true
  }
}

Instanz stoppen

POST /api/v1/instances/:id/stop

Schaltet eine laufende Instanz aus. Die Instanz muss den Status running haben. Die Daten bleiben auf der VPS erhalten.

Beispiel:

curl -X POST https://clawhosters.com/api/v1/instances/42/stop \
  -H "Authorization: Bearer oc_live_dein_api_schlüssel"

Erfolgsantwort (200 OK):

{
  "data": {
    "id": 42,
    "name": "my-ai-bot",
    "status": "stopped",
    "tier": "balanced",
    "can_start": true,
    "can_stop": false,
    "can_restart": false
  }
}

Instanz neu starten

POST /api/v1/instances/:id/restart

Startet eine laufende Instanz neu. Die Instanz muss den Status running haben. Es gibt eine kurze Ausfallzeit während des Neustarts.

Beispiel:

curl -X POST https://clawhosters.com/api/v1/instances/42/restart \
  -H "Authorization: Bearer oc_live_dein_api_schlüssel"

Erfolgsantwort (200 OK):

{
  "data": {
    "id": 42,
    "name": "my-ai-bot",
    "status": "running",
    "tier": "balanced",
    "can_start": false,
    "can_stop": true,
    "can_restart": true
  }
}

Authentifizierung

Alle Aktions-Endpunkte erfordern einen gültigen API-Schlüssel:

Authorization: Bearer oc_live_dein_api_schlüssel

Kein Request-Body wird für diese Endpunkte benötigt.

Fehlerantworten

Nicht verarbeitbar (422)

Wird zurückgegeben, wenn die Aktion für den aktuellen Instanz-Status nicht verfügbar ist. Zum Beispiel beim Versuch, eine running-Instanz zu starten.

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Instance cannot be started in its current state"
  }
}

Nicht gefunden (404)

Die Instanz existiert nicht oder gehört einem anderen Kunden.

{
  "error": {
    "code": "not_found",
    "message": "Instance not found"
  }
}

Nicht autorisiert (401)

Wird zurückgegeben, wenn der API-Schlüssel fehlt, ungültig oder widerrufen ist.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Aktionsverfügbarkeit nach Status

Hinweise

• Power-Aktionen werden von der Hetzner Cloud API verarbeitet und können einige Sekunden dauern. Die Antwort spiegelt den erwarteten Status nach der Aktion wider.
• Das Stoppen einer Instanz löscht keine Daten. Die VPS bleibt zugewiesen und kann jederzeit wieder gestartet werden.
• Der Neustart führt einen sauberen Reboot des Docker-Containers und des OpenClaw-Gateways durch.
• Die tägliche Abrechnung läuft bei gestoppten Instanzen weiter, da die VPS zugewiesen bleibt. Um die Abrechnung vollständig zu stoppen, lösche die Instanz oder lass sie automatisch pausieren, wenn dein Claws-Guthaben null erreicht.

Verwandte Dokumentation

• API-Übersicht — Authentifizierung, Rate-Limits und Antwortformat
• Instanz-Details abrufen — Aktionsverfügbarkeit vor dem Aufruf prüfen
• Instanz löschen — Instanz dauerhaft entfernen