# ネイティブ連携

CodeNomad は、OpenCode ネイティブの MCP 接続、プラグイン有効化、スキル、カスタムコマンドを提供します。これらは実行ホスト上で動きます。サンドボックス化された[パネル拡張機能](extensions.md)や [SideCar](browser-sidecars.md)とは別です。

## 適切なコントロールを選ぶ {#integration-scopes}

| 連携 | 操作する場所 | 変更するもの |
| --- | --- | --- |
| MCP サーバー | **ステータス → MCP サーバー** | 表示された Location のネイティブ接続。サーバーはインストールしません。 |
| ネイティブプラグイン | **ステータス → プラグイン** | パッケージの宣言を追加・削除し、永続的な **グローバル** または **プロジェクト** の有効化ルールを設定します。パッケージプラグインでは、そのパッケージの明示的な更新確認または更新。 |
| スキル | 入力欄の `@` メニュー | 会話の Location で、次のプロンプトへの明示的な添付。 |
| カスタムコマンド | 入力欄の `/` メニュー | その Location に対して OpenCode が公開するコマンドを実行。 |

まず OpenCode がサポートする設定と CLI を使用して、連携を設定／インストールしてください。パッケージのインストール、ソースの宣言、ルールの有効化、サービスの接続、ツールの利用可能化は別の手順です。ネイティブ連携は、OpenCode の権限に従ってホストプロセスの権限を持ち、サンドボックス化された HTML パネルではありません。

## MCP を接続・切断する {#mcp}

1. [OpenCode MCP ドキュメント](https://opencode.ai/v2/docs/mcp-servers/)に従い、OpenCode 実行ホストで MCP サーバーを設定します。
2. プロジェクトの **ステータス → MCP サーバー** を開きます。
3. サーバー横のスイッチで接続／切断し、接続表示が確定するまで待ちます。

スイッチは、報告された Location のネイティブ接続 API を呼び出します。端末ローカルのインストーラーや、ウィンドウごとの表示設定ではありません。その Location を使う他のクライアントにも接続変更が見える場合があります。切断してもサーバー宣言や実行ファイルは削除されません。

サーバーが表示されない場合は、アクティブな Location とそのネイティブ設定を確認します。接続に失敗したら、サーバー設定、必要な環境、ネイティブ認証フローを確認してください。スイッチが OAuth を完了させるとは想定しないでください。再接続後に状態を再確認します。設定の明示的な再読み込みは必要な場合だけ行い、[OpenCode のセットアップ](opencode.md)に記載された中断に注意してください。

## グローバル／プロジェクト範囲でプラグインを有効にする {#plugins}

1. [プラグインを追加](#plugin-sources)するか OpenCode の設定で宣言し、**ステータス → プラグイン** を開きます。
2. 名前にカーソルを合わせるかフォーカスし、ソース、ランタイムの失敗、設定対象の詳細を確認します。
3. **グローバル** または **プロジェクト** を意図的に切り替えます。書き込みを待ち、状態が不明なら **プラグインコントロールを更新** を使用します。
4. パッケージからインストールしたプラグインでは、名前の横のアイコンを使用します。そのメニューには正確な操作が表示されます。パッケージの **… の更新を確認**、または新しいバージョンが見つかった後の **… を更新** です。

グローバルは、接続先デーモンが検出したグローバル設定を対象とします。プロジェクトは、継承した上位ファイルではなく、アクティブな Location 内の設定を対象とします。後のプロジェクトルールはグローバルを上書きできますが、グローバルのスイッチは、最終的なプロジェクト状態を装わず、グローバルのルールを表示します。プロジェクトルールがなければ、解決済みのグローバル状態を継承します。

これらのスイッチは、ソース宣言と無関係な設定を保持しつつ、正確な有効化ルールを追記します。プラグインのオプション編集、パッケージのインストール、ファイル削除はしません。OpenCode 組み込みプラグインには、ユーザー用の有効化スイッチを提供しません。対象をグローバルから安全に分離できない、またはアクティブな Location の外に出る場合、プロジェクトは無効になります。

パッケージの更新は、ツールチップに記載のとおり、OpenCode の共有キャッシュ内のそのパッケージを、それを使う全 Location について変更します。有効化ルールの変更、OpenCode の再起動、設定の再読み込みは行いません。ローカル、組み込み、SDK 提供のプラグインにはパッケージ操作がありません。プラグイン ID を報告する前に失敗したパッケージは、パッケージ名で一覧に表示され、ツールチップに失敗内容があり、更新確認／更新の操作はありますが、有効化スイッチはありません。更新確認や更新の失敗は報告され、自動的に再試行されることはありません。

この画面は、非表示中も直近のスナップショットを保持し、表示時、ネイティブ変更／再接続時、明示的更新時に再検証します。保存済みルールと稼働中の利用可否は、一時的に異なる場合があります。プラグインがまだ利用できない場合は、ツールチップとネイティブ設定を確認してから **OpenCode の設定を再読み込み** を選んでください。この操作はプラグインだけでなく、読み込み済みの全 Location に影響します。不正な設定や同時編集を無断で上書きしません。解決して更新し、明示的に再試行してください。

## プラグインを追加・削除する {#plugin-sources}

1. **ステータス → プラグイン** で **プラグインを追加**（**プラグインコントロールを更新** の横のプラスアイコン）を選びます。
2. npm レジストリのパッケージ（`name`、`name@1.2.3`、`@scope/name@^1`）または Git リポジトリ（`github:owner/repo`、`git+https://…`）を入力します。
3. プラグインをこのプロジェクトだけで実行する場合を除き **グローバル** のままにして、**追加** を選びます。
4. 新しい行は OpenCode が報告するまで **インストール中** と表示されます。その後、スイッチ付きの通常のプラグイン行か、失敗した行になります。

プラグインを削除するには、名前の横のメニューを開いて **グローバル から削除** または **プロジェクト から削除** を選びます。削除されるのはそのスコープの設定ファイルにある宣言だけです。**グローバル**／**プロジェクト** の有効化ルールはルールとして残り、OpenCode のパッケージキャッシュもそのまま残ります。

プラグインのコードは OpenCode 内であなたの権限で実行されます。**プロジェクト** のエントリはそのフォルダーを OpenCode で開くたびに実行され、OpenCode デスクトップアプリ向けの部分を持つパッケージはそれを **グローバル** からのみ読み込みます。そのようなパッケージが別の場所で宣言されている場合はツールチップに表示されます。ローカルパス、設定変数、プラグイン ID はここでは受け付けません。ローカルプラグインは設定ファイルで宣言してください。この Location に適用される設定ですでに宣言されたパッケージは、バージョン、範囲、形式にかかわらず拒否されます。

レビュー済みカタログの OpenCode 統合（例: Blender 統合）は、インストール前から認識されます。アプリケーション内に部分を持つ統合は **グローバル** にのみ追加でき、**プロジェクト** は拒否されます。レジストリパッケージと Git ビルドは同じ 1 つのパッケージとして扱われるため、すでに宣言または読み込まれている統合の別の形を追加すると拒否されます。

プラグイン名にポインターを置くかフォーカスすると、バージョン、**更新があります**、インストールに失敗した場合は OpenCode のログにある参照付きのエラーが表示されます。2 分たっても OpenCode が報告しない行は **未確認** となり、**プラグインコントロールを更新** の操作が表示されます。プラグインが無効になっているか、インストールが完了していない可能性があります（[トラブルシューティング](troubleshooting.md#providers-and-addons)を参照）。

## スキルを添付する {#skills}

1. 入力欄に `@` を入力し、Location の利用可能なスキルを検索して選びます。
2. ファイル／エージェントと並ぶ削除可能な添付を確認し、意図しない場合は送信前に削除します。
3. プロンプトを送信します。スキルのラベルは送信済みメッセージに残ります。

選択は、ネイティブのスキル ID を添付して `@query` トークンを取り除きます。表示中の下書きに指示を貼り付けません。送信は入力欄の選択をクリアしますが、OpenCode がそのメッセージとともに既に保存した指示は消しません。添付の削除で以前の送信を取り消すことはできません。

スキルの利用可否は、CodeNomad 全体のスキルカタログではなく、会話の Location から取得します。一覧を読み込めない場合は、ピッカーを閉じて開き直して再試行します。空の場合はネイティブの検出／設定を確認してください。[OpenCode スキルドキュメント](https://opencode.ai/v2/docs/skills/)と[会話](conversations.md)を参照してください。

## カスタムコマンドを実行する {#commands}

1. 入力欄に `/` を入力し、利用可能なネイティブコマンドを選びます。
2. 引数を指定し、そのコマンドに応じて送信前に **エージェント**、**モデル**、**思考** を確認します。
3. 受け付けが不明な場合は、何度も送信せず、結果の会話を確認します。

コマンドはアクティブな Location の OpenCode から検出します。実行動作は、それぞれのネイティブ定義で選べます。メニューはパッケージインストーラーでも無制限の設定エディターでもありません。CodeNomad は、ネイティブのカスタムコマンド送信前にプロファイルのセッション環境を適用します。環境更新に失敗すると送信をブロックします。`/btw` は CodeNomad 独自の一時的な質問フローであり、通常のカスタムコマンドではありません。

コマンド定義とネイティブ設定の継承は、[OpenCode コマンドドキュメント](https://opencode.ai/v2/docs/commands/)を参照してください。設定変更後は、まず関連画面を更新／開き直します。ランタイムがまだ必要とする場合にのみ、明示的な設定再読み込みを使用してください。表示更新のためだけに、受け付け済みかもしれないコマンドを再実行しないでください。