Moving to OpenResponses for Agentic Workflows

I’ve often found that standard chat APIs don’t quite cut it for complex agents. Mapping agent states to a simple message list feels restrictive when you need semantic streaming and structured items. It usually feels like trying to fit a square peg in a round hole when you need events that actually describe what the agent is doing.

I want to show you how we are bringing the OpenResponses standard to the OpenClaw Gateway. This adds a /v1/responses endpoint designed specifically for agentic workflows. It uses item-based inputs and semantic streaming events instead of just dumping text.

What You’ll Need

• OpenClaw Gateway source code.
• Access to your gateway configuration file.
• A tool like curl for testing the endpoint.
• Auth credentials for your gateway instance.

Quick Start

The new endpoint is currently behind a feature flag. I recommend keeping the legacy Chat Completions active while you test this out.

1. Enable the Endpoint

Update your configuration to enable the OpenResponses gateway. By default, this is turned off.

gateway:
  http:
    endpoints:
      responses:
        enabled: true
      chatCompletions:
        enabled: true

2. Send Your First Response Request

The /v1/responses endpoint accepts ItemParam objects. You can include an optional OpenResponses-Version: latest header.

curl https://your-gateway/v1/responses \
  -H "Content-Type: application/json" \
  -H "OpenResponses-Version: latest" \
  -H "Authorization: Bearer $YOUR_TOKEN" \
  -d '{
    "model": "gpt-4",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [{ "type": "text", "text": "Help me with my task." }]
      }
    ],
    "stream": true
  }'

3. Verify the Stream

If you set stream: true, you should see a specific sequence of semantic events. The gateway will send both the event: and data: fields for each line:

1. response.created
2. response.output_item.added
3. response.content_part.added
4. response.output_text.delta (multiple events)
5. response.output_text.done
6. response.content_part.done
7. response.completed
8. [DONE]

Troubleshooting

Unsupported Content Types

If you try to send images or files in Phase 1, the gateway will return an invalid_request_error. We are currently focusing on text and function outputs.

Usage Values are Zero

You might notice that the usage field in the response resource contains zeroed values. This is expected for now. Token accounting is not yet wired into the new responses handler.

Legacy Warnings

If you keep gateway.http.endpoints.chatCompletions.enabled set to true, you will see a startup warning. This is just a reminder that the Chat Completions endpoint is now considered a legacy compatibility layer.

If you have questions about specific schemas, check out AI Setup Assistant.

What’s Next

• OpenAI Chat Completions Legacy API
• OpenResponses Specification (See src/gateway/open-responses.schema.ts)