OpenAI Chat Completions (HTTP)

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

Dieser Endpoint 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 wie ein normaler Gateway Agent-Lauf ausgeführt (gleicher Codepfad wie openclaw agent), sodass Routing, Berechtigungen und Konfiguration mit deinem Gateway übereinstimmen.

Authentifizierung

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

  • Authorization: Bearer <token>

Hinweise:

  • Bei gateway.auth.mode="token" verwendest du gateway.auth.token (oder OPENCLAW_GATEWAY_TOKEN).
  • Bei gateway.auth.mode="password" verwendest du gateway.auth.password (oder OPENCLAW_GATEWAY_PASSWORD).

Agent auswählen

Keine besonderen Header nötig: Kodiere die Agent-ID im OpenAI model-Feld:

  • 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.

Endpoint aktivieren

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

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

Endpoint deaktivieren

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

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

Session-Verhalten

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

Wenn die Anfrage einen OpenAI user-String enthält, leitet das Gateway daraus einen stabilen Session-Key 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"}]
  }'