ここまでOmnigentをmacOSで動かしてきましたが、日本のお客様の環境はほとんどがWindowsです。macOS前提の手順だけでは実務で使えないので、Windowsで動かす方法を検証しました。
結論を先に書くと、実用するならWSL2です。Windowsネイティブでも起動はしますが、モデルに繋がらないので実質使えません。ただ、なぜ使えないのかを知っておくと判断が早くなるので、両方を順に見ていきます。
最後に、Databricksワークスペースとの連携も扱います。ここには段階が2つあり、混同しやすいので分けて説明します。
検証環境と前提
Windows 11、日本語環境で検証しました。Omnigentのバージョンは0.14.0です。
先に断っておくと、公式にWindows専用の手順はありません。ドキュメントはmacOSとLinuxを前提にしていて、WindowsについてはGitHubのREADMEに「ネイティブでも degraded mode で動くが、一部のPOSIX依存のワークフローには Linux、macOS、またはWSLが必要」と書かれている程度です。
その degraded mode が実際どこまで使えるのか、というのが前半の話になります。
Windowsネイティブを試す
まずネイティブから試しました。uv が入っていれば、インストール自体は一行です。
uv tool install --python 3.12 omnigent
POSIX向けの install.sh はPowerShellでは動かないので使いません。インストール後に omnigent が見つからない場合は、ターミナルを開き直してください。PATHの反映が要ります。
日本語環境では起動すらしない
インストールが済んだので、Debbyを起動してみます。
omni debby
ここで落ちました。
UnicodeDecodeError: 'cp932' codec can't decode byte 0x94 in position 10: illegal multibyte sequence
cp932 は日本語WindowsのデフォルトのANSIコードページです。Omnigentがエージェント定義のYAMLを読むときにエンコーディングを指定していないため、Pythonがロケール既定の cp932 で読もうとして、UTF-8のバイト列を解釈できずに落ちています。
これはWindows固有というより、非UTF-8ロケール環境で read_text() にエンコーディングを指定していない実装漏れです。英語環境なら偶然通るかもしれませんが、日本語環境では確実に踏みます。
回避策は環境変数を1つ設定することです。
$env:PYTHONUTF8 = "1"
omni debby
Python 3.7以降はこれでUTF-8モードになり、既定のエンコーディングがUTF-8になります。これで起動しました。サーバーもWeb UIもTUIも問題なく立ち上がります。
日本語Windowsで試す方は、まずこの環境変数を設定してください。これを知らないと、最初の一歩で意味不明なエラーに遭って終わります。
モデルに繋がらない
起動はしましたが、画面には「Claude → not configured · Codex → not configured」と出ています。認証がまだなので、omni setup で設定しようとしました。
omni setup
ここで最初の壁に当たります。画面の冒頭にこう表示されました。
! Some harnesses need external tools:
• tmux not found — native Claude/Codex need tmux (macOS: `brew install tmux`).
ネイティブのClaude/Codexハーネスにはtmuxが必要で、しかも案内されているのはmacOSのbrewコマンドだけです。tmuxはWindowsネイティブには存在しないので、この時点でネイティブハーネスは使えません。
それでもCLIだけは入るかと思い、Claudeを選んでみました。出てきた選択肢はこれだけです。
1. Yes — install (curl -fsSL https://claude.ai/install.sh | bash)
2. No — back to harnesses
3. I'll run it myself (show the command)
bash です。PowerShellにbashはないので、実行すると即座に失敗します。
Install failed. Run it manually, then re-open: curl -fsSL https://claude.ai/install.sh | bash
手動で実行しろと案内されますが、そのコマンドもbashなので実行できません。つまりClaude CLIは入り口の時点で塞がれています。
さらに問題なのは、この選択肢にAPIキーを登録する道がないことです。omni setup は「CLIがある前提」で作られていて、CLIが無い状態では認証情報の登録に進めません。
環境変数でAPIキーを渡しても403
正規ルートが塞がれているので、環境変数でAPIキーを渡してみました。
$env:ANTHROPIC_API_KEY = "sk-ant-..."
omni debby
画面には「🔑 Anthropic API Key」と表示され、検出はされています。ところが実際に質問を投げると、こうなりました。
Failed to authenticate. API Error: 403 Invalid access token.
キー自体が無効なのかと思い、Omnigentを通さず直接叩いて確認しました。
$headers = @{
"x-api-key" = $env:ANTHROPIC_API_KEY
"anthropic-version" = "2023-06-01"
"content-type" = "application/json"
}
$body = '{"model":"claude-sonnet-4-6","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'
Invoke-RestMethod -Uri "https://api.anthropic.com/v1/messages" -Method Post -Headers $headers -Body $body
こちらは正常に応答が返りました。キーは有効です。つまりOmnigent側がWindowsで環境変数のキーを正しく扱えていない、ということになります。
ネイティブの結論
整理すると、Windowsネイティブの状況はこうです。
サーバー、Web UI、TUIは起動します。ただし日本語環境では PYTHONUTF8=1 が必須です。一方で、ネイティブCLIハーネスはbashとtmuxの壁で使えず、omni setup にAPIキー登録の導線もなく、環境変数で渡したキーは403になります。加えて、第3弾で扱ったOmnibox(OSサンドボックス)もWindowsでは効きません。
起動するがモデルに繋がらないので、実用は不可という結論になります。
WSL2で動かす
ここからが本題です。WSL2ならLinuxの手順がそのまま通ります。
WSL2を入れる
管理者権限のPowerShellで実行します。ここは会社PCだと権限の確認が先に必要かもしれません。
wsl --install
WSL本体のインストールと仮想化機能の有効化が行われ、再起動を求められます。再起動後、ディストリビューションを入れます。
wsl --install -d Ubuntu
これでもう一度再起動が入ります。再起動が2回必要なのは地味に面倒ですが、ここを越えれば後は素直です。
Ubuntuが起動すると、Unixユーザー名とパスワードの設定を求められます。ここで設定するのはLinux側のアカウントで、Windowsのものとは別です。このパスワードは後で sudo を使うときに必要になります。
前提ツールを揃える
Ubuntuのプロンプトが出たら、パッケージを更新します。
sudo apt update && sudo apt upgrade -y
Omnigentが必要とするツールを確認します。
sudo apt install -y tmux bubblewrap curl
ここで気持ちのいい発見がありました。tmuxもbubblewrapも、すでに入っています。
tmux is already the newest version (3.6a-2ubuntu0.1).
bubblewrap is already the newest version (0.11.1-1ubuntu0.1).
Windowsネイティブで「tmux not found」と言われて詰んだものが、WSL2では最初から揃っている。ここが両者の分かれ目です。bubblewrapはLinuxでのサンドボックス(Omnibox)に必要なので、これも重要です。
Node.js 22 LTSを入れます。
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version
Pythonはディストリビューションに入っているものを使います。
Omnigentを入れる
公式インストーラがそのまま使えます。
curl -fsSL https://omnigent.ai/install.sh | sh
ネイティブではClaude CLIのインストーラがbash依存で失敗しましたが、ここでは公式インストーラ自体が問題なく走ります。uvが無ければ自動で入れてくれます。
インストール直後に omni が見つからないことがあります。
Command 'omni' not found
PATHの設定が現在のシェルに反映されていないだけなので、読み込み直します。
source ~/.bashrc
これでも駄目なら、いったん exit してWSLに入り直せば確実です。
認証を設定する
omni setup
Node.jsを入れ忘れていると、ここで「node not found — Claude, Codex, and Pi need Node.js 22 LTS or newer」と警告が出ます。入れてあれば警告なしで一覧が表示されます。
Claudeを選ぶと、ネイティブと同じくCLIのインストールを聞かれます。ただし今度はbashがあるので実際に走ります。
✔ Claude Code successfully installed!
Version: 2.1.273
Location: ~/.local/bin/claude
そのまま認証情報の選択に進みます。ここがネイティブとの決定的な差です。選択肢はこれだけあります。
- Anthropic — API key
- Claude — subscription (Pro/Max)
- Gateway — custom base URL + key
- Databricks — workspace
- AWS Bedrock — API key
サブスクを選ぶとブラウザでのOAuth認証になります。WSL2からWindows側のブラウザが開いて、認証が完了します。macOSと全く同じ体験です。
npmの権限エラーに注意
Codexも設定しようとして、ここで引っかかりました。
npm error code EACCES
npm error Error: EACCES: permission denied, mkdir '/usr/lib/node_modules/@openai'
aptで入れたNode.jsは、グローバルパッケージの導入先が /usr/lib/node_modules になっていて、一般ユーザーでは書き込めません。sudoで入れる手もありますが、後々の更新で権限問題が再発しやすいので、導入先をホームに変えるのが定石です。
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex
codex --version
これで入ります。あらためて omni setup でCodexを選べば、認証情報の設定に進めます。
動作を確認する
Debbyで確認します。日本語環境でも PYTHONUTF8 は不要です。WSL2はUTF-8ロケールなので、ネイティブで踏んだcp932の問題は起きません。
omni debby
起動時にこんなメッセージが出ることがあります。
gio: http://127.0.0.1:6767/c/...: Operation not supported
WSLがブラウザを開こうとして失敗しているだけで、動作には影響しません。表示されているURLをWindows側のブラウザに貼れば、Web UIが開きます。WSL2はlocalhostをWindows側と共有するので、追加設定なしでアクセスできます。
質問を投げると、ClaudeとGPTの両方が並列で応答しました。ネイティブでは403で何も返らなかったので、ここが到達点の差になります。
Databricksワークスペースと連携する
ここからは、お客様の環境で使うことを想定した話です。個人のサブスクリプションやAPIキーではなく、ワークスペースの認証で使えるのが理想的なので、Databricks連携を試しました。
先に整理しておくと、ここには段階が2つあります。混同しやすいので分けて考えてください。
段階1は、モデル呼び出しをDatabricks経由にすることです。Unity AI Gateway にルーティングされ、利用がワークスペースで統制・課金されます。これには omni setup での登録が必要です。
段階2は、エージェントにDatabricks CLIをツールとして叩かせることです。こちらはOmnigent側の設定は不要で、シェルでCLIの認証が通っていれば足ります。
Databricks CLIを入れる
WSL内にCLIを入れます。ここで一つ詰まりました。
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sudo sh
sh: 86: unzip: not found
databricks: command not found
インストーラがzipの展開に unzip を使うのですが、Ubuntuの最小構成には入っていません。先に入れておきます。
sudo apt install -y unzip
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sudo sh
databricks --version
これで入ります。
databricks extra が必要
omni setup でDatabricksを選ぶと、こう言われました。
✗ Databricks routing needs the databricks extra — uv tool install --force "omnigent[databricks]"
公式インストーラをそのまま実行すると、Databricks連携用の依存が入りません。案内どおりに入れ直します。
uv tool install --force "omnigent[databricks]"
最初からDatabricks連携を使うと分かっているなら、インストール時に指定しておく方が手戻りがありません。
curl -fsSL https://omnigent.ai/install.sh | sh -s -- --extra databricks
段階1: モデルをDatabricks経由にする
あらためて omni setup でClaudeを選び、「+ Add a credential」から「Databricks — workspace」を選びます。ワークスペースURLを入力すると、説明が表示されます。
Routes Claude's model calls through this workspace's Databricks Unity AI Gateway (via ucode),
so usage is governed and billed there.
Claudeのモデル呼び出しをワークスペースのUnity AI Gateway経由にルーティングし、利用がそこで統制・課金される。まさに企業で使いたい形です。
ここで注意点があります。この設定はブラウザでのOAuth認証を要求します。PATで ~/.databrickscfg を設定済みでも、それとは別にサインインが走ります。
これが実務では壁になりえます。今回の検証でも、社内のワークスペースはIdPがデバイス制限をかけていて、会社支給のマシン以外からは認証が通りませんでした。SSO環境でOmnigentのDatabricks連携を使う場合は、この点を事前に確認しておく必要があります。
デバイス制限のない検証用ワークスペースで実行したところ、認証が通りました。
✔ Databricks authentication complete
✔ Unity AI Gateway connected
✔ Settings configured for Claude Code
— Installing Databricks AI Tools for claude-code...
omni setup の一覧を見ると、ClaudeもCodexもDatabricks経由に切り替わっています。
個人のサブスクリプションもAPIキーも使わず、ワークスペースの認証だけで2ベンダーが使える状態です。
段階2: CLIをツールとして叩かせる
こちらはもっと単純です。Omnigentが動いているシェルでCLIの認証が通っていれば、エージェントはそれを使えます。
Omnigentを起動して、タスクを投げてみます。
databricks CLIで現在のユーザー情報を表示してください
エージェントは ~/.databrickscfg を読んで、プロファイルが複数あることと、それぞれの認証が有効かどうかを判定した上で、どれを使うか聞いてきました。
どのプロファイルで current-user を実行しますか?
adb-xxxxxxxxxxxx — Azure Databricks。認証有効 (Valid: YES)。すぐに実行できます。
DEFAULT — 認証が無効 (Valid: NO)。実行前に再認証が必要になる可能性があります。
有効な方を選ぶと、databricks current-user me が実行され、ユーザー情報が表形式に整形されて返ってきました。
これで、モデルはDatabricks経由、CLIもエージェントから叩ける、という構成がWindows(WSL2)上で完成しました。
まとめ
Windowsで動かすなら、WSL2が答えです。ネイティブでも起動はしますが、モデルに繋がらないので実用にはなりません。
踏んだ詰まりどころを、順番にまとめておきます。
ネイティブでは、日本語環境で PYTHONUTF8=1 が必須、Claude CLIのインストーラがbash依存で実行不可、tmuxが無いのでネイティブハーネス不可、omni setup にAPIキー登録の導線なし、環境変数のAPIキーは403。
WSL2では、wsl --install に管理者権限と再起動2回、インストール後のPATHが即時反映されない、npmのグローバルインストールで権限エラー、Databricks CLIのインストーラに unzip が必要、ブラウザが自動で開かない。いずれも回避可能なものばかりです。
Databricks連携については、--extra databricks が必要なこと、そしてモデル連携にはOAuth認証が要るため、IdPのデバイス制限がある環境では別途検討が必要なことを押さえておいてください。エージェントにCLIを叩かせるだけなら、シェルで認証が通っていれば足ります。
日本の企業環境はほとんどがWindowsなので、この手順が誰かの時間の節約になれば幸いです。