# CLI 에이전트

터미널에서 이미 쓰고 있는 에이전트를 글쓰기 작업 공간 안에서 사용합니다.

설치해 둔 에이전트를 Oleafly로 가져오세요. **CLI 에이전트** 모드는 해당 에이전트의 런타임과 로그인을 사용하므로, 이미 쓰고 있는 도구로 원고 옆에서 작업할 수 있습니다.

![설정 → AI 어시스턴트 → CLI 에이전트. 위쪽에서 설치된 에이전트 확인을 누른 다음 에이전트를 펼쳐 설정을 마칩니다.](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-cli-agents-dark-window-v2.png#view=519,89,883,902)

## 에이전트 연결하기

1. **설정 → AI 어시스턴트 → CLI 에이전트**를 열고 **설치된 에이전트 확인**을 선택합니다.
2. 에이전트를 펼칩니다. **프로그램** 행에 Oleafly가 찾은 프로그램과 그 위치가 표시됩니다.
3. **테스트**를 선택합니다. 카드에서 브리지가 필요하다고 하면 먼저 **브리지 설치**를 선택합니다.
4. 에이전트 자체의 명령줄 도구로 로그인합니다. 카드에 **로그인 명령**이 표시되며, 프로젝트가 열려 있으면 **로그인 터미널 열기**로 그 명령을 실행할 터미널을 열 수 있습니다.
5. 어시스턴트를 열고 **CLI 에이전트**로 전환한 다음 에이전트를 고릅니다.
6. 프로젝트 구조를 설명하게 하거나 한 문단을 수정하게 하는 것처럼 작은 작업으로 시작합니다.

아직 준비되지 않은 에이전트로 전환하면 어시스턴트에 무엇이 빠졌는지 알려 주는 설정 카드가 표시됩니다. 카드의 버튼(예: **Claude Code 설정**)을 누르면 설정에서 해당 에이전트가 열립니다. 브리지만 빠져 있을 때는 카드의 **브리지 설치**로 설치할 수 있습니다.

인증, 모델 접근, 결제는 선택한 에이전트가 담당합니다. CLI를 지원하는 계정이나 구독은 해당 제공자의 약관에 따라 사용할 수 있으며, Oleafly가 별도의 AI 구독을 더하지는 않습니다.

## 프로그램 고르기

**프로그램** 레이블 아래에는 Oleafly가 시작하는 파일과 그 출처가 표시됩니다. **자동으로 찾음**, **직접 선택함**, **Oleafly가 설치함** 중 하나입니다. 일부 에이전트에서는 이 행이 대신 **ACP 브리지** 세부 정보 안에 있습니다.

다른 사본을 쓰려면 **선택…** 버튼을 눌러 파일을 고르세요. Oleafly가 아무것도 찾지 못했다면 행에 **이 컴퓨터에서 찾을 수 없음**이라고 표시되고 위치를 입력하는 필드가 나타납니다. 경로를 입력하거나 붙여 넣은 뒤 Enter를 누르거나 **테스트**를 선택하세요. 직접 고르거나 입력한 파일은 테스트를 통과한 뒤에만 저장됩니다. **자동 감지 사용**을 선택하면 직접 고른 선택이 해제됩니다.

Oleafly는 설치 프로그램이 에이전트를 두는 폴더를 살펴봅니다.

- Windows에서는 npm, pnpm, Scoop, winget 같은 도구로 어느 드라이브에 설치했든 에이전트를 찾습니다. 검색 경로를 매번 새로 읽으므로, Oleafly를 열어 둔 상태에서 설치한 에이전트도 **설치된 에이전트 확인**으로 찾을 수 있습니다.
- macOS에서는 Dock이나 Finder에서 Oleafly를 열더라도, `~/.local/bin`이나 nvm 폴더처럼 보통 shell만 아는 폴더에서도 에이전트를 찾습니다.

이름은 맞지만 Oleafly가 사용할 수 없는 파일을 찾으면, 설정에서 무엇을 찾았고 왜 쓸 수 없는지 알려 줍니다. Windows에서 흔한 경우는 Oleafly가 `.cmd` 또는 `.exe` 버전을 필요로 하는데 PowerShell 스크립트가 있는 경우입니다. **Oleafly가 건너뛴 파일**에는 그런 파일이 이유와 함께 하나씩 나열됩니다. 예를 들어 폴더, 데스크톱 앱, `node` 같은 shell이나 런타임, 네트워크 위치에 있는 사본이 있습니다.

설정의 경로는 마우스를 올리거나 Tab 키로 이동하기 전까지 흐리게 가려져 있으므로, 설정 화면을 스크린샷으로 찍어도 파일 위치가 드러나지 않습니다.

## 에이전트 테스트하기

**테스트**는 프로젝트와 떨어진 Oleafly 소유의 빈 폴더에서 에이전트를 시작하고 응답을 기다립니다. 아무것도 저장하지 않습니다. 통과하면 에이전트의 이름과 버전이 표시됩니다. 실패하면 이유를 알려 주는 문장 하나와 시도해 볼 방법 하나가 표시됩니다.

| 테스트 결과 | 시도할 일 |
| --- | --- |
| 해당 위치에 파일이 없거나, 폴더, 데스크톱 앱, Oleafly가 시작할 수 없는 파일임 | **선택…** 후 프로그램 파일 자체를 고릅니다 |
| 브리지가 아직 설치되지 않음 | **브리지 설치** |
| 에이전트에 Node.js 또는 더 새로운 버전이 필요함 | **Node.js 받기** |
| 에이전트가 시작되었지만 응답하지 않았거나, 일찍 멈췄거나, Oleafly가 읽을 수 없는 응답을 보냄 | **세부 정보 복사**, 또는 **터미널 열기**로 직접 실행해 봅니다 |

직접 고른 파일이 파일 자체가 아닌 다른 이유로 실패하면 **그래도 사용**으로 그 파일을 그대로 저장할 수 있습니다.

## 에이전트 카탈로그

| 에이전트 | CLI 명령 |
| --- | --- |
| Claude Code | `claude` |
| Codex CLI | `codex` |
| Gemini CLI | `gemini` |
| Pi | `pi` |
| OpenCode | `opencode` |
| OpenClaw | `openclaw` |
| Cline | `cline` |
| Hermes Agent | `hermes` |
| CodeBuddy | `codebuddy` |
| Kimi Code | `kimi` |
| Grok Build | `grok` |
| Cursor | `cursor-agent` 또는 `agent` |
| DeepSeek Harness | `dsh` |
| Qoder | `qodercli` |

카탈로그는 지원되는 실행 경로를 보여 줍니다. 사용할 수 있는 모델, 첨부, 세션 이어가기, 사용량 보고는 에이전트가 제공하는 기능에 따라 달라집니다. 설정은 세션을 시작하기 전에 빠진 요구 사항을 알려 줍니다.

Pi는 0.0.34 버전의 pi-acp 브리지를 통해 실행되며, Oleafly는 이 브리지가 내 Pi 프로그램을 가리키게 합니다. Windows에서는 이름에 공백이 있는 프로젝트 폴더도 처리합니다.

## 원고 옆에서 작업하기

에이전트에게 구체적인 요청을 하고, 어시스턴트 패널에서 응답, 도구 활동, 권한 요청을 따라가세요. 결과로 나온 소스를 열어 Oleafly에서 컴파일합니다.

> 서론과 방법 섹션을 읽어 주세요. 일관되지 않게 도입된 용어를 파일 위치와 함께 나열해 주세요.

별도 사본에서 작업하고 마지막에 검토하려면 [연구 작업](/docs/research-tasks/)에서 사용할 수 있는 에이전트를 고르세요. 격리된 작업의 플랫폼 요구 사항은 그 페이지에 나와 있습니다.

## 연구 시작점

새 대화는 연구 시작점을 제공하는 에이전트 홈 페이지에서 시작됩니다. 하나를 고르면 메시지가 채워지지만 전송되지는 않으므로 먼저 읽고 고칠 수 있습니다. 열려 있는 대화가 아직 없으면 새 대화를 시작합니다.

| 시작점 | 요청하는 내용 |
| --- | --- |
| **문헌 조사** | `oleafly-literature-sweep` 스킬로 프로젝트의 연구 질문에 맞는 주석 달린 읽기 목록을 만듭니다 |
| **관련 연구** | `oleafly-related-work`로 읽기 목록과 참고문헌을 바탕으로 관련 연구 섹션 초안을 작성합니다 |
| **인용 점검** | `oleafly-verify-claims`로 원고의 주장을 인용한 출처와 대조해 확인합니다 |
| **원고 검토** | `oleafly-review-manuscript`로 원고 전체를 검토합니다 |
| **재현성 점검** | 각 결과를 재현하는 데 빠진 것: 코드, 데이터, 소프트웨어 버전, 난수 시드, 빌드 방법 |
| **그림 점검** | 모든 그림과 표를 점검합니다: 캡션, 레이블, 상호 참조, 축 레이블과 단위, 가독성, 그레이스케일에서도 구분되는 색 |
| **Git 검토** | 커밋하지 않은 변경 사항과 최근 커밋을 요약하고 의도하지 않은 것으로 보이는 편집을 표시합니다. Git 저장소에서만 표시됩니다 |
| **참고 문헌 정리** | **참고문헌 라이브러리 정리**를 엽니다. 변경 사항을 미리 본 뒤 인용 키를 표준화하고 중복을 제거합니다 |

점검과 원고 검토는 에이전트에게 원고 파일을 건드리지 말고 `research/`의 파일에 결과를 쓰라고 요청합니다. 예를 들면 `research/figure-audit.md`입니다.

시작점이나 홈 페이지의 스킬 목록에서 고른 스킬은 메시지 위에 칩으로 표시됩니다. Oleafly는 스킬의 지침을 메시지와 함께 보내므로, Pi처럼 Oleafly의 도구를 받지 못하는 에이전트도 그 지침을 따를 수 있습니다. 칩을 클릭하면 스킬이 제거됩니다. 프로젝트에서 스킬이 꺼져 있으면 시작점은 스킬 없이 메시지만 채웁니다.

## 권한 요청

에이전트가 동작하기 전에 묻는 경우, 카드에 **에이전트에 권한이 필요합니다**라고 표시되고 에이전트가 제시하는 선택지가 나옵니다. 요청이 파일을 변경하는 것이라면 카드에 해당 파일이 나열됩니다. **변경 사항 보기**를 누르면 파일의 diff가 열리므로 답하기 전에 읽어 볼 수 있습니다. 너무 커서 표시할 수 없는 변경은 그렇다고 알려 주며, 차례가 끝난 뒤에 검토할 수 있습니다. **닫기**는 요청을 허용하지 않고 취소합니다. 2분 동안 그대로 둔 요청은 만료되며, 에이전트가 다시 물어야 합니다.

## 변경 사항 검토하고 실행 취소하기

파일을 변경한 차례가 끝나면 응답 아래 한 줄에 변경된 파일 수가 표시됩니다. **검토**는 각 변경 사항을 보여 주고, **실행 취소**와 **다시 실행**은 파일 단위 또는 차례 전체에 적용됩니다. 작동 방식과 건드리지 않는 대상은 [차례 검토하고 실행 취소하기](/docs/ai-chat/#review-and-undo-a-turn)에서 설명합니다.

## 대화와 내보내기

어시스턴트 헤더에는 **새 대화**, **저장된 대화**, **에이전트 설정**이 있습니다. 각 대화에는 시작할 때 프로젝트가 있던 Git 커밋이 기록됩니다.

Oleafly 밖에 사본을 보관하려면 **저장된 대화**를 열고 **대화 내보내기…** 항목을 선택한 다음 저장 대화 상자에서 Markdown이나 JSON을 고르세요. Markdown 파일은 프로젝트, 에이전트, 모델, 대화가 시작된 시점의 커밋(커밋하지 않은 변경 사항이 있으면 그렇다고 표시), 시작 시각과 마지막 업데이트 시각으로 시작합니다. 그 뒤에 메시지, 스킬, 도구 호출, 변경된 파일이 이어집니다. JSON에는 전체 기록이 담깁니다.

## 사용자 지정 에이전트

**에이전트 더 찾기**를 선택하면 다른 팀이 공개한 에이전트를 ACP 레지스트리에서 검색하고, **사용자 지정 에이전트 추가**를 선택하면 정의를 직접 붙여 넣을 수 있습니다. 실행하기 전에 실행 파일이나 패키지, 인수, 연결 요구 사항을 검토하세요. 정의를 등록한다고 해서 에이전트가 설치되거나 시작되지는 않습니다.

## 대신 외부 클라이언트 사용하기

에이전트 자체의 인터페이스를 계속 쓰고 싶다면 MCP로 연결하세요. [Oleafly의 MCP 서버](/docs/mcp/)는 Oleafly가 열려 있는 동안 앱의 프로젝트 도구를 에이전트에 제공합니다. [`oleafly` 명령](/docs/cli/#connect-an-agent-over-mcp)은 앱이 닫혀 있어도 작동하고, [`oleafly-cli` 스킬](/docs/cli/#the-oleafly-cli-skill)은 에이전트에게 그 명령을 가르쳐 줍니다.