Configuração do assistente de inicialização

Seja pela Microsoft Store ou pelo Desktop, ao abrir a interface Web do HagiCode pela primeira vez o assistente de inicialização aparece automaticamente. Depois de concluí-lo, você terá um Hagicoder padrão funcional e pelo menos um projeto, e poderá iniciar diretamente sua primeira sessão.

Ele é diferente do guia de primeiro uso do Desktop

O “guia de primeiro uso” do Desktop na primeira inicialização (escolher o idioma, confirmar os documentos legais e baixar o Hagicode Server) acontece antes de a interface Web aparecer; veja a Instalação do Desktop. Esta página descreve o assistente de inicialização que aparece depois, na interface Web.

Antes de começar

Confirme primeiro o seguinte:

• Pelo menos um Agent CLI instalado e com login feito. O assistente lista apenas os CLIs detectados na máquina em que o Hagicode Server está em execução; se nenhum for detectado, não é possível criar o Hagicoder. Para os CLIs compatíveis e as formas de instalação, veja Instalação do AI Agent CLI.
• Usuários de Desktop / Store: o Node.js 24+ e o Git já foram instalados conforme o Guia de instalação.
• Tenha em mãos um repositório local ou diretório de trabalho para conectar: a etapa 3 pedirá que você o registre, e o caminho precisa existir de fato.

Visão geral do assistente

O assistente tem 4 etapas; a navegação à esquerda mostra o progresso atual e o selo no topo exibe “N de 3 etapas prontas”. As 3 primeiras etapas são obrigatórias, e a etapa 4, “Comunidade”, é marcada como opcional (“Opcional”):

Etapa	Objetivo	Indicador de conclusão
1. Idioma e tema	Escolher o idioma da interface e um tema de cores sazonal	Clicar em “Continuar” para confirmar o idioma
2. Hagicoder	Escolher o CLI e o modelo e criar o Hagicoder padrão	O Agente exibe “O Agente está em Tripulação substituta”
3. Projeto	Registrar pelo menos um projeto local	A etapa de projeto exibe “Etapa de projeto concluída”
4. Comunidade (opcional)	Iniciar a primeira conversa ou ver os pontos de entrada da comunidade	Clicar em “Concluir”

“Lembrar mais tarde”, no canto inferior esquerdo, fecha o assistente por enquanto e lembra você depois; “Não mostrar novamente” desativa a abertura automática. Com qualquer uma das duas opções, você pode reabrir o assistente a qualquer momento pela entrada “Assistente” no topo da página, e as etapas não concluídas continuam pendentes.

Etapa 1: Idioma e tema

Objetivo: definir o idioma da interface e o tema de cores.

1. Em “Escolha o idioma da interface”, selecione um idioma (há 10 disponíveis). Isso altera apenas o idioma da interface do app; heróis e projetos não são afetados.
2. Em “Escolha um tema de cores”, selecione a variante “Luz” ou “Escuro” de qualquer uma das estações: primavera, verão, outono ou inverno. O tema é aplicado na hora e pode ser alterado depois pela entrada de temas no topo da página.
3. Clique em “Continuar”. Depois de confirmar o idioma, você avança para a próxima etapa, Hagicoder.

Etapa 2: Configurar o Hagicoder

Objetivo: criar o Agente padrão, cujo nome é sempre Hagicoder, e adicioná-lo à tripulação substituta.

Se o sistema já tiver algum Agente, esta etapa exibe “Agentes encontrados” ou diretamente “O Agente está em Tripulação substituta”:

• Se houver um Agente que não está na tripulação substituta, você pode clicar em “Adicionar a Tripulação substituta” ou escolher “Criar um novo Agente”. O assistente não o adiciona automaticamente.
• Se ele já estiver na tripulação substituta, basta clicar em “Próximo: criar um projeto”.

Caso contrário, crie-o seguindo este fluxo:

1. Escolha seu AgentCLI principal: somente os CLIs detectados nesta máquina são exibidos; o cartão selecionado mostra uma marca de seleção à direita.

2. Escolha seu Modelo principal:

   • Selecione um modelo existente na lista; você pode filtrar por nome ou ID do modelo na caixa de pesquisa acima.
   • Ou digite o nome do modelo manualmente em “Digitar um modelo personalizado”, por exemplo gpt-5.5, glm-5.1 ou claude-opus-4-7; ao criar, o backend reutiliza ou cria o modelo correspondente.

   

3. (Recomendado) Clique em “Executar teste de conexão”: verifica se o CLI escolhido está disponível. Ele não envia nenhum prompt ao modelo, portanto só confirma que o CLI pode ser chamado, não as respostas do modelo. O resultado “A CLI está disponível” indica que o teste passou; se o teste falhar ou expirar, isso não impede a criação, mas o Agente pode não funcionar corretamente até que o CLI seja corrigido.

4. (Opcional) Escolha um retrato padrão: selecione um dos retratos sugeridos ou clique em “Embaralhar” para ver outras opções.

5. Clique em “Criar Agente”. Se tudo der certo, a página exibe “O Agente está em Tripulação substituta”, e o CLI e o modelo selecionados são gravados na configuração padrão do Hagicoder.

   

6. Clique em “Próximo: criar um projeto”.

Quais CLIs são compatíveis

Os CLIs que podem ser escolhidos no assistente dependem dos Agent CLIs instalados e detectados na máquina, e não se limitam a um só. O escopo completo de compatibilidade e as formas de instalação seguem Instalação do AI Agent CLI; entre eles, Hermes, Gemini e DeepAgents exigem que a instalação manual ou a autenticação sejam concluídas antes.

Problemas comuns

• Aparece “Nenhuma CLI local disponível”: instale primeiro um CLI neste computador e faça login seguindo Instalação do AI Agent CLI; depois clique em “Detectar novamente”. Você também pode clicar em “Pular por enquanto”: esta etapa continua pendente e o assistente lembrará você depois.
• Meu CLI não aparece na lista: confirme que ele está instalado e disponível no ambiente em que o Hagicode Server está em execução; no Desktop, reinicie o Desktop para atualizar o PATH.
• O teste de conexão falhou: a página mostra o motivo da falha. As causas comuns são o CLI ainda não estar com login feito ou o token ser inválido. Execute primeiro, no terminal, uma conversa mínima com esse CLI para confirmar que ele funciona por si só e depois clique em “Executar novamente”.
• O Agente foi criado, mas falhou ao adicioná-lo à tripulação substituta: a página oferece “Tentar adicionar a Tripulação substituta novamente”; a nova tentativa só adiciona o mesmo Agente, sem criar um duplicado.

Etapa 3: Criar um projeto

Objetivo: registrar pelo menos um projeto para que as sessões seguintes tenham um diretório de trabalho legível. O assistente verifica primeiro se já existe algum projeto: se não houver, exibe o formulário de registro; se já houver, exibe o resumo do projeto atual.

1. Em “Registrar um projeto local”, preencha o nome do projeto (obrigatório), o caminho da pasta (obrigatório) e, opcionalmente, a descrição do projeto. Os campos e a validação do caminho são exatamente os mesmos da caixa de diálogo “Novo Projeto” da interface principal.
2. Clique em “Criar projeto e continuar”. O caminho é validado ao salvar; se a validação passar, o projeto é criado e o assistente avança automaticamente para a próxima etapa.
3. Se você voltar a esta etapa depois de criar o projeto, verá “Resumo atual dos projetos” e a marca “Etapa de projeto concluída”. Nesse ponto, você pode clicar em “Continuar” para ir à comunidade ou em “Adicionar outro projeto” para registrar mais projetos (salve com “Adicionar projeto” ou volte ao resumo com “Cancelar”).

Quer experimentar primeiro com um projeto de exemplo?

O assistente só oferece o registro de um projeto local. O “Projeto de demonstração” fica na aba “Projeto de demonstração” da caixa de diálogo “Novo Projeto” da interface principal: ele clona e registra automaticamente o repositório oficial MonoSpecs Demo, com o caminho padrão data/repos/monospecs-demo; o diretório real depende da configuração do diretório de dados (DataDir) em tempo de execução. Esse método exige Git e acesso ao GitHub.

Problemas comuns

• Aparece “Falha ao criar o projeto”: confirme que o caminho da pasta está correto e existe de fato.

Etapa 4: Comunidade

Objetivo: confirmar que tudo está pronto e escolher o que fazer a seguir. Esta etapa é opcional.

Depois que as três etapas obrigatórias forem concluídas, a página exibe “O HagiCode está pronto para uso” e o status de conclusão das três etapas obrigatórias:

• Começar a primeira conversa: ao clicar, o assistente é fechado e a caixa de nova conversa é aberta no espaço de trabalho. A conversa precisa de um projeto; se você ainda não tiver nenhum, aparece “Crie um projeto primeiro” junto com o botão “Ir para a etapa de projeto”.
• Sobre o HagiCode: ao clicar em “Abrir a página Sobre”, a página “Sobre” do site oficial é aberta no navegador, reunindo todos os canais da comunidade; o assistente continua aberto.
• Concluir: ao clicar em “Concluir”, no canto inferior direito, o assistente é fechado. Se ainda houver etapas obrigatórias não concluídas, elas continuam pendentes e você pode reabrir o assistente pela entrada “Assistente” no topo da página.

Próximos passos

Criar uma sessão de conversaComece com o modo somente leitura padrão para que a IA entenda o projeto e, depois de confirmar o rumo, decida se vai mudar para o modo de edição.

Criar uma sessão de propostaQuando precisar dividir o plano e revisar a abordagem, use a sessão de proposta para transformar ideias em um plano de implementação estruturado.