OpenHands

Settings → LLM → Advanced recebe três campos — Custom Model, Base URL, API Key — com o ID do modelo contendo um prefixo openai/ e a URL base mantendo seu /v1.

# Settings → LLM → Advanced  (toggle "Advanced" on first)
Custom Model   openai/claude-sonnet-5
Base URL       https://api.kunavo.com/v1
API Key        sk-kn-...

# The "openai/" prefix is the provider, not a vendor: it tells OpenHands to
# speak the OpenAI Chat Completions protocol to the Base URL above. The model
# id after the slash is Kunavo's, and resolves at Kunavo.
#
# Keep the /v1. It belongs to the openai/ prefix — a litellm_proxy/ model
# takes the bare origin instead, which is the opposite convention.

Passo a passo

1. Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
2. Abra Configurações → LLM e ative a opção Advanced. Os três campos aparecem nesta ordem: Custom Model, Base URL, API Key.
3. Digite o ID do modelo com o prefixo — openai/claude-sonnet-5, não claude-sonnet-5. Os IDs oferecidos pela Kunavo são os retornados por GET /v1/models, a mesma lista que a documentação do próprio OpenHands orienta a usar para escolher um ID personalizado.
4. Cole https://api.kunavo.com/v1 em Base URL e sua chave em API Key; em seguida, clique em Save Changes. O OpenHands documenta que, ao salvar um perfil local, a configuração é validada primeiro no backend e o salvamento é bloqueado se houver falha; portanto, um erro aqui é uma rejeição real, não apenas visual.
5. Verifique o que o backend consegue acessar, não o que seu navegador consegue. A URL base precisa ser resolvida pela máquina que executa o Agent Server — a documentação deixa claro que, se o Agent Canvas estiver no Docker, 127.0.0.1 é o contêiner. Um endpoint público como o da Kunavo é o caso simples; um proxy corporativo na frente dele não é.
6. Inicie uma nova conversa e dê a ela uma tarefa que leia e edite um arquivo. O OpenHands observa que uma LLM salva se aplica a conversas novas e que as antigas precisam ser reiniciadas primeiro; além disso, uma execução que usa as ferramentas revela mais sobre essa combinação do que uma saudação.

Verificado em Página de configurações de modelos de linguagem (LLM) do OpenHands em 21 de setembro de 2026. As configurações de terceiros podem mudar; se o nome de um campo aqui já não corresponder ao que você vê, aquela página é a autoridade, não esta.

Verifique antes de depurar o cliente

Uma solicitação determina se a falha está no endpoint, na chave ou no arquivo de configuração. Se isto retornar JSON, a mesma URL base e a mesma chave funcionarão em OpenHands.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Qual ID de modelo inserir no campo

Todo modelo de texto pode ser acessado como um ID de modelo — a lista atual está em GET /v1/models, e o catálogo com preços está na página de modelos. As tarifas são em USD por 1 milhão de tokens, entrada / saída.

Três limites que vale conhecer antes de investigar um problema

O OpenHands tem mais componentes do que uma CLI de processo único, e dois deles se parecem com o endpoint LLM sem serem o endpoint. Estas informações vêm da documentação do próprio OpenHands, consultada na data acima:

1. O sandbox não é o modelo. O OpenHands executa seu trabalho em um sandbox do Agent Server e chama o modelo pela rede; são interfaces distintas, com credenciais distintas. Uma chave configurada aqui permite fazer chamadas ao modelo. Ela não determina o que o sandbox consegue acessar, e um problema de rede no sandbox não se manifesta como erro de autenticação.
2. Os agentes ACP são completamente separados. O Agent Canvas pode delegar para Claude Code, Codex ou Gemini CLI como agente ACP, e a página Configure a Model afirma que eles “gerenciam o próprio acesso ao modelo” — portanto, um perfil LLM não redireciona esse subprocesso. Se você esperava ver tráfego usando sua chave e não vê nenhum, confira qual agente está realmente em execução. A comparação entre OpenHands e Claude Code explica essa diferença, incluindo a regra de prioridade de credenciais que a determina.
3. Perfis e o limite de 10 perfis. Uma configuração salva se torna um perfil LLM, o perfil salvo mais recentemente fica ativo para novas conversas e é possível alternar entre perfis durante uma conversa sem perder o contexto — mecanismo que permite usar um ID econômico e um ID caro com uma só chave. A documentação limita a 10 perfis por conta. Uma conexão de provedor armazena o provedor, a chave de API e uma URL base opcional uma única vez para vários perfis; a mesma página observa que esse painel está disponível em backends locais do Agent Server e oculto em um backend do OpenHands Cloud.