BeeX Tech blog

BeeXではクラウドネイティブアプリ開発、企業の基幹クラウド基盤構築、システム移行、運用保守を行っています。

OpenCode導入ガイド：Azure OpenAI連携

AI Agent

はじめに

本記事では、オープンソースのAIコーディングエージェント「OpenCode」をAzure OpenAIと連携し、Azureにデプロイしたモデルを利用できるようにするまでの手順を整理します。

OpenCodeはAzure OpenAIおよびAzure Cognitive Servicesの2つのAzureプロバイダーをサポートしており、APIキーと環境変数を設定するだけで利用可能です1。

なお、本記事はOpenCodeのインストールが完了している前提で進めます。インストール手順については前回記事をご参照ください。

https://techblog.beex-inc.com/entry/2026/03/31/153834

記事のまとめ

  • Azure OpenAIとAzure Cognitive Servicesは、エンドポイントURL形式と対応サービス範囲が異なる
  • OpenCodeの/connectコマンドでAPIキーを登録し、環境変数でリソース名を渡すことで接続できる

Azure OpenAI と Azure Cognitive Services の違い

OpenCodeでは、Azureプロバイダーとして「Azure OpenAI」と「Azure Cognitive Services」の2種類が用意されています。 どちらもAzure上にデプロイしたOpenAIモデル（GPT-4o、GPT-4.1等）を利用できますが、接続先のエンドポイントが異なります。

項目 Azure OpenAI Azure Cognitive Services
エンドポイント形式 https://<リソース名>.openai.azure.com/ https://<リソース名>.cognitiveservices.azure.com/
環境変数名 AZURE_RESOURCE_NAME AZURE_COGNITIVE_SERVICES_RESOURCE_NAME
対象サービス Azure OpenAI Service専用 Azure Cognitive Services（マルチサービス）配下のOpenAI
OpenCodeでの選択名 Azure Azure Cognitive Services

補足 Azure OpenAI Serviceのリソースを単独で作成した場合は「Azure」を、 Cognitive Servicesのマルチサービスリソースとして作成した場合は「Azure Cognitive Services」を選択してください。 Azureポータルでリソースのエンドポイントを確認し、URLの形式で判断できます。

本記事では、「Azure」プロバイダーでの接続手順を中心に解説します。

実装前の準備（前提条件）

今回の実装のために、以下の準備が必要です。

  • OpenCode インストール済み
    • WSL2（Ubuntu）上にOpenCodeがインストールされていること
  • Microsoftアカウント / Azureアカウント
    • Azureポータルにログインできること
    • Azure OpenAI Serviceを利用可能なサブスクリプションがあること

実装手順

以下ステップで実装を進めていきます。

実装手順1：Azureリソースの準備

Azure OpenAI Serviceのリソースを作成し、APIキーを取得します。

作業パス：ブラウザ（Azureポータル）

前提条件：Azureアカウントでログイン済みであること

Azure OpenAI リソースの作成

  1. Azureポータルにログインします

  2. 上部の検索バーで「Azure OpenAI」を検索し、「Azure OpenAI」を選択します

  3. 「作成」ボタンを押します

リソースタイプの選択：Azure AI Foundry か Azure OpenAI か

「作成」を押すと、以下2つの選択肢が表示されます。

選択肢 特徴
Azure AI Foundry 新しい統合プラットフォーム。Foundryリソース+プロジェクトが自動作成される。エージェント構築・評価・監視など多機能だが、付随リソースが増えコストも増加しやすい
Azure OpenAI 従来の単独リソース。OpenAIモデルのAPI利用に特化。シンプルな構成。

今回は「Azure OpenAI」の「作成」を選択します。

基本タブの設定

「基本情報」タブで以下を設定します。

項目 設定内容 補足
サブスクリプション 利用するAzureサブスクリプション -
リソースグループ 既存または新規作成 -
リージョン 利用したいモデルが提供されているリージョン モデルごとに提供リージョンが異なるため注意2。執筆時点で最新モデルが提供されているEast US 2を設定します
名前 任意のリソース名 エンドポイントURL（https://<名前>.openai.azure.com/）の一部になる
価格レベル Standard S0 現時点で選択可能なレベルはStandard S0のみ

設定後、「次へ」を選択します。

ネットワークタブの設定（セキュリティ）

「ネットワーク」タブでは、リソースへのアクセス経路を制限できます。3つのオプションがあります。

オプション 内容 推奨度
すべてのネットワーク インターネット含む全ネットワークからアクセス可能（デフォルト） 手軽だがセキュリティは最も低い
選択したネットワークのみ 指定したVNet/サブネット・IPアドレスからのみアクセス許可 -
無効化 全ネットワークアクセスを遮断し、プライベートエンドポイント経由のみ 最もセキュアだが、VPNやExpressRoute等の構成が必要でコスト増

補足 個人利用の検証環境では「選択したネットワークのみ」を選択し、 ファイアウォールの「アドレス範囲」に自宅のグローバルIPアドレスを追加する方法がバランスが良いかと思います。

注意 「すべてのネットワーク」を選択した場合、APIキーさえあればどこからでもアクセス可能になるのでご注意ください。

設定後、「次へ」を選択します。

タグ・確認タブ

  • タグ：任意
  • 確認と送信：設定内容を確認し、「作成」を選択

デプロイが完了すると「リソースに移動」ボタンが表示されるので選択します。

APIキーとエンドポイントの確認

リソース作成後、以下の情報を確認しメモしておきます。

  1. 作成したリソースの画面で、「キーの管理」を選択します
  2. 以下の情報を控えます
    • キー 1（または キー 2）：OpenCodeに登録するAPIキー
    • エンドポイント：https://<リソース名>.openai.azure.com/ の形式

      注意 APIキーは機密情報です。外部に漏洩しないよう注意してください。 キー 1とキー 2のどちらを使用しても構いません。ローテーション運用を想定した2キー構成になっています。

実装手順2：Microsoft Foundryでモデルをデプロイ

作成したAzure OpenAIリソースにモデルをデプロイします。

作業パス：ブラウザ（Microsoft Foundry）

前提条件：実装手順1のリソース作成が完了していること

モデルのデプロイ

  1. Microsoft Foundryにアクセスし、サインインします

  2. ポータル上部のトグルで「New Foundry」がオフになっていることを確認します

  3. 「Foundryを使用してビルドを続ける」セクションで「すべてのリソースを表示」を選択します

  4. 実装手順1で作成したAzure OpenAIリソースを見つけ、選択します

  5. 「概要」タブの「モデルカタログ」からデプロイしたいモデルを選択します

  6. 「▶ このモデルを使用する」を選択します

  7. デプロイの構成画面で、「AI リソース」で作成したAzure OpenAIリソースを選択されていることを確認します。

  8. 「デプロイ」を選択します。プロビジョニング状態が「成功」になればデプロイ完了です

重要 デプロイ名はモデル名と一致させてください。OpenCodeがモデルを正しく認識するために必要です[^1]。

実装手順3：環境変数の設定

Azure OpenAIのリソース名を環境変数として設定します。

作業パス：WSL2（Ubuntu）内のホームディレクトリ ~

前提条件：実装手順1が完了していること（リソース名を控えてあること）

注意 この環境変数の設定は、次の実装手順4で /connect コマンドを実行する前に完了させる必要があります。 環境変数が未設定の状態で /connect を実行すると、以下のエラーが発生します。 AI_LoadSettingError: Azure OpenAI resource name setting is missing. Pass it using the 'resourceName' parameter or the AZURE_RESOURCE_NAME environment variable.

環境変数の設定方法

方法1：bash profileに追記する

永続的に環境変数を設定する場合は、~/.bashrc または ~/.bash_profile に追記します。

echo 'export AZURE_RESOURCE_NAME=<リソース名>' >> ~/.bashrc
source ~/.bashrc

<リソース名> には、実装手順1で確認したリソース名を指定します。

エンドポイントが https://my-openai-resource.openai.azure.com/ の場合、リソース名は my-openai-resource です。

方法2：OpenCode起動時に指定する

一時的に利用する場合は、OpenCode起動時に環境変数を渡すこともできます。

AZURE_RESOURCE_NAME=<リソース名> opencode

環境変数の確認

設定が正しく反映されているか確認します。

echo $AZURE_RESOURCE_NAME

リソース名が表示されれば設定完了です。

実装手順4：OpenCodeでAzureプロバイダーに接続

OpenCodeの /connect コマンドを使い、Azure OpenAIのAPIキーを登録します。

作業パス：WSL2（Ubuntu）内の任意のプロジェクトディレクトリ

前提条件：実装手順1〜3が完了していること（環境変数 AZURE_RESOURCE_NAME が設定済みであること）

OpenCodeの起動

WSLターミナルからOpenCodeを起動します。

opencode

/connect コマンドでAPIキーを登録

OpenCodeのTUI画面で、/connect コマンドを入力します。

/connect

プロバイダー一覧が表示されるので、「Azure」を選択します。

補足 Azure Cognitive Servicesを利用する場合は、「Azure Cognitive Services」を選択してください。

APIキーの入力を求められるので、実装手順1で控えたキー1（またはキー 2）を貼り付けます。

補足 入力されたAPIキーは ~/.local/share/opencode/auth.json に保存されます[^1]。

実装手順5：OpenCodeの起動とモデル選択

設定が完了したら、OpenCodeを起動してAzure OpenAIのモデルを選択します。

作業パス：作業対象プロジェクトのルートディレクトリ

前提条件：実装手順1〜4が完了していること

OpenCodeの起動

WSLターミナルからOpenCodeを起動します。

opencode

モデルの選択

OpenCodeが起動したら、/models コマンドを入力します。

/models

モデル一覧が表示されるので、Azure OpenAIプロバイダーのモデル（デプロイしたモデル名）を選択してEnterを押します。

動作確認

モデルを選択後、任意のプロンプトを入力して応答が返ってくることを確認します。

正常に応答が返れば、Azure OpenAIとの連携は完了です。

備考など

  • リージョン選択の注意：利用したいモデルがすべてのリージョンで提供されているとは限りません。モデルの提供状況はMicrosoft FoundryまたはAzure公式ドキュメントで確認してください

参考URL

この記事で参考にしたURLです。

https://opencode.ai/docs/providers/#azure-openai

https://learn.microsoft.com/ja-jp/azure/ai-services/openai/how-to/create-resource

  1. OpenCode公式ドキュメント - Providers↩
  2. Microsoft公式ドキュメント - Azure OpenAI リソースの作成とデプロイ↩

© BeeX Inc. All rights reserved.