n8nに自分のAPIキーで外部モデルを接続する方法

n8nのAI AgentからOpenAI互換の外部APIを使うには、自分のAPIキーと提供元のBase URLを指定したOpenAI認証情報を作り、OpenAI Chat Modelサブノードで選択します。ただし、提供元がワークフローで使うモデルや機能に対応している必要があります。認証情報の接続テストが通るだけでは十分ではありません。

この記事では、架空の請求問い合わせを分類し、読み取り専用の照会ツールを呼び出して結果を検証する、認証情報を含まないワークフローJSONを配布します。API提供元には、この記事の発行元でもあるOfoxを使います。対象は従来のAI Agentであり、別の機能であるAgent Builderではありません。返金処理やメッセージ送信も行いません。

2026年10月20日、n8n 2.43.8のサーバーCLIから、Ofox経由でdeepseek/deepseek-v4.1-flash-1017を使って実行しました。修正後の実行ではツールが正常に応答し、出力の検証も通りました。一方、初回はツールが失敗しているのに、ワークフロー全体は成功したように見えました。配布ファイルに検証ノードを含めているのは、この違いを確認するためです。これは合成データを使った小規模な接続テストであり、すべてのモデルやn8nのバージョンで本番運用の信頼性を証明するものではありません。

インポート前に用意するもの

編集権限のあるn8n環境、選択したモデルを利用できる十分な残高のあるOfoxアカウント、そしてテスト入力をその提供元へ送信する権限を用意します。最初のワークフローは本番用と分けてください。今回使用したのはローカルのセルフホスト環境で、n8n CloudやAgent Builderはテストしていません。

モデルIDをコピーする前に、現在のOfoxモデルカタログを確認してください。カタログ掲載は提供されているモデルを示しますが、自分のアカウントでツール呼び出しが成功することまで保証しません。別のモデルを選ぶ場合は、以下の検証をやり直します。OpenAI互換だからといって、OpenAIのすべてのエンドポイント、組み込みツール、応答形式が実装されているとは限りません。

ワークフローには次の5つのノードがあります。

AgentとモデルはChat Model接続、AgentとCode ToolはTool接続で結びます。通常の実行経路はManual Trigger → Classify demo ticket → Validate resultです。接続の種類が異なるため、すべてを通常のメイン接続でつないでも同じワークフローにはなりません。

テンプレートを取り込み、認証情報を設定する

1. ワークフローJSONをダウンロードし、インポート前に内容を確認します。プロンプトとJavaScriptは含まれますが、APIキー、認証情報への参照、ピン留めした実行結果（pinData）、実在する顧客のデータは含まれていません。
2. n8nで空のワークフローを開き、ワークフローメニューのImport from FileからダウンロードしたJSONを選びます。URLからのインポートも可能です。利用できる方法はn8nのエクスポート／インポート文書に説明があります。
3. Ofox Chat Modelを開き、認証情報の欄からOpenAI認証情報を作成します。この種類名は互換インターフェースを表しており、OpenAIが発行したキーに限定されるわけではありません。
4. API KeysでOfoxのキーを作成またはコピーします。API Keyに貼り付け、Base URLをhttps://api.ofox.ai/v1に設定します。この例ではOrganization IDは空欄のままにします。認証情報を保存し、モデルノードで選択してください。
5. deepseek/deepseek-v4.1-flash-1017が引き続き自分のアカウントで使える場合に限り、このモデルIDを維持します。画面でモデルの選択方法を切り替えられる場合は、表示名ではなく正確なIDを使い、変更後に保存された値を確認します。
6. このテンプレートではUse Responses APIをオフにします。テストしたのはChat Completions経路です。初回確認ではMaximum Number of Tokensを2048、Timeoutを60000ミリ秒、Max Retriesを0、AgentのMax Iterationsを3に維持してください。

Base URLの入力箇所を示すため、以前のn8n認証情報ガイドで使用した英語UIのスクリーンショットを再利用しています。10月20日の実行画面ではなく、このワークフローの成功を示す証拠でもありません。表示名はn8nのバージョンで異なる場合があります。今回のテスト根拠は、以下で説明するサーバーCLIの実行データです。

APIのルートURLを求める欄に、操作名まで含む/chat/completionsのURLを貼り付けたり、/v1を二重に付けたりしないでください。認証情報の接続テストは通るのに実行時に404が返る場合は、別記事のn8nのエンドポイント切り分けガイドを参照してください。本記事ではURLの診断に加え、一連のタスクと出力検証まで行います。

OpenAI Chat Modelの公式文書は、Chat CompletionsとResponsesを区別しています。ここでResponsesをオフにするのは、テストした経路を選ぶためです。スキーマエラー、403、非対応ツールをすべて解決する設定ではありません。また、このテンプレートの通常のローカルCode Toolは、OpenAIの組み込みWeb検索やファイル検索ツールとは別物です。

チケットを実行し、最終出力とツールの応答を確認する

テスト入力は、意図的に小さくしています。

Request ID: DEMO-1020
Message: I was charged USD 19.50 twice.
I have not supplied a payment ID.

Agentは最初に、request_idをDEMO-1020としてlookup_demo_ticketを呼び出す必要があります。実在するアカウントを照会する処理ではなく、JavaScriptが次の固定テストデータを返します。

{"request_id":"DEMO-1020","payment_id_present":false}

このツールを入れることで、モデルがツールを選び、n8nが実行し、その結果をモデルが受け取ってから回答する、という一往復を確認できます。本番では、この固定データを権限の確認された実際の照会処理に置き換えます。このデモで任意のCRMや決済コネクターの動作が確認できたわけではありません。

ワークフローは非アクティブのまま、Execute workflowで手動実行します。今回、インポートと実行を検証したのはサーバーCLIです。エディターでの手順はn8nの公式インポート手順と保存されたノード設定に基づいており、CloudのUIを別途テストしたものではありません。

Classify demo ticketを確認します。出力は、次のフィールドと値だけを含むJSONになるはずです。

{
  "request_id": "DEMO-1020",
  "category": "billing",
  "amount": 19.5,
  "currency": "USD",
  "action": "request_payment_id"
}

中間ステップも確認してください。ツール名が一致するだけでは不十分です。ツールの実行結果であるobservationに、固定データのリクエストIDとpayment_id_present: falseが含まれ、エラーがない必要があります。配布ファイルでは、最後のノードがこの情報を検証できるようにReturn Intermediate Stepsを有効にしています。

最後にValidate resultを開きます。検証に通ると、同じ業務フィールドにvalidated: trueとtool_verified: trueが追加されます。余分なフィールド、誤ったaction、不正なJSON、ツール呼び出しの欠落、ツール応答の失敗があると、このノードはエラーを投げます。後続にメール送信や返金処理はありません。

この検証ノードは、今回の固定テストデータ1件の正解をあらかじめ知る設計です。チケット本文だけを変更し、値の完全一致チェックを残せば検証は失敗します。別の用途に変える前に、新しいケースで期待するルールを定義し、フィールドと型の検証を維持したうえで、未知のIDや照会データを取得できない場合も明示的にテストしてください。正常終了させるためだけに、形式が整ったJSONなら何でも受け入れる設計にしないでください。

初回実行の「成功」に隠れていた失敗

初回のローカル実行では、モデルはツールを呼び出しましたが、ツールのobservationに次のエラーが記録されていました。

Received tool input did not match expected schema
Unrecognized key(s) in object: 'toolCallId'

それでもワークフロー全体は成功として終了し、期待した分類結果を返しました。最初の検証ノードはツールが呼ばれたことだけを確認し、利用できるデータが返ったかを見ていなかったのです。そのため、この実行は接続テストとして不合格としました。

修正後のCode Toolの入力スキーマでは、文字列のrequest_idを必須とし、追加プロパティを許可しました。コードが使うのは許可したリクエストIDだけで、固定データを返す処理に限定しています。入力を別サービスへ転送したり、書き込みを行ったりはしません。これにより、今回のインストール構成で観測した追加フィールドを受け入れられます。最終出力のスキーマは厳密なままとし、検証ノードでツールの応答も確認するようにしました。このエラーを消すためだけに、本番の操作から厳格な入力検証を外さないでください。 データを変更するツールでは、ノードや実行環境の挙動を調べ、明確な入力仕様を定めてから進める必要があります。

修正後の実行ではモデルを2回呼び出しました。1回目はツール実行を要求し、2回目は正常な照会結果を受け取った後に分類を返しました。n8nに記録された合計は、2回の呼び出しで入力1,019トークン、出力101トークンです。不合格とした初回の実行は3回の呼び出しでした。これらは記録された使用量であり、請求額でも、次回以降の使用量を保証する数値でもありません。

別のローカルテストでは、不正なJSON、余分なフィールド、誤ったaction、ツール呼び出しなし、ツールエラーの5種類を検証ノードが拒否することを確認しました。検証用の合成入力を使ったもので、実際の提供元の障害、レート制限、課金エラーを発生させたテストではありません。また、今回のtoolCallIdの問題は、Agent Builderで別途報告されているget_environmentスキーマの問題を再現したものではありません。

自分のAPIキーを使うと、どこから課金されるのか

費用は次のように分けて確認します。

Ofoxの認証情報を使う場合は、Ofoxアカウントで該当モデルのリクエスト履歴と請求を確認します。n8n Gateway creditsとして表示される残高で、Ofoxキーの利用料を支払えるわけではありません。逆に、提供元の残高を追加してもn8n Gateway creditsやAssistant creditsは増えません。Gateway creditsの公式文書では、これらの残高と、自分で管理する認証情報を使う経路を区別しています。

今回のCode Toolはローカルの固定テストデータを返すだけで、外部ツールサービスへのリクエストはありません。実際の検索やスクレイピングツールを組み込めば、別料金が発生する可能性があります。また、今回の2回のテスト実行でも見られたように、1回のワークフロー実行中にAgentがモデルを複数回呼び出す場合があります。

予算を計算する際は、入力、出力、別途報告されるキャッシュの各区分を、すべての呼び出しについて合算します。課金対象の使用量が発生したリトライや失敗した試行も含めます。そのモデル、提供元、アカウントに適用される正確な単価を使い、外部ツールの費用を加えてください。テキストモデルの出力単価を全トークンに適用したり、n8nの1実行をAPIの1リクエストとみなしたりしないことが大切です。本記事ではOfoxの料金単価を掲載せず、実測による費用削減も主張していません。

まずは合成データと小さな予算で始めます。エラーを理解するまではリトライを無効にし、その後、エラーの種類に合った上限付きの方針を設定してください。リトライ回数とAgentの反復回数を同時に増やすと、無効なキーや非対応スキーマを解決できないまま呼び出しだけが増える場合があります。

インポートしたワークフローが失敗する場合

DeepSeekの経路やサービスに関する問題なら、DeepSeek APIのエラーとフォールバックのガイドを参照してください。切り替え先でも必要なプロトコル、ツール、結果の仕様を満たす必要があります。モデル名を変えただけでは、移行を検証したことにはなりません。

実際の業務につなぐ前に、固定テストデータだけに当てはまる前提を取り除き、対象データへのアクセス権を確認してください。書き込み操作には個別の認可と重複実行を防ぐチェックを設けます。最初に目指すのは、自分の認証情報でモデルとツールの一往復を完了し、明示した条件で結果を検証できる状態です。そこまで動いたら、Ofoxの認証文書とアカウントのリクエスト履歴を使い、実際のワークフローにも同じ確認手順を適用していきます。