← Back to PRs

#22107: docs: add local providers troubleshooting guide

by pierreeurope open 2026-02-20 18:32 View on GitHub →
docs size: XS
Users running Ollama, vLLM, or other local models hit the same issues repeatedly (#22055, #4544, #1695): confusing API key errors, model discovery failures, and session corruption from malformed responses. There's no single page covering these common pitfalls across local providers. The individual provider docs have minimal troubleshooting sections. **Adds** `docs/providers/local-troubleshooting.md` covering: - "No API key found" (dummy key requirement) - "Unknown model" (discovery prerequisites) - No tool calling (model capability check) - Connection refused (server not running) - Slow responses/timeouts (hardware limits) - Session corruption after model errors - Mixed local + cloud fallback setup Also adds a link from the providers index page. <!-- greptile_comment --> <h3>Greptile Summary</h3> Adds a new `docs/providers/local-troubleshooting.md` page consolidating common issues when running OpenClaw with local LLM providers (Ollama, vLLM). Covers API key requirements, model discovery, tool calling, connection issues, performance, session corruption, and mixed local/cloud setups. Also adds a link from the providers index page. - Content is accurate and consistent with the existing Ollama and vLLM provider docs - All internal links and anchors resolve correctly (verified against `ollama.md`, `vllm.md`, and `gateway/troubleshooting.md`) - Frontmatter follows the established `summary`/`read_when`/`title` pattern - The page is not added to `docs.json` sidebar navigation, which follows the existing pattern (several providers like Ollama, vLLM, Venice, NVIDIA are also only linked from the index page) - Minor style note: the troubleshooting link is inserted mid-list in the provider index between vLLM and Qianfan, which slightly disrupts the provider catalog flow <h3>Confidence Score: 4/5</h3> - This PR is safe to merge — it only adds documentation with no code changes. - Documentation-only PR adding a well-structured troubleshooting guide. Content is accurate and links are valid. Minor placement concern in the index page is non-blocking. - No files require special attention. The link placement in `docs/providers/index.md` is a minor style suggestion. <sub>Last reviewed commit: cf18a52</sub> <!-- greptile_other_comments_section --> <!-- /greptile_comment -->

Most Similar PRs