---
locale: ko
title: Q Studio
description: 로컬 웹 인터페이스에서 세션 실행, 위임 트리 확인, 변경 검토와 q 구성을 수행합니다.
sectionLabel: 가이드
toc:
  - id: studio-시작
    label: Studio 시작
  - id: 세션과-위임
    label: 세션과 위임
  - id: 저장소-작업-검토
    label: 저장소 작업 검토
  - id: 설정과-운영
    label: 설정과 운영
  - id: 로컬-런타임-경계
    label: 로컬 런타임 경계
---

## Studio 시작

Q Studio는 일상 작업을 위한 기본 인터페이스입니다. q 바이너리가 내장 Svelte 애플리케이션을 직접 제공하므로 별도 웹 서비스를 설치할 필요가 없습니다.

```powershell
q studio
```

Studio는 기본적으로 `127.0.0.1`의 사용 가능한 임의 포트에서 실행되고 브라우저를 엽니다. 고정된 로컬 주소를 사용하려면 다음과 같이 실행하세요.

```powershell
q studio --host 127.0.0.1 --port 7070
```

신뢰할 수 있는 네트워크의 다른 기기에서 접속하려면 모든 IPv4 인터페이스에서 수신한 뒤, 다른 기기에서 `http://<이-컴퓨터의-IP>:7070`을 여세요.

```powershell
q studio --host 0.0.0.0 --port 7070 --no-open
```

`--host`에는 `127.0.0.1`, `0.0.0.0`, `::1`, `::` 같은 IP 주소를 지정할 수 있습니다. 포트 `0`은 사용 가능한 임의 포트를 선택하며, `--no-open`은 브라우저 자동 실행을 끕니다.

**Studio에는 자체 HTTP 인증이 없습니다.** Studio에 접속한 클라이언트는 q 프로세스의 권한으로 파일, 프로세스, Git과 구성 작업을 실행할 수 있습니다. 루프백이 아닌 주소는 신뢰할 수 있고 방화벽으로 보호된 네트워크 또는 인증된 리버스 프록시 뒤에서만 사용하세요.

Studio를 시작한 디렉터리가 워크스페이스 범위를 제한하지 않습니다. 등록된 각 루트 세션이 에이전트가 실행될 저장소 디렉터리를 따로 기록합니다.

## 세션과 위임

**Sessions**에서 저장소 디렉터리를 고른 뒤 기존 루트 세션을 등록하거나 새 세션을 만드세요. 서로 다른 저장소의 루트 세션을 한 목록에서 볼 수 있습니다. 세션을 선택하면 채팅, 컨텍스트 사용량, 현재 실행 제어와 위임된 자식이 열립니다.

메시지는 구문 강조를 포함한 안전한 Markdown으로 렌더링됩니다. 실행은 브라우저 연결과 독립적으로 계속되며 새로고침하면 이벤트 스트림에 다시 연결됩니다. 에이전트가 질문하거나 멈추거나 방향 안내가 필요할 때 선택한 실행에서 응답할 수 있습니다. 실행 중인 작업을 일시 정지, 재개하거나 중단할 수도 있습니다.

위임은 트리로 표시됩니다. 자식을 선택하면 그 세션의 대화와 중첩된 작업을 볼 수 있습니다. 완료된 자식은 채팅 헤더에서 삭제할 수 있습니다. 삭제하면 해당 자식과 모든 하위 자식이 제거되며 부모 대화의 완료된 도구 교환 기록은 유지됩니다.

## 저장소 작업 검토

**Changes**는 저장소 전체의 스테이징, 비스테이징, 이름 변경과 미추적 파일을 보여줍니다. 파일을 고르면 줄 앵커가 포함된 제한된 크기의 구문 강조 diff를 확인할 수 있습니다.

커밋 워크플로는 하나 이상의 Conventional Commit 제안을 만듭니다. 메시지를 편집하거나 제안을 다시 생성하고, 생성할 커밋을 고른 뒤 선택적으로 push할 수 있습니다. Studio는 커밋 전에 검토했던 인덱스와 현재 인덱스가 같은지 확인합니다.

## 설정과 운영

**Settings**에서는 전역 모델과 역할 할당, Gateway 공급자, System One 공급자와 decision 모델, 런타임 제한, 서비스, 직업형 서브에이전트, Agent Skills, MCP, 언어 서버와 `.qignore`를 관리합니다. 필드는 변경되면 자동 저장되며 별도의 저장 단축키가 없습니다.

워크스페이스를 선택하면 저장소별 모델 오버라이드가 표시됩니다. 공급자 변경은 Studio를 재시작하지 않아도 다음 턴부터 적용됩니다. API 키 값은 secret으로 처리되며 읽기 API로 다시 반환되지 않습니다.

**Operations**는 토큰 사용량, 활성·상주 실행, 로컬 서비스 상태, 보존 데이터와 제한된 로그를 보여줍니다. **Help**는 Studio 단축키와 호환 명령이 여는 현재 Studio 화면을 안내합니다.

## 로컬 런타임 경계

Studio는 기본적으로 루프백에 바인딩되며 파일, 프로세스, Git, 구성 작업은 로컬 q 프로세스를 통해 수행합니다. 브라우저에는 파일시스템 직접 접근 권한이 없습니다. 셸 명령은 로컬 q 프로세스의 권한으로 실행되며 운영체제 샌드박스는 아닙니다. `--host`로 네트워크 경계를 넓힌 경우 네트워크 또는 인증된 리버스 프록시에서 접근을 통제해야 합니다.

bare `q`는 호환 채팅 클라이언트로, `q acp`는 ACP 서버 진입점으로 유지됩니다. `q model`, `q gateway`, `q systemone`, `q subagents`, `q skills`, `q mcp`, `q lsp` 같은 구성 명령은 대응하는 Studio 화면을 엽니다.