設定の詳細カスタマイズ：エージェントと権限管理

学習目標

各エージェントが使用するモデルとパラメータをカスタマイズする
エージェントの権限（ファイル編集、Bash実行、Webリクエストなど）を精密に制御する
prompt_appendを使用してエージェントに追加指示を追加する
カスタムCategoryを作成して動的なエージェント組み合わせを実現する
特定のエージェント、Skill、Hook、MCPを有効/無効にする

現在の課題

デフォルト設定は便利ですが、ニーズに完全には合わない場合があります：

Oracleが使用するGPT 5.2が高すぎるので、もっと安いモデルに変えたい
Exploreエージェントはファイル書き込み権限を持つべきではなく、検索のみさせたい
Librarianに公式ドキュメントを優先的に検索させたいが、GitHubではなく
あるHookが常に誤検知するので、一時的に無効にしたい

必要なのは「詳細カスタマイズ」——「使えれば十分」ではなく「ちょうど十分」であることです。

🎒 開始前の準備

前提条件

このチュートリアルは、インストールと設定とProvider設定が完了していることを前提としています。

知っておくべきこと：

設定ファイルの場所：~/.config/opencode/oh-my-opencode.json（ユーザーレベル）または.opencode/oh-my-opencode.json（プロジェクトレベル）
ユーザーレベル設定はプロジェクトレベル設定より優先されます

コアコンセプト

設定の優先順位：ユーザーレベル設定 > プロジェクトレベル設定 > デフォルト設定

~/.config/opencode/oh-my-opencode.json (最高優先度)
    ↓ 上書き
.opencode/oh-my-opencode.json (プロジェクトレベル)
    ↓ 上書き
oh-my-opencode 組み込みデフォルト値 (最低優先度)

設定ファイルはJSONCをサポート：

//でコメントを追加できる
/* */でブロックコメントを追加できる
末尾のカンマを含めることができる

実践してみる

ステップ1：設定ファイルを見つけてSchema自動補完を有効にする

理由 JSON Schemaを有効にすると、エディターが利用可能なすべてのフィールドとタイプを自動的に提示し、設定ミスを防ぐことができます。

操作：

jsonc

{
  // この行を追加して自動補完を有効にする
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  
  // あなたの設定...
}

期待される結果：

VS Code / JetBrainsなどのエディターで、{を入力すると利用可能なすべてのフィールドが自動的に提示される
フィールドにマウスをホバーすると説明とタイプが表示される

ステップ2：エージェントモデルをカスタマイズする

理由異なるタスクには異なるモデルが必要です：

アーキテクチャ設計：最強のモデル（Claude Opus 4.5）
高速探索：最速のモデル（Grok Code）
UIデザイン：視覚モデル（Gemini 3 Pro）
コスト管理：単純なタスクには安いモデル

操作：

jsonc

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",

  "agents": {
    // Oracle：戦略アドバイザー、GPT 5.2を使用
    "oracle": {
      "model": "openai/gpt-5.2",
      "temperature": 0.1  // 低い温度、より決定的
    },

    // Explore：高速探索、無料モデルを使用
    "explore": {
      "model": "opencode/gpt-5-nano",  // 無料
      "temperature": 0.3
    },

    // Librarian：ドキュメント検索、大きなコンテキストモデルを使用
    "librarian": {
      "model": "anthropic/claude-sonnet-4-5"
    },

    // マルチモーダルLooker：メディア分析、Geminiを使用
    "multimodal-looker": {
      "model": "google/gemini-3-flash"
    }
  }
}

期待される結果：

各エージェントがタスクの特性に合わせて最適化された異なるモデルを使用する
設定を保存すると、次回対応するエージェントを呼び出すときに新しいモデルが使用される

ステップ3：エージェント権限を設定する

理由一部のエージェントはすべての権限を持つべきではありません：

Oracle（戦略アドバイザー）：読み取り専用、ファイル書き込みは不要
Librarian（研究専門家）：読み取り専用、Bash実行は不要
Explore（探索）：読み取り専用、Webリクエストは不要

操作：

jsonc

{
  "agents": {
    "explore": {
      // ファイル書き込みとBash実行を禁止、Web検索のみ許可
      "permission": {
        "edit": "deny",
        "bash": "deny",
        "webfetch": "allow"
      }
    },

    "librarian": {
      // 読み取り専用権限
      "permission": {
        "edit": "deny",
        "bash": "deny",
        "webfetch": "allow"  // ドキュメント検索が必要
      }
    },

    "oracle": {
      // 読み取り専用権限
      "permission": {
        "edit": "deny",
        "bash": "deny",
        "webfetch": "allow"  // 資料調査が必要
      }
    },

    // Sisyphus：メインオーケストレーター、すべての操作を実行可能
    "sisyphus": {
      "permission": {
        "edit": "allow",
        "bash": "allow",
        "webfetch": "allow"
      }
    }
  }
}

権限の説明：

権限	値	説明
`edit`	`ask/allow/deny`	ファイル編集権限
`bash`	`ask/allow/deny` またはオブジェクト	Bash実行権限（具体的なコマンドまで細分化可）
`webfetch`	`ask/allow/deny`	Webリクエスト権限
`doom_loop`	`ask/allow/deny`	エージェントが無限ループ検知を上書きすることを許可
`external_directory`	`ask/allow/deny`	プロジェクト外ディレクトリアクセス権限

Bash権限の細分化：

jsonc

{
  "agents": {
    "explore": {
      "permission": {
        "bash": {
          "git": "allow",      // gitコマンドの実行を許可
          "grep": "allow",     // grepの実行を許可
          "rm": "deny",       // ファイル削除を禁止
          "mv": "deny"        // ファイル移動を禁止
        }
      }
    }
  }
}

期待される結果：

権限を設定すると、エージェントが無効な操作を実行しようとすると自動的に拒否される
OpenCodeで権限拒否のプロンプトが表示される

ステップ4：prompt_appendを使用して追加指示を追加する

理由デフォルトのシステムプロンプトはすでに優れていますが、特別なニーズがあるかもしれません：

Librarianに特定のドキュメントを優先的に検索させたい
Oracleに特定のアーキテクチャパターンに従わせたい
Exploreに特定の検索キーワードを使用させたい

操作：

jsonc

{
  "agents": {
    "librarian": {
      // デフォルトのシステムプロンプトの後に追加、上書きはしない
      "prompt_append": "Always use elisp-dev-mcp for Emacs Lisp documentation lookups. " +
                      "When searching for docs, prioritize official documentation over blog posts."
    },

    "oracle": {
      "prompt_append": "Follow SOLID principles and Clean Architecture patterns. " +
                     "Always suggest TypeScript types for all function signatures."
    },

    "explore": {
      "prompt_append": "When searching code, prioritize recent commits and actively maintained files. " +
                     "Ignore test files unless explicitly asked."
    }
  }
}

期待される結果：

エージェントの挙動が変化しますが、既存の能力は保持されます
例えば、Oracleが尋ねられたときに常にTypeScriptタイプを提案するようになります

ステップ5：Category設定をカスタマイズする

理由 Categoryはv3.0の新機能で、動的なエージェント組み合わせを実現します：

特定のタスクタイプのためにモデルとパラメータをプリセット
delegate_task(category="...")で素早く呼び出し
「手動でモデル選択＋プロンプト作成」より効率的

操作：

jsonc

{
  "categories": {
    // カスタム：データサイエンスタスク
    "data-science": {
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.2,
      "prompt_append": "Focus on data analysis, ML pipelines, and statistical methods. " +
                     "Use pandas/numpy for Python and dplyr/tidyr for R."
    },

    // デフォルトを上書き：UIタスクにカスタムプロンプトを使用
    "visual-engineering": {
      "model": "google/gemini-3-pro",
      "prompt_append": "Use shadcn/ui components and Tailwind CSS. " +
                     "Ensure responsive design and accessibility."
    },

    // デフォルトを上書き：高速タスク
    "quick": {
      "model": "anthropic/claude-haiku-4-5",
      "temperature": 0.1,
      "prompt_append": "Be concise. Focus on simple fixes and quick searches."
    }
  }
}

Category設定フィールド：

フィールド	説明	例
`model`	使用するモデル	`"anthropic/claude-sonnet-4-5"`
`temperature`	温度（0-2）	`0.2` (決定的) / `0.8` (創造的)
`top_p`	核サンプリング（0-1）	`0.9`
`maxTokens`	最大Token数	`4000`
`thinking`	Thinking設定	`{"type": "enabled", "budgetTokens": 16000}`
`prompt_append`	追加プロンプト	`"Use X for Y"`
`tools`	ツール権限	`{"bash": false}`
`is_unstable_agent`	不安定としてマーク（強制バックグラウンドモード）	`true`

Categoryの使用：

// OpenCodeで
delegate_task(category="data-science", prompt="このデータセットを分析して可視化を生成")
delegate_task(category="visual-engineering", prompt="レスポンシブダッシュボードコンポーネントを作成")
delegate_task(category="quick", prompt="この関数の定義を検索")

期待される結果：

異なるタイプのタスクが自動的に最適なモデルと設定を使用する
毎回手動でモデルとパラメータを指定する必要がない

ステップ6：特定の機能を無効にする

理由一部の機能はワークフローに適さない場合があります：

comment-checker：プロジェクトで詳細なコメントが許可されている
agent-usage-reminder：いつどのエージェントを使用すべきか分かっている
あるMCP：必要ない

操作：

jsonc

{
  // 特定のHooksを無効にする
  "disabled_hooks": [
    "comment-checker",           // コメントをチェックしない
    "agent-usage-reminder",       // エージェント使用推奨を表示しない
    "startup-toast"               // 起動通知を表示しない
  ],

  // 特定のSkillsを無効にする
  "disabled_skills": [
    "playwright",                // Playwrightを使用しない
    "frontend-ui-ux"            // 組み込みフロントエンドSkillを使用しない
  ],

  // 特定のMCPsを無効にする
  "disabled_mcps": [
    "websearch",                // Exa検索を使用しない
    "context7",                // Context7を使用しない
    "grep_app"                 // grep.appを使用しない
  ],

  // 特定のエージェントを無効にする
  "disabled_agents": [
    "multimodal-looker",        // マルチモーダルLookerを使用しない
    "metis"                   // Metis事前計画分析を使用しない
  ]
}

利用可能なHookリスト（一部）：

Hook名	機能
`todo-continuation-enforcer`	TODOリストの強制完了
`comment-checker`	冗長なコメントの検出
`tool-output-truncator`	ツール出力の切り詰めでコンテキストを節約
`keyword-detector`	ultraworkなどのキーワードの検出
`agent-usage-reminder`	どのエージェントを使用すべきかの推奨
`session-notification`	セッション終了通知
`background-notification`	バックグラウンドタスク完了通知

期待される結果：

無効にされた機能は実行されなくなる
再度有効にすると機能が復元される

ステップ7：バックグラウンドタスクの並行制御を設定する

理由並列バックグラウンドタスクには並行数の制御が必要です：

APIレート制限を回避
コスト管理（高価なモデルはあまり並列実行できない）
Providerのクォータを遵守

操作：

jsonc

{
  "background_task": {
    // デフォルトの最大並行数
    "defaultConcurrency": 5,

    // Providerレベル並行制限
    "providerConcurrency": {
      "anthropic": 3,      // Anthropic APIは最大3並行
      "openai": 5,         // OpenAI APIは最大5並行
      "google": 10          // Gemini APIは最大10並行
    },

    // Modelレベル並行制限（最高優先度）
    "modelConcurrency": {
      "anthropic/claude-opus-4-5": 2,     // Opusは高価なので2並行に制限
      "google/gemini-3-flash": 10,          // Flashは安価なので10並行を許可
      "anthropic/claude-haiku-4-5": 15      // Haikuはさらに安価なので15並行を許可
    }
  }
}

優先順位：

modelConcurrency > providerConcurrency > defaultConcurrency

期待される結果：

並行制限を超えるバックグラウンドタスクは待機キューに入る
高価なモデルの並行実行が制限され、コストが節約される

ステップ8：実験的な機能を有効にする

理由実験的な機能は追加の能力を提供しますが、不安定である可能性があります：

aggressive_truncation：より積極的なコンテキスト切り詰め
auto_resume：クラッシュからの自動回復
truncate_all_tool_outputs：すべてのツール出力を切り詰め

警告

実験的な機能は将来のバージョンで削除または挙動が変更される可能性があります。有効にする前に十分にテストしてください。

操作：

jsonc

{
  "experimental": {
    // より積極的なツール出力切り詰めを有効にする
    "aggressive_truncation": true,

    // thinkingブロックエラーからの自動回復
    "auto_resume": true,

    // すべてのツール出力を切り詰める（Grep/Glob/LSP/AST-Grepだけでなく）
    "truncate_all_tool_outputs": false
  }
}

期待される結果：

アグレッシブモードでは、ツール出力がより厳格に切り詰められ、コンテキストが節約される
auto_resumeを有効にすると、エージェントがエラーに遭遇しても自動的に回復して作業を継続する

チェックポイント ✅

設定が有効になっているか検証：

bash

# 診断コマンドを実行
bunx oh-my-opencode doctor --verbose

期待される結果：

各エージェントのモデル解決結果
設定の上書きが有効になっているか
無効にされた機能が正しく認識されているか

よくある問題

1. 設定ファイルのフォーマットエラー

問題：

JSON構文エラー（カンマ不足、カンマ過多）
フィールド名のタイプミス（temperatureをtemparatureと記述）

解決策：

bash

# JSONフォーマットを検証
cat ~/.config/opencode/oh-my-opencode.json | jq .

2. 権限設定が厳しすぎる

問題：

一部のエージェントが完全に無効化されている（edit: "deny", bash: "deny"）
エージェントが正常に作業できない

解決策：

読み取り専用エージェント（Oracle、Librarian）はeditとbashを無効にしてもよい
メインオーケストレーター（Sisyphus）は完全な権限が必要

3. Category設定が有効にならない

問題：

Category名のタイプミス（visual-engineeringをvisual-engineeringと記述）
delegate_taskでcategoryパラメータを指定していない

解決策：

delegate_task(category="...")の名前が設定と一致しているか確認
doctor --verboseを使用してCategory解決結果を検証

4. 並行制限が低すぎる

問題：

modelConcurrencyが低すぎる（例：1）
バックグラウンドタスクがほぼ直列に実行され、並列の利点が失われる

解決策：

予算とAPIクォータに応じて合理的に設定
高価なモデル（Opus）は2-3に制限、安価なモデル（Haiku）は10以上に設定

レッスンまとめ

設定の詳細カスタマイズ = 精密制御：

設定項目	用途	一般的なシナリオ
`agents.model`	エージェントモデルの上書き	コスト最適化、タスク適合
`agents.permission`	エージェント権限の制御	セキュリティ分離、読み取り専用モード
`agents.prompt_append`	追加プロンプトの追加	アーキテクチャ規範の遵守、検索戦略の最適化
`categories`	動的エージェント組み合わせ	特定タイプタスクの高速呼び出し
`background_task`	並行制御	コスト制御、APIクォータ
`disabled_*`	特定機能の無効化	使用頻度の低い機能の削除

覚えておくべきこと：

ユーザーレベル設定（~/.config/opencode/oh-my-opencode.json）はプロジェクトレベルより優先される
JSONCを使用して設定を読みやすくする
oh-my-opencode doctor --verboseを実行して設定を検証する

次のレッスンのプレビュー

次のレッスンでは、**設定の診断とトラブルシューティング**を学びます。
学ぶこと：
doctorコマンドを使用してヘルスチェックを行う方法
OpenCodeのバージョン、プラグイン登録、Provider設定などの問題を診断する方法
モデル解決メカニズムとCategory設定を理解する
JSON出力を使用して自動診断を行う方法

付録：ソースコード参照

クリックしてソースコードの場所を展開

最終更新日: 2026-01-26

機能	ファイルパス	行号
設定Schema定義	`src/config/schema.ts`	1-378
AgentOverrideConfig	`src/config/schema.ts`	98-119
CategoryConfig	`src/config/schema.ts`	154-172
AgentPermissionSchema	`src/config/schema.ts`	11-17
OhMyOpenCodeConfigSchema	`src/config/schema.ts`	329-350
設定ドキュメント	`docs/configurations.md`	1-595

主要な定数：

PermissionValue = z.enum(["ask", "allow", "deny"])：権限値列挙型

主要なタイプ：

AgentOverrideConfig：エージェント上書き設定（モデル、温度、プロンプトなど）
CategoryConfig：Category設定（モデル、温度、プロンプトなど）
AgentPermissionSchema：エージェント権限設定（edit、bash、webfetchなど）
BackgroundTaskConfig：バックグラウンドタスク並行設定

組み込みエージェント列挙型（BuiltinAgentNameSchema）：

sisyphus, prometheus, oracle, librarian, explore, multimodal-looker, metis, momus, atlas

組み込みSkill列挙型（BuiltinSkillNameSchema）：

playwright, agent-browser, frontend-ui-ux, git-master

組み込みCategory列挙型（BuiltinCategoryNameSchema）：

visual-engineering, ultrabrain, artistry, quick, unspecified-low, unspecified-high, writing

設定の詳細カスタマイズ：エージェントと権限管理 ​

学習目標 ​

現在の課題 ​

🎒 開始前の準備 ​

コアコンセプト ​

実践してみる ​

ステップ1：設定ファイルを見つけてSchema自動補完を有効にする ​

ステップ2：エージェントモデルをカスタマイズする ​

ステップ3：エージェント権限を設定する ​

ステップ4：prompt_appendを使用して追加指示を追加する ​

ステップ5：Category設定をカスタマイズする ​

ステップ6：特定の機能を無効にする ​

ステップ7：バックグラウンドタスクの並行制御を設定する ​

ステップ8：実験的な機能を有効にする ​

チェックポイント ✅ ​

よくある問題 ​

1. 設定ファイルのフォーマットエラー ​

2. 権限設定が厳しすぎる ​

3. Category設定が有効にならない ​

4. 並行制限が低すぎる ​

レッスンまとめ ​

次のレッスンのプレビュー ​

付録：ソースコード参照 ​

設定の詳細カスタマイズ：エージェントと権限管理

学習目標

現在の課題

🎒 開始前の準備

コアコンセプト

実践してみる

ステップ1：設定ファイルを見つけてSchema自動補完を有効にする

ステップ2：エージェントモデルをカスタマイズする

ステップ3：エージェント権限を設定する

ステップ4：prompt_appendを使用して追加指示を追加する

ステップ5：Category設定をカスタマイズする

ステップ6：特定の機能を無効にする

ステップ7：バックグラウンドタスクの並行制御を設定する

ステップ8：実験的な機能を有効にする

チェックポイント ✅

よくある問題

1. 設定ファイルのフォーマットエラー

2. 権限設定が厳しすぎる

3. Category設定が有効にならない

4. 並行制限が低すぎる

レッスンまとめ

次のレッスンのプレビュー

付録：ソースコード参照