OpenHands · DevinVinson · Sep 9, 2026 · Sep 8, 2026 · Sep 8, 2026 · Sep 9, 2026
diff --git a/docs.json b/docs.json
@@ -279,6 +279,7 @@
               "openhands/usage/agent-canvas/conversations",
               "openhands/usage/agent-canvas/agent-profiles",
               "openhands/usage/agent-canvas/llm-profiles",
+              "openhands/usage/agent-canvas/model-configuration",
               "openhands/usage/agent-canvas/acp-agents",
               "openhands/usage/agent-canvas/plugins",
               "openhands/usage/agent-canvas/canvas-extensions",

diff --git a/openhands/usage/agent-canvas/first-time-setup.mdx b/openhands/usage/agent-canvas/first-time-setup.mdx
@@ -12,7 +12,7 @@
 Agent Canvas uses the **Agent-Client Protocol (ACP)** to communicate with agents, which means you're not locked into a single provider.

 - **OpenHands** (selected by default) — the general-purpose OpenHands agent, best for coding and exploration.
 - **Claude Code** — Anthropic's Claude Code agent.
 - **Codex** — OpenAI's Codex agent.
 - **Gemini CLI** — Google's Gemini CLI agent.

@@ -70,7 +70,7 @@
 - **GitHub Repository Monitor** — watch a repository for `@OpenHands` mentions and respond automatically.
 - **Slack Standup Digest** — summarize yesterday's Slack activity into an async standup note.

 You can browse all pre-built automations from the `Automate` view at any time. See [Pre-built Automations](/openhands/usage/agent-canvas/prebuilt-automations) for the full list.

 ## Getting Started Checklist

@@ -79,7 +79,7 @@
 1. **Set up your LLM** — links to `Settings > LLM`
 2. **Connect MCP servers** — links to `Customize > MCP`
 3. **Start a conversation** — links to `Conversations`
 4. **Explore automations** — links to `Automate`
 5. **Customize your agent** — links to `Customize`
 6. **Review settings** — links to `Settings`

@@ -89,6 +89,16 @@
   Toggle the checklist from `Settings > Application` using the **Show getting started checklist** switch. The setting persists across sessions.
 </Note>
 
+## Customize your Agent Canvas
+
+When you are ready to go beyond the default setup, choose the mechanism that fits the task:
+
+- Add repository-wide guidance with [`AGENTS.md`](/overview/skills/repo) for each Workspace.
+- Add reusable task instructions with [Skills](/overview/skills).
+- Connect external tools through [MCP](/openhands/usage/settings/mcp-settings).
+- Add packaged capabilities with [Plugins](/openhands/usage/agent-canvas/plugins).
+- Automate repeated work with [Automations](/openhands/usage/agent-canvas/managing-automations).
+
 ## After Your First Session
 
 Keep the terminal or Docker container that runs Agent Canvas active while you use the browser. When you are done, [stop Agent Canvas](/openhands/usage/agent-canvas/setup#stop-agent-canvas). Start it again with the same command when you return.

diff --git a/openhands/usage/agent-canvas/llm-profiles.mdx b/openhands/usage/agent-canvas/llm-profiles.mdx
@@ -11,6 +11,8 @@
 
 Open `Settings > LLM` to add a reusable LLM profile. Use the **Basic** tab for a provider and model available in the dropdowns. Use the **Advanced** tab when you need to enter a model name and base URL directly. Use the **All** tab to view and customize the full set of model configuration fields.
 
+If you are deciding between a provider key, local endpoint, LiteLLM proxy, OpenRouter, or ACP agent, start with [Configure a Model](/openhands/usage/agent-canvas/model-configuration).
+
 <Note>
 ACP agents such as Claude Code, Codex, and Gemini CLI manage their own model access. See [ACP Agents](/openhands/usage/agent-canvas/acp-agents) instead.
 </Note>
@@ -19,14 +21,14 @@
 
 | I have | Profile tab | Configure |
 |---|---|---|
-| An API key from Anthropic, OpenAI, Google, or another provider | **Basic** | Select the provider and model, then add its API key. |
-| An OpenHands LLM API key | **Basic** | Select `OpenHands`, choose a model, and add your OpenHands LLM API key. |
-| A local OpenAI-compatible server | **Advanced** | Enter the provider, exact model ID, base URL, and any required API key. |
-| A LiteLLM proxy | **Advanced** | Use the `litellm_proxy/` model prefix, proxy base URL, and proxy API key. |
+| An API key from Anthropic, OpenAI, Google, or another provider | **Basic** | Select the provider and model, then add its API key or reuse a Provider Connection. |
+| An OpenHands LLM API key | **Basic** | Select `OpenHands`, choose a model, then add the key or reuse a Provider Connection. |
+| A local OpenAI-compatible server | **Advanced** | Enter the provider and exact model ID, then add its base URL/key or reuse a Provider Connection. |
+| A LiteLLM proxy | **Advanced** | Use the `litellm_proxy/` model prefix, then add its proxy URL/key or reuse a Provider Connection. |
 
 ### Direct Provider
 
-In the **Basic** tab, select your provider and model, add the API key issued by that provider, and save the profile. Use a new conversation to test the change; an existing conversation continues with the agent and model it started with.
+In the **Basic** tab, select your provider and model. Select a **Provider Connection** to reuse its API key, or add an API key directly when it belongs only to this profile. Save the profile, then use a new conversation to test the change; an existing conversation continues with the agent and model it started with.
 
 For provider and model recommendations, see [LLM Configuration](/openhands/usage/llms/llms).
 
@@ -54,7 +56,7 @@

 ### 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.

@@ -64,7 +66,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

@@ -78,7 +80,7 @@
   Provider Connections are available on **local agent-server backends only**. The panel is hidden when using an OpenHands Cloud backend.
 </Note>
 
-When you want multiple LLM profiles to share the same provider credentials, use **Provider Connections** to store an API key and optional base URL once and reference it across profiles. This avoids pasting the same key into every profile and lets you rotate credentials in one place.
+When you want multiple LLM profiles to share the same provider credentials, use **Provider Connections** to store a provider, API key, and optional base URL once and reference it across profiles. This avoids pasting the same key into every profile and lets you rotate credentials in one place. Linked profiles keep their own model selection while using the shared connection for credentials.
 
 ### Create a Provider Connection
 
@@ -90,13 +92,13 @@
 
 ### Link a Profile to a Provider Connection
 
-In the profile editor, use the **provider-connection selector** to link a profile to an existing connection. When a profile is linked, its inline API key and base URL fields are hidden — the profile uses the connection's credentials instead.
+When you add or edit an LLM profile, choose a saved connection in the **Provider Connection** selector. Select **None** to use credentials specific to that profile instead. When a profile is linked, its inline API key and base URL fields are hidden — the profile uses the connection's credentials instead.
 
-Linked profiles are grouped under their provider connection name in the profile list for readability.
+Linked profiles are grouped under their Provider Connection name in the profile list for readability. To use another model with the same API key, add another LLM profile, select the same connection, choose that model, and save.
 
-### Broken Link Badge
+### Update or Delete a Connection
 
-If a provider connection is deleted while still referenced by a profile, the profile shows a **Broken link** badge. Re-link the profile to another connection or restore inline credentials to resolve it.
+Edit a Provider Connection to rename it, rotate its API key, or change its base URL. The update applies to every linked profile. Before deleting a connection, re-link or change every profile that uses it; Agent Canvas prevents deleting a connection while profiles still reference it.
 
 ## Working with LLM Profiles
 
@@ -133,7 +135,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. |


diff --git a/openhands/usage/agent-canvas/model-configuration.mdx b/openhands/usage/agent-canvas/model-configuration.mdx
@@ -0,0 +1,100 @@
+---
+title: Configure a Model
+description: Choose and verify an LLM configuration path in Agent Canvas.
+---
+
+Use this guide to choose a model configuration path in Agent Canvas. Start with the credentials or endpoint you have, then save the profile and test it in a new conversation.
+
+<Note>
+ACP agents such as Claude Code, Codex, and Gemini CLI manage their own model access. Use [ACP Agents](/openhands/usage/agent-canvas/acp-agents) instead of creating an LLM profile for those agents.
+</Note>
+
+## Choose a Configuration Path
+
+| I have | Use | Configure in |
+|---|---|---|
+| An API key from a model provider | A direct provider profile | `Settings > LLM` → `Basic` |
+| An OpenHands LLM API key | An OpenHands provider profile | `Settings > LLM` → `Basic` |
+| A local OpenAI-compatible server | A local endpoint profile | `Settings > LLM` → `Advanced` |
+| A LiteLLM proxy | A proxy profile | `Settings > LLM` → `Advanced` |
+| A signed-in Claude Code, Codex, or Gemini CLI subscription | An ACP agent | `Settings > Agent` |
+
+## Provider Connection for Reusable API Credentials
+
+Create a **Provider Connection** when you expect to use the same provider API key for more than one model or LLM profile. A connection stores the provider, API key, and optional base URL once; each linked profile supplies its own model configuration and uses the connection's credentials.
+
+1. Open `Settings > LLM`.
+2. In **Provider Connections**, select **Add provider connection**.
+3. Enter a recognizable name, such as `Personal OpenHands API` or `Team OpenAI`.
+4. Choose the provider from the searchable provider list.
+5. Enter the API key and, if needed, the provider base URL.
+6. Save the connection.
+7. Add or edit an LLM profile, select the connection in **Provider Connection**, then select the model and save the profile.
+
+When a profile uses a Provider Connection, its API key and base URL come from the connection rather than the profile. Reuse that connection for additional models from the same provider. Update the connection once to rotate its key or change its base URL for every linked profile.
+
+<Note>
+Provider Connections are available on local agent-server backends. The panel is hidden when using an OpenHands Cloud backend.
+</Note>
+
+## Direct Provider or OpenHands Profile
+
+Use the `Basic` tab when you have an API key from Anthropic, OpenAI, Google, OpenHands, or another provider in the selector.
+
+1. If you will reuse the key, create or choose a [Provider Connection](#provider-connection-for-reusable-api-credentials).
+2. Select the provider and model.
+3. Select the Provider Connection, or enter the API key directly for a profile-specific credential.
+4. Save the profile.
+5. Start a new conversation and send a short message to confirm the model responds.
+
+For model recommendations and provider references, see [LLM Configuration](/openhands/usage/llms/llms). For the OpenHands provider, see [OpenHands LLM Provider](/openhands/usage/llms/openhands-llms).
+
+## Local OpenAI-Compatible Server
+
+Use the `Advanced` tab for LM Studio, Ollama, vLLM, SGLang, or another server that exposes an OpenAI-compatible API.
+
+1. Find the exact model ID served by your server, usually from its `GET /v1/models` endpoint.
+2. Enter `openai/<served-model-id>` as the model.
+3. If the server needs an API key or a reusable base URL, create a [Provider Connection](#provider-connection-for-reusable-api-credentials) with those values and select it for the profile. Otherwise, enter them directly in the profile.
+4. Make sure the base URL is reachable from the **backend**.
+5. Save the profile and start a new conversation to verify it.
+
+If Agent Canvas runs in Docker while the model server runs on the host, `127.0.0.1` points to the container, not the host. Use the host address appropriate for your platform, such as `http://host.docker.internal:<port>/v1` where supported.
+
+See [Run Local LLMs with OpenHands](/openhands/usage/llms/local-llms) for server-specific examples.
+
+## LiteLLM Proxy
+
+Use the `Advanced` tab when you use a LiteLLM proxy.
+
+1. Enter `litellm_proxy/<model-name>` as the model.
+2. Create or select a [Provider Connection](#provider-connection-for-reusable-api-credentials) for the proxy URL and API key. You can instead enter those values directly when they are specific to one profile.
+3. Make sure `<model-name>` exactly matches a model configured on the proxy.
+4. Save the profile and start a new conversation to verify it.
+
+See [LiteLLM Proxy](/openhands/usage/llms/litellm-proxy) for the complete proxy configuration.
+
+## OpenRouter
+
+Use OpenRouter when you have an OpenRouter API key and want to access a model through its catalog. Create an `OpenRouter` Provider Connection to reuse the key, then in the `Basic` tab select `OpenRouter`, choose a model, select the connection, and save the profile. Use the `Advanced` tab only when you need to enter a model ID that is not available in the selector.
+
+See [OpenRouter](/openhands/usage/llms/openrouter) for model-ID and recovery guidance.
+
+## Fix a Failed Configuration
+
+| Symptom | Check first | Next step |
+|---|---|---|
+| Provider is not recognized | The profile path and provider/model prefix | Choose the matching path above. |
+| Model ID or format error | The exact model ID from the provider or proxy inventory | Update the model ID or prefix. |
+| Local endpoint cannot be reached | The base URL from the backend | Check host, port, bind address, and container networking. |
+| Authentication or permission error | Key type and provider account access | Re-enter the key and check the provider requirements. |
+| The model cannot complete agent tasks | Context length and tool-use support | Use a more capable model or supported runtime. |
+
+For additional error-specific guidance, see [Troubleshooting](/openhands/usage/agent-canvas/troubleshooting#model-or-api-key-errors).
+
+## Next Steps
+
+- [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles)
+- [Run Local LLMs with OpenHands](/openhands/usage/llms/local-llms)
+- [LiteLLM Proxy](/openhands/usage/llms/litellm-proxy)
+- [Troubleshooting](/openhands/usage/agent-canvas/troubleshooting)
diff --git a/openhands/usage/agent-canvas/overview.mdx b/openhands/usage/agent-canvas/overview.mdx
@@ -3,7 +3,7 @@
 description: Understand Agent Canvas, how it runs agents, and which setup path to choose.
 ---

 Agent Canvas is an open-source control surface for agentic work. From one place, you can manage conversations, files, terminals, model configuration, backends, and automations.

 The browser interface connects to one or more backends that run the agent and its tools. By default, that backend runs on your machine, but you can instead use Docker, a VM, Modal, or [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud). The LLM models can run locally, through a provider API or be accessed through an ACP agent.

@@ -14,7 +14,7 @@
 | If you want to... | Start here |
 |-------------------|------------|
 | Run OpenHands locally in a browser | [Install Agent Canvas](/openhands/usage/agent-canvas/setup) |
 | Use a sandboxed local environment | [Use Docker with Agent Canvas](/openhands/usage/agent-canvas/backend-setup/docker) |
 | Run agents on an always-on machine | [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm) |
 | Connect to managed cloud sandboxes | [Cloud Backend](/openhands/usage/agent-canvas/backend-setup/cloud) |
 | Use Claude Code, Codex, Gemini CLI, or another ACP agent | [ACP Agents](/openhands/usage/agent-canvas/acp-agents) |
@@ -27,8 +27,8 @@

 | Concept | What It Means | Why It Matters |
 |-------|---------------|----------------|
 | **Browser UI** | The web interface you open in your browser. | This is where you chat, inspect files, manage settings, and configure automations. |
 | **Backend** | The agent server that runs conversations, tools, settings, secrets, and automations. | This determines where the agent runs and what machine or sandbox it can access. |
 | **Workspace** | The folder, repository, container mount, or cloud sandbox the agent works in. | This determines which files the agent can read and write. |
 | **Agent and model** | The OpenHands agent or an ACP agent, plus the model credentials it uses. | This determines which LLM or provider receives conversation context and powers the agent. |

@@ -62,7 +62,7 @@
 | Setup | Trust Boundary | Best For |
 |-------|----------------|----------|
 | **npm local install** | Runs directly on your machine. The agent server can operate on the local filesystem. | Fastest local setup when you trust the machine and understand the file access. |
 | **Docker** | Runs inside a container and only sees the directories you mount. | Local sandboxing and clearer file boundaries. |
 | **VM or dedicated machine** | Runs on the remote host you control. | Always-on agents, heavier compute, team-shared backends, or personal/work separation. |
 | **OpenHands Cloud** | Runs in managed OpenHands Cloud sandboxes. | Cloud execution without maintaining your own machine or VM backend. |

@@ -72,7 +72,7 @@

 ## What Happens When You Close the Terminal?

 For a local npm or npx installation, closing the terminal stops the Agent Canvas process, so the browser UI can no longer use its local backend. Start Agent Canvas again with the same command to continue. A Docker container, VM, or cloud backend continues running until that backend is stopped.

 See [Install](/openhands/usage/agent-canvas/setup#run-agent-canvas-again) to restart Agent Canvas and [Troubleshooting](/openhands/usage/agent-canvas/troubleshooting) if the browser cannot reconnect.

@@ -83,20 +83,32 @@
 - **Direct provider key** — enter an API key from Anthropic, OpenAI, Google, or another supported provider.
 - **OpenHands LLM API key** — use an OpenHands LLM API key for verified hosted models.
 - **ACP agent subscription login** — use a signed-in provider, such as Claude Code, Codex, or Gemini, when the backend runs on the same machine as that login.
 - **Local or OpenAI-compatible provider** — connect providers such as Ollama, LM Studio, LiteLLM, or a compatible gateway through model settings.
 
-See [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles) and [ACP Agents](/openhands/usage/agent-canvas/acp-agents) for details.
+See [Configure a Model](/openhands/usage/agent-canvas/model-configuration), [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles), and [ACP Agents](/openhands/usage/agent-canvas/acp-agents) for details.
+
+## Customize Your Agent
+
+After the first conversation, choose the extension point that matches your need:
+
+| If you want to... | Start here |
+|---|---|
+| Add always-on repository guidance | [Repository Context and `AGENTS.md`](/overview/skills/repo) |
+| Add reusable task-specific instructions | [Skills Overview](/overview/skills) |
+| Connect external tools or services | [MCP Settings](/openhands/usage/settings/mcp-settings) |
+| Extend the agent with packaged capabilities | [Plugins](/openhands/usage/agent-canvas/plugins) |
+| Run work on a schedule or in response to events | [Automations](/openhands/usage/agent-canvas/managing-automations) |
 
 ## How It Fits With Other OpenHands Products
 
 | Surface | Best for | Where it runs |
 |---------|----------|---------------|
 | **Agent Canvas** | Browser-first agent work, workspace access, and automations | The backend you select: your machine, Docker, a VM, Modal, or Cloud |
 | **OpenHands SDK** | Building agent-powered Python applications | Your application and the workspace you configure |
 | **OpenHands Cloud** | Fully managed hosted execution | Managed OpenHands Cloud infrastructure |
 | **Local GUI (Legacy)** | Following older Docker-based Local GUI documentation | Your local Docker environment |

 ### Agent Canvas vs "openhands serve"

 `agent-canvas` starts the current Agent Canvas UI and backend stack. `openhands serve` starts the legacy OpenHands CLI GUI server and will not run if you have only installed agent-canvas.

@@ -113,7 +125,7 @@
 - A model access path, such as a provider API key, OpenHands Cloud LLM key, ACP subscription login, or local model server
 - A folder, repository, or project workspace for the agent to work in

 For a sandboxed local setup, use Docker instead of the direct npm backend path.

 ## Where To Go Next


diff --git a/openhands/usage/agent-canvas/troubleshooting.mdx b/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,13 +229,13 @@
 | 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.
 
 ## Model Or API Key Errors
 
-If a conversation fails before the agent responds, check `Settings > LLM`.
+If a conversation fails before the agent responds, check `Settings > LLM`. To choose the right provider, local endpoint, LiteLLM proxy, OpenRouter, or ACP path, start with [Configure a Model](/openhands/usage/agent-canvas/model-configuration).
 
 Common causes:
 
@@ -267,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

@@ -312,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.
@@ -327,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.


diff --git a/openhands/usage/llms/llms.mdx b/openhands/usage/llms/llms.mdx
@@ -4,7 +4,7 @@
 ---

 <Note>
 This section is for users who want to connect OpenHands to different LLMs.
 </Note>

 <Info>
@@ -13,6 +13,20 @@
 for the canonical list of supported parameters.
 </Info>
 
+## Choose a Model Configuration Path
+
+Choose the path that matches the access you have:
+
+| I have | Start here |
+|---|---|
+| An API key from a model provider or OpenHands | [Configure a Model in Agent Canvas](/openhands/usage/agent-canvas/model-configuration) |
+| A local model server such as Ollama, LM Studio, vLLM, or SGLang | [Run Local LLMs with OpenHands](/openhands/usage/llms/local-llms) |
+| A LiteLLM proxy | [LiteLLM Proxy](/openhands/usage/llms/litellm-proxy) |
+| An OpenRouter API key | [Use OpenRouter with OpenHands](/openhands/usage/llms/openrouter) |
+| Claude Code, Codex, or Gemini CLI credentials | [ACP Agents](/openhands/usage/agent-canvas/acp-agents) |
+
+For model-ID, endpoint, API-key, and recovery checks, use [Configure a Model](/openhands/usage/agent-canvas/model-configuration) before changing advanced settings.
+
 ## Model Recommendations
 
 Model quality for coding agents changes quickly. These recommendations are based on current
@@ -55,7 +69,7 @@
 [litellm documentation](https://docs.litellm.ai/docs/providers).

 <Warning>
 OpenHands will issue many prompts to the LLM you configure. Most of these LLMs cost money, so be sure to set spending
 limits and monitor usage.
 </Warning>

@@ -63,7 +77,7 @@

 For local and self-hosted usage, start with
 [Qwen3.6-35B-A3B](https://huggingface.co/Qwen/Qwen3.6-35B-A3B). See the
 [local LLM guide](/openhands/usage/llms/local-llms) for LM Studio, Ollama, SGLang, and vLLM setup examples.

 ### Known Issues

@@ -115,7 +129,7 @@

 LLM providers have specific settings that can be customized to optimize their performance with OpenHands, such as:

 - **Custom Tokenizers**: For specialized models, you can add a suitable tokenizer.
 - **Native Tool Calling**: Toggle native function/tool calling capabilities.

 For detailed information about model customization, see

diff --git a/openhands/usage/llms/local-llms.mdx b/openhands/usage/llms/local-llms.mdx
@@ -1,13 +1,24 @@
 ---
 title: Run Local LLMs with OpenHands
 description: Connect OpenHands to local LLM servers such as LM Studio, Ollama, vLLM, and SGLang.
 ---
 
 Use this guide when you want a local model, rather than a local Agent Canvas backend or local project files. Local LLMs can have limited functionality; use a capable model and GPU-backed server for the best experience.
 
+## Choose What You Mean by Local
+
+| If you want... | Start here |
+|---|---|
+| A model server on your computer or network | Continue with this guide. |
+| Agent Canvas itself to run on your computer | [Install Agent Canvas](/openhands/usage/agent-canvas/setup) |
+| A containerized Agent Canvas backend | [Use Docker with Agent Canvas](/openhands/usage/agent-canvas/backend-setup/docker) |
+| The agent to work with local files | [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) |
+
+For the model ID, base URL, and recovery checks that connect a local server to Agent Canvas, see [Configure a Model](/openhands/usage/agent-canvas/model-configuration).
+
 ## News
 
 - 2026/05/21: We now recommend [Qwen3.6-35B-A3B](https://huggingface.co/Qwen/Qwen3.6-35B-A3B) as the first local model to try with OpenHands. It is an open-weight MoE model built for agentic coding, supports a large context window, and is available through LM Studio, Ollama, vLLM, and SGLang.

 ## Quickstart: Running OpenHands with a Local LLM using LM Studio

@@ -15,12 +26,12 @@

 We recommend:
 - **LM Studio** as the local model server, which handles metadata downloads automatically and offers a simple, user-friendly interface for configuration.
 - **Qwen3.6-35B-A3B** as the LLM for software development. This model is optimized for agentic coding and works well with tool-heavy workflows like OpenHands.

 ### Hardware Requirements

 Running Qwen3.6-35B-A3B requires:
 - A recent GPU with at least 24GB of VRAM for quantized variants, or multiple GPUs for full precision and larger context windows, or
 - A Mac with Apple Silicon with at least 64GB of unified memory for quantized variants

 ### 1. Install LM Studio
@@ -34,7 +45,7 @@

 ![image](./screenshots/01_lm_studio_open_model_hub.png)

 3. Search for **"Qwen3.6-35B-A3B"**, confirm you're downloading from the official Qwen publisher, then proceed to download.

 ![image](./screenshots/02_lm_studio_download_devstral.png)

@@ -52,7 +63,7 @@

 ![image](./screenshots/04_lm_studio_setup_devstral_part_1.png)

 5. Enable the "Show advanced settings" switch at the bottom of the Model settings flyout to show all the available settings.
 6. Set "Context Length" to at least 22000 (for lower VRAM systems) or 32768 (recommended for better performance) and enable Flash Attention.
 7. Click "Load Model" to start loading the model.

@@ -136,21 +147,21 @@

 ## Community-Reported Notes and Troubleshooting

 If OpenHands behaves like a plain chatbot, refuses to use tools or files, or has constant failed tool calls with a local model, the issue may be with the model itself rather than your setup. Even with a large context window, some local models may struggle with reliable tool use.

 **Community-reported working models:**
 - `qwen2.5-coder-14b-instruct` — reported to resolve chatbot-like behavior
 - `qwopus3.5-27b-v3 Q8_0` (and similar retrained qwopus variants) — reported to work well with tool calls

 If you're experiencing issues, try switching to one of these models before assuming the setup is broken.

 ## Advanced: Alternative LLM Backends

 This section describes how to run local LLMs with OpenHands using alternative backends like Ollama, Atomic Chat, SGLang, or vLLM — without relying on LM Studio.

 ### Create an OpenAI-Compatible Endpoint with Ollama

 - Install Ollama following [the official documentation](https://ollama.com/download).
 - Example launch command for Qwen3.6-35B-A3B:

 ```bash
@@ -201,9 +212,9 @@

 - **Connection refused from Docker**: confirm Atomic Chat is running, the local server is enabled, and your `docker run` includes `--add-host host.docker.internal:host-gateway` as in [local setup](/openhands/usage/run-openhands/local-setup).
 - **Wrong model errors**: the Custom Model string must match an `id` returned by `GET /v1/models` after the `openai/` prefix.
 - **Agent ignores tools or acts like a chatbot**: try a stronger coding model or a larger context window; see [Community-Reported Notes and Troubleshooting](#community-reported-notes-and-troubleshooting) on this page.

 ### Create an OpenAI-Compatible Endpoint with vLLM or SGLang

 First, download the model checkpoint:

@@ -211,10 +222,10 @@
 huggingface-cli download Qwen/Qwen3.6-35B-A3B --local-dir Qwen/Qwen3.6-35B-A3B
 ```

 #### Serving the model using SGLang

 - Install SGLang following [the official documentation](https://docs.sglang.io/get_started/install.html).
 - Example launch command (with at least 2 GPUs):

 ```bash
 SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1 python3 -m sglang.launch_server \
@@ -229,7 +240,7 @@
 #### Serving the model using vLLM

 - Install vLLM following [the official documentation](https://docs.vllm.ai/en/latest/getting_started/installation.html).
 - Example launch command (with at least 2 GPUs):

 ```bash
 vllm serve Qwen/Qwen3.6-35B-A3B \
@@ -281,11 +292,11 @@
 2. Enable the **Advanced** toggle at the top of the page.
 3. Set the following parameters, if you followed the examples above:
   - **Custom Model**: `openai/<served-model-name>`
     - For **Ollama**: `openai/qwen3.6:35b-a3b`
     - For **SGLang/vLLM**: `openai/Qwen3.6-35B-A3B`
     - For **Atomic Chat**: `openai/<model-id-from-/v1/models>` (see [Atomic Chat](#create-an-openai-compatible-endpoint-with-atomic-chat) above)
   - **Base URL**: `http://host.docker.internal:<port>/v1`
     Use port `11434` for Ollama, `1337` for Atomic Chat (default), or `8000` for SGLang and vLLM.
   - **API Key**:
     - For **Ollama** or **Atomic Chat**: any placeholder value (e.g. `dummy`, `local-llm`) unless your server requires a real key
     - For **SGLang** or **vLLM**: use the same key provided when starting the server (e.g. `mykey`)
diff --git a/openhands/usage/llms/openrouter.mdx b/openhands/usage/llms/openrouter.mdx
@@ -1,14 +1,32 @@
 ---
-title: OpenRouter
-description: OpenHands uses LiteLLM to make calls to chat models on OpenRouter. You can find their documentation on using OpenRouter as a provider [here](https://docs.litellm.ai/docs/providers/openrouter).
+title: Use OpenRouter with OpenHands
+description: Configure an OpenRouter model and API key in Agent Canvas or OpenHands.
 ---
 
-## Configuration
+Use OpenRouter when you have an OpenRouter API key and want to access a model from its [model catalog](https://openrouter.ai/models).
 
-When running OpenHands, you'll need to set the following in the OpenHands UI through the Settings under the `LLM` tab:
-* `LLM Provider` to `OpenRouter`
-* `LLM Model` to the model you will be using.
-[Visit here to see a full list of OpenRouter models](https://openrouter.ai/models).
-If the model is not in the list, enable `Advanced` options, and enter it in
-`Custom Model` (e.g. openrouter/&lt;model-name&gt; like `openrouter/anthropic/claude-3.5-sonnet`).
-* `API Key` to your OpenRouter API key.
+## Configure Agent Canvas
+
+1. Open `Settings > LLM`.
+2. In the `Basic` tab, select `OpenRouter` as the provider.
+3. Select a model, enter your OpenRouter API key, and save the profile.
+4. Start a new conversation and send a short message to verify the model responds.
+
+If the model is not in the selector, use the `Advanced` tab and enter its model ID with the `openrouter/` prefix. For example, OpenRouter model ID `anthropic/claude-3.5-sonnet` becomes:
+
+```text
+openrouter/anthropic/claude-3.5-sonnet
+```
+
+Copy the current model ID from the [OpenRouter model catalog](https://openrouter.ai/models). Model availability and IDs can change, so do not rely on a previously saved identifier without checking it.
+
+## Fix Common Problems
+
+| Problem | Check | Next step |
+|---|---|---|
+| Model is not found | The exact OpenRouter model ID | Copy the ID from the model catalog and add the `openrouter/` prefix in `Advanced`. |
+| Authentication fails | The API key | Create or copy an active OpenRouter API key, then save the profile again. |
+| The model is unavailable | The selected model in the catalog | Choose an available model or check your OpenRouter account and model access. |
+| The model does not complete agent tasks reliably | Model context and tool-use support | Choose a more capable model that supports the features required for your task. |
+
+For the broader configuration decision and local/proxy recovery paths, see [Configure a Model](/openhands/usage/agent-canvas/model-configuration). For LiteLLM's provider behavior, see [LiteLLM's OpenRouter documentation](https://docs.litellm.ai/docs/providers/openrouter).