OpenCode エージェント設定（Ollama）
SpecDojo CLI と OpenCode を組み合わせ、Ollama のローカルLLMでマルチエージェント実行を行うための設定・構成を定義する。
1. 設計方針
共通の責務分担、実行フロー、割り当て、失敗処理、worktree は エージェント共通設定 に従う。本書では OpenCode と Ollama 固有の設定だけを定義する。
本設計では OpenCode の provider を ollama-local に限定する。API key と外部クラウドLLMを必要としない一方、ホスト側 Ollama の稼働状態、モデルロード時間、メモリ容量が制約になる。
OpenCode は Qwen 3.8 と Gemma 4 を用途別 agent として使い分ける。ただし全 agent は同じ opencode provider を使い、max_concurrency: 1 により同時実行を1件へ制限して、異なるモデルの同時ロードを防ぐ。
コンテキスト長は 64k とする。fully-guided の磨き込みタスクは rulebook / recipe と depends_on 成果物、対象成果物をまとめて読み込むため、32k では作業セットが収まらず agent がツール呼び出しに至らないまま終了（result 未記入のまま exit 0）する事象が確認された。64k にして作業セットに余裕を持たせる。ただし KV キャッシュは 32k 比でおおよそ倍のメモリを消費するため、ホスト側 Ollama の空きメモリを前提として確認する。
- 非対話実行は
opencode run: TUI を起動せず、SpecDojo が生成した plan を標準入力で渡す。 - provider とモデル一覧は
opencode.json: 実際に利用可能なローカルモデルをプロジェクト設定として共有する。 - agent 定義は
.opencode/agents/*.md: 役割ごとの primary / subagent、permission、最小限の実行契約を定義する。モデルは member のmodelを起動時の--modelへ渡し、タスク固有の指示は edit / review plan を正本とする。 - 共通ルールは project root の
AGENTS.mdを基本とする:.opencode/AGENTS.mdを使う場合はopencode.jsonのinstructionsに明示する。 - permission を安全境界とする: edit agent は必要な編集操作を許可し、review agent は result ファイル以外の編集を禁止する。
- モデルと役割を分離する: Qwen は汎用・コード寄り、Gemma は文書作成・レビュー寄りに使うが、モデルは実体 member で選び、agent 定義は役割で選ぶ。通常 agent は
reasoningEffort: none、expert agent はreasoningEffort: highとし、thinking 用の派生タグは作らない。 - limit 情報は provider 非依存に共通化しない: OpenCode 自身の session limit を前提にせず、失敗要因は Ollama のロード待ち、メモリ不足、接続タイムアウトを主として扱う。
2. 責務分担
3層の共通責務は親設計に従う。OpenCode agent は、OpenCode 固有の permission、モデル、agent 定義を使用して plan を処理する。Ollama はモデルのロード、推論、OpenAI 互換 API の提供だけを担い、タスク管理やファイル編集は行わない。
3. 全体フロー
specdojo exec run
→ providers.opencode の command template から解決した opencode run --agent <role> --model <model> を起動
→ plan を標準入力で渡す
→ OpenCode agent が成果物または result を編集
→ OpenCode CLI の終了状態を共通フローへ返すedit / review の選択と終了後の状態遷移は親設計に従う。
4. ディレクトリ構成
repo-root/
├─ opencode.json # provider・モデル・プロジェクト設定
├─ AGENTS.md # OpenCodeを含む共通プロジェクトルール（推奨）
├─ .opencode/
│ ├─ AGENTS.md # instructions で明示して使うOpenCode固有ルール
│ └─ agents/
│ ├─ opencode-executor.md # pipeline executor（edit）
│ ├─ opencode-review-executor.md # pipeline executor（review）
│ ├─ opencode-reporter.md # pipeline reporter
│ └─ opencode-*.md # expert・grade・translator の役割定義OpenCode の設定は複数箇所からマージされる。主な優先順は remote config、global config、OPENCODE_CONFIG、project root の opencode.json、.opencode/、OPENCODE_CONFIG_CONTENT の順で、後の設定が競合キーを上書きする。
SpecDojo の project management 配下と worktree の共通構成は親設計を参照する。
5. opencode.json 設定
5.1. 現在の実設定
プロジェクト直下の opencode.json を provider、利用モデル、グローバルデフォルトモデルの正本とする。本書には設定値の意図だけを記載し、JSON 全文は重複させない。
実際のファイル: opencode.json
5.2. provider 設計
| 項目 | 設定値 | 意図 |
|---|---|---|
| provider | ollama-local | 外部 provider と区別するプロジェクト内識別子 |
| npm | @ai-sdk/openai-compatible | Ollama の OpenAI互換 API を利用 |
| baseURL | http://host.docker.internal:11434/v1 | devcontainer からホスト側 Ollama に接続 |
| apiKey | not-needed | SDKの必須項目を満たすダミー値 |
| model | ollama-local/qwen3.8:27b-mlx-work-64k | agent 未指定時のデフォルト |
ホスト外や Linux ホストで実行する場合は、host.docker.internal の名前解決と Ollama の listen address を別途確認する。
5.3. 使用モデル
opencode.json には Qwen 3.8 と Gemma 4 のモデルを定義し、.specdojo/agent-members.yaml の実体 member が各モデルを明示的に選ぶ。provider 単位の同時実行上限は1である。
| モデルID | 用途 | member 例 | 注意点 |
|---|---|---|---|
qwen3.8:27b-mlx-work-64k | 汎用作業・コード寄りタスク | qwen-* | expert は thinking を有効化する |
gemma4:31b-mlx-work-64k | 文書作成・編集・レビュー | gemma-* | expert は thinking を有効化する |
gemma4:e4b-mlx | 軽作業（短い要約・分類・整形） | - | 選択肢。軽量だが用途を限定する |
5.4. 追加設定方針
利用可能 provider をローカル Ollama に限定する場合は、opencode.json の enabled_providers に ollama-local を指定する。共有無効化、更新通知、追加 instruction ファイルの読込も同ファイルで管理する。
.opencode/AGENTS.md は自動読込対象ではないため、使用する場合は instructions に明示する。現在は project root の AGENTS.md を共通ルールの正本とする。
6. 共通指示の設計
OpenCode は project root から上位方向に AGENTS.md を探索する。project root に AGENTS.md がある場合は、それをプロジェクト共通ルールの正本とする。
OpenCode 固有ルールを .opencode/AGENTS.md に分離する場合は、opencode.json の instructions で明示的に読み込む。instructions で指定したファイルは AGENTS.md と結合される。
共通指示は次の内容に限定する。
- 言語、命名、Markdown frontmatter の規則
- 変更前に読むべき設計書と既存パターン
- 渡された plan だけを実行する SpecDojo ワークフロー
- result ファイルへの done criteria 記録
.env、secrets、破壊的操作、git pushの禁止
モデルは agent member、permission は agent 定義、SpecDojo exec の具体的な処理手順は edit / review plan に置く。AGENTS.md や agent 定義へタスク固有の手順を重複記載しない。
7. .opencode/agents/ エージェント定義
OpenCode の project agent は .opencode/agents/<name>.md に定義する。ファイル名が --agent で指定する agent 名になる。YAML frontmatter に agent 設定、本文にシステムプロンプトを記述する。
本文は、標準入力で渡された plan に従うこと、agent 自身で claim / complete / reopen / block を行わないこと、事実を捏造しないことだけを定める。対象成果物、owner 観点、result の記入方法、検証、正常・異常終了条件は plan に記載する。
7.1. frontmatter フィールド
| フィールド | 必須 | 説明 |
|---|---|---|
description | ○ | agent の用途と選択条件 |
mode | - | primary / subagent / all。SpecDojo 直接起動では primary |
model | - | pipeline の役割定義では指定しない。agent member の model を CLI の --model で渡す |
temperature | - | 出力のランダム性 |
permission | - | allow / ask / deny またはコマンド別パターン |
steps | - | agent の最大ステップ数 |
tools は非推奨のため、新規設定では permission を使用する。
member は全員 stage_role（executor / reporter）を持つ pipeline 構成とし、単体で edit/review を完結する legacy 構成は使わない。
7.2. 役割別 executor
pipeline executor（edit）は executor plan に従って成果物の編集と検証だけを行い、result は更新しない。docs/ja/projects/**/execution/exec/results/** は明示的に deny する。変更ファイルと検証結果は runner が evidence として収集できるよう、ツール出力と最終応答へ残す。
実際のファイル: .opencode/agents/opencode-executor.md、.opencode/agents/opencode-expert-executor.md、.opencode/agents/opencode-grade-executor.md。
主な安全境界は次のとおり。
.envとsecretsの読み取りを禁止する。- Edit ツールは文書成果物の
docs/**、実装成果物のsrc/**、自動テストのtests/**だけを許可し、docs/ja/projects/**/execution/exec/results/**は deny する。 git push、git reset --hard、git clean、rmを禁止する。- Web 検索と検索結果の参照を許可し、外部ディレクトリとsubagentの利用を禁止する。
- agent 自身による claim、complete、reopen、block を禁止する。
7.3. 役割別 review executor
pipeline executor（review）は review plan の各観点に従って成果物を多観点でレビューするが、成果物・result のいずれにも書き込まない（edit を全面 deny する）。レビュー結果はツール出力と最終応答へ残し、reporter が evidence として引き継ぐ。
実際のファイル: .opencode/agents/opencode-review-executor.md、.opencode/agents/opencode-expert-review-executor.md。
主な安全境界は次のとおり。
editを全面禁止する（成果物・result のいずれも変更しない）。- bash は Git の参照系コマンド、Markdown lint、
specdojo exec validateだけを許可する。 .envとsecretsの読み取りを禁止する。Web 検索と検索結果の参照を許可し、外部ディレクトリとsubagentの利用を禁止する。- 全基準を確認できない場合は pass または approve と判定しない。
7.4. reporter
pipeline reporter は標準入力で渡された plan、executor evidence、出力スキーマだけから構造化結果を返す。read / glob / grep / list / bash / edit / Web / subagent をすべて deny とし、成果物や result を直接変更できないようにする。応答には指定スキーマ外の説明やコードフェンスを加えない。edit/review どちらの executor の後段にも使う。
実際のファイル: .opencode/agents/opencode-reporter.md。
対話型オーケストレーターは pipeline role と別の .opencode/agents/specdojo-orchestrator.md を使うため、permission.edit と permission.bash を分離する。利用者の承認後に .specdojo/ や package.json なども変更できるよう、orchestrator の edit はリポジトリ全体で allow する。executor・review executor は読み取りを含む全 gh を deny するが、オーケストレーターは gh pr view・gh pr list・gh run list・gh run view・gh release view などの読み取りだけを allow する。git push、gh api、PR・release・repository などの書き込みサブコマンドは明示 deny し、未列挙の gh は deny 基点の許可リストにより拒否する。
7.5. エージェント一覧
| ファイル名 | --agent 指定名 | mode | モデル指定 | 用途 |
|---|---|---|---|---|
opencode-executor.md | opencode-executor | primary | CLI | 通常 executor（edit） |
opencode-expert-executor.md | opencode-expert-executor | primary | CLI | expert executor（edit） |
opencode-grade-executor.md | opencode-grade-executor | primary | CLI | grade 用 executor |
opencode-review-executor.md | opencode-review-executor | primary | CLI | 通常 executor（review） |
opencode-expert-review-executor.md | opencode-expert-review-executor | primary | CLI | expert executor（review） |
opencode-reporter.md | opencode-reporter | primary | CLI | reporter |
gemma26-translator.md | gemma26-translator | primary | frontmatter | grade finding の翻訳 |
qwen-orchestrator.md | qwen-orchestrator | primary | frontmatter | Qwen 対話型オーケストレーター |
gemma-orchestrator.md | gemma-orchestrator | primary | frontmatter | Gemma 対話型オーケストレーター |
8. エージェント割り当て設定
8.1. .specdojo/agent-members.yaml
起動コマンドは親設計の 起動コマンドの解決 に従い、.specdojo/exec-defaults.yaml の providers.opencode.command_template で定義する。{agent} は command_params から役割ファイルを選び、{model} は実体 member のモデルを渡すため、member の nickname と agent 定義のファイル名は一致させない。
providers:
opencode:
command_template: "opencode run --agent {agent} --model {model}"
command_params:
by_mode:
edit: { agent: opencode-executor }
review: { agent: opencode-review-executor }
report: { agent: opencode-reporter }
by_proficiency:
expert: { agent: opencode-expert-executor }
by_nickname:
qwen-expert-review-executor: { agent: opencode-expert-review-executor }
gemma-expert-review-executor: { agent: opencode-expert-review-executor }
ornith-expert-executor: { agent: opencode-grade-executor }
qwen36-expert-executor: { agent: opencode-grade-executor }同じ変数は by_nickname が最優先なので、edit の expert、review の expert、grade、translator のように mode と proficiency だけでは一意に決まらない役割を明示できる。実体・別名への移行時は、新しい実体 nickname に合わせて by_nickname のキーも更新する。
.specdojo/agent-members.yaml の member は選択属性だけを持ち、command を書かない。
members:
- nickname: opencode-executor
type: agent
provider: opencode
mode: edit
stage_role: executor
proficiency: normal
priority: 1
capabilities: [web_search]
scheduler_strategy: critical-first
- nickname: opencode-review-executor
type: agent
provider: opencode
mode: review
stage_role: executor
proficiency: normal
priority: 1
capabilities: [web_search]
scheduler_strategy: fifo
- nickname: opencode-reporter
type: agent
provider: opencode
stage_role: reporter
proficiency: normal
priority: 1
capabilities: []
scheduler_strategy: fifoOpenCode の executor（edit / review）は websearch と webfetch を利用できるため、capabilities: [web_search] とする。reporter は渡された evidence だけを扱うため capability を持たせない。normal taskでは、Web検索の要否にかかわらず priority: 1 によりOpenCodeを最初の候補とする。各 OpenCode member のモデルは実体 member の model で選ぶ。
8.2. sch-strategy-<track>.yaml
phase の共通契約は親設計に従う。外部Web検索が必要なphaseは capabilities: [web_search] とし、OpenCode agentも候補に含める。proficiency は役割を、実体 member の model はモデルを選ぶため、同じ役割定義を異なるモデルで使用できる。
8.3. .specdojo/exec-defaults.yaml
共通の retry / fallback / block 方針とグローバル既定 / provider 別上書きの2層構造は親設計に従う。Ollama では API rate limit より、モデルロード待ち、メモリ不足、接続タイムアウトが主な失敗要因になるため、OpenCode 固有の検出条件とポリシーを providers.opencode に置き、.specdojo/agent-members.yaml で provider: opencode の member に適用する。
providers:
opencode:
rate_limit_detection:
exit_codes: [] # ローカル実行では exit 1 は実失敗。stderr で判定する
stderr_patterns:
- "timeout"
- "connection refused"
- "out of memory"
- "model is loading"
rate_limit_policy:
on_non_critical:
action: skip
on_critical:
action: try_next
retry:
max_attempts: 3
initial_wait_seconds: 120 # モデル再ロード/メモリ解放に時間がかかるため長め
backoff_multiplier: 2
max_wait_seconds: 600
on_exhausted: block同一ホスト・単一モデルを共有するため、別 opencode member への try_next では復旧しない。復旧手段は wait+backoff の再試行であり、初回待機をモデル再ロード/メモリ解放にかかる時間に合わせて長めに取る。グローバルの rate limit / 429 パターンは Ollama の主たる失敗要因と一致しないため、上書きで OpenCode 固有のシグナルに置き換える。誤検出範囲を確認してから stderr pattern を追加・調整する。
ローカル Ollama を provider とする本構成では、アカウントベースの limit という考え方が他 provider と根本的に異なる。クラウド provider のような rate limit（秒〜分で回復）、session limit（5時間枠など）、quota（週次・月次の利用枠）は存在しない。失敗要因はローカル資源で、すべて reset horizon が秒〜分の transient_failure として wait+retry で扱う。共通モデルへの写像は親設計の limit 表に従う。
| 失敗要因 | 概要 | provider_signal.kind | 扱い |
|---|---|---|---|
| モデルロード待ち | 初回ロードやアンロード後の再ロード | timeout | transient_failure。wait+retry |
| メモリ不足 | KV キャッシュ等でホストの空きメモリが不足 | oom | transient_failure。wait+retry |
| 接続タイムアウト | ホスト側 Ollama への接続不可・応答遅延 | timeout | transient_failure。wait+retry |
| コンテキスト長超過 | 作業セットが設定コンテキスト長を超える | fatal_failure | run 内回復不可。block して設計を見直す |
OpenCode は provider 抽象化層であるため、quota 残量、session limit、reset 時刻のような利用枠情報を OpenCode 共通仕様として前提にしない。必要なら OpenCode 自体の event 出力とは別に、接続先 provider 固有の診断方法を採用する。
実際のファイル: .specdojo/exec-defaults.yaml
8.4. 実行コマンド
共通の実行コマンドは親設計を参照する。OpenCode agent を明示する場合は、モデル系統と役割を表す実体 nickname または互換用の別名を使用する。--agent に渡す役割ファイル名は command template が解決する。
9. 非対話実行とセッション
opencode run [message..] は非対話実行用コマンドである。--agent で primary agent、--model で一時的なモデル、--format json で raw JSON event 出力を指定できる。
opencode stats と session list --format json により、利用済み token や cost、session 一覧の観測はできる。ただしこれらは履歴統計であり、次のリクエストで利用できる残量や rate limit reset を保証する API ではない。
opencode run \
--agent opencode-executor \
--model ollama-local/qwen3.8:27b-mlx-work-64k \
--format json \
"SpecDojo plan を実行してください"--dangerously-skip-permissions は明示的に deny していない permission を自動承認するため、SpecDojo の通常運用では使用しない。必要な操作は agent 定義の permission で allow / deny を明確にする。
10. opencode serve 常駐モード
opencode run は実行ごとにローカル backend と MCP server を起動する。起動コストを削減する場合は opencode serve を常駐させ、opencode run --attach で接続する。
export OPENCODE_SERVER_PASSWORD='<secret>'
opencode serve --hostname 127.0.0.1 --port 4096
opencode run \
--attach http://127.0.0.1:4096 \
--username opencode \
--password "${OPENCODE_SERVER_PASSWORD}" \
--agent opencode-executor \
--model ollama-local/qwen3.8:27b-mlx-work-64k \
"SpecDojo plan を実行してください"常駐 server は loopback に限定し、共有環境では OPENCODE_SERVER_PASSWORD を設定する。モデル本体の保持・アンロードは Ollama 側の設定にも依存する。
11. worktree 分離セットアップ
worktree のライフサイクル、配置、ブランチ名、イベントファイル名は親設計に従う。OpenCode の edit agent を並列実行する場合は worktree を使用し、成果物を変更しない review agent では不要とする。
12. 現状差分と導入順序
| 項目 | 現状 | 対応 |
|---|---|---|
opencode.json | provider・3モデル・デフォルトモデルを定義済み | 必要に応じて instructions と provider 制限を追加 |
AGENTS.md | project root に共通ルールを定義済み | OpenCode 固有指示を追加する場合だけ別ファイルを参照 |
.opencode/agents/*.md | 役割ごとの agent を定義済み | opencode debug agent <name> で認識を確認 |
.specdojo/agent-members.yaml | 旧 nickname の1段名簿 | PJR-8MPY で実体・別名の2段構成へ移行 |
exec-defaults.yaml | {nickname} を --agent に渡す旧テンプレート | PJR-8MPY で {agent} と --model {model} へ切り替える |
導入確認は agent 認識確認、exec-defaults.yaml の command template 更新、単一タスク実行、並列実行の順で行う。