役割: Butler の Maid 構成に新しい LLM モデルを追加する運用手順
対象読者: butler2 の運用者 / 実装者
新しいモデルの追加は、原則としてコード分岐ではなく設定追加で行う。
具体的には次の 2 ファイルを更新する。
config/maid_registry.yml に Maid 定義を追加config/intent_maid_routes.yml に route を追加または切替この方針は Maid 仕様書 v3 と implement 仕様書 の運用ルールに沿う。
implement / session_log の summarizeprovider: openrouter, model: qwen/qwen3-coder-nextGOOSE_COMMAND, OPENROUTER_API_KEYmaid_registry.yml を追加するconfig/maid_registry.yml の maids: に新しい行を追加する。
実用テンプレート（implement 用 Goose Maid）:
- maid_id: goose_openrouter_newmodel_implement
kind: goose
label: Goose OpenRouter NewModel Implement
provider: openrouter
model: vendor/model-name
role: implement
enabled: true
launch_config:
entrypoint: butler.maids.implement_maid:ImplementMaid
command: goose run --instructions - --no-session --quiet
command_env: GOOSE_COMMAND
max_attempts: 3
progress_poll_seconds: 10
stagnation_timeout_seconds: 90
terminate_grace_seconds: 15
verification_profile:
match_fields: []
file_checks: []
http_checks: []
test_commands: []
exact_output: []
実用テンプレート（implement 用 Gemini CLI Maid）:
- maid_id: gemini_cli_newprofile_implement
kind: cli
label: Gemini CLI NewProfile Implement
provider: google_ai_pro
model: gemini-cli-auto
role: implement
enabled: false # 研究枠は false で追加し、検証時だけ true にする
launch_config:
entrypoint: butler.maids.gemini_cli_implement_maid:GeminiCliImplementMaid
command: gemini --approval-mode auto_edit --output-format json -p
command_env: GEMINI_CLI_COMMAND
max_attempts: 2
progress_poll_seconds: 10
stagnation_timeout_seconds: 90
terminate_grace_seconds: 15
output_format: json
approval_mode: auto_edit
command_env_vars:
GOOGLE_GENAI_USE_GCA: "true"
GEMINI_CLI_TRUST_WORKSPACE: "true"
verification_profile:
match_fields: []
file_checks: []
http_checks: []
test_commands: []
exact_output: []
session_log summarize 用なら次を使う。
role: general_reasoningentrypoint: butler.maids.session_log_summary_worker:SessionLogSummaryWorkerintent_maid_routes.yml を追加または切替するconfig/intent_maid_routes.yml の routes: に対象 intent の route を追加する。
implement の例:
- intent: implement
maid_id: goose_openrouter_newmodel_implement
delegatable: true
conditions_json: {}
retry_policy_json:
max_attempts: 3
注意:
maid_registry.yml に追加しただけでは採用されないGoose 系 Maid の場合:
GOOSE_COMMAND または launch_config.commandOPENROUTER_API_KEYGemini CLI 系 Maid の場合:
gemini（対話モード）で Google アカウントにログインしておくGOOGLE_GENAI_USE_GCA=true — Google AI Pro / Code Assist の認証枠を使うために必要GEMINI_CLI_TRUST_WORKSPACE=true — ワークスペースのファイルへのアクセスを許可uv run butler2-mcp を再起動するinspect_runtime_config で available_intents を確認する確認観点:
maid_id に route されるintent_maid_routes.yml の maid_id を旧値へ戻すenabled: false にするdocs/capabilities/implement/仕様書.md## 9. Maid 上の位置づけ（model 追加と route 切替の運用）docs/capabilities/maid/仕様書_v3.md## 6.2 ルーティングテーブルの考え方（registry/route と記述順評価）docs/Butler利用ガイド.md## 8. implement を使う時の注意（GOOSE_COMMAND と認証情報）