Uzupełnienia czatu OpenAI

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
• Ten sam port co Gateway (multipleks WS + HTTP): http://<gateway-host>:<port>/v1/chat/completions

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

​

Uwierzytelnianie

• uwierzytelnianie współdzielonym sekretem (gateway.auth.mode="token" albo "password"): Authorization: Bearer <token-or-password>
• zaufane uwierzytelnianie HTTP przenoszące tożsamość (gateway.auth.mode="trusted-proxy"): kieruj przez skonfigurowany proxy świadomy tożsamości i pozwól mu wstrzyknąć wymagane nagłówki tożsamości
• otwarte uwierzytelnianie dla prywatnego wejścia (gateway.auth.mode="none"): nagłówek uwierzytelniania nie jest wymagany

• Gdy gateway.auth.mode="token", użyj gateway.auth.token (albo OPENCLAW_GATEWAY_TOKEN).
• Gdy gateway.auth.mode="password", użyj gateway.auth.password (albo OPENCLAW_GATEWAY_PASSWORD).
• Gdy gateway.auth.mode="trusted-proxy", żądanie HTTP musi pochodzić ze skonfigurowanego zaufanego źródła proxy; proxy loopback na tym samym hoście wymagają jawnego gateway.auth.trustedProxy.allowLoopback = true.
• Jeśli gateway.auth.rateLimit jest skonfigurowany i wystąpi zbyt wiele nieudanych prób uwierzytelnienia, punkt końcowy zwraca 429 z Retry-After.

​

Granica bezpieczeństwa (ważne)

• Uwierzytelnianie HTTP bearer tutaj nie jest wąskim modelem zakresu per użytkownik.
• Prawidłowy token/hasło Gateway dla tego punktu końcowego należy traktować jak poświadczenie właściciela/operatora.
• Żądania przechodzą przez tę samą ścieżkę agenta płaszczyzny sterowania co zaufane działania operatora.
• Na tym punkcie końcowym nie ma osobnej granicy narzędzi dla nie-właściciela/per użytkownik; gdy wywołujący przejdzie tutaj uwierzytelnianie Gateway, OpenClaw traktuje go jako zaufanego operatora tego Gateway.
• W trybach uwierzytelniania współdzielonym sekretem (token i password) punkt końcowy przywraca normalne pełne domyślne uprawnienia operatora, nawet jeśli wywołujący wyśle węższy nagłówek x-openclaw-scopes.
• Zaufane tryby HTTP przenoszące tożsamość (na przykład uwierzytelnianie przez zaufany proxy albo gateway.auth.mode="none") respektują x-openclaw-scopes, gdy jest obecny, a w przeciwnym razie wracają do normalnego domyślnego zestawu zakresów operatora.
• Jeśli polityka agenta docelowego dopuszcza narzędzia wrażliwe, ten punkt końcowy może ich używać.
• Utrzymuj ten punkt końcowy wyłącznie na loopback/tailnet/prywatnym wejściu; nie wystawiaj go bezpośrednio do publicznego internetu.

• gateway.auth.mode="token" albo "password" + Authorization: Bearer ...
  • dowodzi posiadania współdzielonego sekretu operatora Gateway
  • ignoruje węższe x-openclaw-scopes
  • przywraca pełny domyślny zestaw zakresów operatora: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • traktuje tury czatu na tym punkcie końcowym jako tury wysyłane przez właściciela
• zaufane tryby HTTP przenoszące tożsamość (na przykład uwierzytelnianie przez zaufany proxy albo gateway.auth.mode="none" na prywatnym wejściu)
  • uwierzytelniają jakąś zewnętrzną zaufaną tożsamość lub granicę wdrożenia
  • respektują x-openclaw-scopes, gdy nagłówek jest obecny
  • wracają do normalnego domyślnego zestawu zakresów operatora, gdy nagłówka nie ma
  • tracą semantykę właściciela tylko wtedy, gdy wywołujący jawnie zawęża zakresy i pomija operator.admin

​

Kontrakt modelu z agentem na pierwszym miejscu

• model: "openclaw" kieruje do skonfigurowanego domyślnego agenta.
• model: "openclaw/default" także kieruje do skonfigurowanego domyślnego agenta.
• model: "openclaw/<agentId>" kieruje do konkretnego agenta.

• x-openclaw-model: <provider/model-or-bare-id> nadpisuje model backendu dla wybranego agenta.
• x-openclaw-agent-id: <agentId> pozostaje obsługiwane jako nadpisanie kompatybilności.
• x-openclaw-session-key: <sessionKey> w pełni kontroluje routing sesji.
• x-openclaw-message-channel: <channel> ustawia syntetyczny kontekst kanału wejściowego dla promptów i polityk świadomych kanału.

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

​

Włączanie punktu końcowego

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

​

Wyłączanie punktu końcowego

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

​

Zachowanie sesji

​

Dlaczego ta powierzchnia ma znaczenie

• Większość konfiguracji Open WebUI, LobeChat i LibreChat oczekuje /v1/models.
• Wiele systemów RAG oczekuje /v1/embeddings.
• Istniejące klienty czatu OpenAI mogą zwykle zacząć od /v1/chat/completions.
• Klienty bardziej natywne dla agentów coraz częściej preferują /v1/responses.

​

Lista modeli i routing agentów

​

Streaming (SSE)

• Content-Type: text/event-stream
• Każda linia zdarzenia ma postać data: <json>
• Strumień kończy się data: [DONE]

​

Kontrakt narzędzi czatu

​

Obsługiwane pola żądania

• tools: tablica { "type": "function", "function": { ... } }
• tool_choice: "auto", "none"
• messages[*].role: "tool" kolejne tury
• messages[*].tool_call_id do wiązania wyników narzędzi z wcześniejszym wywołaniem narzędzia
• max_completion_tokens: liczba; limit na wywołanie dla łącznych tokenów ukończenia (w tym tokenów rozumowania). Obecna nazwa pola OpenAI Chat Completions; preferowana, gdy wysłane są zarówno max_completion_tokens, jak i max_tokens.
• max_tokens: liczba; starszy alias akceptowany dla zgodności wstecznej. Ignorowany, gdy obecne jest również max_completion_tokens.

​

Nieobsługiwane warianty

• tools niebędące tablicą
• wpisy narzędzi niebędące funkcją
• brakujące tool.function.name
• warianty tool_choice, takie jak allowed_tools i custom
• tool_choice: "required" (nieegzekwowane jeszcze w czasie wykonywania; będzie obsługiwane po wdrożeniu twardego wymuszania)
• tool_choice: { "type": "function", "function": { "name": "..." } } (to samo uzasadnienie co przy required)
• wartości tool_choice.function.name, które nie pasują do podanych tools

​

Kształt odpowiedzi narzędzi bez streamingu

• choices[0].finish_reason = "tool_calls"
• wpisów choices[0].message.tool_calls[] z:
  • id
  • type: "function"
  • function.name
  • function.arguments (ciąg JSON)

​

Kształt odpowiedzi narzędzi ze streamingiem

• początkowa delta roli asystenta
• opcjonalne delty komentarza asystenta
• jeden lub więcej fragmentów delta.tool_calls przenoszących tożsamość narzędzia i fragmenty argumentów
• końcowy fragment z finish_reason: "tool_calls"
• data: [DONE]

​

Pętla kontynuacji narzędzi

• wcześniejszą wiadomość asystenta z wywołaniem narzędzia
• jedną lub więcej wiadomości role: "tool" z pasującym tool_call_id

​

Szybka konfiguracja Open WebUI

• Bazowy URL: http://127.0.0.1:18789/v1
• Bazowy URL Dockera na macOS: http://host.docker.internal:18789/v1
• Klucz API: Twój token bearer Gateway
• Model: openclaw/default

• GET /v1/models powinno wyświetlić openclaw/default
• Open WebUI powinien używać openclaw/default jako identyfikatora modelu czatu
• Jeśli chcesz określonego providera/modelu backendu dla tego agenta, ustaw normalny domyślny model agenta albo wyślij x-openclaw-model

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

​

Przykłady

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 zwraca cele agentów OpenClaw, a nie surowe katalogi dostawców.
• openclaw/default jest zawsze obecny, więc jeden stabilny identyfikator działa w różnych środowiskach.
• Nadpisania dostawcy/modelu backendu należy umieszczać w x-openclaw-model, a nie w polu OpenAI model.
• /v1/embeddings obsługuje input jako ciąg znaków lub tablicę ciągów znaków.

​

Powiązane

• Dokumentacja konfiguracji
• OpenAI