OpenCode CLI実践ガイド：ワークフロー、自動化、落とし穴

OpenCodeのコマンドラインインターフェースは、スクリプティング、CIパイプライン、無人エージェント実行のために構築されています。この記事では、日々の業務での使用方法に関する実践的なガイドを提供します。

CLIの背後には、モデル、ツール、権限、エージェント、スキル、コマンド、セッション、MCPサーバー、そしてクライアント/サーバーアーキテクチャからなるシステムが存在します。エージェントはプロジェクトファイルの読み書き、リポジトリの検索、シェルコマンドの実行、外部ツールの呼び出し、サブエージェントへの作業委譲を行うことができます。同じ環境は、TUIで対話的に使用することも、スクリプトから非対話的に使用することもできます。

小さなタスクであれば、インストールし、モデルを接続して、数分で質問を開始できます。本格的な作業では、体験の品質はモデルの選択、リポジトリ指示、権限境界、コンテキスト管理、そしてエージェントにどの程度積極的な動作を許可するかによって大きく左右されます。この記事では、コマンドラインから見た第2の段階、つまりどのユースケースが成果を上げるのか、どの自動化ワークフローが日常使用に耐えるのか、そしてAI搭載ターミナルの新規性が薄れた後にどのような問題が現れるのかに焦点を当てます。これは本サイトの AI Developer Tools セクションの一部です。

ここでの観察は、2026年8月時点のOpenCode 1.18.9および現在のドキュメントと照合して確認されています。OpenCodeは急速に变化するため、設定例を長期的なチーム環境にコピーする前に、簡単なドキュメント確認をお勧めします。まだOpenCodeをインストールしていない場合は、OpenCode クイックスタート で、インストール、検証、プロバイダー接続について説明しています。

OpenCodeの正体：チャットボックスではなく、エージェント環境

OpenCodeは、ターミナルを中心に設計されたオープンソースのAIコーディングエージェントです。OpenCodeが統合するものの簡略化されたビューは以下のようになります：

重要な部分は、モデルの意図とOpenCodeが実行できるアクションの間の権限レイヤーです。優れたモデルでも権限設定が悪いと危険になり得ます。弱いモデルでも権限設定が完璧であれば、単に遅くて煩わしいだけです。生産的なOpenCodeの利用には、両方を適正に設定することが必要です。

同じ環境は、対話的なTUIと非対話的なコマンドラインの両方のインターフェースに対応しています。これが、純粋なチャットインターフェースではできない方法で、OpenCodeをスクリプト可能にしているのです。同じターミナルエージェントのアイデアを意図的にミニマルな形で実現したもの（デフォルトのツール4つ、組み込みサンドボックスなし、その他はすべて拡張機能経由）をお探しなら、Pi Coding Agent レビュー が有用な対比となります。

セットアップ：インストール、接続、そしてプロバイダー独立性が重要な理由

OpenCodeは1行でインストールできます（公式インストールスクリプト、npm、またはHomebrew）。リポジトリディレクトリから opencode で起動します。OpenCode クイックスタート で、完全なインストールマトリクス（Arch、Windows、Docker）、検証、プロバイダー接続（/connect と /models）について説明しているため、この記事では繰り返しません。

OpenCode独自のモデルサービスを使用することも、サポートされている外部プロバイダーに接続することもできます。OpenCodeは現在、Models.devを使用してプロバイダーカタログの大部分を構築しており、広範囲の商用およびローカルモデル設定をサポートしています。

プロバイダーの独立性は、OpenCodeの最も有用なアーキテクチャ上の決定の一つです。コーディングワークフローを特定のモデルベンダーに永続的に結合する必要はありません。困難なアーキテクチャ作業には一つのモデル、安価な実装タスクには別のモデル、環境外に出すべきでないコードにはローカルモデルを使用できます。

この柔軟性は現実のものである一方で、管理すべき別の変数を生み出します。OpenCodeの動作が悪い場合、問題はハーネス、プロンプト、利用可能なコンテキスト、選択されたモデル、またはこれら4つの相互作用のいずれかかもしれません。

コードを依頼する前に、AGENTS.mdでリポジトリを初期化

新しいリポジトリで実行すべき最初のコマンドの一つは、以下のものです：

/init

OpenCodeはプロジェクトを分析し、AGENTS.md ファイルを作成します。このファイルはコミットしてください。

AGENTS.md は、リポジトリ固有の制約を、対話型でもスクリプト型でも、すべての会話に対して持続的なコンテキストとして機能させるための場所です。手動で繰り返し説明する必要がなくなります。有用なファイルは、関連性を保つために十分に短く、予測可能なミスを防ぐために十分に具体的である必要があります。例えば：

# Repository Instructions

## Architecture

- API handlers live under src/api.
- Business logic belongs under src/services.
- Database access belongs under src/repositories.
- Do not call database clients directly from HTTP handlers.

## Validation

After TypeScript changes run:

```bash
npm run typecheck
npm test
```

After frontend changes also run:

```bash
npm run lint
```

## Constraints

- Do not modify generated files.
- Do not change public API contracts without asking first.
- Do not create database migrations unless explicitly requested.
- Never run deployment commands.

これは、別のMCPサーバーをインストールすることほどエキサイティングではないかもしれませんが、通常はより多くの価値を提供します。コーディングエージェントが失敗するのは、どの制約が重要であるかを知らずに、驚くほど頻繁に起こります。短いリポジトリ契約は、最初のツール呼び出しの前に、その曖昧さをいくつか取り除きます。

opencode run でコマンドラインから作業する

対話的なインターフェースが最も多くの注目を集めていますが、OpenCodeの非対話モードは、有用なワークフローの範囲を大きく変えます：

opencode run "Explain the error handling strategy in this package"

シェルスクリプト、CIジョブ、Makefile、タスクランナー、またはローカル自動化から、毎回TUIに手動で入力せずにOpenCodeを使用できます。例えば、ワンショットコマンドとしてのdiffレビュー：

opencode run \
  "Review the current git diff for correctness and missing tests. Do not edit files."

または、コンテキストを直接パイプして実行します：

git diff --name-only HEAD~1 |
  opencode run "Inspect the changed files and identify risky behavior changes."

Makefileでは、同じ呼び出しがターゲットになります：

.PHONY: review
review:
	opencode run "Review the current git diff for correctness and missing tests. Do not edit files."

スクリプトによる実行にはプロンプトの前に人間がいないため、設定した権限ポリシーが、モデルとあなたの環境の間に立っている唯一のガードレールです。そのため、以下の権限セクションは、対話的な使用よりも自動化において重要になります。

ここでの興味深い方向性は、決定的なスクリプトをLLMで置き換えることではありません。従来のシェルロジックが困難になる場所にモデルの推論を挿入し、その周りを決定的な検証で囲むことです。

OpenCode CLIのベストユースケース

OpenCodeはほぼすべてのプログラミングタスクを試みることができますが、それはすべてのタスクを同じ方法で委譲すべきを意味しません。最も価値の高いワークフローには、通常3つの特性があります：望ましい結果がテスト可能であること、関連するリポジトリコンテキストが発見可能であること、誤った変更を検査またはロールバックするのが安価であること。以下の各プロンプトは、TUIで動作するか、opencode run の引数として動作します。

1. リポジトリの探索

OpenCodeは、grep、エディター検索、ファイルジャンプ、git log コマンドのシーケンスを必要とする質問に答えるのに優れています。例えば：

Explain how authentication works in this repository.

Trace a request from the HTTP middleware through token validation,
user loading, authorization, and the final handler.

Do not modify anything.

良いエージェントは、エントリーポイントを探索し、参照を追跡し、テストを調査し、単なるテキスト検索よりもアーキテクチャのウォークスルーに近いものを返します。エージェントがコードを書かないで価値を提供できるため、これは既存のコードベースにOpenCodeを導入する最も安全な方法の一つです。

2. 範囲の狭い明確な修正

範囲が狭く明確なバグは、理想的なコーディングエージェントタスクに近づきます。例えば：

The CLI exits with status 0 when config validation fails.

Find the code path responsible, add a regression test, implement
the smallest fix, and run the relevant tests.

Do not refactor unrelated code.

重要なフレーズは「バグを修正する」ことではありません。タスクを取り巻く制約です。テスト、コンパイラ、または観察可能なコマンドで成功が実証できる場合、OpenCodeはよりよく動作します。曖昧な要件は、モデルに実証可能な正しいコードではなく、妥当なコードを作成する余地を与えます。

3. 実装後のテスト生成

テストは、既存の実装がOpenCodeに具体的な推論の対象を与えるため、有用なエージェント作業です。生産的なプロンプトは以下のようになります：

Review src/parser.ts and its existing tests.

Identify important edge cases that are currently uncovered.
Add tests only. Do not modify the implementation.

Run the parser test suite when finished.

テスト生成と実装を分離することは重要です。同じエージェントが1つの制約なしのパスで機能とテストの両方を書くと、意図された動作ではなく、そのエージェント自身の解釈を検証するテストを誤って作成する可能性があります。

4. 機械的なリファクタリング

OpenCodeは、望ましい最終状態が明確な反復的な変換に非常に優れています。例：

• リポジトリ全体で非推奨のAPIを置き換える；
• 繰り返しコードを共有ヘルパーに変換する；
• 設定フィールドをリネームする；
• テストを1つのアサーションパターンから別のパターンに移行する；
• パッケージ移動後のインポートを更新する；
• 古いロギング抽象化を置き換える。

リポジトリのコンパイラとテストが、エージェントのフィードバックループになります。有用なパターンは以下の通りです：

Replace uses of LegacyResult<T> with Result<T, AppError> in
packages/api only.

Preserve runtime behavior.

Work in small batches. After each batch run the package typecheck.
At the end run the package test suite and show me the final git diff
summary.

これは、巨大な1ステップで全体の移行を依頼するよりも、通常は信頼性が高いです。

5. コードレビュー

レビューが別のエージェントロールとして扱われ、同じ編集コンテキストに送られる別のプロンプトとして扱われない場合、OpenCodeははるかに有用になります。ファイルを編集できないレビュー指向のエージェントを作成できます。その後、以下のようないSTRUCTIONSを与えます：

Review the current git diff.

Focus on:
- correctness;
- security;
- concurrency;
- missing tests;
- error handling;
- accidental API changes.

Do not summarize files that are unchanged.
Rank findings by severity.

読み取り専用のレビュアーは、変更が別のコーディングエージェントによって生成された場合でも有用です。この分離は価値があります。実装と批判は異なるタスクであり、数 thousand トークンを費やして一つのアプローチを擁護したばかりのエージェントは、新しいレビュアーよりもそのアプローチに対して懐疑的ではないことが多いからです。

PlanモードとBuildモードを異なるメンタルモードとして使用する

OpenCodeは、プライマリーエージェントとサブエージェントを提供し、計画と実装指向の動作を含む組み込みワークフローを持っています。正確なエージェント設定が時間とともに変わっても、概念的な分離は依然として有用です。

計画では、以下の質問に答えるべきです：

• どのファイルが重要か？
• どの既存のパターンに従うべきか？
• 何が壊れる可能性があるか？
• 変更を検証するにはどうするか？
• 要求された変更は実際にローカルか？

実装は、これらの質問に合理的な答えが出た後に行われるべきです。重要なタスクでは、私は以下のようなプロンプトシーケンスを好みます：

First investigate the request.

Do not edit files yet.

Return:
1. the relevant files;
2. the current behavior;
3. the proposed change;
4. risks;
5. the exact verification commands.

同じシーケンスは、ワンショットコマンドとして動作します：

opencode run "First investigate the request. Do not edit files yet. Return: the relevant files; the current behavior; the proposed change; risks; the exact verification commands."

そして、編集を許可する前に計画を検査します。これは、エージェントにすぐに「実装して」と指示するよりも遅く感じますが、エージェント型コーディングにおける高価な失敗は、通常、最初の編集の前にされた誤った仮定から来ています。

これは、仕様駆動開発 の背後にある同じ直感の、タスクごとに軽量なバージョンです：エージェントが編集を開始する前に計画について合意する。複数のファイル、セッション、または貢献者にまたがる作業では、書面での仕様は、単一の「まず調査する」プロンプトではできない方法で、そのオーバーヘッドを正当化します。GitHub Spec Kit vs Kiro vs Claude Code 比較 は、単一のプロンプトよりもさらに進む構造化されたSDDワークフローを扱っています。

サブエージェントは有用だが、委譲は無料ではない

OpenCodeは、自動的に、または明示的な言及を通じて、専門的なサブエージェントを呼び出すことができます。例えば：

@general find where retry behavior is implemented

セキュリティレビュー、依存関係分析、フロントエンドテスト、ドキュメントなどの作業用に、専用のサブエージェントを定義することもできます。同じパターンは他のハーネスでも動作します。Claude Code サブエージェントガイド は、Anthropic側での類似のデザインを扱っています。

これは強力です。サブエージェントの作業は、プライマリー会話の直接的な推論パスの外に残すことができるためです。プライマリーエージェントは、リポジトリ探索を委譲し、結果を消費することで、独自のコンテキストをすべての中間検索で埋める代わりに処理できます。しかし、サブエージェントは3つの目に見えにくいコストを生み出します：

1. トークンを消費します。 それぞれがリポジトリを再読み込みするエージェントのツリーは、驚くほど高価になり得ます — 私の Oh My Opencode 体験レポート は、そのオーバーヘッドが極限まで持たれた場合に何が起きるかを記録しています。
2. ポリシーの複雑さを生み出します。 権限は、親だけでなく、委譲されたエージェントについても考慮する必要があります。
3. 委譲は推論を隠す可能性があります。 プライマリーエージェントが「サブエージェントがXを見つけた」と言った場合、その結論が実際にどの程度信頼できるかを理解するには、子セッションを検査する必要があるかもしれません。

ほとんどのコーディングタスクにおいて、目的のある2つまたは3つのエージェントは、ターミナルの中に住む架空のソフトウェア企業よりも有用です。

タスクが本当に、固定された専門家の名簿に委譲する完全なオーケストレーターを必要とする場合（並列バックグラウンド実行、計画と調査フェーズ、ロールごとのモデルルーティング）— それは、これらのプリミティブの上に構築された別の製品であり、より大きなプロンプトではありません。Oh My Opencode クイックスタート は、そのハーネスを扱っています。

カスタムエージェントを権限境界として使用する

OpenCodeのエージェントは、別々のプロンプト、モデル、権限を持つことができます。これは、エージェントを単に異なる個性としてではなく、セキュリティとワークフローの境界として有用にします。例えば、プロジェクトローカルのレビューエージェントは、Markdownファイルとして定義できます：

---
description: Reviews code without modifying the repository
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff *": allow
    "git status *": allow
    "git log *": allow
  webfetch: deny
---

Review code for correctness, security, maintainability,
unexpected behavior changes, and missing tests.

Do not modify files.

これは、散文で「何も編集しないでください」と書くよりもずっと良いです。指示はモデルに影響を与えます。権限はツールを制約します。それらは同等の制御ではありません。

OpenCodeの権限を初日から設定する

OpenCodeの最も重要な実用的な特性の一つは、その通常のデフォルトが寛容であることです。デモ中は便利ですが、SSHキー、本番環境の認証情報、パッケージ公開トークン、Kubernetesコンテキスト、複数のクラウドアカウントへのアクセスを含むワークステーションでは、必ずしも望ましいものではありません。無人の opencode run ジョブでは、さらに賭け金が大きくなります：設定したポリシー以外に、実行を止めるものは何もありません。

OpenCodeの現在の権限モデルは、以下をサポートしています：

allow
ask
deny

ルールは、ファイルアクセス、編集、シェルコマンド、Web操作、サブエージェント、スキル、外部ディレクトリ、その他のツールカテゴリーに適用できます。保守的な開始点は以下のようになります：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "git diff *": "allow",
      "git log *": "allow",
      "git push *": "deny",
      "rm *": "deny"
    }
  }
}

正確なルールはあなたの環境に合わせるべきです。重要なのは、ポリシーを意図的にすることであり、エージェントがすでに驚くべき何かを実行した後にデフォルトを発見することではありません。

承認プロンプトとサンドボックスを混同しないこと

権限ルールは有用ですが、オペレーティングシステムによる分離と同じではありません。OpenCodeが許可されたシェルコマンドを実行する権限を持っている場合、そのプロセスはあなたの環境で利用可能なアクセスで実行されます。コーディングエージェントは、ファイル、ネットワークサービス、環境変数、認証情報、ソケット、パッケージマネージャー、その他の開発ツールと潜在的に相互作用できます。

機密リポジトリや無人実行では、より強力な分離を検討する価値があります：

Gitはロールバックです。権限はポリシーです。コンテナやVMは分離です。それらは3つの異なるレイヤーです。

反復的なプロンプトをカスタムコマンドに変換する

同じ指示を繰り返しタイプしている場合、それはチャット履歴ではなく、設定になるべきです。OpenCodeは、対話インターフェース用のプロジェクトおよびグローバルのカスタムスラッシュコマンドをサポートしています。例えば、以下を作成します：

.opencode/commands/review.md

内容は：

---
description: Review the current changes
agent: plan
---

Review the current git diff.

Look for:
- bugs;
- security issues;
- incomplete error handling;
- missing tests;
- accidental API changes.

Do not modify files.

そして使用します：

/review

これは、不釣り合いな価値を持つ小さな機能です。良いプロンプトが個人的なクリップボードのスニペットではなく、共有プロジェクトインフラストラクチャになることで、信頼できるコーディングエージェントワークフローが現れます。他の有用なプロジェクトコマンドには、以下が含まれます：

/test-changes
/review
/prepare-pr
/check-migration
/update-docs
/release-check

スキルを再利用可能なワークフローに使用する

OpenCodeは SKILL.md ファイルもサポートしています。スキルは、ワークフローが単一のプロンプトより多くのものが必要な場合に有用です。スキルは、詳細な操作ガイドとサポートファイルを包含しつつ、エージェントが実際に必要とするまで読み込まれないままにすることができます。有用な候補には、以下が含まれます：

• データベース移行手順；
• リリースワークフロー；
• インシデント調査；
• API互換性レビュー；
• パッケージ公開；
• インフラストラクチャ検証；
• 内部アーキテクチャ規約。

例えば：

.opencode/skills/database-migration/SKILL.md

スキルの説明は、OpenCodeに手順が適用されるタイミングを伝えることができ、本文はスキーマの検査、移行の作成、ロールバック動作の検証、統合テストの実行方法を説明します。もう一つのハーネスで同様の概念をすでに使用している場合、開発者向け Claude Skills ガイド が同じデザイン決定をマッピングします。

利点はコンテキスト規律です。すべての組織ルールを AGENTS.md に投入すると、最終的に高価で、モデルがますます無視しやすくなる巨大なシステムプロンプトが作成されます。スキルは、専門的な指示を必要とする場合のみコンテキストに入ることを可能にします。

MCP：ツールカタログが問題になるまで有用

OpenCodeは、ローカルおよびリモートのMCPサーバーをサポートしています。これにより、問題トラッカー、ドキュメントシステム、ブラウザ、オブザバビリティプラットフォーム、データベース、API、その他のツールをコーディングエージェントに公開できます。典型的な設定は、ドキュメントサーバーを提供するかもしれません：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

MCPは、過剰使用されやすい機能の一つです。エージェントが理解しなければならない各ツールは、注意と頻繁にはコンテキストトークンを消費します。15つのMCPサーバーを持つ設定は、設定スクリーンショットでは強力に見えますが、実際のモデル動作をより遅く、より高価で、予測不可能にすることになります。

私のルールは単純です：ツールが通常の1週間の作業で有用でない場合、おそらくグローバルに有効にすべきではありません。統合が存在するからではなく、ワークフローが必要とするからツールを読み込むのです。

OpenCodeのローカルモデル：現実的な選択肢だが、魔法の解決策ではない

OpenCodeの最も強力なユースケースの一つは、ローカルまたはセルフホストされたOpenAI互換モデルエンドポイントで動作できる能力です。これは、以下の場合に魅力的です：

• ソースコードがローカルに留まる必要がある；
• APIコストが重要な；
• GPUインフラストラクチャをすでに運用している；
• オープンモデルの実験をしたい；
• インターネット接続が信頼できない；
• モデルルーティングがプラットフォームの一部である。

カスタムプロバイダーは、OpenCodeをLM Studio、llama.cpp 経由の llama-server、vLLM、Ollama互換インフラストラクチャ、または他のOpenAI互換サーバーなどのローカルエンドポイントに向けることができます。

ここで、期待値が重要になります。優れたコーディングハーネスは、ツール使用、長期的な計画、コード推論、または指示保持が弱いモデルを完全に補償することはできません。ローカルOpenCode設定に関するコミュニティの議論は、同じ観察に繰り返し収束します：ローカルモデルは範囲の限定されたタスクに非常に優れていますが、小さなものはより多くの監督を必要とする場合が多いです。特定のモデルがOpenCode内で実際にどのように動作するかの実測数値については、私の OpenCode向けハンズオンLLM比較 を参照してください。

実用的な解決策は、タスクの複雑さによるモデルルーティングです。安価またはローカルなモデルを以下に使用します：

• リポジトリ検索；
• ドキュメント；
• 単純なテスト；
• 反復的な編集；
• フォーマット変更；
• 単純なバグ修正。

強力なモデルを以下に使用します：

• アーキテクチャ変更；
• 曖昧なバグ；
• パッケージ横断のリファクタリング；
• 並行性；
• セキュリティに敏感なコード；
• 困難な移行。

プロバイダーの独立性は、この戦略を可能にします。しかし、モデル品質が無関係であるとはしません。

OpenCodeでの実用的な日常ワークフロー

私が好むワークフローは、意図的に保守的です。TUIでも opencode run 経由でも同じように動作します。ステップがプロンプトの場合、コマンドラインのバリアントが並んで表示されます。

ステップ1：クリーンなGit状態から始める

git status

既存の変更をコミットするか、意図的にすでに何が変更されているかを記録します。AIコーディングエージェントが汚れたワーキングツリー内で動作すると、人間の変更とエージェントの変更が混ざり合うため、レビューがはるかに困難になります。

ステップ2：まず調査を依頼する

Investigate issue #482.

Do not modify files.

Explain:
- the current behavior;
- likely root cause;
- relevant files;
- existing tests;
- proposed fix;
- verification commands.

同じプロンプトをワンショットコマンドとして：

opencode run "Investigate issue #482. Do not modify files. Explain the current behavior, likely root cause, relevant files, existing tests, proposed fix, and verification commands."

調査が間違っている場合、修正するのは安価です。

ステップ3：実装を絞り込む

Implement the proposed fix only.

Do not refactor unrelated code.
Add the regression test first.
Run the smallest relevant test suite after the change.

または非対話的に：

opencode run "Implement the proposed fix only. Do not refactor unrelated code. Add the regression test first. Run the smallest relevant test suite after the change."

エージェントには、より小さな決定空間があります。

ステップ4：diffを自分で検査する

git diff --stat
git diff

このステップを完全に別のモデルにアウトソーシングしないでください。コードが妥当に見えるかどうかだけでなく、エージェントが必要としないファイルを触っていないかを確認しています。

ステップ5：決定的な検証を実行する

npm run typecheck
npm test
npm run lint

実際のプロジェクトコマンドを使用してください。「OpenCodeはテストがパスすると述べている」は、ターミナルがテストプロセスの成功を表示することよりも強い証拠ではありません。

ステップ6：独立したレビューを実行する

読み取り専用のエージェントに依頼します：

Review the uncommitted diff as if it were a pull request written
by another engineer.

Try to find reasons this implementation is wrong.

Do not edit files.

コマンドラインのバリアント：

opencode run "Review the uncommitted diff as if it were a pull request written by another engineer. Try to find reasons this implementation is wrong. Do not edit files."

「これが間違っている理由を見つけようとする」というフレーズは意図的なものです。モデルは、妥当な仕事を礼儀正しく確認するのが非常に得意です。レビュープロンプトは、拍手ではなく、反証を奨励すべきです。

ステップ7：diffが意味をなすまでコミットしない

git add -p
git commit

エージェントが生成した変更の後、まだインタラクティブなステージングを好みます。これは、リポジトリ履歴の一部となるすべてのチャンクに対して、最終的な人間によるパスを強制します。

OpenCodeが苛立たしくなる場所：一般的な落とし穴

興味深い制限は、通常「AIが構文エラーを作った」ことではありません。コンパイラはそれらをキャッチするのが得意です。困難な問題は、自律性、コンテキスト、隠れた仮定、設定から来ています。

課題1：モデル品質が体験を支配する

同じOpenCodeワークフローは、一つのモデルでは非常に良く感じられ、別のモデルではほぼ使用不能に感じられることがあります。これは、ユーザーがモデルの動作をエージェントハーネスに帰因することが多いため、製品レビューを困難にします。

OpenCodeが繰り返し：

• 指示を無視する；
• 多くのコードを書き換える；
• ツールを誤って呼び出す；
• 同じ失敗したアクションでループする；
• 制約の追跡を失う；
• APIを捏造する；

場合、OpenCode設定全体を再設計する前に、別のモデルを試してください。ターミナルが突然賢くなったわけではありません。モデルが賢くなったのです。

課題2：長いセッションでは悪いコンテキストが蓄積する

コーディングエージェントのセッションは、誤った仮定が蓄積するにつれて信頼性が低下します。「このサービスはステートレスである」という初期のミスは、関連するファイルが変わった後でも、後の数十の決定に影響を与える可能性があります。

OpenCodeはコンテキスト制限を管理するためのコンパクト化をサポートしていますが、圧縮は独自のトレードオフを作成します。サマリーは必然的に、どの詳細が生存するかを決定します。主要なタスクの移行では、英雄的な80,000トークンの会話を続けるよりも、新しいセッションを開始する方が通常はクリーンです。スクリプト実行では、答えはさらに単純です：新しい opencode run は毎回クリーンなコンテキストで開始するため、長期的な状態は会話ではなく、AGENTS.md のようなファイルに属します。

コンテキストは無料のメモリではありません。それはワーキングステートであり、ワーキングステートは古くなります。

課題3：権限は欺瞞的に複雑になり得る

単純なルールは容易です：

read -> allow
edit -> ask
git push -> deny

複雑なエージェント階層は困難です。プライマリーエージェントがサブエージェント、カスタムツール、MCPサーバー、シェルコマンドを呼び出せるようになった時点で、1つの設定行ではなく、ワークフロー全体の有効な能力について推論する必要があります。

また、サブエージェントの権限動作と権限継承に関する、実際のコミュニティおよびGitHubの議論もありました。教訓は、一つのバグよりも広範です：セキュリティの仮定を実際の使い捨てリポジトリでテストしてください — 例えば、git init /tmp/opencode-perm-test を実行し、そこでエージェントに拒否したコマンドを実行させようとしてください。アクションが絶対に発生してはならない場合、散文の指示だけに頼らないでください。

課題4：OpenCodeは急速に変化する

OpenCodeは驚異的なペースでリリースしてきました。これは機能には良く、ドキュメントの長寿命にはあまり快くありません。2026年に特に落としやすい罠は、異なるOpenCode世代の設定例を見つけることです。現在のドキュメントには、確立された1.x構文とは異なる設定スキーマを持つ別個のV2資料も含まれています。例えば、権限の概念はV2ドキュメントでは異なるフィールド名で現れるかもしれません。

以下からの例を安易に組み合わせないでください：

/docs/

と：

/v2/docs/

実際に使用しているランタイムを確認せずに。ブログ記事からコピーした設定をトラブルシューティングする場合は、OpenCodeが壊れていると仮定する前に、その公開日を確認してください。

課題5：TUIは規模を隠すことがある

会話インターフェースは、10ファイルの変更を、10ファイルの変更よりも小さく感じさせます。エージェントは以下のように報告するかもしれません：

Implemented the new validation and updated the relevant tests.

その文は、3行でも600行でも表す可能性があります。独立したシェルツールを近くに保ってください：

git status --short
git diff --stat
git diff --name-only
git diff

コーディングエージェントは、コーディングエージェントを観察するための唯一のインターフェースであるべきではありません。

課題6：MCPはコンテキスト効率を破壊し得る

より多くの統合が自動的により良いコーディングエージェントを生むわけではありません。大きなMCPサーバーは、多くのツールスキーマを公開し、それぞれがモデルコンテキストを消費し、ツール選択の複雑さを増加させます。OpenCodeがMCPエコシステムの半分をインストールした後、奇妙に決断できないように感じられる場合、大部分を無効にして比較してください。より小さなツールサーフェスは、通常、より良いエージェント動作を生み出します。

課題7：ローカルプライバシーは全パスの検証を必要とする

ローカルモデルの実行は、ツールチェーンのすべての部分がローカルであることを自動的に保証するものではありません。2026年初頭のコミュニティの議論は、OpenCodeの補助モデル動作とWebインターフェースアーキテクチャ周りのプライバシーに関する質問を引き起こしました。それらの主張の一部は古いバージョンを指し、一部は論争があり、一部のコードパスはその後変更されました。

持続的な教訓は「OpenCodeがすべてをどこかに送る」ことではありません。持続的な教訓は：ローカルのみ動作がハードな要件である場合、それを検証することです。ネットワーク検査を使用し、現在の設定を読み、どのインターフェースを使用しているかを理解し、不要なリモート統合を無効にし、デプロイしようとする正確なバージョンをテストしてください。セキュリティ要件は、推測ではなく、検証されるべきです。

OpenCode vs Claude Code と Codex CLI

OpenCodeの最も強力な差別化要因は、必ずしもコーディング品質ではありません。基礎となるモデルが依然としてコーディング品質に大きく貢献しています。その差別化要因は、ハーネスに対する制御です。

OpenCodeが魅力的なのは、あなたが以下を重視する場合です：

• オープンソースの実装；
• プロバイダーの柔軟性；
• ターミナルファーストのワークフロー；
• 設定可能なエージェント；
• 細粒度の権限；
• ローカルモデルサポート；
• MCP；
• 再利用可能なコマンドとスキル；
• クライアント/サーバーアーキテクチャ。

Claude Code が魅力的なのは、強力な第一者モデル動作と、ますます洗練された組み込みエージェントワークフローを持つ、緊密に統合されたAnthropic体験を望む場合です。Codex CLIが魅力的なのは、あなたの好むモデルとワークフローがすでにOpenAIのコーディングスタックを中心にしている場合です。

私は、機能を数えることでそれらを選ぶことはしません。あなたがどのレイヤーを所有したいかに基づいて選んでください。ほとんどのワークフローの決定をベンダーに任せたい場合、第一者コーディングエージェントは魅力的かもしれません。プロバイダーとエージェント設定の実験をする一方で、ハーネスが交換可能に残ることを望む場合、OpenCodeはより強力な論拠を提示します。

Reddit と Hacker News が OpenCode について正しく捉えていること

OpenCode周りのコミュニティの議論は、異様に二極化しています。一部の開発者は、特にCodexモデル、ローカルモデル、またはカスタムエージェント設定と組み合わせられた場合、それを彼らの最爱のコーディングハーネスと説明します。他の人は、リソース使用量、権限動作、プライバシーに関する質問、プロバイダー認証の変更、または一見単純なターミナルアプリケーションがインフラストラクチャになるにつれて現れる複雑さに焦点を当てます。両方の視点も合理的です。

OpenCodeが困難なのは、コマンドラインが困難だからではありません。自律的なコーディング環境が、開発者が以前は明示的に答える必要がなかった質問を露出させるからです：

• どのモデルがこの決定を行うべきか？
• どのファイルを読み取ってよいか？
• どのコマンドを実行してよいか？
• プロセスはどの認証情報を見ることができるか？
• どのタスクがサブエージェントになるべきか？
• どの程度のコンテキストが生存すべきか？
• どのツールが永続的なコンテキストに値するか？
• どの結果を人間が検証すべきか？

洗練されたクローズド製品は、それらの決定の多くをあなたのために下すことができます。OpenCodeは、それらの多くをあなたのものとして残します。それがまさに、高度なユーザーがそれを好む理由です。

私が推奨する開始設定

私は、すぐに複雑なセットアップを構築することに抵抗します。以下から始めてください：

1. 1つの強力なデフォルトモデル；
2. 1つの AGENTS.md；
3. 保守的なシェルと編集権限；
4. 読み取り専用のレビューエージェント；
5. 2つまたは3つのカスタムコマンド；
6. 実際の必要が現れるまでMCPサーバーなし。

シンプルな環境はデバッグが容易です。ワークフローが反復的になったら、それをコマンド、スキル、またはエージェントに昇格させます。機能が危険になったら、権限で制限します。コンテキストが膨らんだら、より大きなコンテキストウィンドウを買うだけではく、ワークフローを分割します。この漸進的なアプローチは、スクリーンショットでは印象的ではありませんが、維持するはるかに快適です。

OpenCodeを使うべき人

OpenCodeは、すでにターミナルの中で生活し、コーディングエージェントが別のプログラム可能な開発ツールのように動作することを望む開発者に特に適しています。以下の場合、強く検討する価値があります：

• 複数のLLMプロバイダー間で作業している；
• ローカルモデルサポートを望んでいる；
• 1つのAIベンダーにロックインされるのが嫌いだ；
• プロジェクト固有のエージェントを必要としている；
• シェルスクリプトから開発タスクを自動化している；
• コーディングハーネスを検査または変更したい；
• Gitと通常のCLIツールをすでに理解している。

主にIDE内の目に見えないAIレイヤーを望む場合、それは魅力的ではありません。OpenCodeは、従来のオートコンプリートツールよりも多くの操作的判断を期待します。diffのレビュー、シェルコマンドの理解、Gitブランチの管理がすでに不快に感じられる場合、自律的なプロセスにそれらのツールへのアクセスを与えることは、基礎的な複雑さを消去しません。

最終的な判定

OpenCodeは、AIコーディングツールが単なるチャットインターフェースではなく、開発者インフラストラクチャになることの、より説得力のある例の一つです。その最高の機能は華やかではありません。プロバイダーの独立性、明示的な権限、再利用可能なエージェント、非対話実行、リポジトリ指示、コマンド、スキル、合成可能なツールは、エージェントを実際のエンジニアリングワークフローに合わせて形成することを可能にします。

弱点はその強さの鏡像です。OpenCodeは、規律のあるコーディング環境を作成するのに十分な制御を与えますが、20のMCPサーバーと明確な検証境界のない、複雑で高価で適切に分離されていないエージェントの群れを作成するのに十分な制御も与えます。

私は、OpenCodeを最大限の自律性のために最適化しません。短いフィードバックループのために最適化します。範囲の限定された問題、問題を理解するのに十分なコンテキスト、必要なアクションのみを実行する権限、そして結果が動作するかを証明できる決定的なコマンドを与えてください。それは、あなたが眠っている間にエージェントにアプリケーション全体を構築させるよう求めるよりも魔法的ではありません。しかし、OpenCodeが本当に有用になる方法にはるかに近いものです。

参考文献

• OpenCode documentation: https://opencode.ai/docs/
• OpenCode changelog: https://opencode.ai/changelog
• OpenCode GitHub repository: https://github.com/anomalyco/opencode
• Models.dev provider catalog: https://models.dev