MoltBot Configuração de Proxy de API: Tutorial completo em 3 etapas para acessar Claude Opus e outros modelos

Quer conectar o MoltBot ao Claude Opus 4.5 ou outros modelos de linguagem grande, mas não sabe como configurar o proxy da API? Este artigo vai te ensinar passo a passo como realizar a configuração de múltiplos provedores (Multi-Provider) no MoltBot, permitindo que seu assistente de IA acesse vários serviços de modelos simultaneamente, com alternância inteligente e backup para tolerância a falhas.

Valor Central: Ao terminar de ler, você dominará o método de configuração models.providers do MoltBot e aprenderá a definir modelos principais, modelos de reserva e apelidos de modelos, criando um assistente de IA estável e confiável.

Configuração de Proxy de API do MoltBot: Análise de Conceitos Principais

O MoltBot permite o acesso a quase todos os principais serviços de modelos de linguagem grande por meio de uma API compatível com OpenAI. Entender os conceitos centrais abaixo é a chave para uma configuração bem-sucedida.

Sistema de Arquivos de Configuração do MoltBot

Campos Principais da Configuração de Provedor do MoltBot

Cada configuração de Provedor (Provider) contém os seguintes campos cruciais:

Explicação dos Tipos de Protocolo de API

O MoltBot suporta dois protocolos principais compatíveis com OpenAI:

🎯 Sugestão de Configuração: A maioria dos serviços de proxy de API (como APIYI apiyi.com) usa o protocolo openai-completions. Se você estiver usando uma implantação local do LM Studio ou Ollama, precisará usar openai-responses.

Configuração Multi-Provedor do MoltBot: Exemplo Completo

Abaixo está um exemplo prático de configuração multi-provedor, conectando simultaneamente os serviços APIYI e Qwen Portal:

Exemplo de Arquivo de Configuração Completo

{
  "models": {
    "providers": {
      "qwen-portal": {
        "baseUrl": "https://portal.qwen.ai/v1",
        "apiKey": "${QWEN_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "coder-model", "name": "Qwen Coder", "contextWindow": 128000 },
          { "id": "vision-model", "name": "Qwen Vision", "contextWindow": 128000 }
        ]
      },
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "${APIYI_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "claude-opus-4-5-20251101", "name": "Claude Opus 4.5", "contextWindow": 200000 },
          { "id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4", "contextWindow": 200000 },
          { "id": "gpt-4o", "name": "GPT-4o", "contextWindow": 128000 }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "apiyi/claude-opus-4-5-20251101",
        "fallbacks": ["qwen-portal/vision-model"]
      },
      "models": {
        "apiyi/claude-opus-4-5-20251101": { "alias": "opus" },
        "apiyi/claude-sonnet-4-20250514": { "alias": "sonnet" },
        "qwen-portal/coder-model": { "alias": "qwen" }
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}"
    }
  }
}

Detalhamento da Estrutura de Configuração

1. Seção models.providers

Esta é a parte central para definir os serviços de proxy de API:

"providers": {
  "apiyi": {
    "baseUrl": "https://api.apiyi.com/v1",
    "apiKey": "${APIYI_API_KEY}",
    "api": "openai-completions",
    "models": [...]
  }
}

• ID do Provedor (apiyi): Identificador de serviço personalizado, usado para referências posteriores.
• baseUrl: Endpoint da API; deve terminar obrigatoriamente com /v1.
• apiKey: Permite preencher a chave diretamente ou utilizar a variável de ambiente ${ENV_VAR}.
• models: Lista de modelos suportados por este provedor.

2. Seção agents.defaults.model

Define o modelo padrão utilizado e a estratégia de contingência (disaster recovery):

"model": {
  "primary": "apiyi/claude-opus-4-5-20251101",
  "fallbacks": ["qwen-portal/vision-model"]
}

• primary: Modelo principal, seguindo o formato id-do-provedor/id-do-modelo.
• fallbacks: Array de modelos de reserva; o sistema alterna automaticamente para estes caso o modelo principal falhe.

3. Seção agents.defaults.models

Define apelidos (aliases) para os modelos, facilitando a troca rápida entre eles:

"models": {
  "apiyi/claude-opus-4-5-20251101": { "alias": "opus" },
  "qwen-portal/coder-model": { "alias": "qwen" }
}

Após configurar os apelidos, você pode usar o comando /model opus durante uma conversa para trocar de modelo rapidamente.

Configuração de Proxy de API do MoltBot: Passo a Passo

Passo 1: Obter a Chave de API (API Key)

Antes de configurar, você precisa ter sua API Key em mãos:

🚀 Começo Rápido: Recomendamos usar o APIYI (apiyi.com) como seu provedor principal. Com apenas uma API Key, você pode acessar os principais modelos como Claude, GPT e Gemini, sem precisar se registrar em várias plataformas.

Passo 2: Configurar Variáveis de Ambiente

Por questões de segurança, sugerimos armazenar suas chaves de API em variáveis de ambiente:

# Linux/macOS - Adicione ao seu ~/.bashrc ou ~/.zshrc
export APIYI_API_KEY="sk-your-apiyi-key"
export QWEN_API_KEY="your-qwen-key"
export TELEGRAM_BOT_TOKEN="your-telegram-token"

# Aplique as configurações
source ~/.bashrc

# Windows PowerShell
$env:APIYI_API_KEY = "sk-your-apiyi-key"
$env:QWEN_API_KEY = "your-qwen-key"
$env:TELEGRAM_BOT_TOKEN = "your-telegram-token"

Passo 3: Editar o Arquivo de Configuração

Abra ou crie o arquivo de configuração do MoltBot:

# Abrir o arquivo de configuração
nano ~/.moltbot/moltbot.json

# Ou use o VS Code
code ~/.moltbot/moltbot.json

Cole a seguinte configuração no arquivo:

{
  "models": {
    "providers": {
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "${APIYI_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-4-5-20251101",
            "name": "Claude Opus 4.5",
            "contextWindow": 200000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "apiyi/claude-opus-4-5-20251101"
      }
    }
  }
}

Passo 4: Verificar a Configuração

Reinicie o MoltBot e verifique se as configurações foram aplicadas:

# Reiniciar o MoltBot
moltbot restart

# Verificar a configuração atual dos modelos
moltbot models list

# Testar a chamada do modelo
moltbot chat "Olá, por favor, me diga qual modelo você é"

{
  "models": {
    "mode": "merge",
    "providers": {
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "${APIYI_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-4-5-20251101",
            "name": "Claude Opus 4.5",
            "contextWindow": 200000,
            "maxTokens": 32000
          },
          {
            "id": "claude-sonnet-4-20250514",
            "name": "Claude Sonnet 4",
            "contextWindow": 200000,
            "maxTokens": 64000
          },
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "contextWindow": 128000,
            "maxTokens": 16384
          },
          {
            "id": "gemini-2.5-pro",
            "name": "Gemini 2.5 Pro",
            "contextWindow": 1000000,
            "maxTokens": 65536
          }
        ]
      },
      "qwen-portal": {
        "baseUrl": "https://portal.qwen.ai/v1",
        "apiKey": "${QWEN_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "coder-model",
            "name": "Qwen Coder",
            "contextWindow": 128000
          },
          {
            "id": "vision-model",
            "name": "Qwen Vision",
            "contextWindow": 128000
          }
        ]
      },
      "local-ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "apiKey": "ollama-local",
        "api": "openai-responses",
        "models": [
          {
            "id": "llama3.3:70b",
            "name": "Llama 3.3 70B",
            "contextWindow": 128000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "apiyi/claude-opus-4-5-20251101",
        "fallbacks": [
          "apiyi/claude-sonnet-4-20250514",
          "qwen-portal/vision-model",
          "local-ollama/llama3.3:70b"
        ]
      },
      "models": {
        "apiyi/claude-opus-4-5-20251101": {
          "alias": "opus",
          "params": { "temperature": 0.7 }
        },
        "apiyi/claude-sonnet-4-20250514": {
          "alias": "sonnet",
          "params": { "temperature": 0.5 }
        },
        "apiyi/gpt-4o": {
          "alias": "gpt"
        },
        "qwen-portal/coder-model": {
          "alias": "qwen"
        },
        "local-ollama/llama3.3:70b": {
          "alias": "llama"
        }
      },
      "imageModel": "apiyi/gpt-4o"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}"
    },
    "discord": {
      "enabled": false,
      "token": "${DISCORD_BOT_TOKEN}"
    }
  }
}

💡 Dica de Configuração: Usar "mode": "merge" permite que você mantenha as configurações de modelo integradas do MoltBot enquanto adiciona seus próprios provedores customizados. Dessa forma, se o seu serviço personalizado estiver indisponível, ele poderá retornar à configuração padrão.

Configuração de Modelos no MoltBot: Detalhes de Parâmetros Avançados

Campos Completos da Entrada do Modelo

Configuração de Parâmetros do Modelo (params)

Em agents.defaults.models, você pode definir parâmetros padrão para cada modelo:

"models": {
  "apiyi/claude-opus-4-5-20251101": {
    "alias": "opus",
    "params": {
      "temperature": 0.7,
      "maxTokens": 16000
    }
  }
}

⚠️ Atenção: temperature é um parâmetro avançado. A menos que você conheça as configurações padrão do modelo e realmente precise ajustá-las, recomendamos não defini-la.

Configuração de Tolerância a Falhas (Fallback) no MoltBot

O mecanismo de Fallback é um recurso essencial do MoltBot, garantindo que o assistente de IA esteja sempre disponível.

Como funciona o Fallback

Requisição do usuário
    ↓
Modelo principal (primary)
    ↓ (Falha)
Modelo de backup 1 (fallbacks[0])
    ↓ (Falha)
Modelo de backup 2 (fallbacks[1])
    ↓ (Falha)
...continuar tentando

Estratégias recomendadas de configuração de Fallback

Configuração recomendada:

"model": {
  "primary": "apiyi/claude-opus-4-5-20251101",
  "fallbacks": [
    "apiyi/claude-sonnet-4-20250514",
    "apiyi/gpt-4o",
    "qwen-portal/vision-model"
  ]
}

💰 Otimização de custos: Ao configurar o Fallback através da APIYI apiyi.com, você pode alternar automaticamente entre vários modelos e ainda aproveitar uma forma de faturamento unificada, o que facilita muito o controle de custos.

Troca de modelos no MoltBot: Dicas práticas

Use apelidos (aliases) para trocar rápido

Após configurar os apelidos, você pode alternar entre os modelos a qualquer momento durante a conversa:

Você: /model opus
MoltBot: Alterado para Claude Opus 4.5

Você: /model sonnet
MoltBot: Alterado para Claude Sonnet 4

Você: /model qwen
MoltBot: Alterado para Qwen Coder

Especifique um modelo para tarefas específicas

Você: /model gpt me ajude a analisar esta imagem
MoltBot: [Usando GPT-4o para analisar a imagem...]

Você: /model opus escreva um artigo técnico aprofundado
MoltBot: [Usando Claude Opus para escrever...]

Verifique o status do modelo atual

# Visualizar via linha de comando
moltbot models list

# Visualizar na conversa
Você: /model
MoltBot: Modelo atual: apiyi/claude-opus-4-5-20251101 (alias: opus)

Configuração de Proxy de API no MoltBot: Perguntas Frequentes

{
  "models": {
    "mode": "merge",
    "providers": {
      "local-ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "apiKey": "ollama-local",
        "api": "openai-responses",
        "models": [...]
      },
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "${APIYI_API_KEY}",
        "api": "openai-completions",
        "models": [...]
      }
    }
  }
}

"agents": {
  "defaults": {
    "model": {
      "primary": "apiyi/claude-opus-4-5-20251101"
    },
    "imageModel": "apiyi/gpt-4o",
    "models": {
      "apiyi/claude-opus-4-5-20251101": { "alias": "opus" },
      "apiyi/gpt-4o": { "alias": "vision" }
    }
  }
}

Configuração de Proxy de API no MoltBot: Resumo e Sugestões

Com este artigo, você dominou o método completo de configuração de proxy de API no MoltBot:

1. Entender a estrutura de configuração: models.providers define os serviços, enquanto agents.defaults define a estratégia de uso.
2. Configurar múltiplos Providers: Conecte vários serviços de API simultaneamente para aumentar a disponibilidade.
3. Configurar Fallback: Mude automaticamente para um modelo reserva caso o modelo principal falhe.
4. Usar apelidos (aliases): Troque de modelo rapidamente através de /model alias.

Sugestões de Melhores Práticas

Recomendamos o APIYI (apiyi.com) como seu principal serviço de proxy de API. A plataforma oferece acesso unificado aos principais modelos como Claude, GPT e Gemini. A configuração é simples, com suporte a modelos de faturamento flexíveis, sendo ideal para o cenário de troca de múltiplos modelos do MoltBot.

Referências

1. Documentação oficial do MoltBot – Models: Detalhes da configuração de modelos

   • Link: docs.molt.bot/concepts/models
   • Descrição: Guia oficial de configuração de modelos

2. Documentação oficial do MoltBot – Configuration: Referência completa de configuração

   • Link: docs.molt.bot/gateway/configuration
   • Descrição: Explicação detalhada de todos os itens de configuração

3. Documentação oficial do MoltBot – Model Providers: Configuração de Providers

   • Link: docs.molt.bot/concepts/model-providers
   • Descrição: Métodos de configuração de provedores (providers) personalizados

4. MoltBot GitHub: Código-fonte e discussões de Issues

   • Link: github.com/moltbot/moltbot
   • Descrição: Últimas versões e feedback de problemas

Autor do artigo: APIYI Team | Para mais compartilhamentos de tecnologia de IA, visite o APIYI em apiyi.com

Data de atualização: Janeiro de 2026