# 지침, 승인, 설정

작성 선호 사항을 정하고, 어시스턴트가 언제 물어볼지 고르고, 재사용할 수 있는 프로젝트 규칙을 설정합니다.

어시스턴트에게 분명한 작성 선호 사항을 알려 주고 변경 사항을 어떻게 처리할지 고르세요. 지침은 원하는 작업을 설명하고, 승인 컨트롤은 어떤 도구 작업을 진행할 수 있는지 결정합니다.

![설정 → AI 어시스턴트 → 지침. 기본 모델을 정하고 지침을 작성한 다음 지침 저장을 누릅니다. PDF 페이지 캡처는 텍스트 필드 아래에 있습니다.](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-instructions-dark-window-v2.png#view=519,89,883,724)

## 기본 채팅 모델

**설정 → AI 어시스턴트 → 지침**을 여세요. **기본 채팅 모델**을 고르면 새 채팅에서 쓸 모델이 정해집니다. 목록에는 설정한 제공자의 활성화된 모델이 들어 있습니다. 개별 대화에서는 언제든 모델을 바꿀 수 있습니다.

## 사용자 지정 지침

**사용자 지정 지침**에 선호 사항을 입력하고 **지침 저장**을 클릭하세요. 연구 원고를 쓸 때 시작점으로 쓸 만한 예는 다음과 같습니다.

```text title="글쓰기 지침 예시"
Use British English and preserve the terminology already used in the paper.
Keep citation keys, labels, equations, and numerical results unchanged unless
I explicitly ask you to edit them.
When a statement needs evidence, mark it for a source check. Do not invent
references or results.
Explain substantive changes briefly so I can review them.
```

지침은 프로젝트 개요 전체를 되풀이하지 않고도 수정 방향을 안내할 수 있을 만큼 구체적으로 쓰세요. 지침은 어시스턴트의 기본 동작을 보완할 뿐 도구 권한을 바꾸지는 않습니다.

## 지침 저장

편집한 뒤 **지침 저장**을 클릭하세요. **저장됨** 표시가 나타나면 저장된 것입니다. 이 필드에서 저장하지 않은 편집은 새 기본값이 되지 않습니다.

## AI의 PDF 페이지 캡처 허용

**AI의 PDF 페이지 캡처 허용**을 켜면 어시스턴트가 비전을 지원하는 모델로 렌더링된 페이지를 확인할 수 있습니다. `verify_pdf_pages` 도구는 레이아웃을 점검하려고 컴파일된 페이지를 이미지로 변환합니다. 페이지 이미지를 설정한 제공자에게 보내고 싶지 않다면 이 컨트롤을 끄세요.

## 도구 카탈로그 살펴보기

지침 탭에서 **어시스턴트가 현재 지원하는 도구**를 펼치세요. 어시스턴트가 수행할 수 있는 작업을 확인한 다음, 섹션 컴파일, PDF 확인, 확인되지 않은 참조 찾기 같은 결과를 요청하세요.

## 페르소나

![설정 → AI 어시스턴트 → 페르소나. 페르소나 만들기는 목록 위에 있고, 편집과 삭제 컨트롤은 각 페르소나 옆에 있습니다.](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-personas-dark-window-v2.png#view=519,89,883,902)

페르소나는 이름을 붙인 지침 프리셋입니다. **설정 → AI 어시스턴트 → 페르소나**에서 만든 다음, 특정 종류의 작업을 할 때 채팅 입력창에서 선택하세요. 예를 들어 간결한 교정 페르소나와 별도의 심사자 페르소나를 만들어 둘 수 있습니다.

활성화된 페르소나는 기본 사용자 지정 지침 텍스트 대신 대화의 지침 프리셋을 제공합니다. 페르소나에도 필요한 상시 선호 사항은 함께 넣으세요. 페르소나가 바꾸는 것은 안내이며, 도구 권한을 부여하지는 않습니다.

## 승인 모드 고르기

![메시지 입력란 아래에서 승인 메뉴를 엽니다. 선택된 모드에는 체크 표시가 나타납니다. 프로젝트에 적용할 정책을 고르세요.](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-approval-menu-dark-window-v2.png#view=1448,770,465,305)

채팅 입력창의 승인 선택기를 사용하세요. 선택한 내용은 현재 프로젝트에 저장됩니다.

| 모드 | 동작 |
|---|---|
| **승인 요청** | 읽기로 분류된 도구는 실행할 수 있고, 그 밖의 작업은 먼저 묻습니다 |
| **알아서 승인** | 읽기와 네트워크 도구는 실행할 수 있고, 파일 변경과 shell 명령은 먼저 묻습니다 |
| **전체 접근 권한** | `deny` 규칙이 막은 도구를 제외하고, 도구 작업이 승인 요청 없이 진행될 수 있습니다 |
| **사용자 지정** | 저장된 `allow`, `deny` 규칙이 적용되고, 규칙이 없는 도구는 표준 위험 정책을 따릅니다 |

**알아서 승인**이 기본값입니다. 일부 도구는 작업 안에서 자체 검사를 수행합니다. 컴파일과 PDF 확인은 소스 파일 쓰기나 shell 명령 실행과 다르게 취급됩니다.

## 제안된 작업 승인하기

승인 카드에서 도구 이름과 제안된 작업을 읽으세요. 승인하면 그 작업이 실행되고, 거부하면 제안된 변경이 적용되지 않은 채로 남습니다. 요청한 작업이 너무 광범위하다면 더 좁은 지시로 대화를 이어 가세요.

## 이 프로젝트에서는 항상

**사용자 지정** 모드에서 승인 요청의 **이 프로젝트에서는 항상**을 사용하면 해당 도구의 규칙이 저장됩니다. 규칙이 다음 실행에 영향을 주기를 기대한다면 선택된 모드를 확인하세요.

## 규칙 검토하거나 제거하기

프로젝트를 연 상태에서 **설정 → AI 어시스턴트 → 제공자와 키**로 이동해 **도구 승인**까지 스크롤하세요. 각 행에는 도구 이름과 항상 허용되는지 거부되는지가 표시됩니다. 규칙을 제거하면 사용자 지정 모드에서 그 도구가 표준 위험 정책으로 돌아갑니다.

## approvals.toml 편집하기

**도구 승인** 아래의 **승인 규칙 파일**에서 `~/.oleafly/approvals.toml`을 편집합니다. **다시 불러오기**는 현재 파일을 읽고, **변경 사항 버리기**는 저장하지 않은 편집을 버리며, **예시 넣기**는 샘플 설정으로 시작합니다. **이 파일의 동작 방식**은 형식을 설명하고 열려 있는 프로젝트의 ID를 보여 줍니다. 저장할 때는 TOML을 먼저 검증한 다음 적용하며, 규칙은 다음 도구 호출부터 적용됩니다.

이 파일에는 모드 테이블과, 표시 제목이 아니라 **프로젝트 폴더 ID**를 키로 하는 도구 규칙 테이블이 들어 있습니다.

```toml title="~/.oleafly/approvals.toml"
["$approval_modes"]
"my-project-folder-id" = "custom"

["my-project-folder-id"]
write_file = "allow"
replace_in_file = "allow"
run_command = "deny"
delete_file = "deny"
```

`my-project-folder-id`를 프로젝트의 실제 폴더 ID로 바꾸세요. 프로젝트 ID는 `~/.oleafly/projects` 아래의 폴더 이름입니다. 모드 값은 `ask-for-approval`, `approve-for-me`, `full-access`, `custom`입니다. 목록에 없는 프로젝트는 알아서 승인을 사용합니다. 도구 규칙 값은 `allow`와 `deny`입니다. `deny` 규칙은 전체 접근 권한을 포함한 모든 모드에 적용되므로 거부된 도구는 절대 실행되지 않습니다. `allow` 규칙은 사용자 지정 모드에서만 적용됩니다. 규칙이 없는 도구는 일반 위험 정책을 따릅니다.

`#`으로 시작하는 주석은 설정에서 저장해도 유지되지만, 승인 카드에서 **이 프로젝트에서는 항상**을 고르면 파일이 주석 없이 다시 쓰입니다.

카탈로그에 있는 정확한 도구 이름을 사용하세요. 자주 쓰는 이름으로는 `write_file`, `replace_in_file`, `create_file`, `rename_file`, `delete_file`, `run_command`, `compile`, `insert_figure`, `set_main_doc`이 있습니다.

## 어떤 설정 파일을 써야 하나요?

| 파일 | 용도 |
|---|---|
| `~/.oleafly/config.json` | 앱 설정이며 설정 화면에서 관리합니다 |
| `~/.oleafly/approvals.toml` | 프로젝트별 승인 모드와 도구별 규칙 |
| `~/.oleafly/agent.toml` | 고급 멀티 에이전트 한도와 지침 |
| 외부 에이전트의 설정 파일(예: `~/.codex/config.toml`) | 해당 에이전트 자체의 설정과 MCP 연결 |

Oleafly는 이 모든 설정에 하나의 `config.toml`을 쓰지 않습니다. 제공자 키와 앱 환경설정은 설정 화면에서 관리하세요. 자격 증명은 별도의 암호화된 저장소에 보관됩니다. 앱 설정 전체를 짧은 예시로 바꾸지 마세요.

## agent.toml 설정하기

고급 사용자는 `~/.oleafly/agent.toml`을 만들어 어시스턴트의 멀티 에이전트 설정을 조정할 수 있습니다. 이 설정은 연결된 CLI 에이전트의 설정과는 별개로 Oleafly 자체 에이전트 런타임을 제어합니다.

```toml title="~/.oleafly/agent.toml"
maxAgentDepth = 2
maxConcurrentSubagents = 8
minWaitTimeoutMs = 1000
maxWaitTimeoutMs = 300000
defaultWaitTimeoutMs = 120000
waitAgentEnabled = true

usageHintText = """
Delegate independent checks with clear scopes. Keep writing decisions with
the parent agent, and close completed agents when their work is collected.
"""

subagentDeveloperInstructions = """
Work only on the assigned task. Report the files and evidence you inspected.
Do not spawn additional agents.
"""
```

### maxAgentDepth

중첩 깊이를 제한합니다. 기본값은 `2`이며, 실행의 하위 에이전트는 더 위임하지 않습니다. 허용되는 최솟값은 `1`입니다.

### maxConcurrentSubagents

한 세션에서 동시에 실행되는 하위 에이전트 수를 제한합니다. 기본값은 `8`이고 최솟값은 `1`입니다. 에이전트가 많아지면 모델 사용량이 늘 수 있으므로, 실제로 독립적으로 진행할 수 있는 작업에만 한도를 올리세요.

### minWaitTimeoutMs

에이전트 대기 시간의 하한을 밀리초 단위로 정합니다. 기본값은 `1000`입니다.

### maxWaitTimeoutMs

에이전트 대기 시간의 상한을 정합니다. 기본값은 `300000`으로 5분입니다. 최솟값 이상으로 유지됩니다.

### defaultWaitTimeoutMs

기본 대기 시간을 정합니다. 기본값은 `120000`으로 2분입니다. 값은 설정된 최솟값과 최댓값 범위 안으로 제한됩니다.

### waitAgentEnabled

에이전트 대기 기능을 사용할 수 있는지를 제어합니다. 기본값은 `true`입니다.

### usageHintText

상위 에이전트에게 위임 지침을 제공합니다. 위 예시는 기본 지침을 직접 쓴 텍스트로 바꿉니다.

### subagentDeveloperInstructions

하위 에이전트에게 지침을 제공합니다. 작업 범위, 보고 방식, 추가 위임이 적절한지를 밝히는 데 사용하세요.

런타임은 이 키의 snake_case 형태, 예를 들어 `max_agent_depth`도 받습니다. 생략한 필드는 기본값을 씁니다. 파일이 없거나 형식이 잘못되면 기본값으로 돌아가므로, 구문을 꼼꼼히 확인하고 설정을 바꾼 뒤에는 새 실행을 시작하세요.

## 작은 작업으로 규칙 시험하기

1. 연습용 프로젝트를 열고 **승인 요청**을 고릅니다.
2. 다음과 같이 요청합니다. “주 문서를 읽고 더 명확한 제목을 제안해 주세요. 파일을 바꾸기 전에 물어봐 주세요.”
3. 제안된 변경 사항을 확인하고 승인하거나 거부합니다.
4. 사용자 지정 모드로 바꾸기 전에 설정에서 저장된 규칙을 검토합니다.
5. 편집을 시작하기 전에 여러 단계를 합의하고 싶다면 [계획 모드](/docs/ai-chat/#plan-before-editing)를 사용합니다.

Oleafly MCP로 연결하는 외부 어시스턴트는 별도로 설정하는 [MCP 서버의 정책](/docs/mcp/#approvals-and-safety)을 따릅니다.