コンテンツにスキップ
OpenCode
app.header.homeapp.header.docs

エージェント

特殊なエージェントを構成して使用します。

エージェントは、特定のタスクやワークフロー向けに構成できる特殊な AI アシスタントです。これらを使用すると、カスタム プロンプト、モデル、ツール アクセスを備えた焦点を絞ったツールを作成できます。

You can switch between agents during a session or invoke them with the @ mention.

種類

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

主要エージェント

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

OpenCode には、Build と Plan という 2 つの組み込みプライマリ エージェントが付属しています。これらについて以下で説明します。

サブエージェント

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

OpenCode には、General と Explore という 2 つの組み込みサブエージェントが付属しています。これについては以下で見ていきます。

内蔵

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

ビルドを使用する

モード: primary

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

利用プラン

モード: primary

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

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

このエージェントは、コードベースに実際の変更を加えずに LLM にコードの分析、変更の提案、または計画の作成を行わせたい場合に役立ちます。

一般的な使用

モード: subagent

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

探索を使用する

モード: subagent

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

圧縮を使用する

モード: primary

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

タイトルを使用する

モード: primary

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

使用概要

モード: primary

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

使用法

  1. プライマリ エージェントの場合は、セッション中に Tab キーを使用してエージェントを切り替えます。設定した switch_agent キーバインドを使用することもできます。

  2. サブエージェントは次のように呼び出すことができます。

    • プライマリ エージェントによって、説明に基づいて特殊なタスクを 自動的に 実行されます。

    • メッセージ内でサブエージェントを @ メンションすることで手動で実行できます。例えば。

      @general help me search for this function

  3. セッション間のナビゲーション: サブエージェントが独自の子セッションを作成する場合、以下を使用して親セッションとすべての子セッションの間を移動できます。

    • <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 オプションを使用して、エージェントの機能とそれをいつ使用するかについての簡単な説明を提供します。

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

これは必須の構成オプションです。

温度

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

値が低いほど、応答はより集中的かつ決定的になりますが、値が高いほど、創造性と変動性が高まります。

opencode.json
{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

通常、温度値の範囲は 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}"
    }
  }
}

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

最大ステップ数

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

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

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

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

無効にする

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

opencode.json
{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

プロンプト

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

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

このパスは、構成ファイルが配置されている場所に対する相対パスです。したがって、これはグローバルな OpenCode 構成とプロジェクト固有の構成の両方で機能します。

モデル

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 構成を使用して、このエージェントで使用できるツールを制御します。特定のツールを 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
      }
    }
  }
}

tools について詳しくはこちらをご覧ください。

権限

権限を設定して、エージェントが実行できるアクションを管理できます。現在、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"
        }
      }
    }
  }
}

これにはグロブ パターンを使用できます。

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 オプションは、エージェントの使用方法を決定するために使用されます。

opencode.json
{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

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

隠れた

@ を使用して、hidden: true オートコンプリート メニューからサブエージェントを非表示にします。他のエージェントによってタスク ツールを介してプログラム的にのみ呼び出す必要がある内部サブエージェントに役立ちます。

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

これは、オートコンプリート メニューでのユーザーの表示にのみ影響します。権限が許可されていれば、非表示のエージェントをタスク ツール経由でモデルから呼び出すことができます。

タスクの権限

permission.task を使用して、エージェントがタスク ツール経由でどのサブエージェントを呼び出すことができるかを制御します。柔軟なマッチングのためにグロブ パターンを使用します。

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

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

色

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

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

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

トップP

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

opencode.json
{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

値の範囲は 0.0 ～ 1.0 です。値が低いほど集中力が高まり、値が高いほど多様性が高まります。

追加

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

たとえば、OpenAI の推論モデルを使用すると、推論の労力を制御できます。

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

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

エージェントの作成

次のコマンドを使用して、新しいエージェントを作成できます。

Terminal window
opencode agent create

この対話型コマンドは次のことを行います。

  1. エージェントを保存する場所を尋ねます。グローバルまたはプロジェクト固有。
  2. エージェントが行うべきことの説明。
  3. 適切なシステム プロンプトと識別子を生成します。
  4. エージェントがアクセスできるツールを選択できます。
  5. 最後に、エージェント構成を含むMarkdown ファイルを作成します。

ユースケース

さまざまなエージェントの一般的な使用例をいくつか示します。

  • ビルド エージェント: すべてのツールを有効にした完全な開発作業
  • 計画エージェント: 変更を加えずに分析および計画を立てる
  • レビュー エージェント: 読み取り専用アクセスとドキュメント ツールを備えたコード レビュー
  • デバッグ エージェント: bash および読み取りツールを有効にして調査に重点を置きます
  • ドキュメント エージェント: ファイル操作を使用してドキュメントを作成しますが、システム コマンドは使用しません

例

以下に、役立つと思われるエージェントの例をいくつか示します。

文書作成エージェント

~/.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