Instalação do Aider e configuração do OmniProxy

O Aider é uma ferramenta que ajuda a alterar código a partir do terminal. Cria um mapa de todo o código para ajudar o modelo a compreender projetos maiores; o Git é uma ferramenta de controlo de versões que regista as alterações ao código e pode ser utilizada para consultar diferenças e reverter alterações. Depois de atribuir uma tarefa ao Aider, este trata-a por etapas e escreve uma mensagem de commit. Se não gostar das alterações, pode anulá-las com /undo.

Preparação antes da instalação

Existem dois métodos de instalação habituais:

• Se já tiver o Python 3.8 a 3.13 no computador: instale primeiro o aider-install. O Python é o ambiente necessário para executar o Aider.
• Se não tiver uma versão adequada do Python: utilize o comando de instalação numa só linha, que também prepara o Python 3.12 quando necessário.

Mac e Linux

install.sh

• Execute com sh após curl
• Instala Python se necessário
• Se não tiver curl, pode usar wget

Windows

install.ps1

• Execute no PowerShell
• Volte a abrir o terminal após a instalação
• Defina as variáveis de ambiente com setx

Python já instalado

aider-install

• Primeiro, instale este pacote com pip
• Depois, execute aider-install
• O próprio cria o ambiente

Certifique-se de que o OmniProxy está em execução. Após concluir a instalação, entre primeiro no diretório do projeto que pretende alterar e, em seguida, inicie o Aider.

Instalar e iniciar pela primeira vez

Se já tiver o Python 3.8 a 3.13

Execute, por esta ordem:

python -m pip install aider-install
aider-install

O aider-install instala o Aider num ambiente Python separado, evitando conflitos com outros projetos Python existentes no computador. Quando necessário, também instala uma versão do Python 3.12 para utilização pelo Aider.

Instalação numa só linha

No Mac e Linux, execute:

curl -LsSf https://aider.chat/install.sh | sh

Se o computador não tiver o curl, pode utilizar:

wget -qO- https://aider.chat/install.sh | sh

No Windows PowerShell, execute:

powershell -ExecutionPolicy ByPass -c "irm https://aider.chat/install.ps1 | iex"

Estes comandos de uma só linha baseiam-se no uv; o uv é um programa utilizado para instalar e gerir ferramentas e ambientes Python. Também pode utilizar o seguinte comando:

uv tool install --force --python python3.12 --with pip aider-chat@latest

Também é possível utilizar o pipx. Ao instalar diretamente através de python -m pip install aider-chat, as versões do Python suportadas são da 3.9 à 3.12, mas este é um método de instalação alternativo; dê prioridade aos métodos anteriores. As versões do Aider disponíveis nos gestores de pacotes do sistema podem ter dependências incompatíveis, pelo que não devem ser a primeira opção de instalação.

Em 2026-10-09, o comando de instalação numa só linha instalou o Aider v0.86.2. Se, durante a instalação, surgir um aviso a indicar que a cache e o destino não estão no mesmo disco e que os ficheiros serão copiados, a instalação será concluída na mesma.

Após a instalação, entre no diretório do projeto. Uma interface compatível é uma interface que utiliza o formato OpenAI para comunicar com outros serviços de modelos. O formato do comando de arranque é:

aider --model openai/<model-name>

Substitua <model-name> pelo ID completo do modelo copiado do OmniProxy na secção seguinte; o ID do modelo é o nome utilizado para identificar o modelo com precisão.

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

É necessário definir as duas variáveis de ambiente seguintes. As variáveis de ambiente podem ser entendidas como um conjunto de definições de ligação lidas pelos programas executados no terminal:

export OPENAI_API_BASE=https://your-omniproxy-origin.example/v1
export OPENAI_API_KEY=<YOUR_OMNIPROXY_API_KEY>

OPENAI_API_BASE é o endereço da interface e tem de terminar em /v1. OPENAI_API_KEY é a chave utilizada para aceder à interface.

No Windows, utilize setx para guardar as variáveis. Depois de executar os comandos, é necessário voltar a abrir o terminal:

setx OPENAI_API_BASE https://your-omniproxy-origin.example/v1
setx OPENAI_API_KEY <YOUR_OMNIPROXY_API_KEY>

Copie o nome completo do modelo a partir da lista atual do OmniProxy, mantendo também as barras existentes no ID do modelo. Ao iniciar o Aider, acrescente openai/ antes do ID completo.

Em 2026-10-09, os dois IDs de referência apresentados na documentação dos fornecedores eram gemini-3.8-flash e grok-4.7. Se estes nomes não aparecerem na lista atual, não os copie diretamente; utilize um ID completo que exista realmente na lista.

Endereço

OPENAI_API_BASE

• Aponte para o OmniProxy
• Termine em /v1
• Não o guarde no repositório

Chave

OPENAI_API_KEY

• Use a que recebeu do gateway
• No Windows, volte a abrir o terminal após a alteração
• Mantenha a chave do fornecedor no gateway

Arranque

openai/modelo

• Use cd para ir para o diretório do projeto
• Adicione openai/ ao nome do modelo
• Use o nome indicado na lista do gateway

Preencher a configuração da ferramenta

Não é necessário criar outro ficheiro de configuração. Entre primeiro no diretório do projeto, inicie o Aider e substitua o ID do modelo por um nome que exista realmente na lista atual do OmniProxy:

cd /path/to/your/project
aider --model openai/gemini-3.8-flash

Para utilizar o outro modelo de exemplo, execute:

aider --model openai/grok-4.7

Quando o Aider encontra um modelo que não reconhece, a interface apresenta um aviso. Esse aviso, por si só, não significa que o endereço esteja incorreto; verifique nos registos de chamadas do OmniProxy se o pedido foi recebido.

O Aider apenas inclui no contexto os ficheiros já monitorizados pelo Git; o contexto corresponde ao código e às informações que o modelo consegue ler durante a tarefa atual. Se o diretório atual ainda não for um repositório Git, o Aider cria o repositório, mas continua sem conseguir ler os ficheiros que não são monitorizados pelo Git. Utilize primeiro git add para adicionar os ficheiros e faça um commit antes de iniciar o Aider.

O Aider poderá continuar a alterar ficheiros. A opção --no-auto-commits apenas desativa os commits automáticos; não impede a alteração dos ficheiros. Na primeira utilização, recomenda-se que escolha um repositório sem importância e execute git diff no fim da tarefa para consultar as alterações reais.

Não guarde chaves reais em ficheiros do projeto nem em páginas públicas. As chaves dos fornecedores devem ser guardadas apenas no OmniProxy. Se o gateway não validar a chave, pode preencher OPENAI_API_KEY com uma sequência de caracteres de substituição utilizada apenas localmente.

Verificar uma tarefa real

Primeiro, confirme que o ficheiro a ler já foi incluído num commit do Git. Em seguida, execute o comando abaixo no diretório do projeto. Substitua o ID do modelo pelo ID completo existente na lista atual do OmniProxy:

aider --model openai/gemini-3.8-flash --message "Qual é a primeira linha deste ficheiro? Não altere o ficheiro." --no-auto-commits

A opção --message envia diretamente uma tarefa ao Aider, enquanto --no-auto-commits indica que não devem ser criados commits do Git automaticamente durante esta execução.

Em 2026-10-09, o Aider v0.86.2 conseguiu ler a primeira linha de um ficheiro monitorizado. Se o ficheiro ainda não for monitorizado pelo Git, o Aider responderá que não consegue ver o conteúdo; isto não significa que o endereço da interface esteja incorreto. Depois de concluir a pergunta, verifique nos registos de chamadas do OmniProxy a origem do pedido e o ID do modelo.

Arranque

O aider abre

• O comando é encontrado
• As variáveis de ambiente estão ativas
• Está no diretório do projeto

Tarefa

Consultou o ficheiro

• Pergunte sobre um ficheiro específico
• Veja a explicação apresentada
• Modelos desconhecidos geram um aviso

Registo

Visível no gateway

• A origem é Aider
• O ID do modelo corresponde
• A chave não aparece na página

Erros comuns

• O comando aider não é encontrado: volte a abrir o terminal. Se tiver utilizado a instalação direta com pip, pode experimentar python -m aider.
• No Windows, a ligação continua a utilizar o endereço antigo depois de alterar as variáveis: depois de executar setx, tem de voltar a abrir o terminal, pois apenas uma nova janela lerá as variáveis atualizadas.
• O nome do modelo não tem openai/: a interface compatível exige o formato openai/<model-name>.
• Surge um aviso sobre um modelo não reconhecido: este é um aviso normal e não significa que a ligação falhou. Verifique depois se o OmniProxy recebeu o pedido.
• O ID do modelo é inválido: volte a copiar o ID completo a partir da lista atual do OmniProxy, mantendo o prefixo openai/ e todas as barras existentes no ID.
• O Aider indica que não existe conteúdo no ficheiro: confirme primeiro que o ficheiro é monitorizado pelo Git. Um repositório vazio ou ficheiros não monitorizados não serão incluídos no contexto.

Referências oficiais

Consulte os passos de instalação em Aider installation. Consulte as variáveis de ambiente e o prefixo do modelo em OpenAI compatible APIs. Os IDs de modelo utilizados nos exemplos podem ser consultados na lista de modelos Gemini e na página de modelos da xAI.

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 · Aider ↗