> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-automation-docs-1-7-0-release.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage LLM Profiles

> Configure models in Agent Canvas and use saved LLM profiles during conversations.

Agent Canvas supports configuring your LLM provider, model, and credentials from the UI. It also supports saved **LLM profiles**, which make it easier to switch models without re-entering provider settings each time.

## Configure an LLM Profile

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.

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

### Choose a Configuration Path

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

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

For provider and model recommendations, see [LLM Configuration](/openhands/usage/llms/llms).

### OpenHands Provider

Use an OpenHands LLM API key when you want Agent Canvas to access models through the OpenHands provider:

1. Copy your LLM API key from [OpenHands Cloud](https://app.all-hands.dev/settings/api-keys).
2. In the **Basic** tab, select `OpenHands`, choose a model, and add the key.
3. Save the profile and start a new conversation.

For key details and available models, see [OpenHands LLM Provider](/openhands/usage/llms/openhands-llms).

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

For example, if the model server runs on the host at port `1234` and the Agent Canvas backend runs in Docker, configure:

* **Model**: `openai/<served-model-id>`, replacing `<served-model-id>` with the exact `id` returned by the server's `GET /v1/models` endpoint
* **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

In the **Advanced** tab, use the model name format `litellm_proxy/<model-name>`, then enter your LiteLLM proxy base URL and API key. The model name after the prefix must match a model configured on the proxy.

See [LiteLLM Proxy](/openhands/usage/llms/litellm-proxy) for the complete configuration.

## Working with LLM Profiles

LLM profiles are useful when you want different model setups for different tasks, such as:

* a fast profile for iteration
* a stronger profile for planning or review
* a local model profile for offline experiments

LLM profiles are separate from [Agent Profiles](/openhands/usage/agent-canvas/agent-profiles). Agent Profiles choose which agent runs a new conversation. OpenHands Agent Profiles reference an LLM profile to decide which model configuration that agent uses.

### Manage Saved Profiles

The available profiles list shows each profile's name, configured model, and whether it is active. Use a profile's menu to edit or rename it, set it as the active profile for new conversations, or delete it when you no longer need it.

## Switching Profiles in a Conversation

You can switch profiles from the profile selector in the chat input or with the `/model` command:

* `/model` — list the saved profiles available to the conversation
* `/model <profile-name>` — switch to a specific saved profile

A switch preserves the conversation history, workspace, and task state; it applies to future model requests only. Agent Canvas also shows model-switch events in the conversation timeline so you can see when a profile changed during a task.

<Note>
  Model switching requires saved LLM profiles. If `/model` is not available in the chat input, create a profile in `Settings > LLM` and confirm that the active backend supports profile switching.
</Note>

## Fix a Failed Configuration

| Symptom                            | Check first                         | Next step                                                      |
| ---------------------------------- | ----------------------------------- | -------------------------------------------------------------- |
| 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. |

For error-specific steps, see [Troubleshooting](/openhands/usage/agent-canvas/troubleshooting#model-or-api-key-errors).

## Recommended Workflow

1. Configure and save a default profile in `Settings > LLM`.
2. Create additional profiles for specific tasks or cost levels, using descriptive names that make their purpose clear.
3. Open `Settings > Agent` and choose which LLM profile an OpenHands Agent Profile should use.
4. Start a new conversation and send a simple message to confirm the selected model responds.
5. Use the profile selector or `/model` when you want to switch profiles without leaving the chat.

## Related Guides

* [Setup](/openhands/usage/agent-canvas/setup)
* [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings)
* [Agent Profiles](/openhands/usage/agent-canvas/agent-profiles)
* [LLM Settings](/openhands/usage/settings/llm-settings)