Twigpine/openclaude

OpenClaude

OpenClaude는 클라우드 및 로컬 모델 제공자를 위한 오픈소스 코딩 에이전트 CLI입니다.

OpenAI 호환 API, Gemini, GitHub Models, Codex OAuth, Codex, Ollama, Atomic Chat 및 기타 지원 백엔드를 사용하면서 하나의 터미널 우선 워크플로를 유지합니다: 프롬프트, 도구, 에이전트, MCP, 슬래시 명령, 스트리밍 출력.

OpenClaude는 GitLawb에도 미러링됩니다: gitlawb.com/node/repos/z6MkqDnb/openclaude

Why OpenClaude

• 클라우드 API와 로컬 모델 백엔드 전반에 걸친 하나의 CLI — 제공자별 도구가 필요 없음
• /provider를 통한 안내식 제공자 설정 및 저장된 프로필
• 한곳에서 코딩 에이전트 워크플로: bash, 파일 도구, grep, glob, 에이전트, 작업, MCP, 웹 도구
• 실행 통합 및 테마 지원을 위한 번들 VS Code 확장
• Enter를 누를 때마다 화살을 발사하는 픽셀 아트 영웅 동반자 (정말로 — Meet your buddy 참조)

Quick Start

Install

OpenClaude는 npm 설치 및 런타임에 Node.js >=22.0.0이 필요합니다. Bun은 소스 빌드와 로컬 개발에만 필요합니다.

npm install -g @gitlawb/openclaude@latest

Arch Linux를 사용하는 경우 커뮤니티에서 관리하는 AUR 패키지에서 OpenClaude를 설치할 수 있습니다:

paru -S openclaude

설치 후 ripgrep not found가 보고되면 시스템 전역에 ripgrep을 설치하고 OpenClaude를 시작하기 전에 동일한 터미널에서 rg --version이 작동하는지 확인하세요.

설치된 버전 확인 / 문제 해결:

openclaude --version
npm view @gitlawb/openclaude dist-tags
npm install -g @gitlawb/openclaude@latest

Start

openclaude

OpenClaude 내부에서:

• 안내식 제공자 설정 및 저장된 프로필을 위해 /provider 실행
• GitHub Models 온보딩을 위해 /onboard-github 실행

참고: OpenClaude는 프로젝트 .env 파일을 자동으로 로드하지 않습니다. 제공자 프로필과 자격 증명을 .openclaude-profile.json에 저장하는 /provider 명령을 통한 설정을 권장합니다. 환경 변수를 선호하는 경우 명시적으로 내보내거나 제공자/설정 변수에 대해 openclaude --provider-env-file.env를 실행하세요. 런타임/디버그 설정은 셸이나 런처에서 내보내세요.

대화 재개 또는 포크

세션 ID로 기존 대화를 재개하거나 현재 디렉터리에서 가장 최근 대화를 계속합니다:

openclaude --resume <session-id>
openclaude --continue

--fork-session을 추가하면 원본 트랜스크립트를 재사용하는 대신 대화 기록을 새 세션 ID로 분기합니다:

openclaude --resume <session-id> --fork-session
openclaude --continue --fork-session

포크는 대화 분기일 뿐입니다. 파일 시스템 격리, 작업 트리 복사, git worktree 브랜치 생성은 하지 않습니다.

백그라운드 세션

현재 터미널에서 분리된 긴 비대화형 프롬프트를 실행합니다:

openclaude --bg "fix failing tests"
openclaude --bg --name auth-refactor "refactor auth middleware"
openclaude ps
openclaude logs auth-refactor
openclaude logs auth-refactor -f
openclaude kill auth-refactor

백그라운드 세션은 로컬 자식 프로세스입니다. OpenClaude는 데몬이나 네트워크 서비스를 시작하지 않으며, 권한/제공자/모델/설정 플래그는 포그라운드 --print 실행과 동일한 방식으로 자식 프로세스에 전달됩니다. 세션 메타데이터와 로그는 해석된 OpenClaude 설정 디렉터리(보통 ~/.openclaude/bg-sessions/) 아래에 저장됩니다. OPENCLAUDECONFIGDIR은 OpenClaude를 다른 위치로 지정할 수 있습니다. CLAUDECONFIGDIR은 OpenClaude 백그라운드 세션 저장에 무시됩니다. 이전 세션이 종료 상태에 도달한 후 세션 이름을 재사용할 수 있습니다. 동일한 이름의 이전 로그를 검사하려면 세션 ID를 사용하세요. 자연스럽게 완료된 세션은 프로세스가 0을 반환하면 exited로, 0이 아닌 값을 반환하거나 종료 신호를 처리하면 failed로 기록됩니다. 프로세스가 관찰된 결과 없이 사라지면 stale이 보수적 결과로 남습니다. 명시적으로 성공한 openclaude kill은 killed로 기록되며, killed는 동일 프로세스에 대해 자연스러운 exited 또는 failed 결과보다 우선합니다. 종료 결과는 bg-sessions/terminal/ 아래에 별도로 저장됩니다. 해당 디렉터리를 삭제하면 완료된 세션이 활성 상태에서 파생된 상태로 폴백됩니다. OpenClaude는 Windows에서 POSIX 신호 이름을 추론하지 않습니다. 관찰할 수 없는 강제 종료, 호스트 충돌, 전원 손실은 모든 플랫폼에서 stale로 남습니다.

openclaude attach 는 현재 일치하는 세션을 보고하고 openclaude logs -f를 가리킵니다. 로컬 백그라운드 세션에 대한 완전한 터미널 재부착은 아직 구현되지 않았습니다.

OpenClaude 설정 전환

OpenClaude는 기본적으로 자체 설정을 ~/.openclaude 및 ~/.openclaude.json 아래에 저장합니다. ~/.claude, 프로젝트 .claude/ 디렉터리 또는 CLAUDECONFIGDIR을 읽지 않습니다. 새 사용자는 빈 OpenClaude 설정으로 시작할 수 있으며 Claude Code가 설치되어 있을 필요가 없습니다.

이전에 .claude 경로로 OpenClaude를 사용했다면 의도적으로 마이그레이션하세요: OpenClaude를 위해 개인적으로 생성한 설정, 명령, 에이전트, 스킬, 예약된 작업 또는 기타 파일만 일치하는 .openclaude 위치로 복사하세요. .claude를 통째로 복사하지 말고 Claude Code 자격 증명이나 인증 파일을 복사하지 마세요. 제공자 인증의 경우 OpenClaude의 제공자 설정을 다시 실행하거나 제공자별 환경 변수를 내보내는 것을 권장합니다.

가장 빠른 OpenAI 설정

macOS / Linux:

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-your-key-here
export OPENAI_MODEL=gpt-4o

openclaude

Windows PowerShell:

$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_API_KEY="sk-your-key-here"
$env:OPENAI_MODEL="gpt-4o"

openclaude

가장 빠른 로컬 Ollama 설정

macOS / Linux:

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=qwen2.5-coder:7b

openclaude

Windows PowerShell:

$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_BASE_URL="http://localhost:11434/v1"
$env:OPENAI_MODEL="qwen2.5-coder:7b"

openclaude

Ollama의 경우 OpenClaude는 Ollama의 네이티브 채팅 API를 사용하고 각 채팅 요청에 32768 토큰 컨텍스트 창을 요청하여 동일 세션 기록이 Ollama의 OpenAI 호환 심(shim)에 의해 조용히 잘리지 않도록 합니다. 다른 요청 수준 컨텍스트 크기가 필요하면 OPENCLAUDEOLLAMANUMCTX 또는 OLLAMACONTEXT_LENGTH를 설정하세요. ollama ps로 확인하는 방법은 Advanced Setup을 참조하세요.

Setup Guides

초보자 친화적 가이드:

• Non-Technical Setup
• Windows Quick Start
• macOS / Linux Quick Start

고급 및 소스 빌드 가이드:

• Advanced Setup
• Smart Auto-Routing
• Agent Routing and Step Limits
• Headless gRPC Server
• Repo Map (코드베이스 인텔리전스)
• Skills
• Android Install

Supported Providers