# OSCODE Web CLI

터미널에서 실행하는 OSCODE 에이전트를 브라우저 대화 화면에서 사용합니다. 별도의 클라우드 서비스가 아닌 로컬 전용 UI입니다.

```sh
# 저장소에서 실행
node bin/oscode.js --web --cwd /path/to/project
# 키 없이 실제 파일 목록을 읽는 제한된 데모
node bin/oscode.js --web --demo --cwd /path/to/project
# 설치된 버전에 --web 기능이 포함된 경우
oscode --web --cwd /path/to/project
```

0.19.0부터 웹 CLI를 지원합니다.

- 왼쪽: 새 대화, 최대 8개 세션 전환, 대화 검색
- 가운데: 자연어 요청, 응답 스트리밍, 복사, 고정 입력창, 실행 중 다음 요청 초안 작성
- 아래: 개별 파일 수정·명령 실행 승인/거절. 영구 자동 승인 버튼은 없습니다.
- 오른쪽: 실제 도구 입력, 결과, 완료/실패 상태
- Enter 전송, Shift+Enter 줄바꿈. IME 조합 중 Enter는 전송하지 않습니다.
- 동일 프로젝트에서는 한 번에 한 작업만 실행합니다. 중단 버튼으로 실행을 취소할 수 있습니다.

## 모델과 권한

기존 oscode.json, CLI 인수, 환경 변수, 저장된 인증 정보를 사용합니다. API 키는 브라우저에 전달하지 않습니다. `oscode auth set` 또는 기존 모델 설정 후 실행하세요. 설정을 바꾸면 서버를 다시 시작합니다. `--demo`는 모델 API 없이 파일 목록을 읽으며 실제 코딩 AI가 아닙니다.

CLI의 실제 `runTurn`, `WorkspaceTools`, 체크포인트 및 세션 저장을 ACP 어댑터를 통해 재사용합니다. 파일 편집 및 셸 실행은 웹에서 한 번씩 승인합니다. 기존 deny 권한은 유지됩니다. 셸은 운영체제 샌드박스가 아니므로 승인한 명령은 프로젝트 밖에 영향을 미칠 수도 있습니다.

127.0.0.1에 임의 포트와 비밀 경로로 열립니다. 이 주소를 공유하거나 외부로 프록시하지 마세요. Host/Origin, POST JSON 검증과 CSP를 적용합니다. 브라우저 접속이 30초 넘게 끊기면 진행 중인 작업에 취소를 요청하며 승인 대기는 최대 2분입니다. 백그라운드 탭을 오래 두면 브라우저의 타이머 제한 때문에 취소될 수 있습니다.

대화는 `.oscode`에 저장됩니다. 실행 중인 서버에서는 새로고침 후 복원됩니다. 서버 재시작 후 과거 세션 선택 UI, 모든 슬래시 명령, MCP 설정 UI, 파일 첨부, 웹 모델 변경은 아직 지원하지 않습니다. 프로젝트 코드가 모델에 전송되는 범위는 기존 CLI와 같습니다.

## 작업 목록 · 승인 · 예정 · ID

입력한 요청은 각각 `OSC-…` 작업 ID로 등록됩니다. 오른쪽 **목록** 또는 왼쪽 **작업 목록**에서 전체 작업, 승인 필요, 예정·대기, 종료된 작업을 골라 볼 수 있습니다. ID를 누르면 복사됩니다. 작업 카드의 **대화 보기**로 관련 대화를 열 수 있습니다.

- **목록**: 대기 / 예정 / 진행 중 / 승인 필요 / 응답 완료 / 실패 / 한도 도달·중단 / 취소를 구분합니다. ‘응답 완료’는 에이전트 턴 종료를 뜻하며 결과물의 품질 검증이나 업무 성공을 보장하지 않습니다.
- **승인**: 파일 변경·명령 실행 요청에 작업 ID가 표시됩니다. 각 작업의 승인 기록에서 승인, 거절, 만료를 확인합니다. 승인은 해당 행동 1회에만 적용됩니다.
- **예정**: 작업 진행 중 새 요청은 대기열에 들어갑니다. 입력창 위 **실행 시점 → 날짜와 시간 지정**으로 예약할 수 있습니다. 화면에 입력한 로컬 시각을 기준으로 예약합니다. 예약 시각은 시작 가능한 가장 이른 시각입니다. 프로젝트당 하나씩 실행하므로 앞 작업이나 승인 대기가 끝날 때까지 늦어질 수 있습니다. 실행 중단과 예정·대기 취소를 지원합니다.
- **ID**: 요청마다 고유한 ID가 생깁니다. 브라우저 새로고침 후 같은 ID와 상태, 승인 기록을 유지합니다. 네트워크 재전송 시 같은 요청 ID로 중복 등록되지 않도록 서버에서 확인합니다.

서버 실행당 최대 100개 작업입니다. 작업 목록·예약·승인 기록은 실행 중인 서버 메모리에 있습니다. 서버 재시작 후에는 복원하지 않으며, 종료하면 대기·예약 작업은 취소됩니다. 실제 대화와 도구 실행 기록은 기존 `.oscode` 세션에 저장됩니다. 서버와 브라우저가 연결된 동안만 대기열을 실행합니다. 브라우저 연결이 끊기면 30초 이후 진행 중 작업에 중단을 요청하고, 나머지 대기 작업은 재연결 시 순서대로 이어집니다. 캘린더 연동·외부 이벤트 감지·반복 예약은 아직 포함하지 않습니다.

## 작업 상세 타임라인

작업 카드의 **작업 상세**를 누르면 왼쪽에 해당 작업의 실제 도구 호출 단계, 오른쪽에 선택한 단계의 입력·승인 시 변경 미리보기·출력·소요 시간이 표시됩니다. 완료·실패·실행 중을 구분하고 승인 기록과 작업 ID를 연결합니다. 대화별 최근 최대 100개 도구 기록을 표시하며, 오래된 단계는 생략될 수 있습니다. 소요 시간은 도구 요청부터 결과 수신까지로 승인 대기를 포함합니다. 도구가 반환한 출력 자체를 표시하며 실행되지 않은 단계나 성공 설명을 생성하지 않습니다. Esc 또는 닫기 버튼으로 돌아갑니다.

## 실시간 브라우저 작업 창

왼쪽 **실시간 브라우저 열기** 버튼으로 작업 창을 엽니다. 주소를 입력하면 별도 Chromium에서 페이지를 실행하고 약 1초마다 현재 화면을 표시합니다. 프레임에는 방문한 페이지의 실제 내용이 포함됩니다. 개인 브라우저의 로그인·쿠키는 공유하지 않습니다.

- **직접 제어**: 화면 클릭·휠 스크롤, 입력칸을 클릭한 후 하단 텍스트 전송, Enter/Tab 등 키 전송, 뒤로가기·새로고침을 지원합니다.
- **에이전트에게 넘기기**: 사용자의 조작 버튼을 잠그고 에이전트가 같은 페이지를 사용할 수 있게 합니다. 자연어로 ‘browser_live로 이 페이지의 버튼을 확인해줘’처럼 요청할 수 있습니다. 에이전트의 각 브라우저 동작은 기존 실행 승인과 deny 권한을 따릅니다. 데모 모델은 브라우저를 조작하지 않습니다.
- **브라우저 직접 제어**: 에이전트로부터 제어권을 가져오고 연결된 실행 작업에 취소를 요청합니다. 이미 시작된 브라우저 동작은 마무리될 수 있으며, 대기 중인 이후 동작은 제어권을 다시 확인합니다.
- **중지**: 브라우저를 종료하고 연결된 작업에 취소를 요청합니다. 창 닫기(×)는 보기만 닫으며 브라우저를 종료하지 않습니다.
- **대화·승인 요청 보기**: 창을 닫고 실제 승인 카드로 돌아갑니다.

Playwright Chromium이 필요합니다. 시작할 수 없다는 안내가 나오면 `npx playwright install chromium`으로 브라우저를 설치하세요.

현재는 1280×800 뷰포트의 단일 탭·기본 입력을 지원합니다. 팝업, 다운로드, 파일 업로드, 브라우저 확인 대화상자, 전체 데스크톱 조작은 지원하지 않습니다. 모델에는 제한된 본문·컨트롤 정보가 전달되며, 스크린샷 영상 스트림 자체를 모델에 전달하지 않습니다. 화면 갱신 간격은 작업 및 시스템 부하에 따라 길어질 수 있습니다. 서버를 종료하면 쿠키를 포함한 격리 브라우저 상태도 종료됩니다. 페이지를 여는 것 자체로 대상 사이트에 네트워크 요청이 발생합니다.