Summary

The /v1/responses endpoint validates tool definitions using the Chat Completions wrapped format ({type, function: {name, ...}}), but the OpenAI Responses API spec uses a flat format ({type, name, description, parameters}). This causes any compliant Responses API client (e.g. OpenAI Codex CLI) to fail with:

tools.0.function: Invalid input: expected object, received undefined

Root Cause

src/gateway/open-responses.schema.ts line 151–160:

export const FunctionToolDefinitionSchema = z
  .object({
    type: z.literal("function"),
    function: z.object({          // ← Chat Completions wrapper
      name: z.string().min(1),
      description: z.string().optional(),
      parameters: z.record(z.string(), z.unknown()).optional(),
    }),
  })
  .strict();  // ← .strict() causes extra top-level keys to fail validation

Clients sending the correct Responses API flat format:

{"type": "function", "name": "my_tool", "description": "...", "parameters": {...}}

fail because the schema only accepts the function: {...} wrapper and .strict() rejects the top-level name/description/parameters keys.

Expected Behavior

/v1/responses should accept the Responses API flat tool format as specified.

Reproduction

curl -s http://localhost:18789/v1/responses \
  -H "Authorization: Bearer <token>" \
  -H "x-openclaw-scopes: operator.write" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openclaw",
    "input": "Use the greet tool",
    "stream": false,
    "tools": [{"type":"function","name":"greet","description":"Say hello","parameters":{}}]
  }'
# Returns: 422 with "tools.0.function: Invalid input: expected object, received undefined"

# Workaround: wrap in function: {} (Chat Completions format) — but that is wrong for this endpoint

Fix

A fix is available in PR: https://github.com/malaiwah/openclaw/pull/1

• Change FunctionToolDefinitionSchema to the flat Responses API shape (fields at top level, add optional strict flag)
• Normalize from the flat API format to the internal ClientToolDefinition wrapped format in extractClientTools()
• Update parity tests to validate the flat format (and explicitly reject the wrapped format)

Affected Clients

Any Responses API client that sends tools in the spec-compliant flat format. Confirmed broken with:

• OpenAI Codex CLI (latest)

Version

OpenClaw v2026.3.28 (f9b1079)