コンテンツにスキップ

Windowsミニオンのセットアップ(旧版)

Windows PC に @geekbeer/minion を入れると、その PC をミニオンとして使えます(セルフホスト)。管理者権限が要るのは最初のセットアップと一部の操作だけで、普段の操作は一般ユーザーで行えます。

  • ミニオン専用の 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 が動きません。先に次のどちらかで許可してください。

Terminal window
# 現在のユーザーに対して許可する(推奨)
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
# 今開いている PowerShell だけで許可する
Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned

RemoteSigned は、手元のスクリプトは実行でき、インターネットから取得したスクリプトには署名を求める設定です。PowerShell の代わりにコマンドプロンプト(cmd.exe)から npm を実行する場合は、この設定は要りません。

サイドバーの ミニオン を開き、ミニオンを追加 から Self-host VPS を選び、ミニオンを登録 を押します(説明には Ubuntu / Debian とありますが、Windows でもこれを選びます)。

登録すると、実行するコマンドが表示されます。Windows を選んでコピーしてください。同じコマンドは、あとからミニオンの詳細画面の セットアップコマンド でも確認できます。

2. パッケージを入れる(管理者の PowerShell)

Section titled “2. パッケージを入れる(管理者の PowerShell)”
Terminal window
npm install -g @geekbeer/minion

終わったら、管理者の PowerShell を開き直します(新しく入った minion-cli-win コマンドを読み込むため)。

3. セットアップを実行する(管理者の PowerShell)

Section titled “3. セットアップを実行する(管理者の PowerShell)”
Terminal window
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)を実行します。

Terminal window
minion-cli-win configure `
--hq-url https://<HQ の URL> `
--minion-id <ミニオン ID> `
--api-token <API トークン> `
--setup-tunnel

--setup-tunnel は外さないでください。 HQ はこのトンネルを通ってミニオンにつながるので、外すと HQ からターミナル・画面・ファイルが使えません。HQ が表示するコマンドには含まれています。

configure は接続情報を保存し、ミニオンと画面共有を起動して、HQ に接続を知らせます。

ミニオンが仕事をするには、AI(LLM)を使えるようにしておく必要があります。HQ のミニオンの画面から画面共有(VNC)でミニオンの PC に入り、PowerShell で claude を実行してサインインしてください。使う AI を切り替える方法は LLMプラグイン を参照してください。

ミニオン ページで、ミニオンがオンラインになっていれば完了です。PC の側でも確かめられます。

Terminal window
minion-cli-win status # ミニオンの状態
minion-cli-win health # ヘルスチェック

画面共有と WSL のターミナルは、ミニオンのユーザーがサインインしている間だけ 動きます。PC を再起動したあとも使えるように、ミニオンのユーザーで自動的にサインインするよう Windows を設定してください。ディスプレイをつながずに置く場合は、ディスプレイをつながずに使う も参照してください。

Terminal window
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つあります。

Terminal window
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\ にあります。

Terminal window
Get-Content $env:USERPROFILE\.minion\logs\service-stdout.log -Tail 50
Get-Content $env:USERPROFILE\.minion\logs\service-stderr.log -Tail 50
Get-Content $env:USERPROFILE\.minion\logs\cloudflared-stderr.log -Tail 50 # HQ との接続

HQ のミニオンの詳細画面に v〜 に更新 が出ていたら、それを押すと更新されます。更新のあとにミニオンが起動しなくなった場合は、困ったとき を参照してください。

HQ の Re-register で接続情報を作り直した場合は、表示されたコマンドで configure をもう一度実行します。このとき、コマンドに --setup-tunnel が無ければ付け足してください。

管理者の PowerShell で実行します。

Terminal window
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 がディスプレイがつながっていると認識し、画面共有が映るようになります。数百円から手に入り、設定の変更は要りません。

ダミープラグを挿すと、画面共有の画面が 4分の1ほどに縮んで 映ることがあります(クリックの位置は元のまま)。

安価なダミープラグの多くは 4K などの高い解像度を Windows に伝えるため、Windows が表示スケールを 150〜200% に上げてしまうのが原因です。ダミープラグによっては、解像度を 1920x1080 に変えても挿し直すと元に戻ります。

対処 1: 表示スケールを 100% にする(推奨) — ミニオン専用の PC なら文字の見やすさは気にしなくてよいので、設定 → ディスプレイ → 拡大縮小とレイアウト で 100% にします。サインアウトしてサインインし直す(または再起動する)と反映されます。

Terminal window
# 今の設定を確かめる(96=100%, 120=125%, 144=150%, 192=200%)
Get-ItemProperty 'HKCU:\Control Panel\Desktop\WindowMetrics' -Name AppliedDPI

対処 2: TightVNC を表示スケールに対応しないモードで動かす

Terminal window
$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" -Force
Set-ItemProperty -Path "HKCU:\Software\Microsoft\Windows NT\CurrentVersion\AppCompatFlags\Layers" `
-Name $tvnPath -Value "~ DPIUNAWARE"

設定したら、管理者の PowerShell で画面共有を起動し直します。

Terminal window
Stop-Process -Name tvnserver -Force -ErrorAction SilentlyContinue
schtasks /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 : 用語 'minion-cli-win' は、コマンドレット、関数、スクリプト ファイル、または
操作可能なプログラムの名前として認識されません。

npm install -g のあと、PowerShell を開き直してください。ミニオンのユーザーで見つからない場合は、一度サインアウトしてサインインし直します。それでも見つからなければ、npm のコマンドの置き場所を PATH に足してから開き直します。

Terminal window
[Environment]::SetEnvironmentVariable('PATH',
[Environment]::GetEnvironmentVariable('PATH', 'User') + ';' + (npm prefix -g), 'User')

ターミナルの部品(node-pty)が入らない

Section titled “ターミナルの部品(node-pty)が入らない”

セットアップは、ターミナルの部品をパッケージのフォルダに入れます。失敗した場合は、管理者の PowerShell で同じ場所に入れ直してください。

Terminal window
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 に組み込みのデータベースを代わりに使います。

診断のコマンドとログで原因を確かめてください。

Terminal window
minion-cli-win diagnose
minion-cli-win daemons

更新のあとにミニオンが起動しない

Section titled “更新のあとにミニオンが起動しない”

Error: Cannot find module './refs/data.json' のようなエラーで起動しない場合は、更新中にファイルの一部が置き換わらなかったことが原因です。管理者の PowerShell で、止めてから入れ直します。

Terminal window
minion-cli-win stop --force
npm install -g @geekbeer/minion@latest
minion-cli-win restart --all

stop --force も効かない場合は、Windowsミニオンが停止できない の手順で止めてください。更新のログは %USERPROFILE%\.minion\logs\update-agent.log にあります。

再起動のあと、ミニオンがオフラインのまま

Section titled “再起動のあと、ミニオンがオフラインのまま”
  1. 管理者の PowerShell で minion-cli-win restart --all を実行する
  2. ミニオンのユーザーでサインインしているか確かめる(再起動しても動くようにする)
  3. それでも戻らなければ、HQ との接続のログ(cloudflared-stderr.log)を確かめる。%USERPROFILE%\.cloudflared\config.yml が無い場合は、--setup-tunnel を付けて configure をやり直す

画面共有(VNC)につながらない

Section titled “画面共有(VNC)につながらない”

「Server is not configured properly」と出る — TightVNC の設定を確かめます。ミニオンのユーザーの設定(HKCU)と PC 全体の設定(HKLM)の両方を見てください。

Terminal window
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 をもう一度実行してください。そのあと、画面共有を起動し直します。

Terminal window
Stop-Process -Name tvnserver -Force -ErrorAction SilentlyContinue
schtasks /Run /TN MinionVNC

中継の部品(websockify)が動いていない — Python が入っていなかった可能性があります。Python を入れてから、管理者の PowerShell で minion-cli-win setup をもう一度実行してください。

Terminal window
winget install Python.Python.3.12

ポートを確かめる

Terminal window
netstat -an | Select-String "5900" # TightVNC
netstat -an | Select-String "6080" # websockify