Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix [Bug]: pdf tool reports Unknown model for config-defined custom providers even when models list shows the model [1 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#65742•Fetched 2026-04-14 05:40:33
View on GitHub
Comments
0
Participants
1
Timeline
1
Reactions
0
Author
lhy1024lhy1024
Participants
lhy1024lhy1024
Timeline (top)
cross-referenced ×1

On OpenClaw 2026.4.10, the pdf tool fails with Unknown model: local-openai/gpt-5.4-mini for a custom provider model defined in models.providers, even though the same model is accepted by config and visible in model listings.

Root Cause

On OpenClaw 2026.4.10, the pdf tool fails with Unknown model: local-openai/gpt-5.4-mini for a custom provider model defined in models.providers, even though the same model is accepted by config and visible in model listings.

Fix Action

Fix / Workaround

Observed local behavior before patch:

  • pdf tool failed with Unknown model: local-openai/gpt-5.4-mini
  • openclaw models / configured defaults accepted the same model

Observed local behavior after a minimal local patch and gateway restart:

  • the same pdf request succeeded on the real gateway/runtime path and returned a summary for a test PDF
  • this confirms the failure was in model resolution, not in the PDF request path itself

A local validation patch that switched the pdf tool from the registry-only helper to the config-aware resolver removed the Unknown model failure and allowed the request to execute successfully on the real gateway path.

PR fix notes

PR #65746: fix(pdf): resolve custom provider models with config-aware resolver

Description (problem / solution / changelog)

Summary

  • Fix the pdf tool so config-defined custom provider models continue to resolve when the runtime registry misses.
  • Keep the fix scoped to the pdf tool path.
  • Add a regression test covering a custom provider model defined under models.providers.

What changed

  • In src/agents/tools/pdf-tool.ts, switch the PDF model lookup from registry-only resolution to a helper that falls back to configured inline provider models.
  • In src/agents/tools/media-tool-shared.ts, add resolveModelFromRegistryOrConfig(...):
    • first try modelRegistry.find(provider, modelId)
    • if that misses, build inline provider models from cfg.models.providers
    • return the configured model if found
    • otherwise preserve the existing Unknown model: provider/model error
  • In src/agents/tools/pdf-tool.test.ts, add a regression test for a config-defined custom provider model when registry lookup misses.

Why this approach

The earlier draft path that pulled resolution through the embedded runner model module introduced test instability in this tool test surface. This version keeps the fix local to media/pdf tool resolution and uses the lighter inline provider config path instead.

That keeps the behavior change narrowly targeted:

  • no provider runtime changes
  • no auth flow changes
  • no global model-selection behavior changes outside the pdf tool path

User-visible behavior

Before:

  • pdf could fail with:
    • Unknown model: local-openai/gpt-5.4-mini

After:

  • if the model is defined under cfg.models.providers, the pdf tool can resolve it even when the runtime registry misses
  • truly unknown models still produce the same Unknown model: ... error

Verification

Real runtime verification

Validated on a real local OpenClaw runtime path (not only source inspection):

  • local OpenClaw install version: 2026.4.10
  • real gateway restarted and re-tested
  • same pdf request that previously failed with Unknown model: local-openai/gpt-5.4-mini succeeded after the local runtime-equivalent fix
  • successful response included:
    • This PDF contains only the text “Dummy PDF file” and no other content.

Source test verification

Ran:

pnpm exec vitest run src/agents/tools/pdf-tool.test.ts --reporter=verbose --testTimeout=5000 --hookTimeout=5000

Result:

  • 1 passed test file
  • 12 passed tests

Also passed local repo checks during commit/push, including:

  • import cycle checks
  • madge import cycle checks
  • tsgo
  • lint
  • webhook/auth guard checks

Linked issue

  • Closes #65742

Notes

This PR is intentionally narrow. It fixes the concrete pdf tool failure for config-defined custom providers without broadening the change into shared embedded-runner model resolution behavior.

Changed files

  • src/agents/tools/media-tool-shared.ts (modified, +26/-0)
  • src/agents/tools/pdf-tool.test.ts (modified, +57/-0)
  • src/agents/tools/pdf-tool.ts (modified, +7/-2)

Code Example

Unknown model: local-openai/gpt-5.4-mini

---

Unknown model: local-openai/gpt-5.4-mini

---

This PDF contains only the text “Dummy PDF file” and no other content.
RAW_BUFFERClick to expand / collapse

[Bug]: pdf tool reports Unknown model for config-defined custom providers even when models list shows the model

Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

On OpenClaw 2026.4.10, the pdf tool fails with Unknown model: local-openai/gpt-5.4-mini for a custom provider model defined in models.providers, even though the same model is accepted by config and visible in model listings.

Steps to reproduce

  1. Configure a custom provider under ~/.openclaw/openclaw.json, for example:
    • models.providers.local-openai.baseUrl = http://<local-gateway>/v1
    • models.providers.local-openai.api = openai-responses
    • models.providers.local-openai.models[].id = gpt-5.4-mini
  2. Set agents.defaults.pdfModel.primary = local-openai/gpt-5.4-mini.
  3. Restart the gateway.
  4. Invoke the pdf tool with either the configured default or an explicit model override:
    • model: local-openai/gpt-5.4-mini
  5. Observe the tool failure.

Expected behavior

The pdf tool should resolve and use the configured custom provider model the same way the main model/runtime path does, instead of failing with Unknown model.

Actual behavior

The pdf tool fails before the request is executed, with:

Unknown model: local-openai/gpt-5.4-mini

Observed local behavior before patch:

  • pdf tool failed with Unknown model: local-openai/gpt-5.4-mini
  • openclaw models / configured defaults accepted the same model

Observed local behavior after a minimal local patch and gateway restart:

  • the same pdf request succeeded on the real gateway/runtime path and returned a summary for a test PDF
  • this confirms the failure was in model resolution, not in the PDF request path itself

OpenClaw version

2026.4.10

Operating system

Manjaro Linux

Install method

npm global

Model

local-openai/gpt-5.4-mini

Provider / routing chain

openclaw -> local-openai -> local OpenAI-compatible gateway

Additional provider/model setup details

Relevant config was under ~/.openclaw/openclaw.json using a custom provider ID (local-openai) with a local baseUrl and api: openai-responses.

The pdf tool source on main still resolves models through resolveModelFromRegistry(...) in src/agents/tools/pdf-tool.ts, via src/agents/tools/media-tool-shared.ts. That helper is a thin modelRegistry.find(...) wrapper and does not follow the broader config-aware resolution path used elsewhere.

A local validation patch that switched the pdf tool from the registry-only helper to the config-aware resolver removed the Unknown model failure and allowed the request to execute successfully on the real gateway path.

Logs, screenshots, and evidence

Observed pre-patch failure:

Unknown model: local-openai/gpt-5.4-mini

Observed source shape on main at time of filing:

  • src/agents/tools/pdf-tool.ts
    • const model = resolveModelFromRegistry({ modelRegistry, provider, modelId });
  • src/agents/tools/media-tool-shared.ts
    • resolveModelFromRegistry(...) calls modelRegistry.find(...) directly

Observed post-patch verification on the real runtime path:

This PDF contains only the text “Dummy PDF file” and no other content.

This was returned by the pdf tool for the same model/provider path after replacing the registry-only resolution step and restarting the gateway.

Impact and severity

Affected: users configuring pdfModel with custom providers defined under models.providers Severity: High (blocks the pdf tool for those models) Frequency: Reproduced consistently before local patch Consequence: pdf tool cannot use configured custom provider routes even though the model appears configured and selectable elsewhere

Additional information

Related issue family / prior context:

  • #45221 shows a similar runtime/config mismatch pattern for the image tool
  • #35857 covers historical pdf-model configuration gaps
  • local investigation also found open PRs in the same area, including #53738

A key point from local validation is that after changing the pdf tool’s resolution path and restarting the real gateway, the exact same request succeeded. This suggests the bug is specifically the registry-only resolution path in the pdf tool rather than a generic provider incompatibility.

extent analysis

TL;DR

The pdf tool fails to resolve custom provider models due to using a registry-only resolution path, which can be fixed by switching to a config-aware resolver.

Guidance

  • The issue is likely caused by the pdf tool using resolveModelFromRegistry which only checks the model registry, instead of following the broader config-aware resolution path used elsewhere.
  • To verify, check if the custom provider model is correctly defined in ~/.openclaw/openclaw.json and if the pdf tool is using the correct resolution path.
  • A potential workaround is to update the pdf tool to use the config-aware resolver, similar to the local validation patch that removed the Unknown model failure.
  • Check related issues #45221 and #35857 for similar runtime/config mismatch patterns and potential solutions.

Example

// Before
const model = resolveModelFromRegistry({ modelRegistry, provider, modelId });

// After (suggested change)
const model = resolveModelFromConfig({ config, provider, modelId });

Note: The exact implementation of resolveModelFromConfig is not provided, but it should follow the config-aware resolution path used elsewhere in the codebase.

Notes

  • The fix may require updating the pdf tool to use the config-aware resolver, which could involve changes to src/agents/tools/pdf-tool.ts and src/agents/tools/media-tool-shared.ts.
  • The issue is specific to the pdf tool and custom provider models, and may not affect other tools or models.

Recommendation

Apply workaround: update the pdf tool to use the config-aware resolver, as this has been shown to resolve the issue in local validation.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

FAQ

Expected behavior

The pdf tool should resolve and use the configured custom provider model the same way the main model/runtime path does, instead of failing with Unknown model.

#api#model download#tokenizer error#prompt formatting#chain error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING