Chaos and Order

💡 왼쪽 원문을 읽으면서 오른쪽에 따라 써보세요. Tab 키로 힌트를 받을 수 있습니다.

概要
- 非同期サブエージェントがなぜ重要か
1. 前提条件 — OpenCode のインストールと基本操作
2. Oh My OpenCode のインストール
3. 設定 — エージェント別・カテゴリ別のモデルオーバーライド
4. マルチエージェントチーム — エージェントロースター
- 4.1 読み取り専用スペシャリストがもたらす安全性
5. ultrawork で作業を実行する
6. コスト安全 — 必ず押さえること
7. いつ使い、いつバニラの OpenCode を使うか
- 7.1 選択チェックリスト
- 7.2 ひと目でわかる要約
参考資料

概要

ターミナルで動く AI コーディングエージェントが増えるにつれ、いまや「1 体のエージェント」ではなく「エージェントのチーム」を扱う時代になった。Oh My OpenCode は、まさにそのチームを組み立てるためのツールだ。サイトは ohmyopencode.com、GitHub リポジトリは opensoft/oh-my-opencode、npm パッケージは oh-my-opencode である。

Oh My OpenCode は独立したエージェントではなく、OpenCode の上に載せる意見の強い(opinionated)プラグインでありオーケストレーションレイヤーだ。OpenCode は opencode.ai が配布するオープンソースのターミナル AI コーディングエージェントで、本記事の前提条件になる。その上に Oh My OpenCode は次を追加する。

Claude Code のように振る舞う非同期サブエージェント(async subagents)
それぞれ適切なモデルに割り当てられた、厳選された専門エージェントのロースター
厳選された MCP サーバー群
同梱される LSP/AST ツール
「Claude Code 互換」レイヤー

一文でまとめると、ターミナルの中に存在する仮想の AI 開発チームだ。コーディネーターが計画を立て、ワーカーがコードを書き、スペシャリストがアーキテクチャをレビューしドキュメントを掘る。本記事では OpenCode の基礎から始め、Oh My OpenCode のインストールと設定、マルチエージェントチームの編成、実際の作業の実行、そして必ず押さえるべきコスト安全までを順に扱う。

なお、別の作者による兄弟プロジェクト oh-my-openagent(別名 lazycodex)も存在する。名前が似ていて紛らわしいので、存在だけ一文で触れておき、本記事は徹底して oh-my-opencode に集中する。

非同期サブエージェントがなぜ重要か

従来のコーディングエージェントは、たいてい一つの対話の流れの中で逐次的に動いていた。ファイルを読み、修正し、次のファイルへ進む、という具合だ。この方式は小さな変更には十分だが、数十のファイルを同時に見なければならない大きな作業ではボトルネックになる。非同期サブエージェントはこのボトルネックを壊す。メインエージェントが複数のサブエージェントを同時に立ち上げ、それぞれ別のファイルや別の観点を並列で処理させるのだ。

Claude Code が広めたこのパターンを、Oh My OpenCode は OpenCode の上で再現する。コーディネーターは全体像を握り、コードベース検索は Explore に、ドキュメント調査は Librarian に、アーキテクチャ判断は Oracle に分担させる。各サブエージェントは自分の担当分だけを終えて結果をコーディネーターに返すので、人が複数のターミナルタブを行き来して手で調整していた作業をツールが肩代わりする。本記事の残りは、そのチームを実際に動かす方法だ。

1. 前提条件 — OpenCode のインストールと基本操作

Oh My OpenCode を使う前に、まず OpenCode をインストールして手に馴染ませておく必要がある。OpenCode がなければ Oh My OpenCode も動作しない。

1.1 インストール

もっとも簡単なのは公式のインストールスクリプトだ。

curl -fsSL https://opencode.ai/install | bash

npm や Homebrew を好むなら、以下の方法もある。

npm i -g opencode-ai

brew install anomalyco/tap/opencode

1.2 プロジェクトで実行する

インストールが済んだら、作業したいプロジェクトのディレクトリに移動して実行する。

cd my-project
opencode

するとターミナル UI(TUI)が起動する。初めて実行するなら、次のコマンドを先に覚えておくとよい。

/init — リポジトリをスキャンして AGENTS.md ファイルを生成する。プロジェクトの構造と規約をエージェントが理解するための基準文書になる。
/connect — モデルプロバイダーを追加する。OpenRouter、OpenAI、Anthropic、ローカルモデルなど好きなものを選び、プロンプトが出たら API キーを貼り付ける。
Tab — Plan モードと Build モードを切り替える。まず計画を立てて実行へ進む流れを作るときに便利だ。
@ — ファイルをファジー検索(fuzzy-find)する。コンテキストに入れるファイルをすばやく見つけられる。
/share、/undo、/redo — セッション共有、取り消し、やり直し。ミスしたときに役立つ。

1.3 OpenRouter を接続する例

/connect を実行するとプロバイダー一覧が出る。OpenRouter を選ぶと API キーを尋ねられるので、openrouter.ai で発行したキーを貼り付ければよい。OpenRouter は多数のモデルを 1 つのキーで扱えるため、後述するエージェントごとのモデル割り当てを試すときに特に便利だ。接続が終われば TUI の中からそのままモデルを選んで使える。

1.4 Plan モードと Build モードを分ける習慣

Tab で切り替える 2 つのモードは、単なる UI スイッチではなく作業姿勢の違いだ。Plan モードは、エージェントがコードをすぐには変えず、何をどうするかをまず提案するようにする。Build モードは実際にファイルを修正して実行する。慣れるまでは、Plan モードでアプローチを確認し、方向が合っていそうなら Build モードへ移る流れを勧める。この習慣ひとつで、「エージェントが見当違いのファイルを触ってしまった」といった事故を大きく減らせる。後述する Oh My OpenCode の計画優先の流れも、結局はこの 2 つのモードの拡張版だ。

2. Oh My OpenCode のインストール

OpenCode に慣れたら、いよいよチームを編成する番だ。Oh My OpenCode のインストールはプロジェクトのルートで実行し、Bun または npx が必要になる。

2.1 対話型インストール

もっとも標準的なのは bunx でインストーラーを実行することだ。

bunx oh-my-opencode install

このコマンドは対話型 TUI を起動する。ここでどのエージェントを使うか、どのツールと MCP を接続するかを段階的に選ぶと、あとは自動で配線(wiring)してくれる。初めてなら、この対話型の方法を勧める。

2.2 非対話型インストール(CI / エージェント向け)

CI パイプラインや別のエージェントが自動で回す必要がある場合は、対話型 UI なしでフラグで指定できる。

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

各フラグでどのプロバイダーを組み込むかを決める。たとえば --claude=max20 は Claude 系を上位ティアで組み込む意味であり、不要なプロバイダーは no でオフにすればよい。

2.3 インストールの確認

インストールが済んだら、プロジェクトに .opencode/ ディレクトリと関連する設定ができたかを確認する。その後 OpenCode を再度実行すると、Oh My OpenCode が配線したエージェント・ツール・MCP が読み込まれた状態で TUI が起動する。もしエージェントが見当たらない場合は、グローバルインストールを試していないか、プロジェクトのルートで実行したかをまず見直すとよい。初期の問題の多くは、実行場所とパッケージ名を取り違えたことに由来する。

2.4 必ず知っておくべき注意点

インストールに関してよくやる間違いがいくつかある。はっきり指摘しておこう。

グローバルインストールはサポートされない。npm i -g や bun add -g は対象外だ。必ずプロジェクトのルートで bunx から実行すること。
npm の omo はまったく別の無関係なパッケージだ。bunx omo を実行すると関係ないパッケージが動くので、絶対に使わないこと。
前述の兄弟プロジェクト oh-my-openagent(lazycodex)とも混同しないこと。名前が似ているだけで、本ガイドの対象ではない。

3. 設定 — エージェント別・カテゴリ別のモデルオーバーライド

Oh My OpenCode の真価は設定にある。どのエージェントがどのモデルを使うかを細かく制御できるからだ。

3.1 設定ファイルの場所

設定ファイルは 2 か所に置ける。

プロジェクト別: .opencode/oh-my-opencode.jsonc
ユーザー別: ~/.config/opencode/oh-my-opencode.json

プロジェクト別の設定はそのリポジトリだけに適用され、ユーザー別の設定はすべてのプロジェクトに適用される。チームのリポジトリなら、再現性の観点からプロジェクト別ファイルをコミットしておくのが有利だ。

3.2 モデルオーバーライドの例

エージェントごと、そしてカテゴリごとにモデルを変えられる。JSONC はコメントを許すので、設定の意図をファイル内に残せる。

{
  "agents": {
    "explore": { "model": "ollama/qwen2.5-coder:7b" },
    "oracle": { "model": "openai/gpt-5.4" }
  },
  "categories": {
    "quick": { "model": "ollama/qwen2.5-coder:7b" },
    "deep": { "model": "openai/gpt-5.3-codex" }
  }
}

この例は 2 つの軸を同時に示している。agents ブロックは特定のエージェント(たとえばコードベースをすばやく掃く Explore)に安価なローカルモデルを割り当て、アーキテクチャ相談を担う Oracle にはより強いモデルを付ける。categories ブロックは作業の性質でまとめ、軽く頻繁な quick 作業はローカルモデルへ、重い deep 作業は codex 系へルーティングする。後のカテゴリ節でこの考え方をさらに掘り下げる。

3.3 エージェント指定とカテゴリ指定の優先順位

よく出る質問は「エージェントに指定したモデルとカテゴリに指定したモデルが衝突したら、どちらが勝つか」だ。概念的に整理するとこうなる。カテゴリは、作業の種類に応じて動的に生成されるエージェント(たとえば Sisyphus-Junior)がどのモデルを継承するかを決める広い規則だ。一方、エージェント別の指定は、名前が固定された特定のエージェント(たとえば Oracle や Explore)に直接付く狭い規則だ。したがって実務では、名前が明確な常設エージェントは agents で、作業種別によって分かれる実行者は categories で管理する、という具合に役割を分けると設定がすっきりする。

3.4 チームリポジトリでの設定共有

プロジェクト別の .opencode/oh-my-opencode.jsonc をリポジトリにコミットしておけば、チーム全員が同じエージェント-モデルの対応で作業することになる。これは「自分のローカルでは安いモデルでうまく回ったのに、同僚の環境では高いモデルに跳ねた」といった再現性の問題を減らす。ただし API キーのような秘密の値はこのファイルに入れない。キーは前述の /connect の流れやプロバイダーごとの環境変数で管理し、設定ファイルにはモデル選択や同時実行数の制限といったポリシーだけを残すのが原則だ。

4. マルチエージェントチーム — エージェントロースター

Oh My OpenCode は役割が定まったエージェントのロースターを提供する。各エージェントには名前、責務、そして推奨モデルが決められている。以下の表は役割グループ別に整理したものだ。

役割グループ	エージェント	責務	推奨モデル / 特徴
オーケストレーター	Sisyphus	メインコーディネーター。計画を立てて委任し、積極的な並列実行でタスクを推し進める	既定 Claude Opus
オーケストレーター	Atlas	ToDo リストのオーケストレーター	Claude Sonnet
プランニング	Prometheus	戦略プランナー。`Tab` または `/start-work` で起動し、インタビューでスコープを固める	プランニング特化
プランニング	Metis	ギャップ分析器(gap analyser)。抜け漏れを見つける	高い temperature
プランニング	Momus	容赦ない計画レビュアー。OK/reject のゲート役	承認ゲート
ワーカー	Hephaestus	自律的なディープコーダー。強力な codex 級モデルを期待する	codex 級モデル
ワーカー	Sisyphus-Junior	動的に生成される実行者。起動元カテゴリのモデルを継承する	カテゴリ継承
スペシャリスト	Oracle	アーキテクチャ/デバッグの相談役(読み取り寄り)	強い推論モデル
スペシャリスト	Librarian	ドキュメントリサーチャー。安く速いモデルで十分	低コストモデル
スペシャリスト	Explore	grep/パターンでコードベースを高速に並列検索	高速モデル
スペシャリスト	Multimodal Looker	ビジョン。図・PDF・画像を読む	マルチモーダルモデル

このロースターを読む鍵は「誰が何を、どのコストで行うか」だ。オーケストレーターとプランナーは全体の流れを制御し、ワーカーは実際にコードを生み出し、スペシャリストは読み取り専用またはツールが制限されたサブエージェントとして特定の作業だけを担う。たとえばドキュメントを掘る Librarian やコードベースを検索する Explore に高価なモデルを付ける理由はなく、自律的に深くコードを書く Hephaestus には強いモデルが必要だ。

ロースターを実際のモデル予算に対応づけるときは、おおよそ次の原則で考えるとよい。

オーケストレーター(Sisyphus、Atlas): 全体を統率するので、判断力の高い上位モデルが有利だ。既定値を尊重しつつ、予算が厳しければ Atlas から下げる。
プランナー(Prometheus、Metis、Momus): 計画の品質が結果を左右するので、安すぎるモデルは避ける。Metis は高い temperature で抜けを見つける役割だと覚えておく。
ワーカー(Hephaestus、Sisyphus-Junior): 実際の実装品質に直結する。Hephaestus には codex 級を、Sisyphus-Junior にはカテゴリを通じて適切なモデルを継承させる。
スペシャリスト(Oracle、Librarian、Explore、Multimodal Looker): 役割の差が大きい。Oracle と Multimodal Looker には強いモデルを、Librarian と Explore には安く速いモデルを割り当てるのがコスト効率的だ。

4.1 読み取り専用スペシャリストがもたらす安全性

スペシャリストのグループが読み取り専用またはツール制限されている点は、単なる制約ではなく設計上の安全装置だ。Oracle がアーキテクチャを診断したり Explore がコードを走査したりするとき、これらがファイルを直接修正できないように縛っておけば、相談の過程で意図せずコードが変わってしまう事故を根本から防げる。実際の変更は Hephaestus や Sisyphus-Junior のようなワーカーにだけ任せ、スペシャリストは助言と情報の提供に徹するよう役割を分けるのだ。この構造のおかげで、並列に多数のエージェントが動いても、ファイルを書く主体は少数のワーカーに絞られ、全体の制御が容易になる。

5. ultrawork で作業を実行する

エージェントチームはあるが、ただプロンプトを入れるだけで自動的にチームが動くわけではない。マルチエージェントの委任は明示的にトリガーする必要がある。

5.1 トリガーキーワード

マルチエージェントの委任は、プロンプトに ultrawork というキーワード(接頭辞 ulw)を入れると発動する。これは自動ではない。つまり、通常のプロンプトは単一エージェントで処理され、チーム全体を動員するには意図的に ultrawork(または ulw)を付ける必要がある、ということだ。

5.2 計画優先の流れ

重い作業ほど、いきなり実行するより先に計画を立てるほうがよい。Tab または /start-work で Prometheus を起動すると、このプランナーがインタビューを通じて作業スコープを明確に固めてくれる。スコープが曖昧なまま並列実行を回すと、サブエージェントがそれぞれ別方向へ走り出しかねないので、大きな作業は計画 → 実行の順を守るのが安全だ。

5.3 カテゴリルーティング

委任された作業はカテゴリを通じてルーティングされる。各カテゴリは推奨モデルとフォールバックチェーン(fallback chain)に割り当てられている。カテゴリは次のとおりだ。

visual-engineering
artistry
ultrabrain
deep
unspecified-high
unspecified-low
quick
writing

作業がどのカテゴリに分類されるかで、どのモデルが付くかが決まる。第 3 章で見たとおり、カテゴリごとにモデルをオーバーライドすれば、コストと性能を作業の性質に合わせて調整できる。

5.4 起動オーバーヘッド

現実的な注意点が一つある。マルチエージェントのオーケストレーションには起動オーバーヘッドが実在する。本格的な作業が始まる前に、およそ 15,000〜25,000 トークンが消費される。小さな作業にこのオーバーヘッドを払うのは損なので、いつチームを動員するかの判断が重要だ。この判断は最終章でまとめる。

5.5 典型的な作業の流れ

これまでの要素を一つにつなぐと、大きな作業の標準的な流れは次のように整理できる。

Tab または /start-work で Prometheus を起動して計画を立てる。ここでインタビューに真剣に答えてスコープを狭める。
必要なら Metis が計画の抜けを見つけ、Momus が計画を承認または却下する。
計画が通れば、プロンプトに ultrawork(または ulw)を付けてマルチエージェント実行を発動する。
Sisyphus が作業をカテゴリごとに分割して委任する。検索は Explore、ドキュメントは Librarian、深い実装は Hephaestus、アーキテクチャ判断は Oracle が担う。
各サブエージェントの結果がコーディネーターに集まったら、最終的な変更をレビューし、必要なら /undo で巻き戻す。

この流れを体に馴染ませれば、「計画なしにいきなり ultrawork」のような危険な習慣を避けられる。計画のステップが短くても、スコープを固めておくことが、並列実行が誤った方向へ暴走するのを防ぐもっとも安価な保険になる。

6. コスト安全 — 必ず押さえること

この部分は正直に指摘すべきだ。マルチエージェントツールは便利な分、コストが制御を外れる危険もある。

6.1 実際にあった事故

初期に確認されたバグにより、予期しない大きな支出が発生した事例がある。あるユーザーは、たった一日の午後だけで約438ドルを請求されたと報告した。原因は静かに起きたモデルルーティング(silent model routing)と暴走するループ(runaway loop)だった。つまり、ユーザーが意図しない高価なモデルへ作業が流れ、それが止まらずに繰り返されて、コストが雪だるま式に膨らんだのだ。

6.2 同時実行数の制限で守る

もっとも実用的な防御策は、設定でプロバイダーの同時実行数(concurrency)を制限することだ。以下のように、特定プロバイダーの同時実行数を縛れる。

{ "background_task": { "providerConcurrency": { "google": 1 } } }

この設定は、バックグラウンド作業における google プロバイダーの同時実行を 1 に制限する。暴走ループが起きても並列呼び出しが抑えられるので、被害を減らせる。

6.3 その他の安全習慣

同時実行制限のほかに、次を習慣化するとよい。

カテゴリとモデルの設定を監査(audit)する。どの作業がどのモデルへ行くかを明示的に把握しておく。
大量に呼び出されるサブエージェントには、より安価なモデルを優先して割り当てる。Librarian や Explore のように頻繁な役割が代表例だ。
プロバイダーの支出ダッシュボードを定期的に確認する。異常を早期に見つけることが最善の防御だ。

6.4 大きな作業の前の事前チェック

コスト事故はたいてい「何気なく回した大きな作業」で起きる。だから規模のある作業を ultrawork で発動する前に、3 つだけ目で確認する習慣をつけるとよい。第一に、設定ファイルで各カテゴリがどのモデルに割り当てられているかを見直す。第二に、同時実行数の制限がかかっているかを確認する。第三に、いま付いているプロバイダーが有料ティアなら、おおよその想定コストを頭に描いておく。この 30 秒のチェックが、先に見た一日で約438ドルのような事故を防ぐもっとも現実的な防壁になる。

7. いつ使い、いつバニラの OpenCode を使うか

最後に、もっとも実用的な問いだ。すべての作業に Oh My OpenCode を使うのが正解ではない。

Oh My OpenCode が輝くのは、大きく、複数ファイルにまたがり、複数フェーズに分かれる作業だ。リサーチ → 計画 → 実装と続く流れのように、並列サブエージェントの利点を活かせる作業がこれにあたる。このときチームは明白なパワー倍増器(power multiplier)になる。

逆に、単一のコンテキストウィンドウに収まる小さな作業や、予算型(budget)モデルを回す場合は、バニラの OpenCode のほうがよい。予算型モデルは 1 つのクリーンなプロンプトでより良い結果を出す。こうした作業にマルチエージェントを動員すると、先に見た起動オーバーヘッドを払うだけで、純粋な無駄になる。

まとめるとこうだ。Oh My OpenCode は適した作業には強力なパワー倍増器であり、合わない作業にはオーバーヘッドにすぎない。作業の規模とフェーズ数、そして並列化の利得を基準に選べばよい。

7.1 選択チェックリスト

迷ったら、次の問いに答えてみよう。「はい」が多いほど Oh My OpenCode 寄りだ。

この作業は 3 つ以上のファイルに触れるか。
リサーチ、計画、実装のように性質の異なるフェーズに分かれるか。
互いに独立していて並列に進められる下位タスクがあるか。
強いモデルを付ける予算の余裕があるか。

逆に「これはプロンプト 1 つで終わる」「予算型のローカルモデルしか使わない」「コンテキストがファイル 1〜2 個で十分だ」に当てはまるなら、バニラの OpenCode が合う。ツールを選ぶ基準は好みではなく、作業の形だ。

7.2 ひと目でわかる要約

本記事の核心を順にまとめ直すと、次のとおりだ。

まず OpenCode をインストールし、/init、/connect、Tab を手に馴染ませる。
プロジェクトのルートで bunx oh-my-opencode install によりチームを配線する。グローバルインストールと bunx omo は厳禁だ。
.opencode/oh-my-opencode.jsonc でエージェント別・カテゴリ別のモデルを調整する。
大きな作業は Tab または /start-work で計画を立ててから ultrawork で実行する。
同時実行数の制限をかけ、カテゴリとモデルの対応を監査し、支出ダッシュボードを定期的に見る。
小さな作業や予算型モデルにはバニラの OpenCode を使う。

この 6 行を守るだけで、Oh My OpenCode の利点の大半を取り込みつつ、リスクの大半を避けられる。

参考資料

Oh My OpenCode — https://ohmyopencode.com
GitHub — https://github.com/opensoft/oh-my-opencode
npm — https://www.npmjs.com/package/oh-my-opencode
OpenCode ドキュメント — https://opencode.ai/docs