Odysseus AIをmacOSでセットアップ: Apple Silicon、Docker、Ollama

最初に確認したい目的でMacの手順を選ぶ

Odysseus AIのワークスペースが起動するかだけを確認するなら、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上で扱うことが多いため、ネイティブ手順が重要です。まずリポジトリ、スクリプト権限、Python依存関係、ローカルポートを確認します。

正常な初回起動では、ローカルUIが開き、設定またはログインに進めます。生成されたパスワードやsecretは一時的な運用情報として扱い、公開スクリーンショットに含めないでください。

1. 公式リポジトリをcloneする

setup 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などを接続します。

http://127.0.0.1:11434/v1

macOSのDocker: 隔離は便利だがendpointに注意

DockerはMacでも、一時的な検証、依存関係の隔離、サーバーに近い検証には有効です。

よくある失敗はlocalhostの意味を混同することです。コンテナ内のlocalhostはコンテナ自身、ホスト側のlocalhostはMac自身です。

Ollama、Metalアクセラレーション、endpointの選び方

Ollamaは通常、Odysseus AIとは別のモデルサーバーです。Macではこの分離が役立ち、Ollamaをローカルruntime側に置いたままOdysseus AIを互換APIへ向けられます。

Odysseus AIとOllamaが同じMacでネイティブ実行なら127.0.0.1を使います。Odysseus AIがDocker内、OllamaがMacホストなら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をネットワーク公開していない。