maestro/ui/src/content/help/17-settings.md

id, title, category, order, keywords

id	title	category	order	keywords
settings	システム設定	admin	170	設定 Settings 管理者 Workers Tools Save & Apply

システム設定 (admin)

設定画面は MAESTRO の挙動を config.yaml に書き込むための UI です。TopBar → 設定 タブで開きます。左にセクションのサイドバー、右に選択中セクションの編集フォームという 2 ペイン構成です。

YAML キーは スネークケース (max_concurrency)、コード内は キャメルケース (maxConcurrency) で、src/config.ts の transformKeys が自動変換します。UI から保存しても YAML はスネークケースのまま保たれます。

画面の構成

• 左サイドバー — セクションをグループ単位で並べる。グループは User / System / LLM / Agent Runtime / Tools / MCP & Connections / SSH の 7 つ
• 右フォーム — 選択したセクションの設定項目。ほとんどはその場で編集するインラインフォーム
• User グループ以外は admin 専用。一般ユーザーには表示されない (adminOnly)

セクション一覧

サイドバーのグループとセクションは以下の通りです。

Preference グループ (全ユーザー)

ペットや通知など、ワークスペース単位ではなく個人単位の設定をまとめたグループです。

セクション	内容
Preferences	自分の新規タスクのデフォルト公開範囲などの個人設定
🔔 Notifications	ブラウザ通知 / Web Push の購読設定
◉ Pets	チャットのマスコット（ペット）と担当ワーカー/バックエンドの設定。個人単位なので Preference グループにあります
🧠 Reflection 履歴	Reflection の実行履歴・差分の閲覧と revert（memory エントリの編集は ワークスペース → 設定 → メモリ）

通知の詳細は ブラウザ通知、memory の詳細は メモリと学習 を参照。

System グループ (admin)

セクション	内容
Branding	アプリ名・ロゴ・アクセント色などの見た目
Paths & Storage	storage.* の作業ディレクトリ・ワークスペース保存先・アップロード上限
Execution	concurrency (全 worker 合計の並列度)・max_movements・retry.*
Authentication	ログイン方式（Google / Gitea OAuth・ローカル認証）の有効化と設定
🏢 Organizations	ローカル組織の作成・メンバー管理（org 公開範囲の単位）
Web Push (Server)	Web Push 配信のサーバー側設定（VAPID キーなど）

LLM グループ (admin)

セクション	内容
Workers	llm.workers[] — ジョブ実行時に呼ぶ LLM 接続の定義
Gateway Server	この MAESTRO 自身を OpenAI 互換 Gateway として公開 + Virtual Keys
Metrics	Prometheus exporter (llm.metrics / gateway.metrics)

Gateway の運用は LLM Gateway 連携 を参照。

Agent Runtime グループ (admin)

セクション	内容
Ask / Subtasks	ASK 上限・サブタスクの制御
Context	コンテキスト使用率の警告閾値 (warn / prompt / force_transition)
Safety	max_iterations・max_revisits・実行デッドライン（Max Job Minutes / Deadline Grace）・history 要約などの自爆防止
Reflection	タスク完了後の自動学習。詳細は Reflection の調整

Tools グループ (admin)

セクション	内容
Web & Search	WebSearch / WebFetch / search_filter
Browser Runtime	Playwright BrowseWeb のタイムアウト・channel など
Media & Documents	Vision / OCR / 音声 / Office ファイルの上限
External Services	X / Maps / Amazon などの外部 API キー
Search Filter	WebSearch 結果のドメイン許可 / 除外フィルタ

MCP & Connections グループ (admin)

セクション	内容
MCP Runtime	MCP のグローバル runtime / quota 設定

個々の MCP サーバーは、各ワークスペースの 設定 → MCP（admin が全体共有する場合はこの MCP & Connections）で管理します。詳細は MCP 連携 を参照。

SSH グループ (admin)

セクション	内容
Admin SSH	グローバル接続・grant・監査ログ・マスターキーローテーション

詳細は SSH リモート操作 を参照。

Network グループ (admin)

セクション	内容
HTTPS / TLS	server.tls.* — アプリ内 TLS 終端・証明書・HTTP→HTTPS リダイレクト・HSTS。詳細は下の「HTTPS とリダイレクト」

ブランディング（見た目のカスタマイズ）

System グループの Branding で、アプリ全体の見た目を組織向けに変えられます。

• アプリ名: タイトルや画面に出る名称
• ロゴ / favicon: 画像をアップロードして差し替え（ブラウザのタブに出るアイコンも変わる）
• アクセント色: ボタンやリンクなどの基調色

ここはアプリ全体の設定です。個々の案件ワークスペースに付ける「ブランド色」（一覧の色帯など）は別物で、各ワークスペースの設定で変えます（→ワークスペースとメンバー）。

Save & Apply の流れ

フォームの値を変更しても、すぐには反映されません。

1. 値を変更すると、画面下部の 保存バー が琥珀色に変わり「未保存: N 項目」と表示される
2. Save & Apply ボタンで /api/config に PATCH 送信。成功すると「保存しました」トースト
3. やり直したいときは Discard Changes でフェッチ済みの値に戻す

注意点:

• 未保存のまま別タブへ移動しようとすると確認ダイアログが出る (useUnsavedGuard)
• 保存は ETag ベースの楽観ロック。他の管理者が先に保存していると「設定が他で変更されました。再読み込みしますか？」と表示される
• Preferences / Notifications / Reflection 履歴 の 3 つは個人 API で保存するため、この共通保存バーは出ない (各フォーム内で完結)

反映タイミング

ほとんどの設定は ConfigManager の変更イベントを各サブシステムが購読しているため サーバ再起動なしで反映 されます。例外は再起動が必要なもの:

• auth.providers.* (認証プロバイダ)
• db_path
• port
• server.tls.* (HTTPS / 証明書 / リダイレクト / HSTS)

HTTPS とリダイレクト

HTTPS / TLS セクション (server.tls.*) でアプリ自身に TLS を終端させられます。リバースプロキシで TLS を終端している場合はオフのままにしてください（二重終端になります）。HTTPS 関連の変更は 再起動が必要 です（フォーム上部に常時バナーが出ます）。

主な項目:

• HTTPS で配信 — アプリ内で TLS を終端。既定は自己署名証明書のため、正式な証明書を入れるまでブラウザに警告が出ます
• HTTP を HTTPS へリダイレクト — 平文 HTTP のアクセスを HTTPS へ転送。一時リダイレクト（302） で送るため、オフにすればリダイレクトは止まります（ブラウザに恒久キャッシュされません）
• HSTS を送出 — 既定オフ。正式な証明書がある場合のみオンにしてください

⚠️ 「オフにしてもずっと HTTPS にリダイレクトされる」場合

原因はサーバ設定ではなく、ブラウザに焼き付いた HSTS（HTTP Strict Transport Security） です。HSTS はブラウザを HTTPS に固定し、一度送るとサーバ側でオフにしても解除できません（ブラウザがリクエスト前に自分で HTTPS へ昇格するため）。

本バージョン以降、HSTS は既定オフで、オフの間はサーバが固定を解除する信号（max-age=0）を送ります。HTTPS をオンのまま一度アプリを HTTPS で開けば、固定が解除されて平文 HTTP に戻れます。証明書を入れて意図的に固定したい場合のみ HSTS をオンにしてください。

センシティブ値の扱い

llm.workers[].api_key や auth.providers.*.client_secret などのシークレットは、/api/config の GET で実値を返さずマスクされます。UI 上は「変更なし」または「env: ENV_NAME」として表示され、保存時に既存値を保持します。

環境変数オーバーライド

一部のキーは環境変数で上書きできます: OLLAMA_BASE_URL, OLLAMA_MODEL, WORKTREE_DIR, CONCURRENCY, DB_PATH, PORT, LOG_LEVEL。env で上書きされたフィールドはフォーム上でも「環境変数で上書き中」と示されます。

TIP

開発時は LOG_LEVEL=debug、本番は info を推奨。

Workers のモデルドロップダウンが空のときは endpoint が応答していない可能性。network / firewall を確認。

ユーザー管理・権限・安全性の調整は ユーザー管理 / 安全性 を参照。