3行でいうと

  • 入口は2つあります。ブラウザのダッシュボード（アカウント作成、トークン作成、AI Gatewayの設定）と、ターミナルの wrangler（ログイン、公開、ログの確認）です。
  • アカウントは、公式の手順ではメールアドレスとパスワードで作ります。Wranglerは、公式が recommend と書く方法で、プロジェクトごとに npm i -D wrangler@latest で入れます。
  • サインインの方法は2つあります。wrangler login（ブラウザで許可）と、APIトークンを環境変数に入れる方法（自動化向けと公式が書く）です。
  • APIトークンは、公式の画面で「権限グループ」「Read/Edit」「対象のリソース」「IPの制限」「有効期限」を選べます。この記事では、AI関連の用途ごとに、公式のページに名前が出ていた権限を表にしました。
  • 秘密の値（トークンなど）は、この記事ではすべて <API_TOKEN> のような置き換え用の文字で書いています。実際の値は、画面に出たものを自分で保管します。

この記事は、公式の資料を2026年10月25日に読んでまとめたものです。この記事は、実際に使って確かめた記録ではありません。手順は「公式の手順を順に並べたもの」で、画面名・ボタン名は公式ページの表記です。画面の表記は変わることがあるので、手元の画面と照らして読んでください。公式ページは要約の形で取得したため、読み切れていない箇所は「公式で確認できていない」「記載が見つからない」と書きます。

先に結論

前提：用語をそろえる

段階1：アカウントを作る（公式の「Create account」の手順）

  1. ブラウザで、公式の手順に出てくるサインアップのページ https://dash.cloudflare.com/sign-up を開きます。
  2. Email と Password の欄に、メールアドレスとパスワードを入れます。
  3. Create Account を選びます。
  4. 作成後、Cloudflareは入力したアドレスに確認のメールを自動で送ると、公式は書いています。メールの案内に沿ってアドレスを確認します（確認の細かい手順は、別の公式ガイドへのリンクがあるだけで、この記事では読めていません）。

公式のこのページに書かれていないこと：2段階認証、クレジットカードの要否、ドメインの要否（記載が見つからない）。

そのほか、アカウント名の初期値は <メールアドレス>'s Account で、Configurations のページの Change Name から変えられると公式は書いています。

段階2：Node.jsとWranglerを入れる

対応しているものと前提（公式の「Install/Update Wrangler」）

項目 公式の記述
必要なもの Node.jsとnpm
Node.jsの版 「Current、Active、Maintenance」の各リリース系列に対応と書かれていますが、具体的な版の数字は、読んだページには載っていません
対応OS macOS 13.5以降、Windows 11、glib 2.35に対応するLinuxディストリビューション
入れ方の考え方 公式は、プロジェクトごとにローカルで入れることを recommend と書く（チームで版をそろえられる、版の固定や戻しをプロジェクトごとにできるため、という趣旨）。グローバルに入れるコマンドは、読んだページには載っていません
Node.jsの版の管理 ページは Vite+ の vp env で版を入れて管理できる、と書いています（ほかの方法は、読んだページでは確認できていません）

Node.js自体のインストール手順（macOS・Windows・Linuxごとの入手先と操作）は、Wranglerの公式ページには書かれていません。Node.jsの公式の資料はこの記事では読んでいないため、ここでは書きません。

手順：プロジェクトの中にWranglerを入れる（OS共通）

  1. ターミナルを開き、使うプロジェクトのフォルダに移動します。まだプロジェクトがない場合は、06の場面2（npm create cloudflare@latest -- hello-ai）で雛形ごと作れます。
  2. 次のコマンドを実行します（公式のコマンドの写し）。
npm i -D wrangler@latest
  1. 公式のページは、yarn、pnpm、bunのタブも用意していると書いていますが、そのコマンドは取得した内容に含まれていませんでした。npm以外を使うときは、公式ページで確認してください。
  2. 版を確かめます（公式の写し）。どちらでも同じ意味です。
npx wrangler --version
npx wrangler -v

期待される結果：Wranglerの版番号が表示されます（具体的な番号は、時期によって変わるため、この記事には書きません）。

更新と、入れていないとき

段階3：Wranglerでサインインする

手順A：ブラウザでログインする（wrangler login）

  1. ターミナルで、次のコマンドを実行します。
npx wrangler login
  1. Wranglerは、手元に一時的な受け取り口（初期値は localhost:8976）を立て、CloudflareのOAuthのリンクをブラウザで開きます。--browser=false を付けると、ブラウザを開かずにリンクが表示されます（公式の説明）。ブラウザが開かなかったときの対処を公式がどう書くかは、読んだ範囲では確認できていません。
  2. ブラウザでCloudflareにログインします。公式のWorkers AIの手順では、続けて、Wranglerがアカウントに変更を加えることを許可するため Allow を選ぶ、と書かれています。
  3. ログインが終わるとブラウザは手元の受け取り口に戻り、Wranglerがそれを受け取ります。

期待される結果：ブラウザで Allow を選ぶとログインが進む、と公式は書いています。ターミナルに出る表示の文言は、読んだページには載っていません。npx wrangler whoami で確かめられます（手順C）。

主なオプション（公式の wrangler login の説明）：

オプション 公式の説明（要約）
--scopes-list 使える権限（OAuthのスコープ）と説明を一覧する
--scopes 空白区切りで権限を指定する。例：npx wrangler login --scopes account:read user:read
--browser=false ブラウザを開かず、リンクを表示する（初期値は true）
--callback-host / --callback-port 受け取り口の場所と番号（初期値は localhost と 8976）。--device とは併用できない
--use-keyring / --no-use-keyring 認証情報を、平文のTOMLファイルではなくOSのキーチェーンに保存する／しない
--device OAuth 2.0のDevice Authorization Grant（RFC 8628）の方式を使う（初期値は false）

権限の指定がないとき、Wranglerは「使える権限のすべて」を求める、と公式は書いています。権限を絞って渡したいときは、--scopes-list で中身を見て --scopes で指定します（スコープの名前そのものは、読んだページには載っていないため、この記事には書きません）。

手順B：リモートのマシン・コンテナでログインする

公式は、ブラウザのログインを別のマシンで行うと、戻り先の localhost に着かず「This site can't be reached」と出ると書いています。直し方は2つ書かれています。

npx wrangler login --device

Wranglerが確認用のURLと短いコードを表示し、ブラウザでURLを開くとコードが入った状態になります。許可の待ち受けは最長5分、と書かれています。ブラウザを開かずURLだけ欲しいときは、npx wrangler login --device --browser=false です。

コンテナでは、ポート8976を渡して --callback-host=0.0.0.0 を付ける方法と、--device を使う方法が書かれています（公式の例の全文は公式ページで確認）。

手順C：自分が誰でログインしているか確かめる／ログアウトする

手順D：環境変数で認証する（自動化向け）

公式の「環境変数」のページには、認証に使う変数として次が書かれています。

変数 公式の説明（要約）
CLOUDFLARE_API_TOKEN 認証用のAPIトークン。CI/CDなどの自動化に便利と書かれている
CLOUDFLARE_ACCOUNT_ID Workers関連のアカウントのID
CLOUDFLARE_API_KEY と CLOUDFLARE_EMAIL 古い方式の認証（組で使う）
CLOUDFLARE_ACCESS_CLIENT_ID と CLOUDFLARE_ACCESS_CLIENT_SECRET Cloudflare Accessのサービストークンの組
CLOUDFLARE_AUTH_USE_KEYRING true / false。wrangler login のキーチェーン設定を、その1回だけ上書きする

プロジェクトのフォルダに .env ファイルを置く方法も、公式は書いています。値が次回以降も残るため、この方法を公式が recommend と書きます。環境ごとの .env.<environment-name> も使え、--env を付けるとそちらが読まれ、.env とは混ぜられません。なお、.env をバージョン管理に入れてよいかどうかは、そのページには書かれていません。トークンの値を入れるファイルなので、共有や公開の範囲は自分で決めてください（これはこの記事の補足で、公式の文ではありません）。

段階4：APIトークンを作る（ダッシュボード）

先に：ユーザートークンとアカウントトークン

種類 公式の説明（要約） 作る場所（公式の記述）
ユーザートークン 特定のユーザーのために動き、そのユーザーの権限の一部を引き継ぐ。その場の作業やスクリプト向けと書かれている My Profile > API Tokens
アカウントトークン（Account API token） 「独自の権限をもつサービスの主体」として動く。CI/CDなど長く使う連携向けで、設定した人が抜けても動き続けると書かれている Manage Account > API Tokens（トークン作成のページの表記）、または Manage account > Account API tokens（アカウント所有トークンのページの表記）

2つのページで、アカウントトークンの画面名の書き方が少し違います（「API Tokens」と「Account API tokens」）。どちらかに決めつけず、手元の画面と照らしてください。

アカウントトークンについて、公式が書いていること：作るには API Token Provisioning の権限かSuper Administratorが要る／作る人は、自分が持つ権限の範囲内でしか権限を渡せない／Super Administratorはアカウントの全トークンを管理でき、それ以外の人は自分が作ったトークンだけ管理できる／一部の製品はまだ対応していない（Page Rules、Registrar、Turnstileなど。一覧は公式ページで確認）。AI関連の製品が対応外かどうかは、読んだ範囲では一覧に出ていませんでした。

手順：ダッシュボードでトークンを作る（公式の「Create API token」の順）

  1. 公式は、先にゾーンIDとアカウントIDを見つけることを前提にしています（段階5を参照）。
  2. トークンの種類（ユーザーかアカウントか）を決めます。
  3. 上の表の場所で、API Tokensのページを開きます。
  4. Create Token を選びます。
  5. テンプレートを選ぶか、カスタムトークンを作ります。公式の例は Edit zone DNS のテンプレートです。テンプレートは、名前と権限があらかじめ入っています。Workers AIには、06の場面1で書くとおり、専用のテンプレート（Create a Workers AI API Token）が別の入口にあります。
  6. トークンに、用途が分かる名前を付けます。
  7. 権限を決めます。権限グループ（Account、User、Zone）を選び、アクセスの度合いを選びます。Edit は作成・読み取り・更新・削除・一覧のすべて、Read は読み取り（と、適用できる場合は一覧）と、公式は説明しています。
  8. 対象のリソースを選びます。公式の例は、Zone DNS Read を example.com だけに付けると、そのゾーンのDNSだけ読め、ほかのゾーンや操作はエラーになる、というものです。
  9. （任意）Client IP Address Filtering（使える接続元のIPの制限）と TTL（有効期間）を入れます。
  10. Continue to summary を選び、要約を見ます。直したいときは Edit token です。作成後に編集もできます。
  11. Create Token を選ぶと、秘密の値が表示されます。
  12. その値をコピーして、他人に見えない場所に保管します。公式は、秘密の値は一度しか表示されないこと、他の人が読める平文の場所には置かないこと、トークンがあれば誰でもその権限の操作ができることを警告しています。

トークンの先頭の文字について、公式のページは次のように書いています（2つのページで書き方が違うため、併記します）。トークン作成のページは「新しいAPIトークンは cfut_ で始まる、スキャンしやすい形式」と書き、ユーザートークンとアカウントトークンのどちらに付くかは書いていません。アカウント所有トークンのページは「新しいアカウントトークンは cfat_ で始まる形式」と書きます。どちらも、漏れた値を探す道具が見つけやすくなるため、という趣旨です。

手順：作ったユーザートークンが有効か確かめる（公式の例）

<API_TOKEN> を、保管した値に置き換えます（公式のコマンドの写し）。

curl "https://api.cloudflare.com/client/v4/user/tokens/verify" \
--header "Authorization: Bearer <API_TOKEN>"

期待される結果：JSONの中に "status": "active" と、トークンが有効という趣旨のメッセージ（This API Token is valid and active）が入ります。アカウントトークンの確認用のエンドポイントは、読んだページには記載が見つかりませんでした。

トークンの外し方・作り直し

段階5：アカウントIDを見つける（公式の「Find account and zone IDs」）

公式は、ダッシュボードの3か所を書いています。

  1. 検索：アカウントのホームで CMD/CTRL + K を押すか Search を選び、「Copy account ID」と入れて、出た結果を選ぶとコピーされます。
  2. Domains：Domains を開いてドメインを選び、Overview ページを下へ進んだ API の欄に、Zone IDと並んでアカウントIDがあります。
  3. Workers & Pages：Workers & Pages を開き、Account Details の欄の、Account ID の横のコピーボタンを使います。

Workers AIのREST APIの手順（公式）では、Workers AI のページで Use REST API を選ぶと、Account ID の値も表示されます（06の場面1）。

段階6：権限を「用途の分だけ」にする

読んだ範囲では、公式のトークン作成のページに「最小権限（least privilege）」という語は見つかりませんでした。ただ、権限グループとRead/Editの選択、対象を特定のアカウントやゾーンに絞ること、IPの制限とTTLの任意設定、という作りになっています。次の表は、公式のページに権限の名前が出ていた用途を並べたものです。この記事で組んだ整理（公式の表ではありません）で、実際の権限名と必要な組み合わせは、手元の画面と公式の各ページで確かめてください。

用途 公式のページに書かれた権限 出どころ
Workers AIをREST APIで呼ぶ（テンプレートを使わず自分で作るとき） Workers AI - Read と Workers AI - Edit の両方 Workers AIの「REST API」の手順
AI GatewayをAPIで作る AI Gateway - Read、AI Gateway - Edit（最初のリクエストでは Workers AI - Read も） AI Gatewayの「Get started」
認証つきゲートウェイを呼ぶためのトークン Run の権限（権限一覧の名前は「AI Gateway Run」） AI Gatewayの「Authentication」、権限一覧
Workersを公開・管理するAPI 権限一覧に「Workers Scripts Read / Edit」がある（AI専用ではない） 権限の一覧

権限一覧のページは、AI関連の名前として「AI Gateway Read」「AI Gateway Edit」「AI Gateway Run」（アカウント単位のみ）、「Workers AI Read」「Workers AI Edit」を挙げていました。AI Search（旧AutoRAG）のREST APIに必要な権限名は、読んだページでは確認できていません（一覧のページは全体の途中までしか読めていません）。なお、同じ権限一覧のページの別の表には、「Workers AI Write」「Workers Scripts Write」という書き方も出ていました。「Edit」と「Write」が併記されているので、手元の画面の表記で確かめてください。

公式の注意が1つあります。AI Gateway Run は、特定の1つのゲートウェイに限定できません。この権限を持つトークンは、そのアカウントの全ゲートウェイを使え、BYOK（他社の鍵を預ける機能）で鍵を保存したゲートウェイも含まれます。分けたいときは、別のアカウントにするか、Workerのバインディングを使う、と公式は書いています。

この記事で組んだ使い分けの案：

段階7：AI Gatewayのゲートウェイを作る（公式の「Get started」）

AI Gatewayを使わない場合は、読み飛ばしてかまいません。

  1. ダッシュボードにログインし、アカウントを選びます。
  2. AI > AI Gateway に進みます。
  3. Create Gateway を選びます。
  4. Gateway name に名前を入れます（64文字まで）。
  5. Workers AI Billing で、次のどちらかを選びます。Standard billing は請求サイクルの終わりにアカウントへ請求、Unified billing は前払いのAI Gatewayクレジットから、その場で差し引かれます。
  6. Create を選びます。

APIでゲートウェイを作る場合は、AI Gateway - Read、AI Gateway - Edit、アカウントID、Cloudflare APIへの POST が要る、と書かれています（リクエストの中身は、この記事では読めていません）。

default という名前のゲートウェイについて、公式の「Get started」は次のように書いています。Workers AIのリクエストに cf-aig-gateway-id: default を付けると、default のゲートウェイを通ります。そのゲートウェイが無ければ、最初の認証つきリクエスト（公式の表現は first authenticated request）で自動的に作られ、請求の方式は Standard billing になります。前払いクレジットで払うには、そのゲートウェイの Workers AI Billing を Unified billing に変えます。他社のモデルでは、ゲートウェイを指定しなくても default が使われ、同じく自動で作られる、とも書かれています。

動作の確かめ方（上から順に）

確認 コマンド・操作 期待される結果
Wranglerが入った npx wrangler --version 版番号が出る
ログインできている npx wrangler whoami ユーザー情報と、認証情報の保存場所が出る（--json もある）
トークンが有効（ユーザートークン） 上のcurl（/user/tokens/verify） "status": "active"
AIが呼べる 06の場面1のcurl JSONの result.response に答えが入る（公式の記述）
ゲートウェイができている AI > AI Gateway の一覧 作った名前が出る

つまずきと直し方

症状 公式に書かれている原因・直し方 書かれていないこと
wrangler login でブラウザが開かない --browser=false でブラウザを開かずリンクを表示できる（公式の説明）。開かないときの対処の書き方は、公式で確認できていない ブラウザの種類ごとの対処
ログイン後「This site can't be reached」 リモートのマシンでログインしているため、localhost に戻れない。--device を使うか、2つ目のターミナルで curl <LOCALHOST_URL> ――
コンテナの中でログインできない ポート8976を渡し、--callback-host=0.0.0.0。または --device ――
ポート8976がふさがっている --callback-port で変え、コンテナなら対応も変える 他のアプリとの競合の調べ方
未ログインのまま自動実行が止まる wrangler whoami --json が0以外の終了コードで終わる。CLOUDFLARE_API_TOKEN を環境変数で渡す方法がある ――
npx wrangler の版が思っていたと違う 入れていないと最新版が使われる。npm i -D wrangler@latest でプロジェクトに入れる 版固定の細かい手順
トークンの値を失くした 秘密の値は一度しか表示されない（公式の警告） 再表示や再発行の画面（読んだページに記載が見つからない）
curlで認証エラーになる トークンの権限不足の可能性。Workers AIを自分で作ったトークンで使うときは、ReadとEditの両方が必要と書かれている エラーコードの意味
ログアウトしたい wrangler logout。APIトークンで認証しているなら、ダッシュボードでそのトークンを削除 ――
認証つきゲートウェイで、ヘッダーなしの呼び出しが失敗する 認証をオンにすると、ヘッダーなしのリクエストは「missing authorization」で失敗する。ただし、同じアカウントのWorkerからのバインディング経由は、あらかじめ認証済み、と公式は書いている ――

たとえ話：入館証を用途ごとに分ける

アカウントは「ビルの入居契約」、wrangler login は「本人確認をして入館証をもらう」こと、APIトークンは「使える部屋と期限を書いた鍵」です。1枚で全部の部屋が開く鍵を避け、用途ごとに分けるイメージです。これは僕らのたとえで、公式の表現ではありません。

気をつけること

出典