Complétions de chat OpenAI

Le Gateway d'OpenClaw peut exposer un petit point de terminaison Chat Completions compatible OpenAI.

Ce point de terminaison est désactivé par défaut. Activez-le d'abord dans la configuration.

• POST /v1/chat/completions
• Même port que le Gateway (multiplexage WS + HTTP) : http://<gateway-host>:<port>/v1/chat/completions

Lorsque la surface HTTP compatible OpenAI du Gateway est activée, elle expose également :

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

Sous le capot, les requêtes sont exécutées comme une exécution normale d'agent Gateway (le même chemin de code que openclaw agent), donc le routage, les autorisations et la configuration correspondent à votre Gateway.

# Authentification

Utilise la configuration d'authentification du Gateway.

Chemins d'authentification HTTP courants :

• authentification par secret partagé (gateway.auth.mode="token" ou "password") : Authorization: Bearer <token-or-password>
• authentification HTTP approuvée portant une identité (gateway.auth.mode="trusted-proxy") : faites passer la requête par le proxy configuré, conscient de l'identité, et laissez-le injecter les en-têtes d'identité requis
• authentification ouverte en entrée privée (gateway.auth.mode="none") : aucun en-tête d'authentification requis

Notes :

• Lorsque gateway.auth.mode="token", utilisez gateway.auth.token (ou OPENCLAW_GATEWAY_TOKEN).
• Lorsque gateway.auth.mode="password", utilisez gateway.auth.password (ou OPENCLAW_GATEWAY_PASSWORD).
• Lorsque gateway.auth.mode="trusted-proxy", la requête HTTP doit provenir d'une source de proxy approuvée configurée ; les proxies loopback sur le même hôte nécessitent gateway.auth.trustedProxy.allowLoopback = true explicitement.
• Si gateway.auth.rateLimit est configuré et que trop d'échecs d'authentification surviennent, le point de terminaison renvoie 429 avec Retry-After.

# Limite de sécurité (important)

Traitez ce point de terminaison comme une surface à accès opérateur complet pour l'instance de Gateway.

• L'authentification HTTP bearer ici n'est pas un modèle de portée étroite par utilisateur.
• Un token/mot de passe Gateway valide pour ce point de terminaison doit être traité comme un identifiant de propriétaire/opérateur.
• Les requêtes passent par le même chemin d'agent du plan de contrôle que les actions d'opérateur approuvées.
• Il n'existe pas de limite d'outils séparée non-propriétaire/par utilisateur sur ce point de terminaison ; une fois qu'un appelant réussit l'authentification Gateway ici, OpenClaw traite cet appelant comme un opérateur approuvé pour ce Gateway.
• Pour les modes d'authentification par secret partagé (token et password), le point de terminaison restaure les valeurs par défaut normales d'opérateur complet même si l'appelant envoie un en-tête x-openclaw-scopes plus restreint.
• Les modes HTTP approuvés portant une identité (par exemple l'authentification par proxy approuvé ou gateway.auth.mode="none") respectent x-openclaw-scopes lorsqu'il est présent et reviennent sinon à l'ensemble normal de portées opérateur par défaut.
• Si la stratégie de l'agent cible autorise des outils sensibles, ce point de terminaison peut les utiliser.
• Gardez ce point de terminaison uniquement sur loopback/tailnet/entrée privée ; ne l'exposez pas directement à l'internet public.

Matrice d'authentification :

• gateway.auth.mode="token" ou "password" + Authorization: Bearer ...
  • prouve la possession du secret partagé de l'opérateur du Gateway
  • ignore les x-openclaw-scopes plus restreints
  • restaure l'ensemble complet de portées opérateur par défaut : operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • traite les tours de conversation sur ce point de terminaison comme des tours émis par le propriétaire
• modes HTTP approuvés portant une identité (par exemple l'authentification par proxy approuvé, ou gateway.auth.mode="none" sur une entrée privée)
  • authentifient une identité approuvée externe ou une limite de déploiement
  • respectent x-openclaw-scopes lorsque l'en-tête est présent
  • reviennent à l'ensemble normal de portées opérateur par défaut lorsque l'en-tête est absent
  • ne perdent la sémantique de propriétaire que lorsque l'appelant restreint explicitement les portées et omet operator.admin

Consultez Sécurité et Accès distant.

# Contrat de modèle centré sur l'agent

OpenClaw traite le champ OpenAI model comme une cible d'agent, pas comme un identifiant brut de modèle fournisseur.

• model: "openclaw" route vers l'agent par défaut configuré.
• model: "openclaw/default" route également vers l'agent par défaut configuré.
• model: "openclaw/<agentId>" route vers un agent précis.

En-têtes de requête facultatifs :

• x-openclaw-model: <provider/model-or-bare-id> remplace le modèle backend pour l'agent sélectionné.
• x-openclaw-agent-id: <agentId> reste pris en charge comme remplacement de compatibilité.
• x-openclaw-session-key: <sessionKey> contrôle entièrement le routage de session.
• x-openclaw-message-channel: <channel> définit le contexte synthétique du canal d'entrée pour les invites et stratégies sensibles au canal.

Alias de compatibilité toujours acceptés :

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

# Activation du point de terminaison

Définissez gateway.http.endpoints.chatCompletions.enabled sur true :

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

# Désactivation du point de terminaison

Définissez gateway.http.endpoints.chatCompletions.enabled sur false :

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

# Comportement de session

Par défaut, le point de terminaison est sans état par requête (une nouvelle clé de session est générée à chaque appel).

Si la requête inclut une chaîne OpenAI user, le Gateway en déduit une clé de session stable, afin que les appels répétés puissent partager une session d'agent.

# Pourquoi cette surface est importante

Il s'agit de l'ensemble de compatibilité à plus fort effet de levier pour les interfaces et outils auto-hébergés :

• La plupart des installations Open WebUI, LobeChat et LibreChat attendent /v1/models.
• De nombreux systèmes RAG attendent /v1/embeddings.
• Les clients de chat OpenAI existants peuvent généralement commencer avec /v1/chat/completions.
• De plus en plus de clients davantage natifs aux agents préfèrent /v1/responses.

# Liste des modèles et routage des agents

# Streaming (SSE)

Définissez stream: true pour recevoir des Server-Sent Events (SSE) :

• Content-Type: text/event-stream
• Chaque ligne d'événement est data: <json>
• Le flux se termine par data: [DONE]

# Configuration rapide d'Open WebUI

Pour une connexion Open WebUI de base :

• URL de base : http://127.0.0.1:18789/v1
• URL de base Docker sur macOS : http://host.docker.internal:18789/v1
• Clé API : votre token bearer Gateway
• Modèle : openclaw/default

Comportement attendu :

• GET /v1/models doit lister openclaw/default
• Open WebUI doit utiliser openclaw/default comme identifiant du modèle de chat
• Si vous voulez un fournisseur/modèle backend précis pour cet agent, définissez le modèle par défaut normal de l'agent ou envoyez x-openclaw-model

Test rapide :

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

Si cela renvoie openclaw/default, la plupart des installations Open WebUI peuvent se connecter avec la même URL de base et le même token.

# Exemples

Sans streaming :

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"}]
  }'

Avec 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-model: openai/gpt-5.4' \
  -d '{
    "model": "openclaw/research",
    "stream": true,
    "messages": [{"role":"user","content":"hi"}]
  }'

Lister les modèles :

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

Récupérer un modèle :

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

Créer des embeddings :

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"]
  }'

Notes :

• /v1/models renvoie des cibles d'agent OpenClaw, pas des catalogues bruts de fournisseurs.
• openclaw/default est toujours présent afin qu'un identifiant stable fonctionne dans tous les environnements.
• Les remplacements fournisseur/modèle backend vont dans x-openclaw-model, pas dans le champ OpenAI model.
• /v1/embeddings prend en charge input comme chaîne ou tableau de chaînes.

# Associé

• Référence de configuration
• OpenAI