shiwenwen/hope-agent: 크로스 플랫폼 연동 및 사용자 맞춤형 데스크톱 AI 어시스턴트, 서비스화 및 클라우드 실행 지원

크로스 플랫폼 연동, 사용할수록 당신을 더 잘 이해하는 데스크톱 AI 어시스턴트, 서비스 형태로 상주하며 클라우드에서도 실행 가능

기억함 · 성장함 · 깊이 있는 융합 · 모든 채팅에서 즉시 호출 가능

간체 중국어 · English

Hope Agent는 AI 어시스턴트를 더 단순하고, 더 안정적이며, 유지보수가 더 쉬운 형태로 만들고자 합니다. 동일한 대화 세션을 사용자의 기기와 채팅 플랫폼 간에 자유롭게 인계할 수 있으며, 매일 사용하는 과정에서 스스로 발전합니다. 즉, 세션 간 기억(Cross-session memory)이 지속적으로 축적되고, 유휴 시간에는 스스로 정리하며, 수행한 작업은 재사용 가능한 기술(Skill)로 정착됩니다. 단일 네이티브 설치 패키지로 주요 대규모 언어 모델(LLM) GUI 템플릿이 모두 내장되어 있어, API Key만 입력하면 바로 대화를 시작할 수 있습니다. 데스크톱 버전은 사용자 권한 부여 시 로컬 컴퓨터를 관찰하고 제어할 수 있습니다(현재 macOS만 지원). 동시에 NAS, 개인 서버, 클라우드 호스트(Cloud Host)에 서비스 형태로 상주하며 IM(Instant Messaging) 채널을 통해 언제 어디서든 호출할 수 있습니다.

우리는 AI 어시스턴트가 진정으로 **설치 즉시 사용 가능(Out-of-the-box)**하기를 바랍니다. 런타임(Runtime)을 먼저 설치하거나 명령줄 인터페이스(CLI)를 배울 필요가 없어야 하며, 이해하기 어려운 설정이나 서비스가 밤중에 다운되었을 때 관리할 사람이 없어 걱정할 필요도 없어야 합니다. 동시에 어디서든 대화를 이어갈 수 있어야 합니다. Hope Agent는 단순한 데스크톱 GUI가 아닙니다. HTTP/WS 서비스로 상주하며 NAS, 개인 서버 또는 클라우드 호스트에서 24시간 7일 내내 구동될 수 있으며, 동시에 IM 채널에 접속하고 IDE(ACP)와 연동될 수 있습니다. 하지만 우리는 가장 편리한 입구는 여전히 데스크톱이라고 믿기에, 데스크톱 GUI와 시스템의 깊은 융합에 가장 많은 공을 들였으며 성능, 안정성 및 상호작용 디테일을 정교하게 다듬었습니다. 핵심 목표는 소박합니다. 사용 및 유지보수 비용을 낮추고, 단순한 시나리오에서는 매우 편리하게 만들며, 장기 실행 시에도 충분히 안정적이게 만드는 것입니다. 또한 사용자와 함께 오래 지속되기를 바랍니다. 동일한 세션이 기기와 입구를 넘나들며 이어지므로, 사용자가 플랫폼을 전환하더라도 작업이 중단되지 않고 기억과 기술이 서서히 축적됩니다.

Hope Agent는 초기 단계에서 openclaw의 영향을 받았으며, 로컬 AI 어시스턴트 방향에서 선구적인 역할을 해준 그들에게 감사를 표합니다. 다만 우리는 다른 구현 경로를 선택했습니다.

🖥️ 데스크톱 네이티브 GUI | macOS / Linux / Windows 3개 플랫폼의 네이티브 애플리케이션으로, 다운로드 즉시 사용 가능합니다. 12가지 언어(중국어 간체/번체, 영어, 일본어, 한국어, 스페인어, 포르투갈어, 러시아어, 아랍어, 터키어, 베트남어, 말레이어)를 지원하며, 다크 테마와 정교하게 조정된 타이포그래피를 제공합니다.

🧙 간편한 Provider 설정 | 206개의 사전 설정 모델을 커버하는 39개의 내장 Provider 템플릿을 제공합니다. Anthropic / OpenAI / Gemini / Codex / OpenRouter / DeepSeek / Kimi / Qwen / 豆包(Doubao) / GLM / MiniMax / xAI / Mistral / Cerebras / DeepInfra / 腾讯混元(Tencent Hunyuan) / Ollama를 원스톱으로 지원합니다. 동일한 Provider 내에서 여러 API Key를 자동으로 순환(Rotation)할 수 있어, 속도 제한(Rate limit)이나 할당량 소진 시 끊김 없이 다음 키로 전환됩니다.

🦙 로컬 소형 모델 원클릭 설치 | 계정, API Key, 터미널이 필요 없습니다. 설정 → 모델 페이지에서 하드웨어 사양에 맞는 Qwen 3.6 / Gemma 4 사이즈 모델을 선택하면 Ollama 설치, 모델 다운로드, Provider 등록 및 전환이 원클릭으로 완료됩니다. 동일한 프로세스로 로컬 임베딩(Embedding) 모델 설치도 지원합니다.

💬 12개 IM 채널 원스톱 연동 | Telegram, Discord, Slack, Feishu, Google Chat, LINE, QQ Bot, Signal, iMessage, IRC, WeChat, WhatsApp을 지원합니다. 이미지 / 음성 / 파일 입력을 멀티모달(Multimodal) 컨텍스트로 자동 변환하며, 도구 승인(Tool approval)은 채팅창의 버튼을 눌러 직접 결정할 수 있습니다. 각 그룹 채팅이나 계정별로 독립적인 Agent와 권한 정책을 바인딩할 수 있습니다.

🤝 자유로운 대화 인계, 크로스 플랫폼 끊김 없는 연결 | 동일한 세션을 데스크톱, 브라우저, IM 사이에서 자유롭게 인계할 수 있습니다. 컴퓨터에서 대화하다가 외출할 때 지하철에서 스마트폰의 Telegram으로 대화를 이어가고, 집에 돌아와 데스크톱 앱을 열면 이미 IM에서 나누었던 대화 내용이 정리되어 있습니다. 동일한 기억 / 도구 상태 / 플랜(Plan) / 작업 디렉토리가 따라오므로, 다른 쪽에서 컨텍스트를 다시 설명할 필요가 없습니다. /handover 명령어로 현재 데스크톱 세션을 지정된 IM 채팅으로 넘길 수 있고, /session <id> 명령어로 IM 단에서 역으로 제어할 수 있습니다. 데스크톱에서 실행 중인 대화는 **IM으로 스트리밍 미러링(Streaming Mirroring)**되어, 모델이 글을 쓰는 동안 Telegram / Feishu / Slack에서 실시간으로 타이핑되는 모습을 볼 수 있습니다.

| 🌐 독립 서비스 · 브라우저가 곧 클라이언트 | 단순한 데스크톱 애플리케이션 그 이상입니다. GUI(그래픽 사용자 인터페이스)에서 완전히 벗어나 독립적인 서비스로 실행될 수 있습니다. 단 한 줄의 명령 hope-agent server start로 HTTP/WS 데몬(Daemon) 프로세스를 시작할 수 있으며, server install을 통해 launchd / systemd에 등록하여 부팅 시 자동 실행되도록 설정할 수 있습니다. 집의 NAS, 클라우드 서버, 혹은 오래된 노트북에 올려 24시간 온라인 상태를 유지하세요. 서버 내에는 완전한 Web GUI가 내장되어 있으며(프론트엔드는 rust-embed를 통해 바이너리에 포함됨), 스마트폰, 태블릿, 브라우저, 다른 컴퓨터에서 클라이언트를 설치하거나 프론트엔드를 설정할 필요 없이 바로 접속할 수 있습니다. Bearer Token 인증과 SSRF(Server-Side Request Forgery) 3단계 전략을 통해 공용 네트워크에 노출되더라도 제어가 가능합니다. 세션(Session), 기억(Memory), Cron, IM 채널은 모두 서버 측에서 실행되며, 클라이언트는 단지 창(Window) 역할만 수행합니다. http://<server>:port 접속만으로 완전한 React 인터페이스를 사용할 수 있습니다.
🔁 세 가지 실행 모드의 동일한 핵심 | 데스크톱 GUI(기본값), HTTP/WS 데몬 + 내장 Web GUI(브라우저 직접 연결), ACP stdio(IDE의 에이전트 백엔드로 사용). 세 가지 모드는 모두 Rust ha-core 핵심 라이브러리를 공유하며, Tauri 의존성이 전혀 없습니다. 즉, 동일한 코드 하나로 데스크톱 앱, 서버, 그리고 IDE 내장형으로 모두 동작할 수 있습니다.

🧠 교차 세션 지속 기억 (Cross-session Persistent Memory) | SQLite + FTS5 전체 텍스트 검색(Full-Text Search) + 벡터 의미론적 검색(Vector Semantic Search)의 삼위일체 구조입니다. 기억은 전역(Global) / 프로젝트(Project) / 에이전트(Agent)의 세 가지 계층적 스코프(Scope)로 조직될 수 있습니다. 시스템 프롬프트(System Prompt) 주입은 통합 예산에 따라 배분되므로, 특정 계층이 너무 길어져 다른 계층을 밀어내는 일이 발생하지 않습니다.
🕶 흔적 없는 대화 (Incognito Chat) | 세션 단위 스위치로, 첫 번째 메시지부터 흔적 없이 대화할 수 있습니다. 이 기능을 켜면 현재 대화에는 어떠한 기억이나 교차 세션 인지 기능도 주입되지 않으며

📋 Plan Mode (계획 모드) | 복잡한 작업에 직면했을 때 수정 및 승계가 가능한 계획서를 먼저 작성합니다. 5가지 상태 머신 (State Machine)으로 실행 진행도를 관리하며, 계획 파일은 Agent / 세션 (Session) 단위로 물리적으로 격리되어 세션 간 간섭이 발생하지 않습니다. 계획은 세션 간 아카이브(Archive)가 가능하며, 다음번에 "지난 계획을 계속해줘"라는 한 마디만으로 이어서 진행할 수 있습니다. 사이드바의 Plans 히스토리 뷰어는 모든 계획( /plan exit로 아카이브된 계획 포함)을 세션 구분 없이 읽기 전용으로 브라우징할 수 있으며, Agent / 상태별 필터링, 버전 전환, 해당 세션으로의 즉시 이동을 지원합니다. 상세 패널에서는 @plan:<short_id>:v<version> 형식으로 현재 대화에 즉시 주입할 수 있습니다. 실행 중에는 화이트리스트(Whitelist) 도구에 따라 엄격하게 작동하여 모델이 통제 범위를 벗어나는 것을 방지합니다.

📁 Project (프로젝트 컨테이너) | 관련 세션들을 동일한 프로젝트 아래로 묶어 프로젝트 레벨의 기억 (Memory) / 프로젝트 지시 사항 (Instruction) / 공유 파일을 상속받습니다. 업로드된 파일은 자동으로 텍스트 추출이 수행되어 3단계로 주입됩니다 (디렉토리 목록 / 소형 파일 자동 인라인 처리 / 대형 파일은 필요 시 읽기). 수동으로 파일을 @ 호출할 필요가 없으며 컨텍스트 (Context) 과부하 걱정도 없습니다.

🖱️ 컴퓨터 제어 | 현재 macOS만 지원합니다. Agent는 권한을 부여받은 접근성 (Accessibility) 및 화면 녹화 권한을 활용하여 현재 데스크톱을 관찰하고, AX 요소와 창을 식별하며, 앱 열기/전환, 클릭, 입력, 스크롤, 드래그, 메뉴, 대화 상자, 창 이동/크기 조절/닫기 등의 작업을 수행할 수 있습니다. 우측의 Mac Control 패널은 데스크톱 상태를 실시간으로 미러링합니다. 부작용(Side effect)이 있는 모든 동작은 통합 도구 승인 프로세스를 거칩니다.

👥 Agent Team (멀티 에이전트 협업) | 설정에서 팀 템플릿(멤버 역할, 연결된 Agent, 기본 작업 템플릿)을 미리 구성할 수 있으며, 모델은 필요에 따라 한 마디로 전문가 그룹을 구성할 수 있습니다. 멤버 간에는 메시지를 주고받으며 협업을 추진할 수 있고, 완료 후에는 트랜스크립트 (Transcript)가 메인 대화로 자동 요약되어 돌아옵니다.

🗓️ 자연어 예약 작업 | "매일 아침 8시에 일일 보고서를 써줘", "매주 월요일에 지난주 할 일을 정리해줘", "평일 매시간 메일을 확인해줘"와 같은 명령이 가능합니다. 정해진 시간에 자동으로 실행되며, 결과물은 원하는 IM 채널로 전송할 수 있습니다. Cron은 데몬 (Daemon) 또는 데스크톱 GUI 환경 모두에서 안정적으로 작동합니다.

📊 Dashboard + Recap (대시보드 및 복기) | 내장 데이터 대시보드를 제공합니다: 비용 / 토큰 (Token) / 활성도 히트맵 / 건강도 4차원 시각화와 함께, 새로운 Plan 서브 패널(상태 분포, 완료율, Agent / 프로젝트별 그룹화, 30일 생성 추세, 평균 실행 시간)이 추가되었습니다. /recap 명령을 통해 지난 N일간의 세션을 심층 복기하여 11개의 AI 섹션 보고서(Agent 도구 최적화 제안, 기억 및 스킬 추천, 비용 최적화 포함)를 생성하며, 독립된 HTML 파일로 내보내 공유할 수 있습니다.

🔌 MCP 클라이언트 (OAuth 2.1) | Model Context Protocol (MCP) 클라이언트가 내장되어 있으며, 네 가지 전송 방식(stdio / Streamable HTTP / SSE / WebSocket)을 모두 지원합니다. 완전한 OAuth 2.1 + PKCE 프로세스(자동 디스커버리, RFC 7591 동적 등록, loopback 콜백)를 지원하며, 자격 증명은 0600 권한으로 원자적(Atomic)으로 디스크에 저장됩니다. Notion / Linear 등 표준 OAuth 서버와 원클릭으로 연동되며, 모든 아웃바운드 URL은 SSRF 정책을 엄격히 통과해야 합니다. GUI에서 claude_desktop_config.json으로부터 원클릭으로 가져올 수 있으며, 도구는 자동으로 mcp__<server>__<tool> 형식으로 메인 대화에 연결됩니다. 또한 mcp_resource / mcp_prompt 도구를 통해 수동적 데이터에 접근할 수 있으며, 장기 실행 도구는 자동으로 백그라운드화됩니다.

🔧 도구 상자 (Toolbox) | 컴퓨터 제어(현재 macOS 전용), 제어 가능한 브라우저(8가지 액션의 고수준 인터페이스, 채팅 우측의 실시간 미러링 패널을 통한 WYSIWYG 지원, Chrome이 Agent의 조작을 자동으로 따름; CDP를 통해 chromiumoxide에 직접 연결되어 런타임 의존성 없음), Canvas 캔버스, AI 그림 생성(7개 Provider), 웹 검색(8개 Provider 페일오버 지원), bash 실행(선택 사항으로 Docker 샌드박스 격리), 파일 읽기/쓰기 / grep / find, URL 미리보기, 크래시 로그, 자가 진단 기능을 포함합니다.

📑 Feishu (페이슈) 워크스페이스 심층 통합 | 40개의 feishu_* 도구가 docx 클라우드 문서(생성/읽기/수정), bitable 다차원 테이블(CRUD + 뷰 + 대시보드), drive 클라우드 드라이브(20MB 이하 업로드/다운로드, 로컬 경로는 protected-path 승인 절차 수행), wiki 지식베이스 링크 파싱, approval 승인(생성/조회/취소), calendar 일정(회의 생성/초대/수정/삭제), contact 연락처(사용자/부서 조회), hire 채용(직무/인재풀/지원)을 지원합니다. 이미 설정된 Feishu IM 채널 자격 증명을 재사용하며, skills/feishu 스킬을 통해 모델이 OKR/주간 보고/회의 예약/승인 취소 등 전형적인 업무 워크플로우를 수행할 수 있도록 지원합니다.

| ⚡ 백그라운드 장기 작업 실행 | 시간이 오래 걸리는 shell 명령 / Web 검색 / AI 그림 생성 등을 Agent가 "백그라운드에서 실행"하도록 할 수 있으며, 즉시 job_id를 반환하여 대화가 차단되지 않고 계속 이어질 수 있습니다. 백그라운드 작업이 완료되면 결과가 메인 대화로 자동 주입되거나, 모델이 능동적으로 job_status를 폴링(poll)하여 결과를 확인할 수 있습니다. 아무리 긴 작업이라도 채팅창이 멈추지 않습니다. |

🔒 도구 승인 + Docker 샌드박스 | 민감한 도구 호출은 승인 게이트웨이(Approval Gate)를 거칩니다 (타임아웃 후 자동 거부(deny) / 진행(proceed) 전략 지원, 채널 레벨의 자동 승인도 지원). 위험도가 높은 bash / 파일 쓰기 작업은 Docker 샌드박스 내에서 격리되어 실행되도록 선택할 수 있습니다. Agent에게 높은 권한을 부여해도 사고가 날 걱정이 없습니다. |

🏠 로컬 우선 · 제3자 중계 없음 | 모든 데이터는 ~/.hope-agent/에 저장됩니다: 설정, 세션, 메모리, 첨부 파일, 스킬, 로그가 모두 로컬 SQLite / 파일로 저장되며, API Key는 모델 제조사에 직접 연결됩니다. 서비스 모드에서는 Bearer Token 인증 + SSRF 3단계 전략을 사용하여 원격 접속도 제어 가능합니다. |

🛟 설정 자동 스냅샷 · 원클릭 롤백 | 모든 설정 변경은 로컬 backups/autossave/에 자동으로 스냅샷이 찍히며, 최근 50개를 보관합니다. 모델이 설정 도구를 통해 파라미터를 엉망으로 변경하더라도, 언제든지 임의의 과거 시점으로 복구할 수 있습니다. |

♻️ 크래시 자가 치유 · 3계층 생존 유지(Keep-alive) | 부모-자식 프로세스 가디언(Guardian)이 자식 프로세스의 비정상 종료를 모니터링하며, 지수 백오프(Exponential Backoff, 1s → 3s → 9s → 15s → 30s) 방식으로 자동 재실행합니다. 5회 연속 크래시 발생 시 자동으로 설정을 백업하고 LLM 자가 진단 및 자동 복구를 시도하며, 크래시 기록은 「설정 → 크래시 기록」에서 확인할 수 있습니다. server install 후에는 launchd KeepAlive / systemd Restart=on-failure와 같은 OS 레벨의 2차 보험이 추가됩니다. 설령 Guardian 자체가 kill -9로 종료되더라도 운영체제가 다시 살려냅니다. Cron / IM 채널 / MCP 연결은 각각 독립적인 워치독(watchdog)이 자동 재연결을 수행합니다. |

더 자세한 하이라이트는 CHANGELOG.md를 확인하세요.

📦 플랫폼별 전체 설치 패키지 목록: Releases

brew tap shiwenwen/hope-agent
brew install --cask hope-agent

이미 Hope Agent.app을 수동으로 설치한 경우:

brew install 뒤에 --adopt (기존 동일 버전 앱을 인수하며 재다운로드하지 않음) 또는 --force (강제 재다운로드 및 덮어쓰기)를 추가하세요.

Releases에서 Hope.Agent_*.dmg를 다운로드하여 「응용 프로그램(Applications)」 폴더로 드래그하면 됩니다.

실행 시 "손상되었거나" "개발자를 확인할 수 없습니다"라는 메시지가 뜨면 터미널에서 다음을 실행하세요:

sudo xattr -cr /Applications/Hope\ Agent.app && sudo codesign --force --deep --sign - /Applications/Hope\ Agent.app

Apple Silicon 및 Intel Mac 모두 네이티브 빌드(arm64 / x64 DMG)를 제공하며, Homebrew 또는 수동 다운로드 시 하드웨어에 맞는 버전을 자동으로 선택합니다.

데스크톱 GUI: Launchpad / 응용 프로그램 폴더 (Hope Agent 아이콘 클릭), 또는 터미널에서 open -a "Hope Agent" / hope-agent 실행
백그라운드 서비스 (HTTP/WS 데몬): hope-agent server start
ACP (IDE 통합): hope-agent acp

scoop bucket add hope-agent https://github.com/shiwenwen/scoop-hope-agent
scoop install hope-agent

Releases에서 Hope.Agent_*-setup.exe를 다운로드하여 더블 클릭으로 설치하세요. Windows 버전은 아직 충분한 테스트가 완료되지 않았으므로, 문제 발생 시 피드백을 부탁드립니다.

실행 시 "MSVCP140_1.dll을 찾을 수 없어 코드를 계속 실행할 수 없습니다" 또는 이와 유사한 VCRUNTIME140.dll / MSVCP140.dll 누락 메시지가 뜨면, Microsoft Visual C++ 2015–2022 런타임(x64)을 설치한 후 앱을 재시작하세요.

현재 x64만 지원합니다.

데스크톱 GUI: 시작 메뉴에서 「Hope Agent」를 클릭하여 실행하거나 PowerShell에서 hope-agent 실행
백그라운드 서비스 (HTTP/WS 데몬): hope-agent server start (PowerShell / cmd)
ACP (IDE 통합): hope-agent acp

yay -S hope-agent-bin # 또는 paru / 임의의 AUR helper 사용

사전 컴파일된 바이너리 버전(GitHub Release의 .deb 방식을 따름)을 사용하며, 소스 코드로부터 직접 컴파일하지 않습니다.

curl -fsSL https://shiwenwen.github.io/hope-agent-linux-repo/pubkey.gpg | \
sudo gpg --dearmor -o /usr/share/keyrings/hope-agent.gpg
echo "deb [signed-by=/usr/share/keyrings/hope-agent.gpg] https://shiwenwen.github.io/hope-agent-linux-repo/apt stable main" | \
...

sudo curl -fsSL https://shiwenwen.github.io/hope-agent-linux-repo/rpm/hope-agent.repo \
-o /etc/yum.repos.d/hope-agent.repo
sudo dnf install hope-agent # 또는 sudo yum install hope-agent

과거 명령어

sudo dnf config-manager --add-repo …는 dnf5 (Fedora 41+)에서 폐기되었습니다. 위의 curl 작성 방식은 dnf4 / dnf5 / yum / zypper 모두와 호환됩니다.

openSUSE 사용자:

sudo zypper addrepo https://shiwenwen.github.io/hope-agent-linux-repo/rpm/hope-agent.repo
sudo zypper install hope-agent

Releases에서 다운로드 (패키지명에 아키텍처 접미사가 포함되어 있으므로, 사용 중인 기기에 따라 _amd64 / _arm64 또는 .x86_64 / .aarch64를 선택하세요):

• AppImage:
  Hope.Agent_*.AppImage —— chmod +x 실행 후 즉시 실행
• Debian / Ubuntu:
  Hope.Agent_*.deb —— sudo dpkg -i Hope.Agent_*.deb
• Fedora / RHEL:
  Hope.Agent_*.rpm —— sudo rpm -i Hope.Agent_*.rpm

amd64 (x86_64) 및 arm64 (aarch64) 두 가지 네이티브 빌드를 제공하여 일반 PC, Raspberry Pi 4/5, Asahi Linux를 실행하는 Apple Silicon, Graviton / Ampere 클라우드 호스트를 지원합니다. apt와 dnf는 모두 dpkg --print-architecture / $basearch에 따라 자동으로 올바른 버전을 선택합니다.

데스크톱 GUI: 애플리케이션 메뉴에서 「Hope Agent」를 클릭하여 실행하거나, 터미널에서 hope-agent 입력
백그라운드 서비스 (HTTP/WS 데몬): hope-agent server start
ACP (IDE 통합): hope-agent acp

• 최초 실행 가이드:
  Provider 템플릿 선택 → API Key 입력 / Codex OAuth 로그인 → 대화 시작
• 데스크톱 애플리케이션에는 GitHub Releases를 통한 자동 업데이트 기능이 내장되어 있습니다. 애플리케이션 내 설정 → 정보에서 업데이트를 확인하고 원클릭으로 설치할 수 있으며, 대화창에 직접 「업그레이드」 또는 「업데이트 확인」이라고 말해도 됩니다. Homebrew / AUR / Scoop을 통해 설치한 버전도 동일하게 애플리케이션 내장 업데이터(updater)를 사용합니다. 패키지 관리자 관점의 버전 번호는 최초 설치 시의 상태를 유지하지만, 기능에는 영향을 주지 않습니다.

Hope Agent를 가정용 NAS / VPS / homelab에서 실행하고 브라우저로 Web GUI에 접속하는 시나리오:

docker run -d \
--name hope-agent \
-p 127.0.0.1:8420:8420 \
...

컨테이너가 실행되면 브라우저에서 http://127.0.0.1:8420을 열고, 온보딩(Onboarding) 가이드에 따라 Provider API Key를 설정하세요. 이미지는 linux/amd64 + linux/arm64 (Apple Silicon / Raspberry Pi 포함)를 모두 지원하며, 매 Release Tag마다 자동으로 빌드됩니다.

Docker Compose 사용법 / Ollama를 이용한 로컬 LLM 연동 / LAN 노출 / 리버스 프록시(Reverse Proxy) 및 TLS / 업그레이드 프로세스에 대한 내용은 docs/deployment/docker.md를 참조하세요.

git clone https://github.com/shiwenwen/hope-agent.git
cd hope-agent
pnpm install
...

로컬 개발 시 브라우저에서 "웹 버전"을 확인하고 실시간으로 새로고침하고 싶다면, pnpm tauri dev를 실행한 후 http://localhost:1420을 여세요.

이는 Vite 개발 서버(dev server)로, Tauri 창과 프론트엔드 HMR(Hot Module Replacement)을 공유합니다. http://localhost:8420은 내장된 HTTP/WS 서비스가 제공하는 정적 Web GUI(dist/ 내의 embedded bundle)로, 패키징된 브라우저 엔트리를 시뮬레이션하며 소스 코드의 HMR을 따르지 않습니다. 만약 로컬 서버에 API Key가 설정되어 있다면, 1420 페이지에서 8420으로 요청 시 401 에러가 발생할 수 있습니다. 개발 시에는 설정에서 서버 API Key를 임시로 비운 뒤 재시작하세요.

모드	실행 방식	시나리오
데스크톱 GUI	아이콘 더블 클릭 / pnpm tauri dev	기능이 가장 완전한 엔트리: 전체 GUI 경험을 제공하며, HTTP/WS 서비스가 내장되어 있어 데스크톱 사용과 동시에 외부 접속을 제공할 수 있음
Server + Web GUI (HTTP/WS)	server start 서브 명령어를 통해 실행; server install로 launchd / systemd에 등록하여 부팅 시 자동 실행 가능	GUI 데몬(daemon) 없이 24시간 온라인 상태를 유지하며, IM 채널 / Cron 작업이 끊기지 않음; 프론트엔드 React UI는 rust-embed를 통해 서버 바이너리에 내장되어 있어, 휴대폰 / 태블릿 / 모든 컴퓨터에서 http://<server>:port를 브라우저로 열면 즉시 완전한 Web GUI를 사용할 수 있음
ACP (stdio)	acp 서브 명령어를 통해 실행	IDE 직접 연결, ACP 프로토콜과 호환되는 에디터가 Hope Agent를 에이전트 백엔드로 호출하여 사용

세 가지 모드는 모두 동일한 ha-core 핵심 로직을 공유하며, 설정, 세션, 메모리는 모두 ~/.hope-agent/ 아래에 저장됩니다.

📦 모델 Provider |
39개 템플릿 · 206개 프리셋 모델 | 국제 · Anthropic · OpenAI · Codex · Google Gemini · OpenRouter · Azure OpenAI · Groq · Together AI · Fireworks · Perplexity · xAI Grok · Mistral · Cohere | 국내 · DeepSeek · Moonshot (Kimi) · 통의천문 (Qwen) · Doubao (Volcengine) · Zhipu GLM · MiniMax · Xiaomi MiMo | 로컬 · Ollama · 모든 OpenAI 호환 엔드포인트 |
💬 IM 채널 |
12개 · Telegram · Discord · Slack · Feishu · Google Chat · LINE · QQ Bot · Signal · iMessage · IRC · WeChat · WhatsApp |
🌐 인터페이스 언어 |
12종 · 간체 중국어 · 번체 중국어 · English · 日本語 · 한국어 · Español · Português · Русский · العربية · Türkçe · Tiếng Việt · Bahasa Melayu |

Cargo Workspace의 3 Crate 아키텍처를 따르며, 핵심 비즈니스 로직은 모두 ha-core에 있습니다:

crates/
ha-core/ Rust 핵심 라이브러리 (Tauri 의존성 없음) — 모든 비즈니스 로직이 여기에 위치
ha-server/ axum HTTP/WS 데몬 (Thin shell)
...

전체 모듈 토폴로지, 아키텍처 규약, 코딩 표준은 AGENTS.md를 참조하세요.

자세한 내용은 docs/를 확인하세요.

메인 브랜치는 활발하게 개발 중이며, Issue / PR을 환영합니다. 기여하기 전에 AGENTS.md의 "아키텍처 규약(Architecture Conventions)"과 "코딩 표준(Coding Standards)" 섹션을 반드시 읽어주세요.

자주 사용하는 명령어:

pnpm tauri dev # 데스크톱 개발
cargo check --workspace # Rust 의존성 / 타입 체크
cargo test -p ha-core -p ha-server # 핵심 테스트
...

• 🐛 Issues — 버그 보고, 기능 요청

• 💡 Discussions — 사용법 공유, 아이디어 토론, 질의응답

• ⭐ Hope Agent가 도움이 되었다면, GitHub에서 Star를 눌러주세요

• 📮 로드맵, 공식 문서 사이트 및 기타 커뮤니티 채널은 준비 중입니다

• openclaw: 로컬 AI 어시스턴트 방향성에 대한 영감

• Ollama: 로컬 대규모 언어 모델 (LLM)의 원클릭 설치 능력은 Ollama의 로컬 런타임 (Runtime) 및 OpenAI 호환 엔드포인트 (Endpoint)를 기반으로 합니다. Hope Agent는 GUI 계층의 래퍼 (Wrapper) 역할만 수행하며, Qwen / Gemma 등의 모델은 Ollama 모델 저장소를 통해 배포됩니다.

• ClawHub / SkillHub: Hope Agent를 위한 공개 스킬 (Skill) 검색 및 발견 소스 제공

• Hermes Agent (obra/superpowers로부터 간접 추적): 일부 내장된 프로그래밍 방법론 스킬은 여기서 개작되었습니다 (MIT 라이선스), 자세한 내용은 THIRD_PARTY_NOTICES.md를 참조하십시오.

• Tauri, axum, React, shadcn/ui, Streamdown, Radix UI 등의 오픈 소스 인프라스트럭처 (Infrastructure)

• 이 프로젝트를 위해 피드백, 테스트, 이슈 (Issue) 제출을 해주신 모든 분들