초기화 마법사 설정

Microsoft Store, Desktop, Docker Compose 중 어떤 방식으로 설치했든 HagiCode의 Web 인터페이스를 처음 열면 초기화 마법사가 나타납니다. 이 마법사를 마치면 사용할 수 있는 기본 Hagicoder와 최소 하나의 프로젝트가 준비되어 첫 번째 세션을 바로 시작할 수 있습니다.

Desktop의 최초 설정과는 다릅니다

Desktop을 처음 실행할 때의 “최초 설정”(언어 선택, 법적 문서 확인, Hagicode Server 다운로드)은 Web 인터페이스가 나타나기 전에 진행되며, Desktop 설치에서 설명합니다. 이 페이지는 그 이후 Web 인터페이스에서 나타나는 초기화 마법사를 설명합니다.

시작하기 전에

먼저 다음을 확인하세요.

• Agent CLI를 최소 하나 설치하고 로그인해 두세요. 마법사에는 Hagicode Server가 실행되는 컴퓨터에서 감지된 CLI만 표시되며, 감지된 CLI가 없으면 Hagicoder를 만들 수 없습니다. 지원하는 CLI와 설치 방법은 AI Agent CLI 설치를 참고하세요.
• Desktop / Store 사용자: 설치 가이드에 따라 Node.js 24+와 Git을 설치해 두어야 합니다.
• Docker 사용자: Docker Compose Builder에서 API 제공자와 Token을 이미 설정해 두어야 합니다.
• 연결할 로컬 저장소 또는 작업 디렉터리를 준비해 두세요. 3단계에서 등록합니다.

마법사 개요

마법사는 4개 단계로 구성되며, 왼쪽 내비게이션에 현재 진행 상황이 표시됩니다.

단계	목표	완료 기준
1. 초기 설정	인터페이스 언어와 테마 선택	“다음: Hagicoder 설정” 클릭
2. Hagicoder 설정	CLI와 모델을 선택해 기본 Hagicoder 생성	“확인 후 Hagicoder 생성” 클릭, 또는 사용할 수 있는 에이전트가 이미 있음
3. 프로젝트 만들기	최소 하나의 프로젝트 생성	프로젝트 단계에 “프로젝트 단계 완료” 표시
4. 커뮤니티 안내	커뮤니티 진입점 확인	“HagiCode 사용 시작” 클릭

1단계: 초기 설정

목표: 인터페이스 언어와 테마를 정합니다.

1. “인터페이스 언어 선택”에서 언어를 하나 고릅니다. 인터페이스 텍스트만 바뀌며 Hagicoder의 언어 스타일은 바뀌지 않습니다.
2. “테마 선택”에서 테마를 하나 고릅니다. 현재 “봄 라이트”와 “봄 다크”를 제공합니다.
3. “다음: Hagicoder 설정”을 클릭합니다.

2단계: Hagicoder 설정

목표: 기본 에이전트를 만듭니다. 이름은 Hagicoder로 고정됩니다.

시스템에 이미 에이전트가 있으면 이 단계에 “기존 에이전트 발견됨”이 표시되며, 기존 구성을 그대로 사용하면 됩니다. 그렇지 않다면 다음 순서로 진행합니다.

1. 주로 사용하는 AgentCLI 선택: 드롭다운에는 로컬에서 감지된 CLI만 표시됩니다. 사용할 수 있는 CLI가 감지되지 않았다는 메시지가 나오면, 먼저 AI Agent CLI 설치에 따라 설치와 로그인을 마친 뒤 돌아와 새로 고치세요.
2. 주로 사용하는 모델 선택:
   • 기존 템플릿 선택: 해당 CLI에 이미 있는 모델 템플릿을 재사용하며, 이름이나 모델 ID로 검색할 수 있습니다.
   • 사용자 지정 모델 입력: gpt-5.5, glm-5.1, claude-opus-4-7처럼 모델 이름을 직접 입력하면, 생성할 때 해당 템플릿이 자동으로 재사용되거나 새로 만들어집니다.
3. (선택) “가용성 테스트 실행” 클릭: 선택한 CLI와 모델에 ping-pong 검증을 한 번 보내 모델이 pong을 반환하는지 확인합니다. 테스트 결과는 현재의 CLI와 모델 조합에만 유효하며, 변경하면 다시 테스트해야 합니다. Hagicoder를 만들 때 테스트 통과가 필수는 아닙니다.
4. (선택) “섞기” 클릭: 기본 이미지를 바꿉니다. 아바타는 이미지 라이브러리에서 무작위로 뽑힙니다.
5. “확인 후 Hagicoder 생성”을 클릭합니다. 생성에 성공하면 긴급 팀에 추가되고, 선택한 CLI와 모델이 기본 구성으로 기록됩니다.

지원하는 CLI

마법사에서 선택할 수 있는 CLI는 로컬에 설치되어 감지된 Agent CLI에 따라 달라지며, 특정 CLI 하나로 제한되지 않습니다. 전체 지원 범위와 설치 방법은 AI Agent CLI 설치를 기준으로 하며, 그중 Hermes, Gemini, DeepAgents는 먼저 수동 설치 또는 인증을 마쳐야 합니다.

자주 발생하는 문제

• 목록에 내 CLI가 없습니다: Hagicode Server가 실행되는 환경에서 해당 CLI가 설치되어 있고 사용할 수 있는지 확인하세요. Desktop 사용자는 Desktop을 다시 시작해 PATH를 새로 읽게 하세요.
• 가용성 테스트 실패: 흔한 원인은 CLI에 아직 로그인하지 않았거나, 토큰이 유효하지 않거나, 해당 CLI가 모델 이름을 지원하지 않는 경우입니다. 먼저 터미널에서 해당 CLI로 최소한의 대화를 실행해 CLI 자체가 동작하는지 확인하세요.
• 긴급 팀 추가 실패: 페이지에 “긴급 팀 추가 재시도”가 표시되므로, 다시 시도하면 됩니다.

3단계: 프로젝트 만들기

목표: 이후 세션이 읽을 수 있는 작업 디렉터리를 갖도록 최소 하나의 프로젝트를 등록합니다. 마법사는 먼저 로컬 프로젝트가 이미 있는지 감지하며, 이미 있으면 현재 프로젝트 요약을 표시하고 없으면 먼저 하나를 등록해야 합니다.

1. “로컬 프로젝트 1개 등록”에서 프로젝트 이름, 폴더 경로, 선택 사항인 프로젝트 설명을 입력합니다. 필드와 경로 검증은 메인 화면의 “새 프로젝트” 대화 상자와 완전히 같습니다.
2. “만들고 계속하기”를 클릭하면 다음 단계로 이동합니다. 이 단계에 머물며 계속 추가하려면 “프로젝트 생성”을 클릭하세요.
3. 이미 프로젝트가 있다면 바로 “커뮤니티로 계속하기”를 클릭하거나, “다른 프로젝트 만들기”를 선택하거나, 설정으로 돌아갈 수 있습니다(“설정으로 돌아가기”).

예제 프로젝트로 먼저 체험해 보고 싶으신가요?

마법사에서는 로컬 프로젝트 등록만 제공합니다. “데모 프로젝트”는 메인 화면의 “새 프로젝트” 대화 상자에 있는 “데모 프로젝트” 탭에 있으며, 공식 MonoSpecs Demo 저장소를 자동으로 클론하고 등록합니다. 기본 경로는 data/repos/monospecs-demo이며, 실제 디렉터리는 런타임 데이터 디렉터리(DataDir) 설정을 따릅니다. 이 방식에는 Git이 필요하고 GitHub에 접근할 수 있어야 합니다.

자주 발생하는 문제

• 경로 검증 실패: 폴더 경로가 올바르고 실제로 존재하는지 확인하세요. Docker 배포에서는 호스트의 경로가 아니라 컨테이너 안에서 접근할 수 있는 마운트 디렉터리를 입력해야 합니다.

4단계: 커뮤니티 안내

목표: 커뮤니티 진입점을 가까이에 둡니다.

공식 웹사이트의 “정보” 페이지에 전체 커뮤니티 링크가 모여 있습니다. 링크를 클릭하면 새 탭에서 열리며, 확인한 뒤 마법사로 돌아와 “HagiCode 사용 시작”을 클릭하면 작업 공간으로 들어갑니다. 이 단계 이후에도 언제든지 마법사를 다시 열 수 있습니다.

다음 단계

대화 세션 만들기먼저 기본 읽기 전용 모드로 AI가 프로젝트를 파악하게 하고, 방향을 확인한 뒤 편집 모드로 전환할지 결정합니다.

제안 세션 만들기계획을 나누거나 방안을 검토해야 할 때 제안 세션으로 아이디어를 구조화된 구현 계획으로 만듭니다.