Instalação do goose e configuração de Provider personalizado

O goose é um assistente de IA de uso geral executado no seu computador. Além de código, ele também pode fazer pesquisas, escrever, automatizar tarefas e organizar dados. Você pode usá-lo pelo aplicativo para desktop, pelo terminal ou por uma interface, e as versões para desktop e terminal compartilham a mesma configuração de modelos. Ele é adequado para trabalhos repetitivos de programação e também pode se conectar ao GitHub, a bancos de dados e a arquivos.

Preparação antes da instalação

O goose oferece duas formas de instalação: Desktop e CLI. Desktop é a versão com interface gráfica, enquanto CLI é a versão usada por meio de comandos no terminal. As duas compartilham as configurações principais, incluindo o Provider e o modelo. Um Provider pode ser entendido como a configuração de conexão que informa ao goose qual serviço de modelos deve ser usado.

Se você quer uma interface

goose Desktop

Baixe o zip no macOS
Ou use brew cask
No Linux, use o pacote de instalação

Se você só quer o terminal

goose CLI

download_cli.sh
Ou Homebrew CLI
Depois, execute goose session

Windows

Primeiro, escolha o ambiente

Git Bash ou MSYS2
Também é possível usar PowerShell
Se o comando não for encontrado, adicione-o ao PATH

No macOS, você pode baixar o aplicativo ou usar o Homebrew. No Linux, a versão para desktop usa o pacote da distribuição. No Windows, verifique primeiro os ambientes de terminal indicados.

Antes de começar, prepare o ID do modelo disponível na lista atual de modelos. O ID do modelo é o nome usado pelo serviço para identificar um modelo específico e deve ser copiado por inteiro.

Instalação e primeira inicialização

Se você quer uma interface gráfica

No macOS, há duas formas de instalação:

Baixe pela página de instalação. A página oferece versões para macOS Silicon e macOS Intel. Depois do download, extraia o arquivo zip e execute o aplicativo.
Ou use o Homebrew:

brew install --cask block-goose

Esse comando baixa o mesmo aplicativo e também pode cuidar das atualizações.

Se estiver usando um Apple Mac M3 e nenhuma janela aparecer depois de abrir o aplicativo, verifique se ~/.config tem permissões de leitura e gravação. O goose usa esse diretório para gravar logs.

No Linux, baixe a versão para desktop pela página de instalação. Estão disponíveis DEB (Ubuntu/Debian), RPM (RHEL/Fedora) e Flatpak. No Debian ou Ubuntu, siga estas etapas: baixe o DEB, acesse o diretório onde ele foi salvo, execute sudo dpkg -i (filename).deb e abra o goose pelo menu de aplicativos. Substitua (filename) pelo nome real do arquivo.

No Windows, baixe a versão para desktop pela página de instalação, extraia o arquivo zip e execute o programa contido nele.

Se você quer apenas o terminal

No macOS e no Linux, execute:

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

Se não quiser fazer a configuração interativa durante a instalação, adicione CONFIGURE=false antes de bash:

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

No macOS, você também pode executar:

brew install block-goose-cli

Para atualizar uma CLI já instalada, use:

goose update

No Windows, é necessário usar um destes três ambientes: Git Bash, incluído no Git for Windows e marcado como recomendado; MSYS2; ou o PowerShell incluído no Windows 10/11. No Git Bash e no MSYS2, use o mesmo comando download_cli.sh mostrado acima. No PowerShell, baixe primeiro o script e depois o execute:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"
.\download_cli.ps1

Se aparecer um aviso de que o goose não está no PATH, siga a página de instalação para adicionar ~/.local/bin ou %USERPROFILE%\.local\bin à configuração do shell atual e depois reabra o terminal. PATH é o conjunto de diretórios em que o terminal procura programas. Se o diretório não estiver incluído, talvez não seja possível executar diretamente o programa pelo nome, mesmo que ele já esteja instalado.

Em 2026-10-09, a versão da CLI era a 1.54.0. Por padrão, o script de instalação coloca o programa em ~/.local/bin. A variável de ambiente GOOSE_BIN_DIR permite alterar esse diretório. Depois da alteração, o script não grava automaticamente o novo diretório na configuração do shell, e o terminal avisa que ele não está no PATH. Adicione esse diretório ao PATH ou execute o programa usando o caminho completo.

No primeiro uso, o goose solicitará a configuração de um Provider. Você pode ignorar inicialmente os provedores integrados e adicionar um Provider personalizado conforme a próxima seção. No terminal, acesse o diretório em que deseja trabalhar e execute:

goose session

Obtenha os parâmetros de conexão no OmniProxy

Prepare o endereço, a chave e o nome do modelo no seu próprio OmniProxy. O exemplo de Provider personalizado usa base_url terminando em /v1/chat/completions, portanto este guia segue o mesmo formato:

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   Copie da lista atual de modelos do OmniProxy; se houver vários, separe-os com vírgulas comuns

Copie o nome completo do modelo da lista atual do OmniProxy, preservando também as barras. Em 2026-10-09, dois IDs usados para comparação na documentação dos fornecedores eram grok-4.7, do Grok, e gpt-6-luna, da documentação da OpenAI. O gpt-6-luna aceita Chat Completions; em Chat Completions, chamadas de função só são aceitas quando reasoning_effort é none. Não copie nomes que não estejam na lista.

Preencha a configuração da ferramenta

Um Provider personalizado usa um formato compatível com OpenAI, Anthropic ou Ollama. Um formato compatível significa que a ferramenta envia solicitações seguindo uma interface comum. Ao conectar ao OmniProxy, selecione OpenAI Compatible.

Versão para desktop

Clique no botão no canto superior esquerdo para abrir a barra lateral.
Clique em Settings.
Clique em Models.
Clique em Configure providers.
Clique em Add Custom Provider na parte inferior da janela.
Em Provider Type, selecione OpenAI Compatible. Em Display Name, você pode inserir OmniProxy. Em API URL, informe o endereço da seção anterior. Quando uma chave for necessária, marque a opção que exige uma API Key e informe a chave do OmniProxy. Em Available Models, informe os nomes dos modelos, separados por vírgulas comuns quando houver mais de um.
Clique em Create Provider.

Atualmente, a versão para desktop não permite definir cabeçalhos de solicitação personalizados nessa janela. Se precisar de cabeçalhos, altere o arquivo de configuração depois de criar o Provider.

Terminal

Execute:

goose configure

Selecione Custom Providers e depois Add A Custom Provider. Em API Type, selecione OpenAI Compatible. Em seguida, siga as instruções para informar o nome, a API URL, se uma chave é necessária, os nomes dos modelos e se há suporte a respostas em streaming.

Ao fazer a configuração manual no Windows, se ocorrer um erro no chaveiro do sistema, selecione a opção de não armazenar a chave no keyring quando isso for perguntado e use uma variável de ambiente. Depois, execute goose configure novamente. O chaveiro é um pequeno armazenamento seguro do sistema usado para guardar chaves.

Arquivo de configuração

Os diretórios indicados são:

macOS e Linux: ~/.config/goose/custom_providers/
Windows: %APPDATA%\Block\goose\config\custom_providers\

Você pode criar o arquivo com base no exemplo abaixo. Substitua o nome, o endereço e os modelos pelos seus. Armazene a chave na variável de ambiente indicada por api_key_env; não grave a chave real no arquivo:

{
  "name": "omniproxy",
  "engine": "openai",
  "display_name": "OmniProxy",
  "api_key_env": "OMNIPROXY_API_KEY",
  "base_url": "https://your-omniproxy-origin.example/v1/chat/completions",
  "models": [
    { "name": "grok-4.7", "context_limit": 128000 },
    { "name": "gpt-6-luna", "context_limit": 128000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

Em context_limit, mantenha um número como no exemplo. O contexto real depende do modelo e do OmniProxy; não considere o número do exemplo como o limite oficial do modelo. Antes de usar, execute:

export OMNIPROXY_API_KEY="<YOUR_OMNIPROXY_API_KEY>"

Depois de acessar o diretório de trabalho, execute:

goose session --provider omniproxy --model grok-4.7

Substitua o valor de --model pelo ID completo disponível na lista. goose session não tem um subcomando start. --provider e --model também podem ser definidos pelas variáveis de ambiente GOOSE_PROVIDER e GOOSE_MODEL. Mesmo quando o gateway não valida a chave, OMNIPROXY_API_KEY precisa ter algum valor, que pode ser uma sequência de caracteres usada apenas como placeholder local. Em 2026-10-09, essa configuração conseguiu ler o arquivo.

Interface

Settings

Settings na barra lateral
Página Models
Add Custom Provider

Terminal

goose configure

Selecione Custom Providers
Depois, selecione a opção para adicionar
Escolha o tipo OpenAI Compatible

Arquivo

custom_providers

No macOS e Linux, fica em ~/.config
No Windows, fica em APPDATA
Defina base_url conforme o exemplo oficial

As três opções gravam o mesmo tipo de configuração. Selecione OpenAI Compatible como tipo de Provider.

Verifique com uma tarefa real

Acesse um diretório que contenha um arquivo comum e execute o goose session da seção anterior. Peça que ele leia a primeira linha de um arquivo específico. Ele deve retornar o conteúdo do arquivo, em vez de apenas informar que a configuração foi salva.

Para ler arquivos ou executar comandos, a sessão precisa da extensão Developer. A extensão Developer pode ser entendida como o módulo de ferramentas que permite ao goose processar arquivos e comandos locais. A configuração padrão normalmente já a inclui. Se ele responder que não tem ferramentas para arquivos, adicione ao comando:

--with-builtin developer

Não adicione --no-profile ao mesmo tempo, pois esse parâmetro desativa as extensões padrão.

Em 2026-10-09, o goose 1.54.0 conseguiu ler a primeira linha do arquivo especificado. A primeira resposta pode levar cerca de um minuto.

Depois, confira nos registros de chamadas do OmniProxy a origem e o nome do modelo.

Inicialização

É possível iniciar uma sessão

goose session
O Provider é o que acabou de ser adicionado
O nome do modelo aparece na lista

Tarefa

Ele realmente executou a tarefa

Por exemplo, listar o diretório atual
Confira a resposta
Não verifique apenas se foi salvo

Registros

Visível no gateway

Use o endereço do exemplo da documentação
Não coloque a chave no repositório
O ID do modelo corresponde ao da lista

Depois de salvar o Provider, confirme a configuração usando uma sessão real.

Erros comuns

Comando goose não encontrado: adicione o diretório de instalação ao PATH conforme indicado na página de instalação e reabra o terminal.
Nenhuma janela aparece na versão para desktop em um M3: verifique as permissões de leitura e gravação de ~/.config.
Falha no chaveiro: não armazene a chave no keyring; use uma variável de ambiente.
O modelo não aparece na lista: na versão para desktop, selecione Use custom model para inserir manualmente o nome do modelo. O goose configure não permite inserir um nome de modelo personalizado; no terminal, use a versão para desktop ou altere diretamente GOOSE_MODEL na configuração.
Não é possível acessar o endereço: confirme se a API URL termina em /v1/chat/completions, como no exemplo, e se o OmniProxy está em execução.
Ele informa que não consegue ler arquivos: adicione a extensão Developer e não use --no-profile.
Retorno unsupported Responses role: system: normalmente, o endereço está correto. Use outro ID completo disponível na lista de modelos.

Referências oficiais

Para a instalação, consulte Install goose. Para Providers personalizados, consulte goose providers. Os IDs de modelo usados nos exemplos estão na página de modelos da xAI e em GPT-6 Luna.

Substitua todos os espaços reservados por valores de sua própria configuração do OmniProxy. Nunca publique uma chave real.

Um resultado salvo ou HTTP 200 sozinho não prova compatibilidade total com o Agente. Verifique a origem e o modelo no registro de chamadas do OmniProxy.

Fontes oficiais · goose ↗