Tutorial de Instalação do OpenFang

Dificuldade: Iniciante | Tempo: 15 minutos | Ganho: Dominar o deploy do OpenFang e a configuração de modelos

Prefácio

Se você está procurando um framework de AI Agent leve e poderoso, o OpenFang merece sua atenção. Este é um Agent Operating System de código aberto escrito em Rust; todo o sistema compilado tem apenas cerca de 32MB, mas possui suporte nativo para mais de 20 provedores de LLM, incluindo Anthropic Claude, Google Gemini, OpenAI GPT, DeepSeek, Groq, entre outros.

Diferente dos frameworks tradicionais, o OpenFang não é um simples wrapper de Chatbot, mas um sistema de Agent autônomo que realmente trabalha para você — ele pode rodar conforme um cronograma planejado, ajudá-lo a construir grafos de conhecimento, monitorar alvos, gerar leads, gerenciar redes sociais e reportar automaticamente os resultados no seu Dashboard.

Hoje, vamos aprender a configurá-lo.

Público-alvo

Desenvolvedores com 1-5 anos de experiência
Profissionais técnicos interessados em AI Agents
Entusiastas de tecnologia que desejam implementar capacidades de IA local rapidamente

Dependências e Ambiente Core

Antes de começar, certifique-se de que sua máquina atenda aos seguintes requisitos:

Sistema Operacional: Linux, macOS, Windows (WSL2 ou PowerShell)
Rust: 1.75+ (recomendado usar rustup para gerenciamento)
Memória: Pelo menos 4GB de RAM
Disco: Pelo menos 500MB de espaço disponível

Instalar Rust (se ainda não tiver)

# Linux/macOS
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Windows (usando PowerShell)
irm https://sh.rustup.rs | iex

Após a instalação, execute rustc --version para confirmar a versão.

Estrutura do Projeto

openfang/
├── agents/                 # Diretório de templates de Agent
│   ├── hello-world/
│   ├── coder/
│   ├── researcher/
│   └── ...
├── crates/                # Rust crates (14 no total)
│   ├── openfang-cli/      # Interface de linha de comando (CLI)
│   ├── openfang-runtime/  # Core do runtime
│   ├── openfang-api/      # REST API
│   └── ...
├── docs/                  # Documentação oficial
├── sdk/                   # SDK multi-linguagem
│   ├── python/
│   └── javascript/
└── config.toml.example    # Exemplo de configuração

Instalação Rápida

Método 1: Instalação oficial em um clique (Recomendado)

Linux/macOS:

curl -fsSL https://openfang.sh/install | sh

Windows PowerShell:

irm https://openfang.sh/install.ps1 | iex

Após a instalação, você verá a seguinte mensagem:

✅ OpenFang installed successfully!
Run 'openfang init' to get started.

Método 2: Compilação Manual

Se você deseja construir a partir do código-fonte ou está em um ambiente que não suporta a instalação rápida:

# Clonar o repositório
git clone https://github.com/RightNow-AI/openfang.git
cd openfang

# Compilar versão release
cargo build --release

# Ou compilar apenas o CLI
cargo build --release -p openfang-cli

Após a compilação, o arquivo binário estará localizado em target/release/openfang (ou target/release/openfang.exe).

Configuração Inicial

Criar Arquivo de Configuração

Execute o comando de inicialização:

openfang init

Isso criará uma pasta de configuração no seu diretório home:

~/.openfang/
└── config.toml    # Arquivo de configuração principal

Estrutura do Arquivo de Configuração

Abra ~/.openfang/config.toml, a configuração básica é a seguinte:

# Configuração do serviço API
host = "127.0.0.1"
port = 4200

# Chave de API (opcional, recomendada para ambiente de produção)
api_key = ""

# Configuração do modelo padrão
[default_model]
provider = "groq"
model = "llama-3.3-70b-versatile"

# Configurações padrão para Agents
[agents.defaults]

[!TIP]
Todos os campos no arquivo de configuração são opcionais; campos omitidos usarão valores padrão.

Configurar API Key

O OpenFang suporta a configuração de chaves de API via variáveis de ambiente. Recomendamos usar Groq (cota gratuita) ou Defapi (metade do preço) para a primeira experiência:

# Opção 1: Groq (Gratuito, com limites de taxa)
export GROQ_API_KEY="gsk_sua_chave_Groq"

# Opção 2: Defapi (Metade do preço, recomendado)
export DEFAPI_API_KEY="sua_chave_Defapi"

[!WARNING]
Não escreva a API Key diretamente no arquivo de configuração; use referências a variáveis de ambiente.

Iniciando o Serviço

Iniciar OpenFang

openfang start

Você verá uma saída similar a esta:

🚀 Starting OpenFang daemon...
📡 Server listening on http://127.0.0.1:4200
🌐 Dashboard: http://127.0.0.1:4200
✅ OpenFang is ready!

Validar o Serviço

# Check de saúde
curl http://127.0.0.1:4200/api/health

# Ver modelos disponíveis
curl http://127.0.0.1:4200/api/models

# Ver status dos provedores
curl http://127.0.0.1:4200/api/providers

Acessar o Dashboard

Abra o navegador e acesse http://127.0.0.1:4200, você verá o Web Dashboard do OpenFang.

Seu Primeiro Agent

Criar usando Template Interno

O OpenFang fornece vários templates de Agent integrados, localizados no diretório agents/:

# Listar templates disponíveis
openfang template list

Templates comuns:

hello-world: Agent de diálogo simples
coder: Assistente de escrita de código
researcher: Assistente de pesquisa
assistant: Assistente genérico

Criar o Agent

# Criar usando o template hello-world
openfang agent create hello-world my-first-agent

Testar enviando mensagem

# Enviar mensagem via CLI
openfang agent message my-first-agent "Hello, say hi in 3 words"

Ou através da REST API:

curl -X POST http://127.0.0.1:4200/api/agents/{agent-id}/message \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, say hi in 3 words"}'

Se retornar uma resposta normal, seu Agent já está funcionando!

Prática de Configuração de Modelos

Configurar Groq (Cota Gratuita)

O Groq oferece um tier gratuito e é extremamente rápido, ideal para desenvolvimento e testes:

# ~/.openfang/config.toml
[default_model]
provider = "groq"
model = "llama-3.3-70b-versatile"

Variável de ambiente:

export GROQ_API_KEY="gsk_sua_chave"

[!TIP]
O tier gratuito do Groq possui limites de taxa (rate limits). Para produção, recomenda-se outros provedores.

Configurar Defapi (Recomendado pelo Preço)

Se você quer usar modelos de alta qualidade por um preço menor, o Defapi é uma escolha excelente. O preço é apenas 50% do oficial:

Gemini 2.5 Pro: Oficial $1.25/M → Defapi apenas $0.625/M
Claude Sonnet 4: Oficial $3.00/M → Defapi apenas $1.50/M

# ~/.openfang/config.toml

# Adicionar provedor personalizado
[[providers]]
name = "defapi"
base_url = "https://api.defapi.org/v1"
api_key_env = "DEFAPI_API_KEY"

# Configurar modelo padrão
[default_model]
provider = "defapi"
model = "claude-sonnet-4-20250514"

Variável de ambiente:

export DEFAPI_API_KEY="sua_chave_Defapi"

[!TIP]
O Defapi suporta múltiplos protocolos: v1/chat/completions, v1/messages, v1beta/models/*, sendo perfeitamente compatível com o OpenFang.

Configurar Anthropic Claude

[default_model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"

export ANTHROPIC_API_KEY="sk-ant-sua_chave"

Configurar Google Gemini

[default_model]
provider = "gemini"
model = "gemini-2.5-flash"

# GEMINI_API_KEY ou GOOGLE_API_KEY, ambos funcionam
export GEMINI_API_KEY="AIza_sua_chave"

Configurar OpenAI

[default_model]
provider = "openai"
model = "gpt-4o-mini"

export OPENAI_API_KEY="sk-sua_chave"

Solução de Problemas Comuns

Q1: A API Key parece não estar funcionando

Passos de verificação:

Confirme se a variável de ambiente foi exportada corretamente: echo $GROQ_API_KEY
Reinicie o serviço OpenFang: openfang restart
Verifique o status do provedor: curl http://127.0.0.1:4200/api/providers

Q2: O modelo aparece como indisponível

Causas possíveis:

API Key não configurada ou formato incorreto
O modelo não está na lista de suporte do provedor
Problemas de conexão de rede

Solução:

# Ver lista detalhada de modelos
curl http://127.0.0.1:4200/api/models | jq

# Testar conexão de um provedor específico
curl -X POST http://127.0.0.1:4200/api/providers/groq/test

Q3: Porta 4200 já está em uso

# Ver processo ocupando a porta
lsof -i :4200   # Linux/macOS
netstat -ano | findstr :4200  # Windows

# Modificar o arquivo de configuração para usar outra porta
# ~/.openfang/config.toml
port = 4201

Q4: Erro de compilação

Certifique-se de que a versão do Rust é recente o suficiente:

rustup update
rustc --version  # Deve ser >= 1.75

Se encontrar problemas de dependência, tente:

cargo clean
cargo build --release

Q5: Comando não encontrado no Windows

Certifique-se de que o binário do OpenFang está no PATH:

# Adicionar diretório binário ao PATH (permanente)
$env:PATH += ";$env:USERPROFILE\.openfang\bin"

# Ou use o caminho completo diretamente
~\.openfang\bin\openfang.exe start

Q6: Como visualizar os logs

# Ver logs em tempo real
openfang logs

# Ou visualizar o arquivo de log
cat ~/.openfang/logs/openfang.log

Direções Avançadas

Hands: 7 Pacotes de Capacidades Integrados

A maior característica do OpenFang são seus 7 "Hands" integrados:

Hand	Função
Clip	Download, corte, dublagem de vídeos do YouTube e publicação automática em redes sociais
Lead	Geração diária de leads, prospecção de clientes, pontuação e eliminação de duplicatas
Collector	Coleta de inteligência OSINT, detecção de mudanças e construção de grafos de conhecimento
Predictor	Engine de previsão, intervalos de confiança e rastreamento de precisão
Researcher	Pesquisa profunda, validação cruzada multi-fonte e relatórios em formato APA
Twitter	Postagem automática, respostas interativas e cronograma de publicações
Browser	Automação web, preenchimento de formulários e workflows de múltiplos passos

# Ativar Researcher Hand
openfang hand activate researcher

# Verificar status
openfang hand status researcher

# Pausar
openfang hand pause researcher

Desenvolvimento de Agent Personalizado

Crie um Agent personalizado:

# my-agent.toml
name = "my-agent"
version = "0.1.0"
description = "My custom agent"
author = "voce"

[model]
provider = "groq"
model = "llama-3.3-70b-versatile"

[capabilities]
tools = ["file_read", "web_fetch", "bash"]
memory_read = ["*"]
memory_write = ["self.*"]

# Fazer deploy do Agent personalizado
openfang agent deploy my-agent.toml

Integração MCP

O OpenFang suporta MCP (Model Context Protocol), podendo conectar-se a vários serviços externos:

[[mcp_servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

Resumo

Hoje concluímos o fluxo completo de configuração do OpenFang:

✅ Instalação do OpenFang (Script oficial ou compilação manual)
✅ Configuração inicial (config.toml + variáveis de ambiente)
✅ Inicialização e validação do serviço
✅ Criação e teste do primeiro Agent
✅ Configuração de múltiplos provedores de LLM (Groq, Defapi, Claude, Gemini)
✅ Solução de problemas comuns

Agora você tem uma plataforma completa de execução de AI Agents! Próximos passos sugeridos:

Ative um Hands e experimente a capacidade de trabalho automatizado
Crie um Agent personalizado, definindo suas próprias ferramentas e capacidades
Explore a integração MCP para conectar mais serviços externos

Divirta-se!

[!TIP]
Para ambientes de produção, recomenda-se usar o Defapi (metade do preço) ou configurar múltiplos Providers para failover, garantindo a estabilidade do serviço.