エージェント

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

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

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

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

Types

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

Primary agents

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

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

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

Subagents

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

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

Built-in

OpenCode には 2 つの組み込みプライマリエージェントと 3 つの組み込みサブエージェントが付属しています。

Use build

モード: primary

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

Use plan

モード: primary

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

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

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

Use general

モード: subagent

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

Use explore

モード: subagent

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

Use scout

モード: subagent

外部ドキュメントと依存関係の調査のための読み取り専用エージェント。依存関係のリポジトリを OpenCode が管理するキャッシュにクローンしたり、ライブラリのソースを調べたり、ワークスペースを変更せずにローカルコードを上流の実装と相互参照したりする必要がある場合に使用します。

Use compaction

モード: primary

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

Use title

モード: primary

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

Use summary

モード: primary

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

Usage

プライマリエージェントの場合、セッション中に Tab キーで順に切り替えます。設定した switch_agent キーバインドも使用できます。
サブエージェントは以下の方法で呼び出せます。
- 自動的に: プライマリエージェントが説明に基づいて特定のタスクのために呼び出します。
- 手動で: メッセージで @ メンション します。例:
```
@general help me search for this function
```
セッション間のナビゲーション: サブエージェントが子セッションを作成したとき、session_child_first（デフォルト: <Leader>+Down）を使用して親から最初の子セッションに入ります。
子セッションに入ったら、以下を使用します。
- session_child_cycle（デフォルト: Right）で次の子セッションに順に移動
- session_child_cycle_reverse（デフォルト: Left）で前の子セッションに順に移動
- session_parent（デフォルト: Up）で親セッションに戻る
これにより、メインの会話と専門的なサブエージェント作業の間を切り替えることができます。

Configure

設定を通じて組み込みエージェントをカスタマイズしたり、独自のエージェントを作成したりできます。エージェントは 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}",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "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.",
      "permission": {
        "edit": "deny"
      }
    }
  }
}

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
permission:
  edit: deny
  bash: deny
---
 
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 エージェントを作成します。

Options

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

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 (deprecated)

tools は非推奨です。新しい設定、更新、よりきめ細かな制御には、エージェントの permission フィールドを使用してください。

このエージェントで使用可能なツールを制御できます。特定のツールを true または false に設定して有効または無効にできます。エージェントの tools 設定では、true は {"*": "allow"} 権限に相当し、false は {"*": "deny"} 権限に相当します。

opencode.json

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

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

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

opencode.json

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

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

Permissions

権限を設定して、エージェントが実行できるアクションを管理できます。各権限キーは以下に設定できます。

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

利用可能な権限キーは次のとおりです。

キー	ゲートするツール
`read`	`read`
`edit`	`write`、`edit`、`apply_patch`
`glob`	`glob`
`grep`	`grep`
`list`	`list`
`bash`	`bash`
`task`	`task`
`external_directory`	プロジェクトのワークツリー外のファイルを読み書きする任意のツール
`todowrite`	`todowrite`、`todoread`
`webfetch`	`webfetch`
`websearch`	`websearch`
`lsp`	`lsp`
`skill`	`skill`
`question`	`question`
`doom_loop`	エージェントが行き詰まっているように見えるときのリカバリープロンプト

read、edit、glob、grep、list、bash、task、external_directory、lsp、skill は、ショートハンドアクション（"allow" | "ask" | "deny"）か、きめ細かな制御のための glob/パターン → アクションのオブジェクトのいずれかを受け付けます。残りのキーはショートハンドアクションのみを受け付けます。

注記: 権限キーは、基礎となるツール名に対してワイルドカードパターンとして照合されます。そのため、組み込みツール、カスタムツール、MCP ツールに対して同じ構文が機能します。例えば "mymcp_*": "deny" は MCP サーバーのすべてのツールを拒否し、"mymcp_search": "ask" は単一のツールを対象とします。

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 を実行して、利用可能なモデルの一覧を確認できます。

Create agents

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

opencode agent create

このインタラクティブなコマンドは次のことを行います。

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

Use cases

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

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

Examples

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

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

Documentation agent

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

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

Security auditor

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

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
permission:
  edit: deny
---
 
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

ルールモデル