OpenClaude Portable: USB에서 바로 실행하는, 7개 LLM 제공자를 지원하는 휴대용 코딩 에이전트

9bow · 5월 13, 2026, 6:30오전

OpenClaude Portable 소개

OpenClaude Portable 은 USB 드라이브나 임의의 폴더에서 그대로 실행되는, 설치가 필요 없는 휴대용 AI 코딩 에이전트입니다. 오픈소스 OpenClaude 엔진을 기반으로 동작하며, 자체 포함된 Node.js 런타임, 시스템 프롬프트를 가공하는 로컬 프록시, 웹 기반 대시보드를 한 폴더 안에 묶어 두기 때문에 호스트 시스템에 어떤 파일도 남기지 않습니다. 학교 컴퓨터처럼 설치 권한이 없는 환경, 회사 보안 정책으로 임의 설치가 제한된 PC, 여러 머신을 오가는 작업 환경 등에서 코딩 에이전트를 그대로 가져갈 수 있도록 설계된 것이 특징입니다.

OpenClaude Portable 프로젝트가 지향하는 핵심 가치는 "어디서나 실행되지만 어디에도 흔적을 남기지 않는다(zero footprint)"입니다. XDG_CONFIG_HOME, XDG_DATA_HOME, CLAUDE_CONFIG_DIR 같은 환경 변수를 모두 프로젝트 내부의 data/ 폴더로 리다이렉트하기 때문에 OS 의 사용자 디렉토리에 설정 파일이 흩어지지 않습니다. API 키, 세션 기록, 로컬 모델 가중치, 프록시 로그까지 전부 USB 드라이브 한 폴더 안에 모이며, USB 를 빼면 모든 흔적이 함께 사라집니다.

LLM 측면에서는 NVIDIA NIM, DeepSeek, OpenRouter, Google Gemini, Anthropic Claude, OpenAI, Ollama 까지 7 종의 제공자를 한 인터페이스로 묶어 줍니다. 인터넷이 가능한 환경에서는 클라우드 API 를 사용하다가, 오프라인 또는 보안이 엄격한 환경에서는 Ollama 의 로컬 모델로 즉시 전환할 수 있습니다. 이름이 OpenClaude 이지만 Anthropic 의 공식 Claude Code 와는 별개의 프로젝트이며, 이름은 기반 엔진인 오픈소스 OpenClaude 를 따른 것입니다.

OpenClaude Portable의 핵심 기능

OpenClaude Portable 저장소는 여러 코딩 에이전트 도구가 만들어 내는 운영상의 마찰을 한 폴더 안으로 정리해주는 데 초점을 맞춘 통합 패키지입니다.

7개 LLM 제공자의 단일 인터페이스: NVIDIA NIM, DeepSeek, OpenRouter, Google Gemini, Anthropic Claude, OpenAI, Ollama 를 모두 같은 메뉴에서 선택할 수 있습니다. 무료 티어가 있는 NVIDIA NIM 이나 Google Gemini 로 시작했다가 작업 성격에 따라 유료 클라우드나 로컬 Ollama 로 전환하기 좋습니다.

제로 풋프린트(zero footprint): API 키와 세션 기록, 로컬 모델 가중치, 프록시 로그까지 모두 프로젝트 내부의 data/ 폴더에 저장됩니다. 호스트 PC 의 사용자 디렉토리나 시스템 폴더에는 어떤 파일도 쓰지 않으며, data/ollama/ 폴더 안에 Ollama 바이너리와 모델까지 함께 보관할 수 있습니다.

로컬 모델용 시스템 프롬프트 트리밍 프록시: tools/local-proxy.js 가 Ollama 로 향하는 요청을 가로채 OpenClaude 의 시스템 프롬프트를 약 10,000 토큰에서 약 300 토큰까지 잘라낸 뒤 전달합니다. README 에 따르면 CPU 전용 환경에서 first-token latency 가 60~120 초에서 5~20 초로 단축되며, 프록시 활동은 data/proxy.log 에만 조용히 기록됩니다.

ChatGPT 스타일 웹 대시보드: Open Dashboard 메뉴에서 http://localhost:3000 으로 열리는 웹 UI 가 제공되며, 에이전트 모드, 도구 카드(tool cards), 사고 과정(thinking) 시각화 같은 기능을 갖추고 있어 CLI 인터페이스에 익숙하지 않은 사용자도 쉽게 활용할 수 있습니다.

Limitless 자동 실행 모드: Limitless Mode 를 선택하면 에이전트가 파일 작성과 셸 명령을 사용자 승인 없이 자동 실행합니다. 일반 모드에서는 매 동작마다 승인 프롬프트가 뜨고, 메뉴는 10 초 동안 입력이 없으면 안전 기본값인 일반 모드를 자동으로 선택합니다.

세션 재개와 일일 자동 업데이트 캐시: RESUME.bat <session-id> 로 중단된 세션을 이어갈 수 있고, 엔진 업데이트 확인은 하루에 한 번만 수행해 반복 실행 시 네트워크 호출을 생략합니다. Windows, Linux, macOS 가 모두 같은 data/ 폴더를 공유합니다.

OpenClaude Portable의 시스템 프롬프트 트리밍 프록시

CPU 전용 또는 USB 2.0 환경에서 로컬 LLM 을 쓸 때 가장 큰 병목은 컴퓨팅 자체보다 긴 시스템 프롬프트의 prefill 단계입니다. OpenClaude 같은 코딩 에이전트는 도구(tool) 정의와 가이드라인을 포함한 약 10,000 토큰 수준의 시스템 프롬프트를 사용하는데, 이 프롬프트가 매 요청마다 전체 디코딩 파이프라인을 거치면 작은 로컬 모델에서는 응답이 시작되기까지 1~2 분이 걸리는 경우가 흔합니다.

OpenClaude Portable 의 로컬 프록시는 이 문제를 다음과 같은 흐름으로 우회합니다.

# 시스템 프롬프트 트리밍 프록시 의사코드
def handle_request(req):
    # 1) 클라이언트에서 들어온 OpenClaude 요청 파싱
    payload = parse_chat_request(req)               # messages, tools, system, ...
    system_full = payload["system"]                 # ~10,000 tokens
    user_messages = payload["messages"]

    # 2) 로컬 모델용으로 시스템 프롬프트 압축
    #    - tool 정의는 그대로 유지하되 설명 텍스트는 핵심만 추출
    #    - 가이드라인/예시는 가장 영향력 큰 항목만 남겨 ~300 토큰 수준으로 축약
    system_trimmed = compress_for_local_model(
        system_full,
        keep=["tools", "core_rules"],
        drop=["long_examples", "verbose_explanations"],
        max_tokens=300,
    )

    # 3) 압축된 프롬프트로 Ollama 호출
    payload["system"] = system_trimmed
    response = forward_to_ollama(payload)

    # 4) 활동 로그는 터미널이 아닌 data/proxy.log 에만 기록
    log_to_file(payload, response, path="data/proxy.log")
    return response

이 트리밍은 클라우드 API 호출에는 적용되지 않고 Ollama 로 향하는 트래픽만 가로챈다는 점이 중요합니다. 즉 Anthropic Claude 나 OpenAI 같은 강력한 모델을 쓸 때는 원본 시스템 프롬프트를 그대로 보내 정확도를 유지하고, 작은 로컬 모델을 쓸 때만 응답 속도를 위해 프롬프트를 축약합니다.

OpenClaude Portable의 보안 및 휴대성

이 프로젝트가 가진 또 다른 매력은 보안 측면의 명료함입니다. README 는 다음과 같은 정책을 명시합니다.

제로 풋프린트(Zero Footprint): 모든 데이터를 프로젝트 디렉토리 내부에 격리하기 위해 XDG_CONFIG_HOME, XDG_DATA_HOME, CLAUDE_CONFIG_DIR 가 data/ 폴더로 리다이렉트됩니다.

텔레메트리 없음(No Telemetry): 사용자가 선택한 LLM 제공자 외부로는 어떤 데이터도 전송되지 않습니다.

API 키의 로컬 보관: API 키는 USB 내부의 data/ai_settings.env 에만 저장되며, 일반 모드에서는 파일 작성과 셸 명령 실행 직전마다 승인을 요구합니다.

이 같은 설계 덕분에 OpenClaude Portable 은 보안 정책이 엄격한 환경에서도 비교적 통제 가능한 형태로 코딩 에이전트를 시도해보기에 적합합니다. 다만 Limitless Mode 는 승인 단계 없이 명령을 자동 실행하므로 신뢰할 수 있는 환경에서만 사용해야 하며, README 도 일반 모드를 기본값으로 권장합니다.

OpenClaude Portable 설치 및 사용법

# Linux / macOS
git clone https://github.com/techjarves/OpenClaude-Portable.git
cd OpenClaude-Portable
chmod +x start.sh
./start.sh

# Windows (PowerShell 또는 cmd)
# .\START.bat

첫 실행 시에는 인터넷 연결이 필요하며, 약 25MB 크기의 Node.js 와 약 5MB 크기의 OpenClaude 엔진을 자동으로 내려받은 뒤 LLM 제공자 선택 마법사로 이어집니다. 두 번째 실행부터는 메뉴가 곧바로 표시됩니다. 메뉴 항목은 일반 모드 실행, Limitless 자동 실행 모드, 웹 대시보드 열기, 제공자 변경, 오프라인 모델 설정으로 구성되며 10 초 동안 입력이 없으면 일반 모드가 자동 선택됩니다.

CPU 전용 머신에서는 gemma3:1b, qwen2.5:1.5b, phi3:mini 같은 소형 모델이 권장되며, USB 2.0 의 읽기 속도가 병목이 될 경우 data/ollama/ 폴더를 로컬 SSD 로 옮겨 두는 것이 권장됩니다.

라이선스

OpenClaude Portable 프로젝트는 MIT 라이선스로 공개되어 있어 개인적 사용은 물론, 사내 도구로 포팅하거나 커스텀 빌드를 만들어 배포하는 것도 자유롭습니다. 다만 기반 엔진인 OpenClaude(gitlawb/openclaude) 의 라이선스 조건도 함께 준수해야 합니다.

OpenClaude Portable 프로젝트 GitHub 저장소

기반 엔진 OpenClaude(gitlawb/openclaude) GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~