エージェント

専門エージェントを設定して使用します。

エージェントは、特定のタスクやワークフロー向けに設定できる専門化された AI アシスタントです。カスタムプロンプト、モデル、ツールアクセスを持つ集中的なツールを作成できます。

ヒント：plan エージェントを使用して、コード変更を行わずにコードを分析し、提案をレビューできます。

セッション中にエージェントを切り替えたり、@ メンションで呼び出したりできます。

タイプ

OpenCode には 2 種類のエージェントがあります：プライマリエージェントとサブエージェント。

プライマリエージェント

プライマリエージェントは、直接対話するメインアシスタントです。Tab キーまたは設定した switch_agent キーバインドで切り替えることができます。これらのエージェントはメインの会話を処理します。ツールアクセスは権限で設定されます。例えば、Build はすべてのツールが有効で、Plan は制限されています。

ヒント：セッション中に Tab キーでプライマリエージェント間を切り替えることができます。

OpenCode には 2 つの組み込みプライマリエージェント、Build と Plan があります。以下で詳しく見ていきます。

サブエージェント

サブエージェントは、プライマリエージェントが特定のタスクのために呼び出せる専門アシスタントです。メッセージで @ メンション して手動で呼び出すこともできます。

OpenCode には 2 つの組み込みサブエージェント、General と Explore があります。以下で詳しく見ていきます。

組み込み

OpenCode には 2 つの組み込みプライマリエージェントと 2 つの組み込みサブエージェントがあります。

build を使用

モード：primary

Build はすべてのツールが有効なデフォルトプライマリエージェントです。ファイル操作とシステムコマンドへの完全なアクセスが必要な開発作業の標準エージェントです。

plan を使用

モード：primary

計画と分析用に設計された制限付きエージェント。権限システムを使用して、より多くの制御を提供し、意図しない変更を防ぎます。デフォルトでは、以下のすべてが ask に設定されています：

file edits：すべての書き込み、パッチ、編集
bash：すべての bash コマンド

このエージェントは、LLM にコードを分析させ、変更を提案させ、計画を作成させたいが、コードベースに実際の変更を加えたくない場合に便利です。

general を使用

モード：subagent

複雑な質問の調査やマルチステップタスクの実行のための汎用エージェント。完全なツールアクセス（todo を除く）があるため、必要に応じてファイル変更を行えます。複数の作業単位を並行して実行するために使用します。

explore を使用

モード：subagent

コードベースを探索するための高速な読み取り専用エージェント。ファイルを変更できません。パターンでファイルをすばやく見つけたり、コード内のキーワードを検索したり、コードベースに関する質問に答えたりする必要がある場合に使用します。

compaction を使用

モード：primary

長いコンテキストを小さな要約に圧縮する隠しシステムエージェント。必要に応じて自動的に実行され、UI では選択できません。

title を使用

モード：primary

短いセッションタイトルを生成する隠しシステムエージェント。自動的に実行され、UI では選択できません。

summary を使用

モード：primary

セッション要約を作成する隠しシステムエージェント。自動的に実行され、UI では選択できません。

使用方法

プライマリエージェントの場合、セッション中に Tab キーで切り替えます。設定した switch_agent キーバインドも使用できます。
サブエージェントは以下の方法で呼び出せます：
- 自動的に：プライマリエージェントが説明に基づいて特定のタスクのために呼び出します。
- 手動で：メッセージで @ メンション します。例：
```
@general help me search for this function
```
セッション間のナビゲーション：サブエージェントが独自の子セッションを作成した場合、親セッションとすべての子セッション間を以下の方法でナビゲートできます：
- <Leader>+Right（または設定した session_child_cycle キーバインド）で前方にサイクル：親 → 子1 → 子2 → … → 親
- <Leader>+Left（または設定した session_child_cycle_reverse キーバインド）で後方にサイクル：親 ← 子1 ← 子2 ← … ← 親
これにより、メインの会話と専門的なサブエージェント作業間をシームレスに切り替えることができます。

設定

設定を通じて組み込みエージェントをカスタマイズしたり、独自のエージェントを作成したりできます。エージェントは 2 つの方法で設定できます：

JSON

opencode.json 設定ファイルでエージェントを設定します：

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

markdown ファイルを使用してエージェントを定義することもできます。以下の場所に配置します：

グローバル：~/.config/opencode/agents/
プロジェクト単位：.opencode/agents/

~/.config/opencode/agents/review.md

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---
 
You are in code review mode. Focus on:
 
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations
 
Provide constructive feedback without making direct changes.

markdown ファイル名がエージェント名になります。例えば、review.md は review エージェントを作成します。

オプション

これらの設定オプションを詳しく見ていきましょう。

Description

description オプションを使用して、エージェントの機能と使用タイミングの簡単な説明を提供します。

opencode.json

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

これは必須の設定オプションです。

Temperature

temperature 設定で LLM の応答のランダム性と創造性を制御します。

低い値は応答をより集中的で決定論的にし、高い値は創造性と変動性を増加させます。

opencode.json

{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Temperature 値は通常 0.0 から 1.0 の範囲です：

0.0-0.2：非常に集中的で決定論的な応答、コード分析と計画に最適
0.3-0.5：ある程度の創造性を持つバランスの取れた応答、一般的な開発タスクに適切
0.6-1.0：より創造的で変動的な応答、ブレインストーミングと探索に有用

opencode.json

{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

temperature が指定されていない場合、OpenCode はモデル固有のデフォルトを使用します。ほとんどのモデルでは通常 0、Qwen モデルでは 0.55 です。

Max steps

エージェントがテキストのみで応答するよう強制される前に実行できるエージェント反復の最大数を制御します。これにより、コストを制御したいユーザーがエージェントアクションに制限を設定できます。

設定されていない場合、エージェントはモデルが停止を選択するか、ユーザーがセッションを中断するまで反復を続けます。

opencode.json

{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

制限に達すると、エージェントは作業の要約と推奨される残りのタスクで応答するよう指示する特別なシステムプロンプトを受け取ります。

注意：レガシーの maxSteps フィールドは非推奨です。代わりに steps を使用してください。

Disable

true に設定してエージェントを無効にします。

opencode.json

{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

prompt 設定でこのエージェント用のカスタムシステムプロンプトファイルを指定します。プロンプトファイルにはエージェントの目的に固有の指示を含める必要があります。

opencode.json

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

このパスは設定ファイルの場所からの相対パスです。したがって、グローバル OpenCode 設定とプロジェクト固有の設定の両方で機能します。

Model

model 設定でこのエージェントのモデルをオーバーライドします。異なるタスクに最適化された異なるモデルを使用するのに便利です。例えば、計画用の高速モデル、実装用のより高性能なモデル。

ヒント：モデルを指定しない場合、プライマリエージェントはグローバルに設定されたモデルを使用し、サブエージェントはそれを呼び出したプライマリエージェントのモデルを使用します。

opencode.json

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

OpenCode 設定のモデル ID は provider/model-id 形式を使用します。例えば、OpenCode Zen を使用している場合、GPT 5.1 Codex には opencode/gpt-5.1-codex を使用します。

Tools

tools 設定でこのエージェントで使用可能なツールを制御します。特定のツールを true または false に設定して有効または無効にできます。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

注意：エージェント固有の設定はグローバル設定をオーバーライドします。

ワイルドカードを使用して複数のツールを一度に制御することもできます。例えば、MCP サーバーのすべてのツールを無効にするには：

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

ツールについて詳しく学ぶ。

Permissions

権限を設定してエージェントが実行できるアクションを管理できます。現在、edit、bash、webfetch ツールの権限を以下のように設定できます：

"ask" — ツールを実行する前に承認を求める
"allow" — 承認なしですべての操作を許可
"deny" — ツールを無効化

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

エージェントごとにこれらの権限をオーバーライドできます。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

Markdown エージェントでも権限を設定できます。

~/.config/opencode/agents/review.md

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---
 
Only analyze code and suggest changes.

特定の bash コマンドに権限を設定できます。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

glob パターンを使用できます。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

* ワイルドカードを使用してすべてのコマンドの権限を管理することもできます。最後にマッチしたルールが優先されるため、* ワイルドカードを最初に、特定のルールを後に配置します。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

権限について詳しく学ぶ。

Mode

mode 設定でエージェントのモードを制御します。mode オプションはエージェントの使用方法を決定するために使用されます。

opencode.json

{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

mode オプションは primary、subagent、または all に設定できます。mode が指定されていない場合、デフォルトは all です。

Hidden

hidden: true で @ オートコンプリートメニューからサブエージェントを非表示にします。Task ツールを通じて他のエージェントによってプログラム的にのみ呼び出されるべき内部サブエージェントに便利です。

opencode.json

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

これはオートコンプリートメニューでのユーザーの可視性にのみ影響します。権限が許可する場合、非表示のエージェントは Task ツールを通じてモデルによって呼び出すことができます。

注意：mode: subagent のエージェントにのみ適用されます。

Task permissions

permission.task でエージェントが Task ツールを通じて呼び出せるサブエージェントを制御します。柔軟なマッチングのために glob パターンを使用します。

opencode.json

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

deny に設定すると、サブエージェントは Task ツールの説明から完全に削除されるため、モデルはそれを呼び出そうとしません。

ヒント：ルールは順番に評価され、最後にマッチしたルールが優先されます。上記の例では、orchestrator-planner は *（deny）と orchestrator-*（allow）の両方にマッチしますが、orchestrator-* が * の後にあるため、結果は allow です。

ヒント：ユーザーは、エージェントのタスク権限が拒否する場合でも、@ オートコンプリートメニューを通じて任意のサブエージェントを直接呼び出すことができます。

Color

color オプションで UI でのエージェントの視覚的な外観をカスタマイズします。これはインターフェースでのエージェントの表示方法に影響します。

有効な 16 進数カラー（例：#FF5733）またはテーマカラー：primary、secondary、accent、success、warning、error、info を使用します。

opencode.json

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

Top P

top_p オプションで応答の多様性を制御します。ランダム性を制御するための temperature の代替手段です。

opencode.json

{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

値は 0.0 から 1.0 の範囲です。低い値はより集中的、高い値はより多様です。

Additional

エージェント設定で指定したその他のオプションは、モデルオプションとしてプロバイダーに直接渡されます。これにより、プロバイダー固有の機能とパラメータを使用できます。

例えば、OpenAI の推論モデルでは、推論の努力を制御できます：

opencode.json

{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

これらの追加オプションはモデルとプロバイダー固有です。利用可能なパラメータについてはプロバイダーのドキュメントを確認してください。

ヒント：opencode models を実行して利用可能なモデルのリストを確認できます。

エージェントの作成

以下のコマンドで新しいエージェントを作成できます：

opencode agent create

このインタラクティブコマンドは：

エージェントを保存する場所を尋ねます：グローバルまたはプロジェクト固有。
エージェントが何をすべきかの説明。
適切なシステムプロンプトと識別子を生成します。
エージェントがアクセスできるツールを選択させます。
最後に、エージェント設定を含む markdown ファイルを作成します。

ユースケース

異なるエージェントの一般的なユースケースをいくつか紹介します。

Build エージェント：すべてのツールが有効な完全な開発作業
Plan エージェント：変更を加えない分析と計画
Review エージェント：読み取り専用アクセスとドキュメントツールを使用したコードレビュー
Debug エージェント：bash と読み取りツールが有効な調査に焦点
Docs エージェント：ファイル操作はあるがシステムコマンドなしのドキュメント作成

例

便利なエージェントの例をいくつか紹介します。

ヒント：共有したいエージェントがありますか？PR を提出 (opens in a new tab)してください。

ドキュメントエージェント

~/.config/opencode/agents/docs-writer.md

---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---
 
You are a technical writer. Create clear, comprehensive documentation.
 
Focus on:
 
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

セキュリティ監査エージェント

~/.config/opencode/agents/security-auditor.md

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---
 
You are a security expert. Focus on identifying potential security issues.
 
Look for:
 
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

ルールモデル