OpenCodeの設定 - エージェントチーム

提供: MochiuWiki : SUSE, EC, PCB

概要

OpenCodeは、Go言語で開発されたオープンソースのターミナルベースAIコーディングアシスタントツールである。
Bubble Teaフレームワークによるターミナルユーザインターフェース (TUI) を実装しており、75以上のAIモデルをサポートする。

OpenCodeには、プライマリエージェントとサブエージェントによる強力なエージェント機能が搭載されている。
プライマリエージェントはタスクの種類に応じて[Tab]キーで切り替え、サブエージェントは @メンション で呼び出すことができる。

oh-my-opencodeは、OpenCodeの機能を大幅に拡張するプラグインである。
the best agent harness として設計されており、11個の専門化されたエージェント、44個のライフサイクルフック、26以上の組み込みツールを提供する。

下表に、oh-my-opencodeが提供するエージェントチームの主な特徴を示す。

組み込みワークフローエージェント一覧
エージェント名 説明
Sisyphus メイン調整役・オーケストレーター
タスク完了まで実行継続し、中断後の自動再開をサポート
Hephaestus ゴール指定での自律的な深掘り作業
コードベース全体をエンドツーエンドで完了
Prometheus インタビューモードで十分なコンテキストを収集した上で専門エージェントに委譲
Librarian ドキュメント管理とコード例・パターン発見に特化
Explore 大規模コードベースのナビゲーションと依存関係分析に特化
Oracle コンテキスト認識型の質問応答とトラブルシューティングに特化



OpenCodeのエージェント機能

OpenCodeは、プライマリエージェントとサブエージェントの2種類のエージェントを提供する。

プライマリエージェント

プライマリエージェントはOpenCodeの主要な動作モードを制御する。

[Tab]キーで切り替えることができる。

エージェントモード一覧
エージェント名 説明
build デフォルトのエージェント
開発作業向けのフルツールアクセスが可能
コード編集、ファイル操作、コマンド実行など全ての操作を実行できる。
plan 読み取り専用エージェント
コード修正を行わずに分析・コード探索を行う。
コードベースの構造理解や実装方針の検討に使用する。


サブエージェント

サブエージェントは、@メンション で呼び出すことができる。

サブエージェント一覧
エージェント名 説明
general 複雑な調査やマルチステップタスクを担当する汎用サブエージェント
explore コードベース探索用の読み取り専用サブエージェント


カスタムエージェントの定義

カスタムエージェントは、opencode.json または ~/.config/opencode/agents/ 内のMarkdownファイルで定義できる。

opencode.json ファイルによるカスタムエージェント定義の例を以下に示す。

 {
    "agents": {
       "custom-agent": {
          "mode": "subagent",
          "model": "anthropic/claude-opus-4",
          "tools": {
             "edit": true,
             "bash": false,
             "view": true
          },
          "permission": {
             "edit": "ask",
             "bash": "deny"
          },
          "temperature": 0.7,
          "prompt": "You are a specialized code reviewer focused on security."
       }
    }
 }


カスタムエージェントの管理には以下のコマンドを使用する。

opencode agent create <エージェント名>
opencode agent list



oh-my-opencodeのインストール

前提条件

oh-my-opencodeのインストールに必要な前提条件を以下に示す。

  • OpenCode 1.0.133以降
    以前のバージョンでは動作しない場合がある。
  • Node.js最新バージョン
    bunx または npx コマンドが利用可能であること


対応プラットフォームを以下に示す。

  • MacOS (ARM64, x64)
  • Linux (x64, ARM64, Alpine/musl)
  • Windows (x64)


インストール手順

oh-my-opencodeのインストール手順を以下に示す。

  1. OpenCodeをインストールする。
    OpenCodeのインストールは、インストール - OpenCodeのページを参照すること。
  2. oh-my-opencodeをインストールする。 
    bunx oh-my-opencode install
  3. OpenCodeを起動する。 
    opencode


oh-my-opencodeはシェルエイリアスやPATHではなく、OpenCodeのプラグインシステムとして動作している。

oh-my-opencodeはOpenCodeのプラグインであり、単独のCLIではない。
インストール時はplugin配列に追加され、設定ファイルが作成される。

インストールオプション

bunx oh-my-opencode install には、各種AIプロバイダーの設定を同時に行うオプションが用意されている。

bunx oh-my-opencode install --no-tui --claude=<yes|no|max20> --gemini=<yes|no> --copilot=<yes|no> --openai=<yes|no>


下表に、利用可能なオプションを示す。

インストールスクリプトのオプション一覧
オプション 説明
--claude=yes|no|max20 Claudeの認証設定を行う。
max20 は、Claude Max (月20ドルプラン) を指定する。
--openai=yes|no OpenAIの認証設定を行う。
--gemini=yes|no Google Geminiの認証設定を行う。
--copilot=yes|no GitHub Copilotの認証設定を行う。
--opencode-zen=yes|no OpenCode Zenの設定を行う。
--zai-coding-plan=yes|no Z.AIコーディングプランの設定を行う。
--no-tui TUIを使用せず、対話なしでインストールを実行する。


代替インストール方法を以下に示す。

npm install -g oh-my-opencode
bun install -g oh-my-opencode
yarn global add oh-my-opencode
pnpm add -g oh-my-opencode



oh-my-opencodeのアンインストール

OpenCodeの設定ファイルからプラグインを削除

OpenCodeの設定ファイルを編集して、プラグインエントリを削除する。

  • 設定ファイルの場所
    • MacOS / Linux
      ~/.config/opencode/opencode.json
      または
      opencode.jsonc
    • Windows
      %USERPROFILE%\.config\opencode\opencode.json
      または
      opencode.jsonc


削除対象ファイル一覧
場所 ファイル 用途
OpenCode設定 ~/.config/opencode/opencode.json
または
/<プロジェクトルート>/opencode.jsonc		 plugin配列からエントリ削除
ユーザ設定 ~/.config/opencode/oh-my-openagent.json[c] ユーザプラグイン設定 (新名称)
ユーザ設定 ~/.config/opencode/oh-my-opencode.json[c] ユーザプラグイン設定 (旧名称)
プロジェクト設定 .opencode/oh-my-openagent.json[c] プロジェクトプラグイン設定 (新名称)
プロジェクト設定 .opencode/oh-my-opencode.json[c] プロジェクトプラグイン設定 (旧名称)


設定ファイル内のplugin配列から oh-my-openagent または oh-my-opencode のエントリを削除する。

設定ファイルを削除

プラグイン固有の設定ファイルを削除する。

  • ユーザ全体の設定ファイル 
     # プラグイン設定ファイルを削除
 rm -f ~/.config/opencode/oh-my-openagent.jsonc ~/.config/opencode/oh-my-openagent.json \
       ~/.config/opencode/oh-my-opencode.jsonc ~/.config/opencode/oh-my-opencode.json

  • プロジェクト固有の設定ファイル (プロジェクト内に存在する場合) 
     # プロジェクト設定ファイルを削除（各プロジェクトディレクトリで実行）
 rm -f .opencode/oh-my-openagent.jsonc .opencode/oh-my-openagent.json \
       .opencode/oh-my-opencode.jsonc .opencode/oh-my-opencode.json


削除の確認

OpenCodeのバージョンコマンドを実行して、プラグインが表示されないことを確認する。

opencode --version



oh-my-opencodeの設定

設定ファイルの場所

oh-my-opencodeの設定ファイルの場所を以下に示す。
優先度が高い設定が低い設定を上書きする。

  • プロジェクト固有設定 (最優先)
    .opencode/oh-my-opencode.json
  • ユーザ全体設定
    ~/.config/opencode/oh-my-opencode.json


エージェント設定

各エージェントの有効 / 無効を設定できる。

 {
    "agents": {
       "planner-sisyphus": {"enabled": true, "replace_plan": true},
       "hephaestus": {"enabled": false},
       "prometheus": {"enabled": false},
       "librarian": {"enabled": false},
       "explore": {"enabled": false},
       "oracle": {"enabled": false}
    }
 }


カスタムエージェントの設定項目
設定項目 説明
enabled true でエージェントを有効化、false で無効化する。
replace_plan true に設定すると、デフォルトのplanエージェントをこのエージェントで置き換える。


フック設定

不要なライフサイクルフックを無効化できる。

 {
    "disabled_hooks": ["comment-checker", "agent-usage-reminder"]
 }


disabled_hooks に無効化するフック名を配列で指定する。

MCP設定

不要なMCPサーバを無効化できる。

 {
    "disabled_mcps": ["context7", "grep_app"]
 }


disabled_mcps に無効化するMCP名を配列で指定する。


エージェントチーム

oh-my-opencodeが提供するエージェントチームの各メンバーについて説明する。

Sisyphus

Sisyphusは、oh-my-opencodeのデフォルトエージェントであり、メインの調整役・オーケストレーターとして機能する。
ギリシャ神話のシジフォスから命名されており、タスクが完了するまで粘り強く実行し続けることを表している。

下表に、主な特徴を示す。

Sisyphusの特徴
項目 説明
役割 メイン調整役・オーケストレーター
計画、委譲、並列実行管理を担当する。
todo-driven workflow タスクリストを管理しながら順序立てて実行する。
extended thinking 複雑な問題に対して深く考察してから行動する。
自動再開 中断後もタスクを自動的に再開できる。
推奨モデル Claude Pro/Maxサブスクリプションを推奨


Sisyphusは replace_plan: true を設定することにより、デフォルトのplanエージェントを置き換えることができる。

Hephaestus

Hephaestusは、ゴールを指定するだけで自律的に深く作業を進めるエージェントである。
ギリシャ神話の鍛冶の神ヘパイストスから命名されており、ツールや技術の精通を象徴する。

下表に、主な特徴を示す。

Hephaestus の主な特徴
項目 説明
役割 自律的な深い作業者
ゴール指定での独立実行が得意。
コードベースパターン探索 プロジェクト全体のパターンを自ら探索・理解する。
エンドツーエンド完了 タスク開始から完了まで自律的に実行する。
Sisyphusとの違い 他のエージェントへの委譲ではなく、自ら深掘りして作業を完遂する。


Prometheus

Prometheusは、十分なコンテキストを収集した上で専門エージェントに委譲する戦略的プランナーエージェントである。
ギリシャ神話のプロメテウスから命名されており、先見性と戦略的思考を象徴する。

下表に、主な特徴を示す。

Prometheusの特徴
項目 説明
役割 戦略的プランナー
委譲ベースの実行を担当する。
インタビューモード 作業開始前に十分なコンテキストを収集するための質問を行う。
要求分類 ユーザの要求をリファクタリングと新機能開発に分類し、適切な専門エージェントに委譲する。
直接実行との違い 自ら直接実行するのではなく、適切な専門家に委ねる。


Librarian

Librarianは、ドキュメント管理とコード例・パターン発見に特化したエージェントである。

下表に、主な特徴を示す。

Librarianの特徴
項目 説明
役割 ドキュメント・コード探索専門
ドキュメント管理、コード例・パターンの発見を担当する。
コードベース構造理解 プロジェクトのファイル構成や依存関係を把握する。
Context7 MCP との連携 Context7 MCPと組み合わせて使用することで効果的に機能する。


Explore

Exploreは、大規模コードベースのナビゲーションに特化したエージェントである。

下表に、主な特徴を示す。

Exploreの特徴
項目 説明
役割 コード探索専門
大規模コードベースのナビゲーションを担当する。
素早いコード移動 関連するコード間を効率的に移動できる。
パターン検出 コードベース内のパターンを素早く見つける。
依存関係分析 モジュール間の依存関係を分析する。
用途 未知のコードベースへの入門や、既存コードの把握に適している。


Oracle

Oracleは、コンテキストを理解した上で質問に答えることに特化したエージェントである。

下表に、主な特徴を示す。

Oracleの特徴
項目 説明
役割 Q&A 特化型。コンテキスト認識型の質問応答を担当する。
コード動作原理説明 なぜそのコードがそのように動作するかを説明する。
ベストプラクティス提示 特定の問題に対する推奨されるアプローチを示す。
トラブルシューティング 問題の原因と解決策を分析する。


エージェントの比較

下表に、各エージェントの特性を示す。

oh-my-opencode エージェント比較
エージェント 主な役割 特性 推奨用途
Sisyphus オーケストレーター todo-driven、委譲、並列実行 複雑なマルチステップタスク全般
Hephaestus 自律実行者 深掘り、エンドツーエンド完了 単一ゴールの自律的な実装
Prometheus 戦略プランナー インタビュー、分類、委譲 要件が不明確な大きなタスク
Librarian ドキュメント探索 コードパターン発見 ドキュメント作成・コード調査
Explore コード探索 ナビゲーション、依存関係分析 未知コードベースへの入門
Oracle Q&A コンテキスト認識型回答 技術的な質問・トラブルシューティング



エージェントの使用方法

基本的な使い方

各エージェントの呼び出し方法を以下に示す。

  • プライマリエージェントの切り替え
    [Tab]キーを押下することにより、build と plan エージェントを切り替える。
  • サブエージェントの呼び出し
    チャット入力欄で @ に続けてエージェント名を入力する。


サブエージェントの呼び出し例を以下に示す。

@Librarian このプロジェクトの認証モジュールの構造を教えて

@Oracle このエラーの原因と解決策を教えて

@Explore このファイルに依存しているモジュールを全て教えて


ultraworkコマンド

oh-my-opencodeが提供する ultrawork コマンド (短縮形: ulw) を使用することにより、エージェントがプロジェクトの探索から実装・検証・完了まで自動的に実行する。

ultraworkコマンドの使用例を以下に示す。

opencode "ultrawork: Refactor user authentication module, add OAuth2 support"


ultraworkコマンドの実行フローを以下に示す。

  1. プロジェクト探索
    コードベース全体の構造を把握する。
  2. パターン研究
    既存のコードパターンやアーキテクチャを理解する。
  3. 実装
    タスクを実行する。
  4. 検証
    実装結果を確認・テストする。
  5. 完了
    タスクを完了して結果を報告する。


auto_resume 機能を有効化することにより、中断後も自動的にタスクを再開できる。
設定方法を以下に示す。

 {
    "experimental": {
       "auto_resume": true
    }
 }



認証設定

Claude (Anthropic)

Anthropic Claudeの認証設定手順を以下に示す。

  1. 以下に示すコマンドを実行する。 
    opencode auth login

  2. 表示された一覧から[Anthropic]を選択する。
  3. Claude Pro/Max を選択する。
  4. Webブラウザが開くので、OAuthで認証する。


Sisyphusエージェントを最大限活用するには、Claude Maxサブスクリプションを推奨する。

Google Gemini

Google Geminiの認証には、opencode-antigravity-auth プラグインを使用する。

  1. ~/.config/opencode/opencode.json にプラグインを追加する。 
     {
    "plugin": ["oh-my-opencode", "opencode-antigravity-auth@latest"]
 }

  2. 以下に示すコマンドを実行する。 
    opencode auth login
  3. 表示された一覧から[Google]を選択し、OAuth (Antigravity) で認証する。


GLM 5 (Z.AI)

GLM-5は、智谱AI (Zhipu AI / Z.AI) が開発した大規模言語モデルである。
744億パラメータのMoEアーキテクチャを採用し、アクティブパラメータは約40億、コンテキスト長は200,000トークンに対応する。

認証手順を以下に示す。

  1. opencode auth login を実行して、[Z.AI]を選択する。
  2. Z.AI Open Platformにアクセスして、APIキーを取得する。
  3. APIキーを入力する。
    APIキーの形式は {API Key ID}.{secret} である。


  • opencode.json ファイルに記述するカスタムプロバイダー設定を以下に示す。 
     {
    "provider": {
       "zai": {
          "npm": "@ai-sdk/openai-compatible",
          "name": "Z.AI",
          "options": {
             "baseURL": "https://api.z.ai/api/paas/v4/",
             "apiKey": "{env:ZAI_API_KEY}"
          },
          "models": {
             "glm-5": {
                "name": "GLM-5"
             }
          }
       }
    },
    "model": "zai/glm-5"
 }

  • コーディング専用エンドポイントを使用する場合の設定を以下に示す。 
     {
    "provider": {
       "zai-coding": {
          "npm": "@ai-sdk/openai-compatible",
          "name": "Z.AI Coding",
          "options": {
             "baseURL": "https://api.z.ai/api/coding/paas/v4/",
             "apiKey": "{env:ZAI_API_KEY}"
          },
          "models": {
             "glm-5": {
                "name": "GLM-5 Coding"
             }
          }
       }
    },
    "model": "zai-coding/glm-5"
 }

  • 環境変数を使用してAPIキーを設定する場合は、以下に示すコマンドを実行する。 
     export ZAI_API_KEY=<APIキー>


GitHub Copilot

GitHub Copilotの認証設定手順を以下に示す。

  1. 以下に示すコマンドを実行する。 
    opencode auth login

  2. 表示された一覧から[GitHub]を選択する。
  3. Webブラウザが開くので、OAuthで認証する。



トラブルシューティング

下表に、oh-my-opencodeのインストールおよび動作に関する問題と対処法を示す。

トラブルシューティング一覧
問題 対処法
インストールが失敗する Node.jsの最新バージョンがインストールされているか確認する。
OpenCode 1.0.133以降を使用しているか確認する。
JSONの設定が反映されない 設定ファイルの内容が有効なJSON形式であるか確認する。
bunx コマンドが見つからない npx oh-my-opencode install を使用する。
npmキャッシュの問題 以下に示すコマンドでキャッシュをクリアする。
npm cache clean --force
Snapでインストールしたbunの問題 npxを使用する、または、OpenCodeのオフィシャルインストーラーを再利用する。
エージェントが起動しない oh-my-opencode.json の enabled が true になっているか確認する。
インストール後にエージェントが表示されない 異なるパッケージマネージャー (npm, bun, yarn, pnpm) でのインストールを試みる。



「https://mochiu.net/index.php?title=OpenCodeの設定_-_エージェントチーム&oldid=14631」から取得