3行でいうと

  • AI Gateway経由で他社のAIを呼ぶとき、提供元への認証は「Unified Billing」「BYOK」「リクエストのヘッダー」の3通りです。ゲートウェイ自体も、認証つきにできます。
  • 「AI Gateway Run」の権限のトークンは、1つのゲートウェイに限定できず、アカウントの全ゲートウェイ（BYOKの鍵を保存したものを含む）を使える、と公式が明記しています。
  • ゲートウェイのログは既定でオンです。他社に送った内容は、その会社の規約で扱われる可能性がある、と公式のWorkers AIのData usageのページは書いています。
  • OpenAI互換の口は、ベースURLと apiKey（CloudflareのAPIトークン）を差し替える形です。Responsesの口は2つのモデルだけで、ストリーミングなしです。
  • Agentが外のMCPサーバーにつなぐには、コードで addMcpServer() を呼びます。外すのは removeMcpServer() です。

この記事は、公式の資料を2026年10月25日に読んでまとめたものです。この記事は、実際に使って確かめた記録ではありません。設定例は「公式の例の写し」と書いたものだけが公式のままで、ほかは「この記事で組んだ例（動作は確かめていません）」です。画面の表記は変わることがあるので、手元の画面と照らして読んでください。OpenAI、Anthropicなどは、Cloudflareとは別の会社で、それぞれの設定画面や規約は、この記事では読んでいません。ゲートウェイの作り方は05の段階7、curlの基本形は06の場面3にあります。

先に結論

前提：用語をそろえる

連携E：自分のアプリから、AI Gateway経由でOpenAIやAnthropicを呼ぶ（公式）

E-1 提供元への認証は3通り（公式の「Get started」）

方法 公式の説明（要約） 使える提供元の記述
Unified Billing 前払いのAI Gatewayクレジットを、Workers AIと対応する他社に使う OpenAI、Anthropic、Google AI Studio、Google Vertex AI、xAI、Groq（提供元ごとの口の場合）
BYOK（Store Keys） 自分の他社APIキーをCloudflareに保存し、実行時にAI Gatewayが付ける 提供元ごとの口
リクエストのヘッダー 自分で提供元のキーを送る（例：Authorization: Bearer <OPENAI_API_KEY>） ――

Unified Billingのページが書く、認証の順番（優先）：リクエストにある提供元のキー、次に default の別名で保存したBYOKのキー、最後にUnified Billing。他の別名のキーは、Unified Billingの口ではこの切り替えを止めない、と書かれています。提供元のキーが無いときにUnified Billingへ切り替わるのを止めたい場合は、Settings の Require provider credentials をオンにするか、APIで byok_only: true を送る、と書かれていて、キーの無いリクエストは 400 になります（この設定はWorkers AIには影響しません）。

E-2 Unified Billingを使う（公式の順）

クレジットを入れる：

  1. ダッシュボードの AI > AI Gateway。
  2. 右上の Credits Available のカードで Manage を選ぶ。
  3. 求められたら、支払い方法を追加する。
  4. Top-up credits を選ぶ。
  5. 金額を入れて Confirm and pay。

自動のチャージ：Manage > Setup auto top-up credits で、しきい値と補充額を決めます。

使う前の条件（公式）：十分なクレジット、ゲートウェイの認証（E-4）、Workers AIを使うなら、ゲートウェイの Workers AI Billing を Unified billing にすること。

呼び方（公式の例の写し）。Workerから：

const resp = await env.AI.run(
    "openai/gpt-4.1-mini",
    {
        messages: [{ role: "user", content: "What is Cloudflare?" }],
    },
    {
        gateway: { id: "my-gateway" },
    },
);

REST APIからは、06の場面3-2のcurl（"model": "openai/gpt-4.1-mini"）と同じ形です。提供元ごとの口を使うときは cf-aig-authorization のヘッダーを使う、と書かれています。

公式が書く、お金とデータの注意：クレジットの購入には手数料がかかる（率は公式の「Unified Billing」のページで確認）／残高がマイナスになると、登録した支払い方法に請求される（毎月の月初に、前月分）／ゲートウェイごとに、モデル・提供元・ユーザーなどの区切りで支出の上限ルールを設けられる／Zero Data Retentionは、Cloudflareが管理する認証情報を使うUnified Billingのリクエストにだけ適用され、AI Gatewayのログの設定は別に決める。

E-3 BYOK：自分のキーを預ける（公式の「Bring your own keys」）

  1. ダッシュボードにログインし、アカウントを選ぶ。
  2. AI > AI Gateway。
  3. ゲートウェイを選ぶ（なければ作る）。
  4. Provider Keys のセクションを開く。
  5. Add API Key。
  6. 提供元を、プルダウンから選ぶ。
  7. キーを入れ、必要なら説明を書く。
  8. Save。

公式の記述：キーはSecrets Storeに保存される（公式の表現は「stored securely with Secrets Store」）と書かれています（暗号化かどうかの明記は、読んだ範囲ではありません）。リクエストは、別名を指定しなければ default を使い、別の別名は cf-aig-byok-alias のヘッダーで選びます。コード側の提供元のキーや認証ヘッダーは消します（プレースホルダのままだと認証エラーになる、と書かれています）。cf-aig-authorization は引き続き必要です。別名のヘッダーは、提供元の口へ直接渡す形のリクエストだけで使えます。

例（公式の例の写し）：

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [...]}'

別の別名を使うときは cf-aig-byok-alias のヘッダーで別名を渡す、と公式は文章で説明しています。この記事は、上の公式の例に別名のヘッダーを足した例は載せません。ヘッダーの書き方は公式ページで確認してください。

キーの入れ替え：提供元で新しいキーを作り、ダッシュボードで該当のキーを編集して置き換えて保存します。アプリはすぐ新しいキーに切り替わり、コードの変更や停止は要らない、と書かれています。削除：ダッシュボードでキーを見つけ、Delete を選んで確認します。そのキーに頼るリクエストは、すぐに止まります。先に別のキーを足すか、アプリを更新します。

条件と注意：ゲートウェイは認証つきである必要があり、Secrets Storeの権限が要ります。APIでキーを作る場合は、秘密の名前を {gateway_id}_{provider_slug}_{alias} の形にする決まりがあります（例：my-gateway_anthropic_default）。

E-4 ゲートウェイを認証つきにする（公式の「Authentication」）

  1. ゲートウェイの設定を開く。
  2. Create authentication token。トークンには Run の権限が要り、二度と表示されないので保管する。
  3. 各リクエストにトークンを付ける。
  4. 設定に戻り、Authenticated Gateway をオンにする。

付けるヘッダー：api.cloudflare.com のREST APIでは Authorization: Bearer（公式は新しい連携にはこちらと書く）、gateway.ai.cloudflare.com の提供元ごとの口では cf-aig-authorization。オンでヘッダーなしだと、リクエストは失敗します（missing authorization）。同じアカウントのWorkerのバインディング経由は、あらかじめ認証済みです。AI Gateway Run は1つのゲートウェイに限定できないので、このトークンを持つ人は、BYOKの鍵を保存したゲートウェイを含め、アカウントの全ゲートウェイを使えます（分けるなら別のアカウントかWorkerのバインディング、と公式は書く）。

E-5 Anthropicを、提供元ごとの口で呼ぶ（公式の「Anthropic」のページ）

口：https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/anthropic。ヘッダー：x-api-key（Anthropicのキー。BYOKかUnified Billingのときは付けない）、cf-aig-authorization: Bearer {CF_AIG_TOKEN}、anthropic-version: 2023-06-01。

公式の例の写し（モデル名は公式の例のものです。モデル名は変わるので、公式のページで確かめてください）：

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/anthropic/v1/messages \
 --header 'x-api-key: {anthropic_api_key}' \
 --header 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
 --header 'anthropic-version: 2023-06-01' \
 --header 'Content-Type: application/json' \
 --data  '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What is Cloudflare?"}
    ]
  }'

公式のページには、AnthropicのSDKの例も載っています。同じページの中で、curlの例は cf-aig-authorization、SDKの例は defaultHeaders の Authorization: Bearer {cf_api_token} と、ゲートウェイの認証のヘッダーの書き方が違います（E-4の説明と合わせて、手元で確かめてください）。BYOKかUnified Billingのときは、SDKの defaultHeaders に x-api-key を入れると失敗する、とも書かれています。

E-6 何が渡るか／外し方／確認点

項目 内容
渡るデータ アプリからの入力と、モデルの出力が、ゲートウェイを通って提供元に渡ります。ゲートウェイのログは既定でオン（06の場面3-4）。提供元に送った内容は、その会社の規約で扱われる可能性がある（Workers AIのData usageのページ）
渡る権限 提供元のキー（BYOKならCloudflareが保存、ヘッダーなら自分で送る）。ゲートウェイを呼ぶためのトークン
外す BYOKのキーは Delete、Unified Billingは「Require provider credentials」で切り替えを止める、認証は Authenticated Gateway をオフ。ゲートウェイそのものの削除は、読んだページに記載が見つからない
確認点 cf-aig-authorization と Authorization のどちらを使う口か、BYOKでキーのヘッダーを残していないか、default の別名か、ゲートウェイ名、Workers AIのモデルに cf-aig-gateway-id があるか、クレジット残高

連携F：OpenAI互換のコードから、Workers AIを呼ぶ（公式の「OpenAI-compatible API endpoints」）

ベースURL：https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1。口は次のとおりです。

口 公式の説明
/v1/chat/completions 多くの文章生成モデル
/v1/embeddings 埋め込み（意味の数値化）のモデル
/v1/responses @cf/openai/gpt-oss-120b と @cf/openai/gpt-oss-20b だけ。ストリーミングなし（stream: false のみ）

同期のChat Completionsでは、リクエスト本文の最上位に options.rejectIfBusy を入れると、容量待ちの列で待たずに失敗させられます（未知の項目を落とすクライアントでは無視される、と書かれています）。AI Gatewayとも互換、と書かれています。

OpenAIのSDKでの書き方（公式の例の写し）：

import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: env.CLOUDFLARE_API_KEY,
    baseURL: `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/ai/v1`,
});

const chatCompletion = await openai.chat.completions.create({
    messages: [{ role: "user", content: "Make some robot noises" }],
    model: "@cf/meta/llama-3.1-8b-instruct",
});

連携G：CloudflareのAgentが、外のMCPサーバーを使う（公式の「MCP client API」）

公式のページによると、Agentのコードから addMcpServer() で外のMCPサーバーをつなぎます（公式の例の写し）。

await this.addMcpServer("notion", "https://mcp.notion.so/mcp");

OAuthのあるサーバーでは、callbackHost を付けられます（公式の例では "https://my-worker.workers.dev"）。戻り値は、ready（ツール発見済み）か authenticating（authUrl へ利用者を誘導）です。接続はエージェントのSQL保存領域に残り、起きると復元されます。OAuthのトークンの保存については、公式のページで確認できていません。公式のページが書いているのは、MCPサーバーの登録が再起動後も残る、という点です。

認証つきのサーバーは、transport の headers に渡します（公式の例の写し。値は置き換え用の文字です）。

await this.addMcpServer("internal", "https://internal-mcp.example.com/mcp", {
    transport: {
        headers: {
            Authorization: "Bearer <TOKEN>",
            "CF-Access-Client-Id": "<ID>",
            "CF-Access-Client-Secret": "<SECRET>",
        },
    },
});
項目 公式の記述
ツールの一覧 this.mcp.listTools()。AI SDKに渡すなら this.mcp.getAITools()
外す await this.removeMcpServer(serverId);。接続を切り、保存した登録を消す
同じ名前とURLで再度呼ぶ 既存の接続が返る（重複しない）。同じ名前で別のURLは、新しい接続になる。置き換えるなら、先に古いIDを removeMcpServer() する
接続先の制限 プライベート、リンクローカル、クラウドのメタデータのアドレスは、SSRF対策で拒否。ローカル開発のループバックは許可
社内サービス 本番の社内サービスには、HTTPでなくDurable ObjectのバインディングによるRPC転送を使うよう、公式は書く
入力の取得 フォーム形式で、秘密の値を集めてはいけない、と書かれている

渡るデータは、Agentが呼ぶ外のMCPサーバーのツールの入出力です。渡るトークンやヘッダーは、Agentのコードが決めます。

渡るデータのまとめ（この記事の連携）

連携 渡る先 渡る内容 公式の記述の有無
E OpenAI、Anthropic等 プロンプトと応答 提供元の規約で扱われる可能性（Workers AI Data usage）
E Cloudflareのログ プロンプト、応答など（既定でオン） 止め方あり（06の場面3-4）
F Cloudflare（Workers AI） 入力と出力 Workers AIのData usage（01・04）
G 外のMCPサーバー ツールの入出力、認証ヘッダー Agentのコードで決まる

MCPサーバーを外のAIにつなぐ連携（A〜D）のデータは、07にあります。

つまずきと直し方

症状 公式に書かれている原因・直し方
ゲートウェイ経由で、認証エラー 認証つきゲートウェイならヘッダーが要る。口によって Authorization か cf-aig-authorization（E-4）
BYOKにしたのに失敗 コードに提供元のキーのプレースホルダが残っていないか。cf-aig-authorization は必要（E-3）
他社のモデルを呼べない クレジット残高、Require provider credentials の設定、キーの別名（E-1・E-2）
Workers AIのモデルがゲートウェイ経由で失敗する cf-aig-gateway-id が常に必要（06の場面3-1）
Agentの addMcpServer() が別の接続を作る 同じ名前で別のURLは新しい接続になる。置き換えるなら先に古いIDを removeMcpServer()（連携G）

気をつけること

出典