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

O goose é um assistente de IA de uso geral que funciona no seu computador. Além de código, também pode fazer pesquisas, escrever, automatizar tarefas e organizar dados. Pode utilizá-lo através da aplicação para ambiente de trabalho, do terminal ou de uma interface, sendo que as versões para ambiente de trabalho e terminal partilham a mesma configuração de modelos. É adequado para tarefas de programação repetitivas e também pode ligar-se ao GitHub, a bases de dados e a ficheiros.

Preparação antes da instalação

O goose disponibiliza duas formas de instalação: Desktop e CLI. Desktop é a versão para ambiente de trabalho com uma janela, enquanto CLI é a versão utilizada através da introdução de comandos no terminal. Ambas partilham a configuração principal, incluindo o Provider e os modelos. Um Provider pode ser entendido como a configuração de ligação que indica ao goose qual o serviço de modelos que deve utilizar.

Se quiser uma janela

goose Desktop

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

Se só precisar do terminal

goose CLI

download_cli.sh
Ou Homebrew CLI
Depois, execute goose session

Windows

Escolha primeiro o ambiente

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

No macOS, pode utilizar uma transferência direta ou o Homebrew. No Linux, a versão para ambiente de trabalho utiliza o pacote da distribuição. No Windows, verifique primeiro os ambientes de terminal indicados.

Antes de começar, prepare o ID do modelo apresentado na lista de modelos atual. O ID do modelo é o nome utilizado pelo serviço para identificar um modelo específico e deve ser copiado integralmente.

Instalar e iniciar pela primeira vez

Se pretender uma janela

No macOS, existem duas formas de instalação:

Transferir a partir da página de instalação. A página disponibiliza versões para macOS Silicon e macOS Intel. Depois da transferência, extraia o ficheiro zip e execute a aplicação incluída.
Em alternativa, utilize o Homebrew:

brew install --cask block-goose

Este comando transfere a mesma aplicação e também pode tratar das atualizações.

Se estiver a utilizar um Apple Mac M3 e não aparecer nenhuma janela depois de abrir a aplicação, verifique se ~/.config tem permissões de leitura e escrita. O goose utiliza este diretório para escrever registos.

No Linux, transfira a versão para ambiente de trabalho a partir da página de instalação. Estão disponíveis DEB (Ubuntu/Debian), RPM (RHEL/Fedora) e Flatpak. No Debian ou Ubuntu, os passos são: transferir o DEB, abrir o diretório onde foi guardado, executar sudo dpkg -i (filename).deb e, em seguida, abrir o goose através do menu de aplicações. Substitua (filename) pelo nome real do ficheiro.

No Windows, transfira a versão para ambiente de trabalho a partir da página de instalação, extraia o ficheiro zip e execute a aplicação incluída.

Se pretender apenas o terminal

No macOS e Linux, execute:

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

Se não pretender efetuar 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, também pode executar:

brew install block-goose-cli

Para atualizar uma CLI já instalada, utilize:

goose update

No Windows, é necessário utilizar um dos seguintes três ambientes: Git Bash (incluído no Git for Windows e assinalado como recomendado), MSYS2 ou o PowerShell incluído no Windows 10/11. No Git Bash e MSYS2, utilize o mesmo download_cli.sh indicado acima. No PowerShell, transfira primeiro o script e depois execute-o:

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

Se receber uma indicação de que o goose não se encontra no PATH, siga a página de instalação para adicionar ~/.local/bin ou %USERPROFILE%\.local\bin à configuração da shell atual e volte a abrir o terminal. O PATH é um conjunto de diretórios onde o terminal procura programas. Se o diretório não tiver sido adicionado, poderá não conseguir executar diretamente o programa pelo nome, mesmo que já esteja instalado.

Em 2026-10-09, a versão da CLI era a 1.54.0. Por predefinição, o script de instalação coloca o programa em ~/.local/bin. Pode alterar este diretório através da variável de ambiente GOOSE_BIN_DIR. Depois da alteração, o script não adiciona automaticamente o diretório à configuração da shell e o terminal indicará que este não se encontra no PATH. Adicione esse diretório ao PATH ou execute o programa utilizando o caminho completo.

Na primeira utilização, o goose solicitará a configuração de um Provider. Pode ignorar inicialmente os fornecedores incluídos e adicionar um Provider personalizado de acordo com a secção seguinte. No terminal, abra o diretório onde pretende trabalhar e execute:

goose session

Obter os parâmetros de ligação do OmniProxy

Prepare o endereço, a chave e o nome do modelo a partir da sua própria instância do OmniProxy. O exemplo de Provider personalizado utiliza um base_url que termina em /v1/chat/completions, pelo que será utilizado o mesmo formato:

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   copie a partir da lista atual de modelos do OmniProxy; separe vários modelos com vírgulas inglesas

Copie integralmente o nome do modelo a partir da lista atual do OmniProxy, incluindo quaisquer barras. Em 2026-10-09, os dois IDs de referência na documentação dos fornecedores eram grok-4.7, da Grok, e gpt-6-luna, apresentado na documentação da OpenAI. O gpt-6-luna suporta Chat Completions; nas Chat Completions, a chamada de funções apenas é suportada quando reasoning_effort está definido como none. Não copie nomes que não estejam presentes na lista.

Preencher a configuração da ferramenta

Um Provider personalizado utiliza um formato compatível com OpenAI, Anthropic ou Ollama. Um formato compatível significa que a ferramenta envia pedidos de acordo com uma interface comum. Ao ligar ao OmniProxy, selecione OpenAI Compatible.

Versão para ambiente de trabalho

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, pode introduzir OmniProxy. Em API URL, introduza o endereço indicado na secção anterior. Se for necessária uma chave, assinale a opção que exige uma API Key e introduza a chave do OmniProxy. Em Available Models, introduza os nomes dos modelos, separados por vírgulas inglesas quando existir mais do que um.
Clique em Create Provider.

Atualmente, a versão para ambiente de trabalho não permite definir cabeçalhos de pedido personalizados nesta janela. Se precisar de cabeçalhos, altere o ficheiro 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 e siga as indicações para preencher o nome, API URL, necessidade de uma chave, nomes dos modelos e suporte de respostas em streaming.

Ao configurar manualmente no Windows, se ocorrer um erro no porta-chaves, selecione a opção para não guardar no keyring quando lhe for perguntado e utilize uma variável de ambiente. Em seguida, volte a executar goose configure. O porta-chaves é um pequeno armazenamento seguro utilizado pelo sistema para guardar chaves.

Ficheiro de configuração

Os diretórios indicados são:

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

Pode criar o ficheiro com base no exemplo apresentado. Substitua o nome, o endereço e os modelos pelos seus valores. Guarde a chave na variável de ambiente indicada por api_key_env; não escreva a chave real no ficheiro:

{
  "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
}

Mantenha um valor numérico em context_limit, como no exemplo. O contexto real depende do modelo e do OmniProxy; não considere o número do exemplo como o limite oficial desse modelo. Antes da utilização, execute:

export OMNIPROXY_API_KEY="<YOUR_OMNIPROXY_API_KEY>"

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

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

Substitua o valor de --model pelo ID completo apresentado na lista. goose session não tem um subcomando start. Também pode definir --provider e --model através das variáveis de ambiente GOOSE_PROVIDER e GOOSE_MODEL. Mesmo que o gateway não valide a chave, OMNIPROXY_API_KEY tem de conter um valor, que pode ser uma sequência de caracteres de preenchimento utilizada apenas localmente. Em 2026-10-09, esta configuração permitiu ler o ficheiro.

Janela

Settings

Settings na barra lateral
Página Models
Add Custom Provider

Terminal

goose configure

Selecione Custom Providers
Depois, selecione adicionar
Escolha OpenAI Compatible como tipo

Ficheiro

custom_providers

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

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

Verificar com uma tarefa real

Abra um diretório que contenha um ficheiro comum e execute o goose session indicado na secção anterior. Peça-lhe para ler a primeira linha do ficheiro que especificar. A resposta deve apresentar o conteúdo do ficheiro, e não apenas indicar que a configuração foi guardada.

Para ler ficheiros 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 trabalhar com ficheiros e comandos locais. Normalmente, a configuração predefinida já a inclui. Se o goose responder que não dispõe de ferramentas para ficheiros, adicione ao comando:

--with-builtin developer

Não adicione simultaneamente --no-profile, porque esse parâmetro desativa as extensões predefinidas.

Em 2026-10-09, o goose 1.54.0 leu a primeira linha do ficheiro especificado. A primeira resposta pode demorar cerca de um minuto.

Em seguida, confirme a origem e o nome do modelo no registo de chamadas do OmniProxy.

Arranque

É possível iniciar uma sessão

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

Tarefa

Executou realmente a tarefa

Por exemplo, listar o diretório atual
Veja a resposta apresentada
Não se limite a confirmar que foi guardado

Registo

Visível no gateway

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

Depois de guardar o Provider, confirme a configuração através de 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 volte a abrir o terminal.
A versão para ambiente de trabalho não apresenta uma janela num M3: verifique as permissões de leitura e escrita de ~/.config.
Falha no porta-chaves: não guarde a chave no keyring; utilize antes uma variável de ambiente.
O modelo não está na lista: na versão para ambiente de trabalho, pode selecionar Use custom model e introduzir manualmente o nome do modelo. O goose configure não permite introduzir nomes de modelos personalizados; no terminal, utilize a versão para ambiente de trabalho ou altere diretamente GOOSE_MODEL na configuração.
Não é possível ligar ao endereço: confirme que o API URL termina em /v1/chat/completions, tal como no exemplo, e que o OmniProxy está em execução.
O goose indica que não consegue ler ficheiros: adicione a extensão Developer e não utilize --no-profile.
É devolvido unsupported Responses role: system: normalmente, o endereço está correto. Experimente outro ID completo da lista de modelos.

Referências oficiais

Para a instalação, consulte Install goose. Para configurar um Provider personalizado, consulte goose providers. Os IDs de modelos utilizados nos exemplos podem ser consultados na página de modelos da xAI e em GPT-6 Luna.

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

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

Fontes oficiais · goose ↗