Conecte um LLM local ou uma IA personalizada ao seu navegador com o SurfMind

O SurfMind não prende você a um único conjunto de modelos. Você pode conectá-lo a um modelo rodando na sua própria máquina (Ollama, LM Studio, Jan, llama.cpp, vLLM) ou para quase qualquer provedor de IA externo que suporte a API de completion da OpenAI — Poe, z.ai, Together, Groq, DeepSeek, AWS Bedrock e dezenas de outros.

A maioria dos provedores populares e dos runners locais já vem configurada nas configurações do SurfMind: você clica em Connect e cola sua API key. Para qualquer outro, o formulário Custom Providers / API permite que você mesmo adicione o endpoint.

O problema: quando não funciona na primeira tentativa, pode ser por causa de um pequeno erro de configuração. A mensagem de erro que aparece ("connection failed", "401", "404", "model not found") nem sempre é fácil de interpretar.

Este post é um guia rápido para verificar a configuração e resolver problemas por conta própria. Passe os olhos pelo checklist e confirme sua configuração. Se ainda assim não funcionar, mande um e-mail para wave@surfmind.ai.

Procurando um provedor específico? Confira nossa lista: modelos locais (Ollama, LM Studio, OpenWebUI, Jan…) ou provedores de IA (Poe, z.ai, Together, Groq, AWS…).

O checklist de 60 segundos

Antes de mais nada, passe por estes pontos. A maioria dos problemas de configuração se resume a um deles:

1. O servidor está realmente rodando? Para modelos locais, o runner (Ollama, LM Studio, etc.) precisa estar iniciado e ter um modelo carregado.
2. A porta está certa? A do Ollama é 11434. A do LM Studio é 1234. Elas não são intercambiáveis, e este é o erro mais comum de todos.
3. O caminho (path) está certo? O caminho nativo do Ollama é /api/chat. Quase todo o resto é /v1/chat/completions. Trocar um pelo outro gera um erro.
4. O protocolo está certo — http ou https? Modelos locais em localhost usam http:// (sem o s). Provedores de nuvem usam https://. Inverter isso faz parecer que a conexão está fora do ar.
5. Você colou o endpoint completo, não só a base? O campo API URL do SurfMind quer a URL completa terminando em /chat/completions (ou /api/chat para o Ollama), e não apenas https://api.provider.com/v1.
6. A API key (e o formato dela) está correta? Runners locais geralmente não precisam de key. Provedores externos precisam de Authentication definido como API Key, do formato Authorization: Bearer e da sua key real.
7. Para modelos locais no navegador: o CORS está liberado? Esta é a etapa extra que só as configurações locais precisam (OLLAMA_ORIGINS, ou "Enable CORS" no LM Studio).

Se mesmo assim você continuar travado, continue lendo — cada um desses pontos tem detalhes que podem passar despercebidos.

Como conectar um provedor

São só alguns cliques a partir do seletor de modelos:

Passo 1. Clique no nome do modelo na parte inferior do painel do SurfMind para abrir seus Favoritos e, em seguida, clique em Show all.

Passo 2. No topo da lista de modelos, clique em Add model provider. Isso abre a página Models nas configurações do SurfMind.

Passo 3. Encontre seu provedor. Runners locais (Ollama, LM Studio, vLLM, llama.cpp, Open WebUI) ficam em Self-hosted. Provedores de nuvem (OpenAI, Anthropic, Google, OpenRouter, Groq, DeepSeek, Mistral, Poe, z.ai, Together, AWS Bedrock e outros) ficam em Providers. Use a caixa de busca se a lista for longa e então clique em Connect.

Passo 4. Para um provedor de nuvem, cole sua API key e clique em Connect. A janela traz um link para a página onde você pode obter uma key. Para um runner self-hosted, o formulário abre com as URLs locais já preenchidas, então basta salvar (o Open WebUI também precisa da sua key).

Depois de conectado, os modelos do provedor aparecem no seletor de modelos. Expanda a linha do provedor para escolher quais devem aparecer.

Não encontrou seu provedor? Adicione-o como provedor personalizado

Se o seu provedor ou runner não estiver na lista (Jan, LocalAI, o gateway da sua empresa ou um provedor que ainda não adicionamos), clique em Custom Providers / API no topo da página Models.

O formulário "Custom Model API" é aberto, e você mesmo informa o endpoint.

O restante deste guia trata principalmente deste formulário, porque é nele que os erros de configuração acontecem.

O que vai em cada campo

Quando você clica em Custom Providers / API, surge o formulário "Custom Model API". Veja exatamente o que cada campo espera:

As duas coisas que as pessoas mais erram são o API URL (base vs. endpoint completo) e o API Key Format (qual cabeçalho). O restante deste guia se aprofunda nesses dois.

Erro #1: o caminho do API URL (a armadilha /api/chat vs /v1/chat/completions)

Este é o grande erro, e vale a pena entender por que ele acontece.

Aqui existem dois formatos de API diferentes:

• A API nativa do Ollama, que usa http://localhost:11434/api/chat.
• A API de completion da OpenAI, que usa .../v1/chat/completions. É o que LM Studio, vLLM, Jan, Poe, z.ai, Together, Groq — basicamente todos os outros — falam.

Então, se você copia um guia de configuração escrito para o LM Studio e tenta usar aquele caminho com o Ollama (ou vice-versa), vai receber um 404 mesmo com o servidor rodando perfeitamente. O servidor está no ar; você só está batendo na porta errada.

Bom saber: o Ollama aceita os dois formatos de API. A entrada Ollama em Self-hosted no SurfMind usa o caminho nativo /api/chat, que é a rota mais simples e oferece descoberta automática de modelos. Você só precisa do caminho /v1/chat/completions do Ollama se alguma ferramenta exigir especificamente o formato OpenAI. Para o SurfMind, basta clicar em Connect na linha do Ollama.

Erro #2: o número da porta

Cada runner local escolhe sua própria porta padrão, e elas são parecidas o suficiente para você errar a digitação:

11434 vs 1234 é a confusão clássica — são fáceis de confundir num relance, mas um dígito errado e nada conecta. Se você mesmo alterou a porta (ex.: rodou o vLLM com --port 9000), use a sua porta, não a padrão.

Um teste rápido: abra no navegador o endereço do servidor com a porta. Visitar http://localhost:11434 deve mostrar a mensagem "Ollama is running" do Ollama. Se a página não carregar nada, o servidor não está no ar ou você está com a porta errada.

Erro #3: colar a URL base em vez do endpoint

A documentação dos provedores quase sempre te dá uma URL base — algo como https://api.poe.com/v1. Isso acontece porque os exemplos de código deles usam o SDK da OpenAI, que adiciona o /chat/completions automaticamente.

O campo API URL do SurfMind não faz isso por você. Ele espera o endpoint completo. Então você precisa adicionar o caminho você mesmo:

• URL base da documentação: https://api.poe.com/v1
• O que você cola no SurfMind: https://api.poe.com/v1/chat/completions

A mesma ideia vale para o campo Models URL (usado para listar automaticamente os modelos disponíveis): pegue a base e adicione /models → https://api.poe.com/v1/models.

Dois deslizes relacionados:

• /v1 duplicado. Se a base já termina em /v1, não adicione outro. .../v1/v1/chat/completions dá 404.
• Barras no final. .../chat/completions/ com barra no final pode falhar em alguns servidores. Remova-a.

Erro #4: incompatibilidade entre http e https

O esquema no início da URL importa, e trocá-lo produz uma "connection failed" que parece que o servidor está fora do ar quando não está.

• Modelos locais são http. Ollama, LM Studio, Jan, llama.cpp — qualquer coisa em localhost — serve http:// puro. Digitar https://localhost:11434 falha, porque não há certificado TLS em um servidor local. Se você copiou um trecho com https na frente de localhost, remova o s.
• Provedores de nuvem são https. Poe, z.ai, Together, Groq e os demais só aceitam https://. Enviar http:// para eles é recusado ou redirecionado silenciosamente.

Também é preciso considerar a segurança do navegador: páginas servidas por https bloqueiam requisições para endpoints http puros ("mixed content"). O SurfMind trata http://localhost como uma exceção confiável, então modelos locais funcionam — mas um IP de LAN puro como http://192.168.1.50:11434 ainda pode ser bloqueado. Se você estiver apontando para outra máquina na sua rede, prefira https, ou sirva o modelo por trás de um proxy https local.

Regra prática: http para localhost, https para tudo na internet pública.

Erro #5: o Models URL não combina com o API URL

O Models URL é opcional. É o endpoint que o SurfMind chama para buscar a lista de modelos que um provedor oferece, para poder exibi-los em um dropdown em vez de fazer você digitar nomes. Se seus modelos não aparecerem no seletor depois de salvar, este campo costuma ser o culpado. Ele precisa usar o mesmo formato de API do endpoint de chat:

Um erro comum é misturá-los — usar /api/tags com um provedor compatível com OpenAI, ou /v1/models com o /api/chat nativo do Ollama. Se você conectou pela linha Ollama em Self-hosted, isto é preenchido corretamente para você; deixe como está.

Quando deixar em branco: alguns provedores não expõem um endpoint público de listagem de modelos, ou o bloqueiam. Tudo bem — deixe o Models URL vazio e simplesmente digite o model id exato no campo de modelo você mesmo (veja o Erro #8). O chat ainda vai funcionar; você só não terá o dropdown preenchido automaticamente.

Erro #6: o formato da API key (Bearer vs x-api-key)

No formulário personalizado, Authentication e API Key Format decidem como sua key é anexada à requisição. Escolha o errado e você receberá um 401 Unauthorized mesmo com uma key perfeitamente válida. As opções:

Então o campo API Key recebe apenas a key em si:

• Não digite a palavra Bearer — o SurfMind a adiciona quando você escolhe Authorization: Bearer.
• Não deixe um espaço no final (uma causa surpreendentemente comum de 401s).
• Para modelos locais, escolha No authentication. (O LM Studio é a exceção — ele quer algum valor não vazio; a própria documentação dele usa lm-studio.)

Em dúvida sobre qual formato um provedor usa: 99% dos provedores compatíveis com OpenAI usam Authorization: Bearer. Só recorra a x-api-key se a documentação do provedor mostrar explicitamente um cabeçalho x-api-key. Ainda recebendo um 401? Gere a key novamente, confira o formato e confirme que não há espaço extra.

Erro #7: CORS — a pegadinha exclusiva dos locais

Os navegadores se recusam a chamar um servidor local a menos que esse servidor permita explicitamente requisições da extensão. Isso atrapalha especificamente as configurações locais (provedores externos já permitem).

• Ollama: inicie-o com o acesso pelo navegador habilitado:

  # Mac/Linux
  OLLAMA_ORIGINS="*" ollama serve
  
  # Windows (PowerShell)
  $env:OLLAMA_ORIGINS="*"; ollama serve

  "port 11434 already in use"? O app em segundo plano do Ollama já está rodando. Encerre-o primeiro (barra de menus no Mac, bandeja do sistema no Windows) e então execute o comando acima.

• LM Studio: na aba Developer / servidor local, ative o Enable CORS antes de iniciar o servidor.

Mais uma sutileza: se localhost não conectar, tente 127.0.0.1 (ou o contrário). Em alguns sistemas eles não são resolvidos da mesma forma.

Erro #8: o nome do modelo precisa bater exatamente

Uma vez conectado, o nome do modelo que você seleciona precisa bater com o que o provedor espera — exatamente, incluindo maiúsculas e minúsculas. Isso pega as pessoas em provedores que não listam modelos automaticamente, ou que usam nomenclaturas incomuns:

• Poe usa os nomes dos bots exibidos na plataforma, como Claude-Sonnet-4.6 e GPT-5.4 — copie-os exatamente como aparecem no Poe.
• z.ai usa ids como glm-4.6 e glm-5.
• Together AI usa ids com namespace: meta-llama/Llama-3.3-70B-Instruct-Turbo, deepseek-ai/DeepSeek-V3.
• Fireworks usa um id de caminho completo: accounts/fireworks/models/llama-v3p3-70b-instruct.

Se a conexão funciona mas você recebe "model not found", quase sempre é um erro de digitação no nome ou maiúsculas/minúsculas erradas. Quando o SurfMind consegue listar modelos automaticamente via Models URL, escolha da lista em vez de digitar.

Referência rápida: modelos locais

Todos estes rodam na sua própria máquina. Ollama, LM Studio, vLLM, llama.cpp e Open WebUI já estão listados em Self-hosted na página Models: clique em Connect e as URLs abaixo são preenchidas para você. Para o Jan e o LocalAI, clique em Custom Providers / API, cole as URLs e defina Authentication como No authentication. Se você mudou a porta de um runner, ajuste a URL de acordo. Os nomes dos provedores levam à documentação de configuração de cada ferramenta.

Ollama

• API URL: http://localhost:11434/api/chat
• Models URL: http://localhost:11434/api/tags
• API key: nenhuma

LM Studio

• API URL: http://localhost:1234/v1/chat/completions
• Models URL: http://localhost:1234/v1/models
• API key: qualquer valor não vazio (ex.: lm-studio)

Jan

• API URL: http://localhost:1337/v1/chat/completions
• Models URL: http://localhost:1337/v1/models
• API key: nenhuma (ou sua key do Jan)

llama.cpp

• API URL: http://localhost:8080/v1/chat/completions
• Models URL: http://localhost:8080/v1/models
• API key: nenhuma (a menos que você o tenha iniciado com --api-key)

vLLM

• API URL: http://localhost:8000/v1/chat/completions
• Models URL: http://localhost:8000/v1/models
• API key: sua --api-key se você definiu uma

LocalAI

• API URL: http://localhost:8080/v1/chat/completions
• Models URL: http://localhost:8080/v1/models
• API key: nenhuma

OpenWebUI: a exceção à regra do "sem key". O OpenWebUI exige uma API key, e os caminhos dele são /api/..., não /v1/.... Conecte-o pela lista Self-hosted e cole sua key sk-…, gerada em Settings → Account → API keys. Use http://localhost:3000 numa instalação típica via Docker, ou o endereço do seu servidor se ele rodar em outra máquina.

• API URL: http://localhost:3000/api/chat/completions
• Models URL: http://localhost:3000/api/models
• API key: sua key do OpenWebUI (sk-…)

A configuração completa e a solução de problemas estão no nosso guia da OpenWebUI API.

Não esqueça da etapa de CORS (Erro #7) para qualquer um destes. Para o Ollama especificamente, o passo a passo completo com capturas de tela está no nosso guia do Ollama, e se você estiver decidindo entre os dois primeiros, veja Ollama vs LM Studio.

Referência rápida: provedores de IA populares

Todos os provedores abaixo já estão listados em Providers na página Models: clique em Connect e cole sua key — as URLs são preenchidas para você. Eles estão listados aqui como referência, ou caso você prefira adicionar algum manualmente com Custom Providers / API (defina Authentication como API Key com o formato Authorization: Bearer). Os nomes dos provedores levam à documentação da API de cada provedor.

Poe — uma única key para centenas de modelos (Claude, GPT, Gemini, Llama…), com o uso descontado dos pontos da sua assinatura do Poe. Os nomes dos modelos são os nomes dos bots exibidos na plataforma — copie-os exatamente como mostrados no Poe (ex.: Claude-Sonnet-4.6, GPT-5.4). Key em poe.com → Settings → API key.

• API URL: https://api.poe.com/v1/chat/completions
• Models URL: https://api.poe.com/v1/models

CanopyWave — provedor de nuvem com GPU que serve modelos abertos (Kimi, DeepSeek, Llama, Qwen). Key no dashboard da CanopyWave.

• API URL: https://inference.canopywave.io/v1/chat/completions
• Models URL: https://inference.canopywave.io/v1/models

z.ai (GLM) — os modelos GLM da Zhipu (glm-4.6, glm-5). Atenção: a z.ai também publica um endpoint separado de Coding Plan (https://api.z.ai/api/coding/paas/v4) e um endpoint de PaaS (https://api.z.ai/api/paas/v4) — use o compatível com OpenAI abaixo e não adicione um /v1 extra.

• API URL: https://api.z.ai/api/openai/v1/chat/completions
• Models URL: https://api.z.ai/api/openai/v1/models

Together AI — grande catálogo de modelos abertos. Os model ids são longos (meta-llama/Llama-3.3-70B-Instruct-Turbo) — copie-os exatamente da página de modelos da Together.

• API URL: https://api.together.xyz/v1/chat/completions
• Models URL: https://api.together.xyz/v1/models

Groq — inferência extremamente rápida. Pegadinha: o caminho é /openai/v1, não apenas /v1.

• API URL: https://api.groq.com/openai/v1/chat/completions
• Models URL: https://api.groq.com/openai/v1/models

DeepSeek — os modelos atuais são deepseek-v4-flash e deepseek-v4-pro (os aliases mais antigos deepseek-chat / deepseek-reasoner estão sendo descontinuados — confira a documentação da DeepSeek para os mais recentes). O /v1 é opcional; a DeepSeek aceita a URL com ou sem ele.

• API URL: https://api.deepseek.com/v1/chat/completions
• Models URL: https://api.deepseek.com/v1/models

Mistral — mistral-large-latest, mistral-small-latest, etc. Compatível com OpenAI padrão.

• API URL: https://api.mistral.ai/v1/chat/completions
• Models URL: https://api.mistral.ai/v1/models

Fireworks AI — pegadinha: o caminho é /inference/v1, não /v1. Os model ids têm a forma accounts/fireworks/models/llama-v3p3-70b-instruct.

• API URL: https://api.fireworks.ai/inference/v1/chat/completions
• Models URL: https://api.fireworks.ai/inference/v1/models

xAI (Grok) — modelos Grok (grok-4, etc.). Compatível com OpenAI padrão.

• API URL: https://api.x.ai/v1/chat/completions
• Models URL: https://api.x.ai/v1/models

AWS Bedrock — o Bedrock agora tem um endpoint compatível com OpenAI, mas com duas pegadinhas: o host é específico de região (ex.: us-west-2) e o caminho é /openai/v1. Você precisa usar uma Bedrock API key (um bearer token que você gera no console) — não suas chaves de acesso normais da AWS/SigV4. Os model ids têm a forma openai.gpt-oss-120b-1:0. Ao conectar o Bedrock pela lista Providers, escolha sua região no dropdown e o SurfMind monta a URL para você.

• API URL: https://bedrock-runtime.<region>.amazonaws.com/openai/v1/chat/completions
• Models URL: deixe em branco — informe o model id depois

Ainda não conecta? Últimas verificações

Percorra esta lista:

1. Confira primeiro a página Models. Se o seu provedor estiver listado, conecte-o por lá em vez de criar uma entrada personalizada.
2. Abra o host do API URL no seu navegador. Servidor local não carregando → ele não está rodando, ou a porta está errada.
3. Releia o caminho. Ollama → /api/chat. Todos os outros → /v1/chat/completions (ou o caminho especial do provedor, da tabela).
4. Confirme que você colou o endpoint completo, não a base, e que não há /v1 duplicado ou barra no final.
5. 401? É a key ou o formato dela. Formato = Authorization: Bearer, key sem espaços, sem prefixo Bearer.
6. 404 "model not found"? A conexão está ok — corrija o nome do modelo (maiúsculas/minúsculas exatas).
7. Modelo local, navegador bloqueado? Habilite o CORS (OLLAMA_ORIGINS="*" ou o toggle do LM Studio) e tente 127.0.0.1 vs localhost.

Esses passos resolvem a grande maioria dos problemas de configuração.

Ainda precisa de ajuda?

Se você já passou pelo checklist e seu provedor ainda não conecta, mande um e-mail para wave@surfmind.ai com o provedor que você está tentando e o erro que aparece. Vamos ajudar você a conectar.

---

Conseguiu conectar? Abra o SurfMind na próxima página que você ia ler e coloque seu modelo para trabalhar.

Obter o SurfMind →