API OpenResponses (HTTP)

Gateway OpenClaw может обслуживать OpenResponses-совместимую конечную точку POST /v1/responses.

Эта конечная точка отключена по умолчанию. Сначала включите ее в конфигурации.

  • POST /v1/responses
  • Тот же порт, что и Gateway (мультиплекс WS + HTTP): http://<gateway-host>:<port>/v1/responses

Под капотом запросы выполняются как обычный запуск агента Gateway (тот же кодовый путь, что и openclaw agent), поэтому маршрутизация/разрешения/конфигурация соответствуют вашему Gateway.

Аутентификация

Использует конфигурацию аутентификации Gateway. Отправьте bearer токен:

  • Authorization: Bearer <token>

Примечания:

  • Когда gateway.auth.mode="token", используйте gateway.auth.token (или OPENCLAW_GATEWAY_TOKEN).
  • Когда gateway.auth.mode="password", используйте gateway.auth.password (или OPENCLAW_GATEWAY_PASSWORD).

Выбор агента

Не требуются пользовательские заголовки: закодируйте id агента в поле model OpenResponses:

  • model: "openclaw:<agentId>" (пример: "openclaw:main", "openclaw:beta")
  • model: "agent:<agentId>" (псевдоним)

Или нацельтесь на конкретного агента OpenClaw по заголовку:

  • x-openclaw-agent-id: <agentId> (по умолчанию: main)

Продвинутое:

  • x-openclaw-session-key: <sessionKey> для полного контроля маршрутизации сессий.

Включение конечной точки

Установите gateway.http.endpoints.responses.enabled в true:

{
  gateway: {
    http: {
      endpoints: {
        responses: { enabled: true }
      }
    }
  }
}

Отключение конечной точки

Установите gateway.http.endpoints.responses.enabled в false:

{
  gateway: {
    http: {
      endpoints: {
        responses: { enabled: false }
      }
    }
  }
}

Поведение сессии

По умолчанию конечная точка без состояния для каждого запроса (новый ключ сессии генерируется при каждом вызове).

Если запрос включает строку user OpenResponses, Gateway выводит стабильный ключ сессии из него, чтобы повторные вызовы могли разделять сессию агента.

Форма запроса (поддерживается)

Запрос следует API OpenResponses с входом на основе элементов. Текущая поддержка:

  • input: строка или массив объектов элементов.
  • instructions: объединяется в системный промпт.
  • tools: определения инструментов клиента (function tools).
  • tool_choice: фильтровать или требовать инструменты клиента.
  • stream: включает SSE стриминг.
  • max_output_tokens: best-effort ограничение вывода (зависит от провайдера).
  • user: стабильная маршрутизация сессий.

Принимается, но в настоящее время игнорируется:

  • max_tool_calls
  • reasoning
  • metadata
  • store
  • previous_response_id
  • truncation

Элементы (input)

message

Роли: system, developer, user, assistant.

  • system и developer добавляются к системному промпту.
  • Самый последний элемент user или function_call_output становится "текущим сообщением".
  • Более ранние сообщения user/assistant включаются как история для контекста.

function_call_output (инструменты на основе ходов)

Отправьте результаты инструментов обратно в модель:

{
  "type": "function_call_output",
  "call_id": "call_123",
  "output": "{\"temperature\": \"72F\"}"
}

reasoning и item_reference

Принимается для совместимости схемы, но игнорируется при построении промпта.

Инструменты (клиентские function tools)

Предоставьте инструменты с tools: [\{ type: "function", function: \{ name, description?, parameters? \} \}].

Если агент решит вызвать инструмент, ответ возвращает элемент вывода function_call. Затем вы отправляете последующий запрос с function_call_output для продолжения хода.

Изображения (input_image)

Поддерживает источники base64 или URL:

{
  "type": "input_image",
  "source": { "type": "url", "url": "https://example.com/image.png" }
}

Разрешенные MIME типы (текущие): image/jpeg, image/png, image/gif, image/webp. Максимальный размер (текущий): 10MB.

Файлы (input_file)

Поддерживает источники base64 или URL:

{
  "type": "input_file",
  "source": {
    "type": "base64",
    "media_type": "text/plain",
    "data": "SGVsbG8gV29ybGQh",
    "filename": "hello.txt"
  }
}

Разрешенные MIME типы (текущие): text/plain, text/markdown, text/html, text/csv, application/json, application/pdf.

Максимальный размер (текущий): 5MB.

Текущее поведение:

  • Содержимое файла декодируется и добавляется к системному промпту, а не к сообщению пользователя, поэтому оно остается эфемерным (не сохраняется в истории сессии).
  • PDF разбираются для текста. Если найдено мало текста, первые страницы растрируются в изображения и передаются модели.

Разбор PDF использует Node-friendly сборку legacy pdfjs-dist (без worker). Современная сборка PDF.js ожидает browser workers/DOM globals, поэтому она не используется в Gateway.

Настройки по умолчанию для получения URL:

  • files.allowUrl: true
  • images.allowUrl: true
  • Запросы защищены (разрешение DNS, блокировка приватных IP, ограничения перенаправлений, таймауты).

Лимиты файлов + изображений (конфигурация)

Настройки по умолчанию можно настроить под gateway.http.endpoints.responses:

{
  gateway: {
    http: {
      endpoints: {
        responses: {
          enabled: true,
          maxBodyBytes: 20000000,
          files: {
            allowUrl: true,
            allowedMimes: ["text/plain", "text/markdown", "text/html", "text/csv", "application/json", "application/pdf"],
            maxBytes: 5242880,
            maxChars: 200000,
            maxRedirects: 3,
            timeoutMs: 10000,
            pdf: {
              maxPages: 4,
              maxPixels: 4000000,
              minTextChars: 200
            }
          },
          images: {
            allowUrl: true,
            allowedMimes: ["image/jpeg", "image/png", "image/gif", "image/webp"],
            maxBytes: 10485760,
            maxRedirects: 3,
            timeoutMs: 10000
          }
        }
      }
    }
  }
}

Значения по умолчанию при опущении:

  • maxBodyBytes: 20MB
  • files.maxBytes: 5MB
  • files.maxChars: 200k
  • files.maxRedirects: 3
  • files.timeoutMs: 10s
  • files.pdf.maxPages: 4
  • files.pdf.maxPixels: 4,000,000
  • files.pdf.minTextChars: 200
  • images.maxBytes: 10MB
  • images.maxRedirects: 3
  • images.timeoutMs: 10s

Стриминг (SSE)

Установите stream: true для получения Server-Sent Events (SSE):

  • Content-Type: text/event-stream
  • Каждая строка события event: <type> и data: <json>
  • Поток заканчивается data: [DONE]

Типы событий, в настоящее время испускаемые:

  • response.created
  • response.in_progress
  • response.output_item.added
  • response.content_part.added
  • response.output_text.delta
  • response.output_text.done
  • response.content_part.done
  • response.output_item.done
  • response.completed
  • response.failed (при ошибке)

Использование

usage заполняется, когда базовый провайдер сообщает подсчеты токенов.

Ошибки

Ошибки используют JSON объект как:

{ "error": { "message": "...", "type": "invalid_request_error" } }

Общие случаи:

  • 401 отсутствующая/недействительная аутентификация
  • 400 недействительное тело запроса
  • 405 неправильный метод

Примеры

Без стриминга:

curl -sS http://127.0.0.1:18789/v1/responses \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "input": "hi"
  }'

Со стримингом:

curl -N http://127.0.0.1:18789/v1/responses \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "stream": true,
    "input": "hi"
  }'
← Назад к документации