OpenResponses API (HTTP)

Gateway của OpenClaw có thể cung cấp endpoint POST /v1/responses tương thích với OpenResponses.

Endpoint này mặc định bị tắt. Các bạn cần bật nó trong config trước.

  • POST /v1/responses
  • Cùng port với Gateway (WS + HTTP multiplex): http://<gateway-host>:<port>/v1/responses

Về cơ bản, các request được thực thi như một Gateway agent run bình thường (cùng codepath với openclaw agent), nên routing/permissions/config sẽ khớp với Gateway của các bạn.

Xác thực

Sử dụng cấu hình auth của Gateway. Gửi bearer token:

  • Authorization: Bearer <token>

Lưu ý:

  • Khi gateway.auth.mode="token", dùng gateway.auth.token (hoặc OPENCLAW_GATEWAY_TOKEN).
  • Khi gateway.auth.mode="password", dùng gateway.auth.password (hoặc OPENCLAW_GATEWAY_PASSWORD).

Chọn agent

Không cần custom header: mã hóa agent id vào trường model của OpenResponses:

  • model: "openclaw:<agentId>" (ví dụ: "openclaw:main", "openclaw:beta")
  • model: "agent:<agentId>" (alias)

Hoặc target một OpenClaw agent cụ thể bằng header:

  • x-openclaw-agent-id: <agentId> (mặc định: main)

Nâng cao:

  • x-openclaw-session-key: <sessionKey> để kiểm soát hoàn toàn session routing.

Bật endpoint

Set gateway.http.endpoints.responses.enabled thành true:

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

Tắt endpoint

Set gateway.http.endpoints.responses.enabled thành false:

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

Hành vi Session

Mặc định endpoint là stateless per request (một session key mới được tạo mỗi lần gọi).

Nếu request có chuỗi user của OpenResponses, Gateway sẽ tạo một session key ổn định từ nó, để các lần gọi lặp lại có thể chia sẻ một agent session.

Cấu trúc Request (được hỗ trợ)

Request tuân theo OpenResponses API với input dạng item. Hiện tại hỗ trợ:

  • input: string hoặc array các item object.
  • instructions: được merge vào system prompt.
  • tools: định nghĩa tool từ client (function tools).
  • tool_choice: lọc hoặc yêu cầu client tools.
  • stream: bật SSE streaming.
  • max_output_tokens: giới hạn output tối đa (tùy provider).
  • user: routing session ổn định.

Được chấp nhận nhưng hiện tại bị bỏ qua:

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

Items (input)

message

Roles: system, developer, user, assistant.

  • system và developer được thêm vào system prompt.
  • Item user hoặc function_call_output gần nhất trở thành “current message.”
  • Các message user/assistant trước đó được đưa vào như history để làm context.

function_call_output (turn-based tools)

Gửi kết quả tool về model:

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

reasoning và item_reference

Được chấp nhận để tương thích schema nhưng bị bỏ qua khi build prompt.

Tools (client-side function tools)

Cung cấp tools với tools: [{ type: "function", function: { name, description?, parameters? } }].

Nếu agent quyết định gọi một tool, response sẽ trả về một function_call output item. Sau đó các bạn gửi một request tiếp theo với function_call_output để tiếp tục turn.

Images (input_image)

Hỗ trợ nguồn base64 hoặc URL:

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

Các MIME type được phép (hiện tại): image/jpeg, image/png, image/gif, image/webp. Kích thước tối đa (hiện tại): 10MB.

Files (input_file)

Hỗ trợ nguồn base64 hoặc URL:

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

Các MIME type được phép (hiện tại): text/plain, text/markdown, text/html, text/csv, application/json, application/pdf.

Kích thước tối đa (hiện tại): 5MB.

Hành vi hiện tại:

  • Nội dung file được decode và thêm vào system prompt, không phải user message, nên nó sẽ là ephemeral (không được lưu trong session history).
  • PDF được parse để lấy text. Nếu có ít text, các trang đầu tiên sẽ được rasterize thành ảnh và truyền cho model.

Parse PDF sử dụng pdfjs-dist legacy build thân thiện với Node (không có worker). Build PDF.js hiện đại yêu cầu browser workers/DOM globals, nên không được dùng trong Gateway.

Mặc định URL fetch:

  • files.allowUrl: true
  • images.allowUrl: true
  • Các request được bảo vệ (DNS resolution, private IP blocking, redirect caps, timeouts).

Giới hạn File + image (config)

Các giá trị mặc định có thể điều chỉnh trong 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,
          },
        },
      },
    },
  },
}

Giá trị mặc định khi bỏ qua:

  • 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

Streaming (SSE)

Set stream: true để nhận Server-Sent Events (SSE):

  • Content-Type: text/event-stream
  • Mỗi dòng event là event: <type> và data: <json>
  • Stream kết thúc với data: [DONE]

Các loại event hiện được phát ra:

  • 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 (khi có lỗi)

Usage

usage được điền khi provider bên dưới báo cáo số lượng token.

Lỗi

Lỗi sử dụng JSON object như:

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

Các trường hợp phổ biến:

  • 401 thiếu/sai auth
  • 400 request body không hợp lệ
  • 405 sai method

Ví dụ

Non-streaming:

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

Streaming:

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