12 KiB
English | 日本語
Configuration Reference
MAESTRO は単一の config.yaml（config.yaml.example をコピーして作成）で設定する。
- YAML キーは snake_case（
max_concurrency）、コード内は camelCase。src/config.tsのtransformKeysが変換する。 - 一部は環境変数で上書きできる（末尾参照）。
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。
| キー | 既定 | 意味 |
|---|---|---|
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。 |
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 検知）, office_max_entries（10000, ZIP 項目数の上限）, speech_server_url/speech_timeout/speech_language（文字起こし）, speak_server_url/speak_model/speak_voice/speak_format/speak_timeout/speak_max_chars（読み上げ Speak。接続先は文字起こしと別。既定形式 mp3・上限 4096 文字）。
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。
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 利用時必須） |