---
name: fine-setup
description: Fine(맥 GUI)을 설치·점검·설정할 때 사용한다. 설정창이 없으므로 `fine` CLI로 상태를 읽고 빠진 것을 채운다. 하네스 추가, 모델·외형·배경 설정, 재시작, 문제 진단.
---

# Fine 설정

Fine에는 설정창도 로그인 화면도 없다. 계정은 하네스(Claude Code·Codex·OpenCode·omp)가
각자 들고 있고, Fine은 그 위에 또 하나의 인증을 만들지 않는다. 대신 `fine` CLI가 설정
표면이다 — 사람이 읽어도 되고, 그대로 실행해도 된다.

## 먼저 할 일

```sh
fine doctor
```

준비된 것, 빠진 것, **빠진 것을 채우는 명령**이 함께 나온다. `✗`는 막는 것이고,
`·`는 없어도 되는 것(기능 하나가 빠질 뿐)이다. 무엇을 할지 정하기 전에 항상 이것부터 읽는다.

응답이 없으면 앱이 안 떠 있는 것이다. `open -a Fine` 후 다시 시도한다.

## 흔한 상황

### 하네스를 추가하고 싶다

`fine doctor`가 실행 파일을 못 찾으면 그 줄에 설치 명령이 붙어 나온다. 설치한 뒤
Fine을 다시 띄우면 컴포저의 하네스 목록에 나타난다 — Fine은 앱을 열 때 있는 것을 찾는다.

### 모델이 안 보인다

```sh
fine models --harness claude    # 지금 이 하네스가 아는 모델과 effort
```

Claude에서 다른 제공사 모델이 안 보이면 라우터(127.0.0.1:4141)가 없는 것이다.
`fine doctor`가 그것을 알려준다. 라우터 없이도 Claude 모델은 쓸 수 있다.

omp는 `~/.omp/agent/config.yml`의 `enabledModels`를 그대로 따른다. 목록이 이상하면
그 파일을 본다 — Fine은 그 화이트리스트를 존중할 뿐 자기 목록을 따로 갖지 않는다.

### 자동 모드가 안 돈다

모델·effort를 질문 난이도로 고르는 기능은 로컬 판정 서버가 필요하다.

로컬 System One 서버를 `127.0.0.1:8009`에 띄우면 된다 (예: `jaredpalmer/kev`).

없어도 대화는 정상적으로 시작된다 — 사용자가 마지막에 쓰던 설정으로 떨어질 뿐이다.

### 외형·배경

```sh
fine appearance            # 지금 상태 (앱과 각 창이 실제로 무엇으로 해석됐는지까지)
fine appearance dark       # 즉시 적용, 재시작 불필요
```

홈 배경은 `~/.fine/home-scene.png`에 파일을 두면 된다 (앱 안에서는 ⇧⌘B).
빌드도 저장소 수정도 필요 없다. 지우면 기본 장면으로 돌아간다.

## 재시작

설정 대부분은 즉시 반영된다. 앱 자체를 새로 빌드했을 때만 재시작이 필요하다.

**Fine 안에서 도는 에이전트가 Fine을 종료하면 자기 세션이 끊긴다.** 먼저 세션 ID를 남긴다:

```sh
fine --json tabs
```

대화 ID가 있는 탭은 다시 열릴 때 스스로 이어지므로, 보통은 그냥 재시작하면 된다.
프로세스 이름이 전체 경로라 `pkill -x Fine`은 매칭되지 않으니 PID로 잡는다.
macOS에는 `setsid`가 없어서 백그라운드 재시작 스크립트에 쓰면 조용히 실패한다.

## 진단

```sh
fine ping                  # 앱이 살아 있나, 제어 소켓이 붙었나
fine tabs                  # 열린 탭과 각자의 모델·세션 ID
fine theme <tab>           # 그 터미널이 실제로 쓰는 색 (눈으로는 확인이 안 되는 값)
fine state                 # 창 상태 덤프
```

화면을 보고 짐작하지 말고 이 값들을 읽는다. 색이나 모델 선택처럼 "그대로인 것 같다"는
보고는 대개 실제 값을 확인하면 갈린다.

## 하지 말 것

- **하네스의 인증 파일을 복사하거나 공유하지 않는다.** omp는 Codex OAuth를 자기
  `agent.db`에 별도 체인으로 들고 있고, `~/.codex/auth.json`과 리프레시 토큰이 다르다.
  한쪽을 다른 쪽에 덮으면 양쪽 모두 revoke된다.
- **다른 체크아웃에서 빌드한 앱을 설치하지 않는다.** UI 시안용으로 떠둔 스냅샷에는
  `fine` CLI와 제어 소켓이 없어, 설치하면 CLI가 통째로 죽는다.