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

O Aider é uma ferramenta que ajuda a modificar código pelo terminal. Ele cria um mapa de todo o repositório para ajudar o modelo a compreender projetos maiores; o Git, por sua vez, é a ferramenta de controle de versão que registra as alterações no código e pode ser usada para visualizar diferenças e restaurar mudanças. Depois que você atribui uma tarefa ao Aider, ele a processa em etapas e escreve uma mensagem de commit. Se não gostar das alterações, use /undo para desfazê-las.

Preparação antes da instalação

Há duas formas comuns de instalar:

Se o computador já tem Python da versão 3.8 a 3.13: instale primeiro o aider-install. Python é o ambiente necessário para executar o Aider.
Se não houver uma versão adequada do Python: use o comando de instalação em uma linha, que também preparará o Python 3.12 quando necessário.

Mac e Linux

install.sh

Execute com sh após o curl
Instala o Python se necessário
Se não houver curl, use wget

Windows

install.ps1

Execute no PowerShell
Reabra o terminal após a instalação
Use setx para as variáveis de ambiente

Python já instalado

aider-install

Primeiro, instale este pacote com pip
Depois, execute aider-install
Ele criará o próprio ambiente

A instalação em uma linha prepara o Python 3.12 quando necessário. Instalar aider-chat diretamente com pip é uma opção menos confiável.

Deixe o OmniProxy em execução e pronto para uso. Após concluir a instalação, entre primeiro no diretório do projeto que você pretende modificar e depois inicie o Aider.

Instalação e primeira execução

Se você já tem Python da versão 3.8 à 3.13

Execute os comandos na ordem indicada:

python -m pip install aider-install
aider-install

O aider-install instala o Aider em um ambiente Python separado, evitando misturá-lo com outros projetos Python do computador. Quando necessário, ele também instala uma versão do Python 3.12 para uso do Aider.

Instalação em uma linha

No Mac e Linux, execute:

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

Se o computador não tiver curl, use:

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

No Windows PowerShell, execute:

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

Esses comandos de uma linha usam o uv, um programa para instalar e gerenciar ferramentas e ambientes Python. Você também pode usar o comando abaixo:

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

Outra opção é usar pipx. Ao instalar diretamente com python -m pip install aider-chat, as versões compatíveis do Python vão de 3.9 a 3.12, mas esse é um método alternativo; dê preferência aos métodos anteriores. O Aider disponível nos gerenciadores de pacotes do sistema pode apresentar incompatibilidades de dependências, portanto não priorize esse método de instalação.

Em 2026-10-09, o comando de instalação em uma linha instalou o Aider v0.86.2. Durante a instalação, se aparecer um aviso informando que o cache e o destino não estão no mesmo disco e que os arquivos serão copiados, a instalação ainda será concluída.

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

aider --model openai/<model-name>

Substitua <model-name> pelo ID completo do modelo copiado do OmniProxy na próxima seção. O ID do modelo é o nome usado para especificar o modelo com precisão.

Obter os parâmetros de conexão no OmniProxy

É necessário definir as duas variáveis de ambiente abaixo. Variáveis de ambiente podem ser entendidas como um conjunto de configurações de conexão lidas pelos programas do 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 deve terminar em /v1. OPENAI_API_KEY é a chave usada para acessar a interface.

No Windows, use setx para salvar as variáveis. Depois de executar os comandos, será necessário reabrir 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 da lista atual do OmniProxy, preservando também as barras presentes no ID. Ao iniciar o Aider, adicione openai/ antes do ID completo.

Em 2026-10-09, os dois IDs de referência na documentação dos fornecedores eram gemini-3.8-flash e grok-4.7. Se esses nomes não estiverem na lista atual, não os copie diretamente; use um ID completo que realmente esteja disponível na lista.

Endereço

OPENAI_API_BASE

Aponte para o OmniProxy
Termine com /v1
Não coloque no repositório

Chave

OPENAI_API_KEY

Use a chave fornecida pelo gateway
No Windows, reabra após alterar
Mantenha a chave do provedor no gateway

Inicialização

openai/modelo

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

As duas variáveis de ambiente, junto ao nome do modelo com o prefixo openai/, formam a configuração da interface compatível.

Preencher a configuração da ferramenta

Não é necessário criar outro arquivo de configuração. Primeiro, entre no diretório do projeto; depois, inicie o Aider e substitua o ID do modelo por um nome que realmente esteja disponível na lista atual do OmniProxy:

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

Para usar o outro modelo de exemplo, execute:

aider --model openai/grok-4.7

Quando o Aider encontra um modelo que não reconhece, a interface exibe um aviso. Esse aviso, por si só, não significa que o endereço esteja incorreto. Verifique nos registros de chamadas do OmniProxy se a solicitação foi recebida.

O Aider só inclui no contexto os arquivos que já são rastreados pelo Git. O contexto é o código e as 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 criará um, mas os arquivos não rastreados pelo Git continuarão inacessíveis. Primeiro, adicione os arquivos com git add e faça um commit; depois, inicie o Aider.

O Aider ainda pode modificar arquivos. --no-auto-commits apenas desativa os commits automáticos; essa opção não impede alterações nos arquivos. Na primeira utilização, é recomendável escolher um repositório sem importância e executar git diff após a tarefa para conferir as alterações efetivamente realizadas.

Não grave chaves reais em arquivos do projeto nem em páginas públicas. Mantenha as chaves dos fornecedores somente no OmniProxy. Se o gateway não validar a chave, você poderá preencher OPENAI_API_KEY com uma sequência de caracteres provisória usada apenas localmente.

Verificar uma tarefa real

Primeiro, confirme que o arquivo a ser lido já foi incluído em um commit do Git. Depois, execute o comando abaixo no diretório do projeto. Substitua o ID do modelo pelo ID completo disponível na lista atual do OmniProxy:

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

--message envia diretamente uma tarefa ao Aider, enquanto --no-auto-commits indica que nenhum commit do Git deve ser criado automaticamente nessa execução.

Em 2026-10-09, o Aider v0.86.2 conseguiu ler a primeira linha de um arquivo rastreado. Se o arquivo ainda não estiver sendo rastreado pelo Git, o Aider responderá que não consegue ver o conteúdo; isso não significa que o endereço da interface esteja incorreto. Depois de concluir a pergunta, confira nos registros de chamadas do OmniProxy a origem da solicitação e o ID do modelo.

Inicialização

aider abre

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

Tarefa

Ele leu o arquivo

Pergunte sobre um arquivo específico
Confira a explicação
Modelos desconhecidos geram um aviso

Registros

Visível no gateway

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

Confirme que as variáveis de ambiente estão ativas, que o comando foi encontrado e conclua uma pergunta real.

Erros comuns

O comando aider não foi encontrado: primeiro, reabra o terminal. Se você fez a instalação diretamente com pip, tente python -m aider.
O Windows ainda se conecta ao endereço antigo após alterar as variáveis: depois de executar setx, é obrigatório reabrir o terminal para que a nova janela leia as variáveis atualizadas.
O nome do modelo não tem openai/: a interface compatível exige o formato openai/<model-name>.
Aparece um aviso de modelo desconhecido: esse é um aviso normal e não significa que a conexão falhou. Em seguida, verifique se o OmniProxy recebeu a solicitação.
O ID do modelo é inválido: copie novamente o ID completo da lista atual do OmniProxy, preservando o prefixo openai/ e as barras já existentes no ID.
O Aider informa que não há conteúdo no arquivo: primeiro, confirme que o arquivo está sendo rastreado pelo Git. Repositórios vazios e arquivos não rastreados não entram no contexto.

Referências oficiais

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

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