초기화 마법사 설정

Microsoft Store, Desktop 중 어떤 방식으로 설치했든 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을 설치해 두어야 합니다.
• 연결할 로컬 저장소 또는 작업 디렉터리를 준비해 두세요. 3단계에서 등록하며, 경로는 실제로 존재해야 합니다.

마법사 개요

마법사는 4개 단계로 구성되며, 왼쪽 내비게이션에 현재 진행 상황이 표시되고 상단 배지에는 “필수 단계 N / 3 완료”가 표시됩니다. 앞의 3단계는 필수 단계이고, 4단계 “커뮤니티”는 선택 단계로 표시됩니다.

단계	목표	완료 기준
1. 언어 및 테마	인터페이스 언어를 선택하고 계절 색상 테마 고르기	“계속”을 눌러 언어 확정
2. Hagicoder	CLI와 모델을 선택해 기본 Hagicoder 만들기	에이전트에 “대리인가 폴백 크루에 있습니다” 표시
3. 프로젝트	로컬 프로젝트를 최소 하나 등록	프로젝트 단계에 “프로젝트 단계 완료” 표시
4. 커뮤니티(선택)	첫 대화를 시작하거나 커뮤니티 진입점 확인	“완료” 클릭

왼쪽 아래의 “나중에 알림”은 마법사를 먼저 닫았다가 나중에 다시 알려 주고, “다시 표시 안 함”은 자동 표시를 끕니다. 어느 쪽이든 페이지 상단의 “마법사” 진입점에서 언제든 마법사를 다시 열 수 있으며, 끝내지 못한 단계는 대기 상태로 유지됩니다.

1단계: 언어 및 테마

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

1. “인터페이스 언어 선택”에서 언어를 하나 고릅니다(10가지 지원). 앱 UI 언어만 바뀌며, 영웅이나 프로젝트에는 영향을 주지 않습니다.
2. “색상 테마 선택”에서 봄, 여름, 가을, 겨울 중 한 계절의 “빛” 또는 “어둠” 변형을 고릅니다. 선택하면 바로 적용되며, 나중에 페이지 상단의 테마 진입점에서 다시 바꿀 수 있습니다.
3. “계속”을 클릭합니다. 언어가 확정되고 다음 단계인 Hagicoder로 넘어갑니다.

2단계: Hagicoder 설정

목표: 기본 에이전트를 만듭니다. 이름은 Hagicoder로 고정되며, 폴백 크루에 추가됩니다.

시스템에 이미 에이전트가 있으면 이 단계에 “에이전트을 찾았습니다”가 표시되거나 곧바로 “대리인가 폴백 크루에 있습니다”가 표시됩니다.

• 에이전트가 있지만 폴백 크루에 없다면 “폴백 크루에 추가”를 클릭하거나, 대신 “대신 새 대리인 만들기”를 선택할 수 있습니다. 마법사가 자동으로 추가하지는 않습니다.
• 이미 폴백 크루에 있다면 “다음: 프로젝트 만들기”를 바로 클릭하면 됩니다.

그렇지 않다면 다음 순서로 만듭니다.

1. 기본 AgentCLI 선택: 로컬에서 감지된 CLI만 표시되며, 선택한 카드의 오른쪽에 체크 표시가 나타납니다.

2. 기본 모델 선택:

   • 목록에서 기존 모델을 고릅니다. 위의 검색 상자(“모델 검색”)로 이름이나 모델 ID로 걸러 낼 수 있습니다.
   • 또는 “사용자 지정 모델 입력”에 gpt-5.5, glm-5.1, claude-opus-4-7처럼 모델 이름을 직접 입력합니다. 만들 때 백엔드가 일치하는 템플릿을 재사용하거나 새로 만듭니다.

   

3. (권장) “연결 테스트 실행” 클릭: 선택한 CLI를 사용할 수 있는지 확인합니다. 모델에 프롬프트를 보내지 않으므로 CLI를 호출할 수 있다는 것만 확인할 뿐, 모델의 응답을 확인하지는 않습니다. 결과가 “CLI를 사용할 수 있습니다”이면 통과입니다. 테스트가 실패하거나 시간 초과되어도 만들기가 막히지는 않지만, CLI를 고치기 전까지는 제대로 동작하지 않을 수 있습니다.

4. (선택) 기본 초상화 고르기: 추천 초상화 중 하나를 고르거나, “셔플”을 클릭해 다른 후보를 확인합니다.

5. “대리인 만들기”를 클릭합니다. 성공하면 페이지에 “대리인가 폴백 크루에 있습니다”가 표시되고, 선택한 CLI와 모델이 Hagicoder의 기본 구성에 기록됩니다.

   

6. “다음: 프로젝트 만들기”를 클릭합니다.

지원하는 CLI

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

자주 발생하는 문제

• “사용 가능한 로컬 CLI가 없습니다”가 표시됩니다: 먼저 AI Agent CLI 설치에 따라 이 컴퓨터에 CLI를 설치하고 로그인한 뒤 “다시 감지”를 클릭하세요. “나중에 하기”를 클릭해 넘어갈 수도 있습니다. 이 경우 이 단계는 미완료 상태로 남고, 마법사가 나중에 다시 알려 줍니다.
• 목록에 내 CLI가 없습니다: Hagicode Server가 실행되는 환경에서 해당 CLI가 설치되어 있고 사용할 수 있는지 확인하세요. Desktop 사용자는 Desktop을 다시 시작해 PATH를 새로 읽게 하세요.
• 연결 테스트 실패: 페이지에 실패 이유가 표시됩니다. 흔한 원인은 CLI에 아직 로그인하지 않았거나 토큰이 유효하지 않은 경우입니다. 먼저 터미널에서 해당 CLI로 최소한의 대화를 실행해 CLI 자체가 동작하는지 확인한 뒤 “다시 실행”을 클릭하세요.
• 에이전트는 만들어졌지만 폴백 크루 추가에 실패했습니다: 페이지에 “폴백 크루 추가 다시 시도”가 표시됩니다. 다시 시도하면 같은 에이전트만 추가되며 중복 생성되지 않습니다.

3단계: 프로젝트 만들기

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

1. “로컬 프로젝트 하나 등록”에서 프로젝트 이름(필수), 폴더 경로(필수), 선택 사항인 프로젝트 설명을 입력합니다. 필드와 경로 검증은 메인 화면의 “새 프로젝트” 대화 상자와 완전히 같습니다.
2. “프로젝트 만들고 계속”을 클릭합니다. 경로는 저장할 때 검증되며, 검증을 통과하면 프로젝트가 만들어지고 마법사가 자동으로 다음 단계로 넘어갑니다.
3. 프로젝트를 만든 뒤 이 단계로 돌아오면 “현재 프로젝트 요약”과 “프로젝트 단계 완료” 표시가 나타납니다. 이때 “계속”을 클릭해 커뮤니티로 넘어가거나, “프로젝트 하나 더 추가”를 클릭해 프로젝트를 더 등록할 수 있습니다(“프로젝트 추가”로 저장하거나 “취소”로 요약으로 돌아갑니다).

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

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

자주 발생하는 문제

• “프로젝트 만들기에 실패했습니다”가 표시됩니다: 폴더 경로가 올바르고 실제로 존재하는지 확인하세요.

4단계: 커뮤니티

목표: 준비가 끝났는지 확인하고 다음에 무엇을 할지 고릅니다. 이 단계는 선택 사항입니다.

필수 단계 세 개를 모두 마치면 페이지에 “HagiCode를 사용할 준비가 되었습니다”와 필수 단계 세 개의 완료 상태가 표시됩니다.

• 첫 대화 시작: 클릭하면 마법사가 닫히고 작업 공간에서 새 대화 창이 열립니다. 대화에는 프로젝트가 필요하므로, 아직 프로젝트가 없으면 “먼저 프로젝트를 만드세요”가 표시되고 “프로젝트 단계로 이동” 버튼이 제공됩니다.
• HagiCode 소개: “About 페이지 열기”를 클릭하면 브라우저에서 공식 웹사이트의 “정보” 페이지가 열립니다. 그곳에 전체 커뮤니티 진입점이 모여 있으며, 마법사는 그대로 열려 있습니다.
• 완료: 오른쪽 아래의 “완료”를 클릭하면 마법사가 닫힙니다. 아직 끝나지 않은 필수 단계가 있으면 대기 상태로 남으며, 페이지 상단의 “마법사” 진입점에서 다시 열 수 있습니다.

다음 단계

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

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