diff --git a/docs.json b/docs.json index b1a47439..c9fba5db 100644 --- 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 index 1ef20ca2..905fb98e 100644 --- a/openhands/usage/agent-canvas/first-time-setup.mdx +++ b/openhands/usage/agent-canvas/first-time-setup.mdx @@ -89,6 +89,16 @@ Each item links directly to the relevant page. The checklist tracks your progres Toggle the checklist from `Settings > Application` using the **Show getting started checklist** switch. The setting persists across sessions. +## 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 index beed1581..22259f27 100644 --- a/openhands/usage/agent-canvas/llm-profiles.mdx +++ b/openhands/usage/agent-canvas/llm-profiles.mdx @@ -11,6 +11,8 @@ LLM profiles can also generate conversation titles. In `Settings > Application > 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). + 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. @@ -19,14 +21,14 @@ ACP agents such as Claude Code, Codex, and Gemini CLI manage their own model acc | 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). @@ -78,7 +80,7 @@ See [LiteLLM Proxy](/openhands/usage/llms/litellm-proxy) for the complete config Provider Connections are available on **local agent-server backends only**. The panel is hidden when using an OpenHands Cloud backend. -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 @@ The provider field in the **create** connection flow is a searchable selector ba ### 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 diff --git a/openhands/usage/agent-canvas/model-configuration.mdx b/openhands/usage/agent-canvas/model-configuration.mdx new file mode 100644 index 00000000..9bfb975a --- /dev/null +++ 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. + + +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. + + +## 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. + + +Provider Connections are available on local agent-server backends. The panel is hidden when using an OpenHands Cloud backend. + + +## 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/` 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:/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/` 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 `` 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 index e6b64afd..8e69cb3b 100644 --- a/openhands/usage/agent-canvas/overview.mdx +++ b/openhands/usage/agent-canvas/overview.mdx @@ -85,7 +85,19 @@ Agent Canvas supports several model access patterns: - **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 diff --git a/openhands/usage/agent-canvas/troubleshooting.mdx b/openhands/usage/agent-canvas/troubleshooting.mdx index 05a8b314..ee91bd3a 100644 --- a/openhands/usage/agent-canvas/troubleshooting.mdx +++ b/openhands/usage/agent-canvas/troubleshooting.mdx @@ -235,7 +235,7 @@ 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: diff --git a/openhands/usage/llms/llms.mdx b/openhands/usage/llms/llms.mdx index b2270bb4..b3f2a5aa 100644 --- a/openhands/usage/llms/llms.mdx +++ b/openhands/usage/llms/llms.mdx @@ -13,6 +13,20 @@ page focuses on how the OpenHands interfaces surface those capabilities. When in for the canonical list of supported parameters. +## 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 diff --git a/openhands/usage/llms/local-llms.mdx b/openhands/usage/llms/local-llms.mdx index 3ed72a0a..c7fe80bd 100644 --- a/openhands/usage/llms/local-llms.mdx +++ b/openhands/usage/llms/local-llms.mdx @@ -5,6 +5,17 @@ description: Connect OpenHands to local LLM servers such as LM Studio, Ollama, v 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. diff --git a/openhands/usage/llms/openrouter.mdx b/openhands/usage/llms/openrouter.mdx index 2b5f2fa8..d5e2d343 100644 --- 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/<model-name> 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).