Paseo 공식 가이드 - 설정과 작업 조율

  • 확인일: 2026-09-26
  • 문서 기준: 공식 웹 문서(https://paseo.sh/docs)를 바탕으로 정리한다. 웹 문서는 특정 설치 버전에 고정된 자료가 아니므로, 공식 기능 설명과 실제 실행 환경의 보장을 구분하여 서술한다.

제공자와 Paseo 역할

Paseo는 모델이나 코딩 에이전트 CLI 자체가 아니다. 시스템에 설치되고 인증된 외부 코딩 CLI나 Agent Client Protocol(ACP) 에이전트를 실행하고 감독하는 UI·CLI·조율 계층이다(Getting started, Providers).

공식 문서의 기본 내장(native) 지원 대상은 Claude Code, Codex, OpenCode, pi 등이다. ACP를 통해서는 Cursor, Gemini, Copilot 등을 연결할 수 있다(Providers). 문서의 native support는 Paseo가 제공하는 어댑터를 의미한다. 외부 CLI가 자체적으로 실행하는 하위 에이전트의 내부 생명주기가 Paseo 작업자와 동일하게 관리되는지는 문서에서 확인되지 않는다(Providers).

Paseo 조율 인터페이스는 CLI, TypeScript SDK, MCP 도구로 나뉜다(CLI reference, SDK Reference, MCP reference). 이 세 경로는 별개로 동작하는 시스템이 아니라 동일한 데몬을 제어하는 접근 경로다. MCP는 에이전트에게 조율 도구를 전달할 때 사용하고, CLI는 터미널이나 스크립트에서 명령을 실행할 때 쓰며, SDK는 애플리케이션 코드가 데몬 API를 직접 호출할 때 사용한다.

작업 공간·프로필·위임

작업 공간(Workspace)은 세션, 터미널, 브라우저가 모이는 논리적 작업 단위다(Workspaces). 작업 공간 분리만으로 파일 격리가 보장되지는 않는다. local 유형의 작업 공간은 동일한 호스트 디렉터리를 가리킬 수 있으며, 이 경우 파일 변경 사항을 함께 공유한다(Workspaces).

독립된 디렉터리와 브랜치가 필요하면 Git worktree를 사용한다(Git worktrees). worktree는 별도 디렉터리, 브랜치, 포트를 제공한다. worktree 설정은 커밋된 베이스 브랜치(origin/main 권장)에서 읽어온다. 다만 여러 작업 공간이 하나의 worktree를 함께 바라보도록 지정할 수 있으며, 이 경우 해당 작업 공간들은 파일을 공유한다(Workspaces, Git worktrees). 새로 생성된 worktree는 셋업 스크립트가 실행되기 전까지 의존성이나 .env 파일이 없다(Git worktrees). 에이전트는 호스트 사용자의 자체 자격증명으로 실행된다(Security). worktree는 이를 사용하는 마지막 작업 공간이 보관(archive)된 후 teardown 절차를 거쳐 정리된다(Git worktrees).

프로필(Agent Profile)은 호스트에 저장하는 제공자, 모델, 실행 모드, 추론(thinking), 기능 설정(feature settings)의 묶음이다(Agent profiles). 도구 제한 목록(paseoTools, disabledTools)은 프로필이 아니라 제공자 설정에 위치한다(MCP reference). 프로필의 When to use 메모는 작업자 선택을 돕는 안내문이며, 실제 작업 내용은 에이전트 생성 시 전달하는 프롬프트로 지정한다(Agent profiles). 프로필을 변경하면 이후 해당 프로필을 새로 선택할 때 적용되며, 이미 실행 중인 에이전트는 갱신하지 않는다(Agent profiles).

지침·설정·권한의 적용

CLI의 paseo daemon config set/unset으로 편집하면 검증된 파일을 저장하고, 데몬에 연결되면 한 번 리로드한다. 연결되지 않으면 saved; not applied, 리로드 실패 시에는 saved; reload failed와 0이 아닌 종료 코드를 반환한다. config.json을 직접 편집했다면 별도 리로드가 필요하다. 일부 항목은 데몬 재시작이 필요하므로 저장 결과와 실제 적용 결과를 나눠 확인한다(Configuration).

SDK의 systemPrompt는 세션 생성 시 전달하는 추가 system 또는 developer 지침으로 정의되어 있다(SDK Reference). 공식 설정 스키마에는 daemon.appendSystemPrompt 항목({"type":"string"})이 존재한다. 그러나 Configuration 설명 페이지에는 해당 항목이 문서화되어 있지 않다(Configuration). 이 설정이 지원되는 제공자의 범위, 신규 또는 기존 세션에 전달되는 방식, 즉시 반영 여부나 재시작 요구 여부는 확인한 공식 문서와 스키마만으로 확정할 수 없다.

실행 모드와 권한 옵션은 제공자별로 확인한다. modeId는 제공자 고유의 동작 모드를 지정하고, modeId와 options가 겹치면 options가 우선한다(SDK Providers, Provider options). OpenCode의 경우 options의 권한 규칙에 ask, allow, deny를 쓰며, ask는 Paseo의 권한 요청으로 연결된다(Provider options).

도구 카탈로그 제한은 셸을 통해 호스트에 접근할 수 있는 에이전트의 보안 경계가 아니다(MCP reference). 에이전트가 호스트 셸 실행 권한을 갖고 있다면 도구 노출 목록을 축소해도 호스트 자원 접근을 차단하지 못한다(MCP reference).

반복 실행과 연결 도구

반복 작업 메커니즘으로 Schedule과 Heartbeat가 있다(Schedules, MCP reference).

  • Schedule: Cron 주기마다 매번 독립된 새 에이전트를 시작한다(Schedules).
  • Heartbeat: 기존에 실행 중인 동일 에이전트 대화에 주기적으로 프롬프트를 전송한다(MCP reference). Heartbeat 생성 및 삭제는 MCP 도구로만 수행할 수 있으며, CLI는 주기 변경만 지원한다(Schedules, MCP reference).

Schedules 페이지는 CI 빌드가 통과할 때까지 한 에이전트가 계속 확인하는 용도를 소개한다. 해당 예시의 구현 방식을 Schedule이나 Heartbeat로 확정하지 않는다(Schedules).

에이전트가 다른 작업자를 실행할 때 Paseo 도구 주입이 필수는 아니다. 셸 접근 권한이 있는 에이전트는 CLI를 직접 실행하여 작업자를 시작할 수 있다(Orchestration). 도구를 주입하는 경우 제공자에 따라 내장 도구 인터페이스 또는 MCP를 통해 전달된다(Orchestration, MCP reference). 기본 설정에서 daemon.mcp.enabled는 true이지만 daemon.mcp.injectIntoAgents는 false이다(MCP reference). 도구 주입 설정을 변경한 경우 새 에이전트를 시작하거나 기존 에이전트를 리로드해야 반영된다(MCP reference).

브라우저 도구는 기본으로 꺼져 있으며 호스트마다 Settings나 config.json에서 켠다(Browser). 브라우저 도구는 신뢰할 수 있는 에이전트에 한해 활성화하도록 안내된다(Browser). 브라우저 탭은 연결된 Paseo 데스크톱 앱에서 호스팅되고 데몬은 호출을 전달한다(Browser). 프로토콜은 HTTP 및 HTTPS로 제한되며, 파일 업로드는 작업 공간 디렉터리 내부 파일로 한정된다(Browser). 오케스트레이션 스킬(Skills)은 호스트(데몬)가 시작될 때 최신 상태로 새로고침된다(Skills). 실행 중인 에이전트가 갱신된 스킬을 반영하는 시점은 문서에 기술되어 있지 않다.

공식 가이드만으로 확정하지 못한 범위

  1. daemon.appendSystemPrompt 세부 동작: 공식 스키마에 정의되어 있으나 공식 설명 페이지에는 문서화되어 있지 않다. 적용 대상 제공자, 신규 및 기존 세션 도달 범위, 실시간 반영 여부는 이 공식 설명만으로 확인하지 못했다.
  2. 외부 CLI 하위 프로세스 수명주기: 외부 코딩 도구가 자체적으로 구동하는 하위 에이전트 라이프사이클이 Paseo 작업자 수명주기와 연동되는지는 공식 문서에서 확인되지 않는다.
  3. 실행 중 에이전트의 스킬 갱신 반영 시점: 데몬 기동 시 스킬 새로고침은 문서화되어 있으나, 실행 중인 세션이 업데이트를 즉시 감지하는지는 문서에 기재되어 있지 않다.

설치본에서 확인한 공통 프롬프트

2026-09-26 메인이 확인한 Windows 설치본은 @getpaseo/desktop 0.9.2다. 실행파일은 C:/Users/aica_/AppData/Local/Programs/Paseo/Paseo.exe, 저장 설정은 C:/Users/aica_/.paseo/config.json에 있었다. C:/labs/paseo-lab은 설치 위치가 아니라 실험·작업 기록 폴더다.

설정의 daemon.appendSystemPrompt에는 메인이 실험 폴더의 delegation/main-start.md를 읽도록 하는 진입문이 저장돼 있었다. 설치본 resources/app.asar의 서버 코드에서도 이 값을 런타임에 변경 가능한 필드로 등록하고, 에이전트 시작 설정에 daemonAppendSystemPrompt로 합치는 경로를 확인했다. Codex의 developer 지침, Claude의 추가 system 지침, 플러그인 시작 설정에 세션별 systemPrompt와 함께 전달하는 코드가 있었다.

이 확인의 근거는 번들 내부 node_modules/@getpaseo/server/dist/server/server/ 아래 daemon-config-store.js의 런타임 변경 목록, bootstrap.js의 필드 변경 처리, agent/agent-manager.js의 applyDaemonAppendSystemPrompt, 제공자별 프롬프트 합성 코드다. 이번에 생성한 Antigravity 작업자의 실행 메타데이터에서도 저장된 진입문이 확인됐다. 코드를 읽고 전달값을 확인한 범위이며, 모든 제공자의 실제 준수나 이미 실행 중인 세션의 즉시 갱신을 시험한 결과는 아니다.

따라서 공통 프롬프트가 존재하는지와 그 프롬프트가 가리키는 운영 문서의 위치가 적절한지는 별도로 판단한다. DanzzaN은 실험 폴더를 상시 메인 지침의 위치로 삼은 점을 정정했고, 문서 이관·공통 규칙·개인사이트 최신화보다 공식 가이드 증류를 먼저 요청했다. 승인한 계획을 문서로 남겨 작업자도 보게 하려는 목적은 후속 정비의 기준이다. 이번 증류는 그 판단 근거를 정리하며, 새 운영 경로·프롬프트 개편·사이트 반영 주기를 확정하거나 설정을 변경한 결과는 아니다.

연결

백링크

그래프 뷰

이 문서로 이어지는 주제