기술 질문(고급)
이 페이지는 명령줄을 쓰거나, 자체 모델을 연결하거나, 연동을 만드는 분들을 위한 것입니다. 파일 처리만 맡기고 싶다면 자주 묻는 질문으로 충분합니다.
설치와 연결
모델은 어떻게 설정하나요? CLI를 실행한 뒤 /connect를 입력하고, 안내에 따라 provider(DeepSeek / OpenAI / 사용자 정의)를 고르고 API Key를 입력, 모델을 선택하고 추론 강도를 설정합니다. 설정 파일을 직접 쓸 필요는 없습니다.
API Key는 어디에 저장되나요? 평문으로 유출되지 않나요? 로컬 ~/.config/zqagent/에 암호화해 저장하며, 평문으로 디스크에 기록하지 않습니다.
어떤 모델을 지원하나요? OpenAI 호환 엔드포인트면 무엇이든 됩니다. DeepSeek, OpenAI, Ollama, 자체 서비스 등입니다. /connect의 "사용자 정의"를 쓰거나 OPENAI_BASE_URL을 설정하세요.
Required parameter(s) missing or invalid / Responses API 호출 실패 오류가 납니다. 대부분 선택한 모델을 대화에 쓸 수 없기 때문입니다. 게이트웨이의 모델 목록(/models)은 "전체 카탈로그"인 경우가 많아, 임베딩(*-embedding), 리랭크(*-rerank), 음성(*-asr / *-tts), 실시간(*-realtime), 이미지(qwen-image* / wan*), 전용 채널(cmaas-*) 같은 모델도 포함되어 있지만 이들은 일반 대화 요청을 받지 않습니다. /connect는 이런 모델을 목록 끝으로 보내고 ⚠️ 표시를 붙이며, 선택 후 자동 자체 점검(최소 요청을 실제로 전송)도 수행합니다. 통과하지 못하면 다시 고르라고 안내합니다. 목록 앞쪽의 대화용 모델(qwen3.8-flash, qwen-plus, deepseek-flash 등)로 바꾸면 됩니다.
자체 점검이 실패할 때 알려주는 두 가지 원인:
| 표시 | 의미 | 처리 |
|---|---|---|
The product is not activated | 이 API Key / 계정에서 해당 모델이 활성화되지 않음(또는 미납·할당량 소진) | 게이트웨이 콘솔에서 활성화하거나 활성화된 모델로 변경 |
InvalidParameter: Required parameter(s) missing or invalid | 모델 이름이 대화 API에 받아들여지지 않거나, 해당 서비스가 지원하지 않는 파라미터를 보냄 | 대화용 모델로 변경. 그래도 안 되면 추론 강도를 "기본"으로 |
특정 모델이 되는지 직접 확인하려면:
curl -s <BaseURL>/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" -H "content-type: application/json" \
-d '{"model":"<모델 이름>","messages":[{"role":"user","content":"hi"}]}'설치 시 command not found가 나오거나 다운로드가 매우 느립니다. 패키지는 공개 npm에 있으므로 보통 그대로 설치하면 됩니다:
npm i -g @zqagent/core다운로드가 느린 것은 대개 네트워크 문제입니다. 국내 미러로 임시 전환할 수 있습니다 (미러는 릴리스 후 자동 동기화됩니다):
npm i -g @zqagent/core --registry=https://registry.npmmirror.com/그 밖의 설치 문제는 설치를 참고하세요.
안정판과 베타판은 어떻게 고르나요? 현재 공개 npm에는 안정판(@latest)만 배포되며 별도 베타 태그는 없습니다. 최신판을 설치하세요. 설치를 참고하세요.
일상 사용
실행 모드는 어떻게 바꾸나요?/discuss(읽기 전용 대화), /plan(읽기 전용 탐색 + 계획), /interactive(매번 승인, 기본), /auto(완전 자동, 고위험). 자세한 내용은 CLI 사용.
위험한 작업이 그대로 실행되나요? 기본 대화형 모드에서는 아닙니다. 파일 쓰기나 명령 실행처럼 부작용이 있는 작업은 먼저 승인 카드가 표시되고, 허용할지 거부할지 직접 정합니다.
오래 걸리는 작업 중에 요구사항을 바꿀 수 있나요? 됩니다. 실행 중에 그대로 입력하고 Enter를 누르면 다음 반복에서 보충 정보로 주입됩니다. 별도 작업을 시작하려면 먼저 중단하세요.
작업이 멈췄을 때는? ESC를 두 번 누르세요.
긴 대화가 모델의 컨텍스트 윈도우를 넘지 않나요? 넘지 않습니다. 임계값에 도달하면 이전 대화를 자동으로 압축해 핵심 정보를 유지합니다. 직접 개입할 필요가 없습니다.
세션 저장과 복원은?/sessions로 저장된 세션을 나열해 복원할 수 있고, /clear로 현재 세션을 비웁니다.
노드와 콘솔
zqagent를 계속 실행하면서 원격으로도 관리하고 싶습니다.zqagent serve로 노드로 상주시키거나 데스크톱 앱을 설치하세요. 사용자 센터에 연결하면 원격으로 확인할 수 있습니다. 절차는 노드 시작을 참고하세요.
브라우저로 노드를 관리할 수 있나요? 휴대폰은? 됩니다. 노드 연결 후 브라우저에서 사용자 센터를 열면 노드 콘솔에 들어갈 수 있습니다. 휴대폰 브라우저도 지원합니다(반응형 + PWA, "홈 화면에 추가" 가능).
사용량과 비용은 어디서 보나요?노드 콘솔의 사용량 패널(프로젝트 홈의 token 카드 또는 노드 상세 "모니터링 → 사용량 보기")에서 기간·모델별 통계와 CSV 내보내기를 할 수 있습니다. 계정 페이지에서는 노드 간 합계도 볼 수 있습니다.
보내지 않은 내용이 사라지나요? 사라지지 않습니다. 콘솔 입력창의 초안은 자동 저장되어 세션을 바꾸거나 페이지를 새로 고쳐도 복원됩니다.
세션 중 연결이 끊기거나 백그라운드로 가면 내용이 사라지나요? 사라지지 않습니다. 실시간 이벤트 스트림이 끊긴 뒤 자동으로 재연결하고 증분을 보충합니다. 복구 후에도 내용이 유실되거나 중복되지 않습니다.
데스크톱 앱
창을 닫아도 작업이 계속 실행되나요? 계속됩니다. 창을 닫아도 트레이로 숨겨질 뿐이며, 트레이에서 "종료"해도 백그라운드 노드 서비스는 launchd / systemd가 유지합니다.
데이터는 어디에 있나요? 노드 데이터는 시스템 서비스의 데이터 디렉터리(macOS ~/Library/Application Support/zqagent/, Linux ~/.zqagent_data/, Windows %APPDATA%\zqagent\)에 있으며 install.sh로 설치한 노드와 공유됩니다. 데스크톱 설정은 별도로 ~/.config/zqagent-desktop/desktop.json에 저장됩니다. 자세한 내용은 데스크톱 앱 → 설치 세부 정보.
원격 제어
공인 IP가 있는 서버가 필요한가요? 필요 없습니다. 휴대폰과 QQ 원격 모두 아웃바운드 연결로, 서드파티 중계를 거칩니다. 자세한 내용은 원격 제어 개요.
휴대폰 / QQ에서 사용하려면?원격 접속과 QQ 봇을 참고하세요.
기존 도구 확장
AI에게 도구를 더 주려면? MCP로 외부 도구 서버에 연결하거나 /tool add로 명령 실행 도구를 추가합니다. 자세한 내용은 MCP와 도구.