OpenAI-Chat-Vervollständigungen

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/responses

​

Authentifizierung

• Shared-Secret-Authentifizierung (gateway.auth.mode="token" oder "password"): Authorization: Bearer <token-or-password>
• vertrauenswürdige identitätstragende HTTP-Authentifizierung (gateway.auth.mode="trusted-proxy"): Leiten Sie über den konfigurierten identitätsbewussten Proxy weiter und lassen Sie ihn die erforderlichen Identitäts-Header einfügen
• offene Authentifizierung für privaten Ingress (gateway.auth.mode="none"): kein Authentifizierungs-Header erforderlich

• Wenn gateway.auth.mode="token" ist, verwenden Sie gateway.auth.token (oder OPENCLAW_GATEWAY_TOKEN).
• Wenn gateway.auth.mode="password" ist, verwenden Sie gateway.auth.password (oder OPENCLAW_GATEWAY_PASSWORD).
• Wenn gateway.auth.mode="trusted-proxy" ist, muss die HTTP-Anfrage von einer konfigurierten vertrauenswürdigen Proxy-Quelle kommen; local loopback-Proxys auf demselben Host erfordern explizit gateway.auth.trustedProxy.allowLoopback = true.
• Wenn gateway.auth.rateLimit konfiguriert ist und zu viele Authentifizierungsfehler auftreten, gibt der Endpunkt 429 mit Retry-After zurück.

​

Sicherheitsgrenze (wichtig)

• HTTP-Bearer-Authentifizierung ist hier kein enges Scope-Modell pro Benutzer.
• Ein gültiges Gateway-Token/Passwort für diesen Endpunkt sollte wie Owner-/Operator-Anmeldedaten behandelt werden.
• Anfragen laufen über denselben Control-Plane-Agentenpfad wie vertrauenswürdige Operator-Aktionen.
• Für diesen Endpunkt gibt es keine separate Nicht-Owner-/Pro-Benutzer-Tool-Grenze; sobald ein Aufrufer hier die Gateway-Authentifizierung besteht, behandelt OpenClaw diesen Aufrufer als vertrauenswürdigen Operator für dieses Gateway.
• Für Shared-Secret-Authentifizierungsmodi (token und password) stellt der Endpunkt die normalen vollständigen Operator-Standardwerte wieder her, selbst wenn der Aufrufer einen engeren x-openclaw-scopes-Header sendet.
• Vertrauenswürdige identitätstragende HTTP-Modi (zum Beispiel vertrauenswürdige Proxy-Authentifizierung oder gateway.auth.mode="none") berücksichtigen x-openclaw-scopes, wenn vorhanden, und fallen andernfalls auf die normale Standard-Scope-Menge für Operatoren zurück.
• Wenn die Richtlinie des Ziel-Agenten sensible Tools erlaubt, kann dieser Endpunkt sie verwenden.
• Halten Sie diesen Endpunkt ausschließlich auf Loopback/Tailnet/privatem Ingress; setzen Sie ihn nicht direkt dem öffentlichen Internet aus.

• gateway.auth.mode="token" oder "password" + Authorization: Bearer ...
  • weist den Besitz des gemeinsamen Gateway-Operator-Secrets nach
  • ignoriert engere x-openclaw-scopes
  • stellt die vollständige Standard-Scope-Menge für Operatoren wieder her: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • behandelt Chat-Turns auf diesem Endpunkt als Owner-Sender-Turns
• vertrauenswürdige identitätstragende HTTP-Modi (zum Beispiel vertrauenswürdige Proxy-Authentifizierung oder gateway.auth.mode="none" auf privatem Ingress)
  • authentifizieren eine äußere vertrauenswürdige Identität oder Deployment-Grenze
  • berücksichtigen x-openclaw-scopes, wenn der Header vorhanden ist
  • fallen auf die normale Standard-Scope-Menge für Operatoren zurück, wenn der Header fehlt
  • verlieren Owner-Semantik nur, wenn der Aufrufer Scopes explizit einschränkt und operator.admin auslässt

​

Agent-First-Modellvertrag

• model: "openclaw" leitet an den konfigurierten Standard-Agenten weiter.
• model: "openclaw/default" leitet ebenfalls an den konfigurierten Standard-Agenten weiter.
• model: "openclaw/<agentId>" leitet an einen bestimmten Agenten weiter.

• x-openclaw-model: <provider/model-or-bare-id> überschreibt das Backend-Modell für den ausgewählten Agenten.
• x-openclaw-agent-id: <agentId> bleibt als Kompatibilitätsüberschreibung unterstützt.
• x-openclaw-session-key: <sessionKey> steuert das Sitzungsrouting vollständig.
• x-openclaw-message-channel: <channel> legt den synthetischen Ingress-Channel-Kontext für Channel-bewusste Prompts und Richtlinien fest.

• model: "openclaw:<agentId>"
• model: "agent:<agentId>"

​

Aktivieren des Endpunkts

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

​

Deaktivieren des Endpunkts

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

​

Sitzungsverhalten

​

Warum diese Oberfläche wichtig ist

• Die meisten Setups von Open WebUI, LobeChat und LibreChat erwarten /v1/models.
• Viele RAG-Systeme erwarten /v1/embeddings.
• Bestehende OpenAI-Chat-Clients können in der Regel mit /v1/chat/completions starten.
• Stärker agentennative Clients bevorzugen zunehmend /v1/responses.

​

Modellliste und Agentenrouting

​

Streaming (SSE)

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

​

Chat-Tool-Vertrag

​

Unterstützte Anfragefelder

• tools: Array von { "type": "function", "function": { ... } }
• tool_choice: "auto", "none"
• messages[*].role: "tool"-Folge-Turns
• messages[*].tool_call_id zum Binden von Tool-Ergebnissen an einen vorherigen Tool-Aufruf
• max_completion_tokens: Zahl; Obergrenze pro Aufruf für die gesamten Completion-Tokens (Reasoning-Tokens eingeschlossen). Aktueller OpenAI-Chat-Completions-Feldname; bevorzugt, wenn sowohl max_completion_tokens als auch max_tokens gesendet werden.
• max_tokens: Zahl; Legacy-Alias, der aus Gründen der Abwärtskompatibilität akzeptiert wird. Wird ignoriert, wenn max_completion_tokens ebenfalls vorhanden ist.

​

Nicht unterstützte Varianten

• Nicht-Array-tools
• Nicht-Function-Tool-Einträge
• fehlendes tool.function.name
• tool_choice-Varianten wie allowed_tools und custom
• tool_choice: "required" (zur Laufzeit noch nicht erzwungen; wird unterstützt, sobald harte Erzwingung implementiert ist)
• tool_choice: { "type": "function", "function": { "name": "..." } } (gleiche Begründung wie bei required)
• tool_choice.function.name-Werte, die nicht zu den bereitgestellten tools passen

​

Antwortform bei nicht streamenden Tools

• choices[0].finish_reason = "tool_calls"
• choices[0].message.tool_calls[]-Einträge mit:
  • id
  • type: "function"
  • function.name
  • function.arguments (JSON-Zeichenfolge)

​

Antwortform bei streamenden Tools

• initiales Assistant-Rollen-Delta
• optionale Assistant-Kommentar-Deltas
• ein oder mehrere delta.tool_calls-Chunks mit Tool-Identität und Argumentfragmenten
• finaler Chunk mit finish_reason: "tool_calls"
• data: [DONE]

​

Tool-Follow-up-Schleife

• vorherige Assistant-Tool-Call-Nachricht
• eine oder mehrere role: "tool"-Nachrichten mit passender tool_call_id

​

Open WebUI-Schnelleinrichtung

• Basis-URL: http://127.0.0.1:18789/v1
• Docker-auf-macOS-Basis-URL: http://host.docker.internal:18789/v1
• API-Schlüssel: Ihr Gateway-Bearer-Token
• Modell: openclaw/default

• GET /v1/models sollte openclaw/default auflisten
• Open WebUI sollte openclaw/default als Chat-Modell-ID verwenden
• Wenn Sie einen bestimmten Backend-Provider/ein bestimmtes Backend-Modell für diesen Agenten wünschen, setzen Sie das normale Standardmodell des Agenten oder senden Sie x-openclaw-model

curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'

​

Beispiele

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

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

curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'

curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \
  -H 'Authorization: Bearer YOUR_TOKEN'

curl -sS http://127.0.0.1:18789/v1/embeddings \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-model: openai/text-embedding-3-small' \
  -d '{
    "model": "openclaw/default",
    "input": ["alpha", "beta"]
  }'

• /v1/models gibt OpenClaw-Agent-Ziele zurück, nicht rohe Provider-Kataloge.
• openclaw/default ist immer vorhanden, sodass eine stabile ID über Umgebungen hinweg funktioniert.
• Backend-Provider-/Modellüberschreibungen gehören in x-openclaw-model, nicht in das OpenAI-Feld model.
• /v1/embeddings unterstützt input als Zeichenfolge oder als Array von Zeichenfolgen.

​

Verwandt

• Konfigurationsreferenz
• OpenAI