Windowsミニオンのセットアップ(旧版)
Windows PC に @geekbeer/minion を入れると、その PC をミニオンとして使えます(セルフホスト)。管理者権限が要るのは最初のセットアップと一部の操作だけで、普段の操作は一般ユーザーで行えます。
準備するもの
Section titled “準備するもの”- ミニオン専用の Windows PC
- 管理者アカウント — パッケージのインストールとセットアップに使います
- ミニオンにするユーザー — ミニオンのデータはこのユーザーのフォルダ(
%USERPROFILE%\.minion\)に置かれます。管理者アカウントと同じユーザーでもかまいません - Node.js 22 LTS 以降(22.23.4・24.22.1 以降) — セットアップは Node.js を入れません。先に nodejs.org から入れておいてください。それより前の版には Brotli の展開の不具合(CVE-2026-111497)があり、悪意のあるサーバーから届いたデータでミニオン上のコードを実行されるおそれがあります。古い版が入っている場合は新しい版を上書きで入れ、
minion-cli-win restartを実行してください - WSL(任意) — WSL のターミナルを使う場合は、セットアップの前に入れておきます
PowerShell の実行ポリシーが既定の Restricted のままだと、npm が動きません。先に次のどちらかで許可してください。
# 現在のユーザーに対して許可する(推奨)Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
# 今開いている PowerShell だけで許可するSet-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSignedRemoteSigned は、手元のスクリプトは実行でき、インターネットから取得したスクリプトには署名を求める設定です。PowerShell の代わりにコマンドプロンプト(cmd.exe)から npm を実行する場合は、この設定は要りません。
セットアップ
Section titled “セットアップ”1. HQ でミニオンを登録する
Section titled “1. HQ でミニオンを登録する”サイドバーの ミニオン を開き、ミニオンを追加 から Self-host VPS を選び、ミニオンを登録 を押します(説明には Ubuntu / Debian とありますが、Windows でもこれを選びます)。
登録すると、実行するコマンドが表示されます。Windows を選んでコピーしてください。同じコマンドは、あとからミニオンの詳細画面の セットアップコマンド でも確認できます。
2. パッケージを入れる(管理者の PowerShell)
Section titled “2. パッケージを入れる(管理者の PowerShell)”npm install -g @geekbeer/minion終わったら、管理者の PowerShell を開き直します(新しく入った minion-cli-win コマンドを読み込むため)。
3. セットアップを実行する(管理者の PowerShell)
Section titled “3. セットアップを実行する(管理者の PowerShell)”minion-cli-win setup最初に確認を求められるので yes と入力します。PC にユーザーが複数いる場合は、どのユーザーをミニオンにするかを番号で選びます。
セットアップは次のことを行います(数分かかります)。
- Git と Claude Code を入れる
- ミニオンを Windows のサービスとして登録する
- 画面共有(TightVNC)を、ミニオンのユーザーがサインインしたときに起動するよう登録する。WSL があれば、WSL のターミナルも同じように登録する
- 画面共有を HQ に中継する部品(websockify)を入れる。Python が無ければ python.org から入れる
- HQ との接続に使う Cloudflare Tunnel(cloudflared)を入れる
- スクリーンセーバー・復帰時のロック・スリープ・ディスプレイの電源オフを無効にする
- ファイアウォールに受信の規則を足す
4. HQ に接続する(ミニオンのユーザーの PowerShell)
Section titled “4. HQ に接続する(ミニオンのユーザーの PowerShell)”ミニオンにするユーザーでサインインし、管理者ではない PowerShell で、HQ が表示したコマンドの後半(configure)を実行します。
minion-cli-win configure ` --hq-url https://<HQ の URL> ` --minion-id <ミニオン ID> ` --api-token <API トークン> ` --setup-tunnel--setup-tunnel は外さないでください。 HQ はこのトンネルを通ってミニオンにつながるので、外すと HQ からターミナル・画面・ファイルが使えません。HQ が表示するコマンドには含まれています。
configure は接続情報を保存し、ミニオンと画面共有を起動して、HQ に接続を知らせます。
5. AI にサインインする
Section titled “5. AI にサインインする”ミニオンが仕事をするには、AI(LLM)を使えるようにしておく必要があります。HQ のミニオンの画面から画面共有(VNC)でミニオンの PC に入り、PowerShell で claude を実行してサインインしてください。使う AI を切り替える方法は LLMプラグイン を参照してください。
6. 確かめる
Section titled “6. 確かめる”ミニオン ページで、ミニオンがオンラインになっていれば完了です。PC の側でも確かめられます。
minion-cli-win status # ミニオンの状態minion-cli-win health # ヘルスチェック再起動しても動くようにする
Section titled “再起動しても動くようにする”画面共有と WSL のターミナルは、ミニオンのユーザーがサインインしている間だけ 動きます。PC を再起動したあとも使えるように、ミニオンのユーザーで自動的にサインインするよう Windows を設定してください。ディスプレイをつながずに置く場合は、ディスプレイをつながずに使う も参照してください。
minion-cli-win status # ミニオンの状態minion-cli-win health # ヘルスチェックminion-cli-win daemons # サービスと画面共有の状態minion-cli-win diagnose # 詳しい診断minion-cli-win restart # ミニオンを再起動するminion-cli-win stop # ミニオンを止めるminion-cli-win start # ミニオンを起動するminion-cli-win version # バージョン管理者の PowerShell が必要な操作が2つあります。
minion-cli-win restart --all # すべてのサービスと画面共有を起動し直すminion-cli-win stop --force # 普通の stop が効かないときに、強制的に止めるrestart --all— 再起動や Windows Update のあと、ミニオンがオフラインのまま戻らないときに使います。普通のrestartはミニオン本体だけを起動し直すので、HQ との接続(cloudflared)が止まっていると戻りませんstop --force— 更新に失敗したときなど、stopが効かない場合に使います。進行中の仕事は中断されます。詳しくは Windowsミニオンが停止できない を参照してください
ログはミニオンのユーザーの %USERPROFILE%\.minion\logs\ にあります。
Get-Content $env:USERPROFILE\.minion\logs\service-stdout.log -Tail 50Get-Content $env:USERPROFILE\.minion\logs\service-stderr.log -Tail 50Get-Content $env:USERPROFILE\.minion\logs\cloudflared-stderr.log -Tail 50 # HQ との接続HQ のミニオンの詳細画面に v〜 に更新 が出ていたら、それを押すと更新されます。更新のあとにミニオンが起動しなくなった場合は、困ったとき を参照してください。
HQ の Re-register で接続情報を作り直した場合は、表示されたコマンドで configure をもう一度実行します。このとき、コマンドに --setup-tunnel が無ければ付け足してください。
アンインストール
Section titled “アンインストール”管理者の PowerShell で実行します。
minion-cli-win uninstall # ミニオンを取り除く(--keep-data を付けると接続情報を残す)npm uninstall -g @geekbeer/minion # パッケージを取り除くNode.js・Claude Code・TightVNC・Git・Python・cloudflared は残ります。不要なら Windows の「アプリ」から個別に削除してください。
ディスプレイをつながずに使う
Section titled “ディスプレイをつながずに使う”ミニ PC などをディスプレイなしで置くと、画面共有が映す画面が無いため、HQ の画面共有が真っ黒になります。
HDMI ダミープラグ(ヘッドレスディスプレイアダプタ)を HDMI 端子に挿すと、Windows がディスプレイがつながっていると認識し、画面共有が映るようになります。数百円から手に入り、設定の変更は要りません。
画面が小さく映る場合
Section titled “画面が小さく映る場合”ダミープラグを挿すと、画面共有の画面が 4分の1ほどに縮んで 映ることがあります(クリックの位置は元のまま)。
安価なダミープラグの多くは 4K などの高い解像度を Windows に伝えるため、Windows が表示スケールを 150〜200% に上げてしまうのが原因です。ダミープラグによっては、解像度を 1920x1080 に変えても挿し直すと元に戻ります。
対処 1: 表示スケールを 100% にする(推奨) — ミニオン専用の PC なら文字の見やすさは気にしなくてよいので、設定 → ディスプレイ → 拡大縮小とレイアウト で 100% にします。サインアウトしてサインインし直す(または再起動する)と反映されます。
# 今の設定を確かめる(96=100%, 120=125%, 144=150%, 192=200%)Get-ItemProperty 'HKCU:\Control Panel\Desktop\WindowMetrics' -Name AppliedDPI対処 2: TightVNC を表示スケールに対応しないモードで動かす
$tvnPath = 'C:\Program Files\TightVNC\tvnserver.exe'if (-not (Test-Path $tvnPath)) { $tvnPath = "$env:USERPROFILE\.minion\tightvnc\PFiles\TightVNC\tvnserver.exe" }New-Item -Path "HKCU:\Software\Microsoft\Windows NT\CurrentVersion\AppCompatFlags\Layers" -ForceSet-ItemProperty -Path "HKCU:\Software\Microsoft\Windows NT\CurrentVersion\AppCompatFlags\Layers" ` -Name $tvnPath -Value "~ DPIUNAWARE"設定したら、管理者の PowerShell で画面共有を起動し直します。
Stop-Process -Name tvnserver -Force -ErrorAction SilentlyContinueschtasks /Run /TN MinionVNC対処 3: 解像度を書き換えられるダミープラグを使う — 「EDID 書き換え対応」の製品(Headless Ghost など)なら、1920x1080 などの解像度に固定できます。少し高価(数千円〜)です。
npm が「スクリプトの実行が無効」で失敗する
Section titled “npm が「スクリプトの実行が無効」で失敗する”npm : このシステムではスクリプトの実行が無効になっているため、ファイル C:\Program Files\nodejs\npm.ps1 を読み込むことができません。PowerShell の実行ポリシーが Restricted のままです。準備するもの のとおりに許可するか、コマンドプロンプト(cmd.exe)から実行してください。
minion-cli-win が見つからない
Section titled “minion-cli-win が見つからない”minion-cli-win : 用語 'minion-cli-win' は、コマンドレット、関数、スクリプト ファイル、または操作可能なプログラムの名前として認識されません。npm install -g のあと、PowerShell を開き直してください。ミニオンのユーザーで見つからない場合は、一度サインアウトしてサインインし直します。それでも見つからなければ、npm のコマンドの置き場所を PATH に足してから開き直します。
[Environment]::SetEnvironmentVariable('PATH', [Environment]::GetEnvironmentVariable('PATH', 'User') + ';' + (npm prefix -g), 'User')ターミナルの部品(node-pty)が入らない
Section titled “ターミナルの部品(node-pty)が入らない”セットアップは、ターミナルの部品をパッケージのフォルダに入れます。失敗した場合は、管理者の PowerShell で同じ場所に入れ直してください。
Set-Location "$(npm prefix -g)\node_modules\@geekbeer\minion"npm install node-pty-prebuilt-multiarchそれでも失敗する場合は、Visual Studio Build Tools を入れてから npm install node-pty を実行します。
npm install -g の途中で better-sqlite3 のビルドエラーが出る
Section titled “npm install -g の途中で better-sqlite3 のビルドエラーが出る”そのままで問題ありません。better-sqlite3 は無くても動く部品で、インストールは成功しています。ミニオンは Node.js に組み込みのデータベースを代わりに使います。
ミニオンが起動しない
Section titled “ミニオンが起動しない”診断のコマンドとログで原因を確かめてください。
minion-cli-win diagnoseminion-cli-win daemons更新のあとにミニオンが起動しない
Section titled “更新のあとにミニオンが起動しない”Error: Cannot find module './refs/data.json' のようなエラーで起動しない場合は、更新中にファイルの一部が置き換わらなかったことが原因です。管理者の PowerShell で、止めてから入れ直します。
minion-cli-win stop --forcenpm install -g @geekbeer/minion@latestminion-cli-win restart --allstop --force も効かない場合は、Windowsミニオンが停止できない の手順で止めてください。更新のログは %USERPROFILE%\.minion\logs\update-agent.log にあります。
再起動のあと、ミニオンがオフラインのまま
Section titled “再起動のあと、ミニオンがオフラインのまま”- 管理者の PowerShell で
minion-cli-win restart --allを実行する - ミニオンのユーザーでサインインしているか確かめる(再起動しても動くようにする)
- それでも戻らなければ、HQ との接続のログ(
cloudflared-stderr.log)を確かめる。%USERPROFILE%\.cloudflared\config.ymlが無い場合は、--setup-tunnelを付けてconfigureをやり直す
画面共有(VNC)につながらない
Section titled “画面共有(VNC)につながらない”「Server is not configured properly」と出る — TightVNC の設定を確かめます。ミニオンのユーザーの設定(HKCU)と PC 全体の設定(HKLM)の両方を見てください。
foreach ($root in 'HKCU', 'HKLM') { Get-ItemProperty "${root}:\Software\TightVNC\Server" -ErrorAction SilentlyContinue | Select-Object PSPath, UseVncAuthentication, LoopbackOnly, AllowLoopback}期待する値は UseVncAuthentication=0、LoopbackOnly=1、AllowLoopback=1 です。違っていれば、管理者の PowerShell で minion-cli-win setup をもう一度実行してください。そのあと、画面共有を起動し直します。
Stop-Process -Name tvnserver -Force -ErrorAction SilentlyContinueschtasks /Run /TN MinionVNC中継の部品(websockify)が動いていない — Python が入っていなかった可能性があります。Python を入れてから、管理者の PowerShell で minion-cli-win setup をもう一度実行してください。
winget install Python.Python.3.12ポートを確かめる
netstat -an | Select-String "5900" # TightVNCnetstat -an | Select-String "6080" # websockify