Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

Primeiro arranque: cais direto no chat

Não há assistente numa instalação nova. O OpenCrabs abre o chat, liga o provider integrado e diz olá:

  1. config.toml e keys.toml são escritos a partir do exemplo incluído, se ainda não existirem.
  2. [providers.opencrabs] fica ligado. O exemplo traz a secção desligada, por isso é isto que a torna o provider ativo.
  3. A instalação pede o seu próprio token a inference.opencrabs.com e guarda-o em keys.toml. O token é reutilizado em todos os arranques seguintes, por isso só acontece uma vez.
  4. O agente lê os seus ficheiros de cérebro e cumprimenta-te com o modelo em que está a correr.

Se o pedido do token falhar (offline, proxy inacessível), aterras na mesma num chat a funcionar com uma linha a dizer o que aconteceu. Escreve /onboard para escolher outro provider, ou corrige a ligação e reinicia. O onboarding só é marcado como concluído quando o provider integrado arrancou de facto, por isso o arranque seguinte tenta outra vez em vez de te deixar num chat sem provider.

O que tens sem configurares nada

CapacidadeModelNotes
Chatdeepseek-v4.1-flash200k de contexto, fixo
Visãodeepseek-v4.1-flashAnexa uma imagem e funciona
Geração de imagensgemini-2.5-flash-imageServido só na rota de imagens, nunca como modelo de chat
Voz a entrarqwen3.8-omni-flashUma nota de voz é transcrita e respondida em texto
Voz a sairnão servidoPrecisa de outro motor TTS, ver Voz

Gratuito, sem conta, sem chave para colar, sem limites de uso durante a fase experimental. O proxy limita abusos (enxurradas de pedidos, criação de instalações em massa) e o uso normal não lhes toca. Os pedidos vão para inference.opencrabs.com, que os reencaminha para o host do modelo a montante. Detalhe completo, incluindo onde vive o token e como sair: OpenCrabs (integrado).

Para mudares para outro provider mais tarde, escreve /models e escolhe um, ou corre /onboard e escolhe Advanced.

Quick Start (o assistente, 1 minuto)

O assistente é opcional: opencrabs --onboard antes do primeiro arranque, ou /onboard dentro de uma sessão. Escolhe QuickStart para manter as omissões e saltar a configuração de canais e voz.

PassoAção
1. ModoSetas até QuickStart, carrega em Enter
2. Espaço de trabalhoPrime Enter para aceitar o caminho predefinido
3. ProviderSetas até ao provider que queres, carrega em Enter. OpenCrabs (integrado) não precisa de chave; qualquer outro pede uma
4. Chave de APISó para um provider que precise de chave. Cola-a (Cmd+V / Ctrl+V), carrega em Enter. A lista de modelos carrega ao vivo
5. ModeloUsa as setas para escolher o teu modelo e prime Enter
6. DaemonSetas para escolher se corre como daemon em segundo plano, carrega em Enter
7. Vibe CheckTodas as verificações devem mostrar ✅. Prime Enter
8. Sobre tiEscreve algo sobre ti. Quanto mais o agente souber, melhor. Carrega em Enter
9. Sobre o agenteEscreve algo sobre a personalidade do agente. Prime Enter
10. ChatEstás dentro. O agente cumprimenta-te e pergunta só o que ainda falta

Configuração Avançada (7 minutos)

Configuração completa com Telegram, voz local, visão e geração de imagens.

PassoAção
1. ModoSetas até Advanced, carrega em Enter
2. Espaço de trabalhoPrime Enter para aceitar o caminho predefinido
3. ProviderUsa 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 APICola a tua chave e prime Enter. A lista de modelos carrega em tempo real
5. ModeloUsa as setas para escolher o teu modelo e prime Enter
6. ChannelsUsa 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. STTEscolhe Local e prime Enter. Escolhe o tamanho do modelo (por exemplo, tiny para mais rapidez) e prime Enter
8. TTSEscolhe 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. ImagemPrime Space para selecionar Vision e Image Generation e prime Enter. Cola a tua chave de API do Gemini e prime Enter
10. DaemonUsa as setas para escolher se o daemon corre em segundo plano e prime Enter
11. Vibe CheckTodas as verificações devem mostrar ✅. Prime Enter
12. Sobre tiEscreve algo sobre ti. Quanto mais o agente souber, melhor. Prime Enter
13. Sobre o agenteEscreve algo sobre a personalidade do agente. Prime Enter
14. ChatEstá 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.

PassoEcrãO que fazes
1Seleção de modoEscolhe QuickStart (sem channels) ou Advanced
2Espaço de trabalhoEscolhe uma pasta de trabalho para as operações com ficheiros
3Provider e autenticaçãoEscolhe o provider → cola a chave de API → escolhe o modelo (obtido em tempo real)
4ChannelsSpace para ativar ou desativar channels → Enter em cada um para configurar
5VozProvider de STT (Groq, Whisper local ou desativado) + voz de TTS
6ImagemInterruptor de visão + modelo de geração + chave de API
7DaemonInstala o daemon em segundo plano (opcional)
8Configuração do brainGera 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.

  • Space ativa ou desativa um channel
  • Enter num channel ativado abre o respetivo ecrã de configuração (token, IDs, listas de permissões)
  • Enter em Continue ou Tab avanç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:

ComandoPasso
/onboardAssistente completo
/onboard:providerSeleção de provider e modelo
/onboard:channelsSeletor de channels
/onboard:voiceConfiguração de voz
/onboard:imageConfiguração de imagem
/onboard:brainGeraçã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.md contigo para discutir valores
  • Configura o USER.md com 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:

  1. Procurar no teu sistema de ficheiros as pastas de configuração da outra ferramenta
  2. Ler e analisar todos os ficheiros relevantes (memória, comandos, skills, preferências)
  3. Produzir uma auditoria que mostra exatamente o que vai para onde
  4. Esperar pela tua confirmação
  5. 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

OrigemDestinoExemplo
Memória / CLAUDE.md / ficheiros de contextoMEMORY.mdDecisões do projeto, contexto anterior
Comandos personalizadoscommands.tomlComandos slash e as respetivas definições
Skills / instruções do agenteAGENTS.md, TOOLS.mdRegras de fluxo de trabalho, configurações das ferramentas
Preferências / perfil do utilizadorUSER.mdNome, fuso horário, estilo de programação
Normas de programação / regras de lintingCODE.mdGuias 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.md e o SOUL.md do assistente, por isso pode fazer a fusão de forma inteligente em vez de substituir.

Comandos principais

ComandoDescrição
/helpMostra todos os comandos disponíveis
/modelsMuda de provider ou de modelo
/newCria uma nova session
/sessionsMuda entre sessions
/cdMuda a pasta de trabalho
/compactCompacta o contexto manualmente
/evolveTransfere a versão mais recente
/rebuildCompila a partir do código-fonte
/approveDefine a política de aprovação

Modos de aprovação

Controla o grau de autonomia do agente:

ModoComportamento
/approvePergunta antes de cada uso de ferramenta (predefinido)
/approve autoAprova automaticamente nesta session
/approve yoloAprova 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 /cd no 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.