OpenCodeの設定 - カスタムコマンド

提供: MochiuWiki : SUSE, EC, PCB

概要

OpenCodeは、様々なLLMプロバイダに対応したオープンソースのターミナルAIコーディングアシスタントである。
75以上のプロバイダと200以上のモデルをサポートし、カスタムコマンド機能によりよく使うプロンプトをコマンドとして登録・再利用できる。

カスタムコマンドは、繰り返し実行するタスクを定義済みプロンプトとして保存する機能である。

カスタムコマンドの特徴
特徴 説明
再利用性 同じプロンプトを何度も入力する手間を省き、コマンド名1つで呼び出せる。
プロジェクト固有・グローバルの使い分け プロジェクト専用のコマンドと、全プロジェクトで使用するグローバルコマンドを別々に管理できる。
プレースホルダーによる柔軟な引数渡し 呼び出し時に引数を渡して動的なプロンプトを生成できる。
ファイル参照・シェルコマンドの埋め込み ファイルの内容やシェルコマンドの実行結果をプロンプトに含められる。



カスタムコマンドの基本構造

カスタムコマンドは、Markdownファイル または opencode.json の2通りの方法で定義できる。

Markdownファイルで定義する場合、フロントマターにメタデータを記述し、本文にプロンプト内容を記述する。

基本的なファイル構造を以下に示す。

 ---
 description: コマンドの説明
 agent: 実行するエージェント名
 model: プロバイダ名/モデルID
 ---
 <プロンプト内容をここに記述する>
 
 <$ARGUMENTS で呼び出し時の引数を受け取る>


下表に、フロントマターの各フィールドを示す。

フィールド 説明
description コマンドパレットやヘルプに表示される説明文 (省略可能)
agent このコマンドを実行するエージェント名
省略した場合はデフォルトエージェントが使用される。
model 使用するLLMモデル
<プロバイダ名>/<モデルID> の形式で指定する。
省略した場合は現在の設定が使用される。



ディレクトリ構造

カスタムコマンドの定義ファイルは、プロジェクト固有 または グローバルの2か所に配置できる。

カスタムコマンドの配置ディレクトリ
スコープ ディレクトリパス 説明
プロジェクト固有 .opencode/commands/ 現在のプロジェクトのみで使用可能
グローバル ~/.config/opencode/commands/ 全プロジェクトで使用可能


ディレクトリ構造の例を以下に示す。

# プロジェクト固有 (例: QML/C++プロジェクト)
.opencode/
   commands/
      build.md          # /build CMakeビルドコマンド
      qml-lint.md       # /qml-lint QMLリントコマンド
      ctest.md          # /ctest ユニットテスト実行コマンド

# グローバル
~/.config/opencode/
   commands/
      commit-msg.md     # /commit-msg コミットメッセージ生成コマンド
      translate.md      # /translate 翻訳コマンド


ファイル名がコマンドIDになる。
例えば、review.md は /review コマンドとして呼び出される。

同名のコマンドが両方に存在する場合、プロジェクト固有のコマンドが優先される。


カスタムコマンドの作成方法

Markdownファイルによる定義

.opencode/commands/ または ~/.config/opencode/commands/ にMarkdownファイルを作成する。

コードレビューコマンドの例を以下に示す。

 ---
 description: コードレビューを実行する
 ---
 以下のコードをレビューして、問題点と改善案を日本語で報告してください。
 
 $ARGUMENTS


特定のファイルを参照するコマンドの例を以下に示す。
@<ファイルパス> の記法でファイルの内容をプロンプトに含めることができる。

 ---
 description: プロジェクトの規約に従いコードを修正する
 ---
 @.opencode/CONVENTIONS.md の規約に従い、以下のコードを修正してください。
 
 $ARGUMENTS


シェルコマンドの実行結果を埋め込む例を以下に示す。
!`<シェルコマンド>` の記法でシェルコマンドの実行結果をプロンプトに挿入できる。

 ---
 description: 現在のGitの差分をレビューする
 ---
 以下のGit差分をレビューして、問題点と改善案を報告してください。
 
 !`git diff HEAD`


位置引数を使用する例を以下に示す。
$1、$2、$3 で個別の引数にアクセスできる。

 ---
 description: 指定した言語に翻訳する
 ---
 以下のテキストを $1 に翻訳してください。
 
 $2


名前付き引数を使用する例を以下に示す。
$NAME の形式で名前付き引数を使用できる。

 ---
 description: テストを生成する
 ---
 $FUNCTION 関数のユニットテストを $FRAMEWORK フレームワークで生成してください。


opencode.jsonによる定義

opencode.json の commands フィールドにコマンドを定義することもできる。

 {
    "commands": {
       "review": {
          "template": "以下のコードをレビューして、問題点と改善案を日本語で報告してください。\n\n$ARGUMENTS",
          "description": "コードレビューを実行する",
          "agent": "default",
          "model": "anthropic/claude-sonnet-4-5"
       },
       "translate": {
          "template": "以下のテキストを $1 に翻訳してください。\n\n$2",
          "description": "指定した言語に翻訳する"
       },
       "test-gen": {
          "template": "$FUNCTION 関数のユニットテストを生成してください。",
          "description": "テストを生成する",
          "model": "openai/gpt-4o"
       }
    }
 }


opencode.json による定義では、以下のフィールドを設定できる。

フィールド 説明
template プロンプトのテンプレート文字列
必須
description コマンドの説明
コマンドパレットに表示される。
agent 使用するエージェント名
model 使用するLLMモデル
<プロバイダ名>/<モデルID> の形式で指定する。



カスタムコマンドの呼び出し方法

スラッシュコマンド形式

チャット入力欄に /コマンド名 と入力することで呼び出せる。

# 引数無しで呼び出す場合
/review

# 引数を渡して呼び出す場合
/translate 日本語 This is a sample text.

# ファイル参照と組み合わせる場合
/review @src/main.go


スラッシュコマンドは入力途中でフィルタリングされ、候補が一覧表示される。
/re と入力すると、名前が "re" で始まるコマンドが候補として表示される。

コマンドパレット ([Ctrl] + [K]キー)

[Ctrl] + [K]キーを押下してでコマンドパレットを開いて、コマンドを検索して実行できる。

コマンドパレットでは以下の操作が可能である。

  • コマンド名や説明でのインクリメンタル検索
  • 上下矢印キーでの選択
  • [Enter]キーでの実行
  • [Esc]キーでのキャンセル



ビルトインスラッシュコマンド一覧

OpenCodeには以下のビルトインスラッシュコマンドが用意されている。
カスタムコマンドで同名のコマンドを定義することにより、ビルトインコマンドを上書きできる。

ビルトインスラッシュコマンド一覧
コマンド 説明
/init プロジェクトを初期化して設定ファイルを生成する。
/undo 直前の操作を取り消す。
/redo 取り消した操作をやり直す。
/share 現在のセッションを共有する。
/help 利用可能なコマンドの一覧とヘルプを表示する。


ビルトインコマンドを上書きする場合は、同名のMarkdownファイルをコマンドディレクトリに配置する。
例えば、/help コマンドを上書きするには、.opencode/commands/help.md を作成する。


キーボードショートカット

リーダーキーシステム

OpenCodeのキーボードショートカットは、リーダーキーシステムを採用している。
デフォルトのリーダーキーは、[Ctrl] + [X]キーである。

操作方法は以下の通りである。

  1. [Ctrl] + [X]キー (リーダーキー) を押下する。
  2. 続けてアクションキーを押下する。


例えばセッション管理画面を開く場合は、[Ctrl] + [X]キーをを押下した後に[L]キーを押下する。

デフォルトショートカット一覧

セッション管理ショートカット
ショートカット 説明
[Ctrl] + [X]キー -> [N]キー 新規セッションを作成する。
[Ctrl] + [X]キー -> [L]キー セッション一覧を表示する。
[Ctrl] + [X]キー -> [Shift] + [S]キー 現在のセッションを共有する。


表示切り替えショートカット
ショートカット 説明
[Ctrl] + [X]キー -> [T]キー テーマを変更する。
[Ctrl] + [X]キー -> [B]キー サイドバーの表示・非表示を切り替える。
[Ctrl] + [X]キー -> [E]キー エディタの表示・非表示を切り替える。


モデル・コマンド操作ショートカット
ショートカット 説明
[F2]キー 最近使用したモデルを順に切り替える。
[Ctrl] + [P]キー コマンドパレットを開く。
[Ctrl] + [K]キー コマンドパレットを開く。([Ctrl] + [P]キーと同じ)


テキスト編集ショートカット (Emacs / Readline形式)
ショートカット 説明
[Ctrl] + [A]キー 行頭に移動する。
[Ctrl] + [E]キー 行末に移動する。
[Alt] + [B]キー 1単語前に移動する。
[Alt] + [F]キー 1単語後に移動する。


カスタムキーバインド設定

opencode.json の keybinds フィールドでキーバインドをカスタマイズできる。

リーダーキーを変更する場合は、leader フィールドで指定する。

 {
    "keybinds": {
       "leader": "ctrl+a",
       "session:new": "ctrl+a n",
       "session:list": "ctrl+a l"
    }
 }


特定のショートカットを無効化するには、値に "none" を指定する。

 {
    "keybinds": {
       "session:share": "none"
    }
 }



CLIコマンド

基本コマンド

OpenCode 基本コマンド一覧
コマンド 説明 例
opencode TUI (ターミナルユーザインターフェース) を起動する。 opencode
opencode run "プロンプト" プロンプトをCLIから直接実行して結果を出力する。 opencode run "このコードを説明して"
opencode session list セッションの一覧を表示する。 opencode session list
opencode export [sessionID] セッションをファイルにエクスポートする。 opencode export abc123
opencode import <ファイル> セッションをファイルからインポートする。 opencode import session.json
opencode models 利用可能なモデルの一覧を表示する。 opencode models
opencode models [provider] 指定したプロバイダのモデル一覧を表示する。 opencode models anthropic
opencode auth login 認証情報を設定する。 opencode auth login
opencode auth list 設定済みの認証情報一覧を表示する。 opencode auth list
opencode serve ヘッドレスサーバーとして起動する。 opencode serve
opencode web Webインターフェースを起動する。 opencode web
opencode attach [url] リモートのOpenCodeインスタンスに接続する。 opencode attach http://localhost:4200
opencode mcp add MCPサーバを追加する。 opencode mcp add
opencode mcp list MCPサーバの一覧を表示する。 opencode mcp list
opencode mcp auth <name> MCPサーバの認証を実行する。 opencode mcp auth my-server
opencode github install GitHub Agentをインストールする。 opencode github install
opencode github run GitHub Agentを実行する。 opencode github run


グローバルフラグ

全てのコマンドで使用できるグローバルフラグを以下に示す。

グローバルフラグ一覧
フラグ 省略形 説明
--help -h コマンドのヘルプを表示する。
--version -v OpenCodeのバージョンを表示する。
--log-level - ログレベルを設定する。 (debug, info, warn, error)


非対話モード

opencode run コマンドを使用すると、TUIを起動せずにプロンプトをCLIから直接実行できる。
パイプやスクリプトとの連携に適している。

使用例を以下に示す。

# プロンプトを直接実行
opencode run "src/main.go のコードを説明して"

# パイプでファイルの内容を渡す
cat src/main.go | opencode run "このコードをレビューして"

# 結果をファイルに保存
opencode run "README.mdのドラフトを作成して" > README.md



実用例

コードレビューコマンド

 ---
 description: 差分をレビューして改善点を報告する
 ---
 以下のGit差分をレビューして、以下の観点から評価してください。
 
 - セキュリティ上の問題
 - パフォーマンスへの影響
 - コードの可読性
 - テストの必要性
 
 !`git diff HEAD`


テスト生成コマンド

 ---
 description: 指定したファイルのユニットテストを生成する
 ---
 以下のコードのユニットテストを生成してください。
 エッジケースも含めて網羅的にテストしてください。
 
 @$1


コミットメッセージ生成コマンド

 ---
 description: ステージング済みの変更からコミットメッセージを生成する
 ---
 以下のGitステージング済みの変更に基づいて、Conventional Commits形式のコミットメッセージを生成してください。
 
 !`git diff --staged`



トラブルシューティング

コマンドが認識されない

コマンドが / コマンドとして認識されない場合は、以下に示す事柄を確認する。

  • ファイルの配置場所を確認する。
    .opencode/commands/ または ~/.config/opencode/commands/ に配置されているか確認する。

  • ファイル名を確認する。
    ファイル名に使用できるのは英数字、ハイフン、アンダースコアのみである。

  • ファイルの拡張子を確認する。
    拡張子は .md である必要がある。

  • OpenCodeを再起動する。
    コマンドを追加した後、OpenCodeを再起動することで反映される場合がある。


プレースホルダーが展開されない

引数が正しく渡されない場合は、以下に示す事柄を確認する。

  • プレースホルダーの記述を確認する。
    $ARGUMENTS (全引数)、$1/$2/$3 (位置引数)、$NAME (名前付き引数) の形式を確認する。

  • 引数の形式を確認する。
    名前付き引数の場合は、<NAME>=<値> の形式で渡す必要がある。


シェルコマンドが実行されない

!`シェルコマンド` の記法でシェルコマンドが実行されない場合は、以下に示す事柄を確認する。

  • 記法を確認する。
    バッククォート (`) で囲まれているか確認する。

  • コマンドのパスを確認する。
    絶対パスを使用する、または、コマンドが PATH に含まれているか確認する。

  • 権限を確認する。
    シェルコマンドの実行には、セキュリティ上の確認が求められる場合がある。



「https://mochiu.net/index.php?title=OpenCodeの設定_-_カスタムコマンド&oldid=14369」から取得