> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure a Model

> 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)