AIエージェントにAPIキーを見せずに渡すにはどうすればよいか
エージェントにはキーではなく参照を渡し、同じマシン上のプロキシがリクエストの送出時に本物のキーを組み込みます。環境変数ではもう十分でなくなった理由と、セットアップ方法を説明します。
エージェントにはキーの代わりに参照を渡し、同じマシン上で動く小さなプロキシが、リクエストの送出時に本物のキーを差し込みます。エージェントは、シークレットを書くべき場所に clavitor://OpenAI/key と書きます。APIは本物のキーを受け取ります。エージェントはキーを一切保持しないため、表示することも、ログに残すことも、言いくるめられて渡してしまうこともありません。
これが基本的な考え方です。このページの残りの部分では、なぜこれが重要なのか、そしてセットアップ方法を説明します。
「とりあえず環境変数に入れればいい」が通用しなくなった理由
1年前なら、export OPENAI_API_KEY=sk-... はスクリプトにキーを渡す普通の方法でした。誰も気にしませんでした。
ところが、そのスクリプトが自分で考えるようになりました。
AIエージェントはファイルを読み、ツールを実行し、ログを書き、インターネット上の見知らぬ相手とやり取りします。そのどれもが、エージェントが保持するキーの流出経路になります。
- 環境。 エージェントが実行するものはすべて環境を引き継ぎます。
/procにも、クラッシュダンプにも、CIの出力にも現れます。 - メモリ。 実行時にキーを取得すれば、エージェントが動いている間ずっとプロセス内に置かれたままです。
- 会話。 Webページやissueコメントに仕込まれたプロンプトインジェクションが、「デバッグのために設定を含めて」とエージェントに求めます。親切なエージェントはその通りにします。
これらにはエージェントのバグは一切不要です。必要なのは、キーがエージェントの届く場所にあることだけです。
パターン:エージェントが要求し、プロキシが署名する
ホテルのキーカードを考えてください。宿泊客は自分の部屋を開けられます。しかしマスターキーは決して見られず、ドアはすべての入退室を記録します。
APIキーの場合、次のようになります。
- 本物のキーはボールトに暗号化されて保存されます。
- プロキシがエージェントの隣、同じマシン上で動きます。
- エージェントは、キーを書くべき場所に参照を入れたHTTPSリクエストを送ります。
- プロキシがボールトから値を取得し、リクエストに組み込んで転送します。
- エージェント側が保持するのは参照だけです。
エージェントのログに表示されるのは参照です。コンテキストウィンドウに載るのも参照です。漏れるものが何もありません。
Clavitorでのセットアップ方法
私たちがこうして構築しました。バイナリ1つ、環境変数1つで、エージェントのコードは変更不要です。
ボールト内に、必要なスコープを持つクライアントをエージェント用に作成し、プロキシを登録して起動します。
$ clavitor-proxy init $ clavitor-proxy ca $ clavitor-proxy serve
init はプロキシをそのクライアントとして登録します。ca はプロキシの認証局を出力します。プロキシ自身がエージェントのHTTPS接続を開くため、この認証局をエージェントのHTTPクライアントが使う信頼ストアに追加してください。次に、エージェントをプロキシに向けます。
$ export HTTPS_PROXY="http://clavitor:$(cat proxy-auth)@127.0.0.1:1983"
$ curl -H "Authorization: Bearer clavitor://OpenAI/key" \
https://api.openai.com/v1/chat/completionsproxy-auth はプロキシ自身のアクセストークンで、バイナリの隣にあるファイルです。すべての接続がこれを運ぶ必要があるため、同じマシンの別のユーザーがプロキシを勝手に使うことはできません。プロキシは 127.0.0.1:1983 で、そのマシン上でのみ待ち受けます。信頼できるプライベートネットワーク向けに意図的に設定する場合は別です。
HTTPS_PROXY を尊重するHTTPクライアントを持つエージェントならどれでも動作します。Claude Code、Codex、自作のスクリプトなどです。資格情報は、そのエントリがWebアドレスとして記載しているホストにしか送られないため、プロンプトインジェクションを受けたエージェントが同じ参照をよそ様のサーバーに向けることはできません。手順に沿ったセットアップはプロキシのドキュメントにあります。
エージェントの他のシークレットはどうするか
すべてのシークレットがHTTPヘッダーで運ばれるわけではありません。デプロイ用のパスワード、SSHキー、サインイン用の二要素認証コードなどです。
これらについては、エージェントは clavitor-cli で一度に1つの名前付きエントリを要求します。しかも、与えられたエントリに対してのみです。
$ clavitor-cli get "GitHub Deploy" --field password $ clavitor-cli get "Stripe API" --field key clavitor-cli: CV-2041: Access denied.
エージェントはボールトの一覧を取得できません。名前検索では一致するタイトルが最大5件、それを超える場合は件数のみが表示されます。
認証アプリのコードも同じ仕組みです。clavitor-cli totp "GitHub" はエージェントのマシン上で現在のコードを算出するため、誰かがスマートフォンを確認しなくても二要素サインインを通過できます。ボールトはシークレットを暗号化して保持します。
これで解決しないこと
プロキシはキーをエージェントの手の届かないところに置きます。しかし、エージェントを信頼できるものにはしません。
- 侵害されたエージェントは、与えられたアクセス権を引き続き使えます。キーを持ち帰ることだけはできません。
- マシンへの管理者アクセスを持つ人は、プロキシを使うことも、そのメモリを読むこともできます。
- APIが応答でキーをそのまま返す場合、それはエージェントの手に渡ります。プロキシはリクエストにキーを組み込むだけで、応答のフィルタリングは行いません。
だからこそ、プロキシと同じくらい周囲のアクセス制御が重要です。
- スコープ。 各エージェントには必要なエントリのみを与えます。仕事用エージェントにはGitHubとAWS。デプロイ用エージェントにはSSHキーとデータベース。
- 読み取り制限。 各エージェントは、1分あたり・1時間あたりに読み取れる異なるエントリの数に上限があり、その数値はあなたが設定します。2時間以内に2回時間あたりの上限を超えたエージェントは、あなたがロック解除するまで停止します。
- 記録。 すべての読み取りが記録されます。どのエージェントが、どのエントリを、いつ。
複数のエージェントを動かしていますか?それぞれに専用のプロキシと専用の登録を与えてください。そうすれば各エージェントが独自のスコープ、独自の制限、独自の記録を持ち、エージェントAがエージェントBのキーを見ることはできません。
要点
エージェントにキーを渡さないでください。キーの名前を渡し、キー自体は一歩離れた場所に置いてください。その場所が、毎回、「このエージェントは今このキーを使ってよいか」を判断します。