CLI 사용
시작하면 대화형 CLI로 들어가 자연어로 작업을 입력할 수 있습니다. 프롬프트는 [모드][agent명] > 형식으로 현재 상태를 표시합니다(예: [plan][code] > ).
내장 명령
| 명령 | 설명 |
|---|---|
/plan | 계획 모드로 전환(읽기 전용 탐색 + 계획 제안) |
/interactive | 대화형 승인 모드로 전환(기본) |
/auto | 완전 자동 모드로 전환(승인 불필요, 고위험) |
/discuss | 토론 모드로 전환(읽기 전용 대화) |
/mode | 현재 모드 표시 |
/connect | LLM 연결(provider 선택 → key → 모델 목록 새로고침 → 추론 강도) |
/connect rm | 연결 구성 삭제(환경 변수로 복귀) |
/providers | 구성된 LLM 공급자 나열(▶가 현재 활성) |
/use <번호|id> | 현재 활성 공급자 전환 |
/rm <번호|id> | 지정 공급자 삭제 |
/link | 계정 연결 마법사 시작(Hub 주소 + 이메일/휴대폰 번호 + 비밀번호 또는 SMS 인증 코드) |
/link <연결 코드> [Hub 주소] | 일회용 연결 코드로 이 기기 노드를 사용자 센터에 연결 |
/sessions | 저장된 세션을 나열하고 복원 선택(전환 후 최근 메시지 표시) |
/history | 현재 세션의 사용자 지시 나열 |
/model <id> | LLM 모델 전환 |
/agent <name> | agent 전환(Prompt + 선택적 모델 동기화) |
/agents | 모든 agent 나열(현재 항목 강조) |
/agent add <name> <prompt...> | 사용자 지정 agent 추가 |
/agent edit <name> <prompt...> | agent의 Prompt 수정(현재 agent는 즉시 핫 리로드) |
/agent rm <name> | agent 삭제 |
/agent show [name] | agent 상세 보기 |
/mcp | MCP 서버와 연결 상태 나열 |
/mcp add <name> stdio <cmd...>|http <url> | MCP 서버 추가 및 연결(도구 자동 주입) |
/mcp rm|enable|disable|refresh [name] | 제거 / 활성화 / 비활성화 / 도구 목록 새로고침 |
/tools | 모든 도구 나열(출처, 위험, 비활성 상태) |
/tool add <name> <cmd...> | 명령 도구 추가(shell 명령 실행) |
/tool rm|disable|enable <name> | 도구 제거 / 비활성화 / 활성화 |
/clear | 현재 세션 비우기 |
quit / exit | 종료 |
reset | 세션 초기화 |
| 실행 중 입력 + Enter | 현재 작업에 보충 정보 전송(다음 반복에 적용) |
| 실행 중 ESC 두 번 | 현재 작업 중단 |
자주 하는 작업 예시
자연어로 바로 입력합니다. 예:
> 현재 디렉터리에 TypeScript 프로젝트를 초기화해 줘
> src/ 아래 코드를 읽고 잠재적 문제를 지적해 줘
> logs/의 모든 .json 파일을 .json.bak로 이름을 바꿔 줘
> 테스트를 실행하고 실패한 케이스를 고쳐 줘파일을 수정하거나 명령을 실행해야 할 때, 대화형 모드에서는 승인 카드가 표시되어 확인을 기다립니다.
실행 모드
| 모드 | 동작 |
|---|---|
discuss | 읽기 전용. 모든 쓰기와 실행 금지 |
plan | 읽기 전용. 모든 쓰기와 실행 금지. 계획 제안용 |
interactive | 부작용이 있는 작업은 사용자가 매번 승인(기본) |
auto | 부작용이 있는 작업을 모두 허용(고위험, 자기 책임) |
승인 카드
대화형 모드의 승인 카드는 다음을 지원합니다:
Y이번만 허용A이 도구 항상 허용D거부run_shell은 추가로C이 명령 항상 허용(명령 단위 허용 목록. 도구 전체를 허용하는 것보다 안전)
실행 중 보충 정보(steering)
작업 실행 중에도 완료를 기다리지 않고 지시를 추가할 수 있습니다. 글자를 입력하고 Enter를 누르면 다음 반복 사이에 user 메시지로 현재 작업에 주입되며, agent는 계속 실행하면서 이 보충 정보를 반영합니다.
새 작업을 시작하려면 현재 작업이 끝날 때까지 기다리거나 ESC를 두 번 눌러 중단하세요. (승인/질문이 대기 중이면 입력은 우선 승인 응답 또는 질문 답변으로 사용됩니다.)
세션 관리
/sessions는 저장된 세션을 나열하고 선택해 복원합니다. 전환 후 최근 메시지를 표시해 중단 지점부터 이어가기 쉽습니다./clear는 현재 세션을 비우고,reset은 세션 상태를 초기화합니다./history는 현재 세션의 사용자 지시를 나열해 문맥을 빠르게 되돌아볼 수 있습니다.
다중 공급자 관리
여러 LLM 연결(다른 벤더 또는 다른 Key)을 저장하고 언제든 전환할 수 있습니다:
/providers # 모든 공급자 나열, ▶가 현재 활성
/use 2 # 번호로 전환(/use <id>도 가능)
/rm 3 # 공급자 삭제새 공급자는 /connect로 추가합니다. 전환은 즉시 적용되며 재시작이 필요 없습니다.
명령줄 하위 명령
zqagent로 대화형 세션에 들어가는 것 외에 4개의 하위 명령이 있습니다:
zqagent serve [--port <n>] [--host <addr>] [--data-dir <dir>] # 헤드리스 상주 서비스
zqagent link --hub <url> --username <이메일/휴대폰> --password '<비밀번호>' # 계정 연결(재시작 불필요)
zqagent link --hub <url> --code <연결 코드> # 일회용 연결 코드로 연결(재시작 불필요)
zqagent rename <이름> # Hub에 표시되는 노드 이름 변경
zqagent update [--status|--check|--now|--rollback] # 노드 자동 업데이트 확인/실행, 롤백zqagent는 --resume <세션ID>로 이전 세션을 복원하고 --debug로 시작 진단 로그를 출력합니다.
serve는 시작 시 바로 연결할 수도 있습니다: --hub <url> --enroll-code <코드> --label <이름>, 또는 계정 방식 --hub <url> --username <이메일/휴대폰> --password <비밀번호>.
Windows 단일 파일에서는 zqagent를 zqagent.exe로 바꿉니다(PATH에 없으면 .\zqagent.exe):
zqagent.exe serve --port 8787 --data-dir "%APPDATA%\zqagent"
zqagent.exe link --hub https://hub.cd-zq.com --username you@example.com --password <비밀번호>
zqagent.exe link --hub https://hub.cd-zq.com --code <연결 코드>zqagent link를 인증 정보 없이 실행하면 대화형 마법사로 들어갑니다. 비밀번호는 ZQAGENT_HUB_PASSWORD로도 제공할 수 있습니다.
Windows의 link도 데스크톱 버전이 설치한 노드 서비스를 자동으로 찾으므로 보통 --data-dir이 필요 없습니다. 수동으로 작업 스케줄러를 설정했고 데이터 디렉터리가 기본 위치가 아닐 때만 명시합니다.
자세히는 노드 시작을 참고하세요.
시작 진단(--debug)
"시작하자마자 종료되고 콘솔에 아무것도 나오지 않는다" 같은 문제에서는 --debug로 진단을 켭니다:
zqagent --debug # 단일 실행 파일(macOS / Linux)
node bin/zqagent --debug # npm 설치 진입점zqagent.exe --debug :: Windows 단일 파일
set ZQAGENT_DEBUG=1 :: Windows cmd, 동일한 표기export ZQAGENT_DEBUG=1 # bash/zsh진단 로그는 동기적으로 디스크에 기록되며(stdout 버퍼를 거치지 않아 프로세스가 크래시하거나 즉시 종료해도 유실되지 않음), 동시에 stderr로도 출력됩니다. 로그 경로는 다음 순서로 결정됩니다:
| 환경 변수 | 의미 |
|---|---|
ZQAGENT_DEBUG_LOG | 로그 파일 전체 경로(우선) |
ZQAGENT_DEBUG_DIR | 로그 디렉터리. 파일 이름은 고정으로 zqagent-debug.log |
| 모두 미설정 | 시스템 임시 디렉터리(os.tmpdir()) 아래 zqagent-debug.log |
로그에는 환경 스냅샷, 시작 각 단계, 크래시 스택이 포함됩니다(OPENAI_API_KEY 같은 인증 정보는 "설정 여부 + 길이"만 기록하고 평문은 출력하지 않음). 로그가 멈춘 줄이 실패 위치입니다. --debug를 끄면 완전히 비활성화되어 파일도 쓰지 않고 핸들러도 등록하지 않습니다.
대조 프로브: 어느 계층의 문제인지 판단
단일 파일 산출물 = 공식 node 기반 + 주입된 SEA blob + 그 안의 비즈니스 코드. 시작 직후 종료되면 최소 샘플로 세 계층을 분리하는 것이 비즈니스 코드를 추측하는 것보다 훨씬 빠릅니다:
| 샘플 | 생성 방법 | 실행되지 않을 때의 의미 |
|---|---|---|
_node-base-<ver>-<platform>-<arch> | 공식 node, 무수정 | 시스템/보안 소프트웨어/로더 계층에서 막힘. 패키징과 무관 |
_sea-minimal-probe-<platform>-<arch> | 최소 SEA 프로브, useCodeCache: false | SEA 주입 또는 로드 실패(종료 코드 확인. 예 0xC0000005) |
_sea-cc-probe-<platform>-<arch> | 위와 같지만 useCodeCache: true | 크로스 빌드가 빌드 머신의 V8 code cache를 포함 |
zqagent-windows-x64.exe | 실제 산출물 | 앞의 세 가지가 정상이면 비즈니스 코드 초기화 문제. --debug로 계속 |
pnpm run probes:sea # win32-x64(기본)
pnpm run probes:sea -- --arch arm64 # win32-arm64
pnpm run probes:sea -- --platform linux --arch x64 # Linux에서 linux 프로브 생성(이 기기에서 실행 가능)
pnpm run probes:sea -- --platform darwin --arch arm64 # macOS에서 macos 프로브 생성(이 기기에서 실행 가능)프로브는 stdout 출력 외에 임시 디렉터리에 zqagent-probe.log를 기록합니다. "콘솔에 출력이 보이지 않는" 경우에도 디스크 로그로 JS가 실제 실행되었는지 증명할 수 있습니다.
주입 후 산출물의 sha256은 빌드마다 바뀝니다(blob에 빌드 머신의 main 스크립트 절대 경로가 기록됨). 따라서 기반
_node-base-*의 해시만 "파일이 완전/일치하는지"의 근거로 사용하세요.
macOS에서 생성/사용 시 주의: SEA에는 Node ≥ 20이 필요합니다.
darwin산출물은 주입 전에codesign --remove-signature, 주입 후codesign --sign - --force로 임시 서명이 필요합니다(이 기기에서 macos 프로브를 생성하는 스크립트가 자동 처리). arm64 커널은 서명되지 않은 바이너리 실행을 거부합니다. Windows 산출물 생성은 순수 크로스 어셈블리(postject는 파일만 쓰고 실행하지 않음)이므로 macOS/Linux에서도.exe를 바로 만들 수 있습니다.
Windows에서는 한 세트를 같은 디렉터리에 두고 release/cli/diagnose.cmd를 실행합니다. node -e, 두 프로브, zqagent --debug를 차례로 실행하고 각 샘플의 종료 코드, 진단 로그, 프로브 디스크 로그를 출력합니다. 화면 텍스트를 그대로 복사해 보내면 원인을 찾을 수 있습니다.