Paseo 활용편 — 처음부터 끝까지 따라 하기
완전 가이드가 “이 기능은 무엇인가”를 설명하는 사전이라면, 활용편은 “이 일을 하려면 무엇을 어떤 순서로 누르나”를 보여 주는 따라 하기 문서입니다. 실습 10개는 모두 준비물 → 따라 하기 → 막히면 순서로 되어 있고, 단계마다 “무엇이 보이면 성공인지”를 적어 두었습니다.
- 1. 설치부터 첫 결과까지 — Paseo 를 처음 켜는 사람
- 2. 두 가지 일을 동시에 — 일 두 개를 한꺼번에 맡기고 싶을 때
- 3. 결과 검토하고 직접 돌려 보기 — 에이전트가 바꾼 것을 내 눈으로 확인하고 싶을 때
- 4. 밖에서 폰으로 이어서 지시하기 — 자리를 비워도 일을 이어가고 싶을 때
- 5. 자주 쓰는 설정을 프로필로 저장하고 두 번째 에이전트에게 검토 맡기기
- 6. 에이전트가 일꾼 에이전트를 부리게 하기 — Paseo tools 켜기
- 7. 매일 아침 정리 작업 예약하기 — Schedules
- 8. 오래 걸리는 빌드를 끝까지 지켜보게 하기 — 하트비트
- 9. 새 워크트리가 바로 돌아가게 준비하기 — .worktreeinclude · paseo.json
- 10. 막혔을 때 — 에이전트가 안 보임 · 설정이 안 먹힘 · 연결 실패
시작 전 준비를 마친 뒤 기본 순서 1 → 2 → 3 → 4 → 5 를 차례대로 따라 하세요. 앞 실습에서 만든 것을 다음 실습이 이어서 씁니다.
6~10 은 선택입니다. 실습 지도에서 필요한 것만 골라 하면 됩니다. 다만 7의 6단계와 8은 6의 1~2단계(Paseo tools 켜기)를 먼저 해 둡니다. 어디서든 막히면 10 막혔을 때를 먼저 봅니다.
실습 지도 — 기본 1 → 2 → 3 → 4 → 5, 선택 6~10
아래 그림의 동그라미와 상자를 누르면 그 실습으로 이동합니다. 윗줄은 차례대로 하는 기본 순서, 아랫줄은 필요할 때 골라 하는 선택 실습입니다.
| 이런 때 | 이 실습 |
|---|---|
| Paseo 를 처음 써 본다 | 1 → 2 → 3 |
| 자리를 비운 사이에도 진행을 보고 지시하고 싶다 | 4 폰으로 이어 하기 |
| 매번 같은 에이전트 설정을 고르기 번거롭다, 결과를 한 번 더 검토받고 싶다 | 5 프로필 · 검토 맡기기 |
| 큰 일을 에이전트가 알아서 나눠 맡기게 하고 싶다 | 6 일꾼 에이전트 부리기 |
| 정해진 시간마다 같은 일을 맡기고 싶다 / 오래 걸리는 일을 끝까지 지켜보게 하고 싶다 | 7 예약 / 8 하트비트 |
| 새 워크트리를 만들 때마다 준비 작업을 손으로 하고 있다 | 9 워크트리 준비 |
| 무언가 안 된다 | 10 막혔을 때 |
시작 전 준비 — 세 가지를 먼저 갖추세요
Paseo 는 에이전트(사람 대신 코드를 읽고 고치고 명령을 실행하는 AI 프로그램 — Claude Code, Codex 등)에게 일을 맡기고, 결과를 검토하고, 직접 돌려 보는 「에이전트 개발 환경」입니다. 실습을 시작하기 전에 아래 세 가지를 준비합니다.
- 에이전트 CLI 하나를 설치하고 로그인하기Paseo 는 에이전트를 직접 갖고 있지 않습니다. 내가 설치해 둔 에이전트 CLI(글자 명령으로 쓰는 프로그램)를 대신 실행하고 관리해 줄 뿐입니다. 그래서 쓸 에이전트를 적어도 하나 직접 설치하고, 내 계정으로 잘 동작하는지 먼저 확인해 두어야 합니다. 방법은 바로 아래 에이전트 준비에 있습니다.
- (권장) GitHub CLI
gh설치하고 로그인하기GitHub CLI(GitHub 를 글자 명령으로 다루는 도구 — 명령 이름이gh)를 설치하고 로그인(인증)까지 해 둡니다. 꼭 있어야 하는 것은 아니고 권장입니다 — 없으면 PR 관련 단계만 못 합니다. Paseo 는 PR(내 변경을 원본에 합쳐 달라는 요청)과 연결된 작업 폴더 기능과 오케스트레이션(에이전트가 다른 에이전트에게 일을 나눠 맡기는 것)의 일부 기능에gh를 씁니다. 설치 안내는 cli.github.com 에 있습니다. - Paseo 데스크톱 앱 받기paseo.sh/download 또는 GitHub 의 releases 페이지에서 받습니다. 데스크톱 앱은 데몬(내 컴퓨터에서 계속 켜져 에이전트와 워크스페이스를 맡아 돌리는 Paseo 의 본체 프로그램)을 함께 갖고 있어서 따로 설치할 것이 없습니다. 실제 설치와 첫 실행은 실습 1의 첫 단계에서 합니다.
“Paseo 로 실습을 하려고 합니다. 에이전트 CLI 하나(예: Claude Code 또는 Codex)를 제 컴퓨터에 설치하고 로그인해서, 터미널에서 실행되는지 확인해 주세요. GitHub CLI gh 도 설치하고 로그인해 주세요. 연습해도 되는 git 저장소를 제 컴퓨터에 준비하고 폴더 위치도 알려 주세요.”
- 준비 완료 기준 ① 터미널(글자로 명령을 입력하는 창)에서 내 에이전트 CLI 를 실행하면 로그인된 상태로 켜집니다.
- 준비 완료 기준 ② (권장)
gh가 설치되어 있고 로그인되어 있습니다. - 준비 완료 기준 ③ 데스크톱 앱 설치 파일을 받을 곳(paseo.sh/download)을 알고 있습니다.
데스크톱 앱 말고 다른 설치 방법
화면 없는 서버나 개발용 컴퓨터에는 데스크톱 앱 없이 데몬만 돌릴 수 있습니다. npm install -g @getpaseo/cli 로 설치하고 paseo 를 실행하면 데몬이 켜지고, 릴레이(폰과 데몬 사이를 이어 주는 중계 서버)를 쓸지와 폰을 짝지을 QR 코드를 보여 줄지를 묻습니다. 서버·NAS 등에는 공식 Docker 이미지도 있습니다(이 이미지에는 에이전트 CLI 가 들어 있지 않아 직접 더해야 합니다). 설정과 상태는 PASEO_HOME(기본 ~/.paseo) 아래에 저장됩니다. 이 활용편은 데스크톱 앱을 기준으로 합니다 → 완전 가이드 1장 설치와 첫 실행 · 7장 어디서나 연결
에이전트 준비 — Paseo 는 에이전트를 내장하지 않습니다
Paseo 가 실행해 주는 에이전트 CLI 한 종류를 프로바이더(provider — Paseo 가 실행하는 에이전트 CLI 한 종류와 그것을 다루는 약속)라고 부릅니다. 아래 그림처럼 Paseo 는 실행만 맡고, 에이전트와 계정은 내가 준비한 것을 그대로 씁니다.
- Claude Code CLI 설치하고 로그인하기Paseo 를 돌릴 컴퓨터에 Claude Code CLI(명령 이름
claude)를 설치하고 로그인합니다. Paseo 는 Claude Code 에이전트를 시작할 때 이 설치본과 계정을 그대로 씁니다. - 확인하기터미널에서
claude를 실행해 평소처럼 켜지고 답하는지 봅니다.
Claude 로그인이 만료되었을 때
Claude Code CLI 에서 다시 로그인한 뒤, Paseo 에서 새 Claude Code 세션(에이전트 대화)을 시작합니다. 이미 돌고 있던 세션은 시작할 때의 로그인 정보를 계속 쓰므로, 다시 로그인해도 그 세션에는 반영되지 않습니다.
- Codex CLI 설치하기Paseo 를 돌릴 컴퓨터의 터미널에서
npm install -g @openai/codex를 실행합니다. 여기서 npm(프로그램 부품을 내려받아 설치하는 도구)은 설치에 쓰는 명령 이름입니다. - 로그인하기ChatGPT 요금제로 쓰려면
codex login을 실행해 ChatGPT 로 로그인합니다. - 확인하기
codex를 실행해 켜지는지 봅니다. Paseo 는 Codex 에이전트를 시작할 때 이 설치본과 로그인을 그대로 씁니다.
codex 명령은 생기지 않습니다. Codex CLI 를 따로 설치해야 Paseo 가 찾을 수 있습니다.API 키로 로그인하기 · Codex 가 Paseo 에 안 보일 때
API 키 로그인. macOS·Linux: printenv OPENAI_API_KEY | codex login --with-api-key · Windows PowerShell: $env:OPENAI_API_KEY | codex login --with-api-key
Codex 가 안 보일 때. 먼저 명령이 있는지 확인합니다 — macOS·Linux which -a codex, Windows where.exe codex. 없으면 ① Codex CLI 를 설치하고 ② 로그인한 뒤 ③ CLI 를 설치할 때 Paseo 데몬이 이미 켜져 있었다면 Paseo 를 다시 시작하고 ④ Paseo 에서 Settings → Providers → Codex(설정 → 프로바이더 → Codex)를 열어 Refresh(새로 고침)를 누릅니다. 이 경로는 Settings → your host → Providers 로도 적혀 있습니다 — 원문 표기가 둘이며 같은 곳입니다. Paseo 가 codex 명령을 찾아 실행할 수 있게 되면 프로바이더가 나타납니다. 더 많은 증상은 실습 10.
설치와 로그인만 하면 바로 되는 것 — Claude Code · Codex · OpenCode · Pi · Antigravity · Muse Code. 해당 CLI 를 설치하고 로그인해 두면 Paseo 에서 고를 수 있습니다.
앱 안 카탈로그에서 고르는 것 — Cursor · Gemini CLI · GitHub Copilot 을 비롯한 여러 에이전트는 앱 안의 프로바이더 카탈로그에서 고르면 그 CLI 가 한 번에 설치됩니다. 어떤 것이 있는지는 앱 안 카탈로그가 가장 정확합니다.
전체 목록과 에이전트별 주의점 → 완전 가이드 3장 에이전트 고르기
한 단계씩 읽는 방법
각 단계는 무엇을 누르거나 입력하는지와 무엇이 보이면 성공인지를 짝지어 적었습니다. 읽고, Paseo 에서 직접 해 보고, 성공 표시가 보이는지 확인한 뒤 다음으로 넘어가세요. 결과가 다르면 넘어가지 말고 그 실습의 ‘막히면’을 봅니다.
- Paseo 는 에이전트를 내장하지 않습니다 — 에이전트 CLI 하나를 직접 설치하고 로그인해 둡니다.
- GitHub CLI
gh도 설치·로그인해 두면 좋고(권장 — 없으면 PR 관련 단계만 못 합니다), 데스크톱 앱은 paseo.sh/download 에서 받습니다. - 기본 순서는 1 → 2 → 3 → 4 → 5, 선택 실습은 6~10 입니다.
- 단계마다 읽기 → 앱에서 해 보기 → 성공 표시 확인 순서로 진행합니다.
출처: paseo.sh/docs (home.md) · paseo.sh/docs/supported-providers (supported-providers.md) · paseo.sh/docs/claude-code (claude-code.md) · paseo.sh/docs/codex (codex.md) — Paseo 0.15.3 · 수집일 2026-11-09. 학습 순서와 도움 요청 문장은 이 활용편의 실습 안내입니다.
설치부터 첫 결과까지 — 프로젝트를 고르고 첫 일 시키기
Paseo 데스크톱 앱을 처음 열고, 프로젝트를 골라 에이전트에게 일 하나를 맡긴 뒤, 무엇이 바뀌었는지 내 눈으로 확인하기까지 따라 하는 순서입니다. 시작 전 준비를 마친 뒤 시작합니다.
- Paseo 데스크톱 앱을 설치하고 엽니다 — 데몬(내 컴퓨터에서 계속 켜져 에이전트와 워크스페이스를 맡아 돌리는 Paseo 의 본체 프로그램)은 앱이 알아서 켭니다.
- New workspace(새 워크스페이스)에서 프로젝트 · 격리 방식 · 에이전트를 고르고 첫 일을 맡깁니다.
- 진행을 읽고, 이어서 지시하고, Changes(변경 내용)에서 바뀐 것을 확인합니다.
걸리는 시간은 맡긴 일의 크기와 에이전트 작업 시간에 따라 다릅니다.
준비물
- 로그인해 둔 에이전트 CLI 1개. Paseo 는 에이전트(사람 대신 코드를 읽고 고치고 명령을 실행하는 AI 프로그램)를 내장하지 않고, 내가 설치해 둔 것을 실행해 줍니다. 아직이라면 에이전트 준비부터 합니다.
- 내 컴퓨터에 있는 git 저장소 폴더 1개. git(파일의 변경 이력을 기록하는 도구)으로 관리되는 프로젝트 폴더를 저장소라고 합니다. 이 실습의 예시는
origin/main(서버에 있는 원본 줄기) 브랜치(같은 저장소 안에서 따로 갈라져 나온 작업 줄기)가 있는 저장소를 씁니다. 연습해도 괜찮은 저장소로 고르세요. - GitHub CLI
gh(권장). PR(내 변경을 원본에 합쳐 달라는 요청)과 관련된 기능에 쓰입니다 — 없으면 PR 관련 단계만 못 합니다 → 시작 전 준비.
따라 하기
1단계 · 데스크톱 앱 설치하고 열기
- 설치 파일 받기paseo.sh/download 또는 GitHub 의 releases 페이지에서 받습니다. 데스크톱 앱은 macOS · Windows · Linux 용이 있습니다.
- 앱 열기설치한 앱을 엽니다. 앱이 자기 데몬을 함께 갖고 있다가 자동으로 켜 주므로 따로 설치할 것이 없습니다. Paseo 계정을 만들 필요도 없습니다.
- 시작 화면 기다리기처음 열면 잠깐 시작 화면이 보입니다.
성공 표시 — 시작 화면이 지나가고 Paseo 화면이 열립니다. 이제 데몬이 켜져 있어 에이전트를 돌릴 준비가 된 것입니다.
2단계 · New workspace 열고 프로젝트 고르기
Paseo 는 채팅이 아니라 워크스페이스(일 하나를 하는 자리 — 작업 폴더가 딸려 있음)를 중심으로 짜여 있습니다. 그래서 첫 일도 “새 대화”가 아니라 “새 워크스페이스”로 시작합니다.
- New workspace(새 워크스페이스) 열기앱에서 New workspace 를 찾아 엽니다.
- 프로젝트 고르기준비해 둔 저장소를 프로젝트로 고릅니다. 프로젝트는 사이드바(화면 옆쪽의 목록 칸)의 맨 위 단위이고, 그 안에 워크스페이스들이 놓입니다. 목록에 내 저장소가 없으면 그 폴더를 프로젝트로 추가합니다 — 터미널(글자로 명령을 입력하는 창)에서 그 저장소 폴더로 이동해
paseo project create를 실행하면 지금 있는 폴더가 프로젝트로 등록되고,paseo project ls로 등록된 프로젝트 목록을 볼 수 있습니다.paseo명령이 없다고 나오면 실습 10의 준비물을 봅니다.
성공 표시 — New workspace 에 내 프로젝트가 선택되어 있습니다.
3단계 · Isolation(격리) 정하기 — New worktree
모든 워크스페이스에는 격리 방식(Isolation — 이 일의 파일을 어디에 둘지)이 있습니다. 둘 중 하나를 고릅니다.
| 방식 | 무슨 뜻인가 | 언제 쓰나 |
|---|---|---|
| Local | 이미 있는 폴더(예: 평소 쓰는 원래 폴더)를 그대로 씁니다. | 세션들이 지금 디스크에 있는 파일을 함께 써야 할 때. git 저장소가 아닌 일반 폴더일 때. |
| New worktree | 워크트리(같은 저장소를 다른 폴더 · 다른 브랜치로 하나 더 꺼내 놓은 작업 폴더)를 새로 만들어 그 안에서 일합니다. | 이 일만을 위한 폴더와 브랜치가 필요할 때. |
- Isolation → New worktree 고르기Isolation(격리)을 New worktree(새 워크트리)로 둡니다. 이 실습은 이 방식으로 진행하고, 실습 2 · 3도 같은 방식을 이어서 씁니다.
- 시작 지점으로
origin/main고르기시작 지점(starting ref)은 새 워크트리가 갈라져 나오는 곳입니다.
성공 표시 — Isolation 이 New worktree, 시작 지점이 origin/main 으로 되어 있습니다.
origin/main 은 최신이고, 그냥 main 은 내가 마지막으로 받아 온 때의 상태에 머물러 있을 수 있습니다. main 을 고르면 옛 내용에서 새 워크트리가 시작될 수 있습니다.4단계 · 에이전트와 모델을 고르고 첫 일 맡기기
- 에이전트와 모델 고르기준비해 둔 에이전트(예: Claude Code, Codex)와 쓸 모델(에이전트가 생각할 때 쓰는 AI 의 종류)을 고릅니다.
- 할 일을 적어 보내기맡길 일을 글로 적어 보냅니다. 무엇을 할지와 함께, 끝난 뒤 확인할 방법(예: “관련 테스트를 실행해 줘”)을 같이 적어 두면 결과를 살펴보기 쉽습니다.
“프로젝트 목록에 필터 기능을 추가해 줘. 관련 테스트를 실행해 줘.”
“README 에 ‘설치 방법’ 절을 추가해 줘. 다른 파일은 건드리지 마. 끝나면 무엇을 바꿨는지 쉬운 말로 세 줄로 알려 줘.”
“파일은 바꾸지 말고, 이 프로젝트가 무엇을 하는 프로그램인지 처음 보는 사람에게 설명하듯 알려 줘.”
성공 표시 — 사이드바의 내 프로젝트 아래에 새 워크스페이스가 생기고, 에이전트가 일을 시작합니다.
5단계 · 진행을 읽고, 이어서 지시하고, 바뀐 것 확인하기
- 진행 읽기사이드바에서 방금 만든 워크스페이스를 고르면 에이전트가 무엇을 하고 있는지 읽을 수 있습니다.
- 이어서 지시하기더 부탁할 것이나 고칠 점이 있으면 같은 워크스페이스의 에이전트에게 이어서 적어 보냅니다. 예: “설치 방법에 Windows 안내도 넣어 줘.”
- Changes 로 바뀐 내용 보기워크스페이스를 고른 상태에서 Command Center(화면과 동작을 찾아 여는 창)에서 Changes(변경 내용)를 엽니다. 에이전트가 바꾼 것이 diff(바뀌기 전과 후의 차이)로 보입니다. Files(파일)를 열면 소스를 둘러보고 직접 고칠 수도 있습니다. Command Center 를 못 찾겠으면 에이전트에게 “무엇을 바꿨는지 파일별로 알려 줘”라고 물어보세요.
성공 표시 — Changes 에 에이전트가 바꾼 내용이 보입니다. 예시 ③처럼 설명만 부탁했다면 바뀐 파일이 없으니, 에이전트의 답을 읽고 프로젝트가 하는 일을 내 말로 한 문장 말할 수 있으면 성공입니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| 쓰려는 에이전트를 고를 수 없음 | Paseo 밖 터미널에서 그 에이전트 CLI 를 직접 실행해 봅니다. 거기서 안 되면 설치 · 로그인 문제입니다(에이전트 준비). Codex 라면 ChatGPT 데스크톱 앱과 Codex CLI 가 별개 설치라는 점을 확인하고, CLI 를 설치할 때 Paseo 가 이미 켜져 있었다면 Paseo 를 다시 시작한 뒤 Settings → Providers → Codex(설정 → 프로바이더 → Codex)에서 Refresh(새로 고침)를 누릅니다. 이 경로는 Settings → your host → Providers 로도 적혀 있습니다 — 원문 표기가 둘이며 같은 곳입니다. |
| Claude 로그인이 만료됨 | Claude Code CLI 에서 다시 로그인한 뒤 Paseo 에서 새 세션을 시작합니다. 이미 돌던 세션은 시작할 때의 로그인을 계속 씁니다. |
| New workspace 에서 내 프로젝트를 찾을 수 없음 | 프로젝트가 될 수 있는 것은 데몬이 도는 컴퓨터(지금은 내 컴퓨터)에 있는 git 저장소 · GitHub 프로젝트 · 폴더입니다. 저장소 폴더가 이 컴퓨터에 실제로 있는지, 위치가 어디인지부터 확인합니다. 프로젝트 등록과 목록 확인은 CLI 로도 할 수 있습니다(아래 안내). |
| 프로젝트가 git 저장소가 아님 | 워크트리는 git 저장소에서만 만들 수 있습니다. 일반 폴더라면 Isolation 을 Local 로 두고 진행합니다 — 이때 에이전트는 그 폴더의 파일을 바로 다루니, 연습해도 되는 폴더인지 먼저 확인하세요. |
저장소에 origin/main 이 없음 | 예시가 origin/main 이 있는 저장소를 기준으로 한 것입니다. 내 저장소에서 기준으로 삼는 브랜치를 시작 지점으로 고릅니다. 무엇인지 모르면 저장소를 준비해 준 사람에게 물어보세요. |
| 새 워크트리가 옛 내용에서 시작함 | 시작 지점을 main 이 아니라 origin/main 으로 골랐는지 확인합니다(3단계 설명). |
| Changes 에 아무것도 없음 | 에이전트가 아직 일하는 중이거나 파일을 바꾸지 않은 것일 수 있습니다. 진행을 읽어 보고, “무엇을 바꿨는지 알려 줘”라고 이어서 물어봅니다. |
에이전트가 안 보이거나 연결이 안 되는 등 더 많은 증상은 실습 10 막혔을 때에 모아 두었습니다. 프로젝트를 등록 · 목록 확인 · 이름 변경 · 삭제하는 CLI 명령은 완전 가이드 8장 설정과 CLI를 봅니다.
- 준비물: 로그인해 둔 에이전트 CLI 1개와 git 저장소 폴더 1개.
- 데스크톱 앱을 받아 열면 데몬이 함께 켜집니다 — 따로 설치할 것도, Paseo 계정도 필요 없습니다.
- New workspace → 프로젝트 → Isolation → New worktree(시작 지점
origin/main) → 에이전트 · 모델 → 할 일 보내기. - 사이드바에서 워크스페이스를 골라 진행을 읽고 이어서 지시하며, Command Center 의 Changes 로 바뀐 내용을 직접 확인합니다.
출처: paseo.sh/docs (home.md) · paseo.sh/docs/why (why.md) · paseo.sh/docs/workspaces (workspaces.md) · paseo.sh/docs/parallel-development (parallel-development.md) · paseo.sh/docs/worktrees (worktrees.md — origin/main 설명) · paseo.sh/docs/claude-code (claude-code.md) · paseo.sh/docs/codex (codex.md) · 프로젝트 명령은 paseo.sh/docs/cli (cli.md) — Paseo 0.15.3 · 수집일 2026-11-09. 예시 ②·③은 이 활용편의 연습용 예시입니다.
두 가지 일을 동시에 — 워크트리 두 개로 병렬 작업
에이전트 하나가 끝나기를 기다리지 않고, 서로 상관없는 일 두 개를 두 에이전트에게 동시에 맡깁니다. 일마다 워크스페이스를 따로 만들어 각자 자기 폴더와 브랜치에서 일하게 하므로, 두 에이전트가 고친 파일이 서로 섞이지 않습니다.
- 같은 프로젝트에서 워크스페이스(일 하나를 하는 자리 — 작업 폴더가 딸려 있음) 두 개를 New worktree(새 워크트리)로 만들어 일을 하나씩 맡깁니다.
- 두 에이전트가 동시에 일하는 동안 사이드바에서 오가며 진행을 읽고 이어서 지시합니다.
- “서로 다른 일 두 개”와 “같은 일을 두 가지로 만들어 비교하기” 중 상황에 맞는 쪽을 고릅니다.
걸리는 시간은 맡긴 일의 크기와 에이전트 작업 시간에 따라 다릅니다.
준비물을 확인하고 왜 워크트리를 따로 만드나의 그림을 본 뒤 따라 하기로 갑니다. 성공 표시가 보이지 않으면 막히면을 봅니다. 폴더 위치 같은 세부는 접힌 상자에 있으니 처음에는 건너뛰어도 됩니다.
준비물
- 실습 1을 마친 상태. 데스크톱 앱이 열리고, 프로젝트를 골라 에이전트(사람 대신 코드를 읽고 고치고 명령을 실행하는 AI 프로그램)에게 일을 맡겨 본 적이 있습니다.
- 내 컴퓨터에 있는 git 저장소. 예시는
origin/main(서버에 있는 원본 줄기) 브랜치(같은 저장소 안에서 따로 갈라져 나온 작업 줄기)가 있는 저장소를 씁니다. - 로그인해 둔 에이전트 CLI 1개 이상. 하나로 두 일을 다 맡겨도 되고, 두 개가 있으면 일마다 다른 것을 써도 됩니다.
- 서로 상관없는 일 두 개. 같은 파일을 고칠 일이 없는 두 가지를 미리 정해 둡니다.
왜 워크트리를 따로 만드나
워크트리(같은 저장소를 다른 폴더 · 다른 브랜치로 하나 더 꺼내 놓은 작업 폴더)는 워크스페이스의 파일을 다른 일과 떼어 놓는 방법입니다. 일마다 워크트리를 새로 만들면 Paseo 가 폴더와 브랜치를 따로 만들어 주므로, 동시에 일하는 에이전트들이 서로의 파일을 건드리지 않습니다.
따라 하기
1단계 · 첫 워크스페이스를 만들고 첫째 일 맡기기
- New workspace(새 워크스페이스) 열고 프로젝트 고르기New workspace 를 열어 내 프로젝트를 고릅니다.
- Isolation → New worktree, 시작 지점
origin/mainIsolation(격리 — 이 일의 파일을 어디에 둘지)을 New worktree(새 워크트리)로 두고, 시작 지점(starting ref — 새 워크트리가 갈라져 나오는 곳)으로origin/main을 고릅니다. - 에이전트와 모델을 고르고 과제 보내기“프로젝트 목록에 필터 기능을 추가해 줘. 관련 테스트를 실행해 줘.”
성공 표시 — 사이드바의 프로젝트 아래에 워크스페이스가 하나 생기고, 에이전트가 일을 시작합니다.
2단계 · 기다리지 말고 둘째 워크스페이스 만들기
첫 에이전트가 끝나기를 기다릴 필요가 없습니다. 바로 하나 더 만듭니다.
- 다시 New workspace → 같은 프로젝트방금과 똑같이 New workspace 를 열고 같은 프로젝트를 고릅니다.
- 이번에도 New worktree, 같은 시작 지점Isolation 을 New worktree 로 두고 시작 지점도 똑같이
origin/main으로 고릅니다. 같은 지점에서 갈라져 나온 두 번째 폴더와 브랜치가 생깁니다. - 둘째 과제 보내기“설정 페이지에 키보드 탐색을 추가해 줘. 관련 테스트를 실행해 줘.”
성공 표시 — 프로젝트 아래에 워크스페이스가 둘 보이고, 두 에이전트가 동시에 일합니다.
3단계 · 오가며 진행을 읽고 이어서 지시하기
- 사이드바에서 워크스페이스 고르기둘 중 하나를 고르면 그 에이전트의 진행을 읽을 수 있습니다.
- 필요하면 이어서 지시하기고른 워크스페이스의 에이전트에게 추가로 부탁할 것을 적어 보냅니다. 예: “필터는 이름으로만 걸러 주면 돼.”
- 다른 워크스페이스로 넘어가 같은 식으로 보기한쪽을 보고 있는 동안에도 다른 쪽 에이전트는 계속 일합니다.
성공 표시 — 두 워크스페이스를 오가며 각자의 진행을 읽고, 고른 쪽 에이전트에게 이어서 지시할 수 있습니다.
4단계 · 끝난 뒤 — 검토하고 합칠 것 고르기
두 에이전트가 일을 마치면 워크스페이스마다 바뀐 내용을 살펴보고 직접 돌려 본 다음, 합칠지 보관할지 정합니다. 끝났는지는 이렇게 알아봅니다 — 대화 끝에 마무리 답이 올라오고 더 진행이 없으면 끝난 것입니다. 헷갈리면 “다 끝났어? 남은 일이 있으면 알려 줘”라고 물어봅니다. 검토하고 합치는 부분은 실습 3에서 한 단계씩 따라 합니다.
성공 표시 — 두 에이전트가 각자 일을 마쳤고, 워크스페이스 두 개가 그대로 남아 있습니다(실습 3에서 이어서 씁니다).
변형 — 같은 일을 둘에게 맡겨 비교하기
워크트리를 따로 쓰는 방식은 두 가지 쓰임새가 있습니다. 위에서 한 것은 왼쪽이고, 같은 순서로 과제만 똑같이 주면 오른쪽이 됩니다.
방법은 1~2단계와 똑같고, 둘째 워크스페이스에 보내는 과제만 첫째와 같게 적습니다. 이때도 두 워크스페이스에 같은 프로바이더를 써도 되고, 서로 다른 프로바이더와 모델을 골라도 됩니다.
워크트리 폴더는 어디에 생기나 · 명령으로 만들기
위치. 워크트리는 기본으로 $PASEO_HOME/worktrees/(보통 ~/.paseo/worktrees/) 아래에, 원래 저장소 폴더 경로로 만든 짧은 식별 글자별로 묶여 생깁니다. 워크스페이스를 만들 때 워크트리마다 짧은 이름(slug)과 브랜치가 하나씩 붙습니다.
~/.paseo/worktrees/
└── 1vnnm9k3/ # 원래 저장소 폴더 경로로 만든 식별 글자
├── tidy-fox/ # 워크트리 이름(slug)
└── bold-owl/
기본 위치는 설정 파일 config.json 의 worktrees.root 로 바꿀 수 있습니다 → 완전 가이드 8장 설정과 CLI.
같은 워크트리를 여러 워크스페이스가 쓸 수도 있습니다. 그래서 Paseo 는 그 워크트리를 쓰는 마지막 워크스페이스가 보관된 뒤에야 폴더를 지웁니다.
명령으로 만들기. 앱 대신 CLI 로도 같은 일을 할 수 있습니다: paseo workspace create --isolation worktree --path ~/dev/my-app --base origin/main. 워크스페이스는 에이전트 없이 먼저 만들어 둘 수도 있습니다 — 작업 폴더가 준비된 채로 남아 있어, 터미널을 열거나 파일을 둘러보다가 나중에 에이전트를 시작할 수 있습니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| 두 에이전트가 같은 파일을 고쳐 내용이 섞임 | 둘째 워크스페이스를 만들 때 Isolation 이 New worktree 였는지 확인합니다. Local 은 이미 있는 폴더를 그대로 함께 쓰는 방식이라 일을 떼어 놓지 못합니다. |
| 프로젝트가 git 저장소가 아님 | 워크트리는 git 저장소에서만 만들 수 있습니다. 일반 폴더라면 이미 있는 폴더를 그대로 쓰는 Local 을 쓰게 되므로, 일을 떼어 놓고 병렬로 하려면 git 저장소로 관리되는 프로젝트를 준비합니다. |
| 새 워크트리가 옛 내용에서 시작함 | 시작 지점을 main 이 아니라 origin/main 으로 고릅니다. Paseo 가 서버 쪽 브랜치를 뒤에서 받아 오므로 origin/main 이 최신이고, 그냥 main 은 내가 마지막으로 받아 온 때의 상태입니다. |
| 새 워크트리에서 앱이 바로 돌지 않음(필요한 파일 · 설치가 빠져 있음) | 새 워크트리는 새 폴더라서 준비 작업이 필요할 수 있습니다. 워크트리를 만들 때마다 자동으로 준비되게 하는 방법은 실습 9(.worktreeinclude · paseo.json)에 있습니다. |
| 두 앱을 동시에 띄우면 한쪽이 안 뜸 | 포트가 겹쳤을 수 있습니다. 워크트리마다 파일은 따로여도 포트는 컴퓨터 한 대가 함께 씁니다. 실행 중인 복사본마다 다른 포트를 줍니다 → 실습 3의 터미널 단계. |
| 어느 워크스페이스가 어느 일인지 헷갈림 | 사이드바에서 하나씩 골라 에이전트에게 처음 보낸 과제를 확인합니다. 워크스페이스 이름을 바꾸는 CLI 명령은 완전 가이드 8장을 봅니다. |
더 많은 증상: 실습 10 막혔을 때
- 일마다 New workspace → Isolation → New worktree(시작 지점
origin/main)로 워크스페이스를 따로 만듭니다. - 워크트리가 다르면 폴더와 브랜치가 달라, 동시에 일하는 에이전트들의 파일 수정이 섞이지 않습니다.
- 사이드바에서 워크스페이스를 골라 진행을 읽고 이어서 지시합니다. 프로바이더는 같아도, 달라도 됩니다.
- 서로 다른 일이면 각각 검토해 각각 병합하고, 같은 일을 두 가지로 만들었다면 비교해서 하나를 고릅니다.
- 파일은 따로지만 네트워크 포트는 함께 쓰므로, 두 앱을 동시에 띄울 때는 포트를 다르게 줍니다.
출처: paseo.sh/docs/parallel-development (parallel-development.md) · paseo.sh/docs/workspaces (workspaces.md) · paseo.sh/docs/worktrees (worktrees.md) — Paseo 0.15.3 · 수집일 2026-11-09. README · 자주 묻는 질문 예시 과제는 이 활용편의 연습용 예시입니다.
결과 검토하고 직접 돌려 보기 — Changes · 터미널 · 브라우저
에이전트가 “끝났다”고 한 것과 결과가 실제로 맞는 것은 다릅니다. 이 실습에서는 바뀐 내용을 읽고, 고칠 점을 전하고, 터미널에서 직접 돌려 보고, 브라우저로 화면을 확인한 뒤, 무엇을 합칠지 정합니다. 이 모든 것을 워크스페이스 하나 안에서 합니다.
- Changes(변경 내용)로 에이전트가 바꾼 것을 읽고, Files(파일)로 소스를 둘러봅니다.
- 고칠 점을 에이전트에게 전하고, New agent(새 에이전트)로 두 번째 의견을 받습니다.
- New terminal(새 터미널)에서 테스트와 앱을 직접 돌리고, New browser(새 브라우저)로 화면을 확인합니다.
- 무엇을 합치고 무엇을 보관할지 정합니다.
걸리는 시간은 변경의 크기와 에이전트 작업 시간에 따라 다릅니다.
준비물 → 따라 하기 1~4단계까지가 기본입니다. 5단계(브라우저)는 웹 화면이 있는 프로젝트일 때만, 6단계(에이전트에게 브라우저 확인 맡기기)는 선택입니다. 마지막 7단계에서 합칠 것을 고릅니다. 막히면 막히면으로 갑니다.
준비물
- 에이전트가 일을 마친 워크스페이스. 대화 끝에 마무리 답이 올라오고 더 진행이 없으면 끝난 것입니다 — 헷갈리면 “다 끝났어? 남은 일이 있으면 알려 줘”라고 물어봅니다. 실습 2의 워크스페이스(일 하나를 하는 자리 — 작업 폴더가 딸려 있음) 두 개가 가장 좋고, 실습 1의 하나만 있어도 1~4단계는 따라 할 수 있습니다.
- Paseo 데스크톱 앱. 브라우저 탭은 데스크톱 앱 안에서만 돕니다.
- 내 프로젝트를 돌리는 방법. 필요한 것을 설치하는 명령, 테스트를 실행하는 명령, 개발 서버(만드는 중인 앱을 내 컴퓨터에서 띄워 보는 프로그램)를 띄우는 명령을 알아 둡니다. 모르면 그 워크스페이스의 에이전트(사람 대신 코드를 읽고 고치고 명령을 실행하는 AI 프로그램)에게 “이 프로젝트의 설치 명령, 테스트 실행 명령, 개발 서버 실행 명령(포트를 바꿔 띄우는 방법 포함)을 알려 줘”라고 물어보세요.
따라 하기
1단계 · Changes 로 바뀐 내용 읽기
- 검토할 워크스페이스 고르기사이드바에서 살펴볼 워크스페이스를 고릅니다.
- Command Center 에서 Changes 열기Command Center(화면과 동작을 찾아 여는 창)에서 Changes(변경 내용)를 엽니다. 그 워크스페이스의 diff(바뀌기 전과 후의 차이)가 보입니다.
성공 표시 — 에이전트가 바꾼 내용이 “바뀌기 전과 후의 차이”로 보입니다.
2단계 · Files 로 소스 보기 — (선택) 대화 옆에 나란히 두기
- Files 열기Files(파일)를 열면 소스를 둘러보고 직접 고칠 수 있습니다.
- (선택) 나란히 놓기분할 화면(split panes)으로 에이전트 대화를 지금 검토하는 코드 옆에 둘 수 있습니다. 읽다가 궁금한 점을 바로 물어볼 수 있습니다. 나누는 방법을 못 찾겠으면 건너뛰어도 됩니다 — 다음 단계는 이것 없이도 따라 할 수 있습니다.
성공 표시 — Files 에서 바뀐 파일 하나를 열어 볼 수 있습니다.
3단계 · 고칠 점을 전하고, 두 번째 의견 받기
- 고칠 점 보내기고칠 것이 보이면 그 워크스페이스의 에이전트에게 적어 보냅니다. 예: “필터를 지웠을 때 전체 목록이 다시 나오게 고쳐 줘.”
- New agent 로 검토 전담 에이전트 부르기다른 눈으로 한 번 더 보고 싶다면 같은 워크스페이스에서 New agent(새 에이전트)를 써서 에이전트를 하나 더 시작하고 이렇게 부탁합니다: “파일은 고치지 말고, 이 워크스페이스의 변경을 검토해서 문제점을 알려 줘.”
- 의견을 읽고 결정하기검토 의견 가운데 받아들일 것을 골라 처음 에이전트에게 수정을 부탁합니다.
성공 표시 — 두 번째 에이전트가 검토 의견을 답하고, 워크스페이스에 에이전트 탭이 둘 있습니다.
검토용 에이전트 설정을 저장해 두고 매번 불러 쓰는 방법은 실습 5에 있습니다.
4단계 · New terminal 에서 테스트와 앱 직접 돌리기
- Command Center 에서 New terminal 열기고른 워크스페이스에서 New terminal(새 터미널)을 엽니다. 터미널(글자로 명령을 입력하는 창)이 그 워크스페이스의 탭으로 열립니다.
- 필요한 것 설치하기프로젝트가 돌아가는 데 필요한 부품(의존성)을 그 터미널에서 설치합니다.
- 테스트나 앱 실행하기내 프로젝트의 테스트 명령 또는 개발 서버(만드는 중인 앱을 내 컴퓨터에서 띄워 보는 프로그램) 실행 명령을 입력합니다. 명령을 모르면 에이전트에게 “의존성을 설치하고 테스트를 돌려 결과를 알려 줘”라고 맡겨도 됩니다.
성공 표시 — 터미널에 테스트 결과가 보이거나, 개발 서버가 켜져서 주소로 열어 볼 수 있습니다.
5단계 · New browser 로 화면 확인하기 (웹 앱일 때)
- New browser 열기같은 워크스페이스에서 New browser(새 브라우저)를 씁니다. 브라우저 탭은 데스크톱 앱 안에서 열립니다.
- 그 워크스페이스의 개발 서버 주소 넣기4단계에서 띄운 개발 서버의 주소(URL)를 입력합니다. 예:
http://localhost:3001 - 바뀐 기능을 직접 써 보기에이전트가 고친 흐름을 처음부터 끝까지 눌러 봅니다. 예: 목록을 이름으로 걸러 보고, 필터를 지워 전체 목록이 돌아오는지 봅니다.
- 다른 워크스페이스로 바꿔 같은 식으로 확인하기워크스페이스를 바꿔 다른 쪽 결과도 그 워크스페이스의 주소로 확인합니다.
성공 표시 — 브라우저 탭에 내 앱 화면이 뜨고, 바뀐 기능이 기대한 대로 움직입니다.
6단계 · (선택) 에이전트에게 브라우저로 확인시키기
화면 확인을 에이전트에게 맡길 수도 있습니다. 에이전트가 내가 보는 바로 그 브라우저 탭을 열고, 페이지를 읽고, 눌러 보고, 스크린샷을 찍습니다. 이 기능은 기본으로 꺼져 있어 먼저 켜야 합니다.
- Browser tools 켜기Settings → your host → Agents(설정 → 내 호스트 → 에이전트)를 열어 Browser tools(브라우저 도구)를 켭니다. 호스트(데몬이 돌아가는 컴퓨터 — 지금은 내 컴퓨터)마다 따로 켜는 설정입니다.
- Enable Paseo tools 도 켜져 있는지 보기같은 페이지의 Enable Paseo tools(Paseo 도구 켜기)도 켜져 있어야 에이전트가 브라우저 도구를 받습니다.
- 에이전트를 다시 불러오기이미 떠 있던 에이전트는 새 도구를 받으려면 다시 불러와야(reload) 할 수 있습니다. 가장 확실한 방법은 같은 워크스페이스에서 New agent 로 새 에이전트를 시작하는 것입니다.
- 주소와 확인할 단계를 구체적으로 주기“http://localhost:3001 을 열고, 프로젝트 목록을 이름으로 걸러 본 다음, 필터를 지우면 전체 목록이 다시 나오는지 확인해 줘. 실패한 것이 있으면 알려 주고, 결과 화면을 스크린샷으로 남겨 줘.”
성공 표시 — 에이전트가 페이지를 직접 열어 확인한 결과(실패 여부와 스크린샷)를 답으로 알려 줍니다.
설정 파일로 켜기
앱 대신 설정 파일 ~/.paseo/config.json 에 아래처럼 적어도 됩니다. 이 경우에도 Paseo tools 가 켜져 있어야 합니다.
{
"daemon": {
"browserTools": {
"enabled": true
}
}
}
설정 파일 전반은 완전 가이드 8장 설정과 CLI.
7단계 · 무엇을 합칠지 고르기
- 워크스페이스마다 diff 와 테스트 결과 다시 보기남은 수정이 있으면 먼저 에이전트에게 부탁해 마무리합니다.
- 커밋하고 PR 열기남길 변경은 커밋(변경을 이력에 기록해 남기는 것)하고 그 브랜치(따로 갈라져 나온 작업 줄기)의 PR(내 변경을 원본에 합쳐 달라는 요청)을 엽니다. 워크스페이스의 터미널에서 평소 쓰던 Git 방식대로 해도 되고, 그 워크스페이스의 에이전트에게 맡겨도 됩니다. 예: “지금까지의 변경을 커밋하고 PR 을 열어 줘.” PR 이 열렸는지는 에이전트에게 “PR 주소를 알려 줘”라고 물어 확인합니다.
- 고르기서로 다른 일 두 개였다면 브랜치마다 검토해서 각각 합칩니다. 같은 일을 두 가지로 만들었다면 남길 쪽 하나를 고릅니다. 합치기는 GitHub 의 PR 화면에서 하며, 팀 저장소라면 담당자에게 맡깁니다.
- 더 쓰지 않는 워크스페이스 보관하기필요 없어진 워크스페이스는 보관(archive)합니다. 연습용이라면 PR 없이 보관만 해도 됩니다. 실습 4 · 5 를 이어서 할 거라면 하나는 남겨 두세요.
성공 표시 — 남길 변경은 PR 로 올라가 있고, 더 쓰지 않는 워크스페이스는 보관되어 있습니다(연습용이라면 PR 없이 보관만 되어 있어도 됩니다).
막히면
| 증상 | 해 볼 것 |
|---|---|
| Changes 에 볼 것이 없음 | Changes 는 바뀐 내용을 보여 주는 곳이라, 에이전트가 파일을 바꾸지 않았다면 볼 것이 없습니다. 올바른 워크스페이스를 골랐는지 확인하고, 에이전트에게 “무엇을 바꿨는지 알려 줘”라고 물어봅니다. |
| 두 번째 앱이 뜨지 않음 | 포트가 겹쳤을 수 있습니다. 워크트리마다 파일은 따로여도 포트는 컴퓨터 한 대가 함께 씁니다. 실행 중인 복사본마다 다른 포트를 정해 주고, 브라우저에도 그 워크스페이스의 주소를 넣습니다. |
| 테스트나 앱을 어떻게 돌리는지 모름 | 그 워크스페이스의 에이전트에게 실행 명령을 물어보거나, 에이전트에게 직접 테스트를 실행하고 결과를 알려 달라고 부탁합니다. |
| 에이전트가 브라우저를 쓰지 못함 | ① Settings → your host → Agents 에서 Browser tools 와 Enable Paseo tools 가 둘 다 켜져 있는지 봅니다. ② 설정을 켜기 전부터 떠 있던 에이전트는 다시 불러옵니다. ③ 데스크톱 앱이 열려 연결되어 있는지 봅니다 — 브라우저 탭은 데스크톱 앱이 갖고 있어서, 연결된 데스크톱 앱이 없으면 에이전트의 요청이 오류로 끝납니다. |
| 에이전트가 다른 워크스페이스의 브라우저 탭을 못 봄 | 정상입니다. 에이전트는 자기 워크스페이스의 탭만 보고 조작합니다. 확인하려는 워크스페이스의 에이전트에게 부탁하세요. |
| 에이전트가 여는 주소가 열리지 않음 | 브라우저 도구는 http · https 로 시작하는 주소만 열 수 있습니다. 개발 서버가 켜져 있는지, 주소의 포트가 그 워크스페이스의 것인지도 확인합니다. |
| 폰이나 웹에서는 브라우저 탭이 없음 | 브라우저 탭은 지금은 데스크톱 앱에서만 됩니다. |
더 많은 증상: 실습 10 막혔을 때
- 워크스페이스를 고르고 Command Center 에서 Changes 를 열어 바뀐 내용을 읽습니다. Files 로 소스를 보고, 원하면 분할 화면으로 대화와 코드를 나란히 둡니다.
- 고칠 점은 그 워크스페이스의 에이전트에게 보내고, New agent 로 “고치지 말고 검토만” 하는 두 번째 의견을 받습니다. 같은 워크스페이스의 에이전트는 작업 폴더를 함께 씁니다.
- Command Center 의 New terminal 에서 테스트와 앱을 돌립니다. 동시에 띄우는 앱은 포트를 서로 다르게 줍니다.
- 웹 앱은 New browser 에 그 워크스페이스의 주소를 넣어 직접 써 봅니다. 브라우저 탭은 데스크톱 앱 안에서 돕니다.
- 에이전트에게 브라우저 확인을 맡기려면 Browser tools 와 Enable Paseo tools 를 둘 다 켭니다 — 믿는 에이전트에게만.
- 서로 다른 일은 각각 병합하고, 같은 일의 두 구현은 하나를 고릅니다. 남길 것을 PR 로 올린 뒤 워크스페이스를 보관합니다 — 실습 4 · 5 를 이어서 할 거라면 하나는 남겨 둡니다.
출처: paseo.sh/docs/parallel-development (parallel-development.md) · paseo.sh/docs/browser (browser.md) · paseo.sh/docs/workspaces (workspaces.md — 세션이 탭으로 열린다는 설명) — Paseo 0.15.3 · 수집일 2026-11-09. 검토 요령과 동료 · 에이전트에게 묻는 문장은 이 활용편의 실습 안내입니다.
밖에서 폰으로 이어서 지시하기 — 릴레이 페어링
컴퓨터에서 시켜 둔 일을 자리를 떠난 뒤에도 폰으로 확인하고, 이어서 지시하는 실습입니다. 할 일은 하나입니다 — 내 컴퓨터와 폰을 QR 코드로 한 번 짝지어 두는 것.
- 데스크톱 앱에서 릴레이(relay — 폰과 내 컴퓨터 사이를 이어 주는 중계 서버)를 켜고, 폰과 페어링(QR 코드나 링크로 폰과 컴퓨터를 짝지어 두는 것)합니다.
- 폰의 Paseo 앱에서 컴퓨터와 같은 작업을 열어, 에이전트(사람 대신 코드를 읽고 고치는 AI 프로그램)에게 이어서 지시합니다.
- 중계 서버를 거치는데도 왜 내용이 새지 않는지, QR 코드를 왜 비밀번호처럼 다뤄야 하는지 설명할 수 있습니다.
준비물 확인 → 따라 하기 6단계를 차례로 진행합니다. QR 코드가 안 나오거나 연결이 안 되면 막히면으로 가세요. 암호화 방식과 Tailscale 같은 다른 연결 방법은 접힌 상자에 있으니 처음에는 건너뛰어도 됩니다.
준비물
- Paseo 데스크톱 앱과, 에이전트가 일하고 있는 워크스페이스 하나. 워크스페이스(일 하나를 하는 자리 — 작업 폴더가 딸려 있음)는 실습 1에서 만든 것을 그대로 씁니다. 모두 보관했다면 실습 1의 2~4단계로 새로 하나 만듭니다. 데스크톱 앱은 데몬(daemon — 내 컴퓨터에서 계속 켜져 에이전트와 워크스페이스를 맡아 돌리는 Paseo 의 본체 프로그램)을 함께 담고 있고, 앱을 열면 알아서 시작합니다.
- Paseo 앱을 설치한 폰. iOS 용과 Android 용 앱이 있습니다 — App Store · Google Play 에서 Paseo 앱을 받습니다. 폰 앱에서는 에이전트·파일·터미널·diff(바뀌기 전과 후의 차이)를 볼 수 있습니다.
- QR 코드를 찍을 수 있게 컴퓨터 화면 앞에 있을 것. 짝지을 때만 컴퓨터 옆에 있으면 되고, 그 뒤의 지시는 밖에서 합니다.
릴레이는 내 앱과 데몬을 잇는 길입니다. GitHub·Slack·Discord 에서 일이 생기면 에이전트를 시작해 주는 Hub 는 별개의 서비스이며, 이 실습에서는 쓰지 않습니다.
따라 하기
1단계 · 컴퓨터에서 일을 하나 시켜 두기
- 데스크톱 앱에서 워크스페이스 열기실습 1에서 만든 워크스페이스를 고릅니다.
- 자리를 비우는 동안 할 일을 부탁하기폰으로 결과를 확인하기 좋게, 끝나면 요약해 달라고 적습니다.
2단계 · 데스크톱에서 Pair a device 열기
- Settings(설정) 열기데스크톱 앱의 설정 화면으로 갑니다.
- your host(내 호스트) 고르기호스트(host — 데몬이 돌아가는 컴퓨터)는 지금 쓰는 이 컴퓨터입니다.
- Pair a device(기기 짝짓기) 누르기경로를 한 줄로 쓰면 Settings → your host → Pair a device 입니다.
3단계 · Enable relay 고르기
릴레이는 내가 켜기 전에는 꺼져 있습니다. 새로 설치한 Paseo 는 릴레이를 쓰지 않으며, 기기를 짝지으려 할 때 켤지 먼저 묻습니다.
- Enable relay(릴레이 켜기) 고르기켜면 데몬이 릴레이에 접속하고, 폰이 만나러 올 수 있게 됩니다.
- QR 코드와 페어링 링크 확인화면에 QR 코드가 나타납니다. 같은 내용을 담은 페어링 링크(pairing link — QR 코드 대신 복사해 붙여 넣는 주소)도 복사할 수 있습니다.
QR 코드(또는 페어링 링크)를 가진 사람은 내 데몬에 연결할 수 있습니다. 화면을 찍어 메신저에 올리거나 공개된 곳에 붙여 넣지 마세요.
4단계 · 폰으로 QR 코드 찍기
- 폰에서 Paseo 앱 열기앱으로 컴퓨터 화면의 QR 코드를 찍습니다.
- 찍기 어렵다면 링크로데스크톱에서 페어링 링크를 복사해 폰으로 옮긴 뒤, 폰 앱에서 Paste pairing link(페어링 링크 붙여 넣기)를 골라 붙여 넣습니다.
5단계 · 폰에서 이어서 지시하기
- 1단계의 워크스페이스 열기폰 앱에서 아까 일을 시켜 둔 워크스페이스와 에이전트 대화를 엽니다.
- 결과 읽기에이전트가 남긴 요약을 읽습니다. 바뀐 파일이 있으면 diff 로 확인할 수 있습니다.
- 이어서 한마디 보내기같은 대화에 다음 부탁을 적습니다.
내장 브라우저는 데스크톱 앱 안에서 돌아갑니다. 웹 화면을 눈으로 확인하는 일은 컴퓨터로 돌아와서 합니다(실습 3).
6단계 · 돌아와서 데스크톱에서 확인하기
- 데스크톱 앱에서 같은 워크스페이스 열기폰에서 주고받은 말이 같은 대화에 그대로 있습니다. 폰과 데스크톱이 같은 데몬의 같은 작업을 보고 있기 때문입니다.
- 바뀐 내용 검토하기에이전트가 고친 것은 실습 3의 방법(Changes · 터미널 · 브라우저)으로 확인합니다.
중계 서버를 거치는데 왜 안전한가요
릴레이가 내용을 들여다볼 수 없게 만들어져 있어, 릴레이를 믿을 필요가 없습니다. 폰과 데몬 사이의 모든 내용은 종단간 암호화(end-to-end encryption — 보내는 쪽과 받는 쪽만 풀 수 있게 잠그는 방식)되어, 릴레이는 잠긴 꾸러미를 건네주기만 합니다. 릴레이가 뚫리더라도 내 대화와 코드는 보호됩니다.
이 잠금의 출발점이 바로 QR 코드입니다. QR 코드에는 내 데몬을 알아보는 열쇠 정보가 들어 있어서, 그것을 찍은 폰만 데몬과 암호화된 연결을 맺습니다. 3단계에서 QR 코드를 비밀번호처럼 다루라고 한 이유입니다.
암호화가 이루어지는 순서 (기술 상세)
- 데몬이 오래 쓰는 ECDH 키 쌍(공개 열쇠와 비밀 열쇠 한 벌)을 만들어
$PASEO_HOME/daemon-keypair.json에 저장합니다. - QR 코드를 찍거나 페어링 링크를 누르면 폰이 데몬의 공개 열쇠를 받습니다.
- 폰이 자기 공개 열쇠를 담은 핸드셰이크(서로를 확인하는 첫 인사) 메시지를 보냅니다. 이 핸드셰이크가 끝나기 전에는 데몬이 어떤 명령도 받아들이지 않습니다.
- 양쪽이 자기 Curve25519 키와 상대의 공개 열쇠를 합쳐 NaCl
box채널을 만들고, 내용을 XSalsa20-Poly1305 로 보호해 주고받습니다.
그래서 릴레이가 나쁜 마음을 먹어도 다음을 할 수 없습니다. 명령 보내기 — 폰의 비밀 열쇠가 없어 핸드셰이크를 끝내지 못합니다. 내용 읽기 — 짝지은 양쪽만 꾸러미를 열 수 있습니다. 위조 — 손댄 꾸러미는 거부됩니다. 재전송 — 연결할 때마다 새 암호 열쇠를 만듭니다. 공식 릴레이 서버는 공개된 소스(getpaseo/paseo-relay)입니다.
비밀번호를 더하고 싶다면. 데몬에 비밀번호를 설정하면 릴레이로 들어오는 폰도 연결할 때 비밀번호를 보내야 합니다. 비밀번호는 암호화된 통로 안으로 전달되어 릴레이는 볼 수 없습니다. 비밀번호가 없으면 페어링 정보를 가진 사람은 누구나 데몬에 연결할 수 있습니다. 설정 방법은 완전 가이드 7장과 8장에 있습니다.
데스크톱 앱 없이 명령으로 짝짓기 (CLI)
화면 없는 서버처럼 데스크톱 앱을 쓰지 않는 컴퓨터에서는 명령 창에 다음을 입력합니다.
paseo daemon pair
릴레이를 켤지 물으면 확인합니다. QR 코드와 페어링 링크가 출력되니, 폰의 Paseo 앱으로 QR 코드를 찍거나 폰 앱에서 Paste pairing link(페어링 링크 붙여 넣기)를 고릅니다. paseo 를 처음 실행할 때도 데몬을 시작한 뒤 릴레이를 켜고 QR 코드를 보여 줄지 묻습니다. 묻는 과정 없이 바로 켜려면 짝짓기·시작 명령에 --relay 를 붙입니다.
릴레이 대신 Tailscale 로 직접 연결하기
릴레이를 쓰지 않으려면 Tailscale(내 기기들만 들어오는 사설 통로를 만들어 주는 VPN 서비스)로 폰과 데몬을 직접 이을 수 있습니다. 준비할 것이 더 많으므로 처음에는 릴레이를 권합니다.
- 데몬이 도는 컴퓨터와 폰에 Tailscale 을 설치하고, 두 기기에서 같은 tailnet 에 로그인합니다.
- 데몬 컴퓨터에서
tailscale ip -4로 Tailscale IP 를 확인합니다(예:100.101.102.103). ~/.paseo/config.json의daemon.listen을"100.101.102.103:6767"처럼 그 IP 로 바꿉니다. 파일의 다른 설정은 그대로 둡니다.- 데몬을 다시 시작합니다 —
paseo daemon restart, 데스크톱 앱이 데몬을 관리한다면 Settings → your host → Overview → Restart daemon. - 폰에서 Tailscale 을 연결하고, Paseo 앱의 Settings → Add host → Direct connection(직접 연결)에서 Host 에 그 IP, Port 에
6767을 넣습니다. Use SSL 은 끈 채로 Connect 를 누릅니다.
이미 릴레이로 짝지어 둔 호스트라면 직접 연결이 같은 호스트에 추가됩니다. 직접 연결에서는 데몬 비밀번호를 설정해 접근을 제한하는 것이 권장됩니다. 자세한 내용은 완전 가이드 7장.
Connection timed out(시간 초과)이면 두 기기 모두 Tailscale 이 연결되어 있는지, 데몬 컴퓨터의 Tailscale IP 를 넣었는지 확인합니다. Connection refused(연결 거부)이면 paseo daemon status 로 데몬이 설정한 IP 와 포트에서 돌고 있는지 봅니다. 설정을 바꿨는데 반영되지 않으면 paseo reload 를 실행하고, 다시 시작이 필요하다고 나오면 데몬을 다시 시작합니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| QR 코드가 나오지 않음 | 릴레이는 켜기 전까지 꺼져 있고, 켜지 않으면 QR 코드가 만들어지지 않습니다. Settings → your host → Pair a device 를 다시 열어 Enable relay 를 고릅니다. |
| 폰으로 QR 코드를 찍을 수 없음 | 데스크톱에서 페어링 링크를 복사해 폰으로 옮긴 뒤, 폰 앱에서 Paste pairing link 를 골라 붙여 넣습니다. |
| 메뉴 이름이 Pair Device 로 보임 | 같은 메뉴입니다. 공식 문서 안에서도 Pair a device 와 Pair Device 두 가지로 적혀 있습니다. |
| 폰에서 웹 화면(브라우저 탭)을 볼 수 없음 | 내장 브라우저는 데스크톱 앱에서 돌아갑니다. 폰에서는 에이전트·파일·터미널·diff 를 봅니다. |
| QR 코드나 링크를 남에게 보인 것 같음 | 페어링 정보는 비밀번호와 같습니다. 데몬에 비밀번호를 설정하면 페어링 정보만으로는 연결할 수 없습니다 — 완전 가이드 7장. |
| 중계 서버를 쓰고 싶지 않음 | 위 접힌 상자의 Tailscale 직접 연결을 씁니다. 릴레이를 켜지 않아도 데몬은 직접 연결(TCP·Tailscale·다른 VPN)로 쓸 수 있습니다. |
연결 방법 전체와 보안 설명: 완전 가이드 7장 — 어디서나 연결
- 에이전트는 내 컴퓨터의 데몬이 돌립니다. 폰 앱과 데스크톱 앱은 같은 데몬에 연결하는 창이라서, 폰에서도 같은 작업을 이어 갑니다.
- 짝짓기는 Settings → your host → Pair a device → Enable relay → 폰의 Paseo 앱으로 QR 코드 찍기(또는 페어링 링크 붙여 넣기).
- 릴레이는 켜기 전에는 꺼져 있습니다. 켜면 공유기 설정이나 VPN 없이 연결됩니다.
- 내용은 종단간 암호화되어 릴레이는 읽지도, 바꾸지도, 명령을 보내지도 못합니다. 대신 QR 코드와 페어링 링크는 비밀번호처럼 다룹니다.
- 폰에서는 에이전트·파일·터미널·diff 를 다루고, 내장 브라우저는 데스크톱에서 씁니다.
출처: paseo.sh/docs/connectivity (connectivity.md) · paseo.sh/docs/security (security.md) · paseo.sh/docs (home.md) · paseo.sh/docs/why (why.md) · 앱 받는 곳은 paseo.sh (site-home.md) — Paseo 0.15.3 · 수집일 2026-11-09
자주 쓰는 설정을 프로필로 저장하고 두 번째 에이전트에게 검토 맡기기
에이전트를 새로 만들 때마다 고르던 설정을 이름 하나로 묶어 저장합니다. 그리고 그 프로필로 두 번째 에이전트를 불러, 첫 에이전트가 고친 내용을 파일은 건드리지 않고 검토하게 합니다.
- 프로필(agent profile — 함께 쓰는 에이전트 설정을 이름 붙여 저장한 묶음)을 만들고, 에이전트를 만들 때 한 번에 불러옵니다.
- 같은 워크스페이스(일 하나를 하는 자리 — 작업 폴더가 딸려 있음)에 두 번째 에이전트를 추가해 검토만 맡깁니다.
- 검토에서 나온 지적을 원래 에이전트에게 돌려주고, 고쳐진 것을 다시 확인합니다.
준비물 확인 → 따라 하기 6단계. 1~3단계가 프로필 만들기, 4~6단계가 검토 맡기기입니다. 프로필이 안 보이거나 검토 에이전트가 파일을 고쳐 버렸다면 막히면을 보세요.
준비물
- 에이전트가 고친 내용이 들어 있는 워크스페이스 하나. 실습 1~3에서 쓰던 것이면 됩니다. 모두 보관했다면 실습 1의 2~4단계로 새로 하나 만듭니다. 아직 바뀐 것이 없다면 먼저 작은 수정을 하나 시켜 두세요.
- 로그인해 둔 에이전트 CLI 하나 이상. Paseo 는 에이전트를 직접 주지 않고, 내가 설치해 둔 것을 실행해 줍니다(시작 전 준비). 둘 이상 있다면 검토를 다른 모델에게 맡길 수 있습니다. 하나뿐이어도 실습은 그대로 할 수 있습니다.
에이전트를 만들 때는 보통 프로바이더(provider — Paseo 가 실행하는 에이전트 CLI 한 종류. Claude Code, Codex 등), 모델(그 에이전트가 쓰는 AI 두뇌의 종류), 모드(mode — 에이전트의 동작 방식), 생각 수준(thinking level — 답하기 전에 얼마나 깊이 따져 볼지)을 하나씩 고릅니다. 프로필은 이 선택들과 그 밖에 쓸 수 있는 기능 설정을 통째로 저장해 둔 것입니다. 저장해 두면 UI work, Planning, Review 같은 이름 하나만 골라도 설정이 한꺼번에 들어갑니다.
프로필마다 맡을 일을 하나씩 정해 주면 쓰기 좋습니다. 공식 문서의 예시는 다음 세 가지입니다. 프로필마다 프로바이더와 모델을 다르게 해도 되고, 같은 모델에 설정만 다르게 해도 됩니다.
| 프로필 이름 | When to use(언제 쓰나)에 적을 메모 예시 |
|---|---|
| UI work (화면 작업) | 화면 구성 요소, 배치, 꾸밈, 보기 좋게 다듬는 일에 사용. |
| Planning (계획) | 구조 설계, 문제의 근본 원인 조사, 구현 방법 비교에 사용. |
| Review (검토) | 변경 내용(diff)의 독립 검토에 사용 — 정확한지, 빠진 테스트가 없는지, 쓸데없이 복잡하지 않은지. |
오늘은 이 가운데 Review 하나를 만듭니다.
따라 하기
1단계 · Agent profiles 열기
- Settings → your host → Agents 로 가기설정 → 내 호스트(host — 데몬이 돌아가는 컴퓨터. 보통 지금 쓰는 이 컴퓨터) → 에이전트.
- Agent profiles(에이전트 프로필) 찾기경로를 한 줄로 쓰면 Settings → your host → Agents → Agent profiles 입니다.
호스트를 고르고 들어가는 이유입니다. 다른 컴퓨터(다른 호스트)에서 쓰려면 그 호스트에서 따로 만듭니다.
2단계 · New profile 로 “Review” 만들기
- New profile 고르고 이름 적기이름은
Review. 무슨 일에 쓰는 프로필인지 이름만 보고 알 수 있게 짓습니다. - 프로바이더와 모델 고르기검토를 맡길 에이전트와 모델을 고릅니다. 다른 모델의 판단을 받아 보고 싶다면, 평소 코드를 고치게 하는 에이전트와 다른 프로바이더를 고릅니다.
- 모드·생각 수준·기능 고르기보이는 선택지 가운데 검토에 쓸 것을 고릅니다. 어떤 칸이 보이는지는 고른 프로바이더와 모델에 따라 다릅니다. 잘 모르겠으면 처음 값 그대로 둡니다.
3단계 · When to use 적고 Save
- When to use(언제 쓰나) 칸 채우기이 프로필이 맡을 일을 한두 문장으로 적습니다. 이 칸이 프로필의 메모입니다.
- Save(저장) 고르기저장하면 다음에 에이전트를 만들 때부터 이 프로필을 고를 수 있습니다.
4단계 · 같은 워크스페이스에서 New agent → Review 프로필 고르기
- 검토할 워크스페이스 고르기사이드바에서 에이전트가 고친 내용이 들어 있는 워크스페이스를 고릅니다.
- New agent(새 에이전트) 쓰기새 워크스페이스를 만드는 것이 아닙니다. 같은 워크스페이스 안에 에이전트를 하나 더 둡니다.
- 모델 고르는 곳에서 Profiles 아래의 Review 고르기모델 선택 목록(model picker)을 열면 Profiles 아래에 저장한 프로필이 있습니다. 고르면 설정이 한꺼번에 들어갑니다. 보내기 전에 일부를 따로 고쳐도 됩니다.
5단계 · 파일을 고치지 않는 검토 부탁하기
새 에이전트에게 다음처럼 적어 보냅니다. “파일은 고치지 마”가 꼭 들어가야 합니다.
6단계 · 지적을 원래 에이전트에게 돌려주고 다시 확인하기
- 검토 결과 읽고 고칠 것 고르기모든 지적을 따를 필요는 없습니다. 맞다고 생각하는 것만 고릅니다.
- 원래 에이전트의 대화로 돌아가 전달하기같은 워크스페이스의 첫 에이전트에게 고칠 것을 적어 보냅니다.
- Changes 로 다시 보기Command Center(화면과 동작을 찾아 여는 창)에서 Changes(변경 내용)를 열어 diff(바뀌기 전과 후의 차이)를 확인합니다. 자세한 방법은 실습 3.
When to use 에 적은 메모는 나만 보는 것이 아닙니다. 에이전트가 다른 에이전트에게 일을 나눠 맡길 때 이 메모를 읽고 어떤 프로필로 일꾼을 띄울지 고릅니다. 그 방법은 실습 6에서 해 봅니다.
에이전트가 프로필을 스스로 고르게 하기 (Paseo tools 를 켠 경우)
Paseo 는 프로필 메모를 Paseo tools(에이전트에게 주는 Paseo 조작 도구)로 내보입니다. 그래서 일을 나눠 맡기는 에이전트가 메모를 읽고, 일꾼 에이전트를 어떤 설정으로 띄울지 고를 수 있습니다. Paseo tools 를 켠 뒤(실습 6) 이렇게 부탁합니다.
에이전트는 프로필을 읽고, 일마다 설정을 골라 일꾼을 띄웁니다. 메모는 고르는 기준일 뿐이니, 일꾼이 실제로 할 일은 부탁하는 글에 따로 적습니다. Paseo 에 함께 들어 있는 Paseo 스킬은 에이전트에게 “일을 맡기기 전에 프로필과 메모를 확인하라”고 안내합니다. 맞는 프로필이 없으면 설정된 프로바이더와 모델을 찾아보고, 대신 무엇을 골랐는지 알려 주게 되어 있습니다.
만들기와 검토를 한 번의 부탁으로 맡기는 예시는 완전 가이드 4장에 있습니다 — 검토 에이전트는 새 대화에서 일꾼이 만든 파일을 봅니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| 에이전트를 만들 때 프로필이 보이지 않음 | 프로필은 만든 호스트에 저장됩니다. 지금 보고 있는 호스트가 프로필을 만든 호스트인지, 3단계에서 Save 까지 했는지 확인합니다. 프로필은 모델 고르는 곳의 Profiles 아래에 있습니다. |
| 프로필을 고쳤는데 이미 도는 에이전트는 그대로임 | 정상입니다. 프로필을 고치면 그 뒤에 고르는 에이전트부터 적용되고, 이미 만든 에이전트는 바뀌지 않습니다. |
| 고르고 싶은 설정 칸이 없음 | 쓸 수 있는 설정은 프로바이더와 모델에 따라 다릅니다. 다른 모델을 골라 보세요. |
| 검토 에이전트가 파일을 고쳐 버림 | 두 에이전트는 같은 작업 폴더를 쓰므로, 고친 내용이 그대로 섞입니다. Changes 에서 무엇이 바뀌었는지 확인하고, 다음에는 부탁에 “파일은 고치지 마”를 분명히 적습니다. |
| 프로필에서 고른 설정 중 하나만 바꾸고 싶음 | 프로필을 고른 뒤에도, 부탁을 보내기 전에는 설정을 따로 고칠 수 있습니다. |
프로필과 프로바이더 전체 설명: 완전 가이드 3장 — 에이전트 고르기
- 프로필 = 프로바이더·모델·모드·생각 수준·기능 설정을 이름 하나로 묶어 저장한 것. 만드는 곳은 Settings → your host → Agents → Agent profiles → New profile.
- 에이전트를 만들 때 모델 고르는 곳의 Profiles 아래에서 고르면 한꺼번에 적용됩니다. 보내기 전에 고칠 수 있습니다.
- 프로필은 그 호스트에 저장되고, 고치면 그 뒤에 고르는 에이전트부터 적용됩니다.
- 검토는 같은 워크스페이스에서 New agent 로 두 번째 에이전트를 만들어 “파일은 고치지 말고 검토해 줘”라고 부탁합니다. 두 에이전트는 작업 폴더를 함께 씁니다.
- 지적은 원래 에이전트에게 돌려주고, Changes 에서 다시 확인합니다.
출처: paseo.sh/docs/agent-profiles (agent-profiles.md) · paseo.sh/docs/parallel-development (parallel-development.md) · paseo.sh/docs/orchestration-workflows (orchestration-workflows.md) — Paseo 0.15.3 · 수집일 2026-11-09
에이전트가 일꾼 에이전트를 부리게 하기 — Paseo tools 켜기
지금까지는 내가 에이전트를 하나씩 만들어 일을 시켰습니다. 이번에는 스위치 하나를 켜서, 내가 대화하는 에이전트가 다른 에이전트를 직접 만들어 일을 나눠 맡기고 결과를 모아 오게 합니다.
- Enable Paseo tools 를 켜서 에이전트에게 Paseo tools(에이전트가 Paseo 를 조작할 수 있게 주는 도구 — 에이전트 만들기, 워크스페이스 만들기 등)를 줍니다.
- 말 한마디로 일꾼 에이전트(서브에이전트 — 일을 나눠 받은 쪽 에이전트)를 띄우고, Subagents track 에서 일하는 모습을 지켜봅니다.
- 조사를 여럿에게 나누고, 중간에 진행을 묻고, 방향을 바꾸고, 멈추게 합니다.
준비물 확인 → 따라 하기 1~4단계까지만 해도 핵심은 끝납니다(스위치 켜기 → 일꾼 하나 띄우기 → 지켜보기). 5~6단계와 그 아래 「더 해 볼 부탁」은 익숙해진 뒤에 해도 됩니다. 에이전트가 일꾼을 못 띄우면 막히면을 보세요.
준비물
- Paseo 데스크톱 앱과 로그인해 둔 에이전트 CLI. 시작 전 준비를 마쳤다면 됩니다. 프로바이더(provider — Paseo 가 실행하는 에이전트 CLI 한 종류)가 둘 이상이면 일꾼을 다른 프로바이더·모델로 띄울 수 있습니다.
- 바뀐 내용이 있는 워크스페이스 하나. 워크스페이스(일 하나를 하는 자리 — 작업 폴더가 딸려 있음)는 실습 1~3에서 쓰던 것을 그대로 씁니다. 모두 보관했다면 실습 1의 2~4단계로 새로 하나 만듭니다. 검토시킬 거리가 있어야 하기 때문입니다.
- (있으면 좋음) 프로필. 실습 5에서 만든 프로필이 있으면, 지휘하는 에이전트가 그 메모를 읽고 일꾼의 설정을 고를 수 있습니다.
따라 하기
1단계 · Enable Paseo tools 켜기
에이전트에게 Paseo tools 를 넣어 주는 기능은 처음에는 꺼져 있습니다. 내가 켜야 에이전트가 다른 에이전트를 만들 수 있습니다.
- Settings → your host → Agents 열기설정 → 내 호스트(host — 데몬이 돌아가는 컴퓨터. 보통 지금 쓰는 이 컴퓨터) → 에이전트.
- Enable Paseo tools 켜기스위치를 켭니다. 이 도구로 에이전트는 자기가 도는 호스트의 에이전트와 워크스페이스를 직접 다룹니다.
2단계 · 새 에이전트 시작하기
스위치를 켰다고 지금 돌고 있는 에이전트가 곧바로 도구를 갖게 되는 것은 아닙니다. 새로 시작하거나 다시 불러온 에이전트가 도구를 받습니다.
- 준비한 워크스페이스에서 새 에이전트 시작하기가장 확실한 방법입니다. 이 에이전트가 오늘의 “지휘하는 에이전트”가 됩니다.
- 또는 쓰던 에이전트를 다시 불러오기(reload)대화를 이어 가고 싶다면 기존 에이전트를 다시 불러와 도구를 받게 합니다.
3단계 · 첫 위임 — 검토 일꾼 하나 띄우기
지휘하는 에이전트에게 다음처럼 부탁합니다. 공식 문서의 첫 예시를 우리말로 옮긴 것입니다.
부탁에는 세 가지가 들어 있습니다 — 무엇으로(Paseo 로), 누구에게 무엇을(두 번째 에이전트에게 검토를), 끝나면 어떻게(요약해서 보고). 브랜치(원본에서 갈라져 나온 작업 줄기)는 지금 워크스페이스에서 작업 중인 것을 가리킵니다.
4단계 · Subagents track 에서 일꾼 지켜보기
- 입력 칸 근처의 Subagents track 찾기Subagents track(일꾼 에이전트들이 나란히 보이는 줄)은 composer(부탁을 적는 입력 칸) 가까이에 있습니다. 방금 띄운 일꾼이 여기에 나타납니다.
- 일꾼을 열어 대화 따라가기일꾼을 열면 그 에이전트가 무엇을 읽고 무엇을 하는지 대화로 볼 수 있습니다.
- 기다리는 동안 계속 말해도 됩니다일꾼이 일하는 동안에도 지휘하는 에이전트와 대화를 이어 갈 수 있습니다. 일꾼이 끝나면 지휘하는 에이전트가 알림을 받습니다.
5단계 · 조사를 셋에게 나누기
서로 상관없이 알아볼 수 있는 질문은 일꾼 여럿에게 나눠 줍니다. 조사만 하고 파일은 고치지 않게 하면, 같은 워크스페이스에서 함께 일해도 서로 부딪치지 않습니다.
6단계 · 중간에 묻고, 방향을 바꾸고, 멈추기
일꾼들이 일하는 동안에도 지휘하는 에이전트에게 말을 걸 수 있습니다. 아래 셋은 필요할 때 따로따로 보내는 부탁입니다.
“서브에이전트들이 지금 무엇을 하고 있는지 요약하고, 막힌 것이 있으면 알려 줘.”
→ 지금 대화에 진행 요약이 올라옵니다.
“테스트를 살펴보는 일꾼에게, 잘못된 입력이 들어오는 경우도 확인하라고 전해 줘.”
→ 그 일꾼이 하던 대화에서 이어서 일합니다.
“처리 순서를 따라가는 일꾼이 지금 하는 일은 멈춰 줘. 다만 에이전트는 남겨 둬, 다른 일을 시킬 거야.”
→ 하던 일만 멈추고, 일꾼은 남아 다음 지시를 기다립니다.
더 해 볼 부탁 세 가지
아래는 공식 문서의 예시를 우리말로 옮긴 것입니다. 내 프로젝트에 맞게 일의 내용만 바꿔 쓰면 됩니다. 셋 모두 실습 5의 프로필을 활용합니다.
계획은 지금 대화에서 세우고, 실제로 고치는 일은 일꾼에게 넘깁니다.
‘파서 수정’은 원문 예시입니다 — 내 프로젝트의 고칠 기능 이름으로 바꿔 적습니다. 일꾼은 자기 워크트리에서 고칩니다. 맞는 프로필이 없으면 에이전트가 설정된 프로바이더와 모델을 찾아보고, 무엇을 골랐는지 알려 줍니다.
서로 상관없는 수정 두 개를 동시에 시킬 때, 일마다 워크트리를 따로 줍니다.
여기서 이슈(GitHub 에 올려 둔 할 일·버그 항목)는 고칠 거리 하나하나를 가리킵니다. 시작 지점은 원문 예시가 main 입니다 — 최신에서 시작하려면 origin/main 이라고 적습니다. 일꾼마다 따로 꺼낸 폴더에서 고치므로 서로 부딪치지 않습니다. 검사 결과가 붙은 변경 두 개를 받아 살펴보면 됩니다. 내가 직접 워크트리를 둘 만드는 방법은 실습 2.
만드는 에이전트와 따져 보는 에이전트를 다르게 고릅니다.
검토 일꾼은 새 대화에서 구현 일꾼이 만든 파일을 봅니다. 다른 모델의 판단을 받고 싶으면 프로바이더가 다른 프로필을 씁니다.
Paseo 일꾼과, 에이전트가 원래 갖고 있던 서브에이전트의 차이
어떤 에이전트 CLI 는 자체 서브에이전트 기능을 갖고 있습니다. Subagents track 에는 두 종류가 모두 나타날 수 있는데, 할 수 있는 일이 다릅니다.
| Paseo 서브에이전트 | 프로바이더 자체 서브에이전트 | |
|---|---|---|
| 프로바이더 | 설정된 어떤 프로바이더든 | 부모 프로바이더의 체계 안에서 정해짐 |
| 워크스페이스 | 지금 워크스페이스 또는 따로 지정한 워크스페이스 | 프로바이더가 관리 |
| 대화 | 내가 직접 말을 걸 수 있는 온전한 에이전트 세션 | 읽기만 되는 진행 기록 |
| 조작 | 이어서 지시, 설정 변경, 보관(archive), 떼어 내기(detach) | 시작과 끝을 프로바이더가 관리 |
다른 워크스페이스에 만든 Paseo 서브에이전트도 부모의 Subagents track 에 속하며, 자기 워크스페이스에서는 탭으로도 열립니다. 부모에게서 독립한 에이전트로 만들려면 앱에서 떼어 내거나(detach) paseo agent detach 를 씁니다.
스위치를 켜지 않고 명령으로 맡기기 (CLI)
명령 창을 쓸 수 있는 에이전트는 Paseo CLI 로도 일꾼을 띄울 수 있습니다. 이 방법은 Enable Paseo tools 를 켜지 않아도 됩니다. Paseo 가 설치되어 있고 호스트가 돌고 있으며 Codex 가 설정되어 있다면:
paseo run --provider codex --no-wait \
"Review this branch without changing files"
paseo ls -a
첫 명령은 일꾼을 시작하고 바로 돌아옵니다. 둘째 명령은 보관된 것과 배경에서 도는 것까지 에이전트를 모두 보여 줍니다. Paseo 안의 에이전트가 이 명령을 실행하면 일꾼은 같은 워크스페이스의 서브에이전트가 되고, 내가 내 터미널에서 실행하면 새 로컬 워크스페이스에서 시작합니다. 자세한 명령은 완전 가이드 8장.
에이전트끼리 말 걸기 · 다른 컴퓨터에 일 시키기
에이전트 ID 로 말 걸기. 에이전트는 에이전트 ID(Paseo 가 특정 에이전트를 가리킬 때 쓰는 식별 번호)로 서로에게 부탁을 보낼 수 있습니다. 같은 호스트라면 워크스페이스가 달라도, 자기가 띄우지 않은 에이전트에게도 보낼 수 있습니다.
- 받을 에이전트의 탭을 오른쪽 클릭해 Copy agent id(에이전트 ID 복사)를 고릅니다.
- 보낼 에이전트와의 대화에 그 ID 를 붙여 넣고 부탁합니다 — “Paseo 로 에이전트 [붙여 넣은 ID] 에게 이 말을 보내 줘: ‘네 워크스페이스의 파서 변경을 검토하고 빠진 테스트를 알려 줘.’”
받는 에이전트는 하던 대화 안에서 그 말을 받습니다. 에이전트가 보낸 말은 기본적으로 진행 중인 차례에 방향을 덧붙이는 방식(steer)으로 들어가고, 그것이 안 되면 끼어들어 멈추는 방식(interrupt)으로 바뀝니다. MCP 의 activeTurnBehavior 나 CLI 의 --behavior 를 steer 또는 interrupt 로 정해 바꿀 수 있습니다. 답장을 따로 받으려면 보내는 쪽의 ID 도 함께 알려 줍니다. 내부적으로는 에이전트가 send_agent_prompt 를 받는 쪽 agentId 와 prompt 로 부르며, list_agents 로 ID 를 찾을 수도 있습니다. CLI 에서는 paseo send <id>.
다른 컴퓨터. CLI 는 다른 Paseo 호스트를 가리킬 수 있습니다. 먼저 CLI 를 그 데몬에 연결하고 그 호스트의 워크스페이스를 정해 둡니다. 저장소와 필요한 프로바이더가 그 컴퓨터에 있어야 합니다. 그런 뒤 “내가 알려 준 원격 호스트와 워크스페이스로 Paseo CLI 를 써서, 거기에 에이전트를 띄워 실패한 빌드를 조사하고 결과를 여기에 요약해 줘. 파일은 바꾸지 마.”처럼 부탁합니다. 일꾼은 그 컴퓨터에서 돕니다. 다른 호스트를 가리킬 때는 CLI 의 --host 옵션을 쓰며, 스위치로 넣어 준 Paseo tools 는 지휘하는 에이전트 자신의 호스트에서만 동작합니다.
Paseo tools 로 에이전트가 할 수 있는 일 전체
- 호스트에 설정된 어떤 프로바이더·모델로든 다른 에이전트를 띄웁니다.
- 조사·구현·검토를 여러 에이전트(프로바이더가 달라도)에게 나눠 동시에 진행합니다.
- 에이전트 ID 로 서로에게 질문하고, 찾은 것을 알리고, 일을 부탁합니다.
- 진행을 확인하고, 일을 멈추고, 결과를 모읍니다.
- 워크스페이스와 워크트리를 만들어 독립된 변경마다 작업 폴더를 따로 줍니다.
- CLI 로, 닿을 수 있는 다른 Paseo 호스트의 에이전트를 띄우고 관리합니다.
- 프로필과 메모를 보고 UI 작업·계획·검토에 맞는 설정을 고릅니다.
- 정한 시간에 새 에이전트로 부탁을 실행하는 예약을 만듭니다 → 실습 7.
- 같은 에이전트를 주기적으로 다시 깨워 하던 일을 잇게 하는 하트비트를 만듭니다 → 실습 8.
도구 목록과 설정은 완전 가이드 4장에 있습니다. 되풀이해 쓰는 작업 순서를 담은 오케스트레이션 스킬은 선택 사항입니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| 에이전트가 다른 에이전트를 띄우지 못함 | Settings → your host → Agents 에서 Enable Paseo tools 가 켜져 있는지 봅니다(처음에는 꺼져 있음). 켠 뒤에는 새 에이전트를 시작하거나 기존 에이전트를 다시 불러와야 도구를 받습니다. |
| 일꾼이 어디 있는지 모르겠음 | 입력 칸 근처의 Subagents track 을 엽니다. 다른 워크스페이스에 만들어진 일꾼도 부모의 줄에 속하고, 그 워크스페이스에서는 탭으로도 열립니다. |
| 일꾼들의 수정이 서로 섞임 | 같은 워크스페이스의 일꾼들은 파일을 함께 씁니다. 고치는 일은 “워크트리 격리로 워크스페이스를 따로 만들어”라고 부탁해 일마다 폴더를 나눕니다. |
| 일꾼에게 직접 말할 수 없고 읽기만 됨 | 프로바이더 자체 서브에이전트일 수 있습니다(읽기만 되는 진행 기록). 직접 말을 걸 수 있는 것은 Paseo 서브에이전트입니다 — 3단계 예시처럼 부탁에 “Paseo 로 … 띄워 줘”를 분명히 적습니다. |
| 일꾼이 엉뚱한 방향으로 감 | 6단계의 부탁을 씁니다 — 방향을 바꾸라고 전하거나, 지금 하는 일만 멈추고 에이전트는 남겨 두라고 합니다. |
| 맞는 프로필이 없다고 함 | 문제가 아닙니다. 에이전트가 설정된 프로바이더와 모델을 찾아 고르고, 무엇을 골랐는지 알려 줍니다. 자주 쓸 조합은 실습 5처럼 프로필로 만들어 둡니다. |
오케스트레이션 전체 설명: 완전 가이드 4장 — 오케스트레이션
- 오케스트레이션 = 내가 대화하는 에이전트가 일꾼 에이전트를 만들어 일을 나눠 맡기고 결과를 모으는 것.
- 먼저 Settings → your host → Agents → Enable Paseo tools 를 켭니다(처음에는 꺼져 있음). 그리고 새 에이전트를 시작하거나 기존 에이전트를 다시 불러옵니다.
- “Paseo 로 두 번째 에이전트를 띄워 …”라고 부탁하면 일꾼이 입력 칸 근처 Subagents track 에 나타납니다. 열어서 대화를 볼 수 있고, 기다리는 동안 계속 말해도 됩니다.
- 조사만 하는 일꾼은 같은 워크스페이스에서, 파일을 고치는 일꾼은 일마다 워크트리를 따로 주어 맡깁니다.
- 진행을 묻고, 방향을 바꾸고, 하던 일만 멈추게 하는 것도 지휘하는 에이전트에게 말로 합니다.
출처: paseo.sh/docs/orchestration (orchestration.md) · paseo.sh/docs/orchestration-workflows (orchestration-workflows.md) — Paseo 0.15.3 · 수집일 2026-11-09
매일 아침 정리 작업 예약하기 — Schedules
“평일 아침 9시마다 밤사이 올라온 일을 정리해 줘” 같은 되풀이되는 일을, 내가 부탁하지 않아도 정한 시간에 에이전트가 시작하도록 걸어 둡니다.
- 예약(schedule — 정한 시간마다 새 에이전트를 시작해 정해 둔 부탁을 실행하는 것)을 앱의 Schedules 화면에서 만듭니다.
- 한 번 돌려 보고, 실행 결과가 사라지지 않게 Archive on finish 를 조절합니다.
- 예약을 잠시 멈추고, 다시 켜고, 고치고, 지웁니다 — 화면에서도, 에이전트에게 말로도.
준비물 확인 → 따라 하기 1~4단계(만들기 → 결과 남기기 → 한 번 돌려 보기)까지가 핵심입니다. 5~6단계는 관리 방법입니다. 실행 결과가 사라졌거나 예약이 뜻대로 안 돌면 막히면을 보세요.
준비물
- Paseo 데스크톱 앱과 로그인해 둔 에이전트 CLI. 예약이 시작하는 것도 결국 내가 설치해 둔 에이전트입니다(시작 전 준비).
- 예약이 일할 저장소. 저장소(repo — 프로젝트 파일과 그 변경 이력이 들어 있는 폴더)는 실습 1에서 쓰던 프로젝트면 됩니다.
- 되풀이할 부탁 한 가지. 아래 예시 중 하나를 골라도 됩니다. GitHub 이슈(GitHub 에 올려 둔 할 일·버그 항목)·PR(내 브랜치의 변경을 원본에 합쳐 달라는 요청) 을 다루는 부탁이라면 시작 전 준비의 GitHub CLI 도 준비되어 있어야 합니다.
- (6단계를 할 때만) Paseo tools 켜기. 6단계(말로 예약 만들기)를 하려면 실습 6의 1~2단계(Paseo tools 켜기 → 새 에이전트 시작)를 먼저 해 둡니다. 1~5단계는 이것 없이 할 수 있습니다.
예약은 “이 시각에, 이 부탁을, 이 저장소에서, 이 에이전트 설정으로 실행한다”는 약속입니다. 시각이 되면 Paseo 가 새 에이전트를 시작합니다. 실행할 때마다 깨끗한 새 에이전트가 처음부터 일하므로, 매일 아침 점검·보고서·정리처럼 매번 새로 하는 일에 맞습니다.
Paseo 에는 하트비트(heartbeat — 이미 있는 같은 에이전트를 주기적으로 다시 깨워 하던 대화를 잇게 하는 것)도 있습니다. 둘 다 “주기적으로”라는 점은 같지만, 예약은 매번 새 에이전트, 하트비트는 같은 에이전트입니다. 오래 걸리는 빌드를 한 에이전트가 끝까지 지켜보게 하는 일은 하트비트 쪽이며 실습 8에서 다룹니다. 이 실습은 예약만 다룹니다.
예약에 어울리는 일의 예시입니다. 하나를 골라 2단계의 프롬프트(에이전트에게 적어 보내는 부탁)로 씁니다.
“새로 올라온 GitHub 이슈와 PR, 실패한 검사를 살펴보고, 내가 봐야 할 것을 요약해 줘.”
“문서가 지금 코드와 어긋난 곳이 있는지 점검하고, 고칠 곳을 목록으로 알려 줘. 파일은 고치지 마.”
“오래되어 쓰이지 않는 브랜치를 찾아 목록으로 알려 줘. 지우지는 마.”
PR(내 브랜치의 변경을 원본에 합쳐 달라는 요청) · 브랜치(원본에서 갈라져 나온 작업 줄기). 처음에는 ②·③처럼 보고만 하고 고치지 않는 부탁으로 시작하면 결과를 믿을 수 있는지 살펴보기 좋습니다.
따라 하기
1단계 · Schedules 화면 열기
예약을 만드는 방법은 네 가지지만, 앱의 Schedules 화면이 만들고 관리하는 주된 방법입니다.
| 방법 | 어떻게 | 이 실습에서 |
|---|---|---|
| 앱 | Schedules 화면에서 네 가지를 채워 만듭니다. | 1~5단계 |
| 채팅 | 에이전트에게 말로 부탁하면 대신 만들어 줍니다. | 6단계 |
| CLI | paseo schedule create — 화면 없는 서버나 스크립트용. | 접힌 상자 |
| MCP(에이전트에게 도구를 쥐여 주는 표준 방식) | 에이전트가 Paseo tools 로 직접 만들고 관리합니다. | — |
- 앱에서 Schedules(예약) 화면 열기예약 목록을 보고 새로 만드는 곳입니다.
2단계 · 네 가지를 채워 예약 만들기
- 에이전트 설정(agent settings)어떤 에이전트와 모델로 돌릴지 고릅니다.
- 반복 시각(cron cadence)언제마다 돌릴지 정합니다. Paseo 는 반복 시각을 cron(크론 — “평일 9시마다”처럼 되풀이되는 시각을 적는 표기법)으로 다룹니다. 예: 평일 아침 9시 =
0 9 * * 1-5(분·시·일·월·요일 순). 식을 모르겠으면 6단계처럼 말로 부탁합니다. - 저장소(repo)에이전트가 일할 프로젝트를 고릅니다.
- 프롬프트(prompt)실행할 때마다 에이전트에게 보낼 부탁을 적습니다. 위 예시 ①~③ 중 하나를 씁니다.
cron 표기 읽는 법과 시간대
cron 식은 빈칸으로 나뉜 다섯 칸입니다. 공식 CLI 문서의 예시 0 9 * * 1-5 는 “평일(월~금) 9시 0분마다”, 0 14 * * 1-5 는 “평일 14시마다”입니다.
CLI 문서에 따르면 예약 시각은 따로 정하지 않으면 UTC(세계 표준시 — 한국 시간보다 9시간 느림) 기준이며, CLI 에서는 --timezone 으로 지역 시간대를 정합니다. 앱 화면에서 시간대를 고르는 방법은 원문에 나와 있지 않으니, 만든 뒤 예약을 열어 다음 실행이 기대한 시각인지 확인하세요. CLI 로 만드는 방법은 완전 가이드 5장.
3단계 · 결과가 남도록 Archive on finish 끄기
예약은 실행할 때마다 워크스페이스를 하나 만듭니다. 그리고 Archive on finish(끝나면 보관)가 기본으로 켜져 있어서, 실행이 끝나면 그 워크스페이스와 에이전트를 자동으로 보관(archive — 더 쓰지 않는 것으로 정리해 두는 것)합니다. 연습하는 동안에는 결과를 열어 볼 수 있게 꺼 둡니다.
- Schedules 화면에서 방금 만든 예약 열기예약의 설정이 보입니다.
- Archive on finish 끄기끄면 실행이 끝나도 워크스페이스와 에이전트가 그대로 남습니다.
- 저장하기저장해야 다음 실행부터 적용됩니다.
꺼 두면 실행할 때마다 워크스페이스가 하나씩 남고, 내가 보관할 때까지 없어지지 않습니다. 매일 도는 예약이라면 금방 늘어나니, 확인이 끝난 것은 보관하세요(워크스페이스 보관 — 실습 3의 7단계와 같습니다). 하나씩 보관하기 번거로우면 Archive on finish 를 다시 켜고 저장해, 그 뒤 실행부터 자동으로 보관되게 합니다.
Archive on finish 의 세부 규칙
- 워크트리(같은 저장소를 다른 폴더·다른 브랜치로 하나 더 꺼내 놓은 작업 폴더) 격리로 도는 실행이라면, 보관할 때 그 워크트리를 쓰는 마지막 활성 워크스페이스가 보관된 뒤 워크트리도 함께 치워집니다.
- 이미 있는 폴더를 그대로 쓰는 Local 격리에도 이 옵션이 적용됩니다. 이 경우 워크스페이스를 보관해도 프로젝트 폴더는 그대로 남습니다.
- 옵션을 꺼 두어도, 에이전트를 만들기도 전에 실패한 실행은 정리됩니다.
- 저장되는 값은
target.config.archiveOnFinish(참/거짓)이며, 적지 않으면true입니다. - CLI 와 MCP 의 예약 도구로는 이 옵션을 바꿀 수 없습니다. 앱에서만 바꿉니다.
- 하트비트는 이미 있는 에이전트를 쓰므로 이 옵션이 없습니다.
4단계 · 한 번 돌려 보기
내일 아침까지 기다리지 않아도 됩니다. 예약에는 정해 둔 반복 시각과 상관없이 한 번 실행(run once)하는 동작이 있습니다.
- 예약을 한 번 실행하기Schedules 화면에서 그 예약을 한 번 실행합니다.
- 새로 생긴 워크스페이스 열기실행 하나가 워크스페이스 하나와 새 에이전트 하나를 만듭니다. 그 대화를 열어 에이전트가 일하는 것을 봅니다.
- 결과 읽고 프롬프트 다듬기답이 너무 길거나 엉뚱하면 예약을 열어 프롬프트를 고칩니다(다음 단계).
5단계 · 멈추고, 다시 켜고, 고치고, 지우기
예약은 만들어 두고 잊는 것이 아니라, 필요에 따라 상태를 바꿉니다. 할 수 있는 일은 여섯 가지입니다.
| 하는 일 | 언제 쓰나 |
|---|---|
| 살펴보기 (inspect) | 예약이 어떤 설정으로 걸려 있는지 확인할 때. |
| 잠시 멈춤 (pause) | 휴가처럼 한동안 돌릴 필요가 없을 때. 예약은 남아 있습니다. |
| 다시 시작 (resume) | 멈춰 둔 예약을 다시 돌릴 때. |
| 한 번 실행 (run once) | 기다리지 않고 지금 한 번 돌려 볼 때(4단계). |
| 고치기 (update) | 시각, 프롬프트, 에이전트 설정을 바꿀 때. |
| 지우기 (delete) | 더 이상 필요 없을 때. |
- 연습 삼아 잠시 멈췄다가 다시 시작해 보기Schedules 화면에서 방금 만든 예약을 멈추고, 다시 시작합니다.
- 연습용이라면 지우기계속 쓸 예약이 아니라면 지웁니다. 계속 쓸 것이라면 결과를 믿을 수 있게 된 뒤 Archive on finish 를 다시 켭니다.
6단계 · 화면 대신 말로 만들고 관리하기
칸을 채우는 대신, 아무 에이전트 대화에서나 말로 부탁해도 됩니다. 에이전트가 내 말에서 반복 시각·에이전트 설정·프롬프트를 골라 예약을 만들고, 만들었다고 알려 줍니다.
만든 뒤의 관리도 같은 방식입니다.
“아침 분류 예약을 잠시 멈춰 줘.”
“그 예약을 지금 한 번 돌려 줘.”
“그 예약을 평일 8시로 바꿔 줘.”
“그 예약을 지워 줘.”
에이전트는 Paseo MCP(에이전트에게 주는 Paseo 조작 도구 — Paseo tools)로 예약을 만듭니다. 에이전트에게 이 도구를 넣어 주는 Enable Paseo tools 는 처음에는 꺼져 있으니, 실습 6의 1~2단계를 먼저 해 둡니다.
“이 작업을 계속해 줘 — 20분마다 스스로 깨어나서 이어서 해”처럼 에이전트가 자기 자신을 다시 깨우도록 하는 것은 하트비트입니다. 새 에이전트가 생기지 않고 같은 대화가 이어집니다. → 실습 8
화면 없는 컴퓨터에서 — CLI 로 예약 만들기
화면 없는 서버나 스크립트에서는 paseo schedule create 명령으로 예약을 만듭니다. CLI 는 5m, 1h 같은 간단한 주기 표기도 받는데, 따로 다른 종류로 저장하지 않고 cron 으로 바꿉니다. cron 이 반복 시각의 기준 표기이기 때문입니다. 명령의 옵션은 완전 가이드 5장에 있습니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| 실행이 끝나자 워크스페이스와 에이전트가 사라짐 | 정상입니다 — Archive on finish 가 기본으로 켜져 있습니다. 결과를 남기려면 Schedules 화면에서 예약을 열어 끄고 저장합니다(3단계). |
| Archive on finish 를 명령이나 채팅으로 바꾸려는데 안 됨 | CLI 와 MCP 의 예약 도구는 이 옵션을 다루지 않습니다. 앱의 Schedules 화면에서만 바꿀 수 있습니다. |
| 어제 하던 일을 이어서 하길 바랐는데 매번 처음부터 함 | 예약은 매번 새 에이전트를 시작합니다. 같은 에이전트가 같은 대화를 이어 가게 하려면 하트비트를 씁니다 → 실습 8. |
| 채팅에서 부탁했는데 예약이 만들어지지 않음 | 에이전트가 Paseo 도구를 받지 못했을 수 있습니다. 실습 6의 1~2단계(Enable Paseo tools 켜기 → 새 에이전트 시작)를 확인합니다. |
| 남겨 둔 실행 워크스페이스가 너무 많아짐 | Archive on finish 를 끄면 내가 보관할 때까지 남습니다. 확인한 것은 보관하고, 예약이 안정되면 옵션을 다시 켭니다. |
| 시간이 아니라 “댓글이 달리면”처럼 일이 생겼을 때 시작하고 싶음 | 예약과 하트비트는 정한 주기로 돕니다. 댓글·멘션 같은 바깥 사건으로 에이전트를 시작하는 것은 Hub 라는 별도 서비스의 일입니다(완전 가이드의 Hub 장). |
예약과 하트비트 전체 설명: 완전 가이드 5장 — 예약과 하트비트
- 예약 = 정한 시각마다 새 에이전트를 시작해 정해 둔 부탁을 실행하는 것. 하트비트(같은 에이전트를 다시 깨움)와 다릅니다.
- 앱의 Schedules 화면에서 에이전트 설정·반복 시각(cron)·저장소·프롬프트 네 가지를 정해 만듭니다.
- 실행마다 워크스페이스가 하나 생기고, Archive on finish 가 기본으로 켜져 있어 끝나면 자동으로 보관됩니다. 결과를 남기려면 예약을 열어 끄고 저장합니다.
- 예약은 살펴보기·잠시 멈춤·다시 시작·한 번 실행·고치기·지우기를 할 수 있습니다.
- 에이전트 대화에서 말로 부탁해 만들고 관리할 수도 있습니다.
출처: paseo.sh/docs/schedules (schedules.md) · paseo.sh/docs/schedules-chat (schedules-chat.md) · cron 예시와 시간대는 paseo.sh/docs/schedules-cli (schedules-cli.md) · Enable Paseo tools 는 paseo.sh/docs/orchestration (orchestration.md) — Paseo 0.15.3 · 수집일 2026-11-09
오래 걸리는 빌드를 끝까지 지켜보게 하기 — 하트비트
빌드가 끝나기를 화면 앞에서 기다리지 않아도 됩니다. 같은 에이전트가 정해 둔 간격마다 스스로 깨어나 빌드 상태를 다시 보고, 실패했으면 고치고, 통과하면 그만두게 만드는 실습입니다.
- 예약(schedule — 정한 시간마다 새 에이전트를 시작)과 하트비트(heartbeat — 이미 있는 같은 에이전트를 주기적으로 다시 깨움)를 구분해서 고릅니다.
- 채팅 한 번으로 하트비트를 만들어, 에이전트가 빌드(소스 코드를 실제로 돌아가는 프로그램으로 만드는 과정)를 끝까지 지켜보게 합니다.
- 깨어나는 간격을 바꾸고, 일이 끝나면 하트비트를 지웁니다.
예약과 하트비트의 차이를 그림으로 먼저 보고 → 준비물 → 따라 하기 다섯 단계를 진행합니다. 뜻대로 안 되면 막히면으로 갑니다. 「개발자용 참고」 상자는 건너뛰어도 됩니다.
먼저 구분하기 — 예약과 하트비트
둘 다 "정한 시각에 프롬프트(에이전트에게 보내는 부탁 글)를 보낸다"는 점은 같습니다. 다른 것은 그 프롬프트를 누가 받느냐입니다. 예약은 매번 새 에이전트를 만들어 맡기고, 하트비트는 지금 일하던 그 에이전트에게 다시 보냅니다. 그래서 하트비트를 받은 에이전트는 앞에서 한 대화를 그대로 이어 갑니다.
| 비교 | 예약 (schedule) | 하트비트 (heartbeat) |
|---|---|---|
| 누가 일하나 | 실행할 때마다 새 에이전트 | 이미 있는 같은 에이전트 하나 |
| 대화 | 매번 새로 시작 | 같은 대화를 이어 감 |
| 어울리는 일 | 매일 아침 이슈(GitHub 에 올려 둔 할 일·버그 항목) 정리, 보고서, 정기 점검 | 빌드 지켜보기, 하던 일을 끊기지 않게 이어 가기 |
| 할 수 있는 관리 | 살펴보기·잠시 멈춤·다시 시작·한 번 실행·수정·삭제 | 만들기·지우기만. CLI(글자 명령으로 쓰는 방식)에서는 깨어나는 간격만 바꿀 수 있음 |
| 따라 하기 | 실습 7 | 이 실습 |
준비물
- 에이전트와 대화할 수 있는 워크스페이스(일 하나를 하는 자리 — 작업 폴더가 딸려 있음) 하나. 아직 없다면 실습 1을 먼저 합니다.
- Paseo tools(에이전트에게 주는 Paseo 조작 도구)가 켜져 있을 것. 채팅에서 부탁하면 에이전트가 이 도구로 하트비트를 만듭니다. 부탁을 받을 에이전트는 Paseo tools 를 켠 뒤에 새로 시작했거나 다시 불러온 에이전트여야 합니다(실습 6의 1~2단계) — 켜기 전에 시작한 에이전트는 하트비트를 만들지 못합니다.
- 지켜볼 빌드 하나. CI(코드를 올리면 자동으로 빌드하고 검사해 주는 서비스), EAS, Docker, 릴리스 빌드(사용자에게 내보낼 배포용 프로그램을 만드는 빌드)처럼 끝날 때까지 시간이 걸리는 것이면 됩니다. 연습용이라면 "테스트 전체 실행"처럼 몇 분 걸리는 일로 대신해도 됩니다.
따라 하기
1단계 · 빌드를 맡을 에이전트 대화 열기
하트비트는 부탁을 받은 바로 그 에이전트를 깨웁니다. 그러니 빌드를 시작했거나 빌드 내용을 아는 에이전트의 대화에서 시작합니다.
- 빌드할 프로젝트의 워크스페이스에서 에이전트 대화를 엽니다이미 빌드를 시작한 대화가 있으면 그 대화를 그대로 씁니다. 새 대화를 열면 그 에이전트는 앞의 사정을 모릅니다. 다만 그 에이전트가 Paseo tools 를 켜기 전에 시작한 것이라면 먼저 다시 불러오거나, 같은 워크스페이스에서 새 에이전트를 시작해 빌드 사정을 알려 준 뒤 진행합니다.
- 무엇을 지켜볼지 먼저 알려 줍니다아래처럼 빌드를 시작하게 하고, 상태를 어떻게 확인하는지 정리하게 합니다.
릴리스 빌드를 시작해 줘. 빌드가 진행 중인지, 실패했는지, 통과했는지를 어떤 방법으로 확인할 수 있는지도 한 줄씩 정리해 줘.
성공 표시 — 에이전트가 빌드를 시작했고, 상태를 확인하는 방법을 답으로 알려 주었습니다.
2단계 · 하트비트를 만들어 달라고 부탁하기
양식을 채울 필요가 없습니다. 같은 대화에 아래 문장을 보내면 에이전트가 깨어나는 간격과 프롬프트를 정해 하트비트를 만들고 결과를 알려 줍니다. 문장 속 로그(프로그램이 남기는 진행 기록)는 빌드가 남긴 기록을 말합니다.
Paseo로 5분마다 하트비트를 만들어 줘. 깨어날 때마다 릴리스 빌드 상태를 확인하고, 실패했으면 로그를 보고 원인을 고친 뒤 다시 돌려 줘. 빌드가 통과하면 하트비트를 지워 줘. 두 시간 뒤에는 만료되게 해 줘.
- "Check the release build every 5 minutes until it passes, and fix the cause if it fails." (릴리스 빌드가 통과할 때까지 5분마다 확인하고, 실패하면 원인을 고쳐 줘.)
- "Keep working on this refactor — wake yourself every 20 minutes and continue where you left off." (이 정리 작업을 계속해 줘 — 20분마다 스스로 깨어나 멈춘 곳에서 이어서.)
성공 표시 — 에이전트가 하트비트를 만들었다고 답했고, 답에 깨어나는 간격이 들어 있습니다.
3단계 · 깨어나는 것을 지켜보기
이제 내가 할 일은 없습니다. 정한 시각이 되면 같은 프롬프트가 같은 대화에 다시 들어오고, 에이전트는 상태를 다시 살핀 뒤 이어서 일합니다. 그동안 다른 워크스페이스에서 다른 일을 해도 됩니다.
- 정한 시각이 지난 뒤 그 대화를 다시 엽니다새 대화가 생기지 않고, 같은 대화 아래쪽에 확인 결과가 이어서 쌓여 있어야 합니다.
- 끼어들고 싶으면 그 대화에 그냥 말합니다예: "다음 확인 때는 테스트 로그도 같이 요약해 줘." 같은 에이전트이므로 이 말도 기억합니다.
성공 표시 — 같은 대화에 깨어날 때마다의 확인 결과가 차례로 보입니다.
4단계 · 간격을 바꾸거나 그만두기
채팅으로 할 수 있는 것은 만들기와 지우기뿐입니다. 그래서 간격이나 할 일을 바꾸려면 "지우고 새로 만들어 달라"고 부탁합니다.
“지금 하트비트를 지우고, 2분마다 깨어나는 것으로 새로 만들어 줘. 할 일과 끝내는 조건은 그대로.”
“지금 하트비트를 지우고 새로 만들어 줘. 이번에는 빌드가 실패해도 고치지 말고 원인만 알려 줘.”
“하트비트를 지워 줘.”
에이전트는 간격을 cron(크론 — "몇 분·몇 시·며칠·몇 월·무슨 요일"을 다섯 칸으로 적는 시간표 표기) 식으로 저장합니다. 에이전트의 답에 이런 식이 보이면 아래 그림처럼 읽습니다.
*는 "모든", */5는 "5마다"라는 뜻입니다. 식을 외울 필요는 없습니다 — 말로 부탁하면 에이전트가 식으로 바꿉니다.성공 표시 — 에이전트가 예전 하트비트를 지우고 새 간격으로 다시 만들었다고 답했습니다.
명령으로 하트비트 다루기 (paseo heartbeat)
하트비트 명령은 Paseo 안에서 돌고 있는 에이전트가 자기 대화에 대해 실행하는 것입니다. Paseo가 에이전트 세션(워크스페이스 안에서 도는 에이전트 대화 하나)에 넣어 주는 PASEO_AGENT_ID 값이 있어야 동작합니다. 에이전트에게 "이 명령을 실행해 줘"라고 시킬 때 씁니다.
paseo heartbeat create \
--cron "*/20 * * * *" \
--name heartbeat \
"Check the current task state and continue with the next useful step."
| 줄 | 뜻 |
|---|---|
paseo heartbeat create \ | 이 명령을 실행한 에이전트의 대화에 하트비트를 만듭니다. 줄 끝의 \는 "명령이 다음 줄로 이어진다"는 표시입니다. |
--cron "*/20 * * * *" | 20분마다 깨웁니다. 하트비트는 cron 식을 그대로 적어야 합니다. --every 5m 같은 줄임 표기는 예약에서만 쓸 수 있습니다. |
--name heartbeat | 하트비트에 붙이는 이름입니다. |
| 마지막 따옴표 문장 | 깨어날 때마다 다시 들어올 프롬프트입니다. 예시는 "지금 일의 상태를 확인하고, 다음으로 쓸모 있는 단계를 이어서 해라"는 뜻입니다. |
바꾸기와 지우기는 아래 두 줄이 전부입니다. <id> 자리에는 그 하트비트의 id를 넣습니다.
paseo heartbeat update <id> --cron "*/10 * * * *"
paseo heartbeat delete <id>
update는 깨어나는 간격(cron)과, 필요하면 시간대만 바꿉니다. 깨울 대상과 프롬프트는 고정입니다.- 채팅(Paseo tools)으로는 간격 변경도 없습니다 — 지우고 새로 만듭니다.
- 매번 깨끗한 새 에이전트로 빌드를 확인하고 싶다면 하트비트가 아니라 예약입니다. 문서의 예:
paseo schedule create --every 5m --name build-watch --max-runs 24 …(5분마다, 최대 24번). → 실습 7
5단계 · 끝났는지 확인하고 하트비트 정리하기
- 결과를 물어봅니다같은 대화에 "빌드가 통과했는지, 그동안 무엇을 고쳤는지, 하트비트를 지웠는지 알려 줘."라고 보냅니다.
- 아직 남아 있다면 지우게 합니다"하트비트를 지워 줘." 한 줄이면 됩니다. 하트비트에는 예약처럼 잠시 멈춤 기능이 없으므로, 쉬게 하려면 지웁니다.
- 고친 내용을 검토합니다에이전트가 빌드를 고치느라 파일을 바꿨을 수 있습니다. 바뀐 내용을 살펴보는 방법은 실습 3과 같습니다.
성공 표시 — 빌드가 통과했고, 에이전트가 하트비트를 지웠다고 답했습니다.
막히면
| 증상 | 먼저 확인할 것 → 해결 |
|---|---|
| 에이전트가 하트비트를 만들 수 없다고 함 | Paseo tools가 켜져 있는지 봅니다. 채팅으로 만드는 하트비트는 이 도구를 거칩니다. → 실습 6의 1~2단계대로 켠 뒤 새 에이전트를 시작해 다시 부탁합니다(켜기 전에 시작한 에이전트는 도구를 받지 못했습니다). |
| 깨어날 때마다 새 에이전트·새 대화가 생김 | 만들어진 것이 하트비트가 아니라 예약입니다. 예약은 지우고(실습 7), "이 대화의 너 자신을 5분마다 깨우는 하트비트를 만들어 줘"처럼 다시 부탁합니다. |
| 빌드가 끝났는데도 계속 깨어남 | 끝내는 조건이 빠졌습니다. "하트비트를 지워 줘"라고 보내고, 다음에는 "통과하면 지워 줘"와 만료 시간을 처음부터 넣습니다. |
| 간격이나 할 일을 고쳐 달라고 했는데 안 된다고 함 | 정상입니다. 채팅으로는 만들기·지우기만 됩니다. "지우고 새로 만들어 줘"라고 부탁합니다. |
paseo heartbeat 명령이 내 터미널에서 실패함 | 이 명령은 에이전트 세션 안에서만 채워지는 PASEO_AGENT_ID가 필요합니다. 에이전트에게 실행을 맡깁니다. --every를 썼다면 --cron "…"으로 바꿉니다. |
| 앞 확인 결과와 상관없이 매번 처음부터 보게 하고 싶음 | 그 경우는 예약이 맞습니다 — 실행마다 새 에이전트가 시작합니다. → 실습 7 |
에이전트가 아예 보이지 않거나 설정이 먹지 않는 문제는 실습 10에서 다룹니다.
- 예약은 매번 새 에이전트, 하트비트는 같은 에이전트를 다시 깨웁니다. 빌드를 끝까지 지켜보는 일은 하트비트입니다.
- 빌드를 아는 에이전트의 대화에서 부탁합니다. 한 문장에 간격 · 깨어나서 할 일 · 끝내는 조건 · 만료 시간을 담습니다.
- 정한 시각마다 같은 대화에 확인 결과가 쌓입니다.
- 채팅으로는 만들기와 지우기만 됩니다. 바꾸려면 지우고 새로 만듭니다.
- 끝나면 하트비트가 지워졌는지 꼭 확인합니다.
출처: paseo.sh/docs/schedules (schedules.md) · paseo.sh/docs/schedules-chat (schedules-chat.md) · paseo.sh/docs/schedules-cli (schedules-cli.md) · paseo.sh/docs/orchestration-workflows (orchestration-workflows.md) — Paseo 0.15.3 · 수집일 2026-11-09
새 워크트리가 바로 돌아가게 준비하기 — .worktreeinclude · paseo.json
새 워크트리는 깨끗한 폴더로 태어나서, 내 컴퓨터에만 있던 설정 파일도 설치해 둔 부품도 없습니다. 파일 두 개를 저장소에 넣어 두면 Paseo가 워크트리를 만들 때마다 파일을 복사하고 준비 명령을 대신 돌려 줍니다.
.worktreeinclude로.env같은 내 컴퓨터 전용 파일을 새 워크트리(같은 저장소를 다른 폴더·다른 브랜치로 하나 더 꺼내 놓은 작업 폴더)에 자동으로 복사합니다.paseo.json으로 워크트리가 만들어진 직후 설치 명령이 저절로 돌게 합니다.- 개발 서버(만드는 중인 웹 화면을 내 컴퓨터에서 띄워 보는 프로그램)를 "서비스"로 등록해, 워크트리가 여러 개여도 포트(한 컴퓨터 안에서 프로그램마다 나눠 쓰는 통신 창구 번호)가 겹치지 않게 띄웁니다.
왜 필요한가를 그림으로 보고 → 준비물 → 따라 하기에서 1·2·4·5단계만 해도 "만들자마자 돌아가는 워크트리"가 됩니다. 3·6단계(서비스)는 웹 화면이 있는 프로젝트일 때 합니다. 안 되면 막히면으로 갑니다.
왜 필요한가 — 새 워크트리에 없는 것
워크트리에는 Git(파일의 변경 이력을 기록하는 도구)이 관리하는 파일만 들어옵니다. 그런데 프로젝트가 돌아가려면 보통 두 가지가 더 필요합니다. 하나는 .env처럼 비밀 값이 들어 있어 일부러 Git에 올리지 않는 파일(gitignore(Git이 못 본 척하도록 목록에 적어 둔 파일) 대상)이고, 다른 하나는 설치 명령을 돌려야 생기는 의존성(프로젝트가 가져다 쓰는 남의 코드 묶음)입니다. 워크트리를 만들 때마다 손으로 채우면 번거롭고, 빠뜨리면 에이전트가 첫 명령부터 실패합니다.
.env는 .worktreeinclude가 복사하고, 설치는 paseo.json의 setup이 맡습니다.Paseo는 워크트리를 만들 때 아래 순서로 움직입니다. 복사가 먼저이므로, 설치 명령이 돌 때는 .env가 이미 제자리에 있습니다.
준비물
- 실습 2를 해 본 프로젝트. 워크스페이스(일 하나를 하는 자리 — 작업 폴더가 딸려 있음)를 New worktree(새 워크트리)로 만들어 본 적이 있으면 됩니다.
- 원본 폴더(워크트리를 만들어 내는 원래 저장소 폴더 — 소스 체크아웃)에 복사하고 싶은 파일이 실제로 있을 것. 예:
.env. 그 파일은.gitignore에 올라 있어야 합니다. - 이 프로젝트를 준비시키는 명령을 알 것. 아래 예시는 문서의 예를 따라 Node 프로젝트(
npm ci로 설치,npm run dev로 개발 서버 실행) 기준입니다. 다른 프로젝트라면 그 자리에 내 프로젝트의 명령을 넣습니다. 모르면 에이전트에게 "이 프로젝트를 처음 받은 사람이 실행해야 하는 설치 명령과 개발 서버 명령을 알려 줘"라고 물어봅니다.
따라 하기
1단계 · .worktreeinclude 만들기 — 복사할 파일 목록
원본 폴더의 맨 위에 .worktreeinclude라는 이름의 글 파일을 만들고, 복사할 파일을 한 줄에 하나씩 적습니다. 편집기로 직접 만들어도 되고, Isolation 을 Local 로 고른 워크스페이스(원본 폴더를 그대로 씀)의 에이전트에게 아래 내용으로 만들어 달라고 해도 됩니다. config/… 두 줄은 예시입니다 — 내 프로젝트에 없으면 지우고 .env 한 줄만 둡니다.
.worktreeinclude
# 내 컴퓨터에만 있는 환경 설정
.env
config/*.local.json
!config/production.local.json
| 줄 | 뜻 |
|---|---|
# 내 컴퓨터에만… | #로 시작하는 줄은 사람이 읽는 메모입니다. Paseo는 건너뜁니다. |
.env | 맨 위 폴더의 .env 파일을 복사합니다. |
config/*.local.json | config 폴더에서 이름이 .local.json으로 끝나는 파일을 모두 복사합니다(*는 "아무 글자나"). 예: config/dev.local.json. |
!config/production.local.json | 맨 앞의 !는 "이것은 빼라"입니다. 위 줄에 걸리더라도 이 파일은 복사하지 않습니다. |
.gitignore에 있는지 함께 확인합니다.성공 표시 — 원본 폴더 맨 위에 .worktreeinclude가 있고, 적어 둔 파일(.env 등)이 원본 폴더에 실제로 있습니다.
2단계 · paseo.json 만들기 — 만든 직후 돌릴 명령
저장소 맨 위에 paseo.json을 만들고 setup에 설치 명령을 적습니다. setup은 워크트리가 만들어진 뒤 한 번 실행됩니다. 의존성 설치와 프로젝트 초기화에 씁니다.
paseo.json
{
"worktree": {
"setup": "npm ci"
}
}
| 줄 | 뜻 |
|---|---|
{ … } | 설정 전체를 감싸는 괄호입니다. 여는 괄호와 닫는 괄호의 짝이 맞아야 합니다. |
"worktree": { … } | "워크트리에 관한 설정"이라는 묶음입니다. |
"setup": "npm ci" | 워크트리를 만든 직후 그 폴더 안에서 npm ci(의존성 설치 명령)를 실행하라는 뜻입니다. 내 프로젝트의 설치 명령으로 바꿉니다. |
\n)으로 이어 적으면 위에서부터 차례로 실행됩니다. 예: "setup": "npm ci\nnpm run db:migrate" — 설치한 다음 데이터베이스 준비 명령을 실행.setup · teardown 자세히, 명령 안에서 쓸 수 있는 값
teardown은 반대쪽 정리 명령입니다. 워크스페이스를 보관(archive)할 때, 폴더가 지워지기 전에 실행됩니다. 예:"teardown": "npm run db:drop || true".- 두 항목 모두 여러 줄 셸 스크립트(터미널 명령을 여러 줄 적은 것)나 명령 배열로 적을 수 있고, 어느 쪽이든 차례로 실행됩니다.
- 명령은 새 워크트리 폴더를 현재 위치로 해서 실행됩니다. 원본 폴더에 있는 파일(Git에 없는 설정, 캐시 등)이 필요하면
$PASEO_SOURCE_CHECKOUT_PATH로 원본 폴더 위치를 가리킵니다. - setup·teardown·스크립트·서비스에서 공통으로 쓸 수 있는 값:
$PASEO_SOURCE_CHECKOUT_PATH(원본 저장소 맨 위),$PASEO_WORKTREE_PATH(워크트리 폴더),$PASEO_BRANCH_NAME(워크트리의 브랜치),$PASEO_WORKTREE_PORT(예전 방식의 워크트리별 포트 — 서비스 안에서는$PASEO_PORT를 권장). - 이미 있는 파일을 옮기는 일은
.worktreeinclude에, 설치·파일 생성·비밀 값 받아 오기처럼 "실행해야 하는 일"은 setup에 둡니다.
성공 표시 — 저장소 맨 위에 paseo.json이 있고, setup에 내 프로젝트의 설치 명령이 적혀 있습니다.
3단계 · 개발 서버를 서비스로 등록하기 (웹 프로젝트일 때)
워크트리마다 파일은 따로지만 포트는 컴퓨터 한 대가 함께 씁니다. 그래서 워크트리 두 개에서 개발 서버(만드는 중인 웹 화면을 내 컴퓨터에서 띄워 보는 프로그램)를 같은 포트 번호로 띄우면 겹칩니다. paseo.json의 scripts에 서버를 서비스로 등록하면 Paseo가 워크트리마다 다른 포트를 정해 줍니다.
$PASEO_PORT("Paseo가 정해 준 포트")를 넘기는 것이 요점입니다.2단계의 파일에 scripts 묶음을 더합니다.
paseo.json
{
"worktree": {
"setup": "npm ci"
},
"scripts": {
"test": { "command": "npm test" },
"web": {
"type": "service",
"command": "npm run dev -- --port $PASEO_PORT"
}
}
}
| 줄 | 뜻 |
|---|---|
"scripts": { … } | 워크트리 안에서 필요할 때 골라 실행하는 "이름 붙인 명령" 모음입니다. |
"test": { "command": "npm test" } | test라는 이름으로 npm test(테스트 실행)를 등록합니다. 한 번 돌고 끝나는 보통 스크립트입니다. |
"web": { … } | web이라는 이름의 스크립트입니다. 이름은 나중에 주소에 쓰입니다. |
"type": "service" | 이 스크립트가 서비스라는 표시입니다. Paseo가 계속 켜 두는 프로그램으로 관리하고, 포트를 정해 주고, 데몬(내 컴퓨터에서 계속 켜져 에이전트와 워크스페이스를 맡아 돌리는 Paseo의 본체)을 거쳐 접속할 주소를 만들어 줍니다. |
"command": "npm run dev -- --port $PASEO_PORT" | 개발 서버를 실행하되 포트는 Paseo가 정해 준 번호를 쓰라는 뜻입니다. 포트를 넘기는 방법(--port)은 프로젝트마다 다를 수 있습니다. |
"port": 3000을 적어 번호를 직접 정할 수도 있습니다. 직접 적은 번호는 다른 어떤 설정보다 우선합니다. 워크트리 여러 개를 함께 띄울 생각이라면 적지 않는 편이 안전합니다.터미널 자동으로 열기 · 포트 범위 정하기 · 서비스끼리 주소 알기
터미널 자동으로 열기. 워크트리가 만들어질 때 터미널을 미리 열어 둡니다. 로그(프로그램이 남기는 진행 기록)를 계속 보여 주거나 바로 명령을 칠 수 있게 해 둘 때 씁니다.
{
"worktree": {
"terminals": [
{ "name": "logs", "command": "tail -f dev.log" },
{ "name": "shell", "command": "bash" }
]
}
}
name은 터미널 이름, command는 그 터미널에서 처음 실행할 명령입니다.
포트 범위. 기본은 운영체제에 "비어 있는 포트"를 물어 받습니다. 범위를 정하려면 전체 설정 ~/.paseo/config.json의 worktrees.servicePorts나 프로젝트 paseo.json의 worktree.servicePorts에 { "range": "3000-4000" }처럼 적습니다. 범위는 양 끝 번호를 포함합니다. 프로젝트에 적은 묶음이 전체 설정 묶음을 통째로 대신하고, 서비스에 직접 적은 port가 언제나 가장 우선합니다.
포트를 정해 주는 프로그램 쓰기. "servicePorts": { "portScript": "/usr/bin/portmake" }처럼 적으면 Paseo가 그 실행 파일을 워크스페이스 폴더에서 네 가지 값(서비스 이름, 워크스페이스 ID, 브랜치 이름, 워크트리 경로)과 함께 실행하고, 출력된 포트 번호 하나를 씁니다. 같은 값은 PASEO_SCRIPTNAME·PASEO_WORKSPACE_ID·PASEO_BRANCH_NAME·PASEO_WORKTREE_PATH로도 전달됩니다. 셸을 거치지 않고 바로 실행하므로 한 줄짜리 셸 명령이 아니라 실제 실행 파일이어야 합니다. 같은 묶음 안에서는 portScript가 range보다 우선하며, Paseo는 돌려받은 번호가 비어 있는지 따로 확인하지 않습니다.
서비스끼리 주소 알기. 같은 워크스페이스에서 띄운 서비스는 서로의 포트와 주소를 값으로 받습니다. web과 api가 있다면 각 프로그램이 PASEO_PORT·PASEO_URL(자기 것)과 PASEO_SERVICE_API_PORT·PASEO_SERVICE_API_URL·PASEO_SERVICE_WEB_PORT·PASEO_SERVICE_WEB_URL을 받습니다. 스크립트 이름은 대문자로 바뀌고 영문자·숫자가 아닌 글자는 _가 됩니다. 화면 쪽 코드가 API 주소를 고정해 두지 말고 $PASEO_SERVICE_API_URL을 보게 합니다. 서비스는 추가로 $HOST도 받습니다 — 데몬이 내 컴퓨터 안에서만 열려 있으면 127.0.0.1, 모든 네트워크에 열려 있으면 0.0.0.0.
성공 표시 — paseo.json에 web 서비스가 있고, 그 명령에 포트 번호 대신 $PASEO_PORT가 들어 있습니다.
4단계 · 두 파일을 커밋하기 — 가장 많이 빠뜨리는 단계
두 파일은 읽히는 곳이 다릅니다. 이 차이를 모르면 "분명히 고쳤는데 안 먹는다"는 일이 생깁니다.
paseo.json은 저장만 해서는 안 되고, 새 워크트리의 출발점으로 고를 브랜치에 커밋(변경을 Git 이력에 기록하는 것)되어 있어야 합니다.- 두 파일을 커밋하고 서버에 올립니다평소 쓰는 Git 방법으로 하거나 에이전트에게 맡깁니다. 예: "
.worktreeinclude와paseo.json두 파일만 커밋하고 서버의 main 에 올려(push) 줘. 커밋 메시지는 '워크트리 준비 설정 추가'. 끝나면 origin/main 에 paseo.json 이 들어 있는지 확인해 줘." 커밋만 하고 올리지 않으면origin/main에는 아직 없어서 5단계에서 setup 이 돌지 않습니다. - 출발점으로 고를 브랜치에 들어가게 합니다새 워크트리를
origin/main(서버에 있는 원본 줄기)에서 시작한다면, 이 커밋이 서버의 main에까지 올라가 있어야 Paseo가 읽습니다. 팀 저장소라면 PR(내 브랜치의 변경을 원본에 합쳐 달라는 요청)로 합칩니다. .env자체는 커밋하지 않습니다.worktreeinclude를 커밋하면 팀원도 같은 목록을 쓰게 됩니다. 복사될 파일의 내용은 Git에 올라가지 않고, 팀원은 각자 자기 원본 폴더에 자기.env를 둡니다.
성공 표시 — paseo.json이 새 워크트리의 출발점으로 고를 브랜치에 들어가 있습니다.
5단계 · 새 워크스페이스를 만들어 확인하기
- New workspace(새 워크스페이스)를 열고 프로젝트를 고릅니다Isolation(격리 — 파일을 어떻게 분리할지)을 New worktree로 두고, 시작 지점은 4단계에서 파일을 넣은 브랜치(예:
origin/main)로 고릅니다. - 에이전트와 모델을 고르고 확인용 과제를 보냅니다이 목록 아래의 예시 문장을 그대로 써도 됩니다.
- 직접 보고 싶으면 터미널을 엽니다Command Center(화면과 동작을 찾아 여는 창)에서 New terminal(새 터미널)을 열고
ls -a(숨김 파일까지 목록 보기)를 입력합니다. 목록에.env와node_modules가 보이면 복사와 설치가 모두 된 것입니다.
이 폴더에 .env 파일이 있는지, 의존성이 설치되어 있는지 확인해 줘. 그다음 테스트를 실행하고 결과를 세 줄로 알려 줘. 파일은 고치지 마.
- 파일은 원본 폴더에서와 같은 위치(같은 상대 경로)에 복사됩니다.
- 복사는 만들 때 한 번뿐입니다. 나중에 원본의
.env를 고쳐도 이미 만든 워크트리에는 따라오지 않습니다. - 새 워크트리에 같은 이름의 파일이 이미 있으면 건너뛰고 원래 내용을 지킵니다.
- 복사 중 오류가 나면 만들기를 멈추고 새 워크트리를 지웁니다.
성공 표시 — 새 워크트리에 .env가 있고, 손으로 설치하지 않았는데도 테스트가 실행됩니다.
명령으로 워크스페이스(New worktree 방식) 만들기 · 워크트리가 놓이는 곳
현재 폴더를 원본으로 삼아 기준 브랜치에서 새 브랜치로 갈라져 나오는 예입니다. 다른 폴더를 원본으로 쓰려면 --path ~/dev/my-app을 더합니다.
paseo workspace create \
--isolation worktree \
--mode branch-off \
--new-branch feature/auth \
--worktree-slug feature-auth \
--base origin/main
--isolation worktree워크트리로 분리 ·--mode branch-off기준에서 새 브랜치로 갈라짐 ·--new-branch새 브랜치 이름 ·--worktree-slug워크트리 폴더 이름 ·--base출발점.- 이미 있는 브랜치를 꺼내려면
--mode checkout-branch --branch feature/existing, PR 하나를 자기 워크스페이스로 열려면--mode checkout-pr --pr-number 2186. Paseo가 저장소 서비스 종류를 알아내지 못하면--forge <이름>을 더합니다. - 워크스페이스와 첫 에이전트를 한 번에:
paseo run --new-workspace worktree --worktree-mode branch-off --new-branch feature/auth --base origin/main "implement auth". - 관리:
paseo workspace ls(목록) ·paseo run --workspace <workspace-id> "…"(그 워크스페이스에서 에이전트 실행) ·paseo workspace rename <workspace-id> "이름"·paseo workspace archive <workspace-id>(보관). - 워크트리는 기본으로
$PASEO_HOME/worktrees/(보통~/.paseo/worktrees/) 아래, 원본 폴더 경로로 만든 짧은 식별 글자 폴더 안에tidy-fox같은 이름으로 놓입니다. 바탕 위치는config.json의worktrees.root로 바꿀 수 있습니다. - 워크스페이스를 보관하면, 그 워크트리를 쓰던 마지막 워크스페이스가 보관된 뒤 Paseo가 teardown을 실행하고 워크트리를 지웁니다.
6단계 · 서비스를 띄우고 주소로 열어 보기 (3단계를 했다면)
- 앱에서
web스크립트를 실행합니다등록한 스크립트는 앱에서 실행합니다. 에이전트에게 "web서비스를 실행해 줘"라고 맡길 수도 있습니다(자동화에서는paseo script명령과 Paseo tools의 스크립트 도구로 다룹니다). - 주소를 만듭니다서비스 주소는 정해진 규칙으로 만들어집니다. 아래 그림대로 스크립트 이름·브랜치·프로젝트 이름을
--로 잇습니다. 데몬 포트는 따로 바꾸지 않았다면6767입니다. 주소를 모르겠으면 에이전트에게 "web 서비스를 실행하고 접속 주소를 알려 줘"라고 물어봅니다. - New browser(새 브라우저)에 그 주소를 넣습니다화면이 뜨면 성공입니다. New worktree 로 만든 다른 워크스페이스에서도 같은 순서로 띄워, 두 화면이 동시에 열리는지 봅니다.
http://<스크립트>--<브랜치>--<프로젝트>.localhost:<데몬 포트>. 기본 브랜치에서는 브랜치 부분이 빠집니다. *.localhost는 요즘 시스템에서 내 컴퓨터를 가리키므로 따로 설정할 것이 없습니다.성공 표시 — 워크트리 두 곳에서 같은 web 서비스를 동시에 띄워도 둘 다 열립니다.
에이전트가 이 화면을 직접 열어 확인하게 하는 방법은 실습 3과 완전 가이드 6장 · 브라우저에 있습니다.
막히면
| 증상 | 먼저 확인할 것 → 해결 |
|---|---|
새 워크트리에 .env가 없음 | ① 원본 폴더에 그 파일이 실제로 있는지 ② 그 파일을 Git이 무시하고 있는지(.gitignore) ③ .worktreeinclude가 워크트리를 만들어 내는 폴더의 맨 위에 있는지 ④ 내장 플러그인(기능을 더해 주는 부속 프로그램) worktree-include가 켜져 있는지 차례로 봅니다. 이 파일이 없으면 아무것도 복사하지 않습니다. |
원본의 .env를 고쳤는데 워크트리에는 옛 내용 | 정상입니다. 복사는 만들 때 한 번뿐이고 계속 맞춰 주지 않습니다. 워크트리의 파일을 직접 고치거나 워크스페이스를 새로 만듭니다. |
| 워크트리 만들기가 실패하고 사라짐 | 복사 오류는 만들기를 멈추고 새 워크트리를 지웁니다. 폴더를 가리키는 바로가기(심볼릭 링크) 폴더나 안에 다른 저장소가 든 폴더는 파일처럼 복사할 수 없으니 .worktreeinclude에서 뺍니다. |
paseo.json을 고쳤는데 setup이 그대로 | 고른 기준 브랜치의 커밋된 버전만 읽습니다. 커밋했는지, 그 커밋이 시작 지점으로 고른 브랜치에 들어가 있는지 봅니다(4단계). |
| setup에서 원본 폴더의 파일을 못 찾음 | setup은 새 워크트리 폴더 안에서 실행됩니다. 원본 폴더의 파일은 $PASEO_SOURCE_CHECKOUT_PATH로 가리킵니다. |
| 두 워크트리의 개발 서버가 포트 때문에 충돌 | 명령에 포트 번호가 고정되어 있는지 봅니다. $PASEO_PORT를 넘기도록 바꾸고, 서비스의 "port" 고정값은 지웁니다(3단계). |
| 새 워크트리가 예전 코드에서 시작함 | 출발점을 main이 아니라 origin/main으로 고릅니다. Paseo는 서버 쪽 브랜치 정보를 뒤에서 받아 오므로 origin/main은 최신이지만, 내 컴퓨터의 main은 마지막으로 받아 온 때의 상태입니다. |
설정 파일을 고쳤는데 반영되지 않는 다른 경우와 에이전트가 보이지 않는 문제는 실습 10에서 다룹니다.
- 새 워크트리에는 Git이 관리하는 파일만 있습니다.
.env와 설치한 의존성은 따로 채워야 합니다. .worktreeinclude= 복사할 파일 목록. Git이 이미 무시하는 파일만 고를 수 있고, 만들 때 한 번 복사됩니다.paseo.json의setup= 만든 직후 한 번 도는 명령. 복사가 끝난 뒤에 실행됩니다.paseo.json은 출발점으로 고른 브랜치에 커밋되어 있어야 읽힙니다.- 개발 서버는 서비스로 등록하고
$PASEO_PORT를 쓰면 워크트리마다 다른 포트로 뜹니다.
출처: paseo.sh/docs/worktrees (worktrees.md) · paseo.sh/docs/worktrees/worktreeinclude (worktrees_worktreeinclude.md) · paseo.sh/docs/parallel-development (parallel-development.md) · 데몬 기본 포트는 paseo.sh/docs/connectivity (connectivity.md) — Paseo 0.15.3 · 수집일 2026-11-09
막혔을 때 — 에이전트가 안 보임 · 설정이 안 먹힘 · 연결 실패
가장 자주 막히는 세 가지를 "증상 → 먼저 확인할 것 → 해결" 순서로 풉니다. 이것저것 눌러 보기 전에 무엇을 먼저 봐야 하는지, 그리고 Paseo가 남긴 기록(로그)을 어떻게 읽는지 익힙니다.
- 설치한 에이전트가 Not installed(설치 안 됨)로 나올 때, Paseo가 무엇을 보고 있는지 확인하고 고칩니다.
- 설정 파일을 고쳤는데 그대로일 때, 다시 읽게 하고 결과 메시지를 읽습니다.
- 연결이 안 될 때, 오류 문구를 보고 어디서 막혔는지 가려냅니다.
- 로그(프로그램이 남기는 진행 기록) 파일이 어디 있고 어느 줄을 봐야 하는지 압니다.
준비물을 갖추고 → 따라 하기에서 내 증상의 탭 하나만 고릅니다. 원인이 궁금하면 왜 터미널에서는 되는데 Paseo에서는 안 될까, 더 파고들려면 로그 읽는 법을 봅니다. 세 증상에 없으면 막히면으로 갑니다.
준비물
- 새로 연 터미널(글자로 명령을 입력하는 창) 하나. 전부터 열려 있던 창이 아니라 방금 새로 연 창이어야 합니다. 이유는 아래에서 설명합니다.
- 데몬(내 컴퓨터나 서버에서 계속 켜져 에이전트와 워크스페이스를 맡아 돌리는 Paseo의 본체 프로그램)이 도는 컴퓨터를 만질 수 있을 것. 증상 ①·②는 그 컴퓨터에서 확인합니다.
- 화면에 나온 문구를 그대로 적어 둘 것. "Not installed", "Connection refused"처럼 정확한 문구가 어느 갈래인지 알려 줍니다.
paseo명령이 되는지. 증상 ②·③은 터미널에서paseo명령을 씁니다. 터미널에서paseo를 쳤을 때command not found(명령을 찾을 수 없음)가 나오면 CLI 가 없는 것입니다 —npm install -g @getpaseo/cli로 설치합니다(완전 가이드 1장 · 8장).
paseo reload는 아무 문제가 없을 때도 연습 삼아 해 볼 수 있습니다(reload는 데몬을 저절로 재시작하지 않습니다). 정상일 때의 모습을 한 번 봐 두면 고장 났을 때 차이가 바로 보입니다.따라 하기 — 증상별
증상 ① 에이전트가 안 보임
Paseo는 에이전트를 품고 있지 않습니다. 내가 설치해 둔 에이전트 CLI를 찾아서 실행합니다. 찾는 곳은 Paseo 자신의 PATH(명령을 찾으러 뒤지는 폴더 목록)입니다. 내 터미널의 PATH에는 있는데 Paseo의 PATH에는 없으면 이 증상이 납니다.
먼저 확인할 것
- 새 터미널에서 명령을 찾아봅니다macOS·Linux:
which -a claude(Codex라면which -a codex) · Windows:where.exe codex. 경로가 한 줄 이상 나오면 설치는 된 것이니 2번으로 갑니다. 아무것도 안 나오면 설치부터 다시 합니다(시작 전 준비). - Paseo가 보는 것을 엽니다Settings → your host → Providers(설정 → 내 호스트 → 프로바이더)에서 그 프로바이더를 누르고 Diagnostic(진단)을 누릅니다. 아래 그림의 세 줄을 읽습니다.
- 두 PATH를 비교합니다새 터미널에서
echo $PATH(내 터미널의 폴더 목록 보기)를 입력해, 화면의 Daemon PATH와 견줍니다. 1번에서 나온 경로의 폴더가 Daemon PATH에 없으면 원인을 찾은 것입니다.
not found이고 Daemon PATH에 내 프로그램의 폴더가 없는 것이 가장 흔한 경우입니다.해결
- 오래가는 방법 — 셸 설정을 고칩니다그 명령이 평범한 로그인 셸(컴퓨터에 로그인할 때처럼 설정 파일을 처음부터 읽고 시작하는 터미널 환경)의
PATH에 들어가도록 셸 설정 파일(.zshrc,.zprofile등)을 고친 뒤 Paseo를 다시 시작합니다. asdf·mise·nvm 같은 버전 관리 도구로 설치한 프로그램이 흔한 원인입니다 — 이미 열어 둔 터미널 안에서만이 아니라 깨끗한 로그인 셸에서도 준비되게 해야 합니다. - 바로 고정하는 방법 — 위치를 직접 알려 줍니다
~/.paseo/config.json에 프로그램의 전체 경로를 적습니다(아래 「개발자용 참고」). 고친 뒤에는 증상 ② 탭대로paseo reload를 실행합니다. - Codex만 안 보인다면ChatGPT 데스크톱 앱과 Codex CLI는 따로 설치하는 것입니다. 앱을 깔았다고
codex명령이 생기지 않습니다. ① Codex CLI 설치(npm install -g @openai/codex) ② 로그인(codex login) ③ 설치할 때 데몬이 이미 돌고 있었다면 Paseo 다시 시작 ④ Settings → Providers → Codex(설정 → 프로바이더 → Codex)에서 Refresh(새로 고침)를 누릅니다. 이 경로는 위의 Settings → your host → Providers 와 같은 곳입니다 — 원문 표기가 둘입니다.
성공 표시 — Diagnostic의 Resolved path에 경로가 나오고 Version이 보이며, 프로바이더를 고를 수 있게 됩니다.
config.json에 프로그램 위치 직접 적기 · 명령으로 진단 보기
~/.paseo/config.json
{
"agents": {
"providers": {
"claude": {
"command": ["/absolute/path/to/claude"]
}
}
}
}
| 줄 | 뜻 |
|---|---|
"agents" → "providers" → "claude" | "에이전트 설정 중, 프로바이더 중, claude에 대한 것"이라는 주소입니다. |
"command": ["/absolute/path/to/claude"] | 이 프로바이더를 실행할 때 쓸 명령입니다. [프로그램, 옵션…] 모양이며 기본 실행 명령을 통째로 대신합니다. 따옴표 안을 1번에서 찾은 실제 경로로 바꿉니다. |
- 실제 경로는
which -a claude로 찾습니다.type -a claude를 치면claude가 별명(alias)이나 셸 함수뿐인지도 알려 줍니다 — 그런 것은 쓸 수 없습니다. Paseo는 프로그램 파일을 직접 실행하므로, 별명이 가리키는 실제 경로를 적습니다. - 파일에 다른 설정이 이미 있으면 지우지 말고 이 부분만 더합니다.
- 명령으로 같은 진단 보기:
paseo provider diagnostic <provider>. 기본(내 컴퓨터) 데몬이 아닌 다른 데몬을 볼 때는paseo --host <host:port> provider diagnostic <provider> --json처럼--host를 명령 앞에 둡니다. - 다른 접속 주소·여러 프로필·직접 만든 실행 파일 같은 더 깊은 설정은 완전 가이드 3장 · 에이전트 고르기에서 다룹니다.
증상 ② 설정이 안 먹힘
config.json을 고치고 저장했는데 Paseo가 예전대로 움직입니다.파일을 저장하는 것만으로는 반영되지 않습니다. 데몬에게 다시 읽으라고 해야 합니다. 그리고 설정에는 켜진 채로 바꿔도 되는 것과, 데몬을 다시 시작해야 바뀌는 것이 있습니다. 어느 쪽인지는 Paseo가 알려 줍니다.
먼저 확인할 것
- 다시 읽게 합니다터미널에
paseo reload를 입력합니다. 데몬은 파일 전체를 먼저 검사한 다음에 적용합니다. - 결과 메시지를 읽습니다아래 그림의 네 갈래 중 어느 것인지 봅니다.
paseo reload의 결과는 네 갈래입니다. 갈래마다 다음에 할 일이 정해져 있습니다. 자세히: 완전 가이드 8장 · 설정과 CLI해결 — 갈래별
| reload가 알려 준 것 | 할 일 |
|---|---|
| 적용되었다 | 끝입니다. 켜진 채로 바꿔도 안전한 설정은 바로 반영됩니다. |
| 재시작이 필요한 설정 이름이 나옴 | 데스크톱 앱을 쓰고 있다면 Settings → your host → Overview(설정 → 내 호스트 → 개요)의 Restart daemon(데몬 다시 시작)을 누릅니다. 터미널에서는 paseo daemon restart를 실행합니다. 돌고 있던 에이전트는 계속 돌고, 앱은 저절로 다시 연결됩니다. |
| JSON(중괄호·따옴표·쉼표로 적는 설정 표기)이 잘못됐거나 형식 오류 | 아무것도 적용되지 않습니다(맞게 쓴 다른 줄도 포함). 알려 준 오류를 고치고 paseo reload를 다시 실행합니다. 쉼표·따옴표·괄호 짝을 먼저 봅니다. |
| 데몬을 켤 때 따로 준 값(환경 변수(프로그램을 띄울 때 함께 넘겨주는 이름 붙은 값)나 옵션)이 파일보다 우선해서 파일 값이 무시된다고 나옴 | 파일의 값이 먹히지 않는 상태입니다. 그 환경 변수·옵션 없이 데몬을 다시 띄워야 파일의 값이 기준이 됩니다. |
paseo reload, 그 결과가 재시작을 말할 때만 재시작합니다(앱의 Restart daemon 또는 paseo daemon restart).성공 표시 — paseo reload가 오류 없이 끝나고, 재시작을 요청했다면 재시작까지 한 뒤 바뀐 설정대로 움직입니다.
어떤 설정이 바로 적용되고 어떤 설정이 재시작을 요구하나 · 명령으로 설정 고치기
| 바로 적용 (reload만) | 재시작 필요 |
|---|---|
| 릴레이 켜기·끄기, MCP 설정, 브라우저 도구, 호스트 이름, CORS 출처, 신뢰하는 프록시, Git 프로세스 한도, 에이전트·터미널 프로필, 프로바이더 정의, 메타데이터 생성, 앱 기본 주소, 프로바이더 목록 시간 제한, 전체 플러그인 스위치 | 쉬는 런타임 정리, 접속을 받는 주소(listen), 인증, 릴레이 접속 주소와 TLS, 워크트리 배정, 서비스 프록시 주소, 내장 웹 화면, 로깅, 음성(말하기·듣기), 자격 증명, 로컬 모델 설정 |
- 재시작이 필요한 항목이 섞여 있어도, reload는 같은 파일의 다른 올바른 수정은 먼저 적용한 뒤 재시작이 필요한 항목을 알려 줍니다.
- 데몬을 켤 때 준 값에 밀려 무시된 설정은 결과의
overrideControlledPaths항목에 나옵니다. - 파일을 직접 열지 않고 명령으로 고칠 수도 있습니다:
paseo daemon config get daemon.listen(값 보기) ·paseo daemon config set daemon.listen 127.0.0.1:6800(값 정하기) ·paseo daemon config unset features.webUi.enabled(값 지우기). 다른 홈 폴더를 쓰면 뒤에--home ~/paseo-test처럼 붙입니다. - 이 명령은 검사를 통과한 파일을 저장한 뒤 데몬에 닿으면 한 번 reload합니다. 데몬이 꺼져 있거나 닿지 않으면 saved; not applied(저장됨, 적용 안 됨), reload가 실패하면 saved; reload failed(저장됨, 다시 읽기 실패)라고 알려 줍니다. 어느 경우에도 저절로 재시작하지는 않습니다.
- 모르는 설정 이름, 잘못된 값, 이미 깨져 있는 파일은 쓰지 않고 거절합니다. 비밀번호는
set-password로 따로 정합니다.
증상 ③ 연결 실패
연결 방식은 세 가지입니다 — SSH(다른 컴퓨터에 안전하게 접속하는 표준 방법), 릴레이(relay — 폰과 데몬 사이를 이어 주는 중계 서버), Tailscale(내 기기들끼리만 통하는 사설 네트워크를 만들어 주는 서비스) 직접 연결. 어느 방식인지와 화면의 문구를 알면 볼 곳이 정해집니다.
먼저 확인할 것
- 데몬이 켜져 있는지 봅니다데몬이 도는 컴퓨터에서
paseo daemon status를 입력합니다. 꺼져 있으면 어떤 연결 방식도 통하지 않습니다. SSH 연결은 원격 컴퓨터에 Paseo를 설치하거나 데몬을 대신 켜 주지 않습니다. - 오류 문구를 아래 표에서 찾습니다증상과 문구가 곧 막힌 위치입니다.
해결 — 문구별
| 증상 · 화면의 문구 | 먼저 확인할 것 | 해결 |
|---|---|---|
| SSH authentication failed SSH 인증 실패 | 터미널에서 ssh user@host가 되는지 | 거기서 열쇠(key), SSH 에이전트, 호스트 키, ~/.ssh/config 항목을 고칩니다. Paseo는 SSH 비밀번호를 묻지 않으므로 비밀번호 없이 접속되는 상태여야 합니다. |
| SSH는 붙는데 Paseo가 거절됨 (refused) | 원격 컴퓨터에서 paseo daemon status | 원격 컴퓨터에서 데몬을 켭니다. SSH 연결은 데몬을 대신 시작해 주지 않습니다. |
| SSH는 붙는데 "Password required" 비밀번호 필요 | 원격 데몬에 비밀번호가 걸려 있는지 | 그 호스트에서 SSH 연결을 지우고 다시 추가하면서(Settings → Add host → Remote SSH) Daemon password(데몬 비밀번호) 칸에 비밀번호를 넣습니다. |
| Connection timed out 연결 시간 초과 | 두 기기 모두 Tailscale이 연결되어 있는지 | 양쪽에서 Tailscale을 연결하고, 입력한 주소가 데몬 컴퓨터의 Tailscale IP가 맞는지 봅니다(데몬 컴퓨터에서 tailscale ip -4). |
| Connection refused 연결 거절 | paseo daemon status | 데몬이 설정한 IP와 포트에서 돌고 있는지 확인합니다. 주소나 포트가 다르면 맞춥니다. |
| 설정을 바꿨는데 그대로 | paseo reload를 했는지 | 실행하고 결과를 봅니다. daemon.listen(접속을 받는 주소)은 시작할 때 정해지는 설정이라, reload가 알려 주면 재시작합니다 — 증상 ② 탭과 같습니다. |
성공 표시 — 오류 문구가 사라지고, 연결한 기기에서 그 호스트(데몬이 돌아가는 컴퓨터)에 붙어 평소처럼 쓸 수 있습니다.
원격 데몬 상태를 내 컴퓨터에서 보기 · SSH 주소 적는 법
paseo daemon status는 내 컴퓨터의 기본 데몬을 봅니다. 원격 데몬을 보려면paseo --host ssh://user@host daemon status처럼--host를 명령 앞에 둡니다.- 원격 데몬은 그 컴퓨터의
127.0.0.1:6767에 있다고 봅니다. SSH 주소의:2222같은 숫자는 SSH 서버의 포트입니다. 데몬 포트가 다르면'ssh://user@host?daemonPort=7777'처럼 따로 적습니다. - 앱의 Settings → Add host → Remote SSH에도 같은
ssh://주소를 넣습니다. - Tailscale 직접 연결은 폰에서 Settings → Add host → Direct connection(직접 연결)에 Tailscale IP와 포트
6767을 넣고 Use SSL은 끈 채 Connect를 누릅니다.
왜 터미널에서는 되는데 Paseo에서는 안 될까
증상 ①의 뿌리입니다. 같은 까닭으로 Paseo 안의 에이전트나 터미널이 매일 쓰던 도구를 두고 command not found(명령을 찾을 수 없음)라고 할 때도 있습니다. 프로그램은 자기를 띄워 준 쪽에서 환경(PATH를 비롯해 프로그램이 물려받는 설정 값 묶음)을 물려받는데, 그 출발점이 다르기 때문입니다.
- 고칠 곳은 Paseo가 아니라 셸 설정 파일(
.zshrc,.zprofile등)입니다. 어느 경로로 띄웠든 마찬가지입니다. - 시험 방법은 하나입니다 — 터미널을 새로 열어 그 명령을 쳐 봅니다. 준비물에서 "새로 연 터미널"을 고집한 이유입니다. 전부터 열려 있던 창은 그 뒤에 손으로 더한 설정을 품고 있어 판단을 흐립니다.
- 셸 설정 파일이 느리거나 중간에 오류를 내면 로그인 셸 단계가 실패할 수 있습니다. 실패했는지는 다음 절의 로그로 확인합니다.
로그 읽는 법
로그는 두 군데에 남습니다. 데스크톱 앱의 로그에는 위 그림의 "로그인 셸 한 번 실행"이 잘됐는지가 적히고, 데몬의 로그에는 데몬이 한 일이 적힙니다.
| 무엇의 로그 | 운영체제 | 파일 위치 |
|---|---|---|
| 데스크톱 앱 | macOS | ~/Library/Logs/Paseo/main.log |
| Linux | ~/.config/Paseo/logs/main.log | |
| Windows | %APPDATA%\Paseo\logs\main.log | |
| 데몬 | 공통 | ~/.paseo/daemon.log — 홈 폴더를 따로 정했다면 $PASEO_HOME/daemon.log |
- 데스크톱 앱 로그에서 표시 줄을 찾습니다macOS 예:
grep "login-shell-env" ~/Library/Logs/Paseo/main.log— "이 파일에서login-shell-env가 들어간 줄만 보여 줘"라는 뜻입니다. Linux는 파일 위치만 위 표대로 바꿉니다. - 줄에 적힌 말을 읽습니다
applied면 성공,failed; keeping inherited env면 실패입니다. 아래 그림과 견줍니다. - 데몬 쪽이 궁금하면 끝부분을 봅니다
tail -n 50 ~/.paseo/daemon.log— "이 파일의 마지막 50줄을 보여 줘"라는 뜻입니다. 문제가 난 직후에 보면 관련된 줄이 끝에 있습니다.
failed가 보이면 느리거나 오류를 내는 .zshrc·.zprofile이 보통 원인입니다. 그 파일을 고친 뒤 Paseo를 다시 시작하고 같은 줄을 다시 찾아봅니다.막히면 — 세 증상에 없을 때
| 증상 | 먼저 확인할 것 → 해결 |
|---|---|
| Linux에서 AppImage(Linux용 실행 파일 한 개짜리 배포 형식)가 열리지 않음 | 받은 파일에 실행 권한을 주고 터미널에서 실행해 오류를 봅니다: chmod +x Paseo-x86_64.AppImage 다음 ./Paseo-x86_64.AppImage. error loading libfuse.so.2가 나오면 ./Paseo-x86_64.AppImage --appimage-extract-and-run으로 실행합니다. Debian·Ubuntu는 .deb, Fedora는 .rpm을 내려받기 페이지에서 받아 설치해도 됩니다. |
Paseo 안의 에이전트·터미널이 평소 쓰던 명령을 command not found라고 함 | 증상 ①과 같은 원인입니다. 새 터미널에서 그 명령이 되는지 보고, 안 되면 셸 설정 파일을 고칩니다 → 왜 터미널에서는 되는데… |
| 재시작하면 돌던 에이전트가 끊길까 걱정됨 | 데몬을 다시 시작해도 돌고 있던 에이전트는 계속 돌고, 앱은 저절로 다시 연결됩니다. |
| 위 방법으로도 안 됨 | 증상, 화면의 문구, 로그에서 찾은 줄을 모아 Paseo 이슈 게시판에 알립니다. 올리기 전에 로그에 비밀 값이 섞여 있지 않은지 살펴봅니다. |
- 에이전트가 안 보임 → 새 터미널에서
which -a로 찾아보고, Diagnostic의 Resolved path·Daemon PATH·Version을 읽습니다. 고칠 곳은 셸 설정 파일입니다. - 설정이 안 먹힘 →
paseo reload를 실행하고 결과를 읽습니다. 재시작은 reload가 요청할 때만 합니다. - 연결 실패 →
paseo daemon status로 데몬부터 확인하고, 오류 문구로 막힌 위치를 가려냅니다. - 판단 기준은 하나 — 새로 연 터미널에서 되는 명령이면 Paseo에서도 되어야 합니다.
- 로그는 데스크톱 앱의
main.log([login-shell-env]줄)와 데몬의~/.paseo/daemon.log에 있습니다.
출처: paseo.sh/docs/troubleshooting (troubleshooting.md) · paseo.sh/docs/connectivity (connectivity.md) · paseo.sh/docs/configuration (configuration.md) · paseo.sh/docs/codex (codex.md) · CLI 설치는 paseo.sh/docs (home.md) — Paseo 0.15.3 · 수집일 2026-11-09