Paseo를 사용하여 Claude Code와 Codex를 하나의 CLI로 통합 관리하는 방법

도입: AI 에이전트 도구의 난립으로 인한 관리 비용의 증가

Claude Code, OpenAI Codex, GitHub Copilot, Cursor…… 2025년 이후, 개발을 지원하는 AI 에이전트가 급격히 증가했습니다. 편리한 반면, 도구별 인증 전환, 워크트리(worktree) 충돌, 포트 중복 등 소규모 팀이나 개인 개발자의 운용은 의외로 번거롭습니다.

저희 코바야시 WEB 시스템에서도 Docker + Ollama의 로컬 LLM 환경을 자택 서버에서 운용하면서, Claude Code와 Hermes 에이전트를 일상적인 개발과 DX 추진에 활용하고 있습니다. 여러 에이전트를 오가는 과정에서 "하나의 명령어로 어떤 에이전트든 동일한 환경에서 실행할 수 없을까"라는 고민이 생겼습니다.

그래서 주목한 것이 Paseo입니다. Claude Code, Codex, Copilot, OpenCode, Pi 등을 단일 인터페이스에서 기동 및 관리할 수 있는 오픈소스 플랫폼으로, 로컬·VM·개발 서버 어디에서든 에이전트를 실행할 수 있습니다.

Paseo란

Paseo는 개발자가 여러 코드 생성 에이전트를 분산 인프라 상에서 포터블(portable)하게 운용하기 위한 오픈소스 프로젝트입니다.

프로바이더 비의존성: Claude Code, Codex, Cursor, OpenCode, Pi를 네이티브 하네스(native harness)로 실행하므로, 구독이나 설정은 각 프로바이더 측의 기능을 그대로 사용 -
어디서든 실행: 노트북·VM·개발 서버에서 에이전트를 기동하고, CLI·Web·모바일에서 접속 -
E2E 암호화 릴레이: 네트워크를 통해 접속하는 경우에도 엔드 투 엔드(end-to-end) 암호화로 전송 -
포트 경합 해소: 브랜치명 기반의 URL을 자동 생성하므로, 여러 에이전트를 병행 실행해도 포트 중복이 없음 -
완전 스크립트 가능: paseo run, paseo ls, paseo attach, paseo send 등 CLI를 통해 모든 조작을 자동화

설치 및 최소 설정

패키지 매니저를 통해 명령어 하나로 도입할 수 있습니다.

npm install -g @getpaseo/cli
paseo init

이렇게 하면 데몬(daemon)이 기동되어 동일 네트워크 내의 디바이스에서 조작할 수 있게 됩니다.

기본적인 CLI 조작

# 에이전트를 기동하여 태스크를 실행
paseo run "implement user authentication"
# 특정 프로바이더에서 worktree를 사용하여 실행
...

Docker로 Paseo를 상주시키기

자택의 Docker 환경에서 영속화할 경우, 컨테이너로서 데몬을 상주시키는 운용 방식이 적합합니다. 다음은 최소한의 docker-compose.yml 예시입니다.

version: "3.8"
services:
paseo:
...

npm install -g를 하지 않고 컨테이너 내부에서만 완결 짓고 싶은 경우에도 빌드의 발판이 됩니다. 다만 2026년 7월 현재, 공식 Docker 이미지의 유무나 권장 라벨은 획득한 정보에 따라 조정해 주십시오. Docker 내부에서 실행하는 경우에도 주요 조작은 모두 CLI로 처리할 수 있습니다.

Docker Compose로 여러 에이전트를 분리 기동

Paseo가 지원하는 worktree 기능과 조합하면, 브랜치별로 서로 다른 컨텍스트에서 에이전트를 병렬 기동할 수 있습니다.

# feature-x라는 worktree에서 Codex를 기동
paseo run --provider codex --worktree feature-x "add billing module"
# feature-y라는 worktree에서 Claude Code를 기동
...

개발 서버를 병렬 기동한 경우에도 Paseo는 브랜치 이름을 기반으로 자동으로 URL을 할당합니다. 포트 중복을 수동으로 회피해야 하는 번거로움을 줄일 수 있어, Docker Compose로 여러 서비스를 띄우는 상황에서도 편리합니다.

yutaka가 실제로 느낀 장점과 주의점

장점 1: 인증과 환경의 통일

Claude Code를 평소에 사용하다 보면, 별도로 Codex를 시도해보고 싶을 때 인증을 전환하는 것이 번거롭습니다. Paseo를 경유할 때의 장점은 각 에이전트의 네이티브 CLI (Native CLI)를 동일한 워크플로우로 감쌀 수 있다는 점에 있습니다. 로컬 설정이나 MCP 서버는 각 프로바이더 (Provider) 측에서 그대로 계승되므로, 이전 비용도 낮습니다.

장점 2: 자택 서버에 상주시키고, 외출 시에도 조작

저는 x1lite 위에 Docker 환경을 구축하여, 로컬 LLM (Ollama + Open WebUI)과 병용하고 있습니다. Paseo의 데몬 (Daemon)을 상주시키면, 외출 중에도 SSH 접속 없이 에이전트에게 태스크를 던지고 결과를 확인할 수 있습니다. E2E 암호화 릴레이 (E2E Encryption Relay) 덕분에 토큰이 평문으로 외부에 유출될 리스크도 억제할 수 있는 설계입니다.

주의점 1: 컨테이너화 시의 권한과 볼륨

Docker로 Paseo를 구동할 경우, 작업 디렉토리의 소유권 (PUID/PGID)이나 호스트의 Git 리포지토리 (Git Repository) 마운트 방법에 주의하십시오. 특히 자택 서버에서 여러 서비스를 나열하여 운영하는 경우, 볼륨 충돌을 피하기 위해 서비스마다 데이터 디렉토리를 분리하는 것을 권장합니다.

주의점 2: 프로바이더의 이용 약관

Paseo 자체는 OSS (Open Source Software)로서 독립된 프로젝트이지만, 이용 대상인 Claude Code나 Codex의 이용 약관은 각 사가 정하는 것입니다. 프로바이더 입장에서는 Paseo를 경유한 실행도 직접 CLI를 실행하는 것과 동일하게 취급되지만, 대규모 상업적 이용 시에는 사전에 약관을 확인해 두는 것이 안심할 수 있습니다.

요약: 에이전트의 전환 용이성이 DX의 속도를 결정한다

Paseo는 Claude Code · Codex · Copilot을 다시 다운로드할 필요 없이, CLI 하나로 통합 운용하기 위한 도구입니다. 로컬 서버와 Docker를 능숙하게 다루는 우리에게 인증의 단일화, 포트 관리의 자동화, 외출 시 조작은 DX (Developer Experience)의 장벽을 크게 낮춰줍니다.

코바야시 WEB 시스템에서는 자사 서버 환경의 Docker 구성 재검토 및 업무 시스템의 AI화 지원에 힘쓰고 있습니다. Paseo나 Hermes 에이전트를 활용하여 귀사의 환경에 맞춘 에이전트 운용 기반 설계에 대해서도 언제든 편하게 상담해 주십시오.

본 기사는 2026년 6월 말 시점의 Paseo (getpaseo/cli)와 Claude Code / Codex / Ollama의 로컬 운용을 바탕으로 작성되었습니다.

Discussion