- A instância local do Ollama não possui chave de API. O servidor em
http://localhost:11434aceita todas as solicitações sem autenticação, por design. - Se um cliente compatível com OpenAI exigir uma chave, insira qualquer sequência não vazia —
ollamaé a convenção adotada. Ela nunca é verificada. - Uma chave de API real do Ollama existe apenas para o Ollama Cloud, criada na sua conta ollama.com e enviada como um token
Bearer. - Para proteger uma instância local, configure um proxy reverso com autenticação à frente dela. Nunca exponha diretamente a porta 11434 à internet.
Uma instalação local do Ollama não possui chave de API nem forma integrada de defini-la. O servidor HTTP que ele executa em http://localhost:11434 responde a qualquer solicitação que o alcance. As pessoas que procuram uma "chave de API do Ollama" normalmente precisam de uma das três coisas: algo para inserir no campo obrigatório de chave de um aplicativo cliente, uma maneira de proteger uma instância acessível por outras máquinas ou uma chave para o serviço em nuvem hospedado do Ollama — o único local onde uma chave real existe. Este guia aborda os três casos.
Por que o Ollama local é distribuído sem autenticação
Por padrão, o Ollama vincula-se ao endereço de loopback 127.0.0.1 na porta 11434. Apenas processos na mesma máquina podem se conectar, portanto uma chave de API acrescentaria complexidade sem aumentar a segurança: qualquer programa local capaz de ler um arquivo de chave poderia chamar a API diretamente com igual facilidade. Trata-se do mesmo modelo de confiança adotado pela maioria dos servidores locais de desenvolvimento.
A consequência: não há OLLAMA_API_KEY variável, sem nenhuma flag de chave nem opção de senha em qualquer parte da configuração. No momento em que este texto foi escrito, o servidor local do Ollama não possui nenhum mecanismo de autenticação embutido — proteger uma instância acessível pela rede é responsabilidade sua, conforme explicado abaixo. Se você ainda estiver configurando o ambiente, comece com nosso Guia de instalação do Ollama ou o mais abrangente Guia completo do Ollama.
O que inserir no campo de chave de API de clientes compatíveis com OpenAI
Ollama expõe endpoints compatíveis com a API da OpenAI em /v1, razão pela qual interfaces gráficas de chat, assistentes de programação e os SDKs oficiais da OpenAI conseguem se comunicar com ele. Esses SDKs se recusam a criar um cliente sem uma chave de API não vazia — essa verificação ocorre no lado do cliente, antes mesmo de qualquer requisição ser enviada. O Ollama, por sua vez, ignora completamente o cabeçalho Authorization , de modo que qualquer string funciona. A convenção adotada é ollama.
| Configuração | Valor para Ollama local |
|---|---|
| URL base | http://localhost:11434/v1 |
| Chave de API | Qualquer string não vazia, por exemplo: ollama |
| Modelo | Uma tag que você já baixou, por exemplo: llama3.2 |
Python, usando o SDK oficial da OpenAI:
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:11434/v1",
api_key="ollama", # exigido pelo SDK, ignorado pelo Ollama
)
response = client.chat.completions.create(
model="llama3.2",
messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)JavaScript / TypeScript:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "http://localhost:11434/v1",
apiKey: "ollama",
});
const response = await client.chat.completions.create({
model: "llama3.2",
messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);O modelo deve já ter sido baixado (ollama pull llama3.2) ou a requisição falhará com um erro de modelo não encontrado. Se você não tiver certeza do que executar, confira nossas recomendações para os melhores modelos locais para Ollama.
Adicionando autenticação real com um proxy reverso
Como o Ollama não consegue verificar chaves por si só, o padrão usual consiste em manter o Ollama vinculado ao loopback padrão e colocar um proxy reverso à frente dele. Esse proxy encerra o TLS, verifica um token e encaminha apenas as requisições válidas para 127.0.0.1:11434. Uma configuração mínima do nginx que exige um token Bearer:
server {
listen 443 ssl;
server_name ollama.example.com;
# linhas ssl_certificate e ssl_certificate_key omitidas
location / {
if ($http_authorization != "Bearer YOUR-LONG-RANDOM-TOKEN") {
return 401;
}
proxy_pass http://127.0.0.1:11434;
proxy_set_header Host $host;
proxy_read_timeout 600s;
}
}Dois detalhes merecem atenção. Gere o token usando algo como openssl rand -hex 32 em vez de inventá-lo manualmente. E o longo valor de proxy_read_timeout é intencional: gerações em streaming podem durar vários minutos, e os tempos limite padrão dos proxies interromperiam essas respostas no meio.
A parte elegante: os SDKs da OpenAI já enviam a chave no formato Authorization: Bearer <chave>. Aponte seu cliente para https://ollama.example.com/v1, defina a chave de API como o token real, e o campo de chave anteriormente ignorado passa a funcionar como autenticação genuína, sem necessidade de alterações no lado do cliente. O Caddy e o Traefik também conseguem impor essa mesma verificação de cabeçalho ou autenticação HTTP básica com poucas linhas em suas próprias configurações; se você já utiliza um desses, prefira-o em vez de adicionar o nginx.
Alterando o endereço em que o Ollama escuta: Windows, macOS, Linux
Um proxy na mesma máquina não exige nenhuma alteração no Ollama. Contudo, se outras máquinas precisarem acessar o Ollama diretamente — seja um proxy em outro host, contêineres Docker ou clientes da LAN — configure OLLAMA_HOST=0.0.0.0 para que ele escute em todas as interfaces. A forma de definir isso varia conforme a plataforma.
Windows
Saia do Ollama através da bandeja do sistema. Abra as Configurações, pesquise por "variáveis de ambiente" e selecione "Editar variáveis de ambiente para sua conta". Adicione uma variável chamada OLLAMA_HOST com o valor 0.0.0.0, salve as alterações e reinicie o Ollama.
macOS
Versões recentes do Ollama para desktop incluem um interruptor nas configurações do aplicativo para expô-lo na rede — verifique primeiro as configurações do aplicativo. Em instalações mais antigas, execute launchctl setenv OLLAMA_HOST "0.0.0.0" e reinicie o aplicativo Ollama.
Linux
Para o serviço systemd instalado pelo script oficial, execute sudo systemctl edit ollama.service e adicione:
[Service]
Environment="OLLAMA_HOST=0.0.0.0"Em seguida, execute sudo systemctl daemon-reload && sudo systemctl restart ollama.
Uma advertência antes de ativar essa opção: 0.0.0.0 em uma máquina com endereço IP público transforma sua GPU em um serviço público. Configure seu firewall para liberar a porta 11434 apenas para os hosts que realmente precisam acessá-la.
Ollama Cloud: onde uma chave de API real é aplicável
O Ollama Cloud executa modelos muito grandes para a maioria dos hardwares locais, utilizando GPUs próprias do datacenter da Ollama, sendo a única parte do ecossistema que oferece chaves de API genuínas. Há duas formas de acessá-lo.
Pelo CLI local. Executar ollama signin para conectar sua conta do ollama.com e, em seguida, execute modelos hospedados na nuvem usando suas tags específicas para a nuvem — no momento da redação deste texto, por exemplo, ollama run gpt-oss:120b-cloud. As requisições ficam vinculadas à sua conta; não há necessidade de gerenciamento manual de chaves.
Diretamente via HTTPS. Crie uma chave de API na seção "Chaves de API" das configurações da sua conta no ollama.com e envie-a como um token Bearer. A API hospedada espelha a API local, com https://ollama.com como URL base, em vez de localhost:11434:
curl https://ollama.com/api/chat
-H "Authorization: Bearer $OLLAMA_API_KEY"
-d '{
"model": "gpt-oss:120b",
"messages": [{"role": "user", "content": "Hello"}],
"stream": false
}'A lista de modelos disponíveis na nuvem, seus endpoints e os limites dos planos mudam ao longo do tempo; portanto, consulte sempre a documentação oficial da nuvem Ollama para obter informações atualizadas sobre nomes de modelos e cotas. Ao decidir se a inferência hospedada ou o hardware local é mais adequado para sua carga de trabalho, nosso calculadora de ponto de equilíbrio entre autohospedagem e API fornece dados quantitativos, e o Calculadora de VRAM informa se um determinado modelo cabe, de fato, na sua GPU.
O perigo real: uma instância sem autenticação exposta à internet
A verdadeira questão de segurança em torno da chave de API do Ollama não é a string de espaço reservado no seu script Python — é a existência de milhares de servidores Ollama que varreduras na internet encontram rotineiramente escutando na porta 11434 sem qualquer autenticação. Qualquer pessoa que encontrar o seu servidor pode executar inferência gratuitamente na sua GPU, enumerar seus modelos por meio de /api/tags, baixar modelos até que seu disco fique cheio ou excluí-los. Além disso, qualquer vulnerabilidade futura no servidor torna-se explorável sem credenciais: a CVE-2024-37032, uma falha de execução remota de código corrigida em 2024, é um precedente nesse sentido.
- Mantenha o valor padrão
127.0.0.1de bind, a menos que algo realmente exija acesso remoto. - Para acesso remoto pessoal, prefira um túnel SSH (
ssh -N -L 11434:127.0.0.1:11434 usuario@servidor) ou uma VPN como WireGuard ou Tailscale, em vez de abrir a porta diretamente. - Se for indispensável deixá-lo acessível publicamente, coloque-o atrás de um proxy reverso com autenticação e terminação TLS, conforme ilustrado acima.
- Mantenha o Ollama atualizado para garantir que vulnerabilidades conhecidas permaneçam corrigidas.
Perguntas frequentes
O Ollama exige uma chave de API?
Não. Um servidor Ollama local não possui autenticação nem opção para habilitá-la. As únicas chaves de API reais do Ollama são as do Ollama Cloud, geradas na sua conta em ollama.com.
O que devo digitar no campo obrigatório de chave de API de um cliente?
Qualquer string não vazia — ollama por convenção. Esse requisito é puramente imposto pelo cliente; o Ollama descarta esse cabeçalho. Caso você tenha configurado um proxy reverso com autenticação na frente do Ollama, insira o token real desse proxy, pois clientes no estilo OpenAI enviam a chave como um token de portador (bearer token), que o proxy pode verificar.
Posso fazer com que o próprio Ollama exija uma chave de API?
Não, até a data desta redação. Não há variável de ambiente, sinalizador ou opção de configuração que habilite autenticação no servidor local, apesar de solicitações contínuas dos usuários nesse sentido. A solução aceita é colocar um proxy reverso na frente do servidor.
Como obtenho uma chave de API do Ollama Cloud?
Crie uma conta em ollama.com e gere uma chave na seção "Chaves de API" das configurações da sua conta. Envie-a como Authorization: Bearer <chave> nas requisições para https://ollama.com. Para uso via linha de comando, o comando ollama signin vincula sua máquina à sua conta sem necessidade de manipulação manual da chave.
Por que o SDK do OpenAI lança um erro de autenticação antes mesmo de enviar qualquer dado?
O SDK valida a presença de uma chave de API no momento em que o cliente é instanciado; assim, uma chave vazia ou ausente falha localmente, mesmo que o Ollama não a verifique. Defina api_key="ollama" (ou qualquer outra string) e certifique-se de que a URL base termine em /v1.
É seguro expor o Ollama em minha rede doméstica?
Em uma LAN doméstica confiável protegida por NAT, expor o Ollama com OLLAMA_HOST=0.0.0.0 é uma configuração comum e razoável. Verifique se seu roteador não está redirecionando a porta 11434 para essa máquina e lembre-se de que todos os dispositivos conectados à rede — incluindo os celulares de visitantes — poderão então usar e gerenciar seus modelos.
