1
사용 경로를 웹/CLI/Desktop으로 분리
CLI와 Desktop은 웹 UI 대체가 아니라 다른 접근 방법입니다.
주의: 웹 UI PASS를 CLI/Desktop PASS로 확대하지 않습니다.
Onyx v4 operator lesson 06 · standalone operator lesson
CLI/Desktop과 운영 점검
웹 UI 밖에서 Onyx를 쓰는 경로와 운영 점검 항목을 분리해, 사용자 확산 전에 접속·토큰·장애대응 기준을 확인합니다.
이 lesson의 목적
웹 UI 밖에서 Onyx를 쓰는 경로와 운영 점검 항목을 분리해, 사용자 확산 전에 접속·토큰·장애대응 기준을 확인합니다.
주 대상: 운영자, 개발자, 사내 도구 배포 담당자, CLI/Desktop 사용자 지원 담당자
언제 이 절차를 쓰나
- 개발자나 파워유저가 터미널에서 Onyx Agent를 쓰려 할 때
- Desktop App을 배포해 웹 브라우저 외 사용 경로를 열 때
- 배포 후 상태 점검, 로그, 업그레이드, 사용자 지원 기준을 만들 때
시작 전에 준비할 것
- 사용자 계정과 access token 발급 경로가 준비되어야 합니다.
- Onyx 서버 URL과 네트워크 접근 경로가 확정되어야 합니다.
- 운영자가 장애 시 확인할 compose/log/config 위치를 알고 있어야 합니다.
대표 작업 순서와 확인값
2
CLI 설치
`pip install onyx-cli` 또는 `uv pip install onyx-cli`로 설치합니다. 소스 빌드는 Onyx CLI 저장소의 현재 `go.mod`/공식 문서에서 요구 Go 버전을 확인한 뒤 진행합니다.
주의: 설치 방식과 버전을 기록하지 않으면 사용자 지원이 어려워집니다.
3
Access Token 생성
User Settings → Accounts & Access → New Access Token에서 CLI용 token을 만듭니다.
주의: 계정 비밀번호를 CLI 설정에 넣는 방식으로 안내하지 않습니다.
4
CLI configure/validate
`onyx-cli configure`로 서버 URL/API key를 저장하고 `onyx-cli validate-config`로 연결을 확인합니다.
주의: 환경변수 `ONYX_SERVER_URL`, `ONYX_API_KEY`, `ONYX_PERSONA_ID`는 CI/자동화에서 유용합니다.
5
CLI 사용 범위 확인
`onyx-cli agents`, `onyx-cli ask`, `onyx-cli ask --json`으로 agent 선택과 one-shot 질의를 확인합니다.
주의: CLI 답변이 회사 문서 기반인지 확인하려면 04의 RAG/citation 검증이 필요합니다.
6
Desktop 배포 안내
Desktop App은 Windows/macOS/Linux 다운로드 경로와 서버 접속 설정을 사용자 배포 문서에 적습니다.
주의: Desktop 페이지 자체는 세부 설치 절차가 짧으므로 실제 배포 가이드는 조직 기준으로 보강합니다.
7
운영 점검 루틴 작성
compose 상태, 로그 레벨, 도메인/SSL, 인증 실패, connector sync 실패, provider 비용/오류를 점검표에 둡니다.
주의: 장애가 난 뒤에만 로그를 보는 운영은 재현성이 낮습니다.
8
업그레이드/토큰 회수 기준
Quickstart install script 재실행 업그레이드와 token 폐기/재발급 절차를 분리합니다.
주의: 사용자 퇴사/권한 변경 시 CLI token 회수 누락이 생기기 쉽습니다.
자주 나는 실수
- Access Token 대신 비밀번호 공유를 안내하는 것
- CLI validate-config 없이 ask 결과만 보고 설정 완료라고 하는 것
- Desktop 사용 가능을 웹 UI/CLI 전체 운영 검증으로 확대하는 것
검증과 readback
- 설치 방식, 서버 URL, token 발급 경로, validate-config 결과를 기록합니다.
- CLI agent 목록과 기본 agent 선택을 확인합니다.
- Desktop은 조직별 OS 배포/보안 정책과 별도 매칭합니다.
근거 문서
아래 문서는 이 정적 lesson의 작성 근거입니다. 실제 화면 라벨이나 배포 성공은 별도 현장 검증이 필요합니다.
다음 판단 / 분기
- CLI/Desktop 사용자가 RAG 답변 품질을 요구하면 04로 되돌아갑니다.
- 외부 실행 도구가 필요하면 05 Actions/MCP를 먼저 승인합니다.
검증 경계
이 페이지는 접근 경로와 운영 체크리스트입니다. 실제 Desktop 설치 화면, CLI token 값, 운영 로그 내용은 이 정적 패키지에 포함하지 않습니다.