Fix OpenClaw reconnect auth drift

Document the required /v1 base URL and per-agent registry refresh behavior for OpenClaw.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: robinson

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2026.3.8] - 2026-03-27
+
+### Changed
+- **OpenClaw docs and connector guidance**: the README and docs-site now make the required `http://localhost:8080/v1` base URL explicit and document the recommended `openclaw models status --agent main --probe` verification path.
+
+### Fixed
+- **OpenClaw reconnect auth drift**: `isartor connect openclaw` now refreshes the `main` / default agent model override and clears stale per-agent `models.json` registries so changing the gateway API key does not leave OpenClaw stuck on old provider auth.
+
 ## [2026.3.7] - 2026-03-27
 
 ### Changed
@@ -395,7 +403,8 @@ Isartor's first CalVer release — marking go-live readiness.
 ### Fixed
 - Build musl targets with runner-based zigbuild (no Docker container)
 
-[Unreleased]: https://github.com/isartor-ai/Isartor/compare/v2026.3.7...HEAD
+[Unreleased]: https://github.com/isartor-ai/Isartor/compare/v2026.3.8...HEAD
+[2026.3.8]: https://github.com/isartor-ai/Isartor/compare/v2026.3.7...v2026.3.8
 [2026.3.7]: https://github.com/isartor-ai/Isartor/compare/v2026.3.6...v2026.3.7
 [2026.3.6]: https://github.com/isartor-ai/Isartor/compare/v2026.3.5...v2026.3.6
 [2026.3.5]: https://github.com/isartor-ai/Isartor/compare/v2026.3.4...v2026.3.5

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "isartor"
-version = "2026.3.7"
+version = "2026.3.8"
 edition = "2024"
 license = "Apache-2.0"
 description = "Open-source Prompt Firewall — a local LLM gateway with caching, semantic deduplication, and content filtering"

Cargo.toml

@@ -180,6 +180,8 @@ One command connects your favourite tool. No proxy, no MITM, no CA certificates.
 
 [Full integration guides →](https://isartor-ai.github.io/Isartor/integrations/overview.html)
 
+OpenClaw note: use Isartor's OpenAI-compatible `/v1` base path, not the root `:8080` URL. If you change Isartor's gateway API key later, rerun `isartor connect openclaw` so OpenClaw's per-agent model registry refreshes too.
+
 ---
 
 ## How Isartor Compares

README.md

@@ -25,8 +25,8 @@ openclaw onboard --install-daemon
 # 4. Register Isartor as an OpenClaw provider
 isartor connect openclaw
 
-# 5. Verify OpenClaw sees the provider/model
-openclaw models status
+# 5. Verify OpenClaw sees the provider/model and auth
+openclaw models status --agent main --probe
 
 # 6. Smoke test a prompt
 openclaw agent --agent main -m "Hello from OpenClaw through Isartor"
@@ -39,6 +39,8 @@ It writes or updates your OpenClaw config (default: `~/.openclaw/openclaw.json`)
 1. `models.providers.isartor`
 2. a single managed model entry matching Isartor's current upstream model
 3. `agents.defaults.model.primary = "isartor/<your-model>"`
+4. the `main` / default agent model override when one is present
+5. a refresh of stale per-agent `models.json` registries so OpenClaw regenerates them with the latest `baseUrl` and `apiKey`
 
 Example generated provider block:
 
@@ -72,6 +74,40 @@ agents: {
 }
 ```
 
+## Base URL and auth path
+
+OpenClaw must talk to Isartor's OpenAI-compatible `/v1` surface.
+
+- Correct base URL: `http://localhost:8080/v1`
+- Wrong base URL: `http://localhost:8080`
+
+Why this matters:
+
+- OpenClaw appends `/chat/completions` for OpenAI-compatible custom providers
+- Isartor exposes that route as `/v1/chat/completions`
+- using the root gateway URL can produce `404` errors such as `gateway unknown L0 via chat/completions`
+
+`isartor connect openclaw` writes the `/v1` path for you, so prefer the connector over hand-editing the provider block.
+
+## Reconnecting after changing the gateway API key
+
+OpenClaw stores custom-provider state in two places:
+
+1. `~/.openclaw/openclaw.json`
+2. per-agent `models.json` registries under `~/.openclaw/agents/<agentId>/agent/`
+
+Those per-agent registries can keep an old `apiKey` or `baseUrl` even after `openclaw.json` changes. That is why you can still see `401` after fixing the key in the top-level config.
+
+The supported fix is simply:
+
+```bash
+isartor connect openclaw --gateway-api-key <your-key>
+openclaw models status --agent main --probe
+openclaw agent --agent main -m "Hello from OpenClaw through Isartor"
+```
+
+The connector now refreshes `openclaw.json`, updates the `main` / default agent model override, and removes stale per-agent `models.json` files so OpenClaw regenerates them with the new auth.
+
 ## Why this is the best fit
 
 The upstream LiteLLM/OpenClaw docs assume the gateway can expose a multi-model catalog and route among many providers behind one endpoint.
@@ -85,6 +121,7 @@ Isartor is different today:
 That means:
 
 - if you change Isartor's provider/model later, rerun `isartor connect openclaw`
+- if you change Isartor's gateway API key later, rerun `isartor connect openclaw --gateway-api-key ...`
 - do **not** expect `isartor/openai/...` and `isartor/anthropic/...` fallbacks to behave like LiteLLM provider switching unless Isartor itself grows multi-provider routing later
 
 ## Options
@@ -98,6 +135,7 @@ That means:
 ## Files written
 
 - `~/.openclaw/openclaw.json` — managed OpenClaw provider config
+- `~/.openclaw/agents/<agentId>/agent/models.json` — regenerated by OpenClaw after Isartor clears stale custom-provider caches
 - `openclaw.json.isartor-backup` — backup, when a prior config existed
 
 ## Disconnecting
@@ -116,7 +154,7 @@ For day-to-day use:
 2. Validate with `isartor check`
 3. Keep Isartor running with `isartor up --detach`
 4. Let OpenClaw use `isartor/<configured-model>` as its primary model
-5. Use `openclaw models status` whenever you want to confirm what OpenClaw currently sees
+5. Use `openclaw models status --agent main --probe` whenever you want to confirm what OpenClaw currently sees
 
 If you later switch Isartor from, for example, Groq to OpenAI or Azure:
 
@@ -143,6 +181,7 @@ That refreshes OpenClaw's provider model to match the new Isartor config.
 | Symptom | Cause | Fix |
 |---------|-------|-----|
 | OpenClaw cannot reach the provider | Isartor not running | Run `isartor up --detach` first |
+| OpenClaw onboarding/custom provider returns 404 | Base URL points at `http://localhost:8080` instead of `http://localhost:8080/v1` | Use `isartor connect openclaw` or update the custom provider base URL to end with `/v1` |
 | OpenClaw still shows the old model | Isartor model changed after initial connect | Re-run `isartor connect openclaw` |
-| Auth errors (401) | Gateway auth enabled | Re-run with `--gateway-api-key` or set `ISARTOR__GATEWAY_API_KEY` |
+| Auth errors (401) after reconnecting | OpenClaw is still using stale per-agent provider state | Re-run `isartor connect openclaw --gateway-api-key <key>` so Isartor refreshes `openclaw.json` and clears stale per-agent `models.json` registries |
 | "Model is not allowed" | OpenClaw allowlist still excludes the managed model | Re-run `isartor connect openclaw` so the managed model is re-added to the allowlist |