OpenCode クイックスタート: インストール、設定、およびターミナルAIコーディングエージェントの使用

OpenCodeは、ターミナル（TUI + CLI）で動作するオープンソースのAIコーディングエージェントです。オプションでデスクトップやIDEのインターフェースも利用可能です。これはOpenCode Quickstartです：インストール、検証、モデル/プロバイダーの接続、そして実際のワークフロー（CLI + API）の実行。

バージョンに関する注意点：OpenCodeは迅速にリリースされます。ここでの「最新」コマンドは安定していますが、出力やデフォルトは変更されることがあります。常に公式のCLIドキュメントと変更履歴（以下にリンク）を確認してください。

この記事はAI Developer Tools: The Complete Guide to AI-Powered Developmentの一部です。

OpenCodeとは（そしてどこに位置するか）

OpenCodeは、ターミナルファーストのエージェント型コーディングに設計されており、プロバイダー/モデルの柔軟性を維持しています。実際には、以下のようなワークフロー層として機能します：

• opencodeを実行するとターミナルUIを起動
• opencode runで非対話型の「ワンショット」プロンプトを実行（スクリプト/自動化）
• opencode serveでヘッドレスHTTPサーバーを公開（opencode webでWebUIも）
• 公式のJS/TS SDK @opencode-ai/sdkでプログラム的に制御可能

/ai-devtools/クラスターを構築している場合、OpenCodeはサブクラスターとして強く候補になります。なぜなら、自然に以下に拡張できるからです：

• CLIの深掘り
• モデル/プロバイダーの動作とコスト（OpenCode内のLLM比較）
• 設定とエージェント
• インテグレーション（GitHub/GitLab/Copilot）
• チートシート

事前準備

必要なもの：

• 現代的なターミナルエミュレータ（TUI体験のために重要）
• 少なくとも1つのモデル/プロバイダーへのアクセス（APIキーまたはサブスクリプション認証、プロバイダーにより異なる）。ローカルオプションとして、Ollamaやllama.cppは、ローカルで互換性のあるサーバーを実行すればAPIキー不要で動作します。

OpenCodeのインストール（コピー＆ペースト）

公式インストールスクリプト（Linux/macOS/WSL）：

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

パッケージマネージャーのオプション（公式の例）：

# Node.jsグローバルインストール
npm install -g opencode-ai

# Homebrew（OpenCodeが最新リリースを推奨）
brew install anomalyco/tap/opencode

# Arch Linux（安定版）
sudo pacman -S opencode

# Arch Linux（AURから最新版）
paru -S opencode-bin

Windowsの注意点（公式ガイドでは、互換性の観点からWSLが推奨されます）。代替としてScoop/Chocolateyまたはnpmもあります。

# Chocolatey（Windows）
choco install opencode

# Scoop（Windows）
scoop install opencode

Docker（すぐに試したい場合に有用）：

docker run -it --rm ghcr.io/anomalyco/opencode

インストールの確認

opencode --version
opencode --help

予期される出力の形状（バージョンにより異なる）：

# 例：
# <バージョン番号を出力、例：vX.Y.Z>
# <利用可能なコマンド/サブコマンドのヘルプを出力>

プロバイダーの接続（実用的な2つのパス）

パスA：TUI /connect（対話型）

OpenCodeを起動：

opencode

その後実行：

/connect

UIの手順に従ってプロバイダーを選択し、認証してください（一部のフローではブラウザ/デバイスログインが開きます）。

パスB：CLI opencode auth login（プロバイダーのキー）

OpenCodeは以下のコマンドでプロバイダーを設定できます：

opencode auth login

注意点：

• 認証情報は ~/.local/share/opencode/auth.json に保存されます。
• OpenCodeは、環境変数またはプロジェクト内の .env ファイルからキーを読み込むこともできます。

ローカルLLMホスティング（Ollama、llama.cpp）

OpenCodeはOpenAI互換APIと連携します。ローカル開発では、多くのユーザーがOllamaを実行し、OpenCodeをそれに接続しています。最近では、llama.cppを使用してOpenCodeを構成・実行した経験がありました。llama-serverはOpenAI互換のエンドポイントを提供するため、GGUF形式のモデルを使用して同じワークフローで動作できます。メモリやランタイムの細かい制御が必要、またはPythonなしで軽量なスタックを望む場合は（ちなみに、ollamaはGoで実装されています）、llama.cppを試してみることをおすすめします。オフロードされたレイヤーの設定や、GGUF形式のモデルの使いやすさ、新しいモデル（例：Qwen3.5）とのより良い/高速な互換性の実装の機会を楽しむことができました。

プロジェクトを正しく開始する（推奨される最初の実行）

リポジトリから：

cd /path/to/your/repo
opencode

その後初期化：

/init

これはプロジェクトを分析し、プロジェクトルートに AGENTS.md ファイルを作成します。通常はこのファイルをコミットして、OpenCode（およびチームメイト）が一貫したプロジェクトコンテキストを共有するようにします。

核心的なCLIワークフロー（コピー＆ペーストの例）

OpenCodeは非対話型の実行をサポートしています：

opencode run "JavaScriptにおけるクロージャの動作を説明してください"

ワークフロー：コード生成（CLI）

目標：最小限の文脈でテスト可能な小さな関数を生成する。

opencode run "Go関数ParsePort(envVar string, defaultPort int) (int, error)を書け。envVarを読み取り、整数を解析し、1-65535の範囲を検証し、空の場合にはdefaultPortを返す。3つのテーブル駆動テストを含めよ。"

予期される出力：

• 説明に加えてコードブロック（関数＋テスト）。コードはモデル/プロバイダーとプロンプトにより異なります。

ワークフロー：ファイルの安全なリファクタリング（CLI + Planエージェント）

目標：より制限的なエージェントを使用して、偶然の編集を避けてリファクタリングを行う。

opencode run --agent plan --file ./src/auth.ts \
  "このファイルを複雑さを減らすようにリファクタリングしてください。出力：(1) 簡潔な計画、(2) 統合された差分パッチ、(3) テストすべきリスク/エッジケース。コマンドは実行しないでください。"

予期される出力：

• 計画セクション＋diff --git ...パッチブロック＋テストチェックリスト。
• 内容は変動します。差分が出力されない場合は、再プロンプト：「差分のみを返してください」または「diff --git形式を使用してください」。

ワークフロー：リポジトリに関する質問（CLI）

目標：実装の詳細を迅速に特定する。

opencode run --agent explore \
  "このリポジトリでは、APIリクエストの認証がどのファイルで検証されていますか？可能性のあるファイルをリストし、フローを説明してください。不確実な場合は、確認した内容を述べてください。"

予期される出力：

• 短いファイルパスのマップ＋フローの説明。
• 出力はリポジトリのサイズとモデル/プロバイダーのコンテキストツールにより異なります。

ワークフロー：繰り返しのCLI実行を速くするために持続可能なサーバーを使用

スクリプト作成や複数の opencode run コールを実行する場合、一度だけヘッドレスサーバーを起動できます：

ターミナル1：

opencode serve --port 4096 --hostname 127.0.0.1

ターミナル2：

opencode run --attach http://localhost:4096 "リポジトリ構造と主要エントリポイントを要約してください。"
opencode run --attach http://localhost:4096 "今度は、3つの高影響リファクタリングを提案し、その理由を説明してください。"

予期される出力：

• opencode runと同様の出力ですが、通常は繰り返しの起動オーバーヘッドが少なくなっています。

プログラム的な使用（公式JS/TS SDK）

OpenCodeはHTTPサーバー（OpenAPI）を公開し、型安全なJS/TSクライアントを提供しています。

インストール：

npm install @opencode-ai/sdk

例：サーバー＋クライアントを起動し、プロンプトを送信

scripts/opencode-sdk-demo.mjsを作成：

import { createOpencode } from "@opencode-ai/sdk";

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    // モデル文字列の形式はプロバイダー/モデル（例としてのみ）
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

console.log(`サーバーが稼働しています: ${opencode.server.url}`);

// 基本的な健康状態/バージョンチェック
const health = await opencode.client.global.health();
console.log("健康状態:", health.data.healthy, "バージョン:", health.data.version);

// セッションを作成し、プロンプトを送信
const session = await opencode.client.session.create({ body: { title: "SDKクイックスタートデモ" } });

const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "このリポジトリを説明する小さなREADMEセクションを生成してください。" }],
  },
});

console.log(result.data);

// 終了時にサーバーを停止
opencode.server.close();

実行：

node scripts/opencode-sdk-demo.mjs

予期される出力の形状：

• “サーバーが稼働しています …”
• バージョン文字列を含む健康応答
• responseStyleとSDKバージョンにより応答オブジェクトの構造が異なるセッションプロンプト応答

コピー可能な最小限のOpenCode設定

OpenCodeはJSONおよびJSONC設定をサポートしています。プロジェクトローカル設定の合理的な出発点です。

リポジトリルートに opencode.jsonc を作成：

{
  "$schema": "https://opencode.ai/config.json",

  // デフォルトモデル（プロバイダー/モデル）を選択。これは `opencode models` が表示する内容と一致させる必要があります。
  "model": "provider/model",

  // オプション：軽量タスク（タイトルなど）に使用するより安価な「小規模モデル」
  "small_model": "provider/small-model",

  // オプション：OpenCodeサーバーのデフォルト（`serve/web`で使用）
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },

  // オプションの安全性：編集/コマンド実行前に確認を求める
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

簡易OpenCodeチートシート（クイックリファレンス）

毎日使用するコマンド

opencode                       # TUIを起動
opencode run "..."             # 非対話型の実行（スクリプト/自動化）
opencode run --file path "..." # プロンプトにファイルを添付
opencode models --refresh      # モデルリストを更新
opencode auth login            # プロバイダーアクセス資格情報を設定
opencode serve                 # ヘッドレスHTTPサーバー（OpenAPI）
opencode web                   # ヘッドレスサーバー＋WebUI
opencode session list          # セッションを一覧
opencode stats                 # トークン/コスト統計

覚えておくべきTUIコマンド

/connect   # プロバイダーを接続
/init      # リポジトリを分析し、AGENTS.mdを生成
/share     # セッションを共有（有効な場合）
/undo      # 変更を元に戻す
/redo      # 変更を再実行
/help      # ヘルプ/ショートカット

デフォルトの「リーダーキー」の概念（TUI）

OpenCodeはターミナルの競合を避けるために設定可能な「リーダー」キー（通常 ctrl+x）を使用します。多くのショートカットは「リーダー + キー」で構成されます。

1ページで印刷可能なOpenCodeチートシート表

このバージョンは意図的に密度が高く、「印刷用」に設計されています。（後で専用の /ai-devtools/opencode/cheatsheet/ ページに貼り付けることもできます。）

参考資料（公式が優先）

公式：

• OpenCodeドキュメント（紹介、CLI、設定、サーバー、SDK）：https://opencode.ai/docs/
• OpenCode変更履歴：https://opencode.ai/changelog
• 公式GitHubリポジトリ：https://github.com/anomalyco/opencode
• リリース：https://github.com/anomalyco/opencode/releases

権威的な統合リファレンス：

• GitHub変更履歴（CopilotがOpenCodeをサポート）：https://github.blog/changelog/2026-01-16-github-copilot-now-supports-opencode/

信頼できる比較/チュートリアル：

• DataCamp：OpenCode vs Claude Code（2026）：https://www.datacamp.com/blog/opencode-vs-claude-code
• Builder.io：OpenCode vs Claude Code（2026）：https://www.builder.io/blog/opencode-vs-claude-code
• freeCodeCamp：OpenCodeを使ってターミナルにAIを統合：https://www.freecodecamp.org/news/integrate-ai-into-your-terminal-using-opencode