Configurar o OpenHands CLI: instalação, API Key e Base URL

Conecte o OpenHands CLI ao BetterToken com variáveis de ambiente. Nos testes em macOS com um modelo GPT, o OpenHands CLI 1.16.0 concluiu solicitações de texto sem interface e chamadas de ferramentas para leitura de arquivos por /v1/responses.

Configurações principais

Campo	Valor
API Key	BetterToken API Key em LLM_API_KEY
Base URL	https://bettertoken.ai/v1 em LLM_BASE_URL
Modelo	openai/YOUR_MODEL_ID em LLM_MODEL
Sobrescrever a configuração	--override-with-envs

Pré-requisitos

• uv e Python 3.12 ou superior
• Uma BetterToken API Key: cadastre-se e obtenha uma
• Um ID de modelo copiado da model plaza

Instalar

Use o nome do pacote e o comando do guia oficial de instalação:

uv tool install openhands --python 3.12
openhands --version

Configuração manual

Substitua YOUR_API_KEY e YOUR_MODEL_ID. Mantenha o prefixo openai/ em LLM_MODEL:

export LLM_MODEL="openai/YOUR_MODEL_ID"
export LLM_API_KEY="YOUR_API_KEY"
export LLM_BASE_URL="https://bettertoken.ai/v1"

Passe --override-with-envs ao iniciar o OpenHands para que essas variáveis substituam as configurações salvas. A substituição vale apenas para essa execução e não salva os valores na configuração.

Verificar a conexão

openhands --headless --json --override-with-envs -t "Reply with only: OK"

Confira se a resposta final na saída JSONL é OK. Para verificar o acesso a arquivos separadamente, execute a partir do projeto e peça que o OpenHands leia um arquivo conhecido; confira tanto o resultado da ferramenta quanto a resposta final.

Trocar de modelo

Altere LLM_MODEL para openai/ seguido de outro ID de modelo exato. Execute novamente com --override-with-envs.

Erros comuns

Sintoma	O que verificar
As configurações de ambiente não são aplicadas	Inclua --override-with-envs no comando.
Falha na autenticação	Confira LLM_API_KEY no terminal que executa o OpenHands.
Endpoint incorreto	Use https://bettertoken.ai/v1 em LLM_BASE_URL, sem /responses nem /chat/completions.
Modelo não encontrado	Mantenha o prefixo openai/ e copie o restante de LLM_MODEL exatamente como aparece na model plaza.

Conteúdo relacionado

• Compare as ferramentas compatíveis
• Erros da API e limites de requisições
• Referência de comandos do OpenHands CLI

Detalhes técnicos

O OpenHands CLI 1.16.0 enviou as solicitações de texto e de leitura de arquivos testadas para /v1/responses. Mantenha a Base URL terminando em /v1; o cliente acrescenta o caminho da solicitação.