openclaw - 💡(How to fix) Fix pdf tool fails with openai-codex/gpt-5.5: "Instructions are required" [2 comments, 3 participants]

Summary

The pdf tool fails when configured to use openai-codex/gpt-5.5 as the PDF model.

Reproduced on:

OpenClaw 2026.5.4 (325df3e)

Model:

openai-codex/gpt-5.5

Error:

PDF model failed (openai-codex/gpt-5.5): Codex error: {"type":"error","status":400,"error":{"type":"invalid_request_error","message":"Instructions are required"}}

Reproduction steps

1. Configure the PDF tool to use Codex only:

{
  "agents": {
    "defaults": {
      "pdfModel": {
        "primary": "openai-codex/gpt-5.5",
        "fallbacks": []
      }
    }
  },
  "tools": {
    "profile": "coding",
    "alsoAllow": ["pdf"]
  }
}

1. Use the pdf tool on a small selectable-text PDF.
2. Prompt example:

What text does this PDF contain? Keep the answer concise.

Current behavior

The pdf tool is available and local extraction appears to run, but the model call fails with:

Instructions are required

This reproduces both in the current session and in a newly spawned session.

After upgrading to OpenClaw 2026.5.4, a previous local workaround was overwritten by the update, and the failure reappeared.

Expected behavior

The pdf tool should successfully pass extracted PDF text/images to openai-codex/gpt-5.5 and receive a normal assistant response.

Probable cause

In the PDF extraction fallback path, buildPdfExtractionContext() returns a context with user messages only and no systemPrompt.

Conceptually:

function buildPdfExtractionContext(prompt, extractions) {
  // ...builds content from extracted PDF text/images and user prompt...
  return {
    messages: [{
      role: "user",
      content,
      timestamp: Date.now()
    }]
  };
}

The OpenAI Codex Responses provider builds the request using:

instructions: context.systemPrompt

So the Codex request receives missing/undefined instructions, causing the API error.

Validated local workaround

Adding a short neutral systemPrompt to the PDF extraction context fixes the issue locally:

return {
  systemPrompt: "You are a helpful assistant. Use the extracted PDF content provided by the user message to answer accurately. If the content is insufficient, say so.",
  messages: [{
    role: "user",
    content,
    timestamp: Date.now()
  }]
};

With this workaround, the same selectable-text PDF smoke test succeeds.

Proposed minimal fix

Add a default systemPrompt in buildPdfExtractionContext() for the non-native PDF extraction fallback path.

The prompt should be brief, neutral, and PDF-specific. It should not include user/private content.

Risks / considerations

• Low behavioral risk: the prompt is generic and only guides PDF answering.
• This affects the PDF extraction fallback path for non-native PDF providers.
• The wording should avoid being provider-specific unless maintainers prefer a Codex-only conditional.
• Existing providers that do not require systemPrompt should continue to work.