OpenCode + Ollama：あなたの環境にコードエージェントを提供します。 terminal

#OllamaとOpenCode：それぞれの役割

OpenCodeはターミナルで動作するオープンソースのコードエージェントで、プロジェクトを読み、ファイルを変更し、コマンドを実行します。OpenCode自体はモデルを提供しません。一方、Ollamaはモデルをマシンにダウンロードして実行し、ローカルAPIを公開します。両者は補完関係にあり、OpenCodeがOllamaにリクエストを送り、Ollamaがローカルモデルで応答します。したがって「OpenCodeかOllamaか」という問題ではなく、両方を使います。

ローカルで動かす利点は、思想的なものではありません。コーディングエージェントは、ディレクトリ構成、設定ファイル、業務ロジックなど、すべてを見ることになります。ローカルモデルを使えば、このコンテキストはマシン内にとどまり、トークン単位の課金もネットワークへの依存もありません。その代わり、能力には限界があります。数百億パラメータ規模のローカルモデルは、ホストされている最大規模のモデルには及ばず、長いタスクの実行も遅くなります。

#前提条件：マシン、ターミナル、Ollama

Ollama が稼働中

設定を始める前に、モデルが応答することを確認してください。まず ollama list を実行し、次にコード用モデルを指定して ollama run を実行します。これが動作すれば、残るのは OpenCode の設定だけです。

現代的なターミナル

OpenCodeのドキュメントでは、WezTerm、Alacritty、Ghostty、Kittyが紹介されています。Windowsでは、より高いパフォーマンスと完全な互換性を得るために、WSLの使用を推奨しています。

コンテキスト用のメモリ

エージェントはファイルを読み取り、履歴を蓄積します。Ollamaによると、OpenCodeには少なくとも64,000トークンのコンテキスト長が必要で、その分、モデルの重みを保持するためのメモリに加えて、さらにメモリが必要になります。

Gitリポジトリ

必須ではありませんが推奨されます：git diff または git restore により、失敗したセッションを適切に取り消すことができます。

#OpenCodeをインストールしてOllamaに接続する

OpenCodeは、スクリプトまたはパッケージマネージャーでインストールできます。ドキュメントには、公式スクリプト、npm、bun、pnpm、yarn、Homebrew、Arch、Chocolatey、Scoop、Mise、Dockerが挙げられています。macOSとLinuxでHomebrewを使う場合は、更新頻度の低い標準のformulaよりも、公式tapを使うことが推奨されています。

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

npm install -g opencode-ai

brew install anomalyco/tap/opencode

choco install opencode
scoop install opencode

#手早い方法：ollama launch opencode

Ollama は、選択したモデルで OpenCode を起動できます。ollama launch opencode コマンドは、~/.config/opencode/opencode.json ファイルを上書きせずに、コマンドラインで設定を渡して OpenCode を起動します。既存の OpenCode 設定は引き続き適用されます。--config オプションを使用すると、Ollama は対話セッションを開くことなく OpenCode を設定できます。opencode.json のみで定義されたモデルは、ollama launch のセレクタに表示されません。

ollama launch opencode

#手動での設定：Ollamaをプロバイダーとして登録

自分で設定を管理したい場合は、グローバルのopencode.json（~/.config/opencode/opencode.json）またはプロジェクトのルートにあるopencode.jsonにプロバイダーを追加してください。OllamaのOpenAI互換エンドポイントは http://localhost:11434/v1 です。modelsの下にある各キーは、ollama listで表示されるモデル名と完全に一致している必要があります。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": {
        "qwen3-coder:30b": { "name": "Qwen3-Coder 30B" },
        "devstral-small-2:24b": { "name": "Devstral Small 2" }
      }
    }
  }
}

OpenCodeを再起動してください。モデル選択欄に、Ollamaプロバイダーの設定で定義したモデルが表示されます。

#最大の落とし穴：コンテキスト長

初めて試す際に失敗することが多いのは、コンテキストが短すぎるためです。エージェントがタスクの冒頭を忘れ、ファイルの読み取りを繰り返したり、一貫性のない変更を行ったりします。Ollamaのコンテキスト長は一律ではありません。ドキュメントでは、VRAMが24GB未満なら4kトークン、24〜48GBなら32kトークン、48GB以上なら256kトークンとされています。また、エージェントやコーディングツールなど、大きなコンテキストを必要とするタスクでは、少なくとも64,000トークンに設定する必要があると明記されています。

値を変更する方法は2つあります。Ollamaアプリでは、設定のスライダーでコンテキスト長を設定します。コマンドラインでは、サーバー起動時に変数OLLAMA_CONTEXT_LENGTHが適用されます。コンテキストを長くすると、メモリ消費量も増えます。モデルの処理が一部でもCPU側に回ると非常に遅くなるため、ollama psでモデル全体がGPUに収まっていることを確認してください。

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

#コードエージェント用のローカルモデルはどれですか？

エージェントは、読み取り、書き込み、実行のためのツールを確実に呼び出せる必要があります。Ollamaのライブラリで「tools」対応と表示されているモデルを選んでください。以下は、ollama.comでタグとサイズを確認した候補モデルです。

これらはファイルのサイズです。コンテキストキャッシュの分も加える必要があり、そのサイズは要求する64,000トークンに応じて大きくなります。15 GBのモデル（Devstral Small 2）は、メモリ24 GBのマシンで最も導入しやすい選択肢です。19 GBのモデル（Qwen3-Coder 30B）には、より多くの余裕が必要です。より低スペックのマシンでは、小さなモデルでも単純で対象を絞ったタスクを実行できますが、複数のファイルにまたがるリファクタリングでは、より早く対応しきれなくなります。

#実際のワークフロー：ルートとそのテストを追加する

具体例：小規模なExpress APIにGET /healthルートを追加し、そのルートをテストで検証する。OpenCodeのドキュメントでは、まず/initを実行することを推奨しています。/initはプロジェクトを分析し、ルートディレクトリにAGENTS.mdファイルを作成します。このファイルをgitにコミットすることで、エージェントがプロジェクトの構造を理解しやすくなります。

1. 01
   プロジェクトを開く

   リポジトリのルートに移動してopencodeを起動し、初回は続けて/initを実行してください。画面下部で、選択されているモデルがOllamaのモデルであることを確認してください。
2. 02
   Plan モードに切り替える

   TabキーでPlanモードとBuildモードを切り替えられます。Planモードでは変更操作が無効になり、エージェントはどのように進めるかを提案するだけです。何かを変更する前に、まずエージェントに計画を提示してもらってください。
3. 03
   タスクを説明する

   ジュニア開発者に説明するように、背景情報を伝えてください：「src/server.jsにstatus okを返すGET /healthルートを追加し、その後test/health.test.jsにテストを追加してください。」@を使うと、プロジェクト内のファイルを検索できます。
4. 04
   Buildモードに切り替える

   計画に納得できたら、もう一度Tabキーを押して、変更を適用するよう依頼してください。
5. 05
   実行し、改善を繰り返す

   エージェントはnpm testを実行し、出力を読み取って修正できます。この「実行・観察・修正」のループが、エージェント型AIの中核です。
6. 06
   確認およびコミット

   コミットする前にgit diffをもう一度確認してください。セッション中の作業が意図から外れてしまった場合は、git restoreでファイルを以前の状態に戻せます。

ローカルモデルでは、各ステップがホストされたモデルより遅くなり、曖昧な指示は言い換えが必要になることもあります。得られる利点は、自分で管理できることです。コードとコンテキストは自分のマシンに残り、ハードウェアに応じて、モデル、量子化、コンテキスト長を選べます。

#権限：エージェントがユーザーに確認を求めずに行えること

エージェントはユーザーの承認なしには何も変更しない、という考えが広く見られます。しかし、デフォルトの動作はそうではありません。OpenCodeのドキュメントによると、設定を行わない場合、ほとんどの権限はallow、つまり確認なしで実行する設定になっています。external_directoryやdoom_loopなど、一部だけがaskに設定されています。.envファイルの読み取りはデフォルトで拒否されますが、.env.exampleは例外です。

信頼性がやや低いローカルモデルを操作するエージェントでは、設定をより厳しくするのが慎重な対応です。opencode.jsonにはpermissionセクションを設定でき、各アクションにallow、ask、denyのいずれかを指定できます。全体に適用するルールとして、*をaskに設定することもできます。

{
  "$schema": "https://opencode.ai/config.json",
  "permission": { "*": "ask" }
}

#OpenCode、Cline、Aider：どれが適しているか？

3つともOllamaのAPIを使用しています。普段の使い方に近い2つを試すには1時間かかりますが、比較記事を読むよりも役に立ちます。エージェントではなくインラインの自動補完を求める場合は、Tabbyをご覧ください。

#トラブルシューティング

モデルが表示されません

opencode.json内の名前がollama listに表示される名前と一致していません。タグも含めて、正確な名前をコピーしてください。ollama launchを使う場合、opencode.json内でのみ定義されているモデルは、そのモデル選択欄に表示されません。

エージェントが直前に読んだ内容を忘れてしまう

コンテキストが短すぎます：64,000トークン（OLLAMA_CONTEXT_LENGTH）に設定し、ollama ps で確認してください。

接続が拒否されました

Ollamaサーバーが起動していないか、デフォルトのポート11434で待ち受けていません。ollama listを試し、次にbaseURLに指定したURLを確認してください。

ツール呼び出しの失敗

このモデルはツールをうまく扱えません。Ollamaのライブラリで「tools」と表示されているモデルを選んでください。

応答が非常に遅い

モデルおよびコンテキストが VRAM を超過し、一部がプロセッサ上で実行されます。コンテキストのサイズ、モデルのサイズ、または量子化を減らしてください。

#さらに詳しく

• Cline + Ollama による VS Code 内での利用
• ターミナルで使うAider + Ollama
• Tabby：ローカルコード補完
• 量子化の選び方
• コンテキストウィンドウを理解する
• Ollamaを 5 分でインストール

• 出典：Ollama、OpenCode統合
• 出典：Ollama、コンテキスト長
• 出典：OpenCodeのドキュメント
• 出典：OpenCodeの権限設定