macOS에서 Odysseus AI 설정: Apple Silicon, Docker, Ollama

먼저 확인할 목표에 따라 Mac 경로를 선택하세요

Odysseus AI workspace가 실행되는지만 보려면 Docker가 의존성을 분리해 주는 통제된 경로입니다. Apple Silicon에서 로컬 모델을 자연스럽게 쓰려면 네이티브 경로가 보통 더 좋은 첫 테스트입니다.

항상 더 좋은 하나의 경로가 있는 것은 아닙니다. Docker는 재현 가능한 컨테이너 실행을 확인합니다. 네이티브 경로는 Mac의 로컬 모델, 파일, 도구 가까이에서 workspace가 동작하는지 확인합니다.

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

Apple Silicon 네이티브 경로: 모델 설정 전에 환경 확인

Apple Silicon 사용자는 Ollama, 로컬 모델, 파일을 같은 Mac에 두는 경우가 많아 네이티브 경로가 중요합니다. 먼저 저장소, script 실행 권한, Python 의존성, 로컬 포트를 확인하세요.

정상적인 첫 실행은 접근 가능한 로컬 UI를 보여 주고 설정 또는 로그인을 요구합니다. 생성된 비밀번호와 로컬 secret은 공개 화면에 남기지 마세요.

1. 공식 저장소 clone

script, issue, README 변경은 공식 저장소를 기준으로 합니다.

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

2. macOS launcher 실행 후 첫 오류 확인

첫 오류는 보통 권한, Python, 의존성, 포트 충돌을 알려 줍니다.

chmod +x ./start-macos.sh
./start-macos.sh

3. 로컬 UI를 열고 초기 로그인 완료

문서화된 포트에서 앱이 뜨면 그 URL을 열고 임시 자격 증명을 교체하세요.

http://127.0.0.1:7860

4. 모델 설정은 그 다음

workspace가 정상일 때 Settings에서 Ollama 또는 다른 provider를 연결하세요.

http://127.0.0.1:11434/v1

macOS Docker: 격리는 유용하지만 tradeoff가 있습니다

Docker는 Mac에서도 일회성 테스트, 의존성 격리, 서버식 검증에 유용합니다.

흔한 실수는 localhost 의미를 섞는 것입니다. 컨테이너 안의 localhost는 컨테이너이고, 호스트의 localhost는 Mac입니다.

Ollama, Metal 가속, endpoint 선택

Ollama는 보통 별도의 모델 서버입니다. Mac에서는 이 분리가 유리합니다. Ollama는 로컬 runtime에 두고 Odysseus AI는 호환 API endpoint를 바라보게 하면 됩니다.

Odysseus AI와 Ollama가 같은 Mac에서 네이티브로 실행되면 127.0.0.1을 사용하세요. Odysseus AI가 Docker 안에 있고 Ollama가 Mac host에 있으면 host.docker.internal을 사용하세요.

http://127.0.0.1:11434/v1

macOS Odysseus AI 문제 해결

시작, 네트워크, 모델 선택 순서로 확인하세요. UI가 정상 전이면 모델 오류는 대개 부차적입니다.

Mac 설치 최종 체크리스트

Mac 설치는 workspace, model endpoint, 보안 경계가 명확할 때 실제 테스트로 넘어갈 수 있습니다.

1. 깨끗한 시작 후 로컬 UI가 열린다.
2. native, Docker, remote 중 무엇인지 알고 있다.
3. Odysseus AI 전에 Ollama가 별도로 응답한다.
4. agent/document 전에 작은 모델이 작동한다.
5. 규칙 없이 workspace를 네트워크에 노출하지 않았다.