Skip to content

docs(ollama): clarify /v1 tool-calling guidance#29204

Merged
vincentkoc merged 1 commit intoopenclaw:mainfrom
vincentkoc:vincentkoc-code/ollama-docs-tool-calling-fix
Feb 27, 2026
Merged

docs(ollama): clarify /v1 tool-calling guidance#29204
vincentkoc merged 1 commit intoopenclaw:mainfrom
vincentkoc:vincentkoc-code/ollama-docs-tool-calling-fix

Conversation

@vincentkoc
Copy link
Copy Markdown
Member

@vincentkoc vincentkoc commented Feb 27, 2026

Summary

  • Problem: Ollama /v1 usage was easy to miss and led to broken tool-calling behavior.
  • Why it matters: Users configuring remote Ollama could silently end up in OpenAI-compatible mode and get raw tool JSON output.
  • What changed: Added prominent warnings and clarified explicit config examples for native Ollama usage.
  • What did NOT change: No code/runtime behavior changes; docs-only.

Change Type (select all)

  • Bug fix
  • Feature
  • Refactor
  • Docs
  • Security hardening
  • Chore/infra

Scope (select all touched areas)

  • Gateway / orchestration
  • Skills / tool execution
  • Auth / tokens
  • Memory / storage
  • Integrations
  • API / contracts
  • UI / DX
  • CI/CD / infra

Linked Issue/PR

User-visible / Behavior Changes

None (docs-only). Ollama setup warnings are now more visible and wording around api: "ollama" is precise.

Security Impact (required)

  • New permissions/capabilities? No
  • Secrets/tokens handling changed? No
  • New/changed network calls? No
  • Command/tool execution surface changed? No
  • Data access scope changed? No

Repro + Verification

Environment

  • OS: N/A (docs)
  • Runtime/container: N/A
  • Model/provider: Ollama
  • Integration/channel: N/A
  • Relevant config: N/A

Steps

  1. Read docs/providers/ollama.md.
  2. Confirm top-level /v1 warning appears before setup.
  3. Confirm custom URL and legacy mode sections both warn about tool-calling limitations.

Expected

  • Users see /v1 pitfall warnings before copying config.

Actual

  • Warnings are present in all relevant sections.

Evidence

  • Diff shows targeted warning and wording updates in docs/providers/ollama.md

Human Verification (required)

  • Verified scenarios: Manual read-through of Ollama docs flow.
  • Edge cases checked: Wording avoids overstating api: "ollama" as universally required.
  • What I did NOT verify: Mintlify local render.

Compatibility / Migration

  • Backward compatible? Yes
  • Config/env changes? No
  • Migration needed? No

Failure Recovery (if this breaks)

  • How to disable/revert this change quickly: Revert this commit.
  • Files/config to restore: docs/providers/ollama.md
  • Known bad symptoms reviewers should watch for: N/A (docs-only)

Risks and Mitigations

None.

@vincentkoc vincentkoc mentioned this pull request Feb 27, 2026
Closed
15 tasks
@openclaw-barnacle openclaw-barnacle bot added docs Improvements or additions to documentation size: XS maintainer Maintainer-authored PR labels Feb 27, 2026
@vincentkoc vincentkoc marked this pull request as ready for review February 27, 2026 23:20
@vincentkoc vincentkoc merged commit d17c083 into openclaw:main Feb 27, 2026
25 checks passed
@greptile-apps
Copy link
Copy Markdown
Contributor

greptile-apps bot commented Feb 27, 2026

Greptile Summary

Added prominent warnings throughout the Ollama documentation to prevent users from accidentally using the /v1 OpenAI-compatible endpoint, which breaks native tool-calling. The changes clarify that remote Ollama users should use the base URL without /v1 and explicitly set api: "ollama" to ensure native tool-calling behavior works correctly.

Key improvements:

  • Top-level warning added before configuration section to catch users early
  • Explicit api: "ollama" recommendation in custom base URL example
  • Clear distinction between native Ollama API (recommended) and OpenAI-compatible mode (legacy/limited)
  • Consistent messaging across all relevant sections

Minor inconsistency noted:
The file docs/concepts/model-providers.md:360 still mentions http://127.0.0.1:11434/v1 which conflicts with this guidance, though that's outside this PR's scope.

Confidence Score: 5/5

  • Safe to merge - documentation-only changes with no runtime impact
  • This is a documentation-only PR that adds helpful warnings and clarifications. No code changes, no runtime behavior changes, and the guidance aligns with the codebase's intent (native Ollama API over OpenAI-compatible mode). The warnings address a real user confusion point about /v1 usage.
  • No files require special attention

Last reviewed commit: 90dbb30

velvet-shark pushed a commit to lailoo/openclaw that referenced this pull request Feb 27, 2026
@vincentkoc @velvet-shark
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
a6e68ad
@github-actions github-actions bot mentioned this pull request Feb 28, 2026
Open
r4jiv007 pushed a commit to r4jiv007/openclaw that referenced this pull request Feb 28, 2026
@vincentkoc @r4jiv007
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
22dbb0e
xiexikang pushed a commit to C-clawd/cclawd that referenced this pull request Feb 28, 2026
@vincentkoc
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
1191726
mylukin pushed a commit to mylukin/openclaw that referenced this pull request Feb 28, 2026
@vincentkoc @mylukin
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
d63e8e6
wanjizheng pushed a commit to wanjizheng/openclaw that referenced this pull request Feb 28, 2026
@vincentkoc @wanjizheng
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
1fe94bc
wanjizheng pushed a commit to wanjizheng/openclaw that referenced this pull request Feb 28, 2026
@vincentkoc @wanjizheng
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
2bf8743 
(cherry picked from commit 1fe94bc)
wanjizheng pushed a commit to wanjizheng/openclaw that referenced this pull request Feb 28, 2026
@vincentkoc @wanjizheng
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
2d56bf0 
(cherry picked from commit 1fe94bc)
wanjizheng pushed a commit to wanjizheng/openclaw that referenced this pull request Feb 28, 2026
@vincentkoc @wanjizheng
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
f63d88f 
(cherry picked from commit 1fe94bc)
vincentkoc added a commit to Sid-Qin/openclaw that referenced this pull request Feb 28, 2026
@vincentkoc
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
eee49ac
vincentkoc added a commit to rylena/rylen-openclaw that referenced this pull request Feb 28, 2026
@vincentkoc
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
0fbeb4e
newtontech pushed a commit to newtontech/openclaw-fork that referenced this pull request Feb 28, 2026
@vincentkoc
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
d2d5f7a
wanjizheng pushed a commit to wanjizheng/openclaw that referenced this pull request Mar 1, 2026
@vincentkoc @wanjizheng
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
2eb14fa
wanjizheng pushed a commit to wanjizheng/openclaw that referenced this pull request Mar 1, 2026
@vincentkoc @wanjizheng
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
da3783d
@github-actions github-actions bot mentioned this pull request Mar 1, 2026
Closed
6 tasks
hughdidit pushed a commit to hughdidit/DAISy-Agency that referenced this pull request Mar 1, 2026
@vincentkoc @github-actions
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
9ac0d9b 
(cherry picked from commit d17c083)

# Conflicts:
#	docs/providers/ollama.md
ansh pushed a commit to vibecode/openclaw that referenced this pull request Mar 2, 2026
@vincentkoc @ansh
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
294c9e1
steipete pushed a commit to Sid-Qin/openclaw that referenced this pull request Mar 2, 2026
@vincentkoc @steipete
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
322b2ed
safzanpirani pushed a commit to safzanpirani/clawdbot that referenced this pull request Mar 2, 2026
@vincentkoc @safzanpirani
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
0b9b97b
steipete pushed a commit to Sid-Qin/openclaw that referenced this pull request Mar 2, 2026
@vincentkoc @steipete
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
b592e29
venjiang pushed a commit to venjiang/openclaw that referenced this pull request Mar 2, 2026
@vincentkoc @venjiang
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
dc0094e
robertchang-ga pushed a commit to robertchang-ga/openclaw that referenced this pull request Mar 2, 2026
@vincentkoc
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
eb5958f
execute008 pushed a commit to execute008/openclaw that referenced this pull request Mar 2, 2026
@vincentkoc @execute008
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
065967b
hughdidit pushed a commit to hughdidit/DAISy-Agency that referenced this pull request Mar 3, 2026
@vincentkoc @github-actions
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
0e0ff94 
(cherry picked from commit d17c083)

# Conflicts:
#	docs/providers/ollama.md
dorgonman pushed a commit to kanohorizonia/openclaw that referenced this pull request Mar 3, 2026
@vincentkoc @dorgonman
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
8ea5f86
sachinkundu pushed a commit to sachinkundu/openclaw that referenced this pull request Mar 6, 2026
@vincentkoc
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
a436495
zooqueen pushed a commit to hanzoai/bot that referenced this pull request Mar 6, 2026
@vincentkoc
docs(ollama): clarify /v1 tool-calling guidance (openclaw#29204)
deb758f
@alexey-pelykh alexey-pelykh mentioned this pull request Mar 10, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docs Improvements or additions to documentation maintainer Maintainer-authored PR size: XS

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs: warn more clearly that openai-responses/openai-completions breaks tool calling for remote Ollama

1 participant

@vincentkoc