원격 제어 개요
zqagent를 자신의 컴퓨터나 서버에서 실행하고 스마트폰이나 QQ로 원격에서 작업을 요청합니다. AI는 서버 측에서 실행되며 진행 상황, 승인 요청, 결과가 실시간으로 손에 전달됩니다. PC 앞에 붙어 있고 싶지 않을 때나 언제든 AI에게 일을 맡기고 싶을 때 적합합니다.
공식 클라우드 사용(권장)
직접 broker를 구축하고 싶지 않다면 이미 배포된 클라우드를 그대로 사용하세요:
ZQAgent 사용자 센터를 열어 가입하고 로그인합니다.
노드 관리를 만들고 일회용 연결 코드를 생성합니다(15분 유효).
대상 기기에서 명령 하나를 실행해 연결합니다(방법 중 하나. 인증 정보는 자동 저장되어 수동 전달 불필요):
기존 노드(핫 연결, 재시작 불필요)
bashzqagent link --hub https://hub.cd-zq.com --code <연결 코드>시작 시 연결(소스 / 베어메탈)
bashHUB_URL=https://hub.cd-zq.com HUB_ENROLL_CODE=<연결 코드> pnpm run serverDocker
bashdocker run -d -p 8787:8787 -v zqagent-data:/data \ -e HUB_URL=https://hub.cd-zq.com -e HUB_ENROLL_CODE=<연결 코드> \ ghcr.io/<owner>/zqagent-server데스크톱 앱: 콘솔 상단의 '클라우드 연결'에서 Hub 주소와 연결 코드를 붙여넣습니다.
인증 정보는
{DATA_DIR}/fleet.json에 자동 저장되며 이후 재시작에는 연결 코드가 필요 없습니다. 노드가 온라인이 되면 사용자 센터 또는 노드 콘솔(브라우저 / 스마트폰)에서 상태, 프로젝트, 이벤트를 확인하고 작업 투입, 승인, 중단 등 완전한 세션 조작을 할 수 있습니다.
노드는 게이트웨이로 아웃바운드 연결(wss://, 보통 443)만 하면 되며 공인 인바운드도 포트 개방도 필요 없습니다.
- 연결 코드는 일회용이며 짧은 시간만 유효합니다. 같은 노드 ID가 다른 노드 관리에 중복으로 편입되지 않습니다(선점 방지).
- 자체 Hub를 구축하면 노드에 배포하는 게이트웨이 주소는 Hub 측
HUB_GATEWAY_URL로 결정됩니다.
CLI만 있는 머신: 노드로 상주
CLI만 설치한 머신(소스 불필요)도 관리 가능한 노드로 상주할 수 있습니다:
zqagent serve # 이 기기에서만 사용
zqagent serve --hub https://hub.cd-zq.com --enroll-code <연결 코드> # 시작 시 연결백그라운드 상주(nohup / pm2 / systemd), 데이터 디렉터리, 온라인 확인 등은 노드 시작을 참고하세요.
빠른 시작
프로젝트 디렉터리에서 서비스를 시작합니다(소스 방식. CLI 설치 시 zqagent serve와 동일):
pnpm run server # 기본 포트 8787. 첫 시작 시 데모 테넌트 demo 자동 생성(apiKey는 무작위 생성해 로그에 출력)시작 로그에 데모 테넌트 정보가 출력됩니다:
zqagent server 监听 http://localhost:8787
数据目录: ./data
已创建演示租户: id=demo apiKey=zk_xxxx（随机生成） model=gpt-4o-mini자세한 구성은 서버 구성을 참고하세요.
공인 네트워크가 필요한가요?
결론: 서버 본체에는 공인 IP가 필요 없습니다. 모든 '원격 상호작용'은 아웃바운드 연결로 제3자 릴레이를 통해 이루어집니다:
| 기능 | 서버 동작 | 중계 | 공인 인바운드 필요? |
|---|---|---|---|
| 원격 제어 | 게이트웨이 연결(아웃바운드 wss) | 공인 Rust 게이트웨이 | 아니요 |
| QQ 봇 | 텐센트 게이트웨이 연결(아웃바운드) | 텐센트 QQ 오픈 플랫폼 | 아니요 |
| 이메일 / Bark / Server酱 / Webhook 알림 | 능동 POST(아웃바운드) | SMTP / 각 푸시 서비스 | 아니요 |
공인 네트워크(또는 내부망 관통)가 필요한 경우는 하나뿐입니다: 외부에서 REST 인터페이스에 직접 접근하게 하려는 경우입니다. 자세히는 서버 구성을 참고하세요.