Configuração do assistente de inicialização

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

Ele é diferente do guia de primeiro uso do Desktop

O guia de primeiro uso do Desktop (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:

• 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 continuar a criação do 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.
• Usuários de Docker: o provedor de API e o token já foram configurados no Docker Compose Builder.
• Tenha em mãos um repositório local ou diretório de trabalho para conectar: a etapa 3 pede que você o registre.

Visão geral do assistente

O assistente tem 4 etapas, e a navegação à esquerda mostra o progresso atual:

Etapa	Objetivo	Indicador de conclusão
1. Configuração inicial	Escolher o idioma e o tema da interface	Clicar em “Próximo: criar um projeto”
2. Configurar o Hagicoder	Escolher o CLI e o modelo e criar o Hagicoder padrão	Clicar em “Confirmar e criar Hagicoder” ou já existir um Agent disponível
3. Criar um projeto	Criar pelo menos um projeto	A etapa do projeto mostra “Etapa do projeto concluída”
4. Guia da comunidade	Conhecer os pontos de entrada da comunidade	Clicar em “Comece a usar HagiCode”

Etapa 1: Configuração inicial

Objetivo: definir o idioma e o tema da interface.

1. Em “Escolher o idioma da interface”, selecione um idioma. Isso altera apenas o texto da interface e não muda o estilo de linguagem do Hagicoder.
2. Em “Escolher tema”, selecione um tema. Atualmente há “Primavera Clara” e “Primavera Escura”.
3. Clique em “Próximo: criar um projeto”.

Etapa 2: Configurar o Hagicoder

Objetivo: criar o Agent padrão, cujo nome é fixo: Hagicoder.

Se o sistema já tiver Agents, esta etapa mostra “Agentes existentes encontrados”, e basta manter a escalação atual. Caso contrário:

1. Escolha o AgentCLI mais usado (“Escolha seu AgentCLI principal”): a lista suspensa mostra apenas os CLIs detectados na máquina. Se aparecer o aviso de que nenhum AgentCLI local foi detectado, conclua a instalação e o login seguindo Instalação do AI Agent CLI e depois volte para atualizar.
2. Escolha o modelo mais usado (“Escolha seu Modelo principal”):
   • Selecionar um modelo existente: reutiliza um modelo já existente para esse CLI; é possível pesquisar por nome ou ID do modelo.
   • Inserir um modelo personalizado: digite o nome do modelo manualmente, por exemplo gpt-5.5, glm-5.1 ou claude-opus-4-7; ao criar, o modelo correspondente é reutilizado ou criado automaticamente.
3. (Opcional) Clique em “Testar disponibilidade”: envia uma verificação ping-pong ao CLI e ao modelo selecionados para confirmar que o modelo consegue responder pong. O resultado do teste vale apenas para a combinação atual de CLI e modelo, e é preciso testar de novo depois de qualquer alteração; criar o Hagicoder não exige que o teste passe.
4. (Opcional) Clique em “Embaralhar” para trocar a aparência padrão; o avatar é sorteado da galeria de imagens.
5. Clique em “Confirmar e criar Hagicoder”. Depois de criado, ele é adicionado à equipe de emergência, e o CLI e o modelo escolhidos são gravados em sua configuração padrão.

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

• Meu CLI não aparece na lista: confirme que ele está instalado e disponível no ambiente em que o Hagicode Server é executado; se você usa o Desktop, reinicie-o para atualizar o PATH.
• O teste de disponibilidade falha: as causas comuns são CLI sem login, token inválido ou nome de modelo que esse CLI não aceita. Primeiro, execute uma conversa mínima com esse CLI no terminal para confirmar que ele funciona por si só.
• Falha ao adicionar à equipe de emergência: a página oferece “Tentar adicionar novamente à equipe de emergência”; basta tentar de novo.

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 primeiro detecta se já existe um projeto local: se houver, mostra o resumo do projeto atual; se não, é preciso registrar um.

1. Em “Registre um projeto local”, informe o nome do projeto, o caminho da pasta 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 e continuar” para ir à próxima etapa; se quiser ficar nesta etapa e continuar adicionando projetos, clique em “Criar projeto”.
3. Se já houver projetos, você pode clicar diretamente em “Continuar para a comunidade”, “Crie outro projeto” ou voltar à configuração (“Voltar à configuração”).

Quer experimentar primeiro com um projeto de exemplo?

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

Problemas comuns

• Falha na validação do caminho: confirme que o caminho da pasta está correto e realmente existe; em implantações com Docker, informe o diretório montado que pode ser acessado dentro do contêiner, e não um caminho do host.

Etapa 4: Guia da comunidade

Objetivo: deixar os pontos de entrada da comunidade à mão.

A página “Sobre” do site oficial reúne todos os canais da comunidade. Os links abrem em uma nova aba; depois de ver, volte ao assistente e clique em “Comece a usar HagiCode” para entrar no espaço de trabalho. Mesmo depois desta etapa, você pode reabrir o assistente a qualquer momento.

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.