0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

OpenCode × Ollama でローカル完結のセルフホスト型コーディングエージェントを構築する

0
Posted at

はじめに

ターミナルで動く AI コーディングエージェントが一気に増えました。なかでも OpenCode は、GitHub スター 17万超（2026年6月時点）で 最も多くのスターを集めた OSS コーディングエージェント です。Claude Code に似た使い勝手を、特定ベンダーに縛られず・自分のインフラ上で動かせるのが大きな特徴です。

この記事では、OpenCode を導入し、Ollama でローカルの LLM につないで「コードがクラウドに出ていかない」自己ホスト型のコーディングエージェント環境 を構築する手順を、実際の設定ファイルつきで解説します。手元でそのまま再現できるハンズオンを目指します。

この記事で学べること

  • OpenCode の立ち位置（誰が作っていて、何ができるか）
  • インストールから最初の起動まで
  • opencode.json で Ollama のローカルモデルにつなぐ設定の書き方
  • グローバル設定とプロジェクト設定の使い分け・AGENTS.md の役割
  • ローカルモデルで詰まりやすい「ツール呼び出しが効かない」問題の回避策

対象読者

  • Claude Code などのクラウド型エージェントを使っているが、コードを外部に出したくない方
  • ローカル LLM（Ollama）で完結する開発環境に興味があるエンジニア
  • ベンダーロックインを避けて複数プロバイダを切り替えたい方

前提環境

  • macOS / Linux / Windows のいずれか（ターミナルが使えること）
  • ローカルモデルを使う場合は Ollama をインストール済みであること

バージョンや細かな仕様は更新が速い領域です。最新の手順は必ず公式ドキュメントを確認してください。本記事は2026年6月時点の公式ドキュメントをもとにしています。

TL;DR

  • OpenCode は Anomaly（SST から派生したチーム） が開発する MIT ライセンスの OSS ターミナルエージェント
  • curl -fsSL https://opencode.ai/install | bash の1行で導入できる
  • Models.dev カタログ経由で 75以上のプロバイダ に対応し、Ollama / LM Studio / llama.cpp などローカルモデルも使える
  • ローカルモデルは opencode.json の provider に @ai-sdk/openai-compatible と baseURL: http://localhost:11434/v1 を書くだけでつながる
  • ローカルモデルでツール呼び出しが不安定なときは Ollama 側の num_ctx を 16k〜32k に上げる

OpenCode とは

OpenCode は、ターミナルに常駐する TUI（テキストユーザーインターフェース）型のコーディングエージェントです。ファイルの編集・コマンド実行・コードベースの探索をエージェントに任せられる点は Claude Code や Codex CLI と同じですが、次の特徴があります。

  • オープンソース（MIT ライセンス）: リポジトリは anomalyco/opencode（旧 sst/opencode）。フォーク・自前ビルド・改変が自由
  • プロバイダ非依存: Models.dev のカタログを通じて 75 以上の LLM プロバイダに対応。OpenAI 互換 API ならローカルモデルでも追加できる
  • LSP 連携: Language Server Protocol に対応し、型情報や診断をエージェントが参照できる
  • エディタ非依存: VS Code / Cursor / Zed など、ターミナルを持つ任意の環境の統合ターミナルで動く

開発元は、インフラ系 OSS で知られる SST から派生した Anomaly（anomalyco）です。

「OpenCode を使えば Claude モデルが自由に使える」という意味ではありません。利用できるモデルは契約しているプロバイダの API キー次第です。ローカル完結を狙うなら、後述の Ollama 連携が現実的な選択肢になります。

なぜ「ローカル self-host」なのか

クラウド型のコーディングエージェントは強力ですが、業務コードを扱う場面では次のような懸念がつきまといます。

懸念 ローカル self-host での解決
ソースコードが外部 API に送信される モデル推論を手元の Ollama で完結させればコードは外に出ない
従量課金が読めない ローカルモデルは推論コストが実質ゼロ（電気代のみ）
ベンダーの仕様変更・提供停止に振り回される プロバイダを opencode.json で差し替えるだけで移行できる

OpenCode は「クラウドのフロンティアモデル」と「ローカルモデル」を設定ファイルで自由に切り替えられるため、機密性の高いリポジトリだけローカルモデル、それ以外はクラウド といった使い分けもできます。

ステップ1: インストール

最も手早いのはインストールスクリプトです。

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

このほか、好みのパッケージマネージャでも導入できます。

# npm（Bun / pnpm / Yarn でも可）
npm install -g opencode-ai

# Homebrew（macOS / Linux）
brew install opencode

# Docker
docker run -it --rm -v "$PWD":/workspace ghcr.io/anomalyco/opencode

Windows では Chocolatey / Scoop / Mise、Arch Linux では Pacman も利用できます。

インストール後、プロジェクトのディレクトリで起動します。

cd your-project
opencode

TUI が立ち上がったら、/connect を実行してプロバイダを選び、API キーを貼り付ければクラウドモデルがすぐ使えます。ここからが本題のローカル接続です。

ステップ2: Ollama でローカルモデルにつなぐ

まず Ollama 側でモデルを起動しておきます。

# 例: コード生成に向くモデルを取得して起動
ollama pull qwen2.5-coder:7b
ollama serve   # 既に常駐している場合は不要

Ollama は OpenAI 互換のエンドポイント（http://localhost:11434/v1）を提供します。OpenCode 側はこのエンドポイントを「OpenAI 互換プロバイダ」として登録するだけです。

プロジェクトルートに opencode.json を作成します。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen2.5-coder:7b": {
          "name": "Qwen2.5 Coder 7B"
        }
      }
    }
  },
  "model": "ollama/qwen2.5-coder:7b"
}

設定の要点は次の3つです。

  • npm: ローカル接続には OpenAI 互換アダプタ @ai-sdk/openai-compatible を指定する
  • options.baseURL: Ollama の OpenAI 互換エンドポイント。末尾の /v1 を忘れない
  • models: 利用するモデル ID（ollama pull したタグ）と表示名を登録する

model キーは プロバイダID/モデルID の形式で、ここでは ollama/qwen2.5-coder:7b を既定モデルにしています。この状態で opencode を起動すると、推論はすべて手元の Ollama で行われ、コードが外部に送られることはありません。

ローカルモデルでは「ファイル編集」「コマンド実行」などの ツール呼び出し（function calling）が不安定 になることがあります。OpenCode の公式ドキュメントは、ツール呼び出しがうまく動かない場合に Ollama 側のコンテキスト長 num_ctx を 16k〜32k へ引き上げることを推奨しています。

num_ctx は Ollama の Modelfile か、リクエスト時のオプションで指定します。

# Modelfile でコンテキスト長を引き上げる例
cat > Modelfile <<'EOF'
FROM qwen2.5-coder:7b
PARAMETER num_ctx 32768
EOF

ollama create qwen2.5-coder-32k -f Modelfile

作成したモデルを opencode.json の models に登録し直せば、ツール呼び出しの安定性が改善します。

ステップ3: グローバル設定とプロジェクト設定の使い分け

OpenCode の設定ファイルは2か所に置けます。

種別 パス 用途
グローバル ~/.config/opencode/opencode.json 全プロジェクト共通の既定プロバイダ・モデル
プロジェクト <project>/opencode.json そのリポジトリ専用の上書き設定

両方とも JSON / JSONC（コメント可）で書けます。機密リポジトリにだけ ollama/... を既定にしたプロジェクト設定を置き、それ以外はグローバルでクラウドモデルを使う、といった運用が自然です。

small_model を併用すると、補完やタイトル生成のような軽いタスクを安いモデル（またはローカルモデル）に振り分けられます。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/qwen2.5-coder:7b",
  "small_model": "ollama/qwen2.5-coder:7b",
  "autoupdate": true
}

ステップ4: AGENTS.md でプロジェクトの作法を伝える

Claude Code の CLAUDE.md に相当するのが AGENTS.md です。プロジェクトルートに置くと、OpenCode がエージェントへの指示として読み込みます。

# AGENTS.md

## このリポジトリの方針
- パッケージマネージャは pnpm を使う
- テストは `pnpm test` で実行する
- コミットメッセージは Conventional Commits に従う

## 触ってはいけない場所
- `legacy/` 配下は変更しない

AGENTS.md は OpenCode 以外のエージェントツールでも採用が進んでいる共通フォーマットです。ツールを乗り換えても指示を再利用しやすいのが利点です。

ハマりどころと回避策

実際に動かすときに引っかかりやすいポイントをまとめます。

  • baseURL の /v1 抜け: Ollama を OpenAI 互換として使うときは http://localhost:11434/v1 が必須。素の http://localhost:11434 ではエラーになる
  • ツール呼び出しが効かない: 前述の num_ctx 引き上げに加え、ツール呼び出し対応のモデル（Qwen2.5 Coder など）を選ぶ。小さすぎるモデルは function calling が苦手
  • モデルが一覧に出ない: opencode.json の models に明示登録していないと選択肢に現れない。ollama pull したタグ名と一致させる
  • 遅い: ローカル推論は GPU の有無で体感が大きく変わる。重いタスクはクラウドモデル、機密タスクはローカル、と使い分けるのが現実的

まとめ

  • OpenCode は MIT ライセンスの OSS ターミナルエージェントで、プロバイダ非依存・ローカルモデル対応が強み
  • curl -fsSL https://opencode.ai/install | bash で導入し、opencode.json に OpenAI 互換プロバイダとして Ollama を登録すればローカル完結の環境が作れる
  • 設定はグローバルとプロジェクトで上書きでき、機密リポジトリだけローカルモデルにする運用が可能
  • ローカルモデルのツール呼び出しが不安定なときは num_ctx を 16k〜32k に上げる

「コードを外に出さずに AI コーディングエージェントを使いたい」という要件は、これまでハードルが高いものでした。OpenCode と Ollama の組み合わせなら、設定ファイル1枚でそれが現実になります。まずは小さなリポジトリでローカルモデルを試し、用途に応じてクラウドモデルと使い分けてみてください。

参考リンク

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?