PandaPaw: Claude Code, Codex 및 PandaCode용 원격 호스트

업데이트

PandaPaw는 사용자가 제어하는 Windows, macOS 또는 Linux 머신을 PandaNpc 에이전트 호스트로 전환합니다. 코딩 엔진, 프로젝트 파일, 셸 및 도구는 해당 호스트에 유지됩니다. PandaNpc 클라이언트는 휴대폰, 브라우저 또는 다른 데스크톱에서 동기화된 인터페이스를 제공합니다.

작업을 수행하는 머신이 사용자가 들고 있는 장치와 다를 때, 클라이언트 연결이 끊겨도 호스트가 유지되기를 원할 때, 또는 여러 코딩 엔진이 동일한 계정 기반 설정 및 Agent Center 구성을 공유해야 할 때 PandaPaw를 사용하세요.

PandaPaw가 관리하는 것

  • Claude Code, OpenAI Codex 및 PandaCode용 원격 에이전트 연결.
  • 백그라운드 서비스 및 자동 시작 — 일반적인 재부팅 후 호스트가 복귀할 수 있도록 합니다.
  • 계정 기반 머신 인증 — 장기간 유효한 Bridge ID, 토큰 또는 서명 키를 수동으로 복사할 필요가 없습니다.
  • 엔진 설치 지원 — 지원되는 코딩 엔진이 없는 경우.
  • Agent Center 프로젝션 — 각 엔진의 지침, 스킬, 메모리 및 에이전트 정의를 해당 엔진의 기본 레이아웃으로 렌더링합니다.
  • 비공개 장치 네트워킹 — Connected Devices 흐름을 통해 연결된 머신용.
  • 업데이트 및 제거 관리 — PandaPaw 이전에 존재했던 도구가 보존되도록 합니다.

PandaPaw는 자체적으로 모델 구독을 제공하지 않습니다. Claude Code, Codex 및 PandaCode는 여전히 해당 엔진에 대해 구성된 공급자 자격 증명 및 한도를 사용합니다.

원격 실행이 작동하는 방식

flowchart LR Client["PandaNpc client\nweb · iOS · desktop · Chrome"] -->|outbound authenticated session| Relay["PandaNpc relay"] Host["PandaPaw host"] -->|outbound authenticated session| Relay Host --> Claude["Claude Code"] Host --> Codex["Codex"] Host --> PandaCode["PandaCode"] Claude --> Project["Local project and tools"] Codex --> Project PandaCode --> Project

양쪽 모두 아웃바운드 연결을 시작하므로 일반적인 가정 또는 사무실 설정에서는 인바운드 방화벽 규칙, 공용 IP 주소, 라우터 포트 전달 또는 공개적으로 노출된 SSH 서버가 필요하지 않습니다. 릴레이는 메시지, 상태 및 승인을 전송하며, 도구 실행은 호스트에서 발생합니다.

호스트가 절전 모드로 전환되거나, 전원이 꺼지거나, 아웃바운드 네트워크 경로를 잃으면 저장된 연결은 계정에 남아 있지만 호스트가 복귀할 때까지 작업을 실행할 수 없습니다.

지원되는 호스트 플랫폼

호스트 플랫폼 패키지 참고
Windows x64 네이티브 실행 파일 및 사용자 수준 서비스 PowerShell에서 설치 프로그램 실행
macOS, Apple Silicon 또는 Intel 유니버설 PandaPaw 애플리케이션/바이너리 동일한 패키지가 두 아키텍처를 모두 지원
Linux x86_64 네이티브 바이너리 및 사용자 서비스 일반적인 glibc 기반 배포판용

PandaNpc 뷰어 클라이언트는 더 넓은 플랫폼 매트릭스를 제공합니다. 클라이언트 및 호스트 패키지를 선택할 때 PandaNpc 및 PandaPaw 설치를 참조하세요.

권장 설치

  1. PandaNpc에 로그인합니다.
  2. Connected Devices를 엽니다.
  3. Add a device를 선택합니다. 일회용 키가 발급되고 대화상자에 감지된 운영 체제에 대한 명령 하나가 표시됩니다.
  4. 해당 명령을 복사하여 호스트에서 실행합니다.
  5. 새 머신을 자동으로 감지하려면 대화상자를 열어 둡니다.

준비된 키는 일회용입니다. 전체 명령을 복사하고 비공개로 유지하며, 만료되었거나 이미 사용된 경우 새 키를 생성하세요.

일반 macOS/Linux 설치 프로그램

준비된 키 대신 브라우저 인증을 원할 때 이 형식을 사용하세요:

bash
curl -fsSL https://cos.pandanpc.com/pandapaw/install.sh | sh

일반 Windows PowerShell 설치 프로그램

powershell
iwr -useb https://cos.pandanpc.com/pandapaw/install.ps1 | iex

일반 설치 프로그램은 pandapaw login을 실행합니다. 열리는 브라우저 페이지에서 머신을 승인하세요. 인증이 중단되더라도 바이너리와 서비스는 여전히 설치될 수 있습니다. 나중에 pandapaw login을 실행하여 계정 연결을 완료하세요.

호스트 확인

먼저 호스트 자체를 확인합니다:

bash
pandapaw status

그런 다음 PandaNpc Agent를 열고 머신에 녹색 온라인 표시등이 있는지 확인합니다. 일회용 또는 읽기 전용 테스트 디렉터리에서 세션을 시작하고 다음을 요청하세요:

테스트 프롬프트: 현재 작업 디렉터리를 출력하고 최상위 파일들을 나열하세요. 아무것도 수정하지 마세요.

성공적인 응답은 단순한 녹색 상태 표시등 이상을 증명합니다. 계정 페어링, 릴레이 연결, 선택된 엔진, 공급자 인증 및 작업 디렉터리 매핑을 검증합니다.

Agent Center 프로젝트의 경우 다음을 실행하세요:

bash
pandapaw agent status --root /absolute/path/to/project

이는 프로젝트가 바인딩되었는지, 관리되는 구성이 로컬에서 사용 가능한지 보여줍니다. 안정적인 Git 원격 저장소는 PandaPaw가 여러 머신에서 동일한 프로젝트를 식별하는 데 도움이 됩니다.

계정 인증 및 연결 ID

pandapaw login은 브라우저 장치 인증 세션을 사용합니다. 승인 후 호스트는 TLS를 통해 장치 범위 자격 증명과 Agent Center 확인 키를 수신하고, ~/.pandapaw/ 아래에 머신 구성을 작성하고, 지원되는 엔진 연결을 등록하고, 인식 가능한 Git 프로젝트를 바인딩합니다.

의도적으로 계정을 전환하거나 만료된 호스트 자격 증명을 교체할 때만 pandapaw login --force를 실행하세요. 이유 없이 정상적인 머신을 다시 인증하면 혼란스러운 중복 또는 대체 ID가 생성될 수 있습니다.

pandapaw qr은 호환성 및 특수 사례를 위해 단기 수동 연결 링크를 계속 생성합니다. 새 호스트의 기본 흐름은 아닙니다. Connected Devices는 감사가 더 쉽고 사용자가 Bridge ID를 이해할 필요가 없습니다.

Agent Center 동기화

Agent Center는 정상 상태에서 이벤트 기반입니다:

  1. 로컬 관리 파일 변경 사항이 감지되어 바인딩된 프로젝트에 게시됩니다.
  2. 서명된 릴리스가 이벤트 스트림을 통해 도착합니다.
  3. 변경되지 않은 매니페스트와 콘텐츠 blob은 다시 다운로드하는 대신 재사용됩니다.
  4. 주기적인 복구 검사는 일시적인 연결 끊김 동안 놓친 이벤트를 포착합니다.

Claude Code, Codex 및 PandaCode는 서로 다른 디렉터리와 지침 형식을 기대하므로 별도의 프로젝션을 받습니다. PandaCode는 새 세션 프롬프트를 조립하기 전에 최신 검증된 릴리스를 준비하므로 시작 시 가져온 구성이 동일한 세션에 영향을 줄 수 있습니다.

Agent Center를 일시적으로 사용할 수 없는 경우 엔진은 마지막으로 검증된 로컬 릴리스로 계속 작동합니다. 네트워크 오류로 인해 서명된 구성이 검증되지 않은 콘텐츠로 조용히 대체되어서는 안 됩니다.

유용한 명령

bash
pandapaw login
pandapaw status
pandapaw agent status --root /absolute/path/to/project
pandapaw update --restart
pandapaw uninstall
명령 용도
pandapaw login 아직 계정에 연결되지 않은 설치된 머신을 인증
pandapaw status 설치된 서비스, 머신 연결 및 기본 상태 확인
pandapaw agent status --root … 한 프로젝트에 대한 Agent Center 상태 검사
pandapaw update --restart 최신 PandaPaw 릴리스 확인, 설치 및 활성화
pandapaw uninstall PandaPaw가 관리하는 서비스와 파일을 안전하게 제거

명령이나 UI가 이전 스크린샷이나 튜토리얼과 다른 경우 PandaPaw 버전 기록을 확인하세요.

보안 경계

  • 원격 운영자는 선택된 에이전트 세션이 허용하는 도구와 작업 디렉터리를 사용할 수 있습니다. 원격 액세스는 자동으로 읽기 전용이 아닙니다.
  • 일회용 장치 명령, 수동 연결 링크, 공급자 키 및 계정 토큰을 로그와 스크린샷에 남기지 마세요.
  • PandaPaw에 연결하기 위해 인바운드 라우터 포트를 열지 마세요.
  • 더 이상 소유하지 않는 호스트를 Connected Devices에서 제거하세요.
  • 도구 승인을 검토하고 편집 또는 셸 명령을 허용하기 전에 작업 디렉터리를 확인하세요.
  • 활성 연결을 공유할 때 수신자는 호스트 소유자의 엔진 할당량을 소비하고 호스트에서 작업을 수행할 수 있습니다. 먼저 연결 공유를 읽으세요.

문제 해결

설치 후 `pandapaw`를 찾을 수 없음

사용자 PATH를 다시 로드하려면 새 터미널을 여세요. 일반적인 위치는 macOS/Linux에서 ~/.local/bin, Windows에서 %LOCALAPPDATA%\Programs\pandapaw입니다. 설치 프로그램을 다시 실행하기 전에 파일이 존재하는지 확인하세요.

설치는 성공했지만 머신이 나타나지 않음

pandapaw status를 실행하세요. 머신에 계정 인증이 없으면 pandapaw login을 실행하세요. 준비된 일회용 키를 사용한 경우 소비된 명령을 다시 시도하지 말고 새 키를 만드세요.

머신이 나타나지만 오프라인 상태로 유지됨

호스트가 깨어 있고 인터넷에 접속할 수 있는지 확인하세요. PandaPaw 상태를 로컬에서 확인하세요. 기업 프록시 또는 방화벽이 아웃바운드 HTTPS/WebSocket 경로를 허용해야 합니다. 인바운드 포트는 차단된 아웃바운드 연결을 해결하지 못합니다.

호스트는 온라인인데 Claude Code 또는 Codex가 응답하지 않음

호스트를 페어링한다고 해서 모든 모델 공급자가 인증되는 것은 아닙니다. 엔진을 로컬에서 열거나 원격 세션에 표시된 로그인 프롬프트를 따르세요. 또한 선택한 모델이 해당 계정에 존재하고 사용 한도가 소진되지 않았는지 확인하세요.

세션이 잘못된 프로젝트에서 열림

테스트를 종료하고 의도한 절대 작업 디렉터리를 선택한 다음 도구를 승인하기 전에 에이전트에게 해당 디렉터리를 출력하도록 요청하세요. PandaPaw는 사용자가 의도한 저장소를 추측하지 않으며 엔진 자체의 권한 모델 외에 파일 시스템 샌드박스를 추가하지 않습니다.

Agent Center 변경 사항이 나타나지 않음

올바른 Git 루트에서 pandapaw agent status --root /path/to/project를 실행하세요. 프로젝트가 바인딩되어 있고, 호스트가 로그인되어 있으며, 로컬 파일이 관리되는 프로젝션의 일부인지 확인하세요. 조사하는 동안 관리되는 디렉터리를 삭제하는 대신 마지막으로 검증된 릴리스를 그대로 두세요.

업데이트 및 제거

pandapaw update --restart는 현재 바이너리를 다운로드하고, SHA-256 체크섬을 확인하고, 설치된 복사본을 교체하고, 관리 서비스를 다시 시작하여 버전이 활성화되도록 합니다. 기존 계정 페어링은 유지됩니다.

pandapaw uninstall은 설치 매니페스트를 사용하여 PandaPaw가 생성한 항목을 제거합니다. 이미 존재했던 호환 가능한 Claude Code, Codex, PandaCode 또는 Node 설치물은 의도적으로 보존됩니다. 제거 후 더 이상 신뢰할 수 없는 경우 호스트를 Connected Devices에서 제거하세요.