Onboarding
A first run does not open the wizard. OpenCrabs goes straight to the chat, with its built-in provider already provisioned and the agent greeting you. The onboarding wizard is opt-in: run opencrabs --onboard, or /onboard from inside a session.
Os vídeos com demonstrações estão na página Vídeos de Onboarding.
Início Rápido (3 minutos)
O caminho rápido permite-te conversar com o agente em menos de 3 minutos.
| Passo | Ação |
|---|---|
| 1. Modo | Prime Enter em QuickStart |
| 2. Espaço de trabalho | Prime Enter para aceitar o caminho predefinido |
| 3. Provider | Usa as setas para escolher o teu provider (por exemplo, z.ai) e prime Enter. Usa a seta para baixo para escolher um plano (por exemplo, Coding) e prime Enter |
| 4. Chave de API | Cola a tua chave (Cmd+V / Ctrl+V / Cmd+Shift+V / Ctrl+Shift+V) e prime Enter. A lista de modelos carrega em tempo real |
| 5. Modelo | Usa as setas para escolher o teu modelo (por exemplo, gemini-2.5-pro) e prime Enter |
| 6. Daemon | Usa as setas para escolher se o daemon corre em segundo plano e prime Enter |
| 7. Vibe Check | Todas as verificações devem mostrar ✅. Prime Enter |
| 8. Sobre ti | Escreve algo sobre ti. Quanto mais o agente souber, melhor. Prime Enter |
| 9. Sobre o agente | Escreve algo sobre a personalidade do agente. Prime Enter |
| 10. Chat | Está tudo pronto. Começa a falar com o teu agente |
Configuração Avançada (7 minutos)
Configuração completa com Telegram, voz local, visão e geração de imagens.
| Passo | Ação |
|---|---|
| 1. Modo | Prime Enter em QuickStart |
| 2. Espaço de trabalho | Prime Enter para aceitar o caminho predefinido |
| 3. Provider | Usa as setas para escolher o teu provider (por exemplo, z.ai) e prime Enter. Usa a seta para baixo para escolher um plano e prime Enter |
| 4. Chave de API | Cola a tua chave e prime Enter. A lista de modelos carrega em tempo real |
| 5. Modelo | Usa as setas para escolher o teu modelo e prime Enter |
| 6. Channels | Usa as setas para escolher Other, prime Space para selecionar Telegram e prime Enter. Cola o token do bot, segue as instruções para obter o teu chat ID e prime Enter. Escolhe o modo de menção e prime Enter. Quando aparecer Connected, prime Enter outra vez. Usa a seta para baixo para escolher Continue e prime Enter |
| 7. STT | Escolhe Local e prime Enter. Escolhe o tamanho do modelo (por exemplo, tiny para mais rapidez) e prime Enter |
| 8. TTS | Escolhe Local outra vez e prime Enter. Escolhe uma voz (por exemplo, Ryan) e prime Enter. Espera que o modelo seja transferido, usa a seta para baixo para escolher Continue e prime Enter |
| 9. Imagem | Prime Space para selecionar Vision e Image Generation e prime Enter. Cola a tua chave de API do Gemini e prime Enter |
| 10. Daemon | Usa as setas para escolher se o daemon corre em segundo plano e prime Enter |
| 11. Vibe Check | Todas as verificações devem mostrar ✅. Prime Enter |
| 12. Sobre ti | Escreve algo sobre ti. Quanto mais o agente souber, melhor. Prime Enter |
| 13. Sobre o agente | Escreve algo sobre a personalidade do agente. Prime Enter |
| 14. Chat | Está tudo pronto. Começa a falar com o teu agente |
Fluxo de onboarding
O assistente é uma TUI controlada pelo teclado, com 8 passos. Navega com as setas, usa Tab para avançar e Esc para voltar atrás.
| Passo | Ecrã | O que fazes |
|---|---|---|
| 1 | Seleção de modo | Escolhe QuickStart (sem channels) ou Advanced |
| 2 | Espaço de trabalho | Escolhe uma pasta de trabalho para as operações com ficheiros |
| 3 | Provider e autenticação | Escolhe o provider → cola a chave de API → escolhe o modelo (obtido em tempo real) |
| 4 | Channels | Space para ativar ou desativar channels → Enter em cada um para configurar |
| 5 | Voz | Provider de STT (Groq, Whisper local ou desativado) + voz de TTS |
| 6 | Imagem | Interruptor de visão + modelo de geração + chave de API |
| 7 | Daemon | Instala o daemon em segundo plano (opcional) |
| 8 | Configuração do brain | Gera automaticamente o SOUL.md a partir do teu perfil |
Configuração de channels (passo 4)
O ecrã de channels lista 5 integrações: Telegram, Discord, WhatsApp, Slack e Trello.
Spaceativa ou desativa um channelEnternum channel ativado abre o respetivo ecrã de configuração (token, IDs, listas de permissões)Enterem Continue ouTabavança para o passo seguinte- Cada ecrã de configuração de channel tem um botão Test Connection
Consulta Channels Overview para o guia completo de navegação.
Voltar a executar a configuração
Podes saltar para qualquer passo sem voltar a executar o assistente completo:
| Comando | Passo |
|---|---|
/onboard | Assistente completo |
/onboard:provider | Seleção de provider e modelo |
/onboard:channels | Seletor de channels |
/onboard:voice | Configuração de voz |
/onboard:image | Configuração de imagem |
/onboard:brain | Geração de ficheiros brain |
Depois do onboarding, o agente arranca e apresenta-se. Lê os seus ficheiros brain (SOUL.md, AGENTS.md, TOOLS.md) e começa uma conversa.
Bootstrap
Na primeira execução, o agente passa por uma fase de bootstrap:
- Fica a conhecer-te (nome, preferências, forma de trabalhar)
- Define a sua identidade (nome, personalidade, emoji)
- Abre o
SOUL.mdcontigo para discutir valores - Configura o
USER.mdcom o teu perfil
O ficheiro de bootstrap (BOOTSTRAP.md) apaga-se quando termina.
Migrar a partir de outra ferramenta
Já usas ClaudeCode, OpenClaw, Hermes ou outro harness de agente de IA? O teu agente pode migrar os teus dados existentes (memória, skills, comandos personalizados, preferências) para os seus próprios ficheiros brain, em linguagem natural. Não é preciso mover ficheiros manualmente.
Funciona com qualquer agente ou harness de programação que guarde a configuração localmente. A migração procura no teu sistema de ficheiros as pastas de configuração da outra ferramenta, lê o conteúdo e converte-o para o formato de ficheiros brain do OpenCrabs (SOUL.md, USER.md, TOOLS.md, MEMORY.md, AGENTS.md, CODE.md).
Migração guiada
Se quiseres rever o que é migrado antes de a migração acontecer:
Procura localmente os meus dados do ClaudeCode/OpenClaw/Hermes (ou de qualquer outro harness de agente que eu usasse), faz uma auditoria de uma migração para os nossos próprios ficheiros brain, informa-me quando terminares e executa só quando eu confirmar e aprovar.
O agente vai:
- Procurar no teu sistema de ficheiros as pastas de configuração da outra ferramenta
- Ler e analisar todos os ficheiros relevantes (memória, comandos, skills, preferências)
- Produzir uma auditoria que mostra exatamente o que vai para onde
- Esperar pela tua confirmação
- Executar a migração e apresentar um resumo completo
Migração autónoma
Se só queres que fique feito:
Procura localmente os meus dados existentes de agentes ou harness e migra tudo para os nossos próprios ficheiros brain, sem precisar da minha aprovação. Avança, planeia e executa, e informa-me quando terminares, com um resumo completo.
O agente salta a etapa de auditoria, planeia a migração internamente, executa-a e dá-te um resumo de tudo o que foi movido.
O que é mapeado
| Origem | Destino | Exemplo |
|---|---|---|
| Memória / CLAUDE.md / ficheiros de contexto | MEMORY.md | Decisões do projeto, contexto anterior |
| Comandos personalizados | commands.toml | Comandos slash e as respetivas definições |
| Skills / instruções do agente | AGENTS.md, TOOLS.md | Regras de fluxo de trabalho, configurações das ferramentas |
| Preferências / perfil do utilizador | USER.md | Nome, fuso horário, estilo de programação |
| Normas de programação / regras de linting | CODE.md | Guias de estilo, convenções |
Dica: Executa a migração logo a seguir ao onboarding, enquanto o contexto está fresco. O agente já tem o teu
USER.mde oSOUL.mddo assistente, por isso pode fazer a fusão de forma inteligente em vez de substituir.
Comandos principais
| Comando | Descrição |
|---|---|
/help | Mostra todos os comandos disponíveis |
/models | Muda de provider ou de modelo |
/new | Cria uma nova session |
/sessions | Muda entre sessions |
/cd | Muda a pasta de trabalho |
/compact | Compacta o contexto manualmente |
/evolve | Transfere a versão mais recente |
/rebuild | Compila a partir do código-fonte |
/approve | Define a política de aprovação |
Modos de aprovação
Controla o grau de autonomia do agente:
| Modo | Comportamento |
|---|---|
/approve | Pergunta antes de cada uso de ferramenta (predefinido) |
/approve auto | Aprova automaticamente nesta session |
/approve yolo | Aprova sempre automaticamente (mantém-se) |
Pasta de trabalho
O agente opera dentro de uma pasta de trabalho para as operações com ficheiros. Muda-a com:
- Comando
/cdno chat - Seletor de pastas na TUI (Tab para selecionar)
- Ferramenta
config_manager set_working_directory
A pasta de trabalho é guardada por session. Ao mudar de session, a pasta é restaurada automaticamente.
Dica de filtro de modelos (v0.3.78)
O seletor de modelos do onboarding passa agora a mostrar sempre uma dica de filtro acima da lista de modelos (“Type to filter…”). Antes, a dica só aparecia depois de começares a escrever, por isso os utilizadores não sabiam que existia filtragem. Além disso, um ID de modelo escrito exatamente tem agora prioridade sobre uma correspondência parcial: se escreveres claude-opus-4-8 exatamente, seleciona esse modelo, mesmo que outros modelos contenham a mesma sequência de caracteres.