Talking to OpenClaw via HTTP with OpenResponses

OpenResponses API (HTTP)

Integrating different AI models often feels like trying to fit square pegs into round holes. You find a great tool, but the API doesn’t match your existing setup, forcing you to write custom wrappers for every single integration.

OpenClaw’s Gateway solves this by offering an OpenResponses-compatible POST /v1/responses endpoint. It is disabled by default, so you need to enable it in your configuration first. Once it is active, you can access it at http://<gateway-host>:<port>/v1/responses. Since it uses the same logic as the openclaw agent command, your routing and permissions will work exactly as you expect.

Authentication, security, and routing

The way this endpoint handles operations matches the OpenAI Chat Completions setup. You need to use Authorization: Bearer <token> with your standard Gateway auth config. This endpoint gives you full operator access to the gateway instance.

If you use shared-secret modes like token or password, the system ignores any specific x-openclaw-scopes and gives you full operator defaults. For trusted identity modes, like a trusted proxy or when gateway.auth.mode="none", the system respects the scopes you declare in the request.

You can pick your agents using model: "openclaw", model: "openclaw/default", model: "openclaw/<agentId>", or the x-openclaw-agent-id header. If you want to change the backend model, use x-openclaw-model. For specific session routing, use x-openclaw-session-key. If you need a different ingress channel context, use x-openclaw-message-channel.

Here is the auth matrix:

• gateway.auth.mode="token" or "password" + Authorization: Bearer ...
  • proves possession of the shared gateway operator secret
  • ignores narrower x-openclaw-scopes
  • restores the full default operator scope set
  • treats chat turns on this endpoint as owner-sender turns
• trusted identity-bearing HTTP modes (for example trusted proxy auth, or gateway.auth.mode="none" on private ingress)
  • honor the declared x-openclaw-scopes header
  • only get owner semantics when operator.admin is actually present in those declared scopes

You can turn this endpoint on or off using gateway.http.endpoints.responses.enabled.

This compatibility layer also includes:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions

To understand how agent-first models and routing work together, check out OpenAI Chat Completions and [Model list and agent routing](/gateway/openai-http-api#model

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

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

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

{
  gateway: {
    http: {
      endpoints: {
        responses: {
          enabled: true,
          maxBodyBytes: 20000000,
          maxUrlParts: 8,
          files: {
            allowUrl: true,
            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],
            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,
            urlAllowlist: ["images.example.com"],
            allowedMimes: [
              "image/jpeg",
              "image/png",
              "image/gif",
              "image/webp",
              "image/heic",
              "image/heif",
            ],
            maxBytes: 10485760,
            maxRedirects: 3,
            timeoutMs: 10000,
          },
        },
      },
    },
  },
}

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

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