빠른 시작
이 페이지에서는 zqagent를 처음부터 설치하고 실행해 첫 대화를 완료하는 과정을 안내합니다.
명령줄을 쓰고 싶지 않다면 데스크톱 앱을 참고하세요. 설치 파일을 다운로드하면 GUI로 사용할 수 있습니다.
설치
세 플랫폼 모두 의존성 없는 실행 패키지를 제공하며 Node를 미리 설치할 필요가 없습니다. 사용 중인 시스템용 다운로드는 다음과 같습니다:
未能识别你的系统。 请从下面选择对应平台的安装包。
不确定选哪个？第一个通常就对了。
Linux와 macOS는 한 줄 명령으로도 설치할 수 있습니다(자동 시작도 등록):
curl -fsSL https://agent.cd-zq.com/install.sh | shNode.js 18+가 있으면 npm으로도 설치할 수 있습니다:
# 전역 설치(공개 npm에 게시됨. 추가 레지스트리 설정 불필요)
npm i -g @zqagent/core설치 후 zqagent를 실행해 CLI를 시작합니다.
버전 채널(안정판 / 테스트판) 선택, 시스템 요구 사항, 설치 문제 해결은 설치를 참고하세요.
LLM 연결
시작 후 .env를 직접 작성할 필요 없이 /connect를 입력하면 대화형으로 LLM 연결을 설정할 수 있습니다:
- provider 선택(OpenAI / DeepSeek / Qwen / Zhipu GLM / Kimi / Xiaomi MiMo / 사용자 지정)
- API Key 입력
- 모델 목록 자동 새로고침 후 선택(대화 모델이 앞쪽. 벡터/음성/이미지/전용 채널 등 비대화 모델은 ⚠️ 표시와 함께 끝으로 정렬)
- 자체 점검: 최소 요청을 실제 전송해 이 엔드포인트에서 모델을 쓸 수 있는지 확인. 실패하면 이유를 알려 주고 다시 선택하도록 안내
- 추론 강도 설정
API Key는 AES-256-GCM으로 암호화되어 이 기기의 ~/.config/zqagent/에 저장됩니다. 평문으로 디스크에 남지 않습니다.
대화할 수 없는 모델을 고르면 게이트웨이는 보통
Required parameter(s) missing or invalid만 반환해 문제를 알기 어렵습니다. 위의 정렬과 자체 점검은 첫 대화가 아니라 설정 단계에서 알아차리게 하기 위한 것입니다. 해결 방법은 자주 묻는 질문을 참고하세요.
로컬 개발
# 의존성 설치
pnpm install
# 환경 변수 설정(.env로 복사해 작성) 또는 시작 후 /connect
# OPENAI_API_KEY=sk-... # 필수(/connect 미사용 시)
# OPENAI_MODEL=모델명 # 선택. 미설정 시 시작 후 /connect로 선택
# OPENAI_BASE_URL=... # 선택. 사용자 지정 엔드포인트
# WORKSPACE=./ # 선택. 워크스페이스 루트, 기본값은 현재 디렉터리
cp .env.example .env
# CLI 시작
pnpm run dev첫 작업
시작하면 대화형 CLI로 들어갑니다. 자연어로 작업을 입력하세요. 예:
> 현재 디렉터리에 TypeScript 프로젝트를 초기화해 줘자동으로 계획하고 도구를 호출해 작업을 완료합니다. 기본은 대화형 모드이며 부작용이 있는 작업은 승인 카드가 표시되어 확인을 기다립니다.
명령, 실행 모드, 승인 세부 사항은 CLI 사용을 참고하세요.