O ficheiro config.toml
Nesta página
Lição atualizada a 2 de novembro de 2026 com base na documentação do Vibe Code: modelo integrado Mistral Medium 3.5 (mais Devstral 2),
enable_update_checks(a chaveenable_auto_updatedeixou de ter efeito), ferramentaedit(anteriormentesearch_replace) e a secção[safety]removida, substituída pordefault_agent. Fontes: Configuration · Configuration reference.
Onde se encontra o config.toml?
O Vibe procura o seu ficheiro de configuração em dois locais, pela seguinte ordem:
- Configuração do projeto:
./.vibe/config.toml(no diretório atual) - Configuração global:
~/.vibe/config.toml(no seu diretório pessoal)
A configuração do projeto tem precedência sobre a configuração global. Este mecanismo torna a ferramenta prática para o fluxo de trabalho diário de um programador: a sua configuração global reflete os seus hábitos, enquanto o repositório de um cliente impõe as suas próprias regras dentro do seu diretório, sem que tenha de alterar manualmente as definições.
Estrutura do ficheiro
O ficheiro config.toml utiliza o formato TOML, um formato de configuração legível e inequívoco. Eis um exemplo completo comentado contendo tudo o que irá precisar:
# ~/.vibe/config.toml
# Modelo ativo: o modelo incorporado ou um alias para uma predefinição [[models]]
active_model = "mistral-medium-3.5"
# Agente padrão (aceita edições se a chave estiver em falta)
default_agent = "ask"
# Prompt de sistema personalizado (~/.vibe/prompts/my_custom_prompt.md)
system_prompt_id = "my_custom_prompt"
# Tema: segue automaticamente o terminal; use /theme para escolher
theme = "auto"
# Verificação diária de novas versões
enable_update_checks = true
Escolha do modelo
O parâmetro active_model determina qual o modelo que o Vibe utiliza para a geração. Espera um alias: quer o modelo incorporado, Mistral Medium 3.5, quer um alias para uma predefinição [[models]] que tenha declarado (abordado na próxima lição).
active_model = "mistral-medium-3.5"
Não precisa de editar o ficheiro para mudar de modelo: o comando /model alterna entre modelos durante a sessão e apresenta a lista de opções disponíveis. Utilize o ficheiro para definir a sua escolha padrão e o comando para testes pontuais.
Personalização do prompt de sistema
O prompt de sistema define o comportamento do Vibe. Por predefinição, está configurado para ser um assistente de codificação eficaz, mas pode especializá-lo. Esta é frequentemente a definição que produz o ganho mais visível: um agente que conhece as suas convenções à partida deixa de propor código que necessita de reformatação.
Os prompts são ficheiros Markdown armazenados em ~/.vibe/prompts/. Crie o seu próprio; eis um exemplo para uma equipa que trabalha com Python e FastAPI:
mkdir -p ~/.vibe/prompts
cat > ~/.vibe/prompts/mon_prompt.md << 'EOF'
Tu es un assistant de développement spécialisé en Python et FastAPI.
Tu écris du code propre, typé, avec des docstrings.
Tu privilégies les approches fonctionnelles quand c'est possible.
Tu réponds toujours en français.
EOF
Em seguida, referencie-o no config.toml utilizando o nome do ficheiro sem a sua extensão:
system_prompt_id = "mon_prompt"
Configuração de agentes
Os agentes vão mais além do que apenas prompts: são perfis de configuração completos onde cada agente tem o seu próprio modelo, prompt de sistema e permissões de ferramentas. Cria-os em ~/.vibe/agents/. O exemplo mais claro é um agente de revisão de código:
# ~/.vibe/agents/code_review.toml
system_prompt_id = "code_reviewer"
disabled_tools = ["write_file", "edit", "bash"]
[tools.bash]
permission = "never"
Execute-o sob demanda:
vibe --agent code_review
Este agente apenas pode ler: não pode escrever ficheiros nem executar comandos. Pode, portanto, deixá-lo analisar a branch de um colega sem receio de modificações acidentais, tornando-o o modo ideal para revisões de código seguras.
Controlo de ferramentas
Esta filtragem de ferramentas aplica-se também à configuração principal. Estão disponíveis duas listas: uma para permitir apenas ferramentas específicas e outra para as proibir:
# Ativar apenas ferramentas específicas
enabled_tools = ["read_file", "grep", "edit"] # edit: anteriormente search_replace
# Desativar ferramentas específicas
disabled_tools = ["bash", "write_file"]
Escrever todos os nomes à mão torna-se tedioso quando um servidor MCP expõe vinte ferramentas. As ferramentas MCP são nomeadas {server}_{tool} e os filtros aceitam wildcards e expressões regulares (prefixo re:). Isto permite-lhe raciocinar por família em vez de por ferramenta individual:
# Ativar todas as ferramentas de um servidor MCP chamado serena (padrão glob)
enabled_tools = ["serena_*"]
# ... ou a mesma coisa com uma expressão regular:
# enabled_tools = ["re:^serena_.*$"]
# Desativar todas as ferramentas do servidor MCP fetch_server
disabled_tools = ["fetch_server_*"]
Tema e localização da configuração
Defina o tema no mesmo ficheiro ou dinamicamente através do comando /theme:
theme = "auto"
Os temas disponíveis variam consoante a versão; utilize /theme no modo interativo para ver a lista completa e pré-visualizar cada opção antes de fixar a sua escolha.
Por fim, o Vibe armazena a sua configuração em ~/.vibe/ por predefinição, mas pode alterar esta localização através de uma variável de ambiente:
export VIBE_HOME="/chemin/vers/mon/dossier/vibe"
Isto é útil se o seu diretório pessoal estiver numa unidade de rede lenta onde cada leitura de configuração implicaria latência, ou se partilhar uma configuração entre várias máquinas através de um serviço de sincronização.
Configuração específica do projeto
Retomando o cenário inicial: para definições específicas do projeto, crie .vibe/config.toml na raiz do projeto:
mkdir -p .vibe
cat > .vibe/config.toml << 'EOF'
system_prompt_id = "python_expert"
[tools.bash]
permission = "ask"
allowlist = ["git status", "git diff", "pytest"]
EOF
O Vibe carrega este ficheiro apenas se tiver declarado a pasta como confiável no primeiro arranque. Como precaução antes de fazer commit: adicione .vibe/ ao seu .gitignore se o ficheiro contiver informações sensíveis, como nomes de variáveis ou URLs internas que não queira enviar para o repositório.
Pontos-chave
- O config.toml existe em versões global (
~/.vibe/) e de projeto (./.vibe/) - A configuração do projeto tem precedência sobre a configuração global
- Os agentes são perfis completos com modelo, prompt e permissões; defina o agente padrão com
default_agent - As ferramentas podem ser filtradas usando wildcards ou regex
- A variável
VIBE_HOMEpermite alterar o diretório de configuração