OpenCode CLIの実践：ワークフロー、自動化、注意点

OpenCodeのコマンドラインインターフェース（CLI）は、スクリプティング、CIパイプライン、および無人のエージェント実行のために設計されています。本記事では、日常業務での実用的な使い方を指南します。

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

小規模なタスクであれば、数分でインストール、モデル接続、質問を開始することができます。しかし、本格的な作業では、体験の質はモデルの選択、リポジトリの指示、権限の境界、コンテキスト管理、そしてエージェントの操作をどの程度許可するかによって大きく左右されます。本記事では、その第二段階、すなわちコマンドラインからのアプローチに焦点を当てます。どのユースケースが成果を上げ、どのオートメーションワークフローが日常使用に耐えうるか、そしてAI駆動のターミナルの新鮮さが薄れた後にどのような問題が顕在化するかについて扱います。本記事は、本サイトのAI開発ツールセクションの一部です。

ここに述べる観察結果は、OpenCode 1.18.9および2026年8月時点の現在のドキュメントに基づいて検証されました。OpenCodeは急速に変更されるため、長期的なチームセットアップに構成例を適用する前に、すばやくドキュメントを確認することをお勧めします。まだOpenCodeをインストールしていない方は、OpenCode クイックスタートが、インストール、検証、プロバイダー接続をカバーしています。

OpenCodeの実体とは：エージェント環境であり、チャットボックスではない

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

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

同じ環境は、対話型TUIと非対話コマンドラインの両方の表層に提供されます。これが、純粋なチャットインターフェースでは実現できないOpenCodeのスクリプタビリティ（スクリプトによる制御可能性）の源です。同じターミナルエージェントのアイデアの意図的にミニマルなアプローチ（デフォルトのツール4つ、組み込みサンドボックスなし、その他は拡張機能で実現）を探している方は、Pi Coding Agent レビューが、有益な対比材料になります。

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

OpenCodeは1行でインストールできます（公式インストールスクリプト、npm、またはHomebrew）。リポジトリディレクトリからopencodeを実行して開始します。OpenCode クイックスタートには、フルインストールマトリクス（Arch、Windows、Docker）、検証、およびプロバイダー接続（/connectと/models）について記載されているため、本記事では繰り返しません。

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

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

その柔軟性は本物ですが、管理すべき変数がもう一つ増えます。OpenCodeの動作が悪い場合、問題の原因はハーネス、プロンプト、利用可能なコンテキスト、選択されたモデル、またはそれらの相互作用にあるかもしれません。

コードを依頼する前に、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"

OpenCodeは、TUIに手動で入力するのではなく、シェルスクリプト、CIジョブ、Makefile、タスクランナー、またはローカルオートメーションから使用できます。例えば、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で決定論的なスクリプトを置き換えることではありません。それは、従来のシェルロジックがawkward（ぎこちない）になる箇所にモデルの推論を挿入し、周囲には決定論的な検証を保持することです。

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の置換；
• 反復コードの共有ヘルパーへの変換；
• 設定フィールドの名前変更；
• テストのアサーションパターンからの移行；
• パッケージ移動後のインポート更新；
• 非推奨ロギング抽象化の置換。

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

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ははるかに有用になります。ファイル編集ができないレビュー指向のエージェントを作成できます。次に、以下のようないしゅつを与えます：

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.

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

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.

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

1日目に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が許可されたシェルコマンドを実行する権限を持っている場合、そのプロセスはあなたの環境に利用可能なアクセスで実行されます。コーディングエージェントは、ファイル、ネットワークサービス、環境変数、認証情報、ソケット、パッケージマネージャー、その他の開発ツールと潜在的にやり取りできます。OpenHands CLI クイックスタート は、サンドボックス化された対極です：Dockerワークスペース、常に承認するヘッドレスモード、そしてOpenHandsプロジェクトが現在ドキュメント化しているAgent Canvas引き継ぎです。

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

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 スキル ガイド が同じ設計決定をマッピングします。

利点はコンテキスト規律です。すべての組織ルールを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インフラストラクチャを運用している；
• オープンモデルの実験を行いたい；
• インターネット接続が不安定である；
• モデルルーティングがプラットフォームの一部である。

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

ここでは期待値が重要です。良いコーディングハーネスは、ツール使用、長期計画、コード推論、または指示保持が弱いモデルを完全に補償することはできません。ローカル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 vs Codex CLI

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

OpenCodeは、以下を重視する場合に魅力があります：

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

Claude Code は、Anthropic体験の緊密な統合と、強いファーストパーティモデル動作、ますます磨かれた組み込みエージェントワークフローを望む場合に魅力があります。Codex CLIは、好むモデルとワークフローがすでにOpenAIのコーディングスタックに中心を置いている場合に魅力があります。

それらの中で機能数を数えることで選ぶべきではありません。どのレイヤーを所有したいかに基づいて選択してください。ベンダーにほとんどのワークフロー決定をさせたい場合、ファーストパーティコーディングエージェントが魅力的になり得ます。プロバイダーやエージェント構成を実験しながら、ハーネスが交換可能に留まることを望む場合、OpenCodeはより強力な主張を行います。

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

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

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

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

磨かれたクローズドプロダクトは、それらの決定の多くをあなたの代わりに行えます。OpenCodeは、それらの多くをあなたのものにします。それがまさに、上級ユーザーがそれを好む理由です。

私が推薦する開始構成

精巧なセットアップをすぐに構築することに抵抗すべきです。次から始めます：

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

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

誰がOpenCodeを使うべきか

OpenCodeは、すでにターミナルで生活し、コーディングエージェントを別のプログラマブルな開発ツールのように動作させたい開発者にとって、特に良い適性があります。以下の場合には、強く考慮するべきです：

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

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

最終判断

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

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

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

参考文献

• OpenCodeドキュメント: https://opencode.ai/docs/
• OpenCode変更履歴: https://opencode.ai/changelog
• OpenCode GitHubリポジトリ: https://github.com/anomalyco/opencode
• Models.devプロバイダーカタログ: https://models.dev