Odysseus AI 설치 및 실행 방법: 경로 선택부터 첫 로그인까지

Docker, 네이티브 또는 플랫폼 가이드를 먼저 선택하세요

공식 프로젝트는 많은 사용자에게 Docker Compose를 반복 가능한 시작점으로 제시합니다. 애플리케이션과 보조 서비스를 정해진 스택 안에서 실행할 수 있어 깨끗한 재구성이 쉽습니다. 다만 컨테이너 안의 localhost는 브라우저나 호스트 운영체제의 localhost와 자동으로 같지 않습니다.

네이티브 구성은 프로세스를 직접 제어하거나 Python을 디버깅하거나 운영체제의 로컬 가속을 활용할 때 유리합니다. 대신 Python 환경, 의존성, 포트, 로그를 직접 관리해야 합니다. Windows에서는 WSL2, Docker Desktop, PowerShell, Ollama가 여러 네트워크 층을 만들 수 있으므로 Windows 전용 가이드를 우선하세요.

설치 전에 환경을 점검하세요

첫 실행 실패는 애플리케이션보다 환경에서 발생하는 경우가 많습니다. 저장소를 복제하기 전에 애플리케이션 위치, 영속 데이터 위치, 모델 서버 위치를 정하세요. 첫 부팅부터 모델, 프록시, LAN, 검색을 모두 추가하지 말고 워크스페이스만 실행해 기준 상태를 만드세요.

코드, 컨테이너, 로그, 모델, 문서에 필요한 저장 공간을 확보하세요. 로컬 모델의 RAM과 VRAM은 워크스페이스 요구 사항과 별개입니다. 첫 브라우저 테스트는 같은 컴퓨터의 localhost에서 진행하고, LAN·VPN·리버스 프록시는 관리자 비밀번호를 변경한 뒤에 검토하세요.

• 선택한 경로에 필요한 Git, Docker Compose 또는 네이티브 런타임을 확인합니다.
• 저장소, .env, 볼륨, 로그, 백업을 둘 영속 폴더를 정합니다.
• 첫 테스트는 localhost에 유지하고 습관적으로 0.0.0.0에 바인딩하지 않습니다.
• Ollama와 SearXNG를 호스트, Docker, 다른 컴퓨터 중 어디에서 실행할지 적습니다.
• 현재 공식 README와 설정 가이드의 명령을 비교합니다.

워크스페이스를 설치하고 실행하세요

첫 시도에는 Docker가 반복 가능한 기준 상태를 만들기 쉽습니다. 공식 저장소를 복제하고 현재 README를 읽은 뒤 예시 환경 파일을 필요에 따라 복사하고 Compose를 실행합니다. 오래된 튜토리얼의 버전이나 존재하지 않는 스크립트를 그대로 전제하지 마세요.

네이티브 구성에서는 호환되는 Python 환경을 만들고 문서에 나온 의존성을 설치한 다음 설정과 애플리케이션 프로세스를 실행합니다. Windows에서는 Linux 명령과 PowerShell 명령을 섞지 말고 프로젝트의 Windows 런처를 사용하세요.

1. 먼저 기본 구성만 실행

   프록시, LAN, 모델, 검색을 동시에 추가하지 말고 정상적인 워크스페이스 프로세스를 확인합니다.

2. 포트를 바꾸기 전에 로그 확인

   브라우저가 연결되지 않으면 프로세스가 의존성 로딩 중 종료되지 않았는지 먼저 확인합니다.

3. 브랜치 기록

   공식 프로젝트의 개발 브랜치와 정리된 브랜치가 다를 수 있으므로 현재 README를 확인합니다.

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
./start-macos.sh

Ollama와 검색 서비스를 따로 연결하세요

워크스페이스가 열리면 모델 백엔드를 연결합니다. Odysseus와 Ollama를 같은 호스트에서 네이티브로 실행하면 localhost가 맞을 수 있습니다. Odysseus가 Docker이고 Ollama가 호스트에 있다면 localhost는 보통 컨테이너를 가리킵니다. Docker 가이드의 호스트 게이트웨이 주소를 사용하고 애플리케이션과 같은 네트워크 위치에서 테스트하세요.

검색은 별도의 서비스 경계입니다. 포함된 SearXNG는 Compose 서비스 이름으로 접근할 수 있지만 외부 인스턴스는 Odysseus에서 접근 가능한 URL이 필요합니다. 화면이 열린다고 모델과 검색이 성공한 것은 아니므로 두 서비스를 작은 테스트로 각각 확인하세요.

실제 작업 전에 첫 로그인을 확인하세요

첫 로그인은 운영 확인 단계입니다. 현재 경로가 알려주는 로컬 포트를 열고 방금 실행한 인스턴스인지 확인한 뒤 임시 관리자 비밀번호를 즉시 변경하세요. 빈 페이지나 리버스 프록시가 보이면 먼저 직접적인 로컬 주소로 돌아가세요.

로그인 후 Settings에서 필요한 서비스가 보이는지 확인합니다. 민감한 파일이 필요 없는 짧은 작업을 실행하고 응답과 계획을 읽으세요. 제안된 변경을 이해하지 못하면 승인하지 말고 중지합니다.

1. 로컬 페이지 접속

   현재 공식 절차와 로그에 표시된 포트를 사용하고 오래된 글의 주소를 그대로 믿지 않습니다.

2. 인증 정보 변경

   LAN, VPN, 리버스 프록시를 시험하기 전에 생성된 비밀번호를 바꿉니다.

3. 모델 테스트

   짧은 프롬프트를 보내 선택한 제공자와 모델을 확인합니다.

4. 워크플로 테스트

   예제 작업 공간에서 계획과 파일 접근을 검토하고 처음에는 수동 승인을 유지합니다.

반복 가능한 실행 절차를 만드세요

안정적인 실행은 컴퓨터 준비, 애플리케이션 시작, 서비스 연결, 사용자 승인으로 나뉩니다. 이를 섞으면 모든 문제가 모델 오류처럼 보입니다. 선택한 경로, 로컬 URL, 테스트한 브랜치나 커밋, 모델·검색 엔드포인트, 데이터 폴더, 중지 명령을 작은 실행 기록으로 남기세요.

이 기록은 다음 재시작을 기억에 의존하지 않는 절차로 바꿉니다. Docker, Ollama, SearXNG, 프록시가 서로 다른 네트워크를 사용할 때 특히 유용합니다.

자주 발생하는 실행 오류를 해결하세요

첫 실행 오류는 프로세스 상태, 잘못된 포트, 컨테이너 안에서 해석된 localhost, 접근할 수 없는 선택 서비스, 볼륨이나 인증 정보의 오해로 나뉩니다. 가장 작은 실패 계층부터 확인하고 한 번에 여러 변수를 바꾸지 마세요.

커뮤니티 영상이나 글을 참고할 때는 브랜치, 포트, 환경 변수, 서비스 이름을 공식 저장소와 비교합니다. 유용한 튜토리얼도 현재 상태와 다를 수 있습니다.

통제된 방식으로 업데이트하세요

현재 프로젝트 지침을 읽지 않고 사용할 수 있는 만능 업데이트 명령은 없습니다. pull이나 재빌드 전에 중요한 데이터를 백업하고 테스트한 브랜치나 커밋을 기록하며 환경 변수와 서비스 이름 변경을 확인하세요. 볼륨과 문서, 인증 정보가 있으면 재빌드는 상태를 가진 작업입니다.

Docker에서는 스택을 중지하고 확인한 뒤 다시 만드세요. 네이티브에서는 이해한 변경과 Python 환경을 유지하고 의존성을 의도적으로 업데이트합니다. localhost 밖으로 공개하기 전에는 인증, HTTPS, 네트워크 제어, 롤백 계획을 준비하세요.