Odysseus AIのインストール方法と実行手順：安全に初回ログインするまで

Docker、ネイティブ、OS別ガイドを先に選ぶ

公式プロジェクトでは、多くの利用者にとってDocker Composeが再現しやすい開始方法です。アプリと補助サービスを決められたスタックで動かせるため、クリーンな再構築もしやすくなります。ただし、コンテナ内のlocalhostはブラウザーやホストOSのlocalhostと同じではありません。

ネイティブ構成は、プロセスを直接確認したい場合、Pythonレベルでデバッグしたい場合、またはOS固有のローカルアクセラレーションを使いたい場合に向いています。その代わり、Python環境、依存関係、ポート、ログの管理を自分で行います。WindowsではWSL2、Docker Desktop、PowerShell、Ollamaが別々のネットワーク境界になるため、専用ガイドを優先してください。

インストール前に環境を確認する

初回起動の失敗は、アプリではなく環境が原因であることがよくあります。リポジトリを取得する前に、アプリの場所、永続データの場所、モデルを同じマシンで動かすかどうかを決めてください。最初からすべての連携を追加せず、ワークスペースだけの起動を基準にすると原因を絞れます。

コード、コンテナ、ログ、モデル、文書データのための空き容量も確認します。ローカルモデルのRAMやVRAMは、ワークスペース本体の要件とは別です。初回のブラウザー確認は同じマシンのlocalhostで行い、LAN、リバースプロキシ、Tailscale、公開アクセスは認証を確認してからにします。

• 選んだ経路に必要なGit、Docker Compose、Pythonなどを確認する。
• リポジトリ、.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ガイドにあるホスト向けのエンドポイントを使い、アプリと同じネットワーク位置からテストしてください。

検索も別のサービス境界です。Composeに含まれるSearXNGはサービス名で参照できる場合がありますが、外部のSearXNGにはOdysseusから到達できるURLが必要です。画面が開くだけではモデルや検索の成功を意味しないため、小さなモデル要求と検索テストを別々に行います。

実際の作業前に初回ログインを確認する

初回ログインは運用上のチェックポイントです。現在の起動経路が示すローカルポートを開き、今起動したワークスペースであることを確認してから、一時的な管理者パスワードを変更します。空白ページやプロキシを見た場合は、まず直接のlocalhostへ戻って確認します。

認証後はSettingsで必要なサービスが見えているか確認します。機密ファイルを使わない短い要約などで、ブラウザー、ワークスペース、モデルの経路を小さくテストしてください。計画や変更内容を理解できない場合は承認せず停止します。

1. ローカルページへ接続

   現在の公式手順とログが示すポートを使い、古い記事のURLをそのまま信用しない。

2. 認証情報を変更

   LAN、VPN、リバースプロキシを試す前に、生成された管理者パスワードを交換する。

3. モデルをテスト

   短いプロンプトを送り、意図したプロバイダーとモデルが選ばれているか確認する。

4. ワークフローをテスト

   サンプルのワークスペースで計画とファイルアクセスを確認し、最初は手動承認を維持する。

再現できる起動手順を作る

安定した起動では、環境準備、アプリ起動、サービス接続、ユーザー承認を分けて考えます。混ぜてしまうとすべてがモデルのエラーに見えます。分ければ、プロセス、ポート、エンドポイント、権限のどこで失敗したかを判断できます。

リポジトリのそばに小さな手順書を置き、選んだ経路、ローカルURL、確認したブランチやコミット、モデルと検索のURL、データフォルダー、停止コマンドを記録してください。

よくある起動エラーを切り分ける

初回の問題は、プロセスが健康でない、ブラウザーが違うポートを見ている、コンテナ内のlocalhostを誤解している、オプションサービスに到達できない、またはボリュームや認証の設定をアプリの不具合と考えている、のいずれかに分かれます。最小の失敗層から確認し、一度に複数の変数を変えないでください。

動画やコミュニティ記事を使う場合は、ブランチ、ポート、環境変数、サービス名を公式リポジトリと比較します。古い手順を無理に動かすより、現在サポートされる手順との差分を見つける方が安全です。

制御を失わずに更新する

現在の手順を読まずに使える万能な更新コマンドはありません。pullやコンテナ再構築の前に重要なデータをバックアップし、確認済みのブランチやコミットを記録し、環境変数やサービス名の変更を確認します。ボリューム、文書、認証情報がある場合、再構築は状態を持つ操作です。

Dockerでは再作成前にスタックを停止して確認します。ネイティブでは理解している変更とPython環境を保ち、依存関係を意図的に更新します。localhostの外へ公開するなら、認証、HTTPS、ネットワーク制御、ロールバック手順を先に準備してください。