# Configuration Reference

MAESTRO は単一の `config.yaml`（`config.yaml.example` をコピーして作成）で設定する。

- **YAML キーは snake_case**（`max_concurrency`）、コード内は camelCase。`src/config.ts` の `transformKeys` が変換する。
- 一部は**環境変数で上書き**できる（[末尾参照](#environment-variable-overrides)）。
- `config_version: 2` が現行スキーマ。

> 値の一次ソースは `config.yaml.example`（コメント付き）と `src/config.ts`。本リファレンスは各項目の意味をまとめたもの。

---

## `llm` — ジョブ実行時の LLM 接続

| キー | 既定 | 意味 |
|------|------|------|
| `timeout_minutes` | 10 | 1 リクエスト全体の上限（分）。 |
| `retry.max_attempts` | 3 | 429/5xx/一時接続失敗時の再試行回数。 |
| `retry.backoff_ms` | [2000,5000,15000] | 各再試行の待機（ms）。 |
| `retry.retryable_status` | [429,500,502,503,504] | 再試行対象の HTTP ステータス。 |

### `llm.workers[]` — ジョブ実行に使う接続先（必須）

| キー | 意味 |
|------|------|
| `id` | ワーカー識別子。 |
| `connection_type` | `direct`（Ollama/vLLM 等の OpenAI 互換 backend に直結）/ `aao_gateway`（別 Gateway 経由、Gateway Key 必須）。 |
| `endpoint` | OpenAI 互換 API のベース URL（例 `http://localhost:11434/v1`）。 |
| `model` | 使用モデル名（ワーカーごとに明示。`default_model` は廃止）。 |
| `api_key` | `aao_gateway` 時の virtual key 等（任意）。 |
| `roles` | 用途フィルタ: `auto`/`fast`/`quality`/`title`/`reflection` 等。`[title]` のみ＝タイトル生成専用。 |
| `max_concurrency` | このワーカーの並列度。 |
| `vlm` | `true` で画像入力対応（ReadImage は VLM ワーカーを優先）。 |
| `enabled` | 有効/無効。 |

### `llm.metrics` — Prometheus exporter（worker 側）

| キー | 既定 | 意味 |
|------|------|------|
| `enabled` | true | `/metrics`（bridge HTTP, 既定 `PORT=9876`）に mount。 |
| `prefix` | `aao_worker` | メトリクス名 prefix。 |
| `bearer_token` | — | 設定すると Bearer 認証必須（`env:NAME` 形式可）。 |
| `allowed_hosts` | localhost のみ | 許可元 IP。本番は bearer か allowlist を必ず設定。 |

---

## `gateway` — LLM Gateway サーバー（任意）

MAESTRO 自身を OpenAI 互換の LLM Gateway として公開する（仮想キー・予算・メトリクス付き、複数 GPU/チーム共有向け）。**env 変数や接続種別が `AAO_*` / `aao_gateway` という歴史的な接頭辞を使う点に注意（AAO = この Gateway 機能の旧称）。** 詳細は [aao-gateway-overview.md](aao-gateway-overview.md)。

| キー | 既定 | 意味 |
|------|------|------|
| `enabled` | false | true で同 process gateway が起動（hot reload 対応）。 |
| `listen_port` | 4000 | separate-deploy 時のみ。 |
| `request_timeout_sec` | 600 | 1 リクエスト全体（streaming 込み）。 |
| `upstream_timeout_sec` | 30 | 各 upstream の TTFB 上限。 |
| `shutdown_graceful_sec` | 30 | SIGTERM 後の SSE drain 上限。 |
| `backends[]` | — | `id`/`endpoint`/`model`/`max_slots`/`api_key`。model 厳密一致で routing。 |
| `virtual_keys[]` | — | bootstrap/backup 用（`key`/`team`/`allowed_models`/`tokens_budget`/`rate_limit_rpm`）。新規発行は admin API 推奨。 |
| `metrics` | enabled | `prefix: aao_gateway`、team/key_prefix/backend ラベル。auth 必須運用。 |

Virtual Key の発行・rotation は admin REST API（`POST /api/admin/gateway/keys`）または UI（Settings → LLM → Gateway Server）で行う。

---

## `storage` — パス・容量

| キー | 既定 | 意味 |
|------|------|------|
| `worktree_dir` | ./data/workspaces | ジョブ作業ディレクトリのベース。 |
| `custom_pieces_dir` | — | リポジトリ内 `pieces/` に加えて読む Piece dir（任意）。 |
| `user_folder_root` | ./data/users | `{root}/{userId}/` に AGENTS.md/scripts/notes 等を保存。 |
| `task_upload_max_size_mb` | 50 | タスク/コメント body 上限（base64 込み。範囲 1–1000）。 |
| `trash_retention_days` | 30 | `trash/` の自動 sweep。0 で都度全削除。 |

---

## Execution — 並列度・上限・再試行

| キー | 既定 | 意味 |
|------|------|------|
| `concurrency` | 4 | 全ワーカー合算の最大並列ジョブ数（env `CONCURRENCY`）。 |
| `max_movements` | 200 | 1 ジョブ内の最大 movement 数（loop 防止）。 |
| `retry.max_attempts` | 3 | ジョブ失敗時の最大再試行。 |
| `retry.backoff_seconds` | [60,300,900] | 各 attempt 間の待機秒。 |
| `ask.max_per_job` | 2 | 1 ジョブの ASK（ユーザー質問）上限。 |
| `subtasks.max_depth` | 2 | SpawnSubTask のネスト最大深度。 |
| `subtasks.max_per_parent` | 10 | 1 ジョブが生成できるサブタスク最大数。 |

---

## `context` — LLM コンテキスト管理

| キー | 既定 | 意味 |
|------|------|------|
| `limit_tokens` | 自動取得→128000 | コンテキスト上限。省略時はプロバイダ API から自動取得。 |
| `thresholds[]` | 0.7=warn / 0.85=prompt / 0.95=force_transition | 使用率閾値ごとの動作。 |

---

## `safety` — 暴走防止・Bash サンドボックス

| キー | 既定 | 意味 |
|------|------|------|
| `max_iterations` | 200 | 1 movement 内の最大イテレーション。 |
| `max_revisits` | 3 | 同一 movement の最大再訪問。超過で ABORT。 |
| `prompt_guard_ratio` | 0.8 | プロンプトがコンテキスト上限の何%まで許容するか（0.5–0.95）。 |
| `history_summarization.enabled` | true | 古い turn を構造化要約に置換して粘る。 |
| `history_summarization.tail_turns` | 2 | 末尾何 turn を保護するか。 |
| `history_summarization.preserve_recent_budget` | 8000 | 末尾保護の最大トークン。 |
| `bash_unrestricted` | false | true で Bash のコマンド許可リストを撤廃（**サンドボックス機構は別途 `bash_sandbox` が制御**）。 |
| `bash_sandbox` | auto | Bash 隔離機構: `auto`（bwrap あれば使用、無ければ hardened-whitelist）/ `always`（bwrap 強制・不在なら起動失敗、本番推奨）/ `off`（bwrap 不使用、env スクラブは維持）。詳細 [operations/bash-sandbox-provisioning.md](operations/bash-sandbox-provisioning.md)。 |

---

## `search_filter` — WebSearch の機密情報漏洩防止

| キー | 既定 | 意味 |
|------|------|------|
| `blocked_patterns[]` | — | 完全一致で検索クエリから除去するパターン。 |
| `auto_block.private_ip` | true | 10/172.16-31/192.168/127.* を自動ブロック。 |
| `auto_block.internal_domain` | true | `.local`/`.internal`/`.lan`/`.intranet`/`.corp`/`.home`。 |
| `auto_block.email` / `phone` | true | メール/電話番号。 |

---

## `browser` — BrowseWeb ランタイム

| キー | 既定 | 意味 |
|------|------|------|
| `page_timeout` | 60000 | ページ遷移 timeout（ms）。 |
| `action_timeout` | 30000 | アクション timeout（ms）。 |
| `captcha_solve` | skip | `skip` / `novnc`（人手 CAPTCHA 解決）。 |
| `max_captcha_pages` | 5 | CAPTCHA ページ上限。 |
| `channel` | chromium | `chromium`/`chrome`/`msedge`。 |
| `executable_path` | — | ブラウザ実行ファイル（channel と排他）。 |

---

## `tools` — ツール設定

UI 上は Web & Search / Browser / Media & Documents / External Services / Legacy Knowledge に分かれるが YAML は `tools` 1 ブロック。主な項目:

**Web & Search**: `searxng_url`（WebSearch フォールバック先）, `webfetch_timeout`(sec), `websearch_timeout`, `webfetch_allowed_hosts[]`（SSRF 例外: private IP/.local を許可する場合）。

**Media & Documents**: `vision_model`/`vision_base_url`/`vision_timeout`/`vision_max_tokens`（ReadImage 用 VLM）, `ocr_model`, `office_{excel,docx,pdf}_max_size_mb`（既定 10）, `office_pptx_max_size_mb`（50）, `office_pptx_max_uncompressed_mb`（200, zip-bomb 検知）, `speech_server_url`/`speech_timeout`/`speech_language`。

**External Services**: `x_*`（Twitter/X CLI 連携: `x_cli_command`/`x_auth_token`/`x_ct0`/`x_proxy`/`x_download_*` 等）, `google_maps_api_key`/`maps_timeout`（未設定で Nominatim/OSRM）, `amazon_affiliate_tag`/`keepa_api_key`。

**User scripts**: `user_scripts_enabled`（RunUserScript。plain runtime は Node `--permission` で sandbox 化）, `user_scripts_allow_userids[]`。

**Legacy Knowledge**: `knowledge_service_url`（未設定で knowledge ツール無効）, `knowledge_namespaces`（namespace ごとの api_key）。新規 namespace は MCP 経由を推奨。

---

## `notes` — Shared Knowledge Notes 注入

`data/users/{userId}/notes/` のノートをシステムプロンプトに注入。`inject.per_note_max_kb`（日本語は 4 推奨）, `inject.total_max_kb`, `inject.over_budget_strategy`（`truncate_last`/`skip_remaining`/`degrade_to_search`）。

---

## `auth` — 認証（任意）

未設定なら認証なしで動作。

| キー | 意味 |
|------|------|
| `session_secret` | セッション署名鍵（ランダム文字列）。 |
| `session_max_age` | セッション有効期間（ms, 既定 86400000=24h）。 |
| `secure_cookie` | HTTPS 環境では true。 |
| `admin_emails[]` | admin ロールにするメール。 |
| `primary_provider` | `google` / `gitea`（両方有効時に明示）。 |
| `providers.google` | `client_id`/`client_secret`/`callback_url`。 |
| `providers.gitea` | `client_id`/`client_secret`/`base_url`/`callback_url`。ログイン時に Gitea org を取得し可視性に利用。 |

---

## `branding`（任意）

`app_name`/`primary_color`/`login_page_title`/`logo_url`/`favicon_url`/`footer_text`。Settings → System → Branding（admin）で GUI 編集可。`config.yaml`・`data/branding/` は gitignore 済み。

---

## `secrets`

`master_key_path`（既定 `./data/secrets/master.key`, 32 byte, 初回起動で自動生成・mode 0600）。SSH 鍵・MCP トークン等の暗号化に使う。

---

## `reflection` — 学習（既定 OFF）

ON で毎ジョブ完了後にユーザーメモリを LLM が自動更新（snapshot は revert 可）。`enabled`, `max_memory_changes_per_job`(3), `piece_edit_cooldown_hours`(24), `snapshot_retention_days`(90), `per_user_daily_budget_tokens`(200000)。

---

## `mcp` — Model Context Protocol

サーバーは admin UI（global）/各ユーザー（self-hosted）で管理。**`MCP_ENCRYPTION_KEY` env（64 hex）が必須。** `call_timeout_seconds`(60), `max_binary_size_mb`(20), `max_output_files_per_job`(10), `max_output_size_mb_per_job`(200), `tool_cache_ttl_seconds`(600), `oauth_pending_ttl_minutes`(10), `allow_private_addresses`（private 網の MCP server 用、既定 false）。

---

## `ssh` — SSH ツール（既定 OFF）

`enabled`, `allow_private_addresses`(global 既定、admin は per-connection grant 可), `call_timeout_seconds`(30), `max_output_bytes`(32768), `max_{upload,download}_size_mb`(100), `audit_retention_days`(90), `admin_bypasses_grants`(true), abuse 検知（`abuse_window_minutes`/`abuse_failure_threshold`/`abuse_lock_minutes`）。

**Interactive Console**（`ssh.console`）: `enabled`, `idle_timeout_seconds`(1800), `max_session_duration_seconds`(14400), `scrollback_bytes`(524288), `max_sessions_per_connection`(3) ほか。手順は [ssh.md](ssh.md)。

---

## `notifications.push` — Web Push（V2, 任意）

HTTPS ホスティング必須（iOS は PWA インストール）。`enabled`, `vapid_subject`(RFC 8292), `vapid_current_path`（自動生成・mode 0600）, `vapid_history_dir`, `payload_max_bytes`(3072, 上限 4096), `queue_concurrency`(8), `per_send_timeout_ms`(10000)。鍵ローテーション: `npm run vapid-rotate`。

---

## Environment variable overrides

一部設定は環境変数で上書きできる:

| 環境変数 | 上書き対象 |
|----------|------------|
| `OLLAMA_BASE_URL` | LLM エンドポイント |
| `OLLAMA_MODEL` | モデル名 |
| `WORKTREE_DIR` | `storage.worktree_dir` |
| `CONCURRENCY` | `concurrency` |
| `DB_PATH` | SQLite DB パス |
| `PORT` | bridge HTTP ポート（既定 9876） |
| `LOG_LEVEL` | `debug`/`info`/`warn`/`error`（既定 info） |
| `MCP_ENCRYPTION_KEY` | MCP/SSH 秘密の暗号化鍵（MCP 利用時必須） |