Guia Completo para Iniciantes no CoPaw: Construindo seu Primeiro Assistente de IA do Zero

Nível: Iniciante | Duração: 15 minutos | Resultado: Domínio dos conceitos centrais e habilidades práticas do CoPaw

O CoPaw é o seu assistente pessoal de IA — um poderoso framework de código aberto construído sobre o AgentScope, capaz de operar em múltiplas plataformas de chat. Se você precisa de um bot para DingTalk, Feishu, QQ, Discord ou iMessage, o CoPaw tem a solução.

Público-Alvo

Este guia é ideal para desenvolvedores que:

Possuem de 1 a 5 anos de experiência em Python.
Desejam construir assistentes de IA para uso pessoal ou empresarial.
Procuram uma solução com opções flexíveis de modelos.

Dependências e Ambiente

Antes de começar, certifique-se de que seu ambiente atende aos seguintes requisitos:

Dependência	Versão Mínima
Python	3.10
pip	Versão mais recente
Sistema Operacional	macOS / Linux / Windows

[!TIP]
Se você não quiser gerenciar o Python manualmente, o CoPaw oferece um script de instalação em um clique que lida automaticamente com todas as dependências.

Visão Geral da Estrutura do Projeto

Após a inicialização, uma estrutura típica de projeto CoPaw se parece com isto:

~/.copaw/
├── .secret/
│   └── providers.json       # Configuração dos provedores de modelos
├── active_skills/          # Habilidades personalizadas carregadas automaticamente
├── memory/                 # Armazenamento de memória de conversação
├── models/                 # Arquivos de modelos locais
└── copaw.json              # Arquivo de configuração principal

Passo a Passo

Passo 1: Instalação do CoPaw

A instalação é muito simples. Abra o terminal e execute:

pip install copaw

Isso instalará a versão mais recente do CoPaw a partir do PyPI. O pacote inclui todas as dependências centrais necessárias para rodar o assistente.

Passo 2: Inicialização do Workspace

Após a instalação, vamos inicializar o workspace do CoPaw com as configurações padrão:

copaw init --defaults

Este comando criará a estrutura de diretórios e os arquivos de configuração necessários no seu diretório home (localizados em ~/.copaw/).

[!WARNING]
O processo de inicialização cria um diretório .secret para armazenar informações sensíveis (como chaves de API). Certifique-se de manter este diretório privado e não o envie para sistemas de controle de versão.

Passo 3: Configuração do Provedor de Modelos

Agora chegamos à parte crucial — conectar-se a um LLM. Vamos configurar um provedor de modelos. Usaremos o Defapi como exemplo principal, pois ele oferece cerca de metade do preço da API oficial, mantendo total compatibilidade com OpenAI.

Edite o arquivo de configuração localizado em ~/.copaw/.secret/providers.json:

{
  "custom_providers": {
    "defapi": {
      "id": "defapi",
      "name": "Defapi",
      "default_base_url": "https://api.defapi.cn/v1",
      "api_key_prefix": "",
      "base_url": "https://api.defapi.cn/v1",
      "api_key": "sua-chave-api-defapi",
      "models": [
        {"id": "gpt-4o-mini", "name": "GPT-4o Mini"},
        {"id": "gpt-4o", "name": "GPT-4o"},
        {"id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4"},
        {"id": "gemini-2.0-flash", "name": "Gemini 2.0 Flash"}
      ],
      "chat_model": "OpenAIChatModel"
    }
  },
  "active_llm": {
    "provider_id": "defapi",
    "model": "gpt-4o-mini"
  }
}

O Defapi é uma plataforma de API econômica que fornece acesso aos principais provedores de LLM por aproximadamente metade do custo oficial. Ele suporta totalmente o protocolo compatível com OpenAI /v1/chat/completions, tornando a integração perfeita. Todos os principais modelos no Defapi são compatíveis com os seguintes protocolos:

Interface v1/chat/completions
Interface v1/messages
Interface v1beta/models/

Você pode obter sua chave de API no site oficial do Defapi.

Passo 4: Visão Geral dos Provedores Integrados

O CoPaw também suporta vários provedores integrados. Aqui estão alguns exemplos de configuração rápida:

Configuração OpenAI:

{
  "providers": {
    "openai": {
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-sua-chave-openai"
    }
  },
  "active_llm": {
    "provider_id": "openai",
    "model": "gpt-4o-mini"
  }
}

ModelScope (Ideal para usuários na China):

{
  "providers": {
    "modelscope": {
      "base_url": "https://api-inference.modelscope.cn/v1",
      "api_key": "ms-sua-chave"
    }
  }
}

DashScope (Alibaba Cloud):

{
  "providers": {
    "dashscope": {
      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "api_key": "sk-sua-chave-dashscope"
    }
  }
}

Passo 5: Iniciar o CoPaw e Verificar

Agora vamos iniciar a aplicação e verificar se tudo está funcionando:

copaw app

Após a execução, abra o navegador e acesse:

http://127.0.0.1:8088/

Você deverá ver a interface do CoPaw Console, onde poderá:

Conversar com o assistente de IA
Configurar canais (DingTalk, Feishu, QQ, Discord, etc.)
Gerenciar habilidades e plugins
Testar a conexão com os modelos

[!TIP]
Use o comando CLI copaw models para visualizar rapidamente a configuração atual do modelo e testar a conexão.

Passo 6: Conectar Canais de Chat (Opcional)

Para tornar seu assistente acessível através de aplicativos de mensagens, vamos adicionar um canal. Usando o Discord como exemplo:

Crie um bot no Portal de Desenvolvedores do Discord
Obtenha o Token do seu bot
Adicione a configuração ao copaw.json:

{
  "channels": {
    "discord": {
      "enabled": true,
      "bot_token": "seu-token-de-bot-discord",
      "channel_ids": ["seu-id-de-canal"]
    }
  }
}

Configurações semelhantes se aplicam ao DingTalk, Feishu, QQ e outras plataformas suportadas.

Solução de Problemas Comuns

Aqui estão os problemas mais comuns ao configurar o CoPaw:

Problema 1: Erro 401 Não Autorizado

Sintoma: A requisição da API falha com o código de status 401.

Solução:

Verifique cuidadosamente se a chave API foi copiada corretamente para o providers.json
Valide se a chave expirou ou foi revogada
Para o Defapi, certifique-se de usar o formato correto da chave API

Problema 2: Tempo de Conexão Esgotado (Timeout)

Sintoma: A requisição fica pendente ou expira após 30 segundos.

Solução:

Verifique sua conexão com a internet
Certifique-se de que as configurações de firewall permitem tráfego HTTPS de saída
Para modelos locais (Ollama), garanta que o serviço está rodando na porta correta

Problema 3: Modelo Não Encontrado

Sintoma: Um ID de modelo específico não é reconhecido.

Solução:

Confirme o ID exato do modelo na documentação do provedor
Alguns modelos podem ter restrições regionais — verifique se estão disponíveis na sua área
Tente usar um modelo comum como gpt-4o-mini para validar a conexão básica

Problema 4: Falha na Conexiva Ollama

Sintoma: Não é possível conectar a modelos locais do Ollama.

Solução:

Certifique-se de que o comando ollama serve está rodando em outro terminal
Verifique se a Base URL está definida como http://localhost:11434/v1
Verifique se o Ollama está instalado e acessível no PATH

Problema 5: Arquivo de Configuração Não Encontrado

Sintoma: O CoPaw não encontra o providers.json.

Solução:

Certifique-se de ter rodado copaw init --defaults primeiro
Verifique se o arquivo existe em ~/.copaw/.secret/providers.json
No Windows, utilize %USERPROFILE%\.copaw\.secret\providers.json

Problema 6: Porta Já em Uso

Sintoma: Não é possível iniciar o CoPaw na porta 8088.

Solução:

Outro aplicativo está usando a porta 8088
Altere a porta na configuração ou pare o aplicativo conflitante

Direções Avançadas

Após dominar o básico, aqui estão algumas direções para explorar:

1. Modelos Locais com Foco em Privacidade

O CoPaw suporta a execução de modelos localmente, sem necessidade de chamadas de API externas. Isso é ideal para:

Aplicações sensíveis à privacidade
Operações offline
Redução de custos

Instale o suporte para modelos locais:

pip install 'copaw[llamacpp]'

Em seguida, baixe e utilize modelos como o Qwen3:

copaw models download Qwen/Qwen3-4B-GGUF

2. Habilidades Personalizadas

O CoPaw suporta a extensão de suas funcionalidades através de habilidades personalizadas. As habilidades são carregadas automaticamente do diretório active_skills/. Você pode escrever scripts Python para definir novas ferramentas que a IA pode utilizar.

3. Tarefas Agendadas (Heartbeat)

Use a função de heartbeat do CoPaw para acionar ações periódicas:

Resumos diários de notícias
Lembretes agendados
Geração automatizada de conteúdo

4. Memória e Gerenciamento de Contexto

O CoPaw implementa um gerenciamento inteligente de memória:

Memória de longo prazo para contexto persistente
Compressão de memória baseada em Tokens para maior eficiência
Configuração da janela de contexto conforme o modelo escolhido

5. Fluxos de Trabalho Multi-Agente

Baseado no AgentScope, o CoPaw pode lidar com cenários complexos de multi-agentes, permitindo que diferentes modelos de IA colaborem para completar tarefas.

Resumo

O CoPaw oferece uma base flexível para construir assistentes de IA que operam em múltiplas plataformas. Pontos-chave deste guia:

Instalação Simples — Basta um pip install copaw para começar
Defapi é o Melhor Custo-Benefício — Cerca de 50% mais barato que a API oficial, mantendo total compatibilidade
Configuração Centralizada — Todos os ajustes estão no providers.json
Console Facilita o Gerenciamento — Interface web para testes e configuração
Extensibilidade Nativa — Habilidades, canais e modelos locais oferecem opções ilimitadas de personalização

Comece com o Defapi para obter o melhor equilíbrio entre custo e desempenho. Uma vez familiarizado, explore outros provedores ou modelos locais conforme suas necessidades específicas.

[!TIP]
Lembre-se: o melhor assistente de IA é aquele que se adapta ao seu cenário de uso. Não tenha medo de experimentar diferentes modelos e configurações para encontrar o que funciona melhor para você.

Divirta-se em sua jornada com a IA!