OpenAI Chat Completions (HTTP)

Das OpenClaw-Gateway kann einen kleinen OpenAI-kompatiblen Chat-Completions-Endpunkt bereitstellen.

Dieser Endpunkt ist standardmäßig deaktiviert. Aktiviere ihn zuerst in der Konfiguration.

POST /v1/chat/completions
Gleicher Port wie das Gateway (WS + HTTP Multiplex): http://<gateway-host>:<port>/v1/chat/completions

Intern werden Anfragen als normaler Gateway-Agent-Run ausgeführt (gleicher Codepfad wie openclaw agent), sodass Routing/Berechtigungen/Konfiguration dem Gateway entsprechen.

Authentifizierung

Verwendet die Gateway-Auth-Konfiguration. Sende ein Bearer-Token:

Authorization: Bearer <token>

Hinweise:

Bei gateway.auth.mode="token" verwende gateway.auth.token (oder OPENCLAW_GATEWAY_TOKEN).
Bei gateway.auth.mode="password" verwende gateway.auth.password (oder OPENCLAW_GATEWAY_PASSWORD).
Wenn gateway.auth.rateLimit konfiguriert ist und zu viele Auth-Fehler auftreten, gibt der Endpunkt 429 mit Retry-After zurück.

Sicherheitsgrenze (wichtig)

Behandle diesen Endpunkt als Vollzugriff auf Operator-Ebene für die Gateway-Instanz.

Die HTTP-Bearer-Authentifizierung ist hier kein feingranulares Per-User-Scope-Modell.
Ein gültiges Gateway-Token/Passwort für diesen Endpunkt sollte wie ein Owner/Operator-Credential behandelt werden.
Anfragen durchlaufen denselben Control-Plane-Agent-Pfad wie vertrauenswürdige Operator-Aktionen.
Es gibt auf diesem Endpunkt keine separate Nicht-Owner/Per-User-Tool-Grenze; sobald ein Aufrufer die Gateway-Authentifizierung besteht, behandelt OpenClaw ihn als vertrauenswürdigen Operator für dieses Gateway.
Wenn die Ziel-Agent-Policy sensitive Tools erlaubt, kann dieser Endpunkt sie nutzen.
Halte diesen Endpunkt auf Loopback/Tailnet/privatem Ingress; stelle ihn nicht direkt ins öffentliche Internet.

Siehe Sicherheit und Remote-Zugriff.

Einen Agent auswählen

Keine besonderen Header erforderlich: Codiere die Agent-ID im OpenAI-Feld model:

model: "openclaw:<agentId>" (Beispiel: "openclaw:main", "openclaw:beta")
model: "agent:<agentId>" (Alias)

Oder wähle einen bestimmten OpenClaw-Agent per Header:

x-openclaw-agent-id: <agentId> (Standard: main)

Erweitert:

x-openclaw-session-key: <sessionKey> für volle Kontrolle über das Session-Routing.

Endpunkt aktivieren

Setze gateway.http.endpoints.chatCompletions.enabled auf true:

{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: { enabled: true },
      },
    },
  },
}

Endpunkt deaktivieren

Setze gateway.http.endpoints.chatCompletions.enabled auf false:

{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: { enabled: false },
      },
    },
  },
}

Session-Verhalten

Standardmäßig ist der Endpunkt zustandslos pro Anfrage (bei jedem Aufruf wird ein neuer Session-Key generiert).

Wenn die Anfrage einen OpenAI-user-String enthält, leitet das Gateway einen stabilen Session-Key daraus ab, sodass wiederholte Aufrufe eine Agent-Session teilen können.

Streaming (SSE)

Setze stream: true, um Server-Sent Events (SSE) zu empfangen:

Content-Type: text/event-stream
Jede Event-Zeile ist data: <json>
Der Stream endet mit data: [DONE]

Beispiele

Ohne Streaming:

curl -sS http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "messages": [{"role":"user","content":"hi"}]
  }'

Mit Streaming:

curl -N http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "stream": true,
    "messages": [{"role":"user","content":"hi"}]
  }'