PR #68349: Ollama: honor Modelfile num_ctx and auto-detect tool support

• Repository: openclaw/openclaw
• Author: neeravmakwana
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/68349

Description (problem / solution / changelog)

Summary

• Problem: On a local Ollama setup, a Modelfile PARAMETER num_ctx 32768 override was ignored during discovery (only the base model's .context_length was read), which tripped context-window-guard with "Model context window too small (8192 tokens)". Non-tool models (e.g. plain llama3) also hit "does not support tools" with no auto-fallback, even though Ollama already reports capabilities on /api/show.
• Why it matters: Local Ollama is a supported provider and these two gaps made common local setups (large-context custom Modelfiles, non-tool base models) fail out of the box. Issue #68344 captured both, plus a third point (OLLAMA_API_KEY requirement) that is already addressed at HEAD via DEFAULT_API_KEY = "ollama-local" / OLLAMA_LOCAL_AUTH_MARKER — so that part is a docs clarification only.
• What changed:
  • queryOllamaModelShowInfo now also parses Ollama's parameters string from /api/show and lets a positive num_ctx <value> override win over model_info[*.context_length] (last-wins, matching Ollama's own generation-time semantics).
  • buildOllamaModelDefinition now auto-sets compat.supportsTools: false when /api/show returns a non-empty capabilities array that does not include "tools". Models with missing or empty capabilities keep compat undefined (existing permissive default).
  • Docs: added a Modelfile num_ctx note to the Context windows accordion, added a Tool support row to the implicit-discovery capability table, and clarified that OLLAMA_API_KEY is optional for local-only setups (reachable local hosts rely on the synthetic local auth marker).
  • Setup: bumped the synthetic pre-discovery capability fallback for kimi-k2.5:cloud from ["vision"] to ["vision", "tools"] so the new capability-driven compat gate does not wrongly flag Kimi as non-tool-supporting during cloud onboarding before its first /api/show refresh.
• What did NOT change (scope boundary):
  • No change to OLLAMA_DEFAULT_CONTEXT_WINDOW, OLLAMA_DEFAULT_MAX_TOKENS, DEFAULT_API_KEY, SSRF policy, reachability checks, or the fetch/timeout contract on /api/show.
  • No change to supportsModelTools gating logic in core — only the discovered compat payload shape.
  • No change to config schema, Plugin SDK public surface, generated baselines, or CODEOWNERS-protected surfaces.

Change Type (select all)

• Bug fix
• Docs

Scope (select all touched areas)

• Integrations

Linked Issue/PR

• Closes #68344
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause (num_ctx): queryOllamaModelShowInfo only inspected model_info[*.context_length] from Ollama's /api/show. The real user-authored override lives in the separate parameters string (multi-line Modelfile params), which was never read. Base-model context_length therefore beat a user's larger num_ctx 32768, and downstream context-window-guard blocked the run.
• Root cause (tool support): buildOllamaModelDefinition already consumed the capabilities array from /api/show for vision detection but ignored the tools bit, so non-tool models required manual compat.supportsTools: false. Ollama's own capability signal is authoritative here.
• Missing detection / guardrail: no test case covered the parameters override path on /api/show, and no test exercised capability-based tool-support detection for discovered models.
• Contributing context: docs recommended setting compat.supportsTools: false by hand for non-tool local models and did not mention Modelfile overrides at all; OLLAMA_API_KEY="ollama-local" was presented as mandatory when it is actually just a compatibility placeholder.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
• Target test or file: extensions/ollama/src/provider-models.test.ts
• Scenario the test should lock in:
  • PARAMETER num_ctx 32768 in /api/show parameters beats llama.context_length: 8192 (and handles repeat/last-wins plus malformed values).
  • Capabilities without "tools" set compat.supportsTools: false; capabilities with "tools" leave compat undefined; missing or empty capabilities preserve the existing permissive default.
• Why this is the smallest reliable guardrail: these are pure data-shape mappings in a single helper, with no network/FS coupling; unit coverage in the same file as the existing enrichment tests is exactly the right level and stays fast in pnpm test:extension ollama.
• Existing test that already covers this (if any): none — prior tests only exercised model_info[*.context_length] and vision capability detection.

User-visible / Behavior Changes

• Local/self-hosted Ollama models created with a Modelfile PARAMETER num_ctx <value> override now report that context window in openclaw models list and stop hitting Model context window too small (8192 tokens) when the override is large enough.
• Discovered Ollama models whose /api/show capabilities omit tools now get compat.supportsTools: false automatically and no longer fail tool-capable flows with "does not support tools"; tool-capable models behave exactly as before.
• Docs-only: Ollama provider page now documents Modelfile num_ctx behavior, the tools capability auto-flag, and that OLLAMA_API_KEY is optional for local-only setups.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No — same /api/show endpoint, same fetchWithSsrFGuard policy, same per-host allowlist, same timeout.
• Command/tool execution surface changed? No — supportsModelTools gating in core is unchanged; only the auto-populated compat.supportsTools value flows through the existing check.
• Data access scope changed? No.
• Behavior is runtime-enforced, not prompt-derived: parseOllamaNumCtxParameter is a pure regex/integer extractor (^num_ctx\s+(-?\d+)\b) that drops non-positive and non-finite values; the result is used only as a numeric context budget. compat.supportsTools: false is consumed by the existing runtime helper (src/agents/model-tool-support.ts) to skip sending tool schemas — not by any prompt text.

Repro + Verification

Environment

• OS: macOS 25.3.0 (Apple Silicon)
• Runtime/container: local repo, pnpm + Vitest
• Model/provider: Ollama local (http://127.0.0.1:11434)
• Integration/channel (if any): none
• Relevant config (redacted): default

Steps

1. Create a Modelfile: FROM llama3:latest / PARAMETER num_ctx 32768; ollama create llama3-32k -f ....
2. Run openclaw models list --provider ollama.
3. Start a chat against ollama/llama3-32k:latest.

Expected

• Model listed with contextWindow = 32768.
• Non-tool-capable base models work for plain chat without a manual compat.supportsTools: false entry.

Actual (before fix)

• Model listed at 8192, run blocked with Model context window too small (8192 tokens; source=model). Minimum is 16000..
• Non-tool models return does not support tools until the user edits config.

Evidence

Exact tests run locally on this branch:

• pnpm vitest run extensions/ollama/src/provider-models.test.ts → 12 passed (4 new)
• pnpm vitest run src/agents/models-config.providers.ollama.test.ts → 13 passed (regression baseline unchanged)
• pnpm test:extension ollama → 118 passed across 10 files
• pnpm test:contracts:plugins → 364 passed across 82 files
• pnpm exec oxlint extensions/ollama/src/provider-models.ts extensions/ollama/src/provider-models.test.ts extensions/ollama/src/setup.ts → 0 warnings, 0 errors
• pnpm format:check on all 5 touched files → clean after pnpm format

Note: pnpm tsgo surfaces pre-existing errors in extensions/qa-lab/src/providers/aimock/server.ts on plain origin/main (verified by re-running against the stashed baseline); those are unrelated to this change.

Human Verification (required)

• Verified scenarios: num_ctx override wins over model_info; repeat num_ctx lines pick the last positive integer; malformed or non-positive num_ctx values fall back to the base context_length; capabilities without tools produce compat.supportsTools: false; capabilities with tools and missing capabilities leave compat undefined; existing capability-driven vision → input: ["text", "image"] behavior unchanged; setup-time Kimi cloud seed still presents as vision + tool capable so its persisted config is unchanged; all 10 existing ollama extension test files remain green.
• Edge cases checked: empty/whitespace parameters string, repeated num_ctx (last-wins), negative/zero num_ctx, parameters not a string, capabilities present but empty, capabilities missing entirely.
• What I did not verify: a live Ollama host call; behavior is covered by the new unit tests against mocked /api/show responses that mirror Ollama's real payload shape.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes — discovered Ollama configs without Modelfile overrides or capability arrays behave exactly as before.
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: An Ollama build reports capabilities: ["completion"] for a model that actually does support tools, causing OpenClaw to skip tool schemas for it.
  • Mitigation: matches Ollama's own advertised capability; users can still override explicitly by configuring models.providers.ollama.models[].compat.supportsTools: true. We only act on a non-empty capabilities array — the old permissive default still applies when capabilities are missing.
• Risk: parameters parsing misinterprets a future Ollama field value.
  • Mitigation: parser requires ^num_ctx\s+<int> with a positive value after Number.parseInt, rejects malformed lines, and only overrides the computed contextWindow when the parsed value is a finite positive integer; tested against the three main Modelfile shapes plus malformed input.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/providers/ollama.md (modified, +23/-10)
• extensions/ollama/src/provider-models.test.ts (modified, +90/-0)
• extensions/ollama/src/provider-models.ts (modified, +43/-0)
• extensions/ollama/src/setup.ts (modified, +4/-2)