AIエージェントにAPIキーを見せずに使わせる方法

Posted on Nov 5 • Originally published at apidog.com

クイックアンサー： AIエージェントにAPIキーを見せることなく利用させるには、エージェントのコンテキストにはキーの「 名前（参照名） 」のみを含め、「 値 」はモデルの外部で解決するようにします。具体的には、エージェントが参照するだけで出力は行わない環境変数、シークレットマネージャーの参照、またはヘッダーを注入するプロキシを利用します。さらに、各キーの有効期限を短く設定しスコープを限定した上で、ログがエージェントに戻る前にマスキング（墨消し）を行います。

DeepSeek Harnessチームは、そのエッセイ 「Exploring Super-agent Design」 の中でこの問題を取り上げました。エージェントのコンテキスト内にある認証情報は漏洩する恐れがあるため、エージェントには認証情報を見せずに利用させるべきだという指摘です。同エッセイではこれを未解決の課題として挙げています。しかし、フレームワーク側の対応を待つ必要はありません。以下で紹介するパターンは、今すぐ実践可能です。

全体像については、 スーパーエージェントの構築方法 をご覧ください。本記事では、「キーをコンテキストウィンドウに一切入れずに、エージェントから認証付きAPIを呼び出すにはどうすればよいか」という1つの問いに絞って解説します。

AIエージェントによるAPIキーの漏洩は、キーの値がコンテキストに入り込んだ瞬間に発生します。モデルがツール呼び出し、ファイル、コミットログ、返答などにその値をそのまま出力してしまう可能性があるためです。サーバーに不正侵入される必要すらありません。多くの場合、エージェント自身がユーザーの要求に応えようとして自らキーを渡してしまうのです。

人間やフロントエンドによる漏洩には異なる対策が必要であり、それらについては ブラウザで露出したAPIキー 、 盗難されたAI APIキーとLLMjacking 、そして シークレットスキャナーによる漏洩キーの検知 で解説しています。本記事で扱う主体はあくまでエージェントです。

ここで紹介するすべてのパターンは、1つのルールに基づいています。それは、エージェントのコンテキストにはシークレットへの 参照 のみを保持させるという点です。モデルの外部にある何かが直前でその参照を実際の実値に解決し、その値は決してエージェント側へ戻さないようにします。

もし右列の値が一度でもコンテキストに入ってしまった場合は、直ちにキーをローテーションしてください。コンテキストウィンドウの内容はログに記録され、キャッシュされ、エクスポートされる可能性があります。一度送信してしまったトークンを取り消すことはできません。

環境変数を使用する場合、キーはプロセスの環境内に保持され、エージェントは $STRIPE_KEY と記述します。これにより、モデルがコマンドを記述した後にシェルによって変数が展開されます。これは最も手軽に導入できるパターンですが、確実に機能させるには次の3つの習慣が必要です。

シークレットファイルをブロックする： Claude Codeでは、 設定の権限（permissions） に Read(./.env) や Read(./.env.*) などの拒否（deny）ルールを追加します。他のエージェントにも同様の許可・拒否リストが用意されています。

Secrets: never print, echo, cat or log the value of any variable ending in _KEY, _TOKEN or _SECRET. Reference them as $NAME. If a value is missing, say which NAME is missing and stop. Enter fullscreen mode Exit fullscreen mode 出力をマスキング（Redact）する： 既知のシークレットパターンをマスクするフィルターを使用し、出力がモデルに戻る前に墨消しを行います。

率直な限界点として、エージェントのシェル自体は変数を 保持している ため、プロンプトインジェクションを受けたエージェントであれば出力させることが可能です。環境変数はうっかりミスを防ぐためのものであり、次のコマンドを掌握した攻撃者を防ぐことはできません。

シークレットマネージャーの参照とは、CLIが実行時に解決する op://vault/item/field のようなポインタであり、設定ファイルやプロンプトにはこのポインタのみが含まれます。参照単体では何の権限も持たないため、エージェントがそれを読み取ったりコミットしたりしても安全です。

1Passwordの シークレット参照（secret references） は分かりやすい一例です。

#.env.agent (safe for the agent to read) STRIPE_KEY = op://payments/stripe/api-key GITHUB_TOKEN = op://ci/github-bot/token Enter fullscreen mode Exit fullscreen mode op run --env-file =.env.agent -- npm test Enter fullscreen mode Exit fullscreen mode op run は子プロセス内でこれらの参照を解決し、 --no-masking を明示的に渡さない限り、標準出力（stdout）や標準エラー出力（stderr）に出力されたシークレットはデフォルトで隠蔽されます。エージェントが実行するコマンドには、絶対にこのフラグを含めないようにしてください。HashiCorp Vault、AWS Secrets Manager、Azure Key Vaultも、独自の構文で同様の機能を提供しています。ただし、子プロセス自体は値を保持しているため、パターン1と同様の限界は残ります。

認証情報注入プロキシは、エージェントとアップストリームAPIの間に位置し、認証ヘッダー自体を付与します。エージェントはキーを含めずにリクエストを送信し、プロキシが認証情報を付加するため、エージェントは出力したり外部へ持ち出したりできる場所に値を一切保持しません。

これは、エージェントがキーを真に一度も持たない唯一のパターンです。最小限の設計は以下のようになります。

認証情報の注入と同じくらい重要なのが許可リストです。仮にエージェントがインジェクション攻撃を受けても、キーを 利用 できるのは事前に承認された呼び出しのみに制限され、キー自体を別の場所へ持ち出すことはできません。エージェントがプロキシの設定ファイルを読み取れないよう、プロキシは別ユーザーまたは別コンテナで実行してください。

これは先述のエッセイで示されているアーキテクチャとも合致しています。エージェントのループ処理はクラウド上で動作し、作業環境は手元のマシン上で軽量デーモンの背後に維持され、認証情報は常にその環境側に留まります。

有効期限の短いスコープ限定トークンは、他のパターンが破られた際の被害を最小限に抑えます。エージェントには数分で期限切れとなり、単一の限定されたタスクのみを実行できる認証情報が渡されるため、たとえ値が漏洩しても攻撃者がそれを利用しようとする頃にはほとんど無価値になっています。これは多層防御のセーフティネットであり、他のパターンの代わりになるものではありません。

エージェントのセッションごとにトークンを1つ発行し、実行するタスクに必要な最小限のスコープに制限し、タスクを完了できる最短の有効期限を設定してください。

マスキングは最後のクリーンアップレイヤーです。たった1行マスキング漏れがあるだけで、これまでの対策がすべて台無しになってしまうため、ツールの出力、CIログ、保存されたエージェントのセッションログ内のシークレットを確実にマスクします。既知のプレフィックス（ sk_live_ 、 ghp_ 、 github_pat_ 、 AKIA 、 xoxb- ）、 [REDACTED CREDENTIAL] や X-[REDACTED CREDENTIAL] などのヘッダー値、そしてそのセッションで注入した正確な値をマスキング対象にします。ツールのラッパー内やCIのログ設定に適用し、会話履歴を共有する前にも必ず実施してください。

Apidogは「名前はコンテキスト内、値はコンテキスト外」のルールに最適です。テストリクエストで {{token}} を参照し、実行時に環境側がそれを解決するため、エージェントが読み書きするのはその名前だけです。コーディングエージェントは、 Apidog CLI を通じてテスト全体の構築から実行までを行うことができます。

1つ重要な注意点があります。Apidogの変数には、Apidogのサーバーやチームと同期される Shared Value（共有値） と、ローカルマシン内にのみ保持される Local Value（ローカル値） があります。 変数に関するドキュメント ではトークンにローカル値を使用することを推奨していますが、CLIはデフォルトで共有値を使用する点に留意してください。そのため、本物のトークンは共有値には含めず、実行時に渡すようにします。

ログイン作業はユーザー自身が行うため、Apidogのトークンがエージェントのコンテキストに入ることはありません。

npm install -g apidog-cli@latest apidog auth login --with-token <YOUR_APIDOG_TOKEN> # in your own terminal npx -y skills add https://apidog.com # pick your agent when prompted export PAYMENTS_TOKEN =... # in your shell, never in a prompt Enter fullscreen mode Exit fullscreen mode 続いて、Claude Codeに次のようなプロンプトを1つ指示します。

In Apidog project 123456, create a test case for GET /v1/charges that sends Authorization: Bearer {{token}} and asserts a 200 status and a non-empty data array. Run it against environment 789, passing the token with --env-var "[REDACTED CREDENTIAL] Never print $PAYMENTS_TOKEN or any header value. Summarize failures only. Enter fullscreen mode Exit fullscreen mode エージェントはスキーマを読み込み、ペイロードを検証してテストケースを作成し、実行します。

apidog cli-schema get test-case-create apidog cli-schema validate test-case-create --file case.json apidog test-case create --project 123456 --file case.json apidog run --test-case <caseId> --project 123456 -e 789 \ --env-var "[REDACTED CREDENTIAL] -r cli,json Enter fullscreen mode Exit fullscreen mode テストケースのJSONには {{token}} が保持され、コマンドには $PAYMENTS_TOKEN が指定されており、モデルがコマンド行を出力した後にシェルが値を補完します。エージェントが受け取るのは成否の結果とアサーションメッセージのみです。保存されたJSONレポートは、共有する前にマスキング処理を通してください。CI環境でも同様の apidog run コマンドに -r junit を付けて実行できます。詳細は Apidog CLIのCI/CDパイプライン ガイドおよび Claude CodeでのApidog CLI セットアップを参照してください。

Enterpriseプランでは、ApidogはHashiCorp Vault、Azure Key Vault、AWS Secrets Managerから シークレット（Vault secrets） を取得し、 {{vault:key}} として参照することも可能です。スクリプト内でその値を console.log で出力しようとしてもマスクされ、チームメンバーに値が共有されることもありません。まずはCLIの手順を試してみたい場合、Apidog Freeプランなら最大4ユーザーまで無料で利用できます。

AIエージェントは見ることのできないAPIキーを使用できますか？ はい、可能です。認証情報注入プロキシを利用すれば、エージェントはキーなしでリクエストを送信し、プロキシがヘッダーを追加します。環境変数やシークレット参照を使う手法では、プロンプトからは値が隠されるものの、エージェントのシェル内には値が残ります。

AIエージェントのAPIキー管理に環境変数を使うのは安全ですか？ プロンプトにキーを直接貼り付けるよりは安全ですが、それ単体では安全とは言えません。エージェントのシェルが変数の値を出力してしまう可能性があり、プロンプトインジェクションによって出力を要求される恐れもあります。読み取り拒否ルール、マスキング処理、有効期限の短いトークンと組み合わせて運用してください。

エージェントがAPIキーを出力してしまった場合はどうすればよいですか？ 直ちにプロバイダー側でキーをローテーションしてください。その後、会話履歴がどこに渡ったかを追跡します（プロバイダー側のログ、エクスポートファイル、PRのコメント、CIの出力など）。メッセージを削除しても、複製されたコピーまでは消去されません。

エージェントにシークレットを露出させずにApidog CLIに渡すにはどうすればよいですか？ トークンをご自身のシェル内に保持し、エージェントには apidog run に対して --env-var "[REDACTED CREDENTIAL] を渡すよう指示します。テスト側では {{token}}` を参照するため、エージェントは名前のみを扱うことになります。

有効期限の短いトークンだけで十分ですか？ いいえ、十分ではありません。有効期限が15分のトークンであっても、その15分間は不正利用される恐れがあります。「名前はコンテキスト内、値はコンテキスト外」のルールやプロキシの背後にある多層防御のセーフティネットとして活用してください。