Owlibou/owlen
2
0
Fork 0
Code Issues 20 Pull Requests Actions Packages Projects Releases 5 Activity

docs(release): prep v0.2 guidance and config samples

Browse Source 
AC:\n- README badge shows 0.2.0 and highlights cloud fallback, quotas, web search.\n- Configuration docs and sample config cover list TTL, quotas, context window, and updated env guidance.\n- Troubleshooting docs explain authentication fallback and rate limit recovery.\n\nTests:\n- Attempted 'cargo xtask lint-docs' (command unavailable: no such command: xtask).
This commit is contained in:
vikingowl
2025-10-24 12:55:17 +02:00
parent 3f6d7d56f6
commit 7e2c6ea037
4 changed files with 44 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/troubleshooting.md
View File

@@ -55,10 +55,19 @@ If Owlen is not behaving as you expect, there might be an issue with your config
If you see `Auth` errors when using the hosted service:
1. Run `owlen cloud setup` to register your API key (with `--api-key` for non-interactive use).
2. Use `owlen cloud status` to verify Owlen can authenticate against [Ollama Cloud](https://docs.ollama.com/cloud).
3. Ensure `providers.ollama.api_key` is set **or** export `OLLAMA_API_KEY` (legacy: `OLLAMA_CLOUD_API_KEY` / `OWLEN_OLLAMA_CLOUD_API_KEY`) when encryption is disabled. With `privacy.encrypt_local_data = true`, the key lives in the encrypted vault and is loaded automatically.
4. Confirm the key has access to the requested models.
5. Avoid pasting extra quotes or whitespace into the config file—`owlen config doctor` will normalise the entry for you.
2. Use `owlen cloud status` to verify Owlen can authenticate against [Ollama Cloud](https://docs.ollama.com/cloud) with the canonical `https://ollama.com` base URL. Override the endpoint via `providers.ollama_cloud.base_url` only if your account is pointed at a custom region.
3. Ensure `providers.ollama_cloud.api_key` is set **or** export `OLLAMA_API_KEY` (legacy: `OLLAMA_CLOUD_API_KEY` / `OWLEN_OLLAMA_CLOUD_API_KEY`) when encryption is disabled. With `privacy.encrypt_local_data = true`, the key lives in the encrypted vault and is loaded automatically.
4. Confirm the key has access to the requested models. Recent accounts scope access per workspace; visit <https://ollama.com/models> while signed in to double-check the SKU name.
5. Owlen disables the cloud provider after consecutive 401/403 responses, posts a toast, and falls back to the last healthy local provider so you can keep chatting. Re-run `owlen cloud setup` and flip back with `:provider ollama_cloud` once the key is valid again.
6. Avoid pasting extra quotes or whitespace into the config file—`owlen config doctor` will normalise the entry for you.
## Ollama Cloud Rate Limits (HTTP 429)
If the hosted API returns `HTTP 429 Too Many Requests`, Owlen keeps the provider enabled but surfaces a rate-limit toast and replays your message against the local provider so you do not lose work. To recover:
1. Check the cockpit header or run `:limits` to see your locally tracked hourly/weekly totals. When either bar crosses 80% Owlen warns you; 95% triggers a critical toast.
2. Raise or remove the soft quotas (`providers.ollama_cloud.hourly_quota_tokens`, `weekly_quota_tokens`) if your vendor allotment is higher, or pause cloud usage until the next window resets.
3. If you need the cloud-only model, retry after the provider’s cooling-off period (Ollama currently resets the rate window hourly for most SKUs). Adjust `list_ttl_secs` upward if automated refreshes are consuming too many tokens.
### Linux Ollama Sign-In Workaround (v0.12.3)