docs: update documentation for OpenHands v1.14.0

openhands/usage/agent-canvas/llm-profiles.mdx

@@ -42,13 +42,19 @@
 
 The `Free` label applies only to those full `openhands/` routes. Endpoints from other providers with similar model names may have separate billing. The label remains visible after you select one of these models.
 
-When you create a local LLM profile, the form initially selects `openhands/glm-5.2` and derives the profile name `glm-5.2`. You can change either value before saving.
+When you create a local LLM profile, the form initially selects `openhands/kimi-k3` and derives the profile name `kimi-k3`. You can change either value before saving.
 
 For key details and available models, see [OpenHands LLM Provider](/openhands/usage/llms/openhands-llms).
 
+### Pre-Save Validation
+
+When you save an LLM profile, the configuration is validated against the backend before it is persisted. If validation fails — for example, because the API key is rejected or the model is unavailable — the save is blocked and the backend error is shown. The save button displays a validating state while the check runs.
+
+Older backends that do not support validation (they return a `404` for the validation endpoint) skip this check and save normally.
+
 ### Local OpenAI-Compatible Endpoint
 
 A local server can be LM Studio, Ollama, vLLM, SGLang, or another service that exposes an OpenAI-compatible API. In the **Advanced** tab, enter the provider, exact model ID, endpoint base URL, and the required API key or a placeholder value when the server does not require one.
 
 The URL must be reachable from the **backend**, not only from your browser. For example, a backend in Docker cannot use `127.0.0.1` to reach a model server running on the host. Use the host address appropriate for that backend and confirm the endpoint's model inventory before saving.
 
@@ -58,7 +64,7 @@
 - **Base URL**: `http://host.docker.internal:1234/v1`
 - **API key**: `local-llm` or another placeholder value when the server does not require authentication
 
 See [Local LLMs](/openhands/usage/llms/local-llms) for LM Studio, Ollama, and other local-server examples.
 
 ### LiteLLM Proxy
 
@@ -99,7 +105,7 @@
 |---|---|---|
 | Provider is not recognized | Provider selection and model prefix | Use the matching configuration path above. |
 | Model format or identifier error | Exact model ID | Compare it with the provider or proxy model inventory. |
 | Local server cannot be reached | Base URL from the backend | Check host, port, and container or network reachability. |
 | Authentication or permission error | Key type and backend scope | Re-enter the key or follow the provider guide. |
 | Model cannot perform the task | Context and tool support | Choose a compatible model from the provider's recommendations. |
 

openhands/usage/agent-canvas/troubleshooting.mdx

@@ -137,7 +137,7 @@
 
 If startup fails because `uv` or `uvx` is missing:
 
 1. Install `uv` from the [official uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
 2. Open a new terminal so your shell reloads its `PATH`.
 3. Verify the install:
 
@@ -229,7 +229,7 @@
 | Default local Agent Canvas | `http://localhost:8000` |
 | Local backend on another port | `http://localhost:8001` |
 | Docker mapped to host port `8000` | `http://localhost:8000` |
 | VM or reverse proxy | Your VM, proxy, or ngrok URL |
 
 If you changed the port with `--port`, use the port you selected.
 
@@ -245,6 +245,11 @@
 - A LiteLLM proxy token is invalid.
 - An OpenAI-compatible provider needs the provider, model, base URL, and key to line up.
 
+Agent Canvas classifies conversation errors and presents them with distinct banner variants:
+
+- **Recoverable errors** (such as authentication failures) are shown with a warning banner, indicating you can take action — for example, updating an API key or switching models.
+- **Internal errors** are shown with an error banner, indicating a problem that may require restarting the conversation or backend.
+
 For model setup details, see:
 
 - [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles)
@@ -262,7 +267,7 @@
 3. Any custom `Base URL` is correct for the provider or local model server.
 4. The API key or token is valid.
 
 If you are using Ollama, LM Studio, LiteLLM, or another OpenAI-compatible endpoint, use the provider and base URL expected by that service. See [Local LLMs](/openhands/usage/llms/local-llms).
 
 ## ACP Agent Credentials Are Not Used
 
@@ -307,11 +312,11 @@
 
 ## Automation Features Are Unavailable
 
 Automations run on the active backend.
 
 If the `Automations` view shows an unavailable or unhealthy state:
 
 1. Switch to the default local backend and check whether automations work there.
 2. Confirm the remote backend includes the automation service.
 3. Check the backend logs for automation startup errors.
 4. Confirm required MCP servers and secrets are configured on the same backend as the automation.
@@ -322,7 +327,7 @@
 
 Agent Canvas currently has fuller support for LLM profiles than the hosted OpenHands Cloud UI.
 
 If profiles appear in Agent Canvas but not in OpenHands Cloud directly, that can be expected while the Cloud rollout is still in progress.
 
 Profiles and settings are also scoped to the active backend, so switching backends can change which profiles are available.
 

openhands/usage/settings/llm-settings.mdx

@@ -6,7 +6,7 @@
 ## Overview
 
 The LLM settings allows you to bring your own LLM and API key to use with OpenHands. This can be any model that is
 supported by litellm, but it requires a powerful model to work properly.
 [See our recommended models here](/openhands/usage/llms/llms#model-recommendations). You can also configure some
 additional LLM settings on this page.
 
@@ -64,6 +64,12 @@
 Alternatively, you can click the `Add LLM Profile` button in the Available Profiles section to create a new profile
 directly.
 
+<Note>
+When saving a local LLM profile, the configuration is validated against the backend before it is persisted. If validation
+fails (for example, an invalid API key or unavailable model), the save is blocked and the error is shown. Older backends
+that do not support validation skip this check and save normally.
+</Note>
+
 ### Managing LLM Profiles
 
 You can manage your saved profiles in the `Available Profiles` section of the LLM settings page. Each profile shows:
@@ -166,7 +172,7 @@
 Implement a simple web page on the features of OpenHands with Claude Opus 4.7, and then switch to GPT-5.5 and review the code.
 ```
 
 ![Agent Canvas showing example switch_llm tool calls that move a task between saved profiles](/openhands/static/img/model-selection-tool-agent-canvas.png)
 
 The model selection tool behaves as follows: