Tutorial do agente de programação goose: instalação, fontes de modelos, configuração da API e custos

goose é um agente de código de IA de código aberto (Apache-2.0) que pode ler e editar arquivos e executar comandos no terminal ou no aplicativo para desktop. Para começar, bastam três passos: instalar, escolher uma fonte de modelos (provider) e abrir uma sessão de trabalho para atribuir uma tarefa. Ele é gratuito; o custo vem do modelo conectado.Este tutorial segue a documentação oficial de 1º de outubro de 2026 e explica a instalação, os três caminhos de pagamento, como conectá-lo a um endpoint compatível com OpenAI (incluindo a armadilha mais comum do /v1) e as operações usuais. A versão mais recente é a v1.52.0, publicada em 23 de setembro de 2026.

Primeiro, vamos esclarecer os nomes. Esta página trata do agente de código em goose-docs.ai, cujo repositório está em aaif-goose/goose; originalmente era block/goose e foi transferido em abril de 2026 para a Agentic AI Foundation, ligada à Linux Foundation. Ele não é o goose.ai — esse é outro serviço hospedado de inferência, e seus preços não têm relação com este projeto. O goose atualmente não tem interface em chinês tradicional; os nomes dos menus abaixo permanecem no inglês original.

instalação

A documentação oficial oferece a versão para desktop (goose Desktop) e a versão de linha de comando (goose CLI); ambas leem a mesma configuração.

# goose Desktop(macOS)
brew install --cask block-goose

# goose CLI（macOS / Linux / Windows 的 Git Bash）
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

# 只安裝、先不進入設定
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# 或用 Homebrew 裝 CLI
brew install block-goose-cli

No Windows, você pode baixar a versão para desktop no site oficial; para a CLI, recomenda-se executar o mesmo comando de instalação no Git Bash (PowerShell também funciona). O nome do pacote Homebrew continua sendo block-goose; isso resulta de a alteração de nome não ter sido totalmente propagada para o pacote de instalação e não significa que o projeto ainda esteja sob o controle da Block.

Primeira inicialização: escolha a fonte do modelo

Ao abrir o goose Desktop pela primeira vez, será exibida uma tela de boas-vindas; na CLI, o modo de configuração será iniciado automaticamente (para alterá-lo depois, execute goose configure). A página de instalação lista três opções:

• OpenRouter Login — entre com sua conta OpenRouter para configurar o modelo automaticamente.
• Tetrate Agent Router Service Login — entre com o Tetrate; a documentação informa que a primeira autenticação automática pelo goose oferece $10 de crédito gratuito, tanto para usuários novos quanto antigos.
• Manual Configuration — escolha o provider e preencha a chave manualmente. Para conectar um endpoint compatível com OpenAI, como a Kunavo, siga esta opção.

Três caminhos de pagamento: escolha o correto antes de configurar

A explicação sobre o caminho ACP vem da documentação de providers ACP do goose, que também alerta que o ID da sessão ACP é diferente do ID da sessão do goose e que os campos de telemetria podem não corresponder. Se você já tem uma assinatura e quer apenas economizar nos custos de API, comece por aqui.

Conectando um endpoint compatível com OpenAI: não inclua /v1 na URL do Host

Este é o ponto em que mais pessoas travam. O goose não aceita uma base URL completa; ele a divide em “host” e “caminho”. De acordo com a documentação de providers, OPENAI_HOST é a “URL do endpoint personalizado (api.openai.com por padrão)”, e OPENAI_BASE_PATH é o “caminho da solicitação anexado ao host (o padrão é v1/chat/completions)”. Ao conectar um proxy, defina OPENAI_HOST como “o endereço raiz do proxy (sem caminho)”. Com a Kunavo, por exemplo:

# goose Desktop → Settings → Models → Configure providers → OpenAI
API Key           sk-kn-...
Host URL          https://api.kunavo.com      ← 只寫網域，不加 /v1
Organization ID   （留空）
Project           （留空）

# 或用環境變數（CLI 也讀）
export OPENAI_API_KEY=sk-kn-...
export OPENAI_HOST=https://api.kunavo.com
# OPENAI_BASE_PATH 不要設：預設就是 v1/chat/completions

No goose Desktop, o caminho é Settings → Models → Configure providers → OpenAI; na CLI, goose configure → Configure Providers → OpenAI. Organization ID e Project são usados com contas próprias da OpenAI e podem ficar vazios. Se a URL do Host for https://api.kunavo.com/v1, a solicitação se tornará /v1/v1/chat/completions; a própria documentação diz que “404 geralmente significa que OPENAI_BASE_PATH não está correto para o seu proxy” — o caminho está errado, não a chave. Por outro lado, se aparecer 401 “No api key passed in”, a chave não foi lida, por exemplo porque foi colocada em config.yaml (o goose a ignora).

Outra opção mais limpa é fazer com que ele apareça como um provider separado na lista. O goose lê arquivos JSON de definição na pasta custom_providers; a Kunavo fornece um arquivo gerado a partir da tabela de preços em tempo real, contendo apenas modelos compatíveis com chamadas de ferramentas e apenas o nome da variável da chave, sem a chave em si:

# macOS / Linux:goose 會讀這個資料夾裡所有 JSON
mkdir -p ~/.config/goose/custom_providers
curl -fsSL https://kunavo.com/goose/kunavo.json \
  -o ~/.config/goose/custom_providers/kunavo.json

# 檔案裡只有變數名稱，金鑰另外設定
export KUNAVO_API_KEY=sk-kn-...
goose session start --provider kunavo

No Windows, a pasta é %APPDATA%\Block\goose\config\custom_providers\. Depois de colocar o arquivo ali, Configure providers no goose Desktop exibirá Kunavo; a chave pode ser armazenada no chaveiro do sistema, em vez de uma variável de ambiente. De acordo com o código-fonte do goose, os IDs de modelos que começam com gpt-5 ou gpt-6 usam /v1/responses; os demais usam /v1/chat/completions. A Kunavo oferece ambos. Também é possível criar manualmente: Configure providers → Add Custom Provider, escolha o tipo OpenAI Compatible e preencha a URL da API com https://api.kunavo.com/v1. A página de configuração completa em inglês está no guia de integração do goose.

Explicação honesta: as configurações acima foram compiladas a partir da documentação e do código-fonte do goose; a Kunavo não executou o goose de fato em seu próprio endpoint — não houve execução de sessão, streaming ou ida e volta de ferramentas. Mantenha o caminho que já funciona para você e primeiro teste com uma pequena tarefa que leia e grave arquivos.

Operações comuns

• Abrir uma sessão:goose session (você pode nomeá-la com -n 名稱); depois, retome-a com goose session --resume -n 名稱; goose session list lista o histórico.
• Alternar o modo de autorização: na sessão, digite /mode para escolher auto, approve, chat ou smart_approve. Para que ele peça sua confirmação antes de cada etapa, use approve.
• Escolher o modelo:goose configure não aceita nomes de modelos personalizados; para IDs que não aparecem na lista, insira-os no goose Desktop ou defina GOOSE_MODEL em config.yaml.
• Arquivo de instruções do projeto: por padrão, o goose lê .goosehints e AGENTS.md (controlado por CONTEXT_FILE_NAMES). Escreva ali as regras do projeto para que elas também possam ser levadas ao mudar para outro agente.
• Não escolha modelos sem suporte a chamadas de ferramentas: a documentação diz que esses modelos “só podem fazer preenchimento de conversa”, e as extensões também precisam ser desativadas.

Quanto custa aproximadamente uma sessão de trabalho

A seguir está uma aritmética de tokens para fins ilustrativos, não o custo real de uma tarefa nem um limite de cobrança. Suponha que uma sessão de trabalho de agente envie, no total entre várias rodadas, 400.000 tokens de entrada não armazenados em cache e receba 25.000 tokens de saída (o agente reenvia o contexto a cada rodada, por isso a entrada é especialmente grande). Os preços unitários vêm dos preços atuais por milhão de tokens na tabela de preços da Kunavo.

Sobre o cache: a documentação do goose diz que, ao usar Claude pelos providers Anthropic, Amazon Bedrock, Databricks, OpenRouter e LiteLLM, ele adiciona automaticamente marcadores cache_control da Anthropic. Claude usado pelo provider OpenAI genérico não está nessa lista, então o goose não adiciona esses marcadores; por isso, a tabela acima presume que não há desconto de cache, uma estimativa conservadora. Os valores da tabela de preços da Kunavo são pisos de cobrança, não tetos: quando o upstream informa um custo, a cobrança usa o maior valor entre o “valor da tabela de preços” e “custo do upstream × margem aplicável”.

Pagamentos em Taiwan

A Kunavo é pré-paga, com cobrança por token e sem mensalidade. A recarga mínima é de $10; o checkout é processado pelo Stripe, e em Taiwan estão disponíveis cartões de crédito (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay e Link; JkoPay e LINE Pay não estão na lista de métodos disponíveis. Consulte os detalhes de cobrança; quando estiver pronto, você poderá criar uma conta e gerar uma chave. Para comparar outros gateways, consulte em inglês goose alternatives e goose vs Claude Code.

Perguntas frequentes

Verificado em 1º de outubro de 2026: documentação de instalação, providers, providers ACP, comandos da CLI e variáveis de ambiente do goose (branch main de aaif-goose/goose), além da versão e do status de arquivamento pela API do GitHub. A Kunavo não executou o goose de fato em seu próprio endpoint; os preços vêm da tabela em tempo real, e os exemplos monetários são apenas aritmética ilustrativa de tokens.