OpenCodeのインストールと使い方：完全ガイド

約8分

OpenCodeのインストールと使い方：完全ガイド

OpenCodeは、人工知能の力を直接ターミナルにもたらすオープンソースのAIコーディングエージェントです。従来のエディターやブラウザ上で動作するAIコーディングツールとは異なり、OpenCodeはターミナルベースのインターフェース、デスクトップアプリ、IDE拡張機能を提供し、開発者の生産性向上を目指しています。この総合ガイドでは、OpenCodeのインストールから設定、効果的な使い方までを詳しく解説します。

OpenCodeとは？

OpenCodeはAI搭載のコーディングアシスタントで、以下のことを支援します：

コードをより速く書くためのインテリジェントなコード生成・補完
効率的なデバッグのためのエラー解析と修正提案
コードベースの理解を助ける自然言語クエリ
新機能追加を自動計画と実装で支援
コードレビューをAI解析と提案でサポート
ワークフロー自動化をAIエージェントとカスタムツールで実現

Anthropic、OpenAI、Googleなど複数のLLMプロバイダーに対応しており、ニーズに合ったモデルを柔軟に選べます。

システム要件

事前準備

OpenCodeをインストールする前に、以下を用意してください：

モダンなターミナルエミュレーター（TUI利用の場合）：
- WezTerm - クロスプラットフォーム
- Alacritty - クロスプラットフォーム
- Ghostty - LinuxおよびmacOS
- Kitty - LinuxおよびmacOS
Node.js（npm/bun/pnpm/yarnによるインストール時）：
- Node.js v18以上推奨
LLMプロバイダー用APIキー：
- Anthropic APIキー（Claudeモデル用）
- OpenAI APIキー（GPTモデル用）
- その他対応プロバイダーのキー

インストール方法

方法1：公式インストールスクリプト（推奨）

OpenCodeを最も速くインストールするには、公式のインストールスクリプトを使用します：

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

この方法はmacOS、Linux、Windows（Git BashまたはWSL利用時）で動作します。

方法2：Node.jsパッケージマネージャー利用

npmの場合：

npm install -g opencode-ai

Bunの場合：

bun install -g opencode-ai

pnpmの場合：

pnpm install -g opencode-ai

Yarnの場合：

yarn global add opencode-ai

方法3：Homebrew（macOS & Linux）

brew install opencode

方法4：Paru（Arch Linux）

paru -S opencode-bin

方法5：Windows専用インストール

Chocolatey使用時：

choco install opencode

Scoop使用時：

scoop bucket add extras
scoop install extras/opencode

Mise使用時：

mise use -g github:sst/opencode

方法6：Docker

コンテナ利用の場合：

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

方法7：バイナリ直接ダウンロード

GitHub Releasesページからプリコンパイル済みのバイナリを直接ダウンロードできます。

インストール確認

インストール後、動作確認を行います：

opencode --version

バージョン番号が表示されれば成功です。

初期設定

OpenCode Zenへの接続（初心者に推奨）

OpenCode ZenはOpenCodeチームが検証したモデルの厳選リストです。最も簡単に始められます。

OpenCodeを起動：

cd /path/to/your/project
opencode

TUIでconnectコマンドを実行:

/connect

プロバイダーリストから「opencode」を選択
認証URLにアクセス：opencode.ai/auth
サインインし、請求情報を追加（または利用可能な無料クレジットを使用）
APIキーをコピーし、ターミナルの指示に従ってペースト

他のプロバイダーへの接続

OpenCodeは他のLLMプロバイダーへの接続も可能です：

`/connect`コマンドを使用：

/connect

Anthropic、OpenAI、Googleなどから希望のプロバイダーを選択し、認証手順に従います。

CLI認証を使う場合：

opencode auth login

Models.devで利用可能なプロバイダーのAPIキー設定を案内します。

設定済みプロバイダー一覧表示：

opencode auth list

または短縮版：

opencode auth ls

プロバイダーからログアウト：

opencode auth logout

プロジェクトコンテキストの設定

プロバイダー設定後、プロジェクトを初期化します：

プロジェクトフォルダーへ移動：

cd /path/to/your/project

OpenCodeを起動：

opencode

initコマンドを実行：

/init

これによりプロジェクト構造の解析が行われ、ルートにAGENTS.mdファイルが作成されます。このファイルはOpenCodeがコーディングパターンやフレームワーク、プロジェクト構成を理解するのに役立ちます。

ヒント：AGENTS.mdはGitにコミットしましょう。チーム内の一貫性が保て、OpenCodeのプロジェクト理解が向上します。

ターミナルユーザーインターフェース（TUI）の使い方

OpenCodeのTUIは、ターミナル内で対話的に操作できる環境を提供します。

TUIの起動

単純に実行：

opencode

オプション付き起動例：

# 前回セッションの続行
opencode --continue

# 指定セッションの続行
opencode --session <session-id>

# プロンプトを指定して起動
opencode --prompt "Explain this codebase"

# モデル指定で起動
opencode --model anthropic/claude-sonnet-4-5

# エージェント指定で起動
opencode --agent plan

基本操作

スクロール：マウスホイールまたは矢印キー
モード切替：TabキーでPlanモードとBuildモードを切り替え
コマンド実行：/でコマンドパレットを開く
ファイル検索：@でプロジェクト内のファイルをあいまい検索
終了：Ctrl+C または /exit

質問する

コードベースについて質問できます：

How is authentication handled in @packages/functions/src/api/index.ts

@記号で特定ファイルを指定可能。OpenCodeがそのファイルを解析し詳細説明を返します。

機能追加

OpenCodeは2つのモードを活用して新機能追加を強力にサポートします。

ステップ1：Planモード

TabでPlanモードへ切り替え
追加したい機能を説明：

When a user deletes a note, we'd like to flag it as deleted in the database.
Then create a screen that shows all the recently deleted notes.
From this screen, the user can undelete a note or permanently delete it.

提案された計画を確認
フィードバックを繰り返す：

We'd like to design this new screen using a design I've used before.
[Image #1] Take a look at this image and use it as a reference.

ヒント：画像をターミナルにドラッグ＆ドロップ可能。OpenCodeが画像を解析します。

ステップ2：Buildモード

TabでBuildモードへ切り替え
実装を承認：

Sounds good! Go ahead and make the changes.

OpenCodeがファイルを作成・修正して機能を実装します。

直接変更を加える

シンプルな変更は計画フェーズを省略できます：

We need to add authentication to the /settings route.
Take a look at how this is handled in the /notes route
in @packages/functions/src/notes.ts and implement the same logic
in @packages/functions/src/settings.ts

変更の取り消し・やり直し

ミスした場合は取り消しコマンド：

/undo

直近の変更を戻し、指示を修正できます。

やり直す場合：

/redo

複数回/undoを実行することで複数の変更を戻せます。

CLIコマンド

OpenCodeはプログラム的な操作や自動化のための強力なCLIを用意しています。

直接プロンプト実行

非対話的にコマンドを実行：

opencode run "Explain how closures work in JavaScript"

スクリプトや自動処理、TUIを起動せずに素早く回答が欲しい時に便利です。

モデル管理

利用可能なモデル一覧表示：

opencode models

プロバイダー指定：

opencode models anthropic

モデルキャッシュの更新（新規モデル追加時など）：

opencode models --refresh

詳細情報付き表示（コストなど）：

opencode models --verbose

ヘッドレスサーバー起動

HTTPサーバーを起動しAPIで利用可能に：

opencode serve

ポート指定例：

opencode serve --port 3000

ウェブアプリ組み込みやスクリプトでの高速応答に役立ちます（MCPサーバーのコールドブートを避けるため）。

サーバーへのアタッチ

一つのターミナルでサーバー起動：

opencode serve

別のターミナルで接続して高速実行：

opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"

エージェント管理

新しいカスタムエージェント作成：

opencode agent create

カスタムのシステムプロンプトやツール設定を対話的に作成できます。

GitHub連携

リポジトリ自動化のためGitHubエージェントをインストール：

opencode github install

コードレビューやIssue管理のGitHub Actionsワークフローが設定されます。

OpenCodeのアップグレード

最新版にアップグレード：

opencode upgrade

特定バージョンにアップグレード：

opencode upgrade v0.1.48

インストール方法を指定する例：

opencode upgrade --method brew

設定

OpenCodeはJSON設定ファイルを用いた柔軟な設定をサポートします。

設定の場所

設定ファイルはマージされ、グローバル、プロジェクト特有、カスタム設定を併用できます。

グローバル設定：~/.config/opencode/opencode.json
- テーマ、プロバイダー、キーバインド、一般設定など
プロジェクト設定：プロジェクトルートのopencode.json
- プロジェクト固有のプロバイダー、エージェント、設定用
- Gitに安全にコミット可能
カスタム設定パス：OPENCODE_CONFIG環境変数で指定
カスタム設定ディレクトリ：OPENCODE_CONFIG_DIR環境変数で指定

基本設定例

以下のような構造で設定ファイルを作成：

{
  "$schema": "https://opencode.ai/config.json",
  
  // テーマ指定
  "theme": "opencode",
  
  // メインで使用するモデル
  "model": "anthropic/claude-sonnet-4-5",
  
  // 軽量タスク用の小型モデル
  "small_model": "anthropic/claude-haiku-4-5",
  
  // 自動アップデート設定
  "autoupdate": true
}

プロバイダー設定

APIキーを直接設定可能：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

セキュリティ上、環境変数を使うことを推奨します。{env:VARIABLE_NAME}形式で指定。

ファイル参照の利用

秘密情報をファイルで参照可能：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

カスタムコマンド

繰り返し作業用のカスタムコマンド定義例：

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run full test suite with coverage report and show any failures.\nFocus on failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

TUIで/testや/component MyComponentと入力して実行可能。

カスタムエージェント

専門用途向けエージェント作成例：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

パーミッション設定

許可なしで実行可能な操作を制御：

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

編集やbash操作はユーザーの承認が必要になります。

コードフォーマッター設定

自動整形ツールの設定例：

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": false
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

TUI設定

ターミナル画面のカスタマイズ例：

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

高度な機能

会話の共有

チームで会話内容を共有：

/share

共有用リンクが作成されクリップボードにコピーされます。会話はデフォルトで共有されません。

共有設定：

{
  "share": "manual"  // "manual", "auto", "disabled"
}

MCPサーバー

Model Context Protocol (MCP)サーバーはOpenCodeの機能を拡張します：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    }
  }
}

インストラクションとルール

プロジェクト固有の指示を提供：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

OpenCodeはこれらを読み込み、プロジェクトのコーディングスタイルや規約を理解します。

環境変数設定例

# セッションを自動的に共有
export OPENCODE_AUTO_SHARE=true

# カスタム設定ファイルへのパス
export OPENCODE_CONFIG=/path/to/config.json

# 設定ディレクトリへのパス
export OPENCODE_CONFIG_DIR=/path/to/config-dir

# 自動アップデートを無効化
export OPENCODE_DISABLE_AUTOUPDATE=true

# デフォルトプラグインを無効化
export OPENCODE_DISABLE_DEFAULT_PLUGINS=true

# 実験的モデルを有効化
export OPENCODE_ENABLE_EXPERIMENTAL_MODELS=true

# Exaウェブ検索機能を有効化
export OPENCODE_ENABLE_EXA=true

実験的機能の有効化

export OPENCODE_EXPERIMENTAL=true

特定の実験的機能：

# アイコンディスカバリーを有効化
export OPENCODE_EXPERIMENTAL_ICON_DISCOVERY=true

# TUIでの選択時コピー無効化
export OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT=true

# bashコマンド出力の最大長設定
export OPENCODE_EXPERIMENTAL_BASH_MAX_OUTPUT_LENGTH=10000

# bashコマンドのタイムアウト（ミリ秒）
export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=30000