# BYOK (独自のキーを持ち込む)

BYOK を使用すると、GitHub Copilot認証をバイパスして、モデル プロバイダーからの独自の API キーで Copilot SDK を使用できます。 これは、エンタープライズ デプロイ、カスタム モデル ホスティング、またはモデル プロバイダーとの直接課金が必要な場合に便利です。

<!-- markdownlint-disable GHD046 GHD005 -->

<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->

## サポートされているプロバイダー

| Provider                       | 型の値           | メモ                                         |
| ------------------------------ | ------------- | ------------------------------------------ |
| OpenAI                         | `"openai"`    | OpenAI API と OpenAI と互換性のあるエンドポイント         |
| Azure OpenAI /Azure AI Foundry | `"azure"`     | Azureホストモデル                                |
| Anthropic                      | `"anthropic"` | クロード モデル                                   |
| Ollama                         | `"openai"`    | OpenAI 互換 API を使用したローカル モデル                |
| マイクロソフト ファウンドリー ローカル           | `"openai"`    | OpenAI 互換 API を使用してデバイス上で AI モデルをローカルで実行する |
| その他の OpenAI 互換                 | `"openai"`    | vLLM、LiteLLM など                            |

## クイックスタート：Azure AI Foundry

Azure AI Foundry (旧称 Azure OpenAI) は、企業向けの一般的な BYOK デプロイ ターゲットです。 完全な例を次に示します。

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

```python
import asyncio
import os
from copilot import CopilotClient
from copilot.session import PermissionHandler

FOUNDRY_MODEL_URL = "https://your-resource.openai.azure.com/openai/v1/"
# Set FOUNDRY_API_KEY environment variable

async def main():
    client = CopilotClient()
    await client.start()

    session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5.2-codex", provider={
        "type": "openai",
        "base_url": FOUNDRY_MODEL_URL,
        "wire_api": "responses",  # Use "completions" for older models
        "api_key": os.environ["FOUNDRY_API_KEY"],
    })

    done = asyncio.Event()

    def on_event(event):
        if event.type.value == "assistant.message":
            print(event.data.content)
        elif event.type.value == "session.idle":
            done.set()

    session.on(on_event)
    await session.send("What is 2+2?")
    await done.wait()

    await session.disconnect()
    await client.stop()

asyncio.run(main())
```

</div>

<div class="ghd-codetab" data-lang="typescript" data-label="TypeScript"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">TypeScript</div>

```typescript
import { CopilotClient } from "@github/copilot-sdk";

const FOUNDRY_MODEL_URL = "https://your-resource.openai.azure.com/openai/v1/";

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-5.2-codex",  // Your deployment name
    provider: {
        type: "openai",
        baseUrl: FOUNDRY_MODEL_URL,
        wireApi: "responses",  // Use "completions" for older models
        apiKey: process.env.FOUNDRY_API_KEY,
    },
});

session.on("assistant.message", (event) => {
    console.log(event.data.content);
});

await session.sendAndWait({ prompt: "What is 2+2?" });
await client.stop();
```

</div>

<div class="ghd-codetab" data-lang="go" data-label="Go"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Go</div>

```golang
package main

import (
    "context"
    "fmt"
    "os"
    copilot "github.com/github/copilot-sdk/go"
)

func main() {
    ctx := context.Background()
    client := copilot.NewClient(nil)
    if err := client.Start(ctx); err != nil {
        panic(err)
    }
    defer client.Stop()

    session, err := client.CreateSession(ctx, &copilot.SessionConfig{
        Model: "gpt-5.2-codex",  // Your deployment name
        Provider: &copilot.ProviderConfig{
            Type:    "openai",
            BaseURL: "https://your-resource.openai.azure.com/openai/v1/",
            WireAPI: "responses",  // Use "completions" for older models
            APIKey:  os.Getenv("FOUNDRY_API_KEY"),
        },
    })
    if err != nil {
        panic(err)
    }

    response, err := session.SendAndWait(ctx, copilot.MessageOptions{
        Prompt: "What is 2+2?",
    })
    if err != nil {
        panic(err)
    }

    if d, ok := response.Data.(*copilot.AssistantMessageData); ok {
        fmt.Println(d.Content)
    }
}
```

</div>

<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

```csharp
using GitHub.Copilot;

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-5.2-codex",  // Your deployment name
    Provider = new ProviderConfig
    {
        Type = "openai",
        BaseUrl = "https://your-resource.openai.azure.com/openai/v1/",
        WireApi = "responses",  // Use "completions" for older models
        ApiKey = Environment.GetEnvironmentVariable("FOUNDRY_API_KEY"),
    },
});

var response = await session.SendAndWaitAsync(new MessageOptions
{
    Prompt = "What is 2+2?",
});
Console.WriteLine(response?.Data.Content);
```

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

```java
import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;

var client = new CopilotClient();
client.start().get();

var session = client.createSession(new SessionConfig()
    .setModel("gpt-5.2-codex")  // Your deployment name
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    .setProvider(new ProviderConfig()
        .setType("openai")
        .setBaseUrl("https://your-resource.openai.azure.com/openai/v1/")
        .setWireApi("responses")  // Use "completions" for older models
        .setApiKey(System.getenv("FOUNDRY_API_KEY")))
).get();

var response = session.sendAndWait(new MessageOptions()
    .setPrompt("What is 2+2?")).get();
System.out.println(response.getData().content());

client.stop().get();
```

</div>

</div>

## プロバイダー構成リファレンス

### ProviderConfig フィールド

| フィールド                                                                                                                                                                           | タイプ | Description                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | -------------------------------------- |
| `type`                                                                                                                                                                          |     |                                        |
| `"openai"`                                                                                                                                                                      |     |                                        |
| \|                                                                                                                                                                              |     |                                        |
| `"azure"`                                                                                                                                                                       |     |                                        |
| \|                                                                                                                                                                              |     |                                        |
| `"anthropic"`                                                                                                                                                                   |     |                                        |
| プロバイダーの種類 (既定値: `"openai"`)                                                                                                                                                     |     |                                        |
| `baseUrl` / `base_url`                                                                                                                                                          | 文字列 |                                        |
| **必須。** API エンドポイント URL                                                                                                                                                         |     |                                        |
| `apiKey` / `api_key`                                                                                                                                                            | 文字列 | API キー (Ollama などのローカル プロバイダーの場合は省略可能) |
| `bearerToken` / `bearer_token`                                                                                                                                                  | 文字列 | ベアラー トークン認証 (apiKey よりも優先されます)         |
| `wireApi` / `wire_api`                                                                                                                                                          |     |                                        |
| `"completions"`                                                                                                                                                                 |     |                                        |
| \|                                                                                                                                                                              |     |                                        |
| `"responses"`                                                                                                                                                                   |     |                                        |
| 広範なモデル互換性 (Chat Completions API) の `"completions"` を選択し、マルチターン状態管理、ツール名の指定、および推論のサポート (Responses API) の `"responses"` を選択します。 Anthropicモデルでは、この設定に関係なく、常に Messages API が使用されます。 |     |                                        |
| `azure.apiVersion` / `azure.api_version`                                                                                                                                        | 文字列 | Azure API バージョン (既定値: `"2024-10-21"`)  |

### Wire API フォーマット形式

`wireApi`設定によって、使用する OpenAI API 形式が決まります。

* **`"completions"`** (既定) - 広範なモデル互換性のためのチャット補完 API (`/chat/completions`)。
* **`"responses"`** - 複数ターンの状態管理、ツール名の指定、および推論のサポートのための応答 API。

Anthropic モデルでは、この設定に関係なく、常に Anthropic Messages API が使用されます。

### 型固有の注記

**OpenAI (`type: "openai"`)**

* OpenAI API と任意の OpenAI 互換エンドポイントで動作します
* `baseUrl` は完全なパスを含める必要があります (例: `https://api.openai.com/v1`)

**Azure (`type: "azure"`)**

* ネイティブ Azure OpenAI エンドポイントに使用する
* `baseUrl` はホスト (例: `https://my-resource.openai.azure.com`) である必要があります
* URL に `/openai/v1` を含めないでください。SDK はパスの構築を処理します

**アントロピック (`type: "anthropic"`)**

* Anthropic API への直接アクセスの場合
* Claude 固有の API 形式を使用します

## 構成例

### OpenAI Direct

```typescript
provider: {
    type: "openai",
    baseUrl: "https://api.openai.com/v1",
    apiKey: process.env.OPENAI_API_KEY,
}
```

### Azure OpenAI (ネイティブ Azure エンドポイント)

`type: "azure"`のエンドポイントに`*.openai.azure.com`を使用します。

```typescript
provider: {
    type: "azure",
    baseUrl: "https://my-resource.openai.azure.com",  // Just the host
    apiKey: process.env.AZURE_OPENAI_KEY,
    azure: {
        apiVersion: "2024-10-21",
    },
}
```

### Azure AI Foundry (OpenAI と互換性のあるエンドポイント)

`/openai/v1/` エンドポイントを使用した Azure AI Foundry デプロイの場合は、次の`type: "openai"`を使用します。

```typescript
provider: {
    type: "openai",
    baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
    apiKey: process.env.FOUNDRY_API_KEY,
    wireApi: "responses",  // For GPT-5 series models
}
```

### Ollama (ローカル)

```typescript
provider: {
    type: "openai",
    baseUrl: "http://localhost:11434/v1",
    // No apiKey needed for local Ollama
}
```

### マイクロソフト ファウンドリー ローカル

[Microsoft Foundry Local](https://foundrylocal.ai) では、OpenAI 互換 API を使用して、独自のデバイスで AI モデルをローカルで実行できます。 Foundry Local CLI を使用してインストールし、ローカル エンドポイントで SDK をポイントします。

```typescript
provider: {
    type: "openai",
    baseUrl: "http://localhost:<PORT>/v1",
    // No apiKey needed for local Foundry Local
}
```

> \[!NOTE]
> Foundry Local は **動的ポート**で開始されます。ポートは固定されていません。
> `foundry service status`を使用して、サービスが現在リッスンしているポートを確認してから、`baseUrl`でそのポートを使用します。

Foundry Local の使用を開始するには:

```bash
# Windows: Install Foundry Local CLI (requires winget)
winget install Microsoft.FoundryLocal

# macOS / Linux: see https://foundrylocal.ai for installation instructions
# List available models
foundry model list

# Run a model (starts the local server automatically)
foundry model run phi-4-mini

# Check the port the service is running on
foundry service status
```

### Anthropic

```typescript
provider: {
    type: "anthropic",
    baseUrl: "https://api.anthropic.com",
    apiKey: process.env.ANTHROPIC_API_KEY,
}
```

### ベアラー トークン認証

一部のプロバイダーでは、API キーの代わりにベアラー トークン認証が必要です。

```typescript
provider: {
    type: "openai",
    baseUrl: "https://my-custom-endpoint.example.com/v1",
    bearerToken: process.env.MY_BEARER_TOKEN,  // Sets Authorization header
}
```

> \[!NOTE]
> `bearerToken` オプションは、**静的トークン文字列**のみを受け入れます。 SDK は、このトークンを自動的に更新しません。 トークンの有効期限が切れると、要求は失敗し、新しいトークンを使用して新しいセッションを作成する必要があります。

## カスタム モデルの一覧

BYOK を使用する場合、CLI サーバーはプロバイダーがサポートするモデルを認識できない場合があります。
`onListModels`がプロバイダーのモデルを標準の`client.listModels()`形式で返すように、クライアント レベルでカスタム `ModelInfo` ハンドラーを指定できます。 これにより、ダウンストリーム コンシューマーは CLI に対してクエリを実行することなく、使用可能なモデルを検出できます。

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="typescript" data-label="TypeScript"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">TypeScript</div>

```typescript
import { CopilotClient } from "@github/copilot-sdk";
import type { ModelInfo } from "@github/copilot-sdk";

const client = new CopilotClient({
    onListModels: () => [
        {
            id: "my-custom-model",
            name: "My Custom Model",
            capabilities: {
                supports: { vision: false, reasoningEffort: false },
                limits: { max_context_window_tokens: 128000 },
            },
        },
    ],
});
```

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

```python
from copilot import CopilotClient
from copilot.client import ModelInfo, ModelCapabilities, ModelSupports, ModelLimits

client = CopilotClient(
    on_list_models=lambda: [
        ModelInfo(
            id="my-custom-model",
            name="My Custom Model",
            capabilities=ModelCapabilities(
                supports=ModelSupports(vision=False, reasoning_effort=False),
                limits=ModelLimits(max_context_window_tokens=128000),
            ),
        )
    ],
)
```

</div>

<div class="ghd-codetab" data-lang="go" data-label="Go"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Go</div>

```golang
package main

import (
    "context"
    copilot "github.com/github/copilot-sdk/go"
)

func main() {
    client := copilot.NewClient(&copilot.ClientOptions{
        OnListModels: func(ctx context.Context) ([]copilot.ModelInfo, error) {
            return []copilot.ModelInfo{
                {
                    ID:   "my-custom-model",
                    Name: "My Custom Model",
                    Capabilities: copilot.ModelCapabilities{
                        Supports: copilot.ModelSupports{Vision: false, ReasoningEffort: false},
                        Limits:   copilot.ModelLimits{MaxContextWindowTokens: 128000},
                    },
                },
            }, nil
        },
    })
    _ = client
}
```

</div>

<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

```csharp
using GitHub.Copilot;

var client = new CopilotClient(new CopilotClientOptions
{
    OnListModels = (ct) => Task.FromResult<IList<ModelInfo>>(new List<ModelInfo>
    {
        new()
        {
            Id = "my-custom-model",
            Name = "My Custom Model",
            Capabilities = new ModelCapabilities
            {
                Supports = new ModelSupports { Vision = false, ReasoningEffort = false },
                Limits = new ModelLimits { MaxContextWindowTokens = 128000 }
            }
        }
    })
});
```

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

```java
import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;
import java.util.List;
import java.util.concurrent.CompletableFuture;

var client = new CopilotClient(new CopilotClientOptions()
    .setOnListModels(() -> CompletableFuture.completedFuture(List.of(
        new ModelInfo()
            .setId("my-custom-model")
            .setName("My Custom Model")
            .setCapabilities(new ModelCapabilities()
                .setSupports(new ModelSupports().setVision(false).setReasoningEffort(false))
                .setLimits(new ModelLimits().setMaxContextWindowTokens(128000)))
    )))
);
```

</div>

</div>

既定の動作と同様に、最初の呼び出しの後に結果がキャッシュされます。 ハンドラーは CLI の `models.list` RPC を完全に置き換えます。サーバーへのフォールバックは発生しません。

## 制限事項

BYOK を使用する場合は、次の制限事項に注意してください。

### ID の制限事項

BYOK 認証では **、静的資格情報のみが使用されます**。

自分で管理する API キーまたは静的ベアラー トークンを使用する必要があります。

### 機能の制限

BYOK では、一部のCopilot機能の動作が異なる場合があります。

* **モデルの可用性** - プロバイダーでサポートされているモデルのみを使用できます
* **Rate limiting** - Copilotではなく、プロバイダーのレート制限に従います
* **Usage tracking** - 使用状況は、GitHub Copilotではなく、プロバイダーによって追跡されます
* **プレミアム リクエスト** - Copilot のプレミアム リクエストのクォータにはカウントされません

### プロバイダー固有の制限事項

| Provider                                           | 制限事項                                                |
| -------------------------------------------------- | --------------------------------------------------- |
| Azure AI Foundry                                   | Entra ID認証なし。API キーを使用する必要があります                     |
| Ollama                                             | API キーがありません。local のみ。モデルのサポートは異なります                |
| [Microsoft Foundry Local](https://foundrylocal.ai) | ローカルのみ。モデルの可用性は、デバイスのハードウェアによって異なります。API キーは必要ありません |
| OpenAI                                             | OpenAI のレート制限とクォータの対象                               |

## Troubleshooting

### "モデルが指定されていません" エラー

BYOK を使用する場合は、 `model` パラメーターが **必要**です。

```typescript
// ❌ Error: Model required with custom provider
const session = await client.createSession({
    provider: { type: "openai", baseUrl: "..." },
});

// ✅ Correct: Model specified
const session = await client.createSession({
    model: "gpt-4",  // Required!
    provider: { type: "openai", baseUrl: "..." },
});
```

### Azure エンドポイントの種類の混乱

Azure OpenAI エンドポイント (`*.openai.azure.com`)は、正しい種類を使用します。

<!-- docs-validate: hidden -->

```typescript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-4.1",
    provider: {
        type: "azure",
        baseUrl: "https://my-resource.openai.azure.com",
    },
});
```

<!-- /docs-validate: hidden -->

```typescript
// ❌ Wrong: Using "openai" type with native Azure endpoint
provider: {
    type: "openai",  // This won't work correctly
    baseUrl: "https://my-resource.openai.azure.com",
}

// ✅ Correct: Using "azure" type
provider: {
    type: "azure",
    baseUrl: "https://my-resource.openai.azure.com",
}
```

ただし、Azure AI Foundryデプロイで OpenAI と互換性のあるエンドポイント パス (例: `/openai/v1/`) が提供される場合は、`type: "openai"` を使用します。

<!-- docs-validate: hidden -->

```typescript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-4.1",
    provider: {
        type: "openai",
        baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
    },
});
```

<!-- /docs-validate: hidden -->

```typescript
// ✅ Correct: OpenAI-compatible Azure AI Foundry endpoint
provider: {
    type: "openai",
    baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
}
```

### 接続が拒否されました (Ollama)

Ollama が実行され、アクセスできることを確認します。

```bash
# Check Ollama is running
curl http://localhost:11434/v1/models

# Start Ollama if not running
ollama serve
```

### 接続が拒否されました (Foundry Local)

Foundry Local は、再起動の間に変更される可能性がある動的ポートを使用します。 アクティブなポートを確認します。

```bash
# Check the service status and port
foundry service status
```

出力に表示されるポートと一致するように `baseUrl` を更新します。 サービスが実行されていない場合は、モデルを使って起動させます。

```bash
foundry model run phi-4-mini
```

### 認証に失敗しました

1. API キーが正しく、有効期限が切れていないかどうかを確認する
2. `baseUrl`がプロバイダーの想定される形式と一致するかどうかを確認する
3. ベアラー トークンの場合は、(プレフィックスだけでなく) 完全なトークンが提供されていることを確認します

## 次のステップ

* [認証](/ja/copilot/how-tos/copilot-sdk/auth) - すべての認証方法について説明します
* [初めてのCopilot搭載アプリを構築する](/ja/copilot/how-tos/copilot-sdk/getting-started) - 初めてのCopilot搭載アプリを構築する