공급자 선택

모델 공급자를 연결하고 q의 기본 역할에 모델을 할당합니다.

Markdown 보기

지원하는 공급자

q의 관리형 Gateway는 다음을 지원합니다.

로컬 서버를 포함한 OpenAI 호환 HTTP API
OpenRouter
xAI 및 Grok
Anthropic 네이티브 Messages API
현재 Codex 로그인을 사용하는 로컬 Codex App Server

Gateway 구성

Studio의 Settings → Providers에서 공급자를 추가하고 Settings → Services에서 리스너를 설정하세요. Studio 호스트는 비공개 루프백 포트에서 관리형 Gateway 자식 프로세스를 감독합니다.

공급자 변경은 교체 프로세스를 먼저 시작한 다음 활성화됩니다. 교체 프로세스가 시작되지 않으면 q는 동작 중인 구성을 유지합니다.

가능하면 공급자 자격 증명은 환경변수 참조로 설정하세요. 전역 공급자 정의는 ~/.q/providers.json에 저장됩니다.

API 유형이 openrouter인 공급자에게 Q는 HTTP-Referer: https://q.saturday.ne.kr와 X-OpenRouter-Title: Q를 보냅니다. OpenRouter는 이렇게 식별된 사용량을 공개 앱 순위에 포함할 수 있습니다. 다른 앱 이름을 쓰려면 ~/.q/providers.json에서 해당 공급자의 headers에 원하는 값을 지정하세요. 직접 지정한 값이 Q의 기본값보다 우선합니다.

모델 역할 할당

Settings → Models에서 기본 채팅과 interviewer, manager, research, reviewer, coder, commit, thinker, librarian 같은 전문 역할에 모델을 할당합니다. senior developer는 reviewer, junior developer는 coder 모델 역할을 사용합니다.

역할 할당 목록에서 재사용 가능한 사용자 정의 역할을 만들 수 있습니다. 사용자 정의 서브에이전트는 자체 도구와 위임 권한을 유지하면서 이 역할을 선택할 수 있습니다.

워크스페이스 오버라이드는 .q/model.json에, 전역 할당은 ~/.q/config.yaml에 저장됩니다.

모델 API 선택

q는 구체적인 모델별로 Chat Completions 또는 Responses를 선택합니다. 네이티브 Responses를 지원하는 것으로 확인된 OpenAI, xAI, OpenRouter Gateway 경로는 Responses를 우선합니다. Codex App Server, Anthropic 네이티브 및 알 수 없는 호환 엔드포인트는 기존 API를 사용합니다. Gateway는 두 입력 경로를 계속 받습니다.

Codex App Server에서는 q의 minimal agent가 node_repl 같은 상속된 비공개 MCP 도구를 비활성화합니다. Q 자체 도구는 계속 사용할 수 있고 세션 추적에 표시됩니다.

Studio의 모델 API 제어에서 선택하거나 ~/.q/config.yaml의 model_api_modes에 전체 모델 ID와 chat_completions 또는 responses를 지정할 수 있습니다. 기본 모델 그룹에 후보가 여러 개면 Responses를 사용할 수 없습니다. 역할별 그룹은 각 후보 모델의 API를 따릅니다. 저장된 세션은 두 API에서 공통 메시지 형식을 사용합니다.

임베딩 구성

모델 할당 화면에는 전역 embedding 대상도 있습니다. 임베딩을 지원하는 모델을 선택하고 해당 모델이 요구하는 벡터 차원을 입력하세요. q는 1부터 4096까지의 차원을 허용합니다.

Workspace Memory와 Library가 공유 파생 인덱스를 유지하므로 임베딩 구성은 전역이며 워크스페이스별로 바꿀 수 없습니다. 모델을 할당하거나 변경하면 재생성 가능한 HNSW 프로젝션을 다시 구성하고 활성 Agent Skills를 새 모델로 백필합니다. 대상을 비우면 스킬과 기록 검색은 BM25만 사용합니다.

구성된 공급자는 임베딩 요청을 지원해야 하며 차원은 선택한 모델과 일치해야 합니다. 설정 오류가 발생해도 기반 JSON 레코드는 계속 사용할 수 있습니다.

폴백 그룹

역할은 순서가 있는 모델 그룹을 참조할 수 있습니다. 후보가 시간 초과되거나 일시적인 HTTP 5xx를 반환하면 q는 다음 후보를 시도합니다.

사용자 취소, 도구 실패, 검증 오류는 폴백을 일으키지 않습니다. 이런 결과는 다른 모델 엔드포인트가 아니라 요청, 도구 상태, 구성을 바꿔야 합니다.