docs: improve model configuration guidance - #783
Conversation
Co-authored-by: openhands <openhands@all-hands.dev>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
| 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). |
There was a problem hiding this comment.
Not a big deal perhaps, just to note: my impression is that “everyone knows” AgentSkills, and it feels likely a better term than the syntagm “reusable task instructions” - but I’m OK with this too 😅
| | 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. | |
There was a problem hiding this comment.
We may be happier when this goes back to a single what-to-do, and that is Provider Connection.
| ### 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. |
There was a problem hiding this comment.
This is very interesting to me: I have used for ~several months a behavior where you could either
- reuse the existing API key for that provider (more raw but the same behavior with Provider Connections)
- or, check a box to say “nah I want to override for this profile”, and then enter a profile-specific key.
It has been necessary to have that override so that I can use two accounts from the same provider. But fast forward to today in OpenHands, if more than one Provider Connections can be made for a provider, e.g. openai_personal and openai_work, then the old way with a key in the profile can be cleaned out. WDYT?
There was a problem hiding this comment.
I don't quite follow @enyst . Or maybe I do...now that I'm typing this out. Are you suggesting we remove the API key field unless they opt-in by checking a box to fill in an API key? I think thats what I'm visualizing.
Separately I think this is in a sort of in-between state of doneness. Provider connection THEN LLM profiles is the intuitive step but its not super clear easy flow yet.
| --- | ||
|
|
||
| ## Configuration | ||
| Use OpenRouter when you have an OpenRouter API key and want to access a model from its [model catalog](https://openrouter.ai/models). Use a direct provider profile when you already have credentials for that provider, a local endpoint for a model server you run, or a LiteLLM proxy when your organization provides one. |
There was a problem hiding this comment.
| Use OpenRouter when you have an OpenRouter API key and want to access a model from its [model catalog](https://openrouter.ai/models). Use a direct provider profile when you already have credentials for that provider, a local endpoint for a model server you run, or a LiteLLM proxy when your organization provides one. | |
| Use OpenRouter when you have an OpenRouter API key and want to access a model from its [model catalog](https://openrouter.ai/models). |
No strong feelings about it, but if you are on OpenRouter page, I wonder, is it necessary?
Co-authored-by: Engel Nyst <engel.nyst@gmail.com>
2 participants
Summary
Implements the provider-configuration priorities from #782.
Validation
docs.jsonas JSON.git diff --check.Closes #782
This pull request was created by an AI agent (OpenHands) on behalf of the user.