OpenCode エージェント（Agent）設定の詳細

エージェントは OpenCode における専門化された AI アシスタントであり、各エージェントは独立したシステムプロンプト、モデル、ツールアクセス権限、動作制約を設定でき、特定の種類のタスクやワークフローを処理するために使用されます。セッション中にいつでもエージェントを切り替えたり、または@プロキシ名の方法で特定のエージェントを直接呼び出せます。

エージェントの種類

OpenCode のエージェントは2種類に分けられ、それらの呼び出し方法と役割が異なります：

種類	説明	切り替え方法
プライマリエージェント（primary）	あなたが直接対話する主要なアシスタントであり、メインの対話フローを処理します。ツールアクセス権限は`permission`設定	按 `Tab`キーで循環切り替え、または設定された`agent_cycle`ショートカットキー
サブエージェント（subagent）	メインエージェントによって呼び出され、専門的なタスクを実行するアシスタントです。独立した子セッションで実行され、メインセッションのコンテキストに影響しません。	メインエージェントが自動的に呼び出すか、メッセージ内で`@プロキシ名`手動で呼び出します

組み込みエージェント

OpenCode には、すぐに使えるエージェントが4つと、自動実行されるシステムエージェントが3つ組み込まれています：

1、Build（プライマリエージェント）

デフォルトのプライマリエージェントで、すべてのツールが有効になっています。完全なファイル操作とシステムコマンドへのアクセス権限を必要とする日常的な開発作業に適しています。これは最も頻繁に使用するエージェントです。

2、Plan（プライマリエージェント）

コード分析とプランニング専用に設計された制限付きエージェントです。デフォルトでは、以下の操作はすべて承認プロンプトをトリガーします（設定：ask）：

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

LLM にコードの分析、提案、実行計画の作成をさせたいが、コードベースに実際の変更を加えたくない場合は、Plan エージェントに切り替えてください。

3、General（サブエージェント）

汎用サブエージェントで、完全なツールアクセス権限（todo ツールを除く）を持ち、ファイルを変更できます。複雑な問題の調査や複数ステップのタスクの実行に適しており、複数の独立した作業ユニットを並行して実行することもできます。

4、Explore（サブエージェント）

読み取り専用のサブエージェントで、ファイルを変更できません。ファイルのすばやい検索、コードキーワードの検索、コードベース構造に関する質問への回答に適しており、高速で副作用がありません。

5、システムエージェント（非表示）

以下の3つのエージェントは OpenCode によって自動管理され、エージェント切り替えリストには表示されません手動で選択する必要はなく、選択することもできません：

エージェント名	役割	トリガータイミング
Compaction	長すぎるコンテキストをより小さな要約に圧縮し、モデルのコンテキスト制限を超えるのを防ぎます	コンテキストの長さがしきい値に達すると自動実行
Title	セッションの短いタイトルを生成	新しいセッション開始後に自動実行
Summary	セッションの要約を作成	セッションの要約が必要なときに自動実行

エージェントの使用方法

1、プライマリエージェントの切り替え

セッション中にTabキーで全てのプライマリエージェントを循環切り替えでき、Shift+Tab逆方向に切り替えます。また、<Leader>aエージェントリストを開いて直接選択できます。

2、サブエージェントの呼び出し

サブエージェントには2つの呼び出し方法があります：

自動呼び出し：メインエージェントがタスクの性質に基づいて特定のサブエージェントが必要と判断した場合、自動的に呼び出してタスクを委任します
手動 @ 呼び出し：メッセージ内で@プロキシ名どのサブエージェントが処理するかを直接指定します

@general help me search for this function across the codebase

3、親子セッション間の移動

サブエージェントの実行時には独立した子セッションが作成され、ショートカットキーを使用して親セッションと各子セッションの間を移動できます：

ショートカットキー	操作
`<Leader>+→`（`session_child_cycle`）	前方に循環：親セッション → 子セッション1 → 子セッション2 → … → 親セッション
`<Leader>+←`（`session_child_cycle_reverse`）	後方に循環：親セッション ← 子セッション1 ← 子セッション2 ← … ← 親セッション
`<Leader>+↑`（`session_parent`）	親セッションに直接戻る

2つの設定方法

エージェントは JSON 設定または Markdown ファイルの2つの方法で定義でき、効果は同じなので、必要に応じて選択します：

方法1：opencode.json で設定

例

{
"$schema": "https://opencode.ai/config.json",
"agent": {
"build": { // 組み込み build エージェントの設定を上書き
"mode": "primary",
"model": "anthropic/claude-sonnet-4-20250514",
"prompt": "{file:./prompts/build.txt}", // ファイルからシステムプロンプトを読み込む
"tools": {
"write": true,
"edit": true,
"bash": true
}
},
"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
}
}
}
}

方法2：Markdown ファイル

以下のパスに.mdファイルを作成し、ファイル名がそのままエージェント名になります（例：review.md対応するエージェント名review）：

グローバル：~/.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.

設定オプションの詳細

description（説明）

エージェントの機能説明で、エージェントリストと@自動補完メニューに表示され、ユーザーとメインエージェントがいつそのエージェントを呼び出すかを判断するのに役立ちます。カスタムエージェントの場合、この項目は必須：

例

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

mode（モード）

エージェントの使用方法を制御し、次の3つの値のいずれかに設定できます：

值	説明
`"primary"`	プライマリエージェント。Tab 切り替えリストに表示され、メインの対話に使用されます
`"subagent"`	サブエージェント。Tab 切り替えリストには表示されず、メインエージェントから呼び出されるか、@ で手動呼び出しされます
`"all"`	プライマリエージェントとサブエージェントの両方として使用（mode 未指定時のデフォルト値）

例

{
"agent": {
"review": {
"mode": "subagent" // サブエージェントとしてのみ使用し、プライマリエージェントの切り替えリストには表示しない
}
}
}

model（モデル）

エージェントに特定のモデルを指定し、グローバル設定のデフォルトモデルを上書きします。形式はprovider/model-id。異なるタスクに異なるモデルを使うのに適しています。例えば、プランニングタスクには高速な小モデル、コード生成にはより強力な大モデルを使います：

例

{
"agent": {
"plan": {
"model": "anthropic/claude-haiku-4-20250514" // プランニングタスクにはより高速な Haiku モデルを使用
},
"build": {
"model": "anthropic/claude-sonnet-4-20250514" // 開発タスクにはより高性能な Sonnet モデルを使用
}
}
}

指定されていない場合model、プライマリエージェントはグローバル設定のデフォルトモデルを使用し、サブエージェントは呼び出し元のプライマリエージェントが使用するモデルを継承します。実行opencode models利用可能なすべてのモデルの一覧を表示できます。

prompt（システムプロンプト）

エージェントにカスタムシステムプロンプトを指定するには、文字列を直接書くこともできますし、経由することもできます。{file:./路径}構文は外部ファイルから読み込まれます。パスは設定ファイルの場所を基準とします：

例

{
"agent": {
"review": {
"prompt": "{file:./prompts/code-review.txt}"
// opencode.json と同じディレクトリの prompts/code-review.txt からプロンプトを読み取る
// プロンプトの内容が長い場合に、それをテキストファイルで別途管理するのに適しています。
}
}
}

temperature（温度）

モデル出力のランダム性を制御します。値が低いほど出力は確定的になり、正確な結果を必要とするタスクに適しています；値が高いほど出力は多様になり、クリエイティブなタスクに適しています：

温度範囲	出力特性	適用場面
0.0 – 0.2	高度集中、確実性が強い	コード分析、計画、デバッグ、レビュー
0.3 – 0.5	バランス、正確さと柔軟性を両立	一般的な開発タスク、ドキュメント作成
0.6 – 1.0	比較的独創的で多様性がある	ブレインストーミング、解決策の探索、クリエイティブライティング

例

{
"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。

steps（最大ステップ数）

エージェントがプレーンテキストで応答するよう強制される前に実行できる最大反復回数（つまり、ツールを呼び出すラウンド数）。コストを制御したり、エージェントの無限ループを防いだりする必要があるシナリオに適しています。

例

{
"agent": {
"quick-thinker": {
"description": "Fast reasoning with limited iterations",
"prompt": "You are a quick thinker. Solve problems with minimal steps.",
"steps": 5 // 最大5回の反復を実行し、超えた場合、エージェントは現在の進捗の要約と残りの推奨タスクを出力します。
}
}
}

未設定steps時、エージェントはモデルが自発的に停止するか、ユーザーが手動で中断するまで反復を続けます。

旧版maxStepsこのフィールドは非推奨です。統一して使用してください。steps。

tools（ツールアクセス）

このエージェントが使用できるツールを制御し、ツール名を設定する。true 或 false。プロキシレベル設定会グローバル設定を上書き：

例

{
"$schema": "https://opencode.ai/config.json",
"tools": {
"write": true, // グローバル：ファイル書き込みを許可
"bash": true // グローバル：bash コマンドを許可
},
"agent": {
"plan": {
"tools": {
"write": false, // プランプロキシ：グローバル設定を上書きし、ファイル書き込みを無効にする
"bash": false // プラン代理：グローバル設定を上書き、bashを無効にする
}
}
}
}

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

例

{
"agent": {
"readonly": {
"tools": {
"mymcp_*": false, // mymcp サーバーのすべてのツールを無効にする（glob マッチング）
"write": false,
"edit": false
}
}
}
}

permission（権限）

エージェントに対してより細かい粒度の権限制御を構成し、操作ごとに設定することができます。"allow"（許可）、"ask"（問い合わせ）または"deny"（拒否）

例

{
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "deny" // グローバル：デフォルトですべてのファイル編集を禁止する
},
"agent": {
"build": {
"permission": {
"edit": "ask" // ビルドプロキシ：グローバル設定を上書き、編集前の承認が必要
}
}
}
}

についてbashツールは、具体的なコマンドにまで詳細に指定でき、Glob ワイルドカードに対応し、さらに最後にマッチしたルールが優先。（提案：*ワイルドカード規則は前に、具体規則は後ろに置く）

例

{
"agent": {
"build": {
"permission": {
"bash": {
"*": "ask", // フォールバック：すべての bash コマンドはデフォルトで承認が必要
"git status *": "allow",// git status 関連コマンドは直接許可（より具体的で、優先マッチ）
"grep *": "allow" // grep 検索コマンドは直接許可する
}
}
}
}
}

Markdown プロキシファイルでは、frontmatter で権限を設定することもできます：

例

# ファイルパス：~/.config/opencode/agents/review.md
---
description: Code review without edits
mode: subagent
permission:
edit: deny # すべてのファイル編集を禁止
bash:
"*": ask bashコマンドはデフォルトで承認が必要です
"git diff": allow git diff を許可する
"git log*": allow git log およびそのバリアントを許可する
"grep *": allow grep検索を許可する
webfetch: deny 外部URLへのアクセス禁止
---

Only analyze code and suggest changes.

permission.task（タスク権限）

そのエージェントが Task ツールを介して呼び出せるサブエージェントを制御し、Glob マッチングに対応します。設定："deny"時、サブエージェントはTaskツールの説明から完全に削除され、モデルはそれを呼び出そうとしません：

例

{
"agent": {
"orchestrator": {
"mode": "primary",
"permission": {
"task": {
"*": "deny", // フォールバック：デフォルトではすべてのサブエージェントの呼び出しを禁止します
"orchestrator-*": "allow", // orchestrator- で始まるサブエージェントの呼び出しを許可する
"code-reviewer": "ask" // code-reviewer を呼び出す前にユーザーの確認が必要
最後にマッチしたルールが優先されます：orchestrator-planner は * と orchestrator-* の両方にマッチします、
// orchestrator-* は後ろにあるため、結果は allow になります。
}
}
}
}
}

hidden（非表示）

サブエージェントから@オートコンプリートメニューでは非表示となり、Taskツールを介してプログラム的にのみ呼び出しが可能で、他のエージェントによって内部的にのみ呼び出されるべきツールエージェントに適しています。

例

{
"agent": {
"internal-helper": {
"mode": "subagent", // hidden は subagent にのみ有効です
"hidden": true // 非表示にした後、ユーザーの @ 補完メニューにこのプロキシは表示されません。
ただし、権限が許可されている場合、モデルはTaskツールを介してそれを呼び出すことができます。
}
}
}

color（色）

UIにおけるエージェントの表示色をカスタマイズします。16進数の色値またはテーマの色キーワードをサポートしています（primary、secondary、accent、success、warning、error、info）：

例

{
"agent": {
"creative": {
"color": "#ff6b6b" // 16進カラーを使用
},
"code-reviewer": {
"color": "accent" // テーマカラーキーワードを使用
}
}
}

top_p（サンプリングの多様性）

top_pであるtemperature以外の、出力の多様性を制御するもう1つのパラメーターで、値の範囲は0.0〜1.0、値が低いほど出力は集中し、値が高いほど出力は多様になります：

例

{
"agent": {
"brainstorm": {
"top_p": 0.9 top_p を高くすると、出力の多様性が増す
}
}
}

disable（無効化）

エージェントを無効状態に設定します。無効にすると、エージェントは選択リストに表示されません：

例

{
"agent": {
"review": {
"disable": true // このプロキシを無効にし、他のプロキシには影響しません。
}
}
}

その他のモデルパラメータ

プロキシ設定内の未認識のフィールドは、すべてモデルパラメータとしてサービスプロバイダーに直接渡されます。これにより、プロバイダー独自の高度な機能を使用できます。

例

{
"agent": {
"deep-thinker": {
"description": "Agent that uses high reasoning effort for complex problems",
"model": "openai/gpt-5",
"reasoningEffort": "high", // OpenAI 推論強度パラメータ、OpenAI API へ直接透過する。
"textVerbosity": "low" // OpenAI 応答詳細度パラメータ
}
}
}

透過パラメータはサービスプロバイダーやモデルによって異なるため、対応するプロバイダーのAPIドキュメントを確認して、利用可能なパラメータ名をご確認ください。

エージェントのクイック作成

手動で設定ファイルを記述する以外にも、対話型コマンドラインツールを使用してプロキシをすばやく生成することもできます：

opencode agent create

このコマンドは、以下の手順を順番に案内します。

プロキシの保存場所を選択（グローバル~/.config/opencode/agents/またはプロジェクトレベル.opencode/agents/）
エージェントの責務と目標を説明する。
適切なシステムプロンプトとエージェント識別子を自動生成する
エージェントがアクセスできるツールを選択
選択した位置に完全な構成を含むMarkdownファイルを生成します。

エージェントの例

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

例

# ファイルパス：~/.config/opencode/agents/docs-writer.md
---
description: Writes and maintains project documentation
mode: subagent
tools:
bash: false bashを無効化し、ドキュメント作成にはコマンド実行は不要です。
---

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

よくある使用シーン

場面	推奨プロキシ設定
日常開発には、完全なツール権限が必要です。	内蔵を使用Build代理
コードを分析し、計画を立てますが、ファイルを修正したくありません。	内蔵に切り替えてPlan代理
読み取り専用でコードベースの構造またはキーワードを照会する	通過`@explore`組み込みを呼び出すExplore子エージェント
複数の独立したタスクを並行して実行する	通過`@general`複数呼び出しGeneralサブエージェントの並列処理
コードのセキュリティまたは品質レビューを実施する。	カスタム読み取り専用サブエージェント（write/editを無効化）、低温度（0.1）に設定
コストを抑え、AIの実行ステップ数を制限する	設定`steps`パラメータの最大反復回数制限

その他の拡張